配置 — 每个智能体条目和多智能体路由

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 目标、作用域化的会话/存储所有者，或显式的 --agent/请求字段。
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。所选提供商/模型配置文件决定哪些值有效；对于 Google Gemini，adaptive 保留提供商拥有的动态思考（Gemini 3/3.1 上省略 thinkingLevel，Gemini 2.5 上为 thinkingBudget: -1）。请参阅思考解析顺序。
reasoningDefault：可选的逐代理默认推理可见性（on | off | stream）。当未设置逐消息或会话推理覆盖时，覆盖此代理的 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 原生代码模式。
runtime：可选的逐代理运行时描述符。当代理应默认使用 ACP 框架会话时，使用 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.* 条目。
沙箱继承保护：如果请求者会话处于沙箱中，sessions_spawn 会拒绝那些将在非沙箱环境中运行的目标。
subagents.requireAgentId：为 true 时，阻止省略 agentId 的 sessions_spawn 调用（强制显式选择配置文件；默认：false）。
subagents.maxConcurrent：每个直接生成/控制会话的最大并发子代理运行数。默认：8；独立会话有独立的预算。Codex 原生子代理使用 Codex 独立的调度器和限制。
subagents.maxChildrenPerAgent：对单个代理会话可生成的活动子代理数量的独立准入限制。默认：5。
subagents.maxSpawnDepth：子代理生成的最大嵌套深度（1-5）。默认：5；设置为 1 可使直接子代成为叶子节点。
subagents.archiveAfterMinutes：已完成的子代理状态在归档前的存活时间。默认：60。

多智能体路由¶

在一个 Gateway 中运行多个隔离的智能体。参见多智能体。

{
  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 用于常规路由（缺少 type 时默认为 route），acp 用于持久 ACP 会话绑定。
match.channel（必填）
match.accountId（可选；* = 任意账户；省略 = 默认账户）
match.peer（可选；{ kind: direct|group|channel, id }）
match.guildId / match.teamId（可选；特定于频道）
session（可选；仅路由绑定）：{ dmScope, groupScope } 覆盖匹配 peer 的会话路由
acp（可选；仅用于 type: "acp"）：{ mode, label, cwd, backend }

确定性匹配顺序：

match.peer
match.guildId
match.teamId
match.accountId（精确匹配，无 peer/guild/team）
match.accountId: "*"（整个频道）
单智能体回退（仅当恰好配置了一个智能体时；没有匹配绑定的显式多智能体集群会失败关闭）

在每个层级内，第一个匹配的 bindings 条目生效。

对于 type: "acp" 条目，OpenClaw 通过精确会话身份（match.channel + 账户 + 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",
          ],
        },
      },
    },
  },
}

有关优先级详情，参见多智能体沙箱与工具。

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

配置 — 每个智能体条目和多智能体路由

agents.entries（逐代理覆盖）¶

多智能体路由¶

绑定匹配字段¶

按智能体访问配置¶

`agents.entries`（逐代理覆盖）¶