OpenClaw ACP 实战指南：用 Telegram/微信指挥 Claude Code 和 Codex 干活

前言

想象一下这样的场景：你正在通勤路上，突然想到一个代码改进方案。掏出手机，打开 Telegram 发一条消息给 AI：“用 Codex 帮我重构这个函数，增加错误处理”，几分钟后收到完成通知。这不是科幻，这是 OpenClaw ACP 带来的真实体验。

本文将详细介绍如何在 OpenClaw 中配置 ACP（Agent Client Protocol），实现通过聊天应用远程控制 Claude Code、Codex 等 AI 编程助手完成工作。

什么是 ACP？

ACP（Agent Client Protocol） 是一种标准化的协议，允许外部 AI 编码工具（如 Claude Code、Codex、Cursor 等）通过 OpenClaw 网关运行。简单来说：

用户消息 → OpenClaw Gateway → ACP 后端 → Claude Code/Codex → 执行任务 → 返回结果

ACP 支持的编码工具

工具	Agent ID	说明
Claude Code	`claude`	Anthropic 官方 CLI
OpenAI Codex	`codex`	OpenAI 编码助手
Cursor	`cursor`	Cursor CLI (`cursor-agent acp`)
Gemini CLI	`gemini`	Google Gemini 命令行
GitHub Copilot	`copilot`	GitHub 编码助手
Pi	`pi`	OpenClaw 内置代理
OpenCode	`opencode`	开源编码工具
Qwen	`qwen`	阿里通义千问

配置步骤

1. 安装 acpx 插件

openclaw plugins install @openclaw/acpx

2. 配置 OpenClaw

编辑 ~/.openclaw/config.json，添加以下配置：

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "permissionMode": "approve-all"
        }
      }
    }
  },
  "acp": {
    "enabled": true,
    "dispatch": {
      "enabled": true
    },
    "backend": "acpx",
    "defaultAgent": "claude",
    "allowedAgents": [
      "claude",
      "codex",
      "cursor",
      "gemini"
    ],
    "maxConcurrentSessions": 8,
    "runtime": {
      "ttlMinutes": 120
    }
  }
}

或者使用命令行配置：

openclaw config set plugins.entries.acpx.enabled true
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set acp.enabled true
openclaw config set acp.dispatch.enabled true
openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude

3. 重启 Gateway

openclaw gateway restart

4. 验证配置

/acp doctor

如果一切正常，你会看到后端健康状态和可用能力列表。

三种使用方式

方式一：自然语言对话（推荐）

直接在聊天中对 OpenClaw 说：

用 Claude Code 帮我重构这个函数

用 Codex 写一个测试用例

OpenClaw 会自动识别意图并路由到 ACP 后端。

方式二：手动 Spawn 会话

/acp spawn claude --mode persistent --thread auto

然后在同一个线程中继续对话，所有内容都会发送给 Claude Code。

方式三：使用 sessions_spawn 工具

在代码或 API 调用中使用：

{
  "task": "帮我写个测试",
  "runtime": "acp",
  "agentId": "claude",
  "thread": true,
  "mode": "session"
}

常用命令速查

命令	作用	示例
`/acp spawn`	创建 ACP 会话	`/acp spawn codex --bind here --cwd /repo`
`/acp status`	查看会话状态	`/acp status`
`/acp steer`	发送指导指令	`/acp steer 优先处理测试失败`
`/acp cancel`	取消当前轮次	`/acp cancel`
`/acp close`	关闭会话	`/acp close`
`/acp model`	切换模型	`/acp model anthropic/claude-opus-4`
`/acp permissions`	设置权限策略	`/acp permissions strict`
`/acp timeout`	设置超时时间	`/acp timeout 120`
`/acp doctor`	健康检查	`/acp doctor`

绑定模式详解

当前会话绑定 (`--bind here`)

将当前聊天绑定到 ACP 会话，后续消息自动路由：

/acp spawn codex --bind here

适用场景：

Discord 频道
Telegram 群组
iMessage 对话

线程绑定 (`--thread auto`)

创建或绑定到一个线程，保持上下文隔离：

/acp spawn claude --thread auto --mode persistent

