跳转至

嵌套子代理与身份验证

嵌套子代理

默认情况下,子代理可以通过深度 5 进行递归委派。每会话执行限制、子代理准入限制、继承的工具策略、沙箱继承以及目标代理允许列表仍然适用。设置较低的深度可以更快地创建叶子工作器。

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // stop nesting after depth 2 (default: 5, range 1-5)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5, range 1-20)
        maxConcurrent: 8, // concurrent child runs per spawning session (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn (0 = no timeout)
        announceTimeoutMs: 120000, // gateway announce timeout, excluding accepted queue waits
      },
    },
  },
}

深度级别

深度 会话键形状 默认角色 可以派生?
0 agent:<id>:main 主代理 总是
1 agent:<id>:subagent:<uuid> 编排器 可以,除非 maxSpawnDepth: 1
2-4 带谱系的持久化扁平子代理键 编排器 可以,默认情况下
5 带谱系的持久化扁平子代理键 叶子 不可以,处于默认边界

通告链

结果逐级向上流动:

  1. 后代完成并向其直接父级通告。
  2. 该父级汇总其子级的结果,然后完成并向上一级通告。
  3. 主代理接收最终通告并将其传递给用户。

每一级只能看到来自其直接子级的通告。

Note

操作指南: 启动子工作一次,然后等待完成事件,而不是围绕 sessions_list、sessions_history、/subagents list 或 exec sleep 命令构建轮询循环。sessions_list 和 /subagents list 会保持子会话关系聚焦于活动工作——活动子级保持附加状态,已结束的子级会在一个较短的时间窗口内保持可见,而过期的仅存储子级链接会在其新鲜度窗口过后被忽略。这可以防止旧的 spawnedBy / parentSessionKey 元数据在重启后复活幽灵子级。如果在发送最终答案之后才收到子级完成事件,请查看该事件并继续任何未完成的工作。避免重复发送已交付的更新。内部编排仍然需要有意义的结果;静默令牌无法了结子任务。

按深度划分的工具策略

  • 子代理在被派生时会捕获请求者的有效发送者策略。即使 toolsBySender 之后发生变化,无发送者的子代理运行和经过身份验证的操作员恢复操作仍会保留该快照;当前的全局、代理、提供商、沙箱和子代理限制仍然适用。针对子代理的新外部渠道轮次则会重新解析当前发送者策略。
  • 角色和控制范围会在派生时写入会话元数据以用于溯源。当前深度策略具有权威性,因此当配置的上限发生变化时,现有会话会获得或失去递归编排工具。
  • 编排器(低于 maxSpawnDepth): 获取 sessions_spawn、subagents、sessions_list、sessions_history,以便派生子代理并检查其状态。其他会话/系统工具仍然被拒绝。
  • 叶子(位于 maxSpawnDepth): 没有递归编排工具。

每代理派生限制

每个代理会话(在任何深度)一次最多可以有 maxChildrenPerAgent(默认 5)个活动子代理。这可以防止单个编排器出现失控的扇出。另外,maxConcurrent 限制该直接派生会话的并发执行子运行数量。每个嵌套编排器都有自己的执行预算;其子代理不共享根会话的槽位。

重置对话

完整的原地对话重置会取消与该会话关联的未完成原生子代理,包括已让出的子代理以及完成请求者与其控制器不同的子代理。聊天 /reset 和 sessions.reset 使用相同的清理所有者。如果子代理取消不完整,重置会在清除对话之前报告失败;请检查剩余任务并重试。子代理记录和不相关的会话会被保留。

级联停止

显式取消编排器会级联到其后代树。主聊天中的 /stop 适用于该请求者的子代理树。有关范围和不完整取消行为,请参阅 停止。

身份验证

子代理身份验证由代理 ID 解析,而不是由会话类型解析:

  • 子代理会话键为 agent:<agentId>:subagent:<uuid>。
  • 本地身份验证覆盖层从该代理的 agentDir 加载。
  • 共享身份验证配置文件作为后备合并进来;冲突时代理配置文件覆盖共享配置文件。

合并是追加式的,因此共享配置文件始终可用作后备。没有任何设置可以将代理的身份验证与共享配置文件隔离开来。

内存受众继承

OpenClaw sessions_spawn(包括 ACP 运行时)和实时语音咨询会记录直接父级键(spawnedBy)、确切的父级会话 ID(spawnedBySessionId)、父级生命周期修订号(parentSessionLifecycleRevision)以及派生调用的受信任所有者状态(spawnedBySenderIsOwner)。这些是主机拥有的事实,而不是工具参数或 sessions.patch 字段。所有者标志永远不会从子代理的合成启动权限中推断出来;语音咨询仅从调用方的入口身份验证中获取该标志。缺失或错误的所有者状态不会授予所有者访问权限。

对于内存访问,OpenClaw 会根据当前父级实例和生命周期验证每一个父级跳转,包括同 ID 重置。然后,它将主机签发的根受众提供给内存提供商和插件工具。提供商必须使用该准备好的受众,并且不得遍历会话谱系或从会话查找中推断内存权限。

子会话重置会保留其已记录的父级授权,因此新解析的受众仍可从同一根继承。任何已记录父级的重置或删除都会使已捕获的受众失效,因此下一个受保护的提供者或工具操作将未通过其受众时效性检查。该子会话的后续轮次不会获得记忆受众。使用原生记忆提供者时,Gateway 日志会警告子会话的血缘已过期,并且必须重新生成或从当前会话重新创建;重置子会话会保留过期的血缘。缺少完整血缘标记的旧版子会话不会获得继承的记忆受众:其轮次在没有私有记忆或对话记忆的情况下运行,并且 Gateway 日志会警告该会话早于记忆血缘回执,并且必须从其父级重新生成。父级缺少生命周期修订的子会话必须在父级下一次重置后重新生成,该重置会建立当前生命周期修订。

此契约涵盖由 OpenClaw 创建的子会话。原生运行时子线程还需要其运行时的工具桥接提供实时授权调用;仅血缘元数据不会添加该桥接。

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