Skip to main content

​
Start ACP sessions

Two ways to start an ACP session:
Use runtime: "acp" to start an ACP session from an agent turn or tool call.
runtime defaults to subagent, so set runtime: "acp" explicitly for ACP sessions. If agentId is omitted, OpenClaw uses acp.defaultAgent when configured. mode: "session" requires thread: true to keep a persistent bound conversation.

​
sessions_spawn parameters

​
string
required
Initial prompt sent to the ACP session.
​
"acp"
required
Must be "acp" for ACP sessions.
​
string
ACP target harness id. Falls back to acp.defaultAgent if set.
​
boolean
default:"false"
Request thread binding flow where supported.
​
"run" | "session"
default:"run"
"run" is one-shot; "session" is persistent. If thread: true and mode is omitted, OpenClaw may default to persistent behaviour per runtime path. mode: "session" requires thread: true.
​
string
Requested runtime working directory (validated by backend/runtime policy). If omitted, ACP spawn inherits the target agent workspace when configured; missing inherited paths fall back to backend defaults, while real access errors are returned.
​
string
Operator-facing label used in session/banner text.
​
string
Resume an existing ACP session instead of creating a new one. The agent replays its conversation history via session/load. Requires runtime: "acp".
​
"parent"
"parent" streams initial ACP run progress summaries back to the requester session as system events. OpenClaw records the full relay history in the child agent’s SQLite state and removes it with the child session. Parent progress streams show assistant commentary and ACP status progress by default unless streaming.progress.commentary=false. Discord parent progress requires an explicit streaming.mode: "progress"; unset Discord streaming stays quiet. Status progress still honors acp.stream.tagVisibility, so tags such as plan remain hidden unless explicitly enabled.
ACP sessions_spawn runs use agents.defaults.subagents.runTimeoutSeconds for their default child turn limit. The tool does not accept per-call timeout overrides (runTimeoutSeconds/timeoutSeconds are rejected with a config-the-default error).
​
string
Explicit model override for the ACP child session. Codex ACP spawns normalize OpenAI refs such as openai/gpt-5.4 to Codex ACP startup config before session/new; slash forms such as openai/gpt-5.4/high also set Codex ACP reasoning effort. When omitted, sessions_spawn({ runtime: "acp" }) uses existing subagent model defaults (agents.defaults.subagents.model or agents.entries.*.subagents.model) when configured; otherwise it lets the ACP harness use its own default model. Other harnesses must advertise ACP model controls for an explicit selection. Without those controls, an explicit selection fails; an inherited default may be omitted so the harness can use its own default.
​
string
Explicit thinking/reasoning effort. For Codex ACP, minimal maps to low effort, low/medium/high/xhigh map directly, and off omits the reasoning-effort startup override. An explicit value takes precedence over a reasoning suffix in model, including off. When omitted, ACP spawns use existing subagent thinking defaults, the configured target agent’s thinkingDefault, and per-model agents.defaults.models["provider/model"].params.thinking for the selected model.

​
Spawn bind and thread modes

Notes:
  • --bind here is the simplest operator path for “make this channel or chat Codex-backed.”
  • --bind here does not create a child thread.
  • --bind here is only available on channels that expose current-conversation binding support.
  • --bind and --thread cannot be combined in the same /acp spawn call.