​

ACP 智能体

​

我需要哪个页面？

​

这是开箱即用的吗？

• 全新安装现在默认启用内置的 acpx 运行时插件。
• 内置的 acpx 插件会优先使用其插件本地固定版本的 acpx 二进制文件。
• 启动时，OpenClaw 会探测该二进制文件，并在需要时自动修复。
• 如果你想快速检查就绪状态，请从 /acp doctor 开始。

• 第一次使用某个目标 harness 时，可能会通过 npx 按需获取对应的适配器。
• 该 harness 的厂商认证信息仍然必须存在于主机上。
• 如果主机没有 npm/网络访问能力，则首次运行的适配器获取可能会失败，直到缓存预热完成或适配器通过其他方式安装。

• /acp spawn codex：OpenClaw 应该已经准备好引导 acpx，但 Codex ACP 适配器仍可能需要首次运行时获取。
• /acp spawn claude：Claude ACP 适配器也是同样情况，另外该主机上还需要 Claude 侧的认证。

​

面向操作员的快速流程

1. 启动一个会话：
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. 在已绑定的会话或线程中工作（或显式指定该会话键）。
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（关闭会话并移除绑定）

​

面向人工用户的快速开始

• “把这个 Discord 渠道绑定到 Codex。”
• “在这里的线程中启动一个持久化的 Codex 会话，并让它保持聚焦。”
• “把这个作为一次性 Claude Code ACP 会话运行，并总结结果。”
• “把这个 iMessage 聊天绑定到 Codex，并让后续消息保持在同一个工作区中。”
• “针对这个任务使用 Gemini CLI 并放在线程中，然后让后续消息继续在同一个线程里。”

1. 选择 runtime: "acp"。
2. 解析请求的 harness 目标（agentId，例如 codex）。
3. 如果请求绑定当前会话，并且当前渠道支持该功能，则将 ACP 会话绑定到该会话。
4. 否则，如果请求线程绑定，并且当前渠道支持该功能，则将 ACP 会话绑定到该线程。
5. 将后续绑定消息路由到同一个 ACP 会话，直到失焦、关闭或过期为止。

​

ACP 与子智能体的区别

​

ACP 如何运行 Claude Code

1. OpenClaw ACP 会话控制平面
2. 内置的 acpx 运行时插件
3. Claude ACP 适配器
4. Claude 侧运行时/会话机制

• ACP Claude 是一种 harness 会话，具备 ACP 控制、会话恢复、后台任务跟踪，以及可选的会话/线程绑定能力。
• CLI 后端是独立的、仅文本的本地回退运行时。参见 CLI 后端。

• 想要 /acp spawn、可绑定会话、运行时控制或持久化 harness 工作：使用 ACP
• 想要通过原始 CLI 实现简单的本地文本回退：使用 CLI 后端

​

已绑定会话

​

当前会话绑定

• OpenClaw 继续负责渠道传输、认证、安全和消息投递。
• 当前会话会固定绑定到所启动的 ACP 会话键。
• 该会话中的后续消息会路由到同一个 ACP 会话。
• /new 和 /reset 会就地重置同一个已绑定的 ACP 会话。
• /acp close 会关闭该会话并移除当前会话绑定。

• --bind here 会保留同一个聊天界面。在 Discord 上，当前渠道仍然是当前渠道。
• 如果你是在启动新的工作，--bind here 仍然可以创建一个新的 ACP 会话。该绑定会将这个会话附加到当前会话。
• --bind here 本身不会创建 Discord 子线程或 Telegram 主题。
• ACP 运行时仍然可以有自己的工作目录（cwd）或由后端管理的磁盘工作区。该运行时工作区与聊天界面是分离的，并不意味着会新建消息线程。
• 如果你启动到另一个 ACP 智能体且没有传入 --cwd，OpenClaw 默认会继承目标智能体的工作区，而不是请求者的。
• 如果继承的工作区路径不存在（ENOENT/ENOTDIR），OpenClaw 会回退到后端默认的 cwd，而不是静默复用错误的目录树。
• 如果继承的工作区存在但无法访问（例如 EACCES），启动会返回真实的访问错误，而不是丢弃 cwd。

