[OpenClaw 文档]工具--代理协作

本文档汇总了 OpenClaw 官方文档站 工具 > 代理协作 子模块下的全部 3 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 智能体发送

原文：https://docs.openclaw.ai/zh-CN/tools/agent-send

openclaw agent 会从命令行运行单个智能体轮次，无需传入聊天消息。可用于脚本化工作流、测试和程序化投递。

快速开始

bash
openclaw agent --message "What is the weather today?"

这会通过 Gateway 网关发送消息并打印回复。

```bash
# Target a specific agent
openclaw agent --agent ops --message "Summarize logs"

# Target a phone number (derives session key)
openclaw agent --to +15555550123 --message "Status update"

# Reuse an existing session
openclaw agent --session-id abc123 --message "Continue the task"
```

```bash
# Deliver to WhatsApp (default channel)
openclaw agent --to +15555550123 --message "Report ready" --deliver

# Deliver to Slack
openclaw agent --agent ops --message "Generate report" \
  --deliver --reply-channel slack --reply-to "#reports"
```

标志

行为

• 默认情况下，CLI 会通过 Gateway 网关。添加 --local 可强制使用当前机器上的嵌入式运行时。
• 如果 Gateway 网关不可达，CLI 会回退到本地嵌入式运行。
• 会话选择：--to 派生会话键（群组/渠道目标会保留隔离；直接聊天会合并到 main）。
• 思考和详细输出标志会持久化到会话存储。
• 输出：默认是纯文本，或使用 --json 输出结构化载荷 + 元数据。
• 使用 --json --deliver 时，JSON 会包含已发送、已抑制、部分发送和发送失败的投递状态。参见
  JSON 投递状态。

示例

# Simple turn with JSON output
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json

# Turn with thinking level
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium

# Deliver to a different channel than the session
openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"

相关内容

完整的 openclaw agent 标志和选项参考。


后台子智能体生成。


会话键的工作方式，以及 --to、--agent 和 --session-id 如何解析它们。


在智能体会话中使用的原生命令目录。

📄 子智能体

原文：https://docs.openclaw.ai/zh-CN/tools/subagents

子智能体是从现有智能体运行中生成的后台智能体运行。
它们在自己的会话（agent:<agentId>:subagent:<uuid>）中运行，
完成后会将结果通知回请求者的聊天
渠道。每个子智能体运行都会作为一个
后台任务进行跟踪。

主要目标：

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

成本说明：默认情况下，每个子智能体都有自己的上下文和 token 使用量。
对于繁重或重复的任务，请为子智能体设置更便宜的模型，
并让主智能体使用质量更高的模型。可通过
agents.defaults.subagents.model 或每个智能体的覆盖项进行配置。当子智能体
确实需要请求者当前的转录记录时，智能体可以在那次生成时请求
context: "fork"。绑定到线程的子智能体会话默认使用
context: "fork"，因为它们会将当前对话分支到一个
后续线程中。

斜杠命令

使用 /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>]

使用顶层 /steer <message> 来操控当前请求者会话的活动运行。当目标是子运行时，使用 /subagents steer <id|#> <message>。

/subagents info 会显示运行元数据（状态、时间戳、会话 ID、
转录记录路径、清理）。使用 sessions_history 获取有界且经过安全过滤的回忆视图；
当你需要原始完整转录记录时，请检查磁盘上的转录记录路径。

线程绑定控制

这些命令适用于支持持久线程绑定的渠道。
请参阅下方的支持线程的渠道。

/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/agents
/session idle <duration|off>
/session max-age <duration|off>

生成行为

/subagents spawn 会以用户命令（而不是内部中继）的形式启动后台子智能体，
并在运行完成时向请求者聊天发送一次最终完成更新。

- 生成命令是非阻塞的；它会立即返回一个运行 ID。
- 完成时，子智能体会向请求者聊天渠道通知一条摘要/结果消息。
- 需要子结果的智能体轮次，应在生成所需工作后调用 sessions_yield。这会结束当前轮次，并让完成事件作为下一条模型可见消息到达。
- 完成是基于推送的。一旦生成，不要在循环中轮询 /subagents list、sessions_list 或 sessions_history，只为等待其完成；仅在调试或干预需要时按需检查状态。
- 子输出是供请求者智能体综合的报告/证据。它不是用户撰写的指令文本，不能覆盖系统、开发者或用户策略。
- 完成时，OpenClaw 会尽力关闭由该子智能体会话打开并受跟踪的浏览器标签页/进程，然后继续通知清理流程。

