跳转至

配置 — 跨代理、会话和子代理工具

会话和子代理工具的作用范围:哪些代理可以相互调用、它们可以针对哪些会话,以及派生子代理时应用的默认设置。

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      allow: ["home", "work"],
    },
  },
}

跨代理访问默认开启。enabled(默认 true)控制跨代理会话工具调用:向另一个代理发送 sessions_send,以及在默认 tools.sessions.visibility: "all" 下跨代理的 sessions_list、sessions_history、sessions_search 和状态读取。设置 enabled: false 可关闭跨代理访问。同代理访问从不参考此策略。请求方拥有的原生子代理和 ACP 子会话是唯一例外:在 tree 或 all 可见性下,它们在参考此策略之前仍可跨代理边界保持可达,即使 enabled: false 也是如此。

allow 列出可以参与跨代理调用的代理 id 或 * 模式。请求代理和目标代理都必须匹配某个条目。精确 id 区分大小写;通配符模式不区分大小写。

Note

省略或空的 allow 视为未设置:由于代理间访问默认开启,每个代理都可以访问其他每个代理。若要限制跨代理访问,请列出所有参与代理,包括请求方和目标方,如上例所示。仅包含空白条目的列表会拒绝所有跨代理调用。删除代理(openclaw agents delete)会将其 id 从 allow 中移除;如果这使列表为空,策略会回退为允许所有,因此删除代理后请重新检查 allow。

按代理的仅发送访问

使用 agents.entries.<agentId>.tools.agentToAgent.send 允许一个代理向选定代理发送请求,而不扩大会话可见性。它不会移除现有读取访问:当你希望仅发送访问时,请保持 tools.sessions.visibility 低于 all。例如,让 specialist 向 ops 请求帮助,而不授予直接的跨代理历史访问:

{
  tools: {
    agentToAgent: { enabled: true, allow: ["specialist", "ops"] },
    sessions: { visibility: "agent" },
  },
  agents: {
    ownership: "explicit",
    entries: {
      specialist: {
        tools: { agentToAgent: { send: ["ops"] } },
      },
      ops: {
        tools: { agentToAgent: { send: [] } },
      },
    },
  },
}

specialist 可以使用 sessions_send 访问 ops 并收到该已发送回合的回复,即使 ops 具有 send: []。ops 不能发起普通跨代理发送。两个代理都不会获得对另一个代理历史的直接访问。调用方的有效工具策略仍必须启用 sessions_send 工具。specialist 可以直接寻址已配置的代理;它不需要先列出 ops 代理的会话。使用以下内容调用 sessions_send:

{ "agentId": "ops", "message": "Please check the service status." }

send 是一个可选字符串数组:

  • 省略 send: 保留全局 tools.agentToAgent 策略以及发送时的 tools.sessions.visibility 检查。
  • send: []: 拒绝该代理发起的普通跨代理发送,即使在 visibility: "all" 下也是如此。与全局 allow 不同,空的 send 不是允许所有。
  • 目标 ID 或 * 模式: 只有匹配的目标代理才能接收来自该请求方的普通跨代理发送。匹配项即使在 self、tree 或 agent 可见性下也允许 sessions_send;它不会扩大其他工具。对任意目标代理使用 ["*"]。删除代理会将其精确 ID 从这些列表中移除;清空后的列表仍保持 [](拒绝),通配符规则仍然保留。
  • 全局策略仍然适用: enabled: false 或排除请求方或目标方的 allow 列表会拒绝发送。这是出站策略,而不是按目标接收策略。
  • 现有边界仍然保留: 同代理发送仍遵守可见性。请求方拥有的原生/ACP 子会话访问不变。隐身限制和沙箱派生会话限制仍然适用,包括对沙箱子代理;send 无法超出该限制范围。
  • 投递前变更: Gateway 会在异步准备之后、接受目标输入之前立即重新检查当前发送策略。撤回目标会阻止尚未接受的发送;它不会撤回已接受的输入或其应回复。
  • 回复,而非历史: 回复属于已授权的发送回合。send 不授予列表、历史、搜索、状态或会话控制访问。watch: true 还要求正常状态可见性;仅发送访问无法订阅否则隐藏的会话状态。

Warning

仅发送访问是请求目标代理执行操作的权限。它不会阻止特权目标在回复中披露数据或执行不受信任的请求。请保持目标工具和指令适合传入请求;使用独立的 Gateway 以实现强隔离。参见 安全信任模型。

tools.sessions

控制哪些会话可以被会话工具(sessions_list、sessions_history、sessions_search、sessions_send、session_status)针对。

默认:all(Gateway 上的每个会话,包括其他代理和其他用户的转录)。跨代理访问由 tools.agentToAgent 控制,默认开启。使用 agent、tree 或 self 缩小可见性。

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "all",
    },
  },
}
可见性范围
  • self:仅当前会话键。
  • tree:当前会话 + 由当前会话派生的会话(子代理)。当调用方是规范主会话时,它包括所有同代理会话,用于列表、历史、搜索、发送和状态。
  • agent:属于当前代理 id 的任何会话(如果在同一代理 id 下运行按发送者划分的会话,则可能包括其他用户)。
  • all:任何会话。跨代理目标由 tools.agentToAgent 控制,默认开启。
  • self 没有主会话可见性例外。隐身模式的拒绝仍然绝对。将可见性缩小为 agent、tree 或 self 会阻止普通跨代理访问,除非按代理的 tools.agentToAgent.send 规则允许仅发送例外。tree 还允许拥有的原生/ACP 子会话跨代理边界。agent 不包括该子会话例外,因此如果你的工作流依赖它,请保留显式 tree。
  • 沙箱限制:当当前会话处于沙箱中且 agents.defaults.sandbox.sessionToolsVisibility="spawned"(默认)时,即使调用方是主会话或 tools.sessions.visibility="all",访问仍限制在派生会话。
  • 当不是 all 时,sessions_list 包含一个紧凑的 visibility 字段,描述有效模式,并警告某些会话可能因在当前范围之外而被省略。

