子代理

• 并行处理研究、长任务和缓慢的工具工作，而不阻塞主运行。
• 默认保持子代理隔离（会话分离，可选沙箱）。
• 保持工具面不易被滥用：子代理默认不获得会话或消息工具。
• 支持可配置的嵌套深度，以满足编排器模式。

​

斜杠命令

/subagents list
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>

​

线程绑定控制

/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/agents
/session idle <duration|off>
/session max-age <duration|off>

​

生成行为

​

上下文模式

​

工具：sessions_spawn

• 模型： 原生子代理继承调用者的模型，除非设置 agents.defaults.subagents.model（或按代理设置 agents.entries.*.subagents.model）。ACP 运行时生成的子代理在存在配置的子代理模型时也使用该模型；否则 ACP 宿主保留其自身的默认值。显式设置的 sessions_spawn.model 优先级最高。
• 思考： 原生子代理继承调用者的思考级别，除非设置 agents.defaults.subagents.thinking（或按代理设置 agents.entries.*.subagents.thinking）。ACP 运行时生成的子代理还会对所选模型应用 agents.defaults.models["provider/model"].params.thinking。显式设置的 sessions_spawn.thinking 优先级最高。
• 运行超时： 传入 runTimeoutSeconds 可为特定的原生、ACP 或可见子代理运行设置超时。省略时，OpenClaw 使用已配置的 agents.defaults.subagents.runTimeoutSeconds；否则回退为 0（无超时）。显式设置为 0 会禁用该次运行的超时。
• 进程生命周期： 分离的 OpenClaw 子代理拥有独立的运行生命周期。在外部 CLI 后端中创建的后台任务则不同：它与父 CLI 子进程共享生命周期，并会在父进程达到 agents.defaults.timeoutSeconds 时停止。
• 任务传递： 原生子代理会在其第一条可见的 [Subagent Task] 消息中接收委派任务。子代理系统提示包含运行时规则和路由上下文，而不是任务的隐藏副本。

​

委派提示模式

• suggest（默认）：保持标准提示，引导把更大或更慢的工作交给子代理。
• prefer：提示主代理保持响应，并将任何比直接回复更复杂的工作通过 sessions_spawn 委派出去。

{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",
        maxConcurrent: 4,
      },
    },
    entries: {
      coordinator: {
        default: true,
        subagents: { delegationMode: "prefer" },
      },
    },
  },
}

​

工具参数

​

任务名称和目标定位

​

工具：sessions_yield

​

工具：subagents

​

线程绑定会话

​

支持线程的通道

​

快速流程

​

手动控制

​

配置开关

• 全局默认值： session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
• 通道覆盖和自动绑定的 spawn 键 依赖适配器。参见上方的 支持线程的通道。

​

白名单

​

发现

​

自动归档

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

​

嵌套子代理

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // 允许子代理生成子级（默认：1，范围 1-5）
        maxChildrenPerAgent: 5, // 每个代理会话的最大活动子级数（默认：5，范围 1-20）
        maxConcurrent: 8, // 全局并发通道上限（默认：8）
        runTimeoutSeconds: 900, // sessions_spawn 的默认超时（0 = 无超时）
        announceTimeoutMs: 120000, // 每次调用的网关通知超时
      },
    },
  },
}

​

深度层级

​

通知链

1. 深度 2 的工作者完成 → 通知其父级（深度 1 的编排器）。
2. 深度 1 的编排器收到通知，综合结果，完成 → 通知主代理。
3. 主代理收到通知并交付给用户。

​

按深度划分的工具策略

• 子代理在生成时会捕获请求者的有效发送者策略。即使之后 toolsBySender 发生变化，无发送者的子代理运行和已认证操作员的恢复仍会保留该快照；但当前的全局、代理、提供方、沙箱和子代理限制仍然适用。面向该子代理的新外部通道轮次会重新解析当前发送者策略。
• 角色和控制范围会在生成时写入会话元数据。这样可以防止扁平或恢复的会话键意外重新获得编排器权限。
• 深度 1（编排器，当 maxSpawnDepth >= 2 时）： 获得 sessions_spawn、subagents、sessions_list、sessions_history，以便它可以启动子级并检查其状态。其他会话/系统工具仍然被禁止。
• 深度 1（叶子，当 maxSpawnDepth == 1 时）： 没有会话工具（当前默认行为）。
• 深度 2（叶子工作者）： 没有会话工具——在深度 2 时始终禁止 sessions_spawn。不能再启动更深层的子级。

