线程绑定的子智能体会话

线程绑定会话¶

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

支持线程的渠道¶

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

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

快速流程¶

1. 生成

sessions_spawn with thread: true（可选 mode: "session"）。

2. 绑定

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

3. 路由后续消息

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

4. 检查超时

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

5. 分离

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

手动控制¶

配置开关¶

• 全局默认值： 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 插件钩子是尽力而为的。钩子执行或插件运行时加载失败会被记录日志，并且不会中止子代理清理。