本页介绍 OpenClaw ACP Agents 功能——通过 Agent Client Protocol 在 OpenClaw 中运行外部编程助手（Codex、Claude Code、Cursor、Gemini CLI 等）。支持将当前对话或 Discord/Telegram 线程直接绑定到 ACP 会话，后续消息自动路由到同一助手实例，实现"养龙虾时让龙虾帮龙虾干活"的多 agent 协作模式。

ACP Agents

Agent Client Protocol（ACP）会话让 OpenClaw 通过 ACP 后端插件运行外部编程助手（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 ACPX 助手）。

如果你用自然语言告诉 OpenClaw"在 Codex 里运行这个"或"在 thread 里启动 Claude Code"，OpenClaw 会把请求路由到 ACP 运行时（而非原生子 agent 运行时）。每个 ACP 会话 spawn 都会作为后台任务被追踪。

如果你想让 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 频道对话，使用 openclaw mcp serve 而非 ACP。

开箱即用？

通常是的。

新安装的 OpenClaw 默认启用内置 acpx 运行时插件。
内置 acpx 插件优先使用其插件本地固定的 acpx 二进制文件。
启动时 OpenClaw 会探测该二进制文件，必要时自动修复。
运行 /acp doctor 可快速检查就绪状态。

首次使用时可能发生的情况：

目标助手适配器可能在第一次使用时通过 npx 按需获取。
该助手的供应商认证仍需在宿主机上存在。
若宿主机无 npm/网络访问，首次运行适配器获取可能失败，直到缓存预热或适配器另行安装。

快速操作流程

实用的 /acp 操作手册：

启动一个会话：
- /acp spawn codex --bind here（绑定当前对话）
- /acp spawn codex --mode persistent --thread auto（绑定线程）
在绑定的对话或 thread 里工作（或明确指定会话 key）。
检查运行时状态：/acp status
按需调整运行时选项：
- /acp model <provider/model>
- /acp permissions <profile>
- /acp timeout <seconds>
向活跃会话发送指令，不替换上下文：
- /acp steer tighten logging and continue
停止工作：
- /acp cancel（停止当前轮次），或
- /acp close（关闭会话 + 移除绑定）

ACP vs 子 Agent

需要外部助手运行时使用 ACP，需要 OpenClaw 原生委派运行时使用子 agent。

维度	ACP 会话	子 Agent 运行
运行时	ACP 后端插件（例如 acpx）	OpenClaw 原生子 agent 运行时
会话 key	`agent:<agentId>:acp:<uuid>`	`agent:<agentId>:subagent:<uuid>`
主要命令	`/acp ...`	`/subagents ...`
启动工具	`sessions_spawn` with `runtime:"acp"`	`sessions_spawn`（默认运行时）

参见 Sub-agents。

当前对话绑定（`--bind here`）

当你希望当前对话成为持久 ACP 工作区，而无需创建子线程时，使用 /acp spawn <harness> --bind here。

行为：

OpenClaw 继续持有频道传输、认证、安全和投递。
当前对话被固定到已 spawn 的 ACP 会话 key。
该对话的后续消息路由到同一 ACP 会话。
/new 和 /reset 就地重置同一绑定的 ACP 会话。
/acp close 关闭会话并移除当前对话绑定。

示例：

/acp spawn codex --bind here：保持当前聊天界面，spawn 或附接 Codex ACP 会话，将此后的消息路由到它
/acp spawn codex --bind here --cwd /workspace/repo：同上，但 Codex 在指定目录中运行
/acp spawn codex --thread auto：OpenClaw 可能创建子线程并在那里绑定 ACP 会话

注意：--bind here 和 --thread ... 在同一个 /acp spawn 调用中互斥。

线程绑定会话

当频道适配器启用了线程绑定功能时，ACP 会话可以绑定到线程：

OpenClaw 将线程绑定到目标 ACP 会话。
该线程的后续消息路由到绑定的 ACP 会话。
ACP 输出发回同一线程。
取消焦点/关闭/归档/空闲超时或最大年龄过期后移除绑定。

线程绑定 ACP 所需的功能标志：

acp.enabled=true
acp.dispatch.enabled 默认开启（设为 false 可暂停 ACP dispatch）
频道适配器 ACP 线程启动标志已启用（适配器特定）
- Discord：channels.discord.threadBindings.spawnAcpSessions=true
- Telegram：channels.telegram.threadBindings.spawnAcpSessions=true

支持线程的频道

Discord threads/channels
Telegram topics（群组/超级群组中的论坛主题以及 DM 主题）
插件频道可通过相同绑定接口添加支持

绑定启动模式

