Claude ACP 配置与避坑指南

OpenClaw + Claude Code (ACP Harness) 部署完整指南 | 枢归档

---

1. 什么是 Claude ACP

Claude ACP（Agent Client Protocol）是 OpenClaw 与外部 Agent Harness（如 Claude Code）之间的通信协议。通过 ACP，OpenClaw 可以调度 Claude Code 作为子 Agent，在指定工作目录下执行任务。

典型应用场景：

• 复杂代码编写（Claude Code 比通用 Agent 更擅长）
• 长周期项目开发
• 需要持久上下文的对话任务

---

2. 安装 acpx

npm install -g acpx@0.4.0

注意：acpx 版本必须与 OpenClaw 内置版本一致，否则会报接口不兼容错误。

版本不一致的表现：

# 全局装了 0.4.1，内置 0.4.0
# → 接口不兼容，报错

如已安装其他版本，先卸载再装指定版本：

npm uninstall -g acpx
npm install -g acpx@0.4.0

---

3. 配置文件完整示例

完整配置位于 C:\Users\user\.openclaw\openclaw.json，分为 acp 配置段和 acpx 插件段。

3.1 acp 配置段

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

3.2 acpx 插件配置段

{
  "plugins": {
    "allow": ["acpx"],
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "permissionMode": "approve-all",
          "nonInteractivePermissions": "deny",
          "strictWindowsCmdWrapper": false,
          "expectedVersion": "any",
          "command": "D:\\xxxxx\\xxxxx\\nodeJs\\node_24\\node_global\\node_modules\\.bin\\acpx.cmd",
          "cwd": "claude工作目录"
        }
      }
    }
  }
}

command是必须的不然会出问题

3.3 配置项说明

配置项	值	作用
backend	acpx	ACP 后端
defaultAgent	claude	默认调度的 Harness
allowedAgents	[“claude”]	允许的 Harness 列表
permissionMode	approve-all	自动批准所有文件读写/命令执行
nonInteractivePermissions	deny	无 TTY 时静默拒绝权限
strictWindowsCmdWrapper	false	用 shell 方式执行 acpx，继承完整 PATH
expectedVersion	any	跳过 acpx 版本校验
command	指向 acpx.cmd	必须是 acpx.cmd，不能是 node.exe
cwd	项目路径	spawn 时的工作目录

---

4. 飞书配置（可选）

4.1 创建应用

在飞书开放平台创建应用，获取 appid 和 secret。

4.2 权限配置

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "application:bot.menu:write"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

4.3 事件订阅

订阅方式：长连接（WebSocket）

必加事件：im.message.receive_v1

4.4 悬浮菜单

动作	发送内容
发送文字消息	/acp spawn claude --bind here （绑定会话，不过有点坑的是不知道为啥会创建大量的node进程，可能有二百来个吧，这个可以注意下）
发送文字消息	/acp status
发送文字消息	/acp steer --session <key> 继续下一步
发送文字消息	/acp close

4.5 openclaw.json 飞书配置

{
  "channels": {
    "feishu": {
      "enabled": true,
      "connectionMode": "websocket",
      "dmPolicy": "allowlist",
      "allowFrom": ["xxxx"],
      "streaming": true,
      "groupPolicy": "allowlist",
      "accounts": {
        "mohu": {
          "appId": "appId1",
          "appSecret": "appSecret1",
          "name": "agentId1"
        }
      }
    }
  },
  "bindings": [
    { "match": { "channel": "feishu" }, "agentId": "mo" }
  ]
}

4.6 配对

1. 飞书给机器人发消息
2. 获取配对码
3. 执行审批：

openclaw pairing approve feishu <配对码>

---

5. Gateway 管理

5.1 启动 Gateway

openclaw gateway install
openclaw gateway start

5.2 计划任务管理

schtasks /query /tn "OpenClaw Gateway" /fo list
schtasks /end /tn "OpenClaw Gateway"
schtasks /run /tn "OpenClaw Gateway"

---

6. ACP 命令详解

6.1 飞书悬浮菜单配置（推荐）

在飞书机器人菜单配置以下动作，通过按钮触发：

菜单按钮	发送内容	作用
新建任务	/acp spawn claude --bind here	启动一个与当前飞书会话绑定的 Claude 会话
查看状态	/acp status	查看当前所有 ACP 会话状态
继续任务	/acp steer --session <key> <指令>	向指定会话发送指令（继续执行）
关闭会话	/acp close	关闭当前/指定会话

6.2 常用命令

# 健康检查（确认 acpx 和 Claude Code 可用）
/acp doctor

# 启动单次任务（oneshot）
/acp spawn claude --mode oneshot -- <任务描述>

# 启动持久会话（persistent）
/acp spawn claude --mode persistent --bind here

# 查看当前所有会话
/acp status

# 向指定会话发送指令
/acp steer --session <session_key> <指令内容>

# 关闭会话
/acp close --session <session_key>

# 或在飞书菜单直接发对应文字
/acp spawn claude --bind here   # 绑定当前会话启动
/acp status                     # 查看状态
/acp close                      # 关闭当前会话

6.3 会话管理

# 持久会话特点
- 会话保持上下文，适合长周期任务
- 每次 spawn 生成一个新的 session_key
- 通过 --bind here 将会话绑定到当前飞书私聊

# oneshot vs persistent 对比
| 模式 | 上下文 | 适用场景 |
|------|--------|---------|
| oneshot | 无（每次独立） | 简单一次性任务 |
| persistent | 保持 | 复杂长任务、多轮对话 |

# 指令注入（steer）
/acp steer --session agent:acp:claude:abc123 继续写下一章
- steer 在当前模型调用结束后注入指令
- 适用于：追加需求、修正方向、继续生成

6.4 已知限制

• OpenClaw 内置 ACP 命令有限，完整功能需依赖飞书悬浮菜单
• --mode persistent 需要 Claude Code 支持 session 模式
• 飞书端修改后需重新部署才能生效

---

7. 避坑指南（重点）

坑 1：spawn 后 Claude 报 “bad option: --format”

现象：spawn 成功但 Claude 无响应，日志显示 bad option: --format

原因：

1. strictWindowsCmdWrapper 默认为 true，Gateway 用非 shell 方式执行，PATH 不完整
2. command 指向 node.exe 时参数被错误传递

解法：

"strictWindowsCmdWrapper": false,
"command": "D:\\...\\acpx.cmd"

坑 2：command 必须指向 acpx.cmd，不能是 node.exe

原因：OpenClaw 发出 --format json 参数，追加到 node.exe 后变成 node.exe --format json，node 不识别此参数

解法：command 必须指向 acpx.cmd，不能是 node.exe 也不能是 cli.js

坑 3：acpx 版本不一致

现象：接口不兼容，报错

原因：全局装了 0.4.1，OpenClaw 内置 0.4.0，版本不匹配

解法：

npm uninstall -g acpx
npm install -g acpx@0.4.0

坑 4：spawn 后 Claude 找不到项目路径

现象：Claude 启动后无法定位 state.json 和上下文

解法：

1. 在 acpx config 设置 cwd 指定项目根目录
2. 在项目目录放置 CLAUDE.md 作为上下文入口

坑 5：cwd 配置的工作目录不存在

现象：Claude 启动后报路径错误

解法：确认 cwd 指向的目录存在且有正确的文件结构

---

---

本文档由枢归档，供星核 Agent 体系内部参考。