OpenClaw + Claude Code 避坑指南:完整部署手册 + 5个血泪教训

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 配置项说明

配置项	值	作用
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.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
查看状态	/acp status
继续任务	/acp steer --session <key> 继续下一步
关闭会话	/acp close

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 对比

模式	上下文	适用场景
oneshot	无（每次独立）	简单一次性任务
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 指向的目录存在且有正确的文件结构

八、相关文件路径

文件	路径
acpx	D:\xxxx\xxx\nodeJs\node_24\node_global\node_modules\acpx\dist\cli.js
acpx wrapper	D:\xxxx\xxx\nodeJs\node_24\node_global\node_modules\.bin\acpx.cmd

总结：部署 OpenClaw + Claude Code 的核心就是三个配置——acp 段、acpx 插件段、以及 command 必须指向 acpx.cmd。把这5个坑记住，能省下你至少半天排查时间。

有问题欢迎评论区交流 👇

来源：OpenClaw + Claude Code 部署实战