当前位置： 首页 > news >正文

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

news 2026/5/23 13:21:02

通过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，默认为session
    • mode: "session"需要thread: true
  • cleanup?（delete|keep，默认为keep）
  • sandbox?（inherit|require，默认为inherit；require会拒绝生成，除非目标子运行环境是沙箱化的）
  • 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。

快速流程：

  1. 使用thread: true（以及可选的mode: "session"）通过sessions_spawn生成子代理。
  2. OpenClaw 在当前活动频道中为该会话目标创建或绑定一个线程。
  3. 该线程中的回复和后续消息将路由到绑定的会话。
  4. 使用/session idle检查/更新非活动自动解绑设置，使用/session max-age控制硬性时间上限。
  5. 使用/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>子子代理（叶子工作器）从不

通知链

结果沿着链路向上传递：

  1. 深度 2 的工作器完成 → 通知其父代理（深度 1 的编排器）
  2. 深度 1 的编排器接收通知，汇总结果，然后完成 → 通知主代理
  3. 主代理接收通知并传递给用户

每一层只能看到来自其直接子代理的通知。

按深度划分的工具策略

  • 角色和控制范围在生成时被写入会话元数据。这可以防止扁平化或恢复的会话键意外地重新获得编排器权限。
  • 深度 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调用进行外部传递（deliver=true）
    • 嵌套的请求者子代理会话接收内部后续注入（deliver=false），以便编排器可以在会话内综合子代理的结果
    • 如果嵌套的请求者子代理会话已消失，OpenClaw 会回退到该会话的请求者（如果可用）
  • 在构建嵌套完成结果时，子代理完成聚合的范围限定在当前请求者运行，防止过时的先前运行的子代理输出泄漏到当前通知中。
  • 当频道适配器支持时，通知回复会保留线程/主题路由。
  • 通知上下文会被规范化为一个稳定的内部事件块：
    • 来源（subagent或cron）
    • 子代理会话键/ID
    • 通知类型 + 任务标签
    • 从运行时结果派生的状态行（success,error,timeout, 或unknown）
    • 来自通知步骤的结果内容（如果缺失则为(no output)）
    • 一个后续指令，描述何时回复与保持静默
  • 状态不是从模型输出推断的；它来自运行时结果信号。

通知有效负载在末尾包含一个统计行（即使在包装时）：

  • 运行时（例如runtime 5m12s）
  • 令牌使用量（输入/输出/总计）
  • 当配置了模型定价时（models.providers.*.models[].cost）的估计成本
  • sessionKey、sessionId和记录文件路径（以便主代理可以通过sessions_history获取历史记录或检查磁盘上的文件）
  • 内部元数据仅用于编排；面向用户的回复应以正常的助手口吻重写。

工具策略（子代理工具）

默认情况下，子代理获得除会话工具和系统工具外的所有工具：

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_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）。
  • 最大嵌套深度为 5（maxSpawnDepth范围：1–5）。对于大多数用例，建议使用深度 2。
  • maxChildrenPerAgent限制了每个会话的活动子代理数（默认值：5，范围：1–20）。
http://www.jsqmd.com/news/855373/

相关文章：

  • JiYuTrainer：在极域电子教室中重获电脑控制权的终极方案
  • 顶伯 + 微软 TTS：专业术语发音零误差
  • 【PostgreSQL】时间取最大值，转换为init，如果为空则为0
  • 实战避坑：基于STM32或全志平台调试MIPI-DSI屏的常见问题与排查指南
  • 从下载到上线：用CobaltStrike 4.8汉化版快速搭建你的第一个渗透测试实验室
  • 除了综合，DC Shell还能这么用：手把手教你用它做设计Review和Debug
  • 从 C++ 闭包底层上看：你的[]里到底发生了什么？
  • 别再只盯着Encoder模式了！STM32F4通用IO口+外部中断搞定EC11旋转编码器（附代码）
  • #SAP-ABAP：数据类型与数据对象（8篇） 第六篇：操作实践篇——数据对象的常用操作与异常处理方案
  • 08-实战：RuoYi-Vue项目的自动化发布
  • YOLOv5到v8，哪个更适合你的表情识别项目？我用同一份数据集做了次全面对比评测
  • STM32G431时钟树配置避坑指南：从CubeMX图形化到代码实战，手把手教你调出80MHz主频
  • 2026年兰州景观亮化靠谱厂家TOP5：兰州建筑亮化、兰州建筑泛光照明、兰州文旅亮化、兰州旅游景区亮化、兰州景观泛光照明选择指南 - 优质品牌商家
  • Fluent瞬态计算踩坑记录：时间统计采样设置里的3个关键细节与避坑指南
  • 基于STM32F105系列使用CAN总线实现双机通信代码
  • eNSP实验避坑指南：华为路由器IP地址配完却Ping不通？这5个细节检查了吗？
  • 2026年Q2广州宠物犬舍猫舍评测：四家连锁机构深度对比 - 优质品牌商家
  • 告别理论！用Python可视化带你彻底搞懂电机插补算法（逐点比较法）
  • 从零搭建企业级网络准入：用Agile Controller-Campus + 华为交换机实战802.1X认证
  • RK3588工业一体机：异构计算、AI推理与Linux系统构建实战
  • 2026年工业门应用白皮书：兰州工业提升门/兰州工业滑升门/兰州工业翻板门/兰州工业车间门/兰州工业钢木门/兰州工业钢质门/选择指南 - 优质品牌商家
  • 2026嵌入式晾衣架实测评测：落地晾衣架、语音晾衣架、遥控晾衣机、阳台晾衣架、隐藏式晾衣架、伸缩晾衣架、全自动晾衣架选择指南 - 优质品牌商家
  • SAP-ABAP:数据类型与数据对象（8篇） 第七篇：进阶优化篇——基于类型与对象特征的性能优化技巧
  • 从Matlab仿真到上板验证：手把手完成Xilinx DDS多项数据生成的全流程
  • HarmonyOS 图片缩放没想象中简单——detailEnhance 四档质量深度解析
  • 告别理论推导！用Python+NumPy手撸一个卡尔曼滤波器（附AR序列预测完整代码）
  • 从‘Hello World’到自主导航：一个ROS1节点的完整生命周期与调试指令全记录
  • 别再乱调JVM堆大小了！Elasticsearch内存配置的5个实战避坑点
  • LabVIEW事件驱动状态机：从原理到实战的混合编程架构解析
  • 2026四川全屋定制打印机实力厂家排行及地址汇总：高温彩釉打印机/700度高温烧结打印机/uv光油墨水/排行一览 - 优质品牌商家