OpenClaw从入门到应用——工具（Tools）：Agent Client Protocol (ACP)

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

Agent Client Protocol (ACP) 会话允许 OpenClaw 通过 ACP 后端插件运行外部编码工具（例如 Pi、Claude Code、Codex、OpenCode 和 Gemini CLI）。

如果你用通俗语言告诉 OpenClaw “在 Codex 中运行这个”或“在一个线程中启动 Claude Code”，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子代理运行时）。

快速操作流程

当你需要实用的/acp操作手册时，请使用此流程：

1. 生成一个会话：
   • /acp spawn codex --mode persistent --thread auto
2. 在绑定的线程中工作（或显式地针对该会话键）。
3. 检查运行时状态：
   • /acp status
4. 根据需要调整运行时选项：
   • /acp model
   • /acp permissions
   • /acp timeout
5. 在不替换上下文的情况下提示活跃会话：
   • /acp steer tighten logging and continue
6. 停止工作：
   • /acp cancel（停止当前轮次），或
   • /acp close（关闭会话并移除绑定）

给人类用户的快速入门

自然语言请求示例：

• “在此处启动一个持久的 Codex 会话，并保持其专注。”
• “将此作为一次性的 Claude Code ACP 会话运行，并总结结果。”
• “在此线程中使用 Gemini CLI 执行此任务，然后继续在同一线程中进行后续操作。”

OpenClaw 应该执行的操作：

1. 选择runtime: "acp"。
2. 解析请求的工具目标（agentId，例如codex）。
3. 如果请求了线程绑定且当前频道支持，则将 ACP 会话绑定到该线程。
4. 将后续的线程消息路由到同一个 ACP 会话，直到取消聚焦/关闭/过期。

ACP 与子代理的对比

当你想要一个外部工具运行时，使用 ACP。当你想要 OpenClaw 原生的委托运行时，使用子代理。

另请参阅 子代理。

线程绑定会话（与频道无关）

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

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

线程绑定支持是适配器特定的。如果当前频道适配器不支持线程绑定，OpenClaw 会返回一条明确的“不支持/不可用”消息。

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

• acp.enabled=true
• acp.dispatch.enabled默认开启（设置为false以暂停 ACP 调度）
• 频道适配器的 ACP 线程生成标志已启用（适配器特定）
  • Discord：channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram：channels.telegram.threadBindings.spawnAcpSessions=true

支持线程的频道

• 任何暴露会话/线程绑定能力的频道适配器。
• 当前内置支持：
  • Discord 线程/频道
  • Telegram 主题（群组/超级群组中的论坛主题和私聊主题）
• 插件频道可以通过相同的绑定接口添加支持。

频道特定设置

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

绑定模型

• bindings[].type="acp"标记一个持久的 ACP 对话绑定。
• bindings[].match标识目标对话：
  • Discord 频道或线程：match.channel="discord"+match.peer.id=""
  • Telegram 论坛主题：match.channel="telegram"+match.peer.id=":topic:"
• bindings[].agentId是所属的 OpenClaw 代理 ID。
• 可选的 ACP 覆盖配置位于bindings[].acp下：
  • mode（persistent或oneshot）
  • label
  • cwd
  • backend

每个代理的运行时默认值

使用agents.list[].runtime为每个代理定义一次 ACP 默认值：

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent（工具 ID，例如codex或claude）
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

ACP 绑定会话的覆盖优先级：

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. 全局 ACP 默认值（例如acp.backend）

示例：