/acp spawn 支持 --bind here|off：

模式	行为
`here`	就地绑定当前活跃对话；若无活跃对话则失败。
`off`	不创建当前对话绑定。

/acp spawn 支持 --thread auto|here|off：

模式	行为
`auto`	在活跃 thread 中：绑定该 thread。在 thread 外：在支持的地方创建/绑定子 thread。
`here`	要求当前活跃 thread；不在 thread 中则失败。
`off`	不绑定。会话以未绑定状态启动。

频道专用设置

对于非临时工作流，在顶层 bindings[] 条目中配置持久 ACP 绑定。

绑定模型

bindings[].type="acp" 标记持久 ACP 对话绑定。
bindings[].match 标识目标对话：
- Discord 频道或 thread：match.channel="discord" + match.peer.id="<channelOrThreadId>"
- Telegram 论坛主题：match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
- BlueBubbles/iMessage：match.channel="bluebubbles"/"imessage" + match.peer.id="<handle|chat_id:*|...>"
bindings[].agentId 是所属 OpenClaw agent 的 id。
可选 ACP 覆盖配置在 bindings[].acp 下：mode、label、cwd、backend

每个 Agent 的运行时默认值

json5

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
  ],
}

启动 ACP 会话（接口）

通过 `sessions_spawn`

json