• 聊天界面：人们持续交流的地方（Discord 渠道、Telegram 主题、iMessage 聊天）
• ACP 会话：OpenClaw 路由到的、持久化的 Codex/Claude/Gemini 运行时状态
• 子线程/主题：仅由 --thread ... 创建的可选额外消息界面
• 运行时工作区：harness 运行所在的文件系统位置（cwd、仓库检出目录、后端工作区）

• /acp spawn codex --bind here：保留当前聊天，启动或附加一个 Codex ACP 会话，并将未来消息都路由到它
• /acp spawn codex --thread auto：OpenClaw 可能会创建一个子线程/主题，并在那里绑定 ACP 会话
• /acp spawn codex --bind here --cwd /workspace/repo：与上面相同的聊天绑定，但 Codex 在 /workspace/repo 中运行

• 宣告支持当前会话绑定的聊天/消息渠道，可以通过共享的会话绑定路径使用 --bind here。
• 具有自定义线程/主题语义的渠道，仍然可以在相同共享接口之后提供渠道特定的规范化处理。
• --bind here 始终表示“就地绑定当前会话”。
• 通用的当前会话绑定使用共享的 OpenClaw 绑定存储，并能在正常的 Gateway 网关 重启后保留。

• 在 /acp spawn 中，--bind here 与 --thread ... 互斥。
• 在 Discord 上，--bind here 会就地绑定当前渠道或线程。只有当 OpenClaw 需要为 --thread auto|here 创建子线程时，才需要 spawnAcpSessions。
• 如果当前渠道不暴露当前会话 ACP 绑定能力，OpenClaw 会返回清晰的不支持提示。
• resume 和“新会话”问题属于 ACP 会话层面的问题，而不是渠道层面的问题。你可以复用或替换运行时状态，而无需更改当前聊天界面。

​

线程绑定会话

• OpenClaw 将一个线程绑定到目标 ACP 会话。
• 该线程中的后续消息会路由到已绑定的 ACP 会话。
• 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[].type="acp" 表示一个持久化 ACP 会话绑定。
• bindings[].match 用于标识目标会话：
  • Discord 渠道或线程：match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram 论坛主题：match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • BlueBubbles 私信/群聊：match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" 对于稳定的群组绑定，优先使用 chat_id:* 或 chat_identifier:*。
  • iMessage 私信/群聊：match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" 对于稳定的群组绑定，优先使用 chat_id:*。
• bindings[].agentId 是所属的 OpenClaw 智能体 id。
• 可选的 ACP 覆盖值位于 bindings[].acp 下：
  • mode（persistent 或 oneshot）
  • label
  • cwd
  • backend

​

每个智能体的运行时默认值

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

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 会话键。
• 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍会生效。
• 对于未显式指定 cwd 的跨智能体 ACP 启动，OpenClaw 会从智能体配置继承目标智能体工作区。
• 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败则会作为启动错误暴露出来。

​

启动 ACP 会话（接口）

​

从 sessions_spawn 启动

