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 <session-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"
错误处理对照表
| 错误信息 | 根因 | 解决方法 |
|---|---|---|
unknown option '--cwd' | OpenClaw acpx runtime bug，参数构造顺序错误 | 等待 OpenClaw 修复；当前可在 agent config 里 workaround |
agent needs reconnect | acpx session 记录在但进程断了 | acpx sessions ensure <name> 或 sessions new |
RUNTIME: Resource not found | session id 失效 | 不要复用旧 id，用新的 spawn |
RUNTIME: Authentication required | 找不到 API key | 配 ANTHROPIC_API_KEY 环境变量或 authCredentials |
forbidden / Session visibility restricted | sessions_send 跨 session 被限制 | 改用 thread=true 模式，结果自动推回 |
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字段