{
  "task": "打开 repo 并汇总失败的测试",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

接口详情：

task（必填）：发送到 ACP 会话的初始提示。
runtime（ACP 必填）：必须为 "acp"。
agentId（可选）：ACP 目标助手 id。如设置了 acp.defaultAgent 则回退到该值。
thread（可选，默认 false）：在支持的地方请求线程绑定。
mode（可选）：run（单次）或 session（持久）；mode: "session" 需要 thread: true。
cwd（可选）：请求的运行时工作目录。
label（可选）：面向操作员的标签。
resumeSessionId（可选）：恢复已有 ACP 会话，需要 runtime: "acp"。
streamTo（可选）："parent" 将进度摘要作为系统事件流式传回请求者会话。

恢复已有会话

json

{
  "task": "从上次停下来的地方继续——修复剩余的测试失败",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

常见场景：将 Codex 会话从笔记本电脑交接到手机，或继续因 gateway 重启而中断的工作。目标 agent 必须支持 session/load（Codex 和 Claude Code 均支持）。

沙箱兼容性

ACP 会话运行在宿主机运行时，不在 OpenClaw 沙箱内。

沙箱会话中无法 spawn ACP 会话。
sessions_spawn with runtime: "acp" 不支持 sandbox: "require"。

需要沙箱强制执行时使用 runtime: "subagent"。

ACP 控制命令速查

命令	作用	示例
`/acp spawn`	创建 ACP 会话；可选当前对话绑定或线程绑定。	`/acp spawn codex --bind here`
`/acp cancel`	取消目标会话的进行中轮次。	`/acp cancel`
`/acp steer`	向运行中的会话发送指导指令。	`/acp steer prioritize failing tests`
`/acp close`	关闭会话并移除绑定。	`/acp close`
`/acp status`	显示后端、模式、状态、运行时选项。	`/acp status`
`/acp set-mode`	设置运行时模式。	`/acp set-mode plan`
`/acp set`	通用运行时配置选项写入。	`/acp set model openai/gpt-5.4`
`/acp cwd`	设置运行时工作目录覆盖。	`/acp cwd /workspace/repo`
`/acp permissions`	设置审批策略配置。	`/acp permissions strict`
`/acp timeout`	设置运行时超时（秒）。	`/acp timeout 120`
`/acp model`	设置运行时模型覆盖。	`/acp model anthropic/claude-opus-4-6`
`/acp reset-options`	移除会话运行时选项覆盖。	`/acp reset-options`
`/acp sessions`	列出最近的 ACP 会话。	`/acp sessions`
`/acp doctor`	后端健康状态、能力、可操作修复建议。	`/acp doctor`
`/acp install`	打印安装和启用步骤。	`/acp install`

acpx 内置助手别名

claude、codex、copilot、cursor（Cursor CLI）
droid、gemini、iflow、kilocode、kimi、kiro
openclaw、opencode、pi、qwen

必要配置

json5

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

Discord 线程绑定配置示例：

json5

{
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

acpx 后端插件设置

新安装默认启用内置 acpx 插件，通常无需手动安装。

bash

/acp doctor          # 检查就绪状态
openclaw plugins install acpx   # 若已禁用则手动安装

如需自定义 acpx 命令/版本：

json

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

插件工具 MCP 桥接

默认情况下，ACPX 会话不向 ACP 助手暴露 OpenClaw 插件注册的工具。若需要让 Codex 或 Claude Code 调用已安装的 OpenClaw 插件工具（如记忆存取），启用专用桥接：

bash

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

这会在 ACPX 会话启动时注入内置 MCP 服务器 openclaw-plugin-tools，暴露当前已安装并启用的插件工具。启用前请检查已安装插件，因为这会扩展 ACP 助手的工具使用范围。

权限配置

ACP 会话以非交互方式运行，没有 TTY 来批准权限提示。

`permissionMode`

值	行为
`approve-all`	自动批准所有文件写入和 shell 命令。
`approve-reads`	自动批准读取；写入和执行需要提示。（默认）
`deny-all`	拒绝所有权限提示。

`nonInteractivePermissions`

值	行为
`fail`	以 `AcpRuntimeError` 中止会话。（默认）
`deny`	静默拒绝权限并继续（优雅降级）。

bash

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

重要： 若龙虾在非交互模式下需要写文件或执行命令，建议设置 permissionMode=approve-all，否则任何写入/执行都可能报 AcpRuntimeError。

故障排查

症状	可能原因	修复方法
`ACP runtime backend is not configured`	后端插件缺失或已禁用。	运行 `/acp doctor`，按提示安装启用。
`ACP is disabled by policy`	ACP 全局禁用。	设置 `acp.enabled=true`。
`ACP agent "<id>" is not allowed by policy`	Agent 不在许可名单中。	更新 `acp.allowedAgents`。
`--bind here requires running /acp spawn inside an active conversation`	无活跃可绑定对话。	移到目标频道重试，或使用未绑定 spawn。
`Conversation bindings are unavailable for <channel>`	适配器不支持当前对话 ACP 绑定。	使用 `--thread ...` 或配置顶层 `bindings[]`。
`Thread bindings are unavailable for <channel>`	适配器缺少线程绑定能力。	使用 `--thread off` 或移到支持的频道。
`Sandboxed sessions cannot spawn ACP sessions`	ACP 运行时在宿主机上。	从非沙箱会话发起 ACP spawn，或使用 `runtime="subagent"`。
`AcpRuntimeError: Permission prompt unavailable`	`permissionMode` 阻止非交互写入/执行。	设置 `permissionMode=approve-all` 并重启 gateway。
ACP 会话提前以很少输出失败	权限提示被阻止。	检查 gateway 日志中的 `AcpRuntimeError`，调整权限配置。

常见问题

Q: --bind here 和 --thread auto 有什么区别？

A: --bind here 将 ACP 会话绑定到当前这个对话（不创建新线程），后续消息在同一聊天界面中路由到助手。--thread auto 则会在支持的频道（Discord/Telegram）创建子线程并绑定到那里，适合需要隔离上下文的场景。两者不能同时使用。

Q: 如何让 Codex 在我的 iMessage 群聊中运行？

A: 配置顶层 bindings[]，设置 type: "acp"、match.channel: "imessage"，以及对应的 peer.id（推荐用 chat_id:* 格式保证稳定）。参见频道专用设置部分的配置示例。

Q: ACP 会话过期后能否恢复？

A: 可以，用 resumeSessionId 参数即可恢复已有 ACP 会话（Codex 和 Claude Code 均支持），agent 会通过 session/load 重放完整的对话历史，无缝接续中断前的工作。

ACP Agents ​

开箱即用？ ​

快速操作流程 ​

ACP vs 子 Agent ​

当前对话绑定（--bind here） ​

线程绑定会话 ​

支持线程的频道 ​

绑定启动模式 ​

频道专用设置 ​

绑定模型 ​

每个 Agent 的运行时默认值 ​

启动 ACP 会话（接口） ​

通过 sessions_spawn ​

恢复已有会话 ​

沙箱兼容性 ​

ACP 控制命令速查 ​

acpx 内置助手别名 ​

必要配置 ​

acpx 后端插件设置 ​

插件工具 MCP 桥接 ​

权限配置 ​

permissionMode ​

nonInteractivePermissions ​

故障排查 ​

常见问题 ​

ACP Agents

开箱即用？

快速操作流程

ACP vs 子 Agent

当前对话绑定（`--bind here`）

线程绑定会话

支持线程的频道

绑定启动模式

频道专用设置

绑定模型

每个 Agent 的运行时默认值

启动 ACP 会话（接口）

通过 `sessions_spawn`

恢复已有会话

沙箱兼容性

ACP 控制命令速查

acpx 内置助手别名

必要配置

acpx 后端插件设置

插件工具 MCP 桥接

权限配置

`permissionMode`

`nonInteractivePermissions`

故障排查

常见问题