OpenClaw + Claude Code 开发实战:ACPX 安装与配置

不想错过苏米的分享和推送？

戳上方蓝字“苏米客”关注我吧

并点击右上角“···”菜单，

选择“设为星标”

OpenClaw + Claude Code 开发实战：ACPX 安装与配置

别再当AI监工了，用OpenClaw + Claude Code实现全自动写代码

OpenClaw + Claude Code 实战指南：自动开发系统的完整方案

在前两篇里，我主要从“能不能自动写代码”这个结果层面，拆解了 OpenClaw + Claude Code 的整体方案。但实际落地时，很多人卡在更底层的一步：OpenClaw 是怎么调度 Claude Code 的？

这件事的关键不在 Claude Code 本身，而在一个中间层——ACPX（Agent Client Protocol 扩展）。简单理解：ACPX 负责把 OpenClaw 的任务，转成具体的编码 Agent 会话，并管理这些会话的生命周期。

这篇我把 ACPX 的安装、配置和实际调用方式完整梳理一遍，重点放在“怎么用”，而不是概念解释。

一、ACPX 插件安装

ACPX 是通过 OpenClaw 插件系统接入的，安装方式分为两种。

# 安装 acpx 插件openclaw plugins install acpx# 启用插件openclaw config set plugins.entries.acpx.enabled true

2）开发环境安装

如果你在本地做扩展开发：

openclaw plugins install ./extensions/acpx

3）验证安装状态

/acp doctor

这里的检查主要是确认：

• ACP runtime 是否可用
• 后端是否正确绑定为 acpx
• Agent 列表是否加载成功

二、核心配置（openclaw.json）

安装完成后，真正决定 ACPX 是否能工作的，是这一段配置：

{  "acp": {    "enabled":true,    "dispatch": { "enabled":true },    "backend": "acpx",    "defaultAgent": "codex",    "allowedAgents": ["pi", "claude", "codex", "opencode", "gemini", "kimi"],    "maxConcurrentSessions": 8  }}

这一段配置可以拆成几个关键维度来看：

| 配置项 | 作用 | 使用建议 || --- | - | || enabled | 是否启用 ACP | 必须开启 || dispatch.enabled | 是否允许调度 | 自动化场景必须开启 || backend | 使用的后端 | 固定为 acpx || defaultAgent | 默认编码 Agent | 建议设为 codex 或 claude || allowedAgents | 可调用 Agent 白名单 | 控制安全与资源 || maxConcurrentSessions | 最大并发会话数 | 根据机器性能调整 |

三、ACPX 的调用方式

ACPX 本质上是一个“会话调度层”，它提供三种调用方式。

1）自然语言调用

这是最轻量的方式，适合快速测试：

• “Start a persistent Codex session in a thread here”
• “Run this as a one-shot Claude Code ACP session”
• “Use Gemini CLI for this task in a thread”

特点：

• 不需要记命令
• 依赖模型理解
• 可读性强，但可控性略弱

2）/acp 命令调用（推荐）

这是最稳定、可控性最高的方式：

# 持久化会话（有上下文）/acp spawn codex --mode persistent --thread auto# 一次性任务（无上下文）/acp spawn codex --mode oneshot --thread off# 在当前线程创建/acp spawn codex --thread here

几个关键参数：

| 参数 | 含义 || | -- || mode | persistent / oneshot || thread | 是否绑定线程 || agent | 使用的编码模型 |

使用建议：

• 长任务 → persistent
• 单次生成 → oneshot
• 多轮协作 → thread here

3）通过 sessions_spawn（程序化调用）

适合接入自动化流程或 Agent 编排：

{  "task": "你的任务描述",  "runtime": "acp",  "agentId": "codex",  "thread":true,  "mode": "session"}

这个方式的特点是：

• 可嵌入工作流
• 可批量调度
• 更适合“无人干预”的自动执行

四、支持的 Agent 类型

ACPX 默认支持多个编码 Agent：

Agent	说明
pi	Pi Dev
claude	Claude Code
codex	Codex
opencode	OpenCode
gemini	Gemini CLI
kimi	Kimi

这里有一个实际使用中的差异点：

• Claude / Codex → 更偏复杂代码生成
• Gemini / Kimi → 更偏辅助处理或轻量任务

五、权限配置（必须处理）

ACPX 的执行是非交互式的，权限策略必须提前设好，否则任务会直接失败。

# 开发环境：允许所有操作openclaw config set plugins.entries.acpx.config.permissionMode approve-all# 只读模式openclaw config set plugins.entries.acpx.config.permissionMode approve-reads# 非交互式默认策略openclaw config set plugins.entries.acpx.config.nonInteractivePermissions deny

可以理解为三种策略：

模式	行为
approve-all	自动放行所有操作
approve-reads	仅允许读取
deny	默认拒绝

实践建议：

• 本地开发 → approve-all
• 生产环境 → 精细化控制

六、常用 ACP 命令

| 命令 | 功能 || - | || /acp spawn | 创建会话 || /acp status | 查看状态 || /acp cancel | 取消任务 || /acp close | 关闭会话 || /acp steer | 发送控制指令 || /acp sessions | 查看历史会话 |

这里 /acp steer 很关键，它允许你在会话运行过程中动态调整任务方向，相当于对 Agent 进行“中途干预”。

七、allowedAgents 的作用（容易被忽略）

"acp": {  "allowedAgents": ["agent1", "agent2"]}

这个配置本质上是一个白名单机制，作用有三层：

1）安全控制

只有在列表中的 Agent 才能被启动

2）防止滥用

避免任意 Agent 调用外部编码能力

3）资源管理

限制并发来源，避免系统被占满

如果你希望开放所有 Agent：

"allowedAgents": ["*"]

但在实际使用中，不建议默认全开放。

八、典型使用场景

从我自己的使用情况来看，ACPX 主要解决的是“任务隔离 + 会话管理”：

• 代码生成：让 Claude Code 在独立会话中完成复杂模块
• 项目分析：持续扫描代码库（需要 persistent）
• 多轮开发：保持上下文连续
• 团队协作：不同成员绑定不同会话

结尾总结

如果只看结果，OpenClaw + Claude Code 像是在“自动写代码”；但从系统结构来看，真正关键的是 ACPX 这一层：

• 它负责把任务转成会话
• 管理Agent 调度
• 控制权限与资源
• 提供可持续上下文

也正因为有这一层，OpenClaw 才能从“单次调用模型”，变成“可调度的开发系统”。

如果你之前卡在“为什么调不起来 Claude Code”，基本可以从这三点排查：

• ACPX 是否正确安装
• openclaw.json 是否配置完整
• 权限策略是否允许执行

把这三步跑通，后面的自动化能力才有意义。

如果你喜欢我的文章，请关注、点赞、转发，这对我真的很重要，感谢你的喜爱。如果想第一时间收到推送，请将本公众号加个星标🌟

📮 往期精彩文章

微信ClawBot来了！个人微信也能玩转AI助手
在飞书里用语音跟虾米聊天是什么体验？
虾米公司流水线升级：终于不用天天盯岗了！
OpenClaw + Claude Code 实战指南：自动开发系统的完整方案
别再当 AI 监工了，用 OpenClaw + Claude Code 实现全自动写代码