配置 — 每个代理条目和多代理路由

每个代理在 agents.entries 和 multiAgent 绑定下覆盖，决定哪个代理应答消息。

agents.entries（每个代理覆盖）

使用 agents.entries.*.tts 为代理指定其自己的 TTS 提供商、语音、模型、 风格或自动 TTS 模式。代理配置块会与全局 tts 进行深度合并，因此共享凭据可以集中放置，而各个代理只需覆盖所需的语音或提供商字段。当前代理的覆盖设置会应用于自动语音回复、/tts audio、/tts status 以及 tts 代理工具。有关提供商示例和优先级，请参阅文本转语音。

{  agents: {    entries: {      main: {        name: "Main Agent",        workspace: "~/.openclaw/workspace",        agentDir: "~/.openclaw/agents/main/agent",        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }        utilityModel: "openai/gpt-5.4-mini",        thinkingDefault: "high", // per-agent thinking level override        reasoningDefault: "on", // per-agent reasoning visibility override        fastModeDefault: false, // per-agent fast mode override        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key        tts: {          providers: {            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },        skills: ["docs-search"], // replaces agents.defaults.skills when set        identity: {          name: "Samantha",          theme: "helpful sloth",          emoji: "🦥",          avatar: "avatars/samantha.png",        },        groupChat: { mentionPatterns: ["@openclaw"] },        sandbox: { mode: "off" },        runtime: {          type: "acp",          acp: {            agent: "codex",            backend: "acpx",            mode: "persistent", // persistent | oneshot            cwd: "/workspace/openclaw",          },        },        subagents: { allowAgents: ["*"] },        tools: {          profile: "coding",          allow: ["browser"],          deny: ["canvas"],          elevated: { enabled: true },        },      },    },  },}

• agents.entries 对象密钥是稳定代理 ID。
• cwd：用​​于回复运行的可选工作目录，与 workspace 分开。覆盖 agents.defaults.cwd；有关优先级和沙箱限制，请参阅 工作目录。
• default 已退役。恰好一个配置的代理隐式解析；多代理操作需要绑定、表面 agentId 目标、范围 session/store 所有者或显式 --agent/request 字段。
• model：字符串形式会为代理设置严格的主模型，不使用模型回退；对象形式的 { primary } 同样严格，除非添加 fallbacks。使用 { primary, fallbacks: [...] } 可让该代理启用回退，或使用 { primary, fallbacks: [] } 明确指定严格行为。只覆盖 primary 的 Cron 作业仍会继承默认回退，除非设置 fallbacks: []。
• utilityModel：可选的代理级覆盖项，用于生成会话标题和线程标题等简短内部任务。会回退到 agents.defaults.utilityModel，然后回退到当前有效会话提供程序声明的小模型默认值。控制面板标题会使用当前有效的常规会话模型重试一次。空字符串会跳过该代理的备用实用模型路径，但不会禁用控制面板标题生成。
• params：代理范围的流参数合并到共享的和代理特定的每个模型参数上。将此用于应适用于代理模型的覆盖，例如 cacheRetention、temperature 或 maxTokens。
• tts：可选的代理级文本转语音覆盖项。该配置块会与 tts 深度合并，因此应将共享的提供程序凭据和回退策略保留在 tts 中，并仅在此处设置角色专用的值，例如提供程序、语音、模型、风格或自动模式。
• skills：可选的代理级技能允许列表。如果省略，代理会在设置时继承 agents.defaults.skills；显式列表会替换默认值而不是合并，[] 表示不使用任何技能。
• thinkingDefault：可选的每个代理默认思维级别 （off | minimal | low | medium | high | xhigh | adaptive | max | ultra）。当未设置每条消息或会话覆盖时，优先于代理特定和共享模型 params.thinking 设置和 agents.defaults.thinkingDefault。所选的 provider/model 配置文件控制哪些值有效；对于Google Gemini，adaptive保持提供商拥有的动态思维（thinkingLevel在Gemini 3/3.1上省略，thinkingBudget: -1在Gemini 2.5上省略）。参见思维解析顺序。
• reasoningDefault：可选的代理级默认 reasoning 可见性（on | off | stream）。当未设置每条消息或会话级 reasoning 覆盖时，会覆盖该代理的 agents.defaults.reasoningDefault。
• fastModeDefault：可选的代理级快速模式默认值（"auto" | true | false）。当未设置每条消息或会话级快速模式覆盖时，会覆盖该代理的 agents.defaults.fastModeDefault。
• models：可选的每个代理模型设置，由完整的 provider/model id 键入。使用 models["provider/model"].params 进行特定于模型的请求设置，使用 models["provider/model"].agentRuntime 进行运行时异常。 models["provider/model"].codeMode 接受 true 或 false，并优先于代理的 tools.codeMode 激活、共享模型覆盖和全局默认值。省略它来继承；它不影响 Codex 本机代码模式。
• nativeRuntimeConsent：设置期间记住的harness ID 的可选列表，例如 ["muse"]。仅适用于该代理；它没有全局或默认继承。管理员选择记住的harness或与其创建聊天会自动使用完全访问权限并禁用可选沙箱。此促销使用与显式设置更改相同的权限更改生命周期，并在活动运行期间拒绝更改。非管理员客户端无法使用记住的同意来提高聊天权限；他们现有的限制仍然适用。强制沙箱和工作区边界仍然拒绝运行时。每轮都会检查当前列表、当前会话身份、完全访问权限、沙箱关闭以及是否存在工具白名单、禁用工具或群体收集。在本机调度之前会立即再次检查当前的实时配置，因此删除同意也会阻止依赖它的排队或准备工作。在 记住的本机运行时权限 下的“设置”中删除 ID，以便根据记住的同意对每个聊天撤销它。明确的 继续此聊天 同意保持不变。该字段是可加的并且不需要迁移。
• runtime：可选的代理级运行时描述符。当代理应默认使用 ACP harness 会话时，使用 type: "acp" 以及 runtime.acp 默认值（agent、backend、mode、cwd）。
• identity.avatar：相对于工作区的路径、http(s) URL 或 data: URI。
• 本地工作空间相关的 identity.avatar 图像文件仅限于 2 个 MB。不会根据本地文件大小限制检查 http(s) URL 和 data: URI。
• identity 派生默认值：ackReaction 来自 emoji，mentionPatterns 来自 name/emoji.
• subagents.allowAgents：显式 sessions_spawn.agentId 目标的已配置代理 ID 的白名单（["*"] = 任何已配置目标；默认值：仅限相同代理）。当应允许自我定位 agentId 调用时，请包含请求者 ID。代理配置被删除的过时条目将被 sessions_spawn 拒绝，并从 agents_list 中省略；运行 openclaw doctor --fix 来清理它们，或者添加一个最小的 agents.entries.* 条目（如果该目标在继承默认值时应保持可生成）。
• tools.agentToAgent.send：sessions_send 的可选传出目标代理 ID 或 * 模式。忽略保留全局策略和可见性检查； [] 拒绝普通的跨代理发送。匹配允许在狭窄的可见性下进行仅发送访问，而不授予历史记录、搜索、列表、状态或会话控制。全球智能体对智能体政策和沙箱限制仍然适用；同一代理和请求者拥有的子规则保持不变。请参阅 仅发送配置。
• 沙箱继承保护：如果请求方会话处于沙箱中，sessions_spawn 会拒绝将以未沙箱方式运行的目标。
• subagents.requireAgentId：为 true 时，阻止省略 agentId 的 sessions_spawn 调用（强制显式配置文件选择；默认值：false）。
• subagents.maxConcurrent：每个即时 spawning/controller 会话的最大并发子代理运行数。默认：8；独立会话有独立预算。 Codex-native 子代理使用 Codex 的单独调度程序和限制。
• subagents.maxChildrenPerAgent：单个代理会话可以生成的活动子项的单独入场限制。默认值：5。
• subagents.maxSpawnDepth：子代理生成的最大嵌套深度（1-5）。默认：5；设置 1 使直接子节点离开。
• subagents.archiveAfterMinutes：已完成子代理状态被归档前的存留时间。默认值：60。

多代理路由

在一个网关内运行多个独立的代理。请参阅 Multi-Agent。

{  agents: {    ownership: "explicit",    defaults: { heartbeat: { agentId: "home" }, systemAgent: { agentId: "home" } },    entries: {      home: { workspace: "~/.openclaw/workspace-home" },      work: { workspace: "~/.openclaw/workspace-work" },    },  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],  talk: { agentId: "home" },}

绑定匹配字段

• type（可选）：正常路由使用 route（缺省时默认为 route），持久化 ACP 会话绑定使用 acp。
• match.channel（必需）
• match.accountId（可选；* = 任意账户；省略 = 默认账户）
• match.peer（可选；{ kind: direct|group|channel, id }）
• match.guildId / match.teamId（可选；按渠道不同）
• session（可选；仅限路由绑定）：{ dmScope, groupScope } 覆盖匹配对等方的会话路由
• acp（可选；仅适用于 type: "acp"）：{ mode, label, cwd, backend }

固定比赛顺序：

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId（精确匹配，不含 peer/guild/team）
5. match.accountId: "*"（频道范围）
6. 单代理后备（仅当仅配置了一个代理时；没有匹配绑定的显式多代理队列拒绝请求）

在每个层级内，最先匹配的 bindings 条目获胜。

对于 type: "acp" 的条目，OpenClaw 会按精确会话身份（match.channel + account + match.peer.id）解析，不使用上面的路由绑定层级顺序。

每个代理的访问配置

{  agents: {    entries: {      personal: {        workspace: "~/.openclaw/workspace-personal",        sandbox: { mode: "off" },      },    },  },}

{  agents: {    entries: {      family: {        workspace: "~/.openclaw/workspace-family",        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },        tools: {          allow: [            "read",            "sessions_list",            "sessions_history",            "sessions_send",            "sessions_spawn",            "session_status",          ],          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],        },      },    },  },}

{  agents: {    entries: {      public: {        workspace: "~/.openclaw/workspace-public",        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },        tools: {          allow: [            "sessions_list",            "sessions_history",            "sessions_send",            "sessions_spawn",            "session_status",            "whatsapp",            "telegram",            "slack",            "discord",            "gateway",          ],          deny: [            "read",            "write",            "edit",            "apply_patch",            "exec",            "process",            "browser",            "canvas",            "nodes",            "cron",            "gateway",            "image",          ],        },      },    },  },}

有关优先级详细信息，请参阅 多代理沙箱和 Tools。