- OpenClaw 会通过带有稳定幂等键的 agent 轮次，将完成结果交还给请求者会话。
- 如果请求者运行仍处于活动状态，OpenClaw 会先尝试唤醒/操控该运行，而不是启动第二条可见回复路径。
- 如果请求者智能体的完成交接失败或没有产生可见输出，OpenClaw 会将交付视为失败，并回退到队列路由/重试。它不会将子结果直接原样发送到外部聊天。
- 如果无法使用直接交接，则回退到队列路由。
- 如果队列路由仍然不可用，通知会以短暂的指数退避重试，然后才最终放弃。
- 完成交付会保留解析后的请求者路由：当可用时，绑定到线程或绑定到对话的完成路由优先；如果完成来源只提供渠道，OpenClaw 会从请求者会话解析后的路由（lastChannel / lastTo / lastAccountId）填充缺失的目标/账号，以便直接交付仍然可用。

给请求者会话的完成交接是运行时生成的
内部上下文（不是用户撰写的文本），并包含：

- `Result` — 最新可见的 `assistant` 回复文本，否则为经过净化的最新工具/toolResult 文本。终止且失败的运行不会复用捕获到的回复文本。
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。
- 紧凑的运行时/token 统计信息。
- 一条交付指令，要求请求者智能体以正常 assistant 口吻重写（而不是转发原始内部元数据）。

- --model 和 --thinking 会覆盖该特定运行的默认值。
- 使用 info/log 在完成后检查详情和输出。
- /subagents spawn 是一次性模式（mode: "run"）。对于持久的线程绑定会话，请使用带有 thread: true 和 mode: "session" 的 sessions_spawn。
- 对于 ACP harness 会话（Claude Code、Gemini CLI、OpenCode，或显式 Codex ACP/acpx），当工具声明该运行时时，请使用带有 runtime: "acp" 的 sessions_spawn。调试完成或智能体到智能体循环时，请参阅 ACP 交付模型。启用 codex 插件时，除非用户明确要求 ACP/acpx，否则 Codex 聊天/线程控制应优先使用 /codex ...，而不是 ACP。
- OpenClaw 会隐藏 runtime: "acp"，直到 ACP 已启用、请求者未被沙箱隔离，并且已加载如 acpx 这样的后端插件。runtime: "acp" 需要一个外部 ACP harness ID，或一个带有 runtime.type="acp" 的 agents.list[] 条目；对于来自 agents_list 的普通 OpenClaw 配置智能体，请使用默认子智能体运行时。

上下文模式

原生子智能体默认以隔离方式启动，除非调用方明确要求 fork
当前转录记录。

请谨慎使用 fork。它用于上下文敏感的委派，
不能替代清晰的任务提示词。

工具：sessions_spawn

在全局 subagent 通道上以 deliver: false 启动一个子智能体运行，
然后运行一个通知步骤，并将通知回复发布到请求者
聊天渠道。

可用性取决于调用方的有效工具策略。coding 和
full 配置文件默认公开 sessions_spawn。messaging 配置文件
不会公开；请添加 tools.alsoAllow: ["sessions_spawn", "sessions_yield",
"subagents"]，或对应该委派工作的智能体使用 tools.profile: "coding"。
渠道/群组、提供商、沙箱，以及每个智能体的允许/拒绝策略，
仍然可以在配置文件阶段之后移除该工具。请在同一
会话中使用 /tools 确认有效工具列表。

默认值：

• 模型：继承调用方，除非你设置了 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（无超时）。

委派提示模式

agents.defaults.subagents.delegationMode 只控制提示词指导；它不会改变工具策略，也不会强制委派。

• suggest（默认）：保留标准提示，建议对更大或更慢的工作使用子智能体。
• prefer：告诉主智能体保持响应，并通过 sessions_spawn 委派任何比直接回复更复杂的事项。

每个智能体的覆盖项使用 agents.list[].subagents.delegationMode。

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

工具参数

子智能体的任务描述。


可选的稳定句柄，用于后续 subagents 定向。必须匹配 [a-z][a-z0-9_]{0,63}，且不能是 last 或 all 等保留目标。当协调器可能需要在生成多个子项后引导、终止或识别特定子项时，优先使用它。


可选的人类可读标签。


在 subagents.allowAgents 允许时，在另一个智能体 ID 下生成。


acp 仅用于外部 ACP harness（claude、droid、gemini、opencode，或明确请求的 Codex ACP/acpx），以及 runtime.type 为 acp 的 agents.list[] 条目。


