配置 — 按智能体条目与多智能体路由
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/modelid 为键。使用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 }
确定性匹配顺序:
match.peermatch.guildIdmatch.teamIdmatch.accountId(精确匹配,无 peer/guild/team)match.accountId: "*"(整个频道)- 单智能体回退(仅当恰好配置了一个智能体时;显式多智能体集群如果没有匹配的绑定,则失败关闭)
在每个层级内,第一个匹配的 bindings 条目生效。
对于 type: "acp" 条目,OpenClaw 通过精确的会话身份(match.channel + 账户 + match.peer.id)进行解析,并且不使用上述 route 绑定层级顺序。
每个智能体的访问配置¶
完全访问(无沙箱)
只读工具 + 工作区
{
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