{
  "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 目标 harness id。如果设置了 acp.defaultAgent，则回退到该值。
• thread（可选，默认 false）：在支持时请求线程绑定流程。
• mode（可选）：run（一次性）或 session（持久化）。
  • 默认值为 run
  • 如果 thread: true 且省略了 mode，OpenClaw 可能会按运行时路径默认使用持久化行为
  • mode: "session" 需要 thread: true
• cwd（可选）：请求的运行时工作目录（由后端/运行时策略校验）。如果省略，ACP 启动会在已配置时继承目标智能体工作区；缺失的继承路径会回退到后端默认值，而真实访问错误会被返回。
• label（可选）：用于会话/横幅文本中的面向操作员标签。
• resumeSessionId（可选）：恢复一个现有 ACP 会话，而不是创建新会话。智能体会通过 session/load 重放其会话历史。要求 runtime: "acp"。
• streamTo（可选）："parent" 会将初始 ACP 运行的进度摘要，以系统事件形式流式回传给请求者会话。
  • 在可用时，返回结果中可包含 streamLogPath，指向一个会话范围的 JSONL 日志（<sessionId>.acp-stream.jsonl），你可以 tail 它来查看完整的转发历史。

​

恢复现有会话

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

• 将一个 Codex 会话从你的笔记本交接到手机上 —— 让你的智能体接着你上次离开的地方继续
• 继续你之前在 CLI 中交互式开启、现在想通过智能体无头继续的编码会话
• 继续因 Gateway 网关 重启或空闲超时而中断的工作

• resumeSessionId 要求 runtime: "acp" —— 如果与子智能体运行时一起使用会返回错误。
• resumeSessionId 会恢复上游 ACP 会话历史；thread 和 mode 仍会像平常一样应用到你正在创建的新 OpenClaw 会话，因此 mode: "session" 仍然需要 thread: true。
• 目标智能体必须支持 session/load（Codex 和 Claude Code 支持）。
• 如果找不到该会话 ID，启动会以明确错误失败 —— 不会静默回退到新会话。

​

面向操作员的冒烟测试

1. 在目标主机上验证已部署的 Gateway 网关 版本/提交。
2. 确认已部署源码在 src/gateway/sessions-patch.ts 中包含 ACP 血缘接受逻辑（subagent:* or acp:* sessions）。
3. 向一个在线智能体打开一个临时 ACPX 桥接会话（例如 jpclawhq 上的 razor(main)）。
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>.

• 除非你有意测试线程绑定的持久化 ACP 会话，否则请将这个冒烟测试保持在 mode: "run"。
• 基础检查不需要 streamTo: "parent"。该路径依赖请求者/会话能力，是单独的集成检查项。
• 将线程绑定的 mode: "session" 测试视为第二轮、更深入的集成验证，应从真实的 Discord 线程或 Telegram 主题发起。

​

沙箱兼容性

• 如果请求者会话处于沙箱中，则 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".

​

从 /acp 命令启动

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

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

​

会话目标解析

1. 显式目标参数（或 /acp steer 的 --session）
   • 先尝试 key
   • 再尝试 UUID 形状的 session id
   • 最后尝试 label
2. 当前线程绑定（如果此会话/线程绑定到了 ACP 会话）
3. 当前请求者会话回退

​

启动绑定模式

• --bind here 是“让这个渠道或聊天由 Codex 提供支持”的最简单操作路径。
• --bind here 不会创建子线程。
• --bind here 仅在暴露当前会话绑定支持的渠道上可用。
• --bind 和 --thread 不能在同一个 /acp spawn 调用中组合使用。

​

启动线程模式

• 在不支持线程绑定的界面上，默认行为实际上等同于 off。
• 线程绑定启动需要渠道策略支持：
  • Discord：channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram：channels.telegram.threadBindings.spawnAcpSessions=true
• 当你想固定当前会话而不创建子线程时，请使用 --bind here。

​

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 命令手册

​

运行时选项映射

• /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 harness 支持（当前）

• claude
• codex
• copilot
• cursor（Cursor CLI：cursor-agent acp）
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

必需配置

{
  acp: {
    enabled: true,
    // 可选。默认值为 true；设为 false 可在保留 /acp 控制的同时暂停 ACP 分发。
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    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

​

acpx 后端的插件设置

/acp doctor

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

openclaw plugins install ./path/to/local/acpx-plugin

/acp doctor

​

acpx 命令和版本配置

1. 命令默认指向 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 指向自定义二进制文件/路径时，插件本地自动安装会被禁用。
• 在后端健康检查运行期间，OpenClaw 启动保持非阻塞。

​

自动安装依赖

​

插件工具 MCP 桥接

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

• 将一个名为 openclaw-plugin-tools 的内置 MCP 服务器注入到 ACPX 会话 启动流程中。
• 暴露由已安装并启用的 OpenClaw 插件注册的插件工具。
• 保持该功能为显式启用，且默认关闭。

• 这会扩大 ACP harness 的工具暴露面。
• ACP 智能体只能访问 Gateway 网关 中已经处于活动状态的插件工具。
• 应将其视为与允许这些插件在 OpenClaw 本身中执行相同的信任边界。
• 启用前请审查已安装的插件。

​

运行时超时配置

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

​

权限配置

​

permissionMode

​

nonInteractivePermissions

​

配置

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，这样会话会优雅降级而不是崩溃。

​

故障排除