仅 ACP。在 runtime: "acp" 时恢复现有 ACP harness 会话；对原生子智能体生成会被忽略。


仅 ACP。在 runtime: "acp" 时将 ACP 运行输出流式传输到父会话；原生子智能体生成时省略。


覆盖子智能体模型。无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中给出警告。


覆盖子智能体运行的思考级别。


设置后默认为 agents.defaults.subagents.runTimeoutSeconds，否则为 0。设置后，子智能体运行会在 N 秒后中止。


当为 true 时，为此子智能体会话请求频道线程绑定。


如果 thread: true 且省略 mode，默认值会变为 session。mode: "session" 需要 thread: true。


"delete" 会在公告后立即归档（仍会通过重命名保留转录记录）。


require 会拒绝生成，除非目标子运行时处于沙箱隔离状态。


fork 会将请求者的当前转录记录分支到子会话中。仅原生子智能体。线程绑定生成默认为 fork；非线程生成默认为 isolated。

sessions_spawn 不接受频道投递参数（target、
channel、to、threadId、replyTo、transport）。如需投递，请从生成的运行中使用
message/sessions_send。

任务名称和定向

taskName 是用于编排的面向模型句柄，不是会话键。
当协调器可能需要稍后引导或终止该子项时，可将其用于稳定的子项名称，例如 review_subagents、
linux_validation 或 docs_update。

目标解析接受精确的 taskName 匹配和无歧义的前缀。
匹配范围限定在与编号 /subagents 目标相同的活动/近期目标窗口内，因此过时的已完成子项不会让复用的句柄变得有歧义。如果两个活动或近期子项共享同一个
taskName，该目标就有歧义；请改用列表索引、会话键或运行 ID。

保留目标 last 和 all 不是有效的 taskName 值，
因为它们已经具有控制含义。

工具：sessions_yield

结束当前模型轮次并等待运行时事件，主要是子智能体完成事件，以便它们作为下一条消息到达。当请求者必须等到这些完成事件到达后才能生成最终回答时，在生成必需的子项工作后使用它。

sessions_yield 是等待原语。不要仅为检测子项完成而用对 subagents、sessions_list、sessions_history 的轮询循环、shell
sleep 或进程轮询来替代它。

只有在会话的有效工具列表包含 sessions_yield 时才使用它。某些极简或自定义工具配置可能会暴露 sessions_spawn 和
subagents，但不暴露 sessions_yield；在这种情况下，不要为了等待完成而发明轮询循环。

当存在活动子项时，OpenClaw 会在正常轮次中注入一个紧凑的运行时生成
Active Subagents 提示块，让请求者无需轮询即可看到当前子会话、运行 ID、状态、标签、任务和
taskName 别名。该块中的任务和标签字段会作为数据而非指令被引用，因为它们可能来自用户/模型提供的生成参数。

工具：subagents

列出、引导或终止请求者会话拥有的已生成子智能体运行。
它的作用域限定为当前请求者；子项只能查看/控制自己控制的子项。

将 subagents 用于按需状态、调试、引导或终止。
使用 sessions_yield 等待完成事件。

线程绑定会话

当某个频道启用线程绑定时，子智能体可以保持绑定到某个线程，使该线程中的后续用户消息继续路由到同一个子智能体会话。

支持线程的频道

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.spawnSessions。

快速流程

带 thread: true 的 sessions_spawn（也可选择带 mode: "session"）。


OpenClaw 会在活动频道中创建线程，或将线程绑定到该会话目标。


该线程中的回复和后续消息会路由到已绑定会话。


使用 /session idle 检查/更新非活动自动取消聚焦，并使用
/session max-age 控制硬上限。


使用 /unfocus 手动分离。

手动控制

配置开关

• 全局默认值： session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
• 频道覆盖和生成自动绑定键是适配器特定的。见上方支持线程的频道。

有关当前适配器详情，请参阅配置参考和
斜杠命令。

允许列表

可通过显式 agentId 定向的智能体 ID 列表（["*"] 允许任意智能体）。默认值：仅请求者智能体。如果你设置了列表，并且仍希望请求者使用 agentId 生成自身，请在列表中包含请求者 ID。


当请求者智能体未设置自己的 subagents.allowAgents 时使用的默认目标智能体允许列表。


阻止省略 agentId 的 sessions_spawn 调用（强制显式选择配置文件）。按智能体覆盖：agents.list[].subagents.requireAgentId。