环境组监视器仍会将活动通知加入队列,并告知主会话事件发生的位置。它们不授予访问权限。默认的 all 作用域已涵盖跨代理的会话,包括与其他用户的对话。按对等方(per-peer)设置的 session.dmScope 用于隔离 DM 上下文,但不会限制会话工具。如需更窄的访问范围,请明确选择 agent、tree 或 self,或使用 tools.agentToAgent.allow 限制代理对。设置 tools.agentToAgent.enabled: false 可阻止普通的跨代理访问;请求方拥有的原生子代理和 ACP 子会话在 tree 或 all 下仍保持可达。tree 保留规范的主会话例外;self 甚至将主会话限制在其当前会话内。

tools.sessions_spawn

控制 sessions_spawn 的内联附件支持。

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}
附件说明
  • 附件需要 enabled: true。
  • 子代理附件会暂存于 Gateway 拥有的状态中,并带有 .manifest.json;它们绝不会通过子工作区写入。
  • 沙箱化的子会话只能在 /openclaw/attachments/<uuid>/ 以只读方式接收其会话拥有的附件。带附件的 agent 作用域会话使用专用运行时,因此同级 guest 会话无法继承该投影。没有只读资源投影的共享作用域沙箱和后端会在暂存前拒绝带附件的派生请求。
  • 未沙箱化的子会话会收到 Gateway 拥有的绝对路径,并可通过工作区作用域的文件/媒体工具读取。
  • ACP 附件仅支持图片,在通过相同的文件数、单文件字节数和总字节数限制后,会以内联方式转发到 ACP 运行时。
  • 附件内容会自动从转录持久化中移除。
  • Base64 输入会经过严格的字母表/填充校验以及解码前大小守卫检查。
  • 子代理附件的文件权限为:目录 0700,文件 0600。
  • 子代理清理遵循 cleanup 策略:delete 始终移除附件;keep 仅在 retainOnSessionKeep: true 时保留附件。
  • 从早于 readOnlyResourceMounts 的版本升级:先前暂存的附件仍保留在其子工作区的 .openclaw/attachments/<uuid>/ 中。其注册表记录会在不删除也不遍历这些文件的情况下退役,因此请通过常规工作区清理来移除残留文件。新的派生请求会暂存于 Gateway 拥有的状态中;子会话 prompt 路径是唯一可用的文件系统位置。附件收据中的 relDir 是保留的标识符,而非可用的位置,不得对其进行解析。

agents.defaults.subagents

{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        announceTimeoutMs: 120000,
        archiveAfterMinutes: 60,
      },
    },
  },
}
  • model:派生子代理的默认模型。如果省略,子代理将继承调用方的模型。
  • allowAgents:当请求方代理未设置自己的 subagents.allowAgents 时,sessions_spawn 使用的已配置目标 agent id 默认允许列表(["*"] = 任意已配置目标;默认:仅同一代理)。其 agent 配置已被删除的过期条目会被 sessions_spawn 拒绝,并从 agents_list 中省略;运行 openclaw doctor --fix 可清理它们。
  • maxConcurrent:每个直接发起派生的控制会话的最大并发普通子代理运行数。默认:8;独立会话不共享此预算。Swarm 收集器子会话改用 tools.swarm.maxConcurrent。Codex 原生子代理使用 Codex 自己的调度器和限制。
  • maxChildrenPerAgent:每个会话中活动子会话数的独立准入限制。默认:5;提高 maxConcurrent 不会提高此限制。
  • runTimeoutSeconds:当调用方未传入自己的覆盖值时,sessions_spawn 的超时时间(秒)。默认:0(无超时);上面显示的 900 是常见的可选配置值,并非内置默认值。
  • announceTimeoutMs:gateway agent announce 投递尝试的每次调用超时时间(毫秒)。默认:120000。瞬时重试可能使 announce 的总等待时间超过单个配置的超时时间。
  • archiveAfterMinutes:子代理会话完成后,经过多少分钟会自动归档。默认:60;0 表示禁用自动归档。
  • 每个子代理的工具策略:tools.subagents.tools.allow / tools.subagents.tools.deny。

tools.swarm

Swarm 默认启用。收集器子会话(collect: true)在专用的 subagent:swarm:<schedulerGroupKey> 通道中运行,并受该组解析后的 maxConcurrent 上限约束。它们使父级的普通子代理通道保持可用。由收集器派生的普通子会话使用该收集器自身的会话通道。

{
  tools: {
    swarm: {
      maxConcurrent: 32,
      maxChildrenPerGroup: 50,
      maxTotalPerGroup: 200,
    },
  },
}

maxConcurrent 默认为 32,接受 1 到 1000 的整数。每个运行中的子会话消耗一个模型流和一个 Code Mode worker 隔离实例。单独的 maxChildrenPerGroup 和 maxTotalPerGroup 准入限制默认保持为每组 50 个活动子会话和 200 次生命周期内派生。有关所有设置和每代理覆盖项,请参阅 Swarm 配置。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw