子代理

• 在不阻塞主运行的情况下，并行化“调研 / 长任务 / 慢工具”工作。
• 默认保持子代理隔离（会话分离 + 可选沙箱）。
• 尽量让工具面不易被滥用：默认情况下，子代理不获得会话工具。
• 支持可配置的嵌套深度，以适配编排器模式。

​

斜杠命令

/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.list[].subagents.model）。ACP 运行生成也会在存在时使用相同配置的子代理模型；否则 ACP 宿主保持自己的默认值。显式的 sessions_spawn.model 仍然优先。
• 思考： 原生子代理会继承调用方，除非你设置 agents.defaults.subagents.thinking（或按代理覆盖 agents.list[].subagents.thinking）。ACP 运行生成也会对所选模型应用 agents.defaults.models["provider/model"].params.thinking。显式的 sessions_spawn.thinking 仍然优先。
• 运行超时： 当设置了 agents.defaults.subagents.runTimeoutSeconds 时，OpenClaw 会使用它；否则回退到 0（无超时）。sessions_spawn 不接受按调用覆盖的超时设置。
• 任务投递： 原生子代理会在其首条可见的 [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。
• 通道覆盖和自动绑定的 spawn 键 依赖适配器。参见上方的 支持线程的通道。

​

白名单

​

发现

​

自动归档

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

​

嵌套子代理

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

​

深度层级

​

通知链

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

​

按深度划分的工具策略

• 角色和控制范围会在生成会话时写入会话元数据。这样可以防止扁平或恢复后的会话键意外重新获得编排器权限。
• 深度 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，则不会发布任何内容。
• 如果最新的 assistant 文本恰好是静默标记 NO_REPLY / no_reply，即使之前存在可见进度，也会抑制 announce 输出。

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

​

通知上下文

​

统计行

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

​

为什么优先使用 sessions_history

• assistant 记忆会先被规范化：移除 thinking 标签；移除 <relevant-memories> / <relevant_memories> 脚手架；移除纯文本工具调用 XML 载荷块（<tool_call>、<function_call>、<tool_calls>、<function_calls>），包括未能完整闭合的截断载荷；移除降级的工具调用/结果脚手架和历史上下文标记；移除泄露的模型控制标记（<|assistant|>、其他 ASCII <|...|>、全角 <｜...｜>）；移除格式损坏的 MiniMax 工具调用 XML。
• 会对凭证/令牌样式文本进行脱敏。
• 长块内容可能会被截断。
• 超大历史记录可能会丢弃较旧行，或将过大的单行替换为 [sessions_history omitted: message too large]。
• 当你需要按字节逐字节查看完整转录时，可回退到原始磁盘转录检查。

​

工具策略

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

​

通过配置覆盖

{
  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 会中止请求者会话，并停止由其派生的任何活动子代理运行，同时级联到嵌套子级。

​

限制

• 子代理公告是尽力而为的。如果网关重启，待处理的“回传公告”工作会丢失。
• 子代理仍然共享同一个网关进程资源；请将 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 agents
• Agent send
• 后台任务
• 多代理沙箱工具