第 16 章

ACP 协议：调用 Claude Code / Codex / Gemini CLI 作为外部 Harness

第16章：ACP 协议——调用 Claude Code / Codex / Gemini CLI 作为外部 Harness

本章概览

当编程任务的复杂度超过单一模型对话的能力边界时，OpenClaw 提供了一套名为 ACP（Agent Client Protocol） 的协议层，允许它作为编排者，将具体的代码执行任务委托给专业化的外部 Agent（称为 Harness）。本章深入讲解 ACP 的架构设计、支持的 Harness 清单、核心操作命令，以及何时该选择 ACP 而非其他集成方式。

16.1 ACP 的架构定位

编排层 vs 运行时

ACP 确立了两个清晰的角色边界：

层级	角色	持有能力
OpenClaw（编排层）	调度者、协调者	路由决策 / 后台任务状态管理 / Delivery 模式 / Bindings（目录绑定）/ Policy 执行
Harness（运行时）	执行者、专家	Provider 登录凭据 / 模型目录访问 / 文件系统行为 / Native Tools（如终端、代码执行器）

这种分层的核心价值是：OpenClaw 永远不需要知道 Harness 内部如何运作。它只关心"任务完成了吗？输出是什么？"，而将所有执行细节委托给最擅长该任务的 Harness。

为什么不直接让 OpenClaw 写代码？

OpenClaw 是通用编排引擎，它的设计目标是跨领域协调，而不是深度代码工程。对于以下场景，专用 Harness 的优势明显：

大型多文件重构：需要同时理解数十个文件的上下文，维护跨文件一致性
复杂 C# / Java 项目：类型系统推理需要专门的语言服务器集成
持续集成任务：需要运行测试、等待 CI 结果、循环修复

实测数据表明，将此类任务路由至专用 Harness 后，准确率提升 25-35%，主要原因在第 16.8 节分析。

16.2 ACP 所支持的 10 种 Harness

OpenClaw 当前官方支持以下 Harness，每种都有独特的技术特点：

Harness	开发方	模型访问方式	擅长场景	特点备注
Claude Code	Anthropic	API Key / Claude.ai	多文件理解、长上下文重构	与 OpenClaw 同生态，集成最深
Codex	OpenAI	API Key	快速代码补全、单文件任务	速度快，Token 成本低
GitHub Copilot	GitHub/MS	GitHub 账户	IDE 内联建议、PR 审查	需要 GitHub 授权
Cursor	Anysphere	Cursor 账户	编辑器内多文件 Agent	Composer 模式支持深度重构
Droid	社区	可配置	移动端代码任务	轻量，适合资源受限环境
Gemini CLI	Google	Google 账户/API	超长上下文任务（100万 token）	上下文窗口最大
OpenCode	社区	可配置	开源替代方案	完全本地化部署
Qwen	阿里云	API Key	中文代码任务、中文注释生成	中文语境理解最佳
Kimi	Moonshot AI	API Key	长文档代码任务	长上下文中文优化
iFlow / Kilo Code	社区	可配置	工作流驱动的代码生成	适合 CI/CD 集成

Harness 选择决策树

任务是否涉及中文代码库注释？
  ├─ 是 → 优先 Qwen 或 Kimi
  └─ 否 → 文件数量 > 20？
            ├─ 是 → 上下文优先：Gemini CLI（100万token）
            │       准确度优先：Claude Code
            └─ 否 → 速度优先：Codex
                    集成度优先：Claude Code

16.3 核心操作命令：spawn / status / close

spawn：启动 Harness 实例

# 基础语法
/acp spawn <harness-name> [--bind <path>] [--cwd <dir>] [--thread <mode>]

# 示例1：在当前目录绑定 Claude Code
/acp spawn claude --bind here --cwd /workspace/repo

# 示例2：后台启动 Codex，自动管理 thread
/acp spawn codex --thread auto

# 示例3：为 Gemini CLI 指定特定工作目录
/acp spawn gemini --cwd /workspace/big-monorepo --thread new

参数说明：

参数	说明	默认值
`--bind here`	将当前目录绑定为 Harness 的工作根	无（需显式指定）
`--bind <path>`	指定绑定目录的绝对路径	无
`--cwd <dir>`	设置 Harness 进程的初始工作目录	继承 OpenClaw 当前目录
`--thread auto`	自动复用已有 thread 或创建新 thread	`new`
`--thread new`	强制创建全新对话 thread	—

