智能体剖析
代理通过单个 [agents.<alias>] 配置块进行配置。每个字段要么是对其他位置所配置内容的引用,要么是针对单个代理的覆盖项。下表根据配置 schema 自动生成,因此始终与正在运行的构建版本保持一致。点击字段可展开;再次点击可查看如何进行设置。
a2a
按代理的 A2A 发布块([agents.<alias>.a2a])。用于控制该别名是否可作为符合规范的 A2A 代理被发现,以及其卡片上显示哪些已解析技能。默认关闭(published = false,不暴露技能)。参见 crate::multi_agent::AgentA2aConfig。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.a2a 字段。
zerocode
在 Config 面板中,设置 agents.<alias>.a2a 字段。
zeroclaw config
zeroclaw config set agents.<alias>.a2a <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__a2a=
acp_enable_mcp
当该 agent 提供 ACP (session/new) 会话时,初始化其 mcp_bundles 工具。默认关闭:MCP 服务器是外部进程/服务,在连接时可能阻塞启动,而 ACP session/new 预期应尽快返回。仅当该 agent 必须通过 ACP 调用其 mcp_bundles 工具时启用;这样 session/new 会承担一次性的 MCP 连接成本(每个服务器都有上限且非致命)。按 agent 单独设置,这样每个 ACP 配置文件都可独立选择加入;当该 agent 是 ACP 默认值(acp.default_agent,或是唯一配置的 agent)时,对于省略 agentAlias 的会话会自动采用该标志。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.acp_enable_mcp 字段。
zerocode
在 Config 面板中,设置 agents.<alias>.acp_enable_mcp 字段。
zeroclaw config
zeroclaw config set agents.<alias>.acp_enable_mcp <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__acp_enable_mcp=
channels
此代理处理的通道别名(例如 ["telegram.<alias>", "discord.<alias>"])。每个条目都是一个 ChannelRef,通过 [channels.<type>.<alias>] 进行解析;Config::validate() 会在引用悬空时直接报错。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.channels 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.channels 字段。
zeroclaw config
zeroclaw config set agents.<alias>.channels <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__channels=
classifier_provider
针对每条消息的 LLM 回复意图分类器(zeroclaw-channels 中的 classify_channel_reply_intent)的可选覆盖项。当此项非空时,通道编排器会将“这条消息是否应当被回复?”的分类调用路由到此处引用的 [providers.models.<type>.<alias>],而不再复用主智能体的 model_provider。api_key / uri / model / temperature 等的权威来源是所引用的 [providers.models.<type>.<alias>] 条目。根据 AGENTS.md 中的 SINGLE SOURCE OF TRUTH 原则,此字段仅为引用(绝不是副本)。为空(Default)= 继承主智能体已解析的 provider+model(保留 PR 前的行为;向后兼容)。使用场景:分类只是一个低成本的 REPLY/NO_REPLY 判定,不需要高端模型。可将其指向一个快速/免费的小模型(例如 kimi-k2.5、qwen-turbo),同时让 model_provider 保持使用昂贵的应答模型(例如 qwen3.6-plus)。注意:TOML 表名不能包含 .,因此别名 kimi-k2.5 必须写成 [providers.models.custom.kimi-k2-5]。底层的 model = "kimi-k2.5" 字符串仍可包含点号。ACP 通道(IDE 直连)始终回复并完全跳过分类器,因此此字段对 ACP 流量没有影响。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.classifier_provider 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.classifier_provider 字段。
zeroclaw config
zeroclaw config set agents.<alias>.classifier_provider <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__classifier_provider=
cron_jobs
Cron 作业别名。每个条目引用 cron[key],这是一个声明式的计划作业,由调度器在其配置的触发器上调用。当 cron 触发时,此 agent 是执行该作业的执行者。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.cron_jobs 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.cron_jobs 字段。
zeroclaw config
zeroclaw config set agents.<alias>.cron_jobs <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__cron_jobs=
delegate_same_risk_profile
自动允许委派给与该智能体共享相同风险配置的所有智能体。默认值 true 保留历史可达范围,即任何相同配置的同级智能体都是委派目标。设置为 false 可使该智能体退出此机制,从而仅允许显式 delegates 列表中的智能体可达。门控(即是否允许委派)仍由风险配置的 delegation_policy.mode 控制;此设置仅缩小可达范围。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.delegate_same_risk_profile 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.delegate_same_risk_profile 字段。
zeroclaw config
zeroclaw config set agents.<alias>.delegate_same_risk_profile <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__delegate_same_risk_profile=
delegates
显式委派名册:此代理可委派给的额外代理别名,超出同配置档案的同级代理。可以为空。为便于手动编辑,接受字符串条目并作为有界委派加载;保存配置时会发出带显式模式的对象条目。条目可命名处于不同风险配置文件上的代理。Config::validate() 在别名悬空、别名重复或自引用时会报错。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.delegates 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.delegates 字段。
zeroclaw config
zeroclaw config set agents.<alias>.delegates <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__delegates=
identity
每个代理的身份格式([agents.<alias>.identity])。每个代理在其各自的代理工作区内渲染自己的 IDENTITY.md / SOUL.md;此区块用于选择格式(OpenClaw 或 AIEOS)以及代理身份文档的可选内联/文件来源。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.identity 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.identity 字段。
zeroclaw config
zeroclaw config set agents.<alias>.identity <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__identity=
knowledge_bundles
知识包别名。增量式:代理会加载列出的每一个知识包。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.knowledge_bundles 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.knowledge_bundles 字段。
zeroclaw config
zeroclaw config set agents.<alias>.knowledge_bundles <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__knowledge_bundles=
mcp_bundles
MCP bundle 别名。每个条目都引用 mcp_bundles[key],即一组有名称的 MCP 服务器。默认安全:仅授予代理其 bundle 中所命名的服务器。没有 mcp_bundles 的代理不会接收任何 MCP 服务器(省略不等于授予)。参见 Config::mcp_servers_for_agent。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.mcp_bundles 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.mcp_bundles 字段。
zeroclaw config
zeroclaw config set agents.<alias>.mcp_bundles <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__mcp_bundles=
memory
每个 agent 的内存后端选择([agents.<alias>.memory])。backend 字段在 agent 创建时锁定,后续加载时不可变。默认为 Sqlite。参见 crate::multi_agent::AgentMemoryConfig。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.memory 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.memory 字段。
zeroclaw config
zeroclaw config set agents.<alias>.memory <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__memory=
model_provider
带点的模型提供方别名(例如 "anthropic.<alias>")。运行时通过 model_providers.<type>.<alias> 进行解析;Config::validate() 会对悬空引用直接报错。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.model_provider 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.model_provider 字段。
zeroclaw config
zeroclaw config set agents.<alias>.model_provider <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__model_provider=
precheck
按代理的回复意图预检查控制。分类器调用会在消息时读取此块;模型/提供方选择仍保留在 classifier_provider,因此只有一个路由单一事实来源。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.precheck 字段。
zerocode
在 Config 面板中,设置 agents.<alias>.precheck 字段。
zeroclaw config
zeroclaw config set agents.<alias>.precheck <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__precheck=
risk_profile
风险配置文件别名(例如 "default")。在运行时解析委派防护规则。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.risk_profile 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.risk_profile 字段。
zeroclaw config
zeroclaw config set agents.<alias>.risk_profile <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__risk_profile=
runtime_profile
运行时配置别名(例如 "default")。用于解析 agentic/迭代设置。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.runtime_profile 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.runtime_profile 字段。
zeroclaw config
zeroclaw config set agents.<alias>.runtime_profile <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__runtime_profile=
skill_bundles
技能包别名。每个条目在运行时解析为 skill_bundles[key].directory;代理会加载列出的每个包。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.skill_bundles 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.skill_bundles 字段。
zeroclaw config
zeroclaw config set agents.<alias>.skill_bundles <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__skill_bundles=
summary_provider
面向每个代理的 context-compression summarizer provider 覆盖项,作为 providers.models.<type>.<alias> 引用。空值(Default)= 继承运行时配置文件的 context_compression.summary_provider,否则为该代理自身解析后的 provider+model。仅为引用,绝不复制;由 [Config::effective_summary_provider] 解析。由 Config::validate() 校验。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.summary_provider 字段。
zerocode
在 Config 面板中,设置 agents.<alias>.summary_provider 字段。
zeroclaw config
zeroclaw config set agents.<alias>.summary_provider <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__summary_provider=
transcription_provider
转录 / STT 提供方,以点分隔的别名引用形式(<type>.<alias>,例如 "groq.<alias>")。通过 transcription_providers.<type>.<alias> 解析。留空 = agent 没有转录偏好;接入语音的渠道仍需要一个已解析的提供方(没有全局默认值),因此当入站语音流进入一个 transcription_provider 为空的 agent 时,会在渠道边界处显式报错。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.transcription_provider 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.transcription_provider 字段。
zeroclaw config
zeroclaw config set agents.<alias>.transcription_provider <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__transcription_provider=
tts_provider
TTS 提供方采用点号别名引用形式(<type>.<alias>,例如 "openai.<alias>")。通过 tts_providers.<type>.<alias> 进行解析。留空 = 此 agent 不启用 TTS(不存在全局默认提供方的概念;每个需要 TTS 的 agent 都要自行设置 tts_provider)。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.tts_provider 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.tts_provider 字段。
zeroclaw config
zeroclaw config set agents.<alias>.tts_provider <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__tts_provider=
workspace
每个 agent 的工作区块([agents.<alias>.workspace])。保存该 agent 的文件系统路径、跨 agent 访问允许列表、文件系统逃逸布尔值以及跨 agent 内存允许列表。默认完全隔离(无跨 agent 访问)。参见 crate::multi_agent::AgentWorkspaceConfig。
将它放置在任何表面上:
网关仪表板
打开 /config/agents 并设置 agents.<alias>.workspace 字段。
zerocode
在 Config 窗格中,设置 agents.<alias>.workspace 字段。
zeroclaw config
zeroclaw config set agents.<alias>.workspace <value>
环境变量
导出此覆盖配置(POSIX shell;可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中)。将 <alias> 替换为实际的别名:
export ZEROCLAW_agents__<alias>__workspace=
引用指向的位置
代理的大部分配置都是点式别名,指向在各自专属配置段中所配置的内容。代理本身并不拥有这些内容,它只是进行指向,并且同一个目标可以被多个代理共享。上方的字段表才是权威清单;以下说明了每一类引用的指向位置:
- 提供方(模型提供方):智能体的聊天模型及其配套的文本转语音、转录和分类器提供方,每个都需指定一个
[providers.models.<type>.<alias>]条目。 - 配置文件(安全与自治):风险配置文件设置自治和沙盒策略;运行时配置文件设置操作调优(工具迭代上限、预算、超时、上下文限制)。
- 通道(通道):智能体进行响应的消息传递界面。当两个智能体共享同一个通道时,由对等组决定它们能否相互通信。
- 捆绑包 (工具):可复用的技能、知识和 MCP 服务器组,通过别名进行附加。
- Cron:绑定到 agent 的命名计划任务。
每个代理的覆盖设置
代理的某些配置不是引用,而是用于覆盖全局默认值的、针对每个代理的配置块:工作区、记忆和身份。这些是连接中位于磁盘上的部分,详见 Filesystem components。
验证
如果 model_provider 无法解析为已配置的 provider 条目,或者 risk_profile 无法解析为已配置的风险配置,Config::validate() 会在启动时直接报错失败。错误的引用会在 agent 运行前被捕获,而不是被静默忽略。