ACP 代理

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. 在绑定的线程里干活（或者显式指定会话 key）。
3. 查看运行时状态：
   • /acp status
4. 按需调整运行时选项：
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
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="<channelOrThreadId>"
  • Telegram 论坛话题：match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• 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 会话 key。
• 临时运行时绑定（比如线程聚焦流程创建的）在存在时仍然有效。

启动 ACP 会话（接口）

通过 sessions_spawn

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

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

注意事项：

• runtime 默认为 subagent，所以 ACP 会话必须显式设置 runtime: "acp"。
• 如果省略 agentId，OpenClaw 会使用已配置的 acp.defaultAgent。
• 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 日志（<sessionId>.acp-stream.jsonl），你可以 tail 它来查看完整的中继历史。

恢复已有会话

使用 resumeSessionId 继续之前的 ACP 会话，而不是重新开始。代理通过 session/load 重放对话历史，所以它会带着之前的完整上下文继续。

{
  "task": "Continue where we left off — fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

常见用途：

• 把 Codex 会话从笔记本电脑交接到手机 — 让代理接着上次的进度继续
• 继续一个你在 CLI 中交互式开始的编码会话，现在通过代理无头运行
• 接手因网关重启或空闲超时中断的工作

注意事项：

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

操作者冒烟测试

在网关部署后想快速验证 ACP spawn 端到端可用（不仅仅是通过单元测试）时使用。

推荐步骤：

1. 确认目标主机上部署的网关版本/提交。
2. 确认部署的源码包含 src/gateway/sessions-patch.ts 中的 ACP 血统接受逻辑（subagent:* or acp:* sessions）。
3. 对一个在线代理（比如 jpclawhq 上的 razor(main)）打开一个临时 ACPX 桥接会话。
4. 让该代理调用 sessions_spawn，参数为：
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: 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=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

注意事项：

• 冒烟测试保持 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.
• sessions_spawn 加 runtime: "acp" 不支持 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 <absolute-path>
• --label <name>

参见 斜杠命令。

会话目标解析

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

解析顺序：

1. 显式目标参数（或 /acp steer 的 --session）
   • 先尝试 key
   • 然后尝试 UUID 格式的 session id
   • 然后尝试 label
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 提供了便捷命令和通用 setter。

等价操作：

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

acpx 工具支持（当前）

当前 acpx 内置的工具别名：

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

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

acpx CLI 也支持通过 --agent <command> 直接使用任意适配器，但那是 acpx CLI 的原生转义功能（不是正常的 OpenClaw agentId 路径）。

必需配置

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 plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

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

openclaw plugins install ./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@<pinned> 然后重新验证。

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

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

注意事项：

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

参见 插件。

权限配置

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

permissionMode

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

nonInteractivePermissions

控制当需要显示权限提示但没有可用的交互式 TTY 时的行为（ACP 会话始终是这种情况）。

配置方式

通过插件配置设置：

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

更改这些值后需要重启网关。

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

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

故障排除