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



上一篇：[第032篇] OpenClaw v2026.4.1 深度解析：聊天原生任务板、SearXNG 搜索与安全护栏如何重塑 AI Agent 工作流
下一篇：[第034篇] OpenClaw v2026.4.2 深度解析：Task Flow 持久任务流与 Provider 传输安全全面升级

---

OpenClaw ACP（Agent Client Protocol） 是一套用于在消息平台中统一管理外部编码智能体的标准化协议层。通过 OpenClaw 官方维护的 acpx 插件，开发者可以在单个 OpenClaw 实例中同时调度 Claude Code、Codex、Gemini CLI、Cursor 等 10+ 主流编码智能体，实现跨工具协作的“超级工作流”。本文将从协议原理、acpx 插件安装、配置详解、使用场景、权限安全五个维度，为读者提供从理论到实战的完整指南。

---

1.1 ACP 的本质定义

ACP（Agent Client Protocol） 是 OpenClaw 用于接入外部编程工具的统一协议层，通过消息代理模式实现多智能体的标准化通信。

在 ACP 出现之前，开发者需要在不同工具间切换：写代码用 Claude Code、查文档用 Gemini CLI、做代码补全用 Cursor。这种“工具孤岛”现象严重影响了开发效率。ACP 的出现，正是为了解决这一痛点。

1.2 ACP vs MCP：两个协议的分工

很多开发者容易将 ACP 与 MCP（Model Context Protocol）混淆。实际上，两者有着明确的分工：

根据 OpenClaw 官方文档，ACP 协议复用 MCP 的 JSON 表示格式，并默认采用 Markdown 作为用户可读文本格式，这种设计降低了学习成本，同时保证了协议的互操作性。

1.3 ACP 的核心价值

ACP 协议的三大核心价值：

• 协议标准化：解耦智能体与平台，支持生态互通
• 会话持久化：通过线程绑定保持上下文，支持跨设备续接
• 多智能体并发：通过队列机制支持并行任务处理

---

2.1 acpx 是什么

acpx 是 OpenClaw 官方维护的 TypeScript 编写的 ACP 后端插件，提供对外部编码智能体的统一接入能力。GitHub 仓库目前已获得 992+ Stars（数据截至 2026-04-02）。

acpx 的设计理念是“Headless CLI Client”——无需图形界面，通过命令行即可管理有状态的 ACP 会话。它支持两种运行方式：

# 全局安装（推荐） npm install -g acpx@latest

# 无需安装直接使用 npx acpx@latest

2.2 支持的编码智能体矩阵

截至 acpx 0.4.0 版本（2026-03-29 发布），已原生支持以下编码智能体：

2.3 acpx 0.4.0 新特性

2026 年 3 月 29 日发布的 0.4.0 版本带来了多项重要更新：

流程执行功能（Flow Execution）：

acpx flow run <file> # 支持 TypeScript 流程模块 

Flow 执行支持多种步骤类型：acp（智能体调用）、action（确定性操作）、compute（计算）、checkpoint（检查点）。

增强的会话管理：

• 命名会话支持并行工作流
• 队列感知提示提交
• 优雅的取消机制（Ctrl+C 发送 ACP 取消信号）

灵活的输出格式：

acpx codex –format text # 人类可读格式（默认） acpx codex –format json # NDJSON 事件流 acpx codex –format quiet # 仅显示最终文本 

---

3.1 Client-Agent 通信模型

ACP 采用经典的 Client-Agent 架构：

┌─────────────────────────────────────────────────────────┐ │ OpenClaw Gateway │ │ ┌─────────────────────────────────────────────────┐ │ │ │ ACP 会话管理层 │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Claude │ │ Codex │ │ Gemini │ … │ │ │ │ │ Code │ │ │ │ CLI │ │ │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ └───────┼────────────┼────────────┼────────────────┘ │ │ │ │ │ │ └──────────┼────────────┼────────────┼─────────────────────┘

 │ │ │ ▼ ▼ ▼ [Unix Socket / HTTP / stdio] │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Claude │ │ Codex │ │ Gemini │ │ Code CLI│ │ CLI │ │ CLI │ └─────────┘ └─────────┘ └─────────┘ 

通信流程：

1. 用户通过消息平台（Discord/Telegram/飞书）发送指令
2. OpenClaw Gateway 解析指令，通过 acpx 后端创建 ACP 会话
3. acpx 与目标智能体 CLI 建立连接
4. 智能体执行任务，通过 JSON-RPC 2.0 协议回传进度
5. Gateway 将结果格式化后返回给用户