Gateway 网关 agent 公告投递尝试的单次调用超时。值为正整数毫秒，并会钳制到平台安全的定时器最大值。瞬时重试可能会让总公告等待时间长于一个配置的超时。

如果请求者会话处于沙箱隔离状态，sessions_spawn 会拒绝会以非沙箱隔离方式运行的目标。

设备发现

使用 agents_list 查看当前允许用于 sessions_spawn 的智能体 ID。响应包含每个列出智能体的有效模型和嵌入式运行时元数据，以便调用方区分 PI、Codex 应用服务器以及其他已配置的原生运行时。

自动归档

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

嵌套子智能体

默认情况下，子智能体不能生成自己的子智能体
（maxSpawnDepth: 1）。设置 maxSpawnDepth: 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. 主智能体收到公告并投递给用户。

每一级只能看到来自其直接子项的公告。

操作指导：只启动一次子任务，并等待完成事件，而不是围绕 sessions_list、sessions_history、/subagents list 或 exec sleep 命令构建轮询循环。sessions_list 和 /subagents list 让子会话关系专注于实时工作：实时子会话保持附加，已结束的子会话会在短暂的最近窗口内保持可见，过时的仅存储子链接会在其新鲜度窗口后被忽略。这可以防止旧的 spawnedBy / parentSessionKey 元数据在重启后重新唤起幽灵子会话。如果子会话完成事件在你已经发送最终答案后到达，正确的后续响应是精确的静默令牌 NO_REPLY / no_reply。

按深度划分的工具策略

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

投递取决于请求者深度：

• 顶层请求者会话使用带外部投递的后续 agent 调用（deliver=true）。
• 嵌套请求者子智能体会话会收到内部后续注入（deliver=false），这样编排器可以在会话内合成子结果。
• 如果嵌套请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者。

对于顶层请求者会话，完成模式的直接投递会先解析任何已绑定的对话/线程路由和钩子覆盖，然后从请求者会话存储的路由中填补缺失的渠道目标字段。这样即使完成来源只标识渠道，完成结果也会保持在正确的聊天/主题上。

构建嵌套完成发现时，子完成聚合会限定在当前请求者运行范围内，防止旧的先前运行子输出泄漏到当前公告中。当渠道适配器上可用时，公告回复会保留线程/主题路由。

公告上下文

公告上下文会规范化为稳定的内部事件块：

终止失败的运行会报告失败 Status，而不会重放捕获的回复文本。超时时，如果子会话只执行到工具调用，公告可以将该历史折叠为简短的部分进度摘要，而不是重放原始工具输出。

统计行

公告载荷末尾会包含统计行（即使被包装）：

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

内部元数据仅用于编排；面向用户的回复应改写为正常的助手语气。

为什么优先使用 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] 替换过大的行。
• 当你需要完整的逐字节转录时，原始磁盘转录检查是后备方案。

工具策略

子智能体首先使用与父智能体或目标智能体相同的配置文件和工具策略管线。之后，OpenClaw 会应用子智能体限制层。

在没有限制性 tools.profile 的情况下，子智能体会获得除会话工具和系统工具之外的所有工具：

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

sessions_history 在这里仍然是有界且经过清理的回忆视图，并非原始转录转储。

当 maxSpawnDepth >= 2 时，深度 1 编排器子智能体还会收到 sessions_spawn、subagents、sessions_list 和 sessions_history，以便管理它们的子会话。

通过配置覆盖

{
  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.subagents.tools.allow 是最终的仅允许过滤器。它可以收窄已经解析出的工具集，但不能加回被 tools.profile 移除的工具。例如，tools.profile: "coding" 包含 web_search/web_fetch，但不包含 browser 工具。要让 coding-profile 子智能体使用浏览器自动化，请在配置文件阶段添加 browser：

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

当只有一个智能体应获得浏览器自动化时，使用逐智能体的 agents.list[].tools.alsoAllow: ["browser"]。

并发

子智能体使用专用的进程内队列通道：

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

存活性与恢复

OpenClaw 不会将缺少 endedAt 视为子智能体仍然存活的永久证明。超过陈旧运行窗口的未结束运行，在 /subagents list、Status 摘要、后代完成门控和逐会话并发检查中不再计为活跃/待处理。

Gateway 网关重启后，陈旧的未结束恢复运行会被剪除，除非其子会话被标记为 abortedLastRun: true。这些因重启中止的子会话仍可通过子智能体孤儿恢复流程恢复，该流程会在清除中止标记前发送一条合成恢复消息。

自动重启恢复按每个子会话设有边界。如果同一个子智能体子会话在快速重新卡住窗口内反复被接受进行孤儿恢复，OpenClaw 会在该会话上持久化一个恢复墓碑，并在后续重启时停止自动恢复它。运行 openclaw tasks maintenance --apply 来协调任务记录，或运行 openclaw doctor --fix 来清除带墓碑会话上的陈旧中止恢复标志。

如果子智能体生成因 Gateway 网关 PAIRING_REQUIRED / scope-upgrade 失败，请先检查 RPC 调用方，再编辑配对状态。内部 sessions_spawn 协调应通过直连 loopback 共享 token/密码身份验证，以 client.id: "gateway-client" 和 client.mode: "backend" 连接；该路径不依赖 CLI 的已配对设备范围基线。远程调用方、显式 deviceIdentity、显式设备 token 路径以及 browser/node 客户端仍需要正常设备批准才能进行范围升级。

停止

• 在请求者聊天中发送 /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 沙盒工具

📄 多 Agent 沙盒和工具

原文：https://docs.openclaw.ai/zh-CN/tools/multi-agent-sandbox-tools

Each agent in a multi-agent setup can override the global sandbox and tool policy. This page covers per-agent configuration, precedence rules, and examples.

后端和模式 — 完整的沙箱参考。


调试“为什么这被阻止了？”


面向受信任发送者的 elevated exec。

凭证按 agent 划定范围：每个 agent 都有自己的 agentDir 凭证存储，位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json。切勿在多个 agent 之间复用 agentDir。当 agent 没有本地配置文件时，可以读取默认/主 agent 的凭证配置文件，但 OAuth 刷新令牌不会克隆到次级 agent 存储中。如果你手动复制凭证，只复制可移植的静态 api_key 或 token 配置文件。

配置示例

json
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"name": "Personal Assistant",
"workspace": "~/.openclaw/workspace",
"sandbox": { "mode": "off" }
},
{
"id": "family",
"name": "Family Bot",
"workspace": "~/.openclaw/workspace-family",
"sandbox": {
"mode": "all",
"scope": "agent"
},
"tools": {
"allow": ["read", "message"],
"deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
"message": {
"crossContext": {
"allowWithinProvider": false,
"allowAcrossProviders": false
}
}
}
}
]
},
"bindings": [
{
"agentId": "family",
"match": {
"provider": "whatsapp",
"accountId": "*",
"peer": {
"kind": "group",
"id": "120363424282127706@g.us"
}
}
}
]
}

**结果：**

- `main` agent：在主机上运行，拥有完整工具访问权限。
- `family` agent：在 Docker 中运行（每个 agent 一个容器），仅允许 `read` 和当前对话消息发送。

json
{
"agents": {
"list": [
{
"id": "personal",
"workspace": "~/.openclaw/workspace-personal",
"sandbox": { "mode": "off" }
},
{
"id": "work",
"workspace": "~/.openclaw/workspace-work",
"sandbox": {
"mode": "all",
"scope": "shared",
"workspaceRoot": "/tmp/work-sandboxes"
},
"tools": {
"allow": ["read", "write", "apply_patch", "exec"],
"deny": ["browser", "gateway", "discord"]
}
}
]
}
}


json
{
"tools": { "profile": "coding" },
"agents": {
"list": [
{
"id": "support",
"tools": { "profile": "messaging", "allow": ["slack"] }
}
]
}
}

**结果：**

- 默认 agent 获得编码工具。
- `support` agent 仅支持消息传递（+ Slack 工具）。

json
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "session"
}
},
"list": [
{
"id": "main",
"workspace": "~/.openclaw/workspace",
"sandbox": {
"mode": "off"
}
},
{
"id": "public",
"workspace": "~/.openclaw/workspace-public",
"sandbox": {
"mode": "all",
"scope": "agent"
},
"tools": {
"allow": ["read"],
"deny": ["exec", "write", "edit", "apply_patch"]
}
}
]
}
}

配置优先级

当同时存在全局配置（agents.defaults.*）和 agent 专属配置（agents.list[].*）时：

沙箱配置

agent 专属设置会覆盖全局设置：

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.list[].sandbox.{docker,browser,prune}.* 会覆盖该 agent 的 agents.defaults.sandbox.{docker,browser,prune}.*（当沙箱范围解析为 "shared" 时会被忽略）。

工具限制

过滤顺序如下：

tools.profile 或 agents.list[].tools.profile。


tools.byProvider[provider].profile 或 agents.list[].tools.byProvider[provider].profile。


tools.allow / tools.deny。


tools.byProvider[provider].allow/deny。


agents.list[].tools.allow/deny。


agents.list[].tools.byProvider[provider].allow/deny。


tools.sandbox.tools 或 agents.list[].tools.sandbox.tools。


tools.subagents.tools，如适用。

- 每一层都可以进一步限制工具，但不能把前面层级已拒绝的工具重新授予回来。
- 如果设置了 agents.list[].tools.sandbox.tools，它会替换该 agent 的 tools.sandbox.tools。
- 如果设置了 agents.list[].tools.profile，它会覆盖该 agent 的 tools.profile。
- 提供商工具键既可以接受 provider（例如 google-antigravity），也可以接受 provider/model（例如 openai/gpt-5.4）。

如果该链路中的任何显式允许列表让本次运行没有任何可调用工具，OpenClaw 会在把 prompt 提交给模型之前停止。这是有意设计的：配置了缺失工具的 agent，例如 agents.list[].tools.allow: ["query_db"]，应当在注册 query_db 的插件启用之前明确失败，而不是作为纯文本 agent 继续运行。

工具策略支持 group:* 简写，它们会展开为多个工具。完整列表见 工具组。

每个 agent 的 elevated 覆盖项（agents.list[].tools.elevated）可以进一步限制特定 agent 的 elevated exec。详情见 Elevated mode。

从单 Agent 迁移

json
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace",
"sandbox": {
"mode": "non-main"
}
}
},
"tools": {
"sandbox": {
"tools": {
"allow": ["read", "write", "apply_patch", "exec"],
"deny": []
}
}
}
}


json
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"workspace": "~/.openclaw/workspace",
"sandbox": { "mode": "off" }
}
]
}
}

旧版 agent.* 配置由 openclaw doctor 迁移；今后优先使用 agents.defaults + agents.list。

工具限制示例

json
{
"tools": {
"allow": ["read"],
"deny": ["exec", "write", "edit", "apply_patch", "process"]
}
}


json
{
"tools": {
"allow": ["read", "exec", "process"],
"deny": ["write", "edit", "apply_patch", "browser", "gateway"]
}
}

<Warning>
此策略会禁用 OpenClaw 文件系统工具，但 `exec` 仍然是一个 shell，并且可以在所选主机或沙箱文件系统允许的任何位置写入文件。对于只读 Agent，请拒绝 `exec` 和 `process`，或将 shell 访问与沙箱文件系统控制结合使用，例如 `agents.defaults.sandbox.workspaceAccess: "ro"` 或 `"none"`。
</Warning>

json
{
"tools": {
"sessions": { "visibility": "tree" },
"allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
"deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
}
}

此配置文件中的 `sessions_history` 仍会返回一个有界且已清理的回忆视图，而不是原始转录转储。助手回忆会在编辑/截断之前剥离思考标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 和被截断的工具调用块）、降级的工具调用脚手架、泄漏的 ASCII/全角模型控制令牌，以及格式错误的 MiniMax 工具调用 XML。

常见陷阱："non-main"

agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey（默认值为 "main"），而不是 Agent ID。群组/渠道会话始终会获得自己的键，因此它们会被视为非主会话并进行沙箱隔离。如果你希望某个 Agent 永不沙箱隔离，请设置 agents.list[].sandbox.mode: "off"。

测试

配置多 Agent 沙箱和工具后：

bash
openclaw agents list --bindings


bash
docker ps --filter "name=openclaw-sbx-"


- 发送一条需要受限工具的消息。
- 验证 Agent 无法使用被拒绝的工具。

bash
tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

故障排除

- 检查是否存在覆盖它的全局 agents.defaults.sandbox.mode。
- Agent 专用配置优先级更高，因此请设置 agents.list[].sandbox.mode: "all"。

- 检查工具过滤顺序：全局 → Agent → 沙箱 → 子 Agent。
- 每一层只能进一步限制，不能重新授予权限。
- 使用日志验证：[tools] filtering tools for agent:${agentId}。

- 在 Agent 专用沙箱配置中设置 scope: "agent"。
- 默认值是 "session"，即每个会话创建一个容器。

相关

• 提权模式
• 多 Agent 路由
• 沙箱配置
• 沙箱与工具策略与提权 — 调试“为什么这被阻止了？”
• 沙箱隔离 — 完整沙箱参考（模式、范围、后端、镜像）
• 会话管理