适用场景：

Discord 线程
Telegram 话题

持久化绑定配置

在 config.json 中配置永久绑定：

{
  "bindings": [
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "discord",
        "accountId": "default",
        "peer": {
          "kind": "channel",
          "id": "222222222222222222"
        }
      },
      "acp": {
        "label": "codex-main",
        "cwd": "/workspace/my-project"
      }
    }
  ]
}

权限配置

ACP 会话是非交互式的，无法实时批准权限提示。因此需要预设权限策略：

permissionMode 选项

值	行为
`approve-all`	自动批准所有文件写入和 Shell 命令
`approve-reads`	只自动批准读取操作，写入和执行需要提示
`deny-all`	拒绝所有权限提示

配置示例

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

重要：如果不设置 approve-all，写入文件或执行命令时会因权限提示而失败。

实战场景

场景一：通勤路上修复 Bug

用户: 查看 src/auth/login.js 第 45 行的逻辑，修复那个空指针问题
Claude Code: [分析代码] 发现问题，已添加空值检查
用户: 写个测试用例覆盖这个场景
Claude Code: [生成测试] 已创建 test/auth/login.test.js

场景二：多项目管理

{
  "bindings": [
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "telegram",
        "peer": {
          "kind": "group",
          "id": "-1001234567890:topic:42"
        }
      },
      "acp": {
        "cwd": "/workspace/project-a"
      }
    },
    {
      "type": "acp",
      "agentId": "claude",
      "match": {
        "channel": "telegram",
        "peer": {
          "kind": "group",
          "id": "-1001234567890:topic:43"
        }
      },
      "acp": {
        "cwd": "/workspace/project-b"
      }
    }
  ]
}

不同 Telegram 话题绑定不同项目和工具。

场景三：代码审查

用户: 用 Claude Code 检查 PR #123 的代码质量
Claude Code: [分析 PR] 发现 3 个问题：1) 内存泄漏 2) 缺少错误处理 3) 类型不匹配
用户: 修复第一个问题
Claude Code: [修复] 已在 src/cache.js 添加内存释放逻辑

故障排除

问题	原因	解决方案
`ACP runtime backend is not configured`	后端插件未启用	运行 `/acp doctor`，安装并启用 acpx
`ACP is disabled by policy`	ACP 全局禁用	设置 `acp.enabled=true`
`Permission prompt unavailable`	权限模式不允许自动批准	设置 `permissionMode=approve-all`
`Agent not allowed by policy`	Agent 不在允许列表	更新 `acp.allowedAgents`
会话卡住无输出	权限提示被阻塞	检查 Gateway 日志，调整权限配置

最佳实践

使用 approve-all 权限模式 - ACP 会话无法交互式批准，必须预设权限
合理设置会话超时 - 默认 120 分钟，复杂任务可延长
使用持久化绑定 - 为常用项目配置固定绑定，避免重复创建会话
监控并发会话数 - 默认最多 8 个并发会话，根据需求调整
定期检查健康状态 - 使用 /acp doctor 确保后端正常

总结

OpenClaw ACP 让 AI 编程助手突破了终端的限制，通过熟悉的聊天应用即可远程控制 Claude Code、Codex 等工具完成编程任务。无论是通勤路上的灵感捕捉，还是多项目的并行管理，ACP 都能显著提升开发效率。

配置简单，体验强大——这就是 OpenClaw ACP 的魅力所在。

参考资料：

前言#

什么是 ACP？#

ACP 支持的编码工具#

配置步骤#

1. 安装 acpx 插件#

2. 配置 OpenClaw#

3. 重启 Gateway#

4. 验证配置#

三种使用方式#

方式一：自然语言对话（推荐）#

方式二：手动 Spawn 会话#

方式三：使用 sessions_spawn 工具#

常用命令速查#

绑定模式详解#

当前会话绑定 (--bind here)#

线程绑定 (--thread auto)#

持久化绑定配置#

权限配置#

permissionMode 选项#

配置示例#

实战场景#

场景一：通勤路上修复 Bug#

场景二：多项目管理#

场景三：代码审查#

故障排除#

最佳实践#

总结#

前言