3.2 会话管理机制

会话标识格式：

• ACP 会话：agent: :acp:
• Sub-agent 会话：agent: :subagent:

会话模式：

{ “runtime”: “acp”, “agentId”: “codex”, “mode”: “session” // 或 “run”（一次性执行） } 

• run 模式：任务完成后会话结束，适用于简单查询
• session 模式：保持会话，支持多轮对话，适用于复杂项目

3.3 线程绑定机制

线程绑定是 ACP 实现跨会话上下文保持的核心机制，允许同一个任务在不同消息线程中无缝续接。

绑定配置示例：

{ “bindings”: [

{ "type": "acp", "agentId": "codex", "match": { "channel": "discord", "accountId": "default", "peer": { "kind": "channel", "id": "" } }, "acp": { "label": "codex-main" } } 

] }

绑定生命周期：

• 支持 Discord 线程、Telegram 话题等平台
• 绑定后，同一线程内的消息自动路由到对应的 ACP 会话
• 绑定在空闲超时（默认 300 秒）、关闭或归档时自动解除

3.4 流式进度回传

ACP 支持实时流式传输智能体执行进度：

{ “task”: “分析代码库并生成测试报告”, “runtime”: “acp”, “agentId”: “codex”, “streamTo”: “parent”, // 启用流式回传 “streamLogPath”: “/tmp/codex.log” } 

这使得用户可以在 OpenClaw 对话窗口中实时看到 Claude Code 或 Codex 的执行日志，实现真正的“实时协作”。

---

4.1 环境准备

前置条件：

1. OpenClaw Gateway 已安装并运行
2. Node.js 18+ 环境
3. 目标智能体 CLI 已安装（Claude Code / Codex 等）

验证 OpenClaw 安装：

openclaw –version # 输出应类似: openclaw/2026.4.1 或更高版本 

4.2 acpx 插件安装

步骤一：安装 acpx 全局包

npm install -g acpx@latest 

步骤二：在 OpenClaw 中启用 acpx 插件

openclaw plugins install acpx openclaw config set plugins.entries.acpx.enabled true 

步骤三：配置目标智能体

根据需要调用的智能体类型，配置相应的 API 密钥：

# Claude Code 配置 export ANTHROPIC_API_KEY=“sk-ant-…”

# Codex 配置 export OPENAI_API_KEY=“sk-…”

# Gemini CLI 配置 export GOOGLE_API_KEY=“…”

4.3 OpenClaw 配置详解

完整配置示例（openclaw.yml）：

# acp 全局配置 acp: enabled: true backend: “acpx” defaultAgent: “codex” # 默认调用的智能体 allowedAgents:

- "claude" # Claude Code - "codex" # OpenAI Codex - "gemini" # Gemini CLI - "kimi" # 国产 Kimi 

maxConcurrentSessions: 8 # 最大并发会话数 permissionMode: “approve-reads” # 权限模式

# acpx 插件配置 plugins: entries:

acpx: enabled: true config: permissionMode: "approve-reads" # approve-all / approve-reads / deny-all nonInteractivePermissions: "fail" # fail / deny sessionTtlMinutes: 120 

# 会话配置 session: threadBindings:

enabled: true idleHours: 24 

4.4 智能体级别配置

可以为不同的智能体配置独立参数：

agents: list:

- id: "codex" runtime: type: "acp" acp: agent: "codex" backend: "acpx" mode: "persistent" cwd: "/workspace/openclaw" env: OPENAI_API_KEY: "${OPENAI_API_KEY}" 

---

5.1 场景一：自然语言调度多智能体

最推荐的使用方式——直接用自然语言指令 OpenClaw：

用户：在 /workspace/openclaw 目录下，用 Claude Code 重构用户认证模块，重点优化安全性 

OpenClaw 会自动识别任务需求，通过 ACP 调用 Claude Code 执行。执行结果实时流式回传至对话窗口。

5.2 场景二：手动 Spawn 持久化会话

对于需要长时间协作的任务，使用 /acp spawn 命令创建持久化会话：

# 创建 Codex 持久化会话 /acp spawn codex –mode persistent –thread auto –cwd /workspace/project

# 查看会话状态 /acp status

# 发送指导指令 /acp steer prioritize error handling and add logging

# 关闭会话 /acp close

5.3 场景三：多智能体协作

ACP 支持同时运行多个智能体，实现专业分工：

用户：分析这个 Python 项目的性能瓶颈

 - 用 Claude Code 做代码分析 - 用 Gemini CLI 查相关文档 - 汇总成报告 

5.4 场景四：与消息平台集成

Discord 集成示例：

1. 在 Discord 创建专属频道
2. 配置 OpenClaw 的 Discord 绑定
3. 在频道中直接调用 ACP 智能体：

@OpenClaw /acp spawn claude –cwd /repo/backend 

5.5 核心命令速查表

---

6.1 三种权限模式

ACP 提供细粒度的权限控制，满足不同场景需求：

配置命令：

openclaw config set plugins.entries.acpx.config.permissionMode approve-all openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail 

6.2 非交互模式策略

当智能体请求权限但无法弹出确认框时（如后台运行），acpx 提供两种处理策略：

• fail：权限被拒时直接报错并中止会话
• deny：静默拒绝并继续执行（跳过需要权限的操作）

6.3 安全加固建议

基于 2026 年 OpenClaw 安全白皮书，企业级部署应遵循以下原则：

1. 最小权限原则：生产环境建议使用 approve-reads 模式
2. 会话隔离：不同项目使用独立的 ACP 会话
3. API 密钥管理：使用环境变量而非配置文件存储敏感信息
4. 审计日志：开启 OpenClaw 的审计功能，记录所有 ACP 调用
5. 超时控制：设置合理的会话 TTL（默认 120 分钟）

---

7.1 常见问题与解决方案

7.2 诊断命令

健康检查：

/acp doctor 

该命令会检查 acpx 插件状态、可用智能体列表、权限配置等关键指标。

烟雾测试：

/acp spawn codex –mode run –task “echo ‘ACP is working’” 

成功的响应应包含 LIVE-acp-spawn-ok 标识。

7.3 日志查看

实时日志：

tail -f ~/.openclaw/logs/acp.log 

会话日志：

cat /tmp/codex.log # 需在 spawn 时指定 streamLogPath 

---

8.1 两种工具的互补优势

OpenClaw 与 Claude Code 有着截然不同的设计哲学：

OpenClaw 的 ACP 强调长时间运行、实时监控和灵活控制；Claude Code 的 Team 系统则在结构化协作、角色分工方面更为出色。

8.2 推荐协同模式

场景：复杂项目开发

1. 规划阶段：在 OpenClaw 中用自然语言描述需求，OpenClaw 调用 Claude Code 生成技术方案
2. 编码阶段：Claude Code 执行具体编码任务，通过 ACP 流式回传进度
3. 审查阶段：OpenClaw 整合 Claude Code 的输出，调用 Codex 进行代码审查
4. 部署阶段：通过 OpenClaw 的多渠道通知，跨平台协作完成部署

8.3 跨设备续接

ACP 的线程绑定机制支持跨设备续接：

用户在办公室电脑启动 Codex 会话，处理用户认证模块

 ↓ 

下班后，用户在手机上继续会话，OpenClaw 自动恢复上下文

 ↓ 

在家中电脑，用户查看会话历史，继续未完成的任务

---

OpenClaw ACP Agents 代表了 AI 编程工作流的未来方向——不是用单一智能体完成所有任务，而是通过标准化协议将多个专业化工具整合成统一的工作流平台。

本文核心要点回顾：

• ACP 协议是连接 OpenClaw 与外部编码智能体的标准化桥梁
• acpx 插件是 ACP 协议的核心实现，支持 10+ 主流编码智能体
• 会话持久化与线程绑定是实现跨会话上下文保持的关键
• 权限控制提供从 approve-all 到 deny-all 的灵活选择
• ACP 与 Claude Code 的互补使用可以最大化开发效率

随着 acpx 0.4.0 引入的 Flow 执行功能，OpenClaw ACP Agents 正在从“工具集成层”进化为“智能工作流编排平台”，这或许是 2026 年 AI 开发领域最值得关注的技术趋势之一。

---

上一篇：[第032篇] OpenClaw v2026.4.1 深度解析：聊天原生任务板、SearXNG 搜索与安全护栏如何重塑 AI Agent 工作流
下一篇：[第034篇] OpenClaw v2026.4.2 深度解析：Task Flow 持久任务流与 Provider 传输安全全面升级

---

1. ACP 代理 - OpenClaw 官方文档
2. GitHub - openclaw/acpx
3. OpenClaw ACP Agents：在消息平台中统一管理 Claude Code 和 Codex
4. OpenClaw ACP Agents 深度解析：让 AI 驱动外部编程工具
5. OpenClaw vs Claude Code 深度代码级对比研究报告 v2
6. OpenClaw ACP 实战指南：用 Telegram 指挥 Claude Code