跳转至

ACP 代理会话

启动 ACP 会话

启动 ACP 会话有两种方式:

使用 `runtime: "acp"` 从代理回合或工具调用启动 ACP 会话。

```json
{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}
```

Note

runtime 默认为 subagent,因此对于 ACP 会话请显式设置 runtime: "acp"。如果省略 agentId,OpenClaw 在配置了 acp.defaultAgent 时会使用它。mode: "session" 需要 thread: true 以保持持久的绑定会话。

在聊天中使用 /acp spawn 进行显式的操作者控制。

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here

关键标志:

  • --mode persistent|oneshot
  • --bind here|off
  • --thread auto|here|off
  • --cwd <absolute-path>
  • --label <name>

参见斜杠命令。

sessions_spawn 参数

user string (path)
该人员的 requester_profile.id;当多个人驱动了本轮对话时必填。
task string (path) required
发送给 ACP 会话的初始 prompt。
runtime "acp" (path) required
对于 ACP 会话必须为 "acp"。
agentId string (path)
ACP 目标 harness ID 或已配置的 ACP 代理别名。若已设置,则回退到 acp.defaultAgent。原始 harness 会在发起请求的 OpenClaw 代理下创建子会话;配置的别名拥有这些子会话。无论哪种情况,harness 都保持 ACP 运行时身份。 对于跨代理别名,线程绑定和内联交付使用所有者已绑定的频道账户。原始 harness 保留发起请求的代理的活动入站账户。
thread boolean (path) default: false
在支持的情况下请求线程绑定流程。
mode "run" | "session" (path) default: run
"run" 是一次性的;"session" 是持久的。如果设置了 thread: true 且省略 mode,OpenClaw 可能按运行时路径默认采用持久行为。mode: "session" 需要 thread: true。
cwd string (path)
请求的运行时工作目录(由后端/运行时策略验证)。如果省略,则在配置后 ACP spawn 会继承 OpenClaw 所有者的工作区;缺失的继承路径回退到后端默认值,而真实的访问错误会被返回。
label string (path)
用于会话/横幅文本的面向操作者的标签。
resumeSessionId string (path)
恢复现有 ACP 会话,而不是创建新会话。代理通过 session/load 重放其对话历史。需要 runtime: "acp"。该 ID 必须是为所选后端和 harness 记录的,并且属于请求者(请求者本身,或它生成或作为父级的会话)。未知 ID 会被拒绝,且不会枚举代理的会话。历史上由 harness 拥有的记录在相同检查下仍符合条件;生成操作不会移动或重写其历史。OpenClaw 在初始化恢复的运行时之前会再次检查所有权。
streamTo "parent" (path)
"parent" 会将 ACP 运行的初始进度摘要以系统事件的形式流式传回给请求者会话。OpenClaw 会在子代理的 SQLite 状态中记录完整的中继历史,并随子会话一并移除。默认情况下,父级进度流会显示助手评论和 ACP 状态进度,除非 streaming.progress.commentary=false。Discord 父级进度需要显式设置 streaming.mode: "progress";未设置时,Discord 流式输出保持静默。状态进度仍然遵循 acp.stream.tagVisibility,因此 plan 等标签除非显式启用,否则保持隐藏。

ACP sessions_spawn 运行使用 agents.defaults.subagents.runTimeoutSeconds 作为其默认子轮次限制。该工具不接受每次调用的超时覆盖(runTimeoutSeconds/timeoutSeconds 会被拒绝,并返回 config-the-default 错误)。

model string (path)
ACP 子会话的显式模型覆盖。Codex ACP spawn 操作会先将 openai/gpt-5.4 之类的 OpenAI 引用规范化为 Codex ACP 启动配置,再执行 session/new;openai/gpt-5.4/high 这类斜杠形式还会设置 Codex ACP 的推理强度。省略时,sessions_spawn({ runtime: "acp" }) 会依次使用目标代理的 subagents.model、agents.defaults.subagents.model,再使用目标代理显式配置的 model.primary。如果均未配置,则让 ACP harness 使用自己的默认模型。原生子代理 spawn 不会继承 ACP 代理的 harness 主模型;它们会改用原生子代理设置或原生默认值。其他 harness 必须声明支持 ACP 模型控制,才能进行显式选择。如果没有这些控制,显式选择会失败;继承的默认值可能会被省略,以便 harness 使用自己的默认值。
thinking string (path)
显式的思考/推理强度。对于 Codex ACP,minimal 映射为低强度,low/medium/high/xhigh 直接映射,off 则省略推理强度的启动覆盖。显式值优先于 model 中的推理后缀,包括 off。省略时,ACP spawn 会使用现有的子代理思考默认值、已配置目标代理的 thinkingDefault,以及所选模型的 per-model params.thinking。目标代理的 agents.entries.<agent>.models["provider/model"] 设置会覆盖共享的 agents.defaults.models["provider/model"] 设置。

Spawn 绑定与线程模式

模式 行为
模式 行为
here 就地绑定当前活动会话;如果没有活动会话则失败。
off 不创建当前会话绑定。
说明:

- `--bind here` 是“让此频道或聊天由 Codex 提供支持”的最简单操作路径。
- `--bind here` 不会创建子线程。
- `--bind here` 仅在暴露当前会话绑定支持的频道上可用。
- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中组合使用。
模式 行为
auto 在活动线程中:绑定该线程。在线程外:在受支持时创建/绑定子线程。
here 要求当前活动线程;如果不在线程中则失败。
off 无绑定。会话以未绑定状态启动。

说明:

  • 在非线程绑定界面上,默认行为实际上为 off。
  • 线程绑定的 spawn 需要频道策略支持:
  • Discord/Telegram: session.threadBindings.spawnSessions=true
  • 当你希望固定当前会话而不创建子线程时,请使用 --bind here。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw