Acpx Harness Delegation

通过 ACP runtime 委托 acpx-enabled harness（Claude Code / Codex 等）的标准协议。

触发条件（满足其一）

• "调用 Claude Code"
• "通过 acp 调用"
• "通过 acpx 调用"
• "delegation to claude"
• "delegation to codex"
• "Coordinator 调用 Executor"
• "spawn acpx harness"
• "用 acp 调用外部 agent"
• "通过 ACP 委托 harness"

核心调用方式

✅ 标准 sessions_spawn（结果自动推回父 channel）

sessions_spawn({
  runtime: "acp",
  agentId: "claude",       // 或 codex / pi / opencode / gemini / kimi
  mode: "session",          // 关键：持久 session，不是 run
  thread: true,             // 关键：结果通过 parent channel 推送回来
  label: "executor",        // 固定 label，复用 session
  task: "任务描述"
})

效果：结果直接出现在 Coordinator 的聊天里，不需要跨 session 查。

❌ 错误方式（不要用）

// 错误1：mode="run" 是 fire-and-forget，无法获取返回结果
sessions_spawn({ runtime: "acp", agentId: "claude", mode: "run", task: "..." })

// 错误2：sessions_send 跨 session 访问会被 visibility 限制
sessions_send({ sessionKey: "agent:claude:acp:...", message: "..." })
// → 报错：forbidden / Session visibility restricted

// 错误3：visibility=all 有安全风险，不推荐
// → CVE-2026-27004 相关风险

调用前必须满足的 3 个前提

1️⃣ 认证：ANTHROPIC_API_KEY 必须存在

acpx 调用 Claude adapter 时，runtime 会广告 authMethods，如果找不到凭据则报错 RUNTIME: Authentication required。

检查方式：

echo $ANTHROPIC_API_KEY

配置方式（二选一）：

方式 A：环境变量（推荐用于测试）

export ANTHROPIC_API_KEY=sk-...
# 然后调用

方式 B：acpx 配置文件（推荐用于生产） 在 ~/.acpx/config.json 添加：

{
  "authCredentials": {
    "ANTHROPIC_API_KEY": "sk-你的key"
  }
}

注意：authPolicy: "skip" 只能跳过认证检查，不能替代凭据。如果 Claude adapter 要求 API key 而找不到，会直接失败。

2️⃣ acpx 全局权限配置

~/.acpx/config.json 必须包含：

{
  "defaultPermissions": "approve-all",
  "nonInteractivePermissions": "deny",
  "authPolicy": "skip"
}

这个配置让 acpx 在自动化环境下自动批准所有操作，不弹确认框。

3️⃣ Session 可用性验证（可选但推荐）

如果之前调用过同一个 label，可能需要先验证 session 是否健康：

acpx sessions list

如果看到某个 session 显示 needs reconnect，先修复：

acpx sessions ensure \x3Csession-name>
# 或重建
acpx sessions new claude

完整调用流程（推荐写入你的 Coordinator Agent prompt）

当需要调用 Claude Code 执行任务时：

1. 前置检查：确认 ANTHROPIC_API_KEY 环境变量存在
   （如果不存在，回复："请先配置 ANTHROPIC_API_KEY 环境变量"）

2. 调用 spawn：
   sessions_spawn(
     runtime="acp",
     agentId="claude",
     mode="session",
     thread=true,
     label="executor",
     task="具体任务描述"
   )

3. 等待结果：结果会通过 thread 自动推送回当前 channel
   不要使用 sessions_send 去跨 session 查结果

4. 如果结果未返回，检查：
   - acpx sessions list → 是否有 needs reconnect
   - echo $ANTHROPIC_API_KEY → API key 是否有效

已知问题记录

🔍 unknown option '--cwd' 排查

已验证： OpenClaw acpx runtime.ts（2026.3.13）构造命令时 --cwd 是放在 agent 之前的，顺序正确：

acpx --format json --json-strict --cwd /path claude prompt --session ...

如果仍看到这个错误： 说明调用方不是 OpenClaw runtime，而是外部脚本直接调用 acpx claude --cwd /path。检查那个脚本，把 --cwd 移到 claude 之前：

✅ acpx --cwd /path claude "prompt"
❌ acpx claude --cwd /path "prompt"

错误处理对照表

Session 复用说明

使用固定 label 的好处：

• 第一次调用：创建 session
• 后续调用：自动 reconnect 到已有 session，保留上下文
• Session 有 30 天归档清理 + 500 条上限

不需要手动管理 session 生命周期，只要 label 固定，acpx 会自动处理。

关键澄清

• --dangerously-skip-permissions 是 Claude Code CLI 的参数，不是 acpx 的参数
• acpx 的正确权限控制是 defaultPermissions 配置项（见上方配置）
• mode:"session" + thread:true 是唯一可靠的结果返回方式
• 不要用 visibility=all，有安全风险

相关文件

• Skill 配置：~/.openclaw/skills/acp-harness-delegation/SKILL.md
• Harness 列表：~/.openclaw/skills/acp-harness-delegation/references/harness-list.md
• acpx 全局配置：~/.acpx/config.json
• Claude API Key 配置：~/.acpx/config.json 的 authCredentials 字段