status：查询任务状态

# 查看所有活跃的 ACP 实例
/acp status

# 查看特定实例
/acp status --id <session-id>

输出示例：

ACP Sessions:
  [abc123] claude  RUNNING   task: "Refactor auth module"  elapsed: 4m32s
  [def456] codex   COMPLETE  task: "Generate unit tests"   elapsed: 1m15s
  [ghi789] gemini  WAITING   task: "Analyze 80k-line codebase" elapsed: 12m01s

close：终止实例

# 正常关闭（等待当前任务完成）
/acp close <session-id>

# 强制终止
/acp close <session-id> --force

16.4 Interactive vs Background 两种交付模式

ACP 的交付模式（Delivery Mode）决定了 Harness 如何将结果返回给用户。

Interactive 模式（实时响应）

/acp spawn claude --bind here --delivery interactive

Harness 的输出实时流式传回 OpenClaw 对话界面
用户可以在任务进行中提问或修正方向
适合需要频繁人工决策的任务（如"遇到模糊需求时询问我"）
代价：占用前台 context，不能同时处理其他任务

典型使用场景：

正在进行的 API 设计讨论
需要实时确认数据库 Schema 变更的迁移任务
代码审查（需要作者在场解释意图）

Background 模式（完成后 announce）

/acp spawn codex --bind here --delivery background

Harness 在后台独立运行，OpenClaw 不阻塞
任务完成后，通过 announce 机制通知用户（通常是通知 + 摘要）
可以同时启动多个 Background Harness
适合：运行时间长（>5分钟）、无需实时干预的任务

典型使用场景：

生成整个模块的单元测试（可能需要 10-20 分钟）
分析大型代码库的依赖关系图
批量重命名/重构（跨 100+ 文件）

模式选择矩阵

场景特征	推荐模式
任务时间 < 2 分钟	Interactive
需要中途决策	Interactive
任务时间 > 5 分钟	Background
可并行多任务	Background
需要实时反馈	Interactive
批处理类任务	Background

16.5 Bindings：目录绑定机制

Bindings 是 ACP 中最重要的概念之一。它决定了 Harness 可以访问哪些文件系统路径。

# 绑定当前目录（最常用）
/acp spawn claude --bind here

# 绑定指定目录
/acp spawn claude --bind /workspace/backend

# 绑定多个目录（逗号分隔）
/acp spawn claude --bind /workspace/frontend,/workspace/backend

安全含义：

Harness 只能访问 bindings 内的路径
bindings 外的文件对 Harness 不可见（即使 Harness 本身有文件系统访问能力）
OpenClaw 的 Policy 层可以进一步限制读/写权限

16.6 实战案例：用 Claude Code 处理大型多文件重构

场景描述

一个 Node.js 项目需要将所有 callback 风格的异步函数迁移为 async/await，涉及 47 个文件，约 12,000 行代码。

步骤一：规划与启动

# 在项目根目录启动 Claude Code，后台模式
/acp spawn claude \
  --bind here \
  --cwd /workspace/node-project \
  --delivery background \
  --thread new

步骤二：发送任务描述

[ACP → Claude Code]
Task: Migrate all callback-style async functions to async/await across the entire codebase.

Constraints:
- Do NOT modify test files (*.test.js, *.spec.js)
- Preserve all existing JSDoc comments
- Run `npm test` after each file to verify no regressions
- If a file has > 3 failures, pause and report back

Start with the files in src/api/ directory, then src/services/, finally src/utils/

步骤三：监控进度

/acp status
# Output:
# [abc123] claude  RUNNING  task: "Callback→async/await migration"
#   Progress: 12/47 files complete, 0 test failures
#   Current: src/services/payment.service.js
#   Elapsed: 8m45s

步骤四：接收结果

任务完成后，OpenClaw 界面显示 announce：

✅ ACP Task Complete [abc123]
Harness: Claude Code
Duration: 34m12s
Files modified: 47
Test results: 284 passed, 0 failed
Summary: Successfully migrated all callback-style functions to async/await.
Notable: Found 3 cases where callback error handling was incomplete — added proper try/catch blocks.

16.7 三方对比：ACP vs Sub-agents vs Native Plugin