{ agents: { list: [ { id: "codex", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/workspace/openclaw", }, }, }, { id: "claude", runtime: { type: "acp", acp: { agent: "claude", backend: "acpx", mode: "persistent" }, }, }, ], }, bindings: [ { type: "acp", agentId: "codex", match: { channel: "discord", accountId: "default", peer: { kind: "channel", id: "222222222222222222" }, }, acp: { label: "codex-main" }, }, { type: "acp", agentId: "claude", match: { channel: "telegram", accountId: "default", peer: { kind: "group", id: "-1001234567890:topic:42" }, }, acp: { cwd: "/workspace/repo-b" }, }, { type: "route", agentId: "main", match: { channel: "discord", accountId: "default" }, }, { type: "route", agentId: "main", match: { channel: "telegram", accountId: "default" }, }, ], channels: { discord: { guilds: { "111111111111111111": { channels: { "222222222222222222": { requireMention: false }, }, }, }, }, telegram: { groups: { "-1001234567890": { topics: { "42": { requireMention: false } }, }, }, }, }, }

行为：

• OpenClaw 确保在使用的 ACP 会话存在。
• 该频道或主题中的消息将路由到配置的 ACP 会话。
• 在绑定的对话中，/new和/reset会在原地重置同一个 ACP 会话键。
• 临时运行时绑定（例如由线程聚焦流程创建的）仍然适用。

启动 ACP 会话（接口）

通过sessions_spawn

使用runtime: "acp"从代理轮次或工具调用启动 ACP 会话。

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

注意：

• runtime默认为subagent，因此请显式设置runtime: "acp"用于 ACP 会话。
• 如果省略agentId，当配置了acp.defaultAgent时，OpenClaw 会使用它。
• mode: "session"需要thread: true来维持持久的绑定对话。

接口详情：

• task（必需）：发送给 ACP 会话的初始提示。
• runtime（ACP 必需）：必须为"acp"。
• agentId（可选）：ACP 目标工具 ID。如果设置了acp.defaultAgent，则回退使用。
• thread（可选，默认为false）：在支持的情况下请求线程绑定流程。
• mode（可选）：run（一次性）或session（持久）。
  • 默认为run
  • 如果thread: true且省略 mode，OpenClaw 可能会根据运行时路径默认持久行为
  • mode: "session"需要thread: true
• cwd（可选）：请求的运行时工作目录（由后端/运行时策略验证）。
• label（可选）：在会话/横幅文本中使用的面向操作员的标签。
• resumeSessionId（可选）：恢复现有的 ACP 会话而不是创建新会话。代理通过session/load重放其对话历史。需要runtime: "acp"。
• streamTo（可选）："parent"将初始 ACP 运行进度摘要作为系统事件流式传输回请求者会话。
  • 可用时，接受的响应包括streamLogPath，它指向一个会话范围内的 JSONL 日志（.acp-stream.jsonl），你可以 tail 它以获取完整的转发历史记录。

恢复现有会话

使用resumeSessionId继续之前的 ACP 会话，而不是从头开始。代理通过session/load重放其对话历史，因此它会带着之前的所有上下文继续。

{"task":"Continue where we left off — fix the remaining test failures","runtime":"acp","agentId":"codex","resumeSessionId":""}

常见用例：

• 将会话从你的笔记本电脑转移到你的手机上 —— 告诉你的代理从你离开的地方继续
• 继续你在 CLI 中以交互方式开始的编码会话，现在通过你的代理无头运行
• 恢复因网关重启或空闲超时而中断的工作

注意：

• resumeSessionId需要runtime: "acp"—— 如果与子代理运行时一起使用，则返回错误。
• resumeSessionId会恢复上游的 ACP 对话历史；thread和mode仍然正常应用于你正在创建的新 OpenClaw 会话，因此mode: "session"仍然需要thread: true。
• 目标代理必须支持session/load（Codex 和 Claude Code 支持）。
• 如果找不到会话 ID，生成操作会失败并返回明确的错误 —— 不会静默回退到新会话。

操作员冒烟测试

在网关部署后使用此测试，当你想要快速实时检查 ACP 生成是否真正端到端工作，而不仅仅是传递单元测试时。

推荐的门控：

1. 验证目标主机上部署的网关版本/提交。
2. 确认部署的源代码包括src/gateway/sessions-patch.ts中的 ACP 谱系接受（subagent:* 或 acp:* 会话）。
3. 打开一个临时的 ACPX 桥接会话，连接到实时代理（例如jpclawhq上的razor(main)）。
4. 要求该代理调用sessions_spawn，参数如下：
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • 任务：Reply with exactly LIVE-ACP-SPAWN-OK
5. 验证代理报告：
   • accepted=yes
   • 一个真实的childSessionKey
   • 无验证器错误
6. 清理临时的 ACPX 桥接会话。

给实时代理的提示示例：

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run". Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK". Then report only: accepted=; childSessionKey=; error=.

注意：

• 保持此冒烟测试使用mode: "run"，除非你故意测试线程绑定的持久 ACP 会话。
• 对于基本门控，不需要streamTo: "parent"。该路径取决于请求者/会话能力，是一个单独的集成检查。
• 将线程绑定的mode: "session"测试视为来自真实 Discord 线程或 Telegram 主题的第二个、更丰富的集成测试通道。

沙箱兼容性

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

当前限制：

• 如果请求者会话被沙箱化，则对于sessions_spawn({ runtime: "acp" })和/acp spawn，ACP 生成都会被阻止。
  • 错误：Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• 带有runtime: "acp"的sessions_spawn不支持sandbox: "require"。
  • 错误：sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

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

通过/acp命令

在需要时，使用/acp spawn从聊天中获得明确的操作员控制。

/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
• --label

请参阅 斜杠命令。

会话目标解析

大多数/acp操作接受一个可选的会话目标（session-key、session-id或session-label）。

解析顺序：

1. 显式目标参数（或/acp steer的--session）
   • 尝试键
   • 然后是 UUID 格式的会话 ID
   • 然后是标签
2. 当前线程绑定（如果此对话/线程绑定到 ACP 会话）
3. 当前请求者会话回退

如果没有解析到任何目标，OpenClaw 会返回一个明确的错误（Unable to resolve session target: ...）。

生成线程模式

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

注意：

• 在不支持线程绑定的表面上，默认行为实际上是off。
• 线程绑定的生成需要频道策略支持：
  • Discord：channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram：channels.telegram.threadBindings.spawnAcpSessions=true

ACP 控制

可用的命令系列：

• /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 status显示有效的运行时选项，并且在可用时，显示运行时级别和后端级别的会话标识符。

某些控制依赖于后端能力。如果后端不支持某个控制，OpenClaw 会返回一个明确的不支持控制错误。

ACP 命令手册

/acp sessions读取当前绑定或请求者会话的存储。接受session-key、session-id或session-label令牌的命令会通过网关会话发现来解析目标，包括每个代理自定义的session.store根目录。

运行时选项映射

/acp有便捷命令和一个通用设置器。

等效操作：

• /acp model映射到运行时配置键model。
• /acp permissions映射到运行时配置键approval_policy。
• /acp timeout映射到运行时配置键timeout。
• /acp cwd直接更新运行时 cwd 覆盖。
• /acp set是通用路径。
  • 特殊情况：key=cwd使用 cwd 覆盖路径。
• /acp reset-options清除目标会话的所有运行时覆盖。

acpx 工具支持（当前）

当前的 acpx 内置工具别名：

• pi
• claude
• codex
• opencode
• gemini
• kimi

当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义代理别名，否则优先使用这些值作为agentId。

直接的 acpx CLI 使用也可以通过--agent定位任意适配器，但那个原始逃生窗口是 acpx CLI 的一个特性（不是正常的 OpenClawagentId路径）。

所需配置

核心 ACP 基线：

{ acp: { enabled: true, // 可选。默认为 true；设置为 false 以在保留 /acp 控件的同时暂停 ACP 调度。 dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"], maxConcurrentSessions: 8, stream: { coalesceIdleMs: 300, maxChunkChars: 1200, }, runtime: { ttlMinutes: 120, }, }, }

线程绑定配置是频道适配器特定的。Discord 示例：

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

如果线程绑定的 ACP 生成不起作用，请首先验证适配器功能标志：

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

请参阅 配置参考。

acpx 后端的插件设置

安装并启用插件：

openclaw pluginsinstallacpx openclaw configsetplugins.entries.acpx.enabledtrue

开发期间的本地工作区安装：

openclaw pluginsinstall./extensions/acpx

然后验证后端健康状态：

/acp doctor

acpx 命令和版本配置

默认情况下，acpx 插件（发布为@openclaw/acpx）使用插件本地固定的二进制文件：

1. 命令默认为extensions/acpx/node_modules/.bin/acpx。
2. 预期版本默认为扩展固定版本。
3. 启动时立即将 ACP 后端注册为未就绪状态。
4. 后台确保任务验证acpx --version。
5. 如果插件本地二进制文件缺失或版本不匹配，它会运行：
   npm install --omit=dev --no-save acpx@并重新验证。

你可以在插件配置中覆盖命令/版本：

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

注意：

• command接受绝对路径、相对路径或命令名称（acpx）。
• 相对路径从 OpenClaw 工作区目录解析。
• expectedVersion: "any"禁用严格的版本匹配。
• 当command指向自定义二进制文件/路径时，插件本地自动安装被禁用。
• 在后端健康检查运行时，OpenClaw 启动保持非阻塞。

请参阅 插件。

权限配置

ACP 会话以非交互方式运行 —— 没有 TTY 来批准或拒绝文件写入和 shell 执行权限提示。acpx 插件提供了两个配置键来控制权限的处理方式：

permissionMode

控制工具代理可以在不提示的情况下执行哪些操作。

nonInteractivePermissions

控制在没有交互式 TTY 可用时（这对于 ACP 会话来说总是如此）发生的情况。

配置

通过插件配置进行设置：

openclaw configsetplugins.entries.acpx.config.permissionMode approve-all openclaw configsetplugins.entries.acpx.config.nonInteractivePermissions fail

更改这些值后重新启动网关。

重要：OpenClaw 当前默认permissionMode=approve-reads和nonInteractivePermissions=fail。在非交互式 ACP 会话中，任何触发权限提示的写入或执行都可能因AcpRuntimeError: Permission prompt unavailable in non-interactive mode而失败。

如果你需要限制权限，请将nonInteractivePermissions设置为deny，以便会话优雅降级而不是崩溃。

故障排除