跳转至

配置 — 按智能体条目与多智能体路由

Per-agent overrides under agents.entries and the multiAgent bindings that decide which agent answers a message.

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,然后是有效会话提供商声明的小模型默认值。仪表盘标题会使用有效常规会话模型重试一次。空字符串会跳过该代理的备用 utility 路由,但不会禁用仪表盘标题生成。
  • 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 原生 Code Mode。
  • 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:每个直接生成/控制器会话的最大并发子代理运行数。默认: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(可选;仅用于 route 绑定):{ dmScope, groupScope } 为匹配的 peer 覆盖会话路由
  • 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 + 账户 + match.peer.id)进行解析,并且不使用上述 route 绑定层级顺序。

每个智能体的访问配置

完全访问(无沙箱)
{
  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