夜雨聆风不想错过苏米的分享和推送？
戳上方蓝字“苏米客”关注我吧
并点击右上角“···”菜单，
选择“设为星标”
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 true2）开发环境安装
如果你在本地做扩展开发：
openclaw plugins install ./extensions/acpx3）验证安装状态
/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：
这里有一个实际使用中的差异点：
• 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 • 生产环境 → 精细化控制
六、常用 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 是否配置完整 • 权限策略是否允许执行
把这三步跑通，后面的自动化能力才有意义。
📮 往期精彩文章
