子智能体

• 并行执行研究、长时间任务和缓慢的工具工作，而不阻塞主运行。
• 默认保持子智能体相互隔离（会话分离，可选沙箱隔离）。
• 降低工具面的误用风险：默认情况下，子智能体不会获得会话或消息工具。
• 支持可配置的嵌套深度，以适应编排器模式。

​

斜杠命令

/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 harness 会保留自己的默认模型。显式设置的 sessions_spawn.model 仍具有最高优先级。
• **思考：**除非设置 agents.defaults.subagents.thinking（或按智能体设置 agents.entries.*.subagents.thinking），否则原生子智能体会继承调用方的设置。ACP 运行时派生也会为所选模型应用 agents.defaults.models["provider/model"].params.thinking。显式设置的 sessions_spawn.thinking 仍具有最高优先级。
• **运行超时：**设置后，OpenClaw 使用 agents.defaults.subagents.runTimeoutSeconds；否则回退到 0（无超时）。sessions_spawn 不接受按调用设置的超时覆盖。
• **进程生命周期：**分离的 OpenClaw 子智能体拥有自己的运行生命周期。在外部 CLI 后端中创建的后台任务则有所不同：它会与父 CLI 子进程共享生命周期，并在父进程达到 agents.defaults.timeoutSeconds 时停止。
• **任务交付：**原生子智能体通过其第一条可见的 [Subagent Task] 消息接收委派任务。子智能体系统提示词包含运行时规则和路由上下文，不包含任务的隐藏副本。

​

委派提示模式

• suggest（默认）：保留标准提示，建议对规模较大或耗时较长的工作使用子智能体。
• prefer：要求主智能体保持响应，并通过 sessions_spawn 委派任何比直接回复更复杂的工作。

{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",
        maxConcurrent: 4,
      },
    },
    list: [
      {
        id: "coordinator",
        subagents: { delegationMode: "prefer" },
      },
    ],
  },
}

​

工具参数

​

任务名称和目标定位

​

工具：sessions_yield

​

工具：subagents

​

线程绑定会话

​

支持线程的渠道

​

快速流程

​

手动控制

​

配置开关

• 全局默认值： session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
• 渠道覆盖和生成时自动绑定键取决于适配器。请参阅上文的支持线程的渠道。

​

允许列表

​

设备发现

​

自动归档

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

​

嵌套子智能体

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

​

深度级别

​

通知链

1. 深度为 2 的工作单元完成 → 通知其父级（深度为 1 的编排器）。
2. 深度为 1 的编排器收到通知、综合结果并完成 → 通知主智能体。
3. 主智能体收到通知并将结果交付给用户。

​

按深度划分的工具策略

• 子级生成时会捕获请求方当时实际生效的发送方策略。即使 toolsBySender 随后发生变化，无发送方的子级运行和经过身份验证的操作员恢复操作仍会保留该快照；当前的全局、Agent、提供商、沙箱和子智能体限制仍然适用。如果新的外部渠道轮次以该子级为目标，则会改为重新解析当前发送方策略。
• 角色和控制范围会在生成时写入会话元数据。这样可防止扁平化或恢复后的会话键意外重新获得编排器权限。
• **深度 1（当 maxSpawnDepth >= 2 时为编排器）：**获得 sessions_spawn、subagents、sessions_list、sessions_history，以便生成子级并检查其状态。其他会话/系统工具仍被拒绝。
• **深度 1（当 maxSpawnDepth == 1 时为叶级）：**没有会话工具（当前默认行为）。
• **深度 2（叶级工作单元）：**没有会话工具——在深度 2 时始终拒绝 sessions_spawn。无法继续生成子级。

​

每个 Agent 的生成限制

​

级联停止

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

​

身份验证

• 子智能体会话键为 agent:<agentId>:subagent:<uuid>。
• 身份验证存储从该 Agent 的 agentDir 加载。
• 主智能体的身份验证配置文件作为后备合并；发生冲突时，Agent 配置文件会覆盖主智能体的配置文件。

​

通知

• 通知步骤在子智能体会话中运行（而不是在请求方会话中）。
• 如果子智能体的回复与 ANNOUNCE_SKIP 完全一致，则不会发布任何内容。
• 如果最新的助手文本是完全一致的静默令牌 NO_REPLY / no_reply，即使此前存在可见进度，也会抑制通知输出。

• 顶层请求方会话使用后续 agent 调用进行外部交付（deliver=true）。
• 嵌套的请求方子智能体会话接收内部后续注入（deliver=false），以便编排器在会话内综合子级结果。
• 如果嵌套的请求方子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求方。

​

通知上下文

​

统计行

• 运行时长（例如 runtime 5m12s）。
• Token 用量（输入/输出/总计）。
• 配置模型定价时的预估成本（models.providers.*.models[].cost）。
• sessionKey、sessionId 和记录路径，以便主智能体通过 sessions_history 获取历史记录或检查磁盘上的文件。

​

为什么首选 sessions_history

• 即使通用日志脱敏功能已禁用，也会隐去类似凭据/Token 的文本。
• 截断较长的文本块（每块 4000 个字符），并丢弃思维签名、推理重放载荷和内联图像数据。
• 强制执行 80 KB 的响应上限；超大行会替换为 [sessions_history omitted: message too large]。
• 如果存在 nextOffset，使用它向后翻页查看更早的记录窗口。
• sessions_history 不会从消息文本中去除推理标签、<relevant-memories> 脚手架或工具调用 XML——它返回接近原始记录格式的结构化内容块，只进行脱敏并限制大小。/subagents log 会应用更严格的文本清理器（去除推理标签、记忆脚手架和工具调用 XML），因为它呈现的是纯聊天行，而不是结构化块。
• 当需要完整、逐字节一致的记录时，直接检查磁盘上的原始记录是后备方案。

​

工具策略

​

通过配置覆盖

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // 拒绝规则优先
        deny: ["gateway", "cron"],
        // 如果设置了 allow，则仅允许其中所列工具（拒绝规则仍然优先）
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

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

​

并发

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

​

活跃性与恢复

​

停止

• 在请求方聊天中发送 /stop 会中止请求方会话，并停止由其生成的所有活动子智能体运行，此操作会级联至嵌套子智能体。

​

限制

• 子智能体通知是尽力而为的。如果 Gateway 网关重启，待处理的“回传通知”工作将丢失。
• 子智能体仍共享同一个 Gateway 网关进程的资源；应将 maxConcurrent 视为安全阀。
• sessions_spawn 始终是非阻塞的：它会立即返回 { status: "accepted", runId, childSessionKey }。
• 子智能体上下文仅注入 AGENTS.md 和 TOOLS.md（不注入 SOUL.md、IDENTITY.md、USER.md、MEMORY.md、HEARTBEAT.md 或 BOOTSTRAP.md）。Codex 原生子智能体遵循相同的边界：TOOLS.md 保留在继承的 Codex 线程指令中，而仅属于父级的角色设定、身份和用户文件会作为轮次范围的协作指令注入，因此子智能体不会复制它们。
• 最大嵌套深度为 5（maxSpawnDepth 范围：1-5）。对于大多数使用场景，建议使用深度 2。
• maxChildrenPerAgent 限制每个会话的活动子智能体数量（默认值为 5，范围为 1-20）。

​

相关内容

• 会话工具和状态变更
• ACP 智能体
• 智能体发送
• 后台任务
• 多 Agent 沙盒工具