配置 — 跨 agent、session 和 subagent 工具

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

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 区分大小写；通配符模式不区分大小写。

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",
    },
  },
}

环境群组监听仍会排队活动通知，并告诉主会话某事发生在哪里。它们不授予访问权限。默认 all 范围已覆盖跨代理的会话，包括与其他用户的对话。按对等方的 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"
      },
    },
  },
}

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 的已配置目标代理 ID 的默认允许列表（["*"] = 任意已配置目标；默认：仅同一代理）。其代理配置已被删除的过期条目会被 sessions_spawn 拒绝，并从 agents_list 中省略；运行 openclaw doctor --fix 可清理它们。
• maxConcurrent: 每个直接生成/控制器会话中，普通子代理运行的最大并发数。默认：8；独立会话不共享此预算。Swarm 收集器子项改用 tools.swarm.maxConcurrent。Codex 原生子代理使用 Codex 的独立调度器和限制。
• maxChildrenPerAgent: 每个会话上活动子项的独立准入限制。默认：5；提高 maxConcurrent 不会提高此限制。
• runTimeoutSeconds: 当调用方未传入自己的覆盖值时，sessions_spawn 的超时时间（秒）。默认：0（无超时）；上面显示的 900 是常见的可选值，不是内置默认值。
• announceTimeoutMs: 网关 agent 公告投递尝试的每次调用超时时间（毫秒）。默认：120000。瞬时重试可能使总公告等待时间超过一个配置的超时时间。
• 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 工作器隔离环境。 独立的 maxChildrenPerGroup 和 maxTotalPerGroup 准入限制 默认仍为每组 50 个活动子项和 200 个生命周期生成数。 有关所有设置和 每个代理的覆盖，请参阅 Swarm 配置。