这三种集成方式经常让用户困惑，以下是权威对比：

ACP（外部 Harness）

OpenClaw ──ACP协议──▶ 独立进程（Claude Code / Codex 等）
                        ↑
                   运行在 OpenClaw 沙箱之外
                   拥有完整文件系统权限
                   可以运行任意 shell 命令

不受 OpenClaw 沙箱约束
有独立的模型访问、文件系统、网络访问
适合：需要完整系统访问权限的编程任务

Sub-agents（内部子代理）

OpenClaw ──内部调度──▶ Sub-agent
                        ↑
                   受 OpenClaw 沙箱约束
                   只能使用 OpenClaw 授权的工具
                   在同一 context 预算内运行

受 OpenClaw 沙箱约束
共享父代理的 context 预算和权限
适合：任务分解、并行查询、数据汇总

Native Plugin（原生插件）

OpenClaw ──插件 API──▶ 扩展模块
                        ↑
                   在 OpenClaw 进程内运行
                   访问 OpenClaw 内部 API
                   不启动独立 Agent

不是 Agent，是功能扩展
适合：添加新工具、新命令、UI 扩展

三方对比表

维度	ACP	Sub-agents	Native Plugin
独立进程	✅ 是	❌ 否	❌ 否
沙箱约束	❌ 不受约束	✅ 受约束	✅ 受约束
文件系统访问	完整	受限	受限
独立模型访问	✅ 是	❌ 否	❌ 否
适合任务类型	复杂编程	任务分解	功能扩展
启动开销	高（秒级）	低（毫秒级）	极低
错误隔离	完全隔离	部分隔离	无隔离

16.8 准确率提升 25-35% 的原理解析

实测数据中，将复杂编程任务路由至专用 Harness 后准确率提升 25-35%，主要来自以下四个机制：

1. 专用上下文窗口（最重要因素）

当 Claude Code 作为 Harness 运行时，它拥有独立的、干净的上下文窗口，没有被 OpenClaw 的对话历史、Skill 内容、工具定义等占用。对于一个 12,000 行的代码库，这意味着：

OpenClaw 直接处理：可用代码 context ≈ 总窗口 - 系统 prompt - 对话历史 ≈ 60-70%
Claude Code Harness 处理：可用代码 context ≈ 95%+

2. 专用工具集

Harness 的 native tools（如 Claude Code 的 read_file、write_file、bash）是专为代码工程优化的，比通用 OpenClaw 工具调用更高效。

3. 循环验证能力

Harness 可以运行代码、观察结果、修复错误，形成自主修复循环：

写代码 → 运行测试 → 分析失败 → 修复 → 再次运行测试 → ...

OpenClaw 本身没有这种持久化的执行环境。

4. 模型专业化

不同 Harness 使用不同底层模型，可以针对任务类型选择最优模型：

Gemini CLI → 超长上下文任务
Claude Code → 推理密集型任务
Codex → 高频低复杂度补全

16.9 ACP Policy 与安全控制

OpenClaw 的 Policy 层在 ACP 调用中仍然生效：

# openclaw.json 中的 ACP 策略配置示例
acp:
  allowed_harnesses:
    - claude
    - codex
  default_delivery: background
  max_concurrent_sessions: 3
  binding_restrictions:
    - allow: /workspace/**
    - deny: /workspace/secrets/**

关键安全原则：

OpenClaw 无法限制 Harness 内部行为，但可以限制哪些 Harness 被允许启动
Binding 路径是 OpenClaw 能施加影响的最主要安全边界
生产环境中建议明确列出 allowed_harnesses，避免用户启动未经审计的 Harness

16.10 本章小结

ACP 将 OpenClaw 定位为编排层，将代码执行委托给专业化 Harness
10 种 Harness 各有侧重，选择时优先考虑任务类型和上下文需求
spawn / status / close 是 ACP 的核心三件套
Interactive vs Background 的选择取决于任务时长和是否需要实时干预
ACP Harness 不受 OpenClaw 沙箱约束，这是它与 Sub-agents 的最大区别
准确率提升 25-35% 主要来自专用上下文窗口和自主修复循环

下一章将进入 Skills 系统的内部原理，解释 SKILL.md 格式的每个字段、懒加载机制，以及 description 如何成为模型决策的触发器。

本章评分

4.5 / 5 (18 评分)