​

ACP agents

​

Fast operator flow

1. Spawn a session:
   • /acp spawn codex --mode persistent --thread auto
2. Work in the bound thread (or target that session key explicitly).
3. Check runtime state:
   • /acp status
4. Tune runtime options as needed:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Nudge an active session without replacing context:
   • /acp steer tighten logging and continue
6. Stop work:
   • /acp cancel (stop current turn), or
   • /acp close (close session + remove bindings)

​

Quick start for humans

• “Start a persistent Codex session in a thread here and keep it focused.”
• “Run this as a one-shot Claude Code ACP session and summarize the result.”
• “Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread.”

1. Pick runtime: "acp".
2. Resolve the requested harness target (agentId, for example codex).
3. If thread binding is requested and the current channel supports it, bind the ACP session to the thread.
4. Route follow-up thread messages to that same ACP session until unfocused/closed/expired.

​

ACP versus sub-agents

​

Thread-bound sessions (channel-agnostic)

• OpenClaw binds a thread to a target ACP session.
• Follow-up messages in that thread route to the bound ACP session.
• ACP output is delivered back to the same thread.
• Unfocus/close/archive/idle-timeout or max-age expiry removes the binding.

• acp.enabled=true
• acp.dispatch.enabled=true
• Channel-adapter ACP thread-spawn flag enabled (adapter-specific)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true

​

Thread supporting channels

• Any channel adapter that exposes session/thread binding capability.
• Current built-in support: Discord.
• Plugin channels can add support through the same binding interface.

​

Start ACP sessions (interfaces)

​

From sessions_spawn

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• 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.

• task (required): initial prompt sent to the ACP session.
• runtime (required for ACP): must be "acp".
• agentId (optional): ACP target harness id. Falls back to acp.defaultAgent if set.
• thread (optional, default false): request thread binding flow where supported.
• mode (optional): run (one-shot) or session (persistent).
  • default is run
  • if thread: true and mode omitted, OpenClaw may default to persistent behavior per runtime path
  • mode: "session" requires thread: true
• cwd (optional): requested runtime working directory (validated by backend/runtime policy).
• label (optional): operator-facing label used in session/banner text.

​

From /acp command

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here

• --mode persistent|oneshot
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

​

Session target resolution

1. Explicit target argument (or --session for /acp steer)
   • tries key
   • then UUID-shaped session id
   • then label
2. Current thread binding (if this conversation/thread is bound to an ACP session)
3. Current requester session fallback

​

Spawn thread modes

• On non-thread binding surfaces, default behavior is effectively off.
• Thread-bound spawn requires channel policy support (for Discord: channels.discord.threadBindings.spawnAcpSessions=true).

​

ACP controls

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

​

ACP command cookbook

​

Runtime options mapping

• /acp model <id> maps to runtime config key model.
• /acp permissions <profile> maps to runtime config key approval_policy.
• /acp timeout <seconds> maps to runtime config key timeout.
• /acp cwd <path> updates runtime cwd override directly.
• /acp set <key> <value> is the generic path.
  • Special case: key=cwd uses the cwd override path.
• /acp reset-options clears all runtime overrides for target session.

​

acpx harness support (current)

• pi
• claude
• codex
• opencode
• gemini

​

Required config

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

​

Plugin setup for acpx backend

openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

openclaw plugins install ./extensions/acpx

/acp doctor

​

Pinned acpx install strategy (current behavior)

1. The extension pins an exact acpx dependency in extensions/acpx/package.json.
2. Runtime command is fixed to the plugin-local binary (extensions/acpx/node_modules/.bin/acpx), not global PATH.
3. Plugin config does not expose command or commandArgs, so runtime command drift is blocked.
4. Startup registers the ACP backend immediately as not-ready.
5. A background ensure job verifies acpx --version against the pinned version.
6. If missing/mismatched, it runs plugin-local install (npm install --omit=dev --no-save acpx@<pinned>) and re-verifies before healthy.

• OpenClaw startup stays non-blocking while acpx ensure runs.
• If network/install fails, backend remains unavailable and /acp doctor reports an actionable fix.

​

Troubleshooting