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 参数¶
userstring (path)- 该人员的
requester_profile.id;当多个人驱动了本轮对话时必填。 taskstring (path) required- 发送给 ACP 会话的初始 prompt。
runtime"acp" (path) required- 对于 ACP 会话必须为
"acp"。 agentIdstring (path)- ACP 目标 harness ID 或已配置的 ACP 代理别名。若已设置,则回退到
acp.defaultAgent。原始 harness 会在发起请求的 OpenClaw 代理下创建子会话;配置的别名拥有这些子会话。无论哪种情况,harness 都保持 ACP 运行时身份。 对于跨代理别名,线程绑定和内联交付使用所有者已绑定的频道账户。原始 harness 保留发起请求的代理的活动入站账户。 threadboolean (path) default:false- 在支持的情况下请求线程绑定流程。
mode"run" | "session" (path) default:run"run"是一次性的;"session"是持久的。如果设置了thread: true且省略mode,OpenClaw 可能按运行时路径默认采用持久行为。mode: "session"需要thread: true。cwdstring (path)- 请求的运行时工作目录(由后端/运行时策略验证)。如果省略,则在配置后 ACP spawn 会继承 OpenClaw 所有者的工作区;缺失的继承路径回退到后端默认值,而真实的访问错误会被返回。
labelstring (path)- 用于会话/横幅文本的面向操作者的标签。
resumeSessionIdstring (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 错误)。
modelstring (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 使用自己的默认值。 thinkingstring (path)- 显式的思考/推理强度。对于 Codex ACP,
minimal映射为低强度,low/medium/high/xhigh直接映射,off则省略推理强度的启动覆盖。显式值优先于model中的推理后缀,包括off。省略时,ACP spawn 会使用现有的子代理思考默认值、已配置目标代理的thinkingDefault,以及所选模型的 per-modelparams.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