OpenClaw ACP Agents 深度解析：让 AI 驱动外部编程工具

在 AI 辅助开发的浪潮中，如何将 Codex、Claude Code、Gemini CLI 等强大的外部编程工具无缝集成到自动化工作流中，一直是开发者关注的核心问题。OpenClaw 的 ACP（Agent Client Protocol） 机制给出了一个优雅的答案——通过统一的协议层，将任意外部编程 Harness 纳入 OpenClaw 的 Agent 编排体系，实现聊天驱动的代码工作流。

一、什么是 ACP Agents

ACP 的全称是 Agent Client Protocol，它是 OpenClaw 用于接入外部编程 Harness 的协议层。通过 ACP，OpenClaw 可以将 Pi、Claude Code、Codex、OpenCode、Gemini CLI、Kimi 等外部工具作为 Agent 会话来管理——你只需用自然语言告诉 OpenClaw “用 Codex 跑一下这个"或者"在 Discord 线程里启动一个 Claude Code 会话”，OpenClaw 就会自动路由到 ACP 运行时处理，而不是走原生的 Sub-Agent 路径。

这与 Sub-Agent 的本质区别在于：Sub-Agent 是 OpenClaw 原生的委托运行机制，ACP Session 是对外部 Harness 运行时的桥接。两者的对比如下：

选择原则很简单：需要外部 Harness 时用 ACP，需要 OpenClaw 原生委托时用 Sub-Agent。

二、快速上手：五步操作流程

对于想快速开始的开发者，以下是最精简的操作路径：

# 第一步：启动一个持久化 ACP 会话并绑定到当前线程
/acp spawn codex --mode persistent --thread auto

# 第二步：在绑定的线程中正常工作，消息自动路由到该 ACP 会话

# 第三步：检查运行时状态
/acp status

# 第四步：按需调整运行时参数
/acp model anthropic/claude-opus-4-5
/acp permissions approve-all
/acp timeout 300

# 第五步：结束工作
/acp cancel   # 停止当前轮次（保留会话）
/acp close    # 关闭会话并移除线程绑定

你也可以直接用自然语言驱动，OpenClaw 会自动解析意图：

• “在这里启动一个持久化 Codex 会话并保持专注。”
• “用 Claude Code 做一次性任务并总结结果。”
• “用 Gemini CLI 处理这个任务，后续跟进保持在同一线程。”

三、会话启动方式详解

3.1 通过 sessions_spawn 工具启动

在 Agent 的工具调用中，通过 sessions_spawn 并指定 runtime: "acp" 来启动 ACP 会话：

{
  "task": "打开仓库并总结失败的测试用例",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

关键参数说明：

• runtime：必须显式设置为 "acp"，否则默认走 subagent 路径。
• agentId：目标 Harness 的 id（如 codex、claude、gemini），省略时使用 acp.defaultAgent。
• mode：run（一次性）或 session（持久化），后者必须配合 thread: true。
• cwd：指定运行时工作目录，由后端策略验证。
• streamTo: "parent"：将 ACP 运行进度实时流式回传到发起方会话，接受响应中会包含 streamLogPath 指向 JSONL 日志文件。

3.2 通过 /acp spawn 命令启动

适合需要精确控制的操作者：

/acp spawn codex --mode persistent --thread auto --cwd /workspace/repo
/acp spawn claude --mode oneshot --thread off
/acp spawn gemini --thread here

--thread 参数的三种模式行为不同：

3.3 恢复已有会话

这是 ACP 的一个实用特性——通过 resumeSessionId 可以续接之前的会话，Agent 会通过 session/load 重播完整的对话历史，完整保留上下文：

{
  "task": "继续之前的工作——修复剩余的测试失败",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

典型应用场景包括：从笔记本切换到手机继续 Codex 会话、将命令行交互式会话无缝转为 Agent 托管的无头运行、从 gateway 重启或空闲超时中断后恢复工作。目前 Codex 和 Claude Code 均支持 session/load。

四、线程绑定机制

线程绑定是 ACP 的核心交互模式，它让 ACP 会话与聊天线程之间建立持久路由关系：OpenClaw 将线程绑定到目标 ACP 会话，该线程中的后续消息自动路由到绑定的 ACP 会话，ACP 输出也回传到同一线程，直到解绑、关闭、归档或超时。

目前内置支持线程绑定的渠道包括 Discord（线程/频道）和 Telegram（论坛话题）。启用时需要在配置中打开对应的 feature flag：

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

五、持久化渠道绑定配置

对于长期固定的工作流，可以在顶层 bindings[] 中配置持久化的 ACP 绑定，让特定渠道或话题始终路由到指定的 ACP 会话：

{
  "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" }
    }
  ]
}

配置生效后，对应渠道的消息会自动路由到配置的 ACP 会话，/new 和 /reset 命令会在原会话 key 上就地重置，而不是创建新会话。

配置优先级为：bindings[].acp.* > agents.list[].runtime.acp.* > 全局 ACP 默认值。

六、完整命令速查

七、后端安装与权限配置

7.1 安装 acpx 插件

ACP 功能依赖 acpx 后端插件，安装步骤如下：

# 安装插件
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

# 验证后端健康状态
/acp doctor

开发阶段也可以从本地路径安装：

openclaw plugins install ./extensions/acpx

7.2 核心 ACP 配置

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

7.3 权限配置（重要）

ACP 会话运行在非交互模式下，没有 TTY 来响应文件写入或 shell 执行的权限提示。acpx 插件提供两个关键配置项：

permissionMode 控制 Harness Agent 可以无提示执行的操作范围：

nonInteractivePermissions 控制在无 TTY 时遇到权限提示的处理方式：

实际使用中，默认的 permissionMode=approve-reads + nonInteractivePermissions=fail 组合意味着：任何写入或执行操作都会触发权限提示，而非交互模式下这会直接报错崩溃。强烈建议根据实际需求调整：

# 完全开放权限（适合受信任环境）
openclaw config set plugins.entries.acpx.config.permissionMode approve-all

# 或者设置优雅降级（写入被静默拒绝，不崩溃）
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions deny

修改后需要重启 gateway 生效。

八、沙箱兼容性说明

ACP 会话目前运行在宿主机运行时，而非 OpenClaw 沙箱内部。这带来一个重要约束：

• 如果发起方会话处于沙箱中，sessions_spawn({ runtime: "acp" }) 和 /acp spawn 都会被阻止，错误信息为：Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host.
• sessions_spawn 的 sandbox: "require" 参数对 ACP 运行时不支持。

结论： 需要沙箱隔离执行时，请使用 runtime: "subagent"；ACP 只能从非沙箱会话中发起。

九、常见问题排查

十、总结

OpenClaw 的 ACP Agents 机制填补了 AI 编程工具链中的一个关键空白——它让你不必在"用 OpenClaw 的 Agent 能力"和"用 Codex/Claude Code 等专业编程工具"之间二选一，而是通过统一的协议层将两者融合。聊天驱动、线程绑定、会话恢复、流式进度回传，这些特性共同构建了一个真正可用于生产环境的 AI 编程工作流平台。

对于希望将 AI 深度集成到开发流程的团队来说，ACP 值得作为核心基础设施认真评估和部署。

转载自CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/weixin_45092204/article/details/159216020