大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



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

---

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

典型应用场景：

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

---

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 

---

完整配置位于 C:Users퇕.openclawopenclaw.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 配置项说明

---

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 悬浮菜单

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.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.1 飞书悬浮菜单配置（推荐）

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

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 模式
  • 飞书端修改后需重新部署才能生效

  ---

坑 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 体系内部参考。