子智能体

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 并行处理“研究 / 长任务 / 慢工具”工作，而不阻塞主运行。
• 默认保持子智能体隔离（会话隔离 + 可选沙箱隔离）。
• 让工具表面难以被误用：子智能体默认不会获得会话工具。
• 支持可配置的嵌套深度，以适配编排器模式。

​

斜杠命令

/subagents list
/subagents kill <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>
/subagents steer <id|#> <message>
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

​

线程绑定控制

/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.list[].subagents.model）；显式的 sessions_spawn.model 仍然优先。
• **Thinking：**继承调用方，除非你设置了 agents.defaults.subagents.thinking（或每个智能体的 agents.list[].subagents.thinking）；显式的 sessions_spawn.thinking 仍然优先。
• **运行超时：**如果省略 sessions_spawn.runTimeoutSeconds，OpenClaw 会在已设置时使用 agents.defaults.subagents.runTimeoutSeconds；否则回退到 0（无超时）。

​

委派提示模式

• 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 网关重启，待处理定时器会丢失。
• runTimeoutSeconds 不会自动归档；它只会停止运行。会话会保留到自动归档。
• 自动归档同样适用于深度 1 和深度 2 的会话。
• 浏览器清理独立于归档清理：运行结束时，会尽力关闭被跟踪的浏览器标签页/进程，即使转录记录/会话记录被保留。

​

嵌套子智能体

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
        announceTimeoutMs: 120000, // per-call gateway announce timeout
      },
    },
  },
}

​

深度级别

​

公告链

1. 深度 2 工作项完成 → 向其父项（深度 1 编排器）公告。
2. 深度 1 编排器收到公告，合成结果并完成 → 向主智能体公告。
3. 主智能体收到公告并投递给用户。

​

按深度划分的工具策略

• 角色和控制范围会在生成时写入会话元数据。这可以避免扁平化或恢复后的会话键意外重新获得编排器权限。
• **深度 1（编排器，当 maxSpawnDepth >= 2 时）：**获得 sessions_spawn、subagents、sessions_list、sessions_history，以便管理它的子会话。其他会话/系统工具仍被拒绝。
• **深度 1（叶节点，当 maxSpawnDepth == 1 时）：**没有会话工具（当前默认行为）。
• **深度 2（叶工作器）：**没有会话工具，sessions_spawn 在深度 2 始终被拒绝。不能再生成更多子会话。

​

每个智能体的生成限制

​

级联停止

• 主聊天中的 /stop 会停止所有深度 1 智能体，并级联停止它们的深度 2 子会话。
• /subagents kill <id> 会停止特定子智能体，并级联停止它的子会话。
• /subagents kill all 会停止请求者的所有子智能体，并执行级联停止。

​

身份验证

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

​

公告

• 公告步骤在子智能体会话内部运行（不是请求者会话）。
• 如果子智能体精确回复 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

• 助手回忆会先被规范化：移除思考标签；移除 <relevant-memories> / <relevant_memories> 脚手架；移除纯文本工具调用 XML 载荷块（<tool_call>、<function_call>、<tool_calls>、<function_calls>），包括从未干净闭合的截断载荷；移除降级的工具调用/结果脚手架和历史上下文标记；移除泄漏的模型控制令牌（<|assistant|>、其他 ASCII <|...|>、全角 <｜...｜>）；移除畸形的 MiniMax 工具调用 XML。
• 类似凭据/token 的文本会被打码。
• 长块可以被截断。
• 极大的历史可以丢弃较旧行，或用 [sessions_history omitted: message too large] 替换过大的行。
• 当你需要完整的逐字节转录时，原始磁盘转录检查是后备方案。

​

工具策略

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

​

通过配置覆盖

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

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

​

并发

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

​

存活性与恢复

​

停止

• 在请求者聊天中发送 /stop 会中止请求者会话，并停止从它生成的所有活跃子智能体运行，同时级联到嵌套子会话。
• /subagents kill <id> 会停止特定子智能体，并级联停止它的子会话。

​

限制

• 子智能体公告是尽力而为的。如果 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）。
• 最大嵌套深度是 5（maxSpawnDepth 范围：1–5）。大多数用例推荐深度 2。
• maxChildrenPerAgent 限制每个会话的活跃子会话数量（默认 5，范围 1–20）。

​

相关

• ACP Agents
• Agent send
• 后台任务
• 多 Agent 沙盒工具