OpenClaw从入门到应用——工具（Tools）：子代理（Sub-agents）

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》子代理是从现有代理运行中衍生出的后台代理运行。它们在独立的会话中运行agent:agentId:subagent:uuid并在完成后将结果通知回请求者的聊天频道。斜杠命令使用/subagents来检查或控制当前会话的子代理运行/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/subagents info显示运行元数据状态、时间戳、会话 ID、记录文件路径、清理策略。生成行为/subagents spawn作为一个用户命令启动后台子代理而不是一个内部中继。当运行完成时它会向请求者的聊天频道发送一条最终的完成更新。spawn命令是非阻塞的它会立即返回一个运行 ID。完成后子代理会向请求者的聊天频道通知一条摘要/结果消息。对于手动生成消息传递是可靠的OpenClaw 首先尝试使用稳定的幂等键进行直接的agent消息传递。如果直接传递失败则回退到队列路由。如果队列路由仍然不可用则在最终放弃前会以短指数退避的方式重试通知。到请求者会话的完成交接是运行时生成的内部上下文非用户编写的文本包括结果assistant回复文本如果 assistant 回复为空则为最新的toolResult状态成功完成/失败/超时/未知简洁的运行时/令牌统计信息一个传递指令指示请求者代理以正常的助手口吻重写结果不直接转发原始内部元数据--model和--thinking会覆盖该次特定运行的默认设置。使用info/log在完成检查细节和输出。/subagents spawn是单次运行模式mode: run。对于需要持久绑定线程的会话请使用thread: true和mode: session的sessions_spawn。对于 ACP 框架会话如 Codex, Claude Code, Gemini CLI请使用runtime: acp的sessions_spawn并参阅 ACP 代理译者注此链接目标地址已按规则修改为 https://blog.csdn.net/hy592070616/article/details/81707766。主要目标并行执行“研究/长任务/慢速工具”的工作避免阻塞主运行。默认情况下保持子代理的隔离性会话分离 可选沙箱。保持工具接口难以被误用子代理默认不获得会话工具。支持可配置的嵌套深度以实现编排器模式。成本注意每个子代理都有其自身的上下文和令牌使用量。对于繁重或重复性的任务为子代理设置一个成本较低的模型并让主代理使用更高质量的模型。你可以通过agents.defaults.subagents.model或基于每个代理的覆盖配置进行设置。工具使用sessions_spawn启动一个子代理运行deliver: false全局通道subagent然后执行一个通知步骤并将通知回复发布到请求者的聊天频道默认模型继承调用者的模型除非你设置了agents.defaults.subagents.model或基于代理的设置agents.list[].subagents.model显式设置的sessions_spawn.model仍然优先。默认思考级别继承调用者的思考级别除非你设置了agents.defaults.subagents.thinking或基于代理的设置agents.list[].subagents.thinking显式设置的sessions_spawn.thinking仍然优先。默认运行超时如果省略sessions_spawn.runTimeoutSeconds当设置了agents.defaults.subagents.runTimeoutSeconds时 OpenClaw 会使用该值否则回退到0无超时。工具参数task必需label?可选agentId?可选如果允许在另一个代理 ID 下生成model?可选覆盖子代理模型无效值将被跳过子代理将使用默认模型运行并在工具结果中显示警告thinking?可选覆盖子代理运行的思考级别runTimeoutSeconds?默认为设置时的agents.defaults.subagents.runTimeoutSeconds否则为0设置后子代理运行将在 N 秒后被中止thread?默认为false当为true时为此子代理会话请求频道线程绑定mode?run|session默认值为run如果thread: true且省略mode默认为sessionmode: session需要thread: truecleanup?delete|keep默认为keepsandbox?inherit|require默认为inheritrequire会拒绝生成除非目标子运行环境是沙箱化的sessions_spawn不接受频道传递参数target,channel,to,threadId,replyTo,transport。对于消息传递请使用生成运行中的message/sessions_send。绑定线程的会话当为频道启用了线程绑定时子代理可以保持绑定到一个线程这样该线程中的后续用户消息会继续路由到同一个子代理会话。支持线程的频道Discord目前唯一支持的频道支持持久的线程绑定子代理会话使用thread: true的sessions_spawn、手动线程控制/focus,/unfocus,/agents,/session idle,/session max-age以及适配器键channels.discord.threadBindings.enabled、channels.discord.threadBindings.idleHours、channels.discord.threadBindings.maxAgeHours和channels.discord.threadBindings.spawnSubagentSessions。快速流程使用thread: true以及可选的mode: session通过sessions_spawn生成子代理。OpenClaw 在当前活动频道中为该会话目标创建或绑定一个线程。该线程中的回复和后续消息将路由到绑定的会话。使用/session idle检查/更新非活动自动解绑设置使用/session max-age控制硬性时间上限。使用/unfocus手动解绑。手动控制/focus target将当前线程或创建一个绑定到子代理/会话目标。/unfocus移除当前绑定线程的绑定。/agents列出活动运行和绑定状态thread:id或unbound。/session idle和/session max-age仅适用于已聚焦的绑定线程。配置开关全局默认值session.threadBindings.enabled,session.threadBindings.idleHours,session.threadBindings.maxAgeHours频道覆盖和生成自动绑定键是适配器特定的。请参阅上面的支持线程的频道。请参阅配置参考译者注此链接目标地址已按规则修改为 https://blog.csdn.net/hy592070616/article/details/81707766和斜杠命令译者注此链接目标地址已按规则修改为 https://blog.csdn.net/hy592070616/article/details/81707766了解当前适配器的详细信息。允许列表agents.list[].subagents.allowAgents可以通过agentId指定的代理 ID 列表使用[*]允许任何代理。默认值仅允许请求者代理。沙箱继承保护如果请求者会话是沙箱化的sessions_spawn会拒绝在非沙箱环境下运行的目标。发现使用agents_list查看当前允许用于sessions_spawn的代理 ID。自动归档子代理会话会在agents.defaults.subagents.archiveAfterMinutes默认值60分钟后自动归档。归档使用sessions.delete并将记录文件重命名为*.deleted.timestamp在同一文件夹中。cleanup: delete在通知后立即归档仍然通过重命名保留记录文件。自动归档是尽力而为的如果网关重启待处理的计时器会丢失。runTimeoutSeconds不会触发自动归档它只会停止运行。会话会一直存在直到自动归档。自动归档同样适用于深度为 1 和深度为 2 的会话。嵌套子代理默认情况下子代理不能生成它们自己的子代理maxSpawnDepth: 1。你可以通过设置maxSpawnDepth: 2来启用一层嵌套这允许编排器模式主代理 → 编排器子代理 → 工作器子子代理。如何启用{ agents: { defaults: { subagents: { maxSpawnDepth: 2, // 允许子代理生成子代理默认值1 maxChildrenPerAgent: 5, // 每个代理会话的最大活动子代理数默认值5 maxConcurrent: 8, // 全局并发通道上限默认值8 runTimeoutSeconds: 900, // 当省略 sessions_spawn.runTimeoutSeconds 时的默认超时时间0 表示无超时 }, }, }, }深度级别深度会话键格式角色能否生成子代理0agent:id:main主代理总是可以1agent:id:subagent:uuid子代理当深度 2 允许时作为编排器仅当maxSpawnDepth 2时2agent:id:subagent:uuid:subagent:uuid子子代理叶子工作器从不通知链结果沿着链路向上传递深度 2 的工作器完成 → 通知其父代理深度 1 的编排器深度 1 的编排器接收通知汇总结果然后完成 → 通知主代理主代理接收通知并传递给用户每一层只能看到来自其直接子代理的通知。按深度划分的工具策略角色和控制范围在生成时被写入会话元数据。这可以防止扁平化或恢复的会话键意外地重新获得编排器权限。深度 1编排器当maxSpawnDepth 2时获得sessions_spawn、subagents、sessions_list、sessions_history工具以便它可以管理其子代理。其他会话/系统工具仍被拒绝。深度 1叶子节点当maxSpawnDepth 1时没有会话工具当前的默认行为。深度 2叶子工作器没有会话工具 ——sessions_spawn在深度 2 总是被拒绝。不能生成更多子代理。基于代理的生成限制每个代理会话在任何深度最多可以同时拥有maxChildrenPerAgent默认值5个活动子代理。这可以防止单个编排器产生失控的扇出。级联停止停止一个深度为 1 的编排器会自动停止其所有深度为 2 的子代理在主聊天中执行/stop会停止所有深度为 1 的代理并级联停止其深度为 2 的子代理。/subagents kill id会停止特定的子代理并级联停止其子代理。/subagents kill all会停止请求者的所有子代理并进行级联停止。认证子代理的认证由代理 ID解析而不是会话类型子代理会话键是agent:agentId:subagent:uuid。认证存储从该代理的agentDir加载。主代理的认证配置文件会作为后备合并进来代理配置文件在冲突时会覆盖主配置文件。注意合并是累加的因此主配置文件始终可作为后备。目前尚不支持每个代理完全隔离的认证。通知子代理通过一个通知步骤进行报告通知步骤在子代理会话而非请求者会话内部运行。如果子代理回复的内容恰好是ANNOUNCE_SKIP则不会发布任何消息。否则传递方式取决于请求者的深度顶级请求者会话使用后续的agent调用进行外部传递delivertrue嵌套的请求者子代理会话接收内部后续注入deliverfalse以便编排器可以在会话内综合子代理的结果如果嵌套的请求者子代理会话已消失OpenClaw 会回退到该会话的请求者如果可用在构建嵌套完成结果时子代理完成聚合的范围限定在当前请求者运行防止过时的先前运行的子代理输出泄漏到当前通知中。当频道适配器支持时通知回复会保留线程/主题路由。通知上下文会被规范化为一个稳定的内部事件块来源subagent或cron子代理会话键/ID通知类型 任务标签从运行时结果派生的状态行success,error,timeout, 或unknown来自通知步骤的结果内容如果缺失则为(no output)一个后续指令描述何时回复与保持静默状态不是从模型输出推断的它来自运行时结果信号。通知有效负载在末尾包含一个统计行即使在包装时运行时例如runtime 5m12s令牌使用量输入/输出/总计当配置了模型定价时models.providers.*.models[].cost的估计成本sessionKey、sessionId和记录文件路径以便主代理可以通过sessions_history获取历史记录或检查磁盘上的文件内部元数据仅用于编排面向用户的回复应以正常的助手口吻重写。工具策略子代理工具默认情况下子代理获得除会话工具和系统工具外的所有工具sessions_listsessions_historysessions_sendsessions_spawn当maxSpawnDepth 2时深度为 1 的编排器子代理会额外获得sessions_spawn、subagents、sessions_list和sessions_history以便它们可以管理其子代理。通过配置覆盖{ agents: { defaults: { subagents: { maxConcurrent: 1, }, }, }, tools: { subagents: { tools: { // deny 优先 deny: [gateway, cron], // 如果设置了 allow则变为仅允许模式deny 仍然优先 // allow: [read, exec, process] }, }, }, }并发子代理使用专用的进程内队列通道通道名称subagent并发数agents.defaults.subagents.maxConcurrent默认为8停止在请求者聊天中发送/stop会中止请求者会话并停止从中生成的所有活动子代理运行同时级联到嵌套的子代理。/subagents kill id会停止特定的子代理并级联停止其子代理。限制子代理通知是尽力而为的。如果网关重启待处理的“通知回传”工作会丢失。子代理仍然共享相同的网关进程资源将maxConcurrent视为一个安全阀。sessions_spawn始终是非阻塞的它会立即返回{ status: accepted, runId, childSessionKey }。子代理上下文仅注入AGENTS.md和TOOLS.md没有SOUL.md、IDENTITY.md、USER.md、HEARTBEAT.md或BOOTSTRAP.md。最大嵌套深度为 5maxSpawnDepth范围1–5。对于大多数用例建议使用深度 2。maxChildrenPerAgent限制了每个会话的活动子代理数默认值5范围1–20。