​

每个代理的启动上限

​

级联停止

• 主聊天中的 /stop 会停止所有深度 1 代理，并级联停止其深度 2 子级。

​

认证

• 子代理会话键为 agent:<agentId>:subagent:<uuid>。
• 认证存储从该代理的 agentDir 加载。
• 主代理的认证配置会作为回退合并进来；冲突时以代理配置覆盖主配置。

​

通知

• announce 步骤在子代理会话中运行（而不是请求者会话中）。
• 精确的 ANNOUNCE_SKIP 响应会抑制通知输出。
• 对于必须完成的运行，子代理精确返回 NO_REPLY 或无输出表示交付内容缺失，需要交由请求者／父级进行可见呈现或重试；这不会被视为静默交付。
• 可选、重复、已可见或其他非必需路径可以使用精确的 NO_REPLY 来有意保持静默。

• 顶层请求者会话使用带外部交付的后续 agent 调用（deliver=true）。
• 嵌套的请求者子代理会话接收内部后续注入（deliver=false），这样编排器就可以在会话内综合子级结果。
• 如果嵌套的请求者子代理会话已消失，OpenClaw 会在可用时回退到该会话的请求者。

​

通知上下文

​

统计行

• 运行时长（例如 runtime 5m12s）。
• 令牌用量（输入／输出／总计）。
• 当已配置模型定价时的估算成本（models.providers.*.models[].cost）。
• sessionKey、sessionId 和转录路径，以便主代理可通过 sessions_history 获取历史或在磁盘上检查文件。

​

为什么优先使用 sessions_history

• 即使禁用了通用日志脱敏，也会对凭据／令牌样式文本进行脱敏。
• 会截断长文本块（每块 4000 字符），并丢弃思考签名、推理回放载荷以及行内图片数据。
• 强制实施 80 KB 响应上限；过大的行会被替换为 [sessions_history omitted: message too large]。
• 当存在 nextOffset 时，使用它向后分页读取更早的转录窗口。
• sessions_history 不会从消息文本中移除 reasoning 标签、<relevant-memories> 脚手架或工具调用 XML——它返回的是接近原始转录形态的结构化内容块，只是做了脱敏和大小限制。/subagents log 使用更强的散文净化器（会移除 reasoning 标签、记忆脚手架和工具调用 XML），因为它渲染的是普通聊天行，而不是结构化块。
• 当你需要逐字节的完整转录时，原始磁盘上的转录检查是后备方案。

​

工具策略

​

通过配置覆盖

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // 拒绝优先
        deny: ["gateway", "cron"],
        // 如果设置了 allow，它会变为仅允许白名单（deny 仍然优先）
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

​

并发

• 通道名称： subagent
• 并发数： agents.defaults.subagents.maxConcurrent（默认 8）

​

活跃性与恢复

​

停止

• 在请求者聊天中发送 /stop 会中止请求者会话，并停止由其派生的任何活动子代理运行，同时级联到嵌套子级。

​

限制

• 直接通知尝试属于尽力而为，但已接受的会话队列完成交接及其所有者／任务投影会在共享 SQLite 状态数据库中跨网关重启保留。
• 子代理仍共享同一网关进程资源；请将 maxConcurrent 视为安全阀。
• sessions_spawn 始终是非阻塞的：它会立即返回 { status: "accepted", runId, childSessionKey }。
• 子代理上下文仅注入 AGENTS.md（不包含 SOUL.md、IDENTITY.md、USER.md、MEMORY.md 或 BOOTSTRAP.md）。其中的 ## Tools 部分包含特定于环境的说明。原生 Codex 子代理通过原生的 AGENTS.md 发现机制遵循相同边界，而仅限父代理使用的角色、身份和用户文件则作为本轮范围的协作指令注入，因此子代理不会复制这些文件。
• 最大嵌套深度为 5（maxSpawnDepth 范围：1-5）。对于大多数使用场景，建议深度为 2。
• maxChildrenPerAgent 限制每个会话的活动子代理数量（默认值为 5，范围：1-20）。

​

相关内容

• 会话工具和状态更改
• ACP 代理
• Agent 发送
• 后台任务
• 多代理沙箱工具。