ACP 代理

快速操作流程

1. ✦创建一个会话：
   • ✦/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（关闭会话 + 移除绑定）

人类用户快速入门

• ✦"在这里的线程中启动一个持久 Codex 会话并保持专注。"
• ✦"将此作为一次性 Claude Code ACP 会话运行并总结结果。"
• ✦"在线程中使用 Gemini CLI 完成此任务，然后在同一线程中继续后续操作。"

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

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>"
• ✦bindings[].agentId 是所属 OpenClaw 代理 ID。
• ✦可选的 ACP 覆盖项位于 bindings[].acp 下：
  • ✦mode（persistent 或 oneshot）
  • ✦label
  • ✦cwd
  • ✦backend

每个代理的运行时默认值

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

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

json5
{
  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

json
{
  "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 日志（<sessionId>.acp-stream.jsonl），你可以 tail 查看完整的中继历史。

恢复现有会话

json
{
  "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，创建将失败并返回明确错误 — 不会静默回退到新会话。

操作者冒烟测试

1. ✦验证目标主机上已部署的网关版本/提交。
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 桥接会话。

text
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 主题中执行。

沙箱兼容性

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

通过 /acp 命令

text
/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>

会话目标解析

1. ✦显式目标参数（或 /acp steer 的 --session）
   • ✦先尝试 key
   • ✦然后尝试 UUID 格式的 session id
   • ✦然后尝试 label
2. ✦当前线程绑定（如果当前对话/线程绑定到 ACP 会话）
3. ✦当前请求方会话回退

创建线程模式

• ✦在不支持线程绑定的界面上，默认行为实际上是 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 命令手册

运行时选项映射

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

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

必需配置

json5
{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

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

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

acpx 后端的插件设置

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

bash
openclaw plugins install ./extensions/acpx

text
/acp doctor

acpx 命令和版本配置

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

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

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

权限配置

permissionMode

nonInteractivePermissions

配置

bash
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，使会话优雅降级而非崩溃。

故障排查