夜雨聆风OpenClaw + Claude Code 避坑指南
完整部署手册 + 5个血泪教训，收藏备用
用 OpenClaw 调度 Claude Code 做复杂代码任务，真的很香。但部署过程坑不少。
今天把完整流程和5个致命坑点整理出来，建议先收藏再阅读。
一、什么是 Claude ACP
ACP（Agent Client Protocol）是 OpenClaw 与 Claude Code 之间的通信协议。通过 ACP，OpenClaw 可以调度 Claude Code 作为子 Agent，在指定目录下执行任务。
适用场景：
复杂代码编写（比通用 Agent 更擅长） 长周期项目开发 需要持久上下文的对话任务
二、安装 acpx
执行以下命令安装 acpx：
npm install -g acpx@0.4.0
⚠️ 关键提醒：acpx 版本必须与 OpenClaw 内置版本一致，否则会报接口不兼容错误。
三、配置文件完整示例
配置文件位于用户目录下，需同时配置 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工作目录" } } } } }
3.3 配置项说明
| 必须是 acpx.cmd，不能是 node.exe | ||
四、飞书配置（可选）
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 pairing approve feishu <配对码>
五、Gateway 管理
启动 Gateway
openclaw gateway install
openclaw gateway start
计划任务管理
schtasks /query /tn "OpenClaw Gateway" /fo list
schtasks /end /tn "OpenClaw Gateway"
schtasks /run /tn "OpenClaw Gateway"
六、ACP 命令详解
常用命令
# 健康检查
/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>
oneshot vs persistent 对比
七、避坑指南（重点⭐）
这部分内容是精华，建议仔细阅读
坑 1：spawn 后 Claude 报 "bad option: --format"
现象：spawn 成功但 Claude 无响应，日志显示 bad option: --format
原因：
strictWindowsCmdWrapper 默认为 true，Gateway 用非 shell 方式执行，PATH 不完整 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 和上下文
解法：
在 acpx config 设置 cwd指定项目根目录在项目目录放置 CLAUDE.md作为上下文入口
坑 5：cwd 配置的工作目录不存在
现象：Claude 启动后报路径错误
解法：确认 cwd 指向的目录存在且有正确的文件结构
八、相关文件路径
总结：部署 OpenClaw + Claude Code 的核心就是三个配置——acp 段、acpx 插件段、以及 command 必须指向 acpx.cmd。把这5个坑记住，能省下你至少半天排查时间。
有问题欢迎评论区交流 👇
来源：OpenClaw + Claude Code 部署实战
