跳转至

线程绑定的子代理会话

线程绑定会话

当某个渠道启用了线程绑定时,生成的子代理可以获得自己的新线程。该线程中的后续用户消息会继续路由到同一个子代理会话,而你生成它所在的对话仍保留在你的代理中。

支持线程的渠道

使用 thread: true 的 sessions_spawn 始终会打开一个新的子线程;它永远不会将当前对话交给工作代理。可以打开子线程的内置渠道包括:Discord 和 Matrix。在会改为绑定当前对话的渠道上(例如 Telegram、iMessage、Feishu 和 LINE),thread: true 会被拒绝;请使用 mode: "run" 生成,结果会通告回对话。使用每个渠道的 threadBindings 配置键来启用功能、设置超时以及配置 spawnSessions。

旧版本在当前对话上创建的工作代理绑定会被忽略:那里的消息会再次路由到你的代理,过期的绑定会通过其正常空闲超时失效。若要有意将对话交给 ACP 会话,请使用 /acp spawn --bind here。

快速流程

1. 生成

使用 thread: true 的 sessions_spawn(可选 mode: "session")。

2. 绑定

OpenClaw 会在活动渠道中打开一个新的子线程,并将其绑定到该会话。

3. 路由后续消息

该线程中的回复和后续消息会路由到已绑定的会话。

4. 检查超时

使用 /session idle 检查/更新不活动过期时间,使用 /session max-age 控制硬性上限。

5. 分离

使用 /session unbind 分离而不关闭代理会话。

手动控制

命令 效果
/session unbind 移除当前对话绑定,而不关闭代理会话
/agents 列出活动运行和绑定状态(binding:<id>、unbound 或 bindings unavailable)
/session idle 检查/更新当前绑定的不活动过期时间
/session max-age 检查/更新当前绑定的最大存活时间

配置开关

  • 全局默认值: session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
  • 渠道覆盖和生成自动绑定键 因适配器而异。参见上文 支持线程的渠道。

参见 配置参考 和 斜杠命令 了解当前适配器详情。

允许列表

agents.entries.*.subagents.allowAgents string[] (路径)
可通过显式 agentId 指定的已配置代理 ID 列表(["*"] 允许任意已配置目标)。默认值:仅请求方代理。如果你设置了列表,但仍希望请求方使用 agentId 生成自身,请将请求方 ID 包含在列表中。
agents.defaults.subagents.allowAgents string[] (路径)
当请求方代理未设置自己的 subagents.allowAgents 时使用的默认已配置目标代理允许列表。
agents.defaults.subagents.requireAgentId boolean (路径) 默认值:false
阻止省略 agentId 的 sessions_spawn 调用(强制显式选择代理配置)。按代理覆盖:agents.entries.*.subagents.requireAgentId。
agents.defaults.subagents.announceTimeoutMs number (路径) 默认值:120000
网关 agent 通告交接尝试的超时时间。一旦交接被接受,等待父会话的回合不会消耗此预算。执行开始后,请求方的正常 运行时超时和取消控制 生效;通告计时器不会重启。值为正整数毫秒,并被限制在平台安全计时器最大值。队列等待、请求方执行和瞬时重试可能使总交付时间长于一个配置的超时时间。

如果请求方会话被沙箱化,sessions_spawn 会拒绝会在非沙箱中运行的目标。

发现

使用 agents_list 查看当前允许用于 sessions_spawn 的代理 ID。响应包含每个列出代理的有效模型和嵌入式运行时元数据,以便调用方区分 OpenClaw、Codex app-server 以及其他已配置的原生运行时。

allowAgents 条目必须指向 agents.entries.* 中已配置的代理 ID。["*"] 表示任意已配置目标代理以及请求方。如果某个代理配置被删除,但其 ID 仍保留在 allowAgents 中,sessions_spawn 会拒绝该 ID,且 agents_list 会省略它。运行 openclaw doctor --fix 清理过期的允许列表条目,或者当目标应保持可生成并继承默认值时,添加一个最小的 agents.entries.* 条目。

自动归档

  • 子代理会话会在 agents.defaults.subagents.archiveAfterMinutes(默认 60)后自动归档。
  • 归档使用 sessions.delete,并将转录重命名为 *.deleted.<timestamp>(同一文件夹)。
  • cleanup: "delete" 会在通告后立即归档(仍通过重命名保留转录)。
  • 自动归档是尽力而为的;如果网关重启,待处理的计时器会丢失。
  • 已配置的运行超时不会自动归档;它们只会停止运行。会话会保留到自动归档。
  • 自动归档同样适用于每一层子代理深度。
  • 浏览器清理与归档清理是分开的:跟踪的浏览器标签页/进程会在运行结束时尽力关闭,即使转录/会话记录被保留。

如果较新的运行接管了同一会话,较旧的运行会停止为清理而占用标签页。已为某个标签页接受的清理仍会针对该标签页捕获的所有权结算;它不会移除后续注册。

subagent_ended 插件钩子是尽力而为的。钩子执行或插件运行时加载失败会被记录日志,并且不会中止子代理清理。

定期 context-engine 清理会在发起该清理的请求结束后继续执行。 尽力而为的 context-engine 清理失败会记录脱敏后的错误、清理原因 以及已掩码的子会话密钥。

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