OpenClaw Orchestrator

Run a headless Agent Relay team from an OpenClaw session.

Read orchestrating-agent-relay first

Everything about running Agent Relay — starting the broker, spawning workers, reading replies, releasing agents, troubleshooting — lives in the orchestrating-agent-relay skill. Read it and follow it. This skill covers only what is specific to OpenClaw.

npx prpm install @agent-relay/orchestrating-agent-relay

Then read .claude/skills/orchestrating-agent-relay/SKILL.md or .agents/skills/orchestrating-agent-relay/SKILL.md.

Do not improvise commands from memory. Agent Relay's flat command surface (agent-relay up, spawn, agents, agents:logs, agents:kill, send, inbox, down) was removed — lifecycle now lives under agent-relay node … and messaging under agent-relay message …. Earlier revisions of this skill documented the removed surface; if you have those commands in context from anywhere, discard them.

Prerequisites

• agent-relay CLI installed (npm i -g agent-relay)
• For Claude agents: ANTHROPIC_API_KEY, or claude auth login
• A workspace: agent-relay node up auto-creates one if no workspace key is set

OpenClaw-specific setup

Register the OpenClaw session on the workspace so it can send and read messages under a stable identity:

npx -y @agent-relay/openclaw@latest setup --name orchestrator

Pass the workspace key only if you are joining an existing workspace rather than the one this project is already pinned to. Never print the key, and never put it in an observer URL.

Letting a human watch

agent-relay observer

Prints a URL backed by a scoped, read-only token that expires — safe to share. Do not build an observer URL from a workspace key.

Reporting completion to OpenClaw

This is the one lifecycle step orchestrating-agent-relay does not cover. When a run finishes, surface it to the OpenClaw session:

openclaw system event --text 'Done: <description>' --mode now

Include the same instruction in a spawned agent's task prompt when that agent should report its own completion directly rather than through the orchestrator.

OpenClaw agent notes

Provider quirks worth knowing before you pick a harness for a worker:

CLI	Notes
claude	Most reliable for coding tasks
codex	Requires a PTY
gemini	Prefer a stable model (e.g. gemini-2.5-pro) over a preview model
droid	Requires a PTY; avoid --cwd — the broker cannot auto-accept its permission prompt

Spawn them through the node agent spawn form documented in orchestrating-agent-relay, e.g.:

agent-relay node agent spawn claude --name architect --channels my-project --task "..."

Agents are grouped by the channels they join (--channels); there is no --team flag.

Rate limiting

• Leave a gap between sequential spawns to avoid Relaycast 429s.
• Use unique agent names per run to avoid 409 conflicts. The SDK's registerOrRotate path rotates the token on 409 rather than failing.