配置参考

ZeroClaw 通过 TOML 文件进行配置。除非另有说明，所有字段都是可选的。

章节	描述
`a2a`	为将来的兄弟配置留出空间的 A2A 节包装器。
`acp`	ACP (Agent Client Protocol) 服务器配置（`[acp]` 部分）。
`agents`	此安装中的别名代理。`[agents.<alias>]` 下的每个条目
`backup`	备份工具配置（`[backup]` 部分）。
`browser`	Browser 自动化配置（`[browser]` 部分）。
`browser_delegate`
`channels`	顶层通道配置（`[channels]` 部分）。
`claude_code`	Claude Code CLI 工具配置（`[claude_code]` 部分）。
`claude_code_runner`	Claude Code 任务运行器配置（`[claude_code_runner]` 部分）。
`cloud_ops`	控制只读云转换分析工具：
`codex_cli`	Codex CLI 工具配置（`[codex_cli]` 部分）。
`composio`	Composio 托管的 OAuth 工具集成（`[composio]` 部分）。
`conversational_ai`	Conversational AI agent builder 配置（`[conversational_ai]` 部分）。
`cost`	成本跟踪和预算强制执行配置（`[cost]` 部分）。
`cron`	声明式 cron 作业（`[cron.<alias>]`），按别名键控。
`data_retention`	数据保留和清除配置（`[data_retention]` 部分）。
`delegate`	默认超时值的全局委托工具配置。
`embedding_routes`	Embedding 路由规则 — 将 `hint:<name>` 路由到特定
`enroll`	证书注册端点（`[enroll]`）。
`escalation`	升级路由配置（`[escalation]` 部分）。
`eval`	代理评估 harness（`[eval]`）的配置，通过该
`file_download`	独立文件下载工具配置 (`[file_download]`)。
`file_upload`	独立文件上传工具配置（`[file_upload]`）。
`file_upload_bundle`	独立多文件 bundle 上传工具配置
`gateway`	网关服务器配置（`[gateway]` 部分）。
`gemini_cli`	Gemini CLI 工具配置（`[gemini_cli]` 部分）。
`google_workspace`	Google Workspace CLI (`gws`) 工具配置（`[google_workspace]` 部分）。
`hardware`	用于物理世界交互的向导式硬件配置。
`heartbeat`	用于周期性健康 ping 的 Heartbeat 配置（`[heartbeat]` 部分）。
`hooks`
`http_request`	HTTP 请求工具配置（`[http_request]` 部分）。
`image_gen`	独立图像生成工具配置（`[image_gen]`）。
`jira`	Jira 集成配置（`[jira]`）。
`knowledge`	用于捕获和复用专业知识的知识图谱配置。
`knowledge_bundles`	命名知识包（`[knowledge_bundles.<alias>]`）。
`link_enricher`	用于入站频道消息的自动链接理解（`[link_enricher]`）。
`linkedin`	LinkedIn 集成配置（`[linkedin]` 部分）。
`locale`	工具描述的区域设置（例如 `"en"`、`"zh-CN"`）。
`mcp`	外部 MCP 客户端配置（`[mcp]` 部分）。
`mcp_bundles`	命名 MCP 服务器捆绑包（`[mcp_bundles.<alias>]`）。
`media_pipeline`	自动媒体理解流水线配置（`[media_pipeline]`）。
`memory`	内存后端配置（`[memory]` 部分）。
`microsoft365`	通过 Microsoft Graph API 的 Microsoft 365 集成（`[microsoft365]` 部分）。
`model_routes`	模型路由规则 — 将 `hint:<name>` 路由到特定的
`multimodal`	多模态（图像）处理配置（`[multimodal]` 部分）。
`nodes`	动态节点发现系统（`[nodes]`）的配置。
`notion`	Notion 集成配置（`[notion]`）。
`observability`	可观测性后端配置（`[observability]` 部分）。
`onboard_state`	多客户端工作区隔离配置。
`opencode_cli`	OpenCode CLI 工具配置（`[opencode_cli]` 部分）。
`pacing`	慢速/本地 LLM 工作负载的节奏控制（`[pacing]` 部分）。
`peer_groups`	命名对等组（`[peer_groups.<name>]`）。每个条目绑定一个
`peripherals`	外设板集成配置（`[peripherals]` 部分）。
`pipeline`	Pipeline 工具配置（`[pipeline]` 部分）。
`plugins`	插件系统配置。
`project_intel`	项目交付智能配置（`[project_intel]` 部分）。
`providers`	每个已配置提供程序类别的顶层包装器。
`proxy`	用于出站 HTTP/HTTPS/SOCKS5 流量的代理配置（`[proxy]` 部分）。
`query_classification`	自动查询分类——通过关键字/模式对用户消息进行分类
`relay`	指定中继客户端（`[relay]`）。
`reliability`	可靠性和监督配置（`[reliability]` 部分）。
`risk_profiles`	命名的风险/自主配置文件（`[risk_profiles.<alias>]`）。
`runtime`	运行时适配器配置（`[runtime]` 部分）。
`runtime_profiles`	命名的运行时/LLM 执行配置文件（`[runtime_profiles.<alias>]`）。
`scheduler`	定时任务执行的调度器配置（`[scheduler]` 部分）。
`schema_version`	配置文件模式版本。
`secrets`	Secrets 加密配置（`[secrets]` 部分）。
`security`	用于审计日志记录、OTP、急停、IAM/SSO、WebAuthn 的安全配置，
`security_ops`	托管网络安全服务（MCSS）仪表板代理配置（`[security_ops]`）。
`shell_tool`	Shell 工具配置（`[shell_tool]` 部分）。
`skill_bundles`	命名技能包（`[skill_bundles.<alias>]`）。
`skills`	Skills 加载配置（`[skills]` 部分）。
`sop`	标准操作程序引擎配置（`[sop]`）。
`storage`	持久存储配置（`[storage]` 部分）。
`text_browser`	Text browser 工具配置（`[text_browser]` 部分）。
`transcription`	带有多提供商支持的语音转录配置。
`trust`
`tts`	文本转语音子系统配置（`[tts]`）。
`tunnel`	用于将网关公开暴露的隧道配置（`[tunnel]` 部分）。
`verifiable_intent`	可验证意图（VI）凭据签发与约束检查
`web_fetch`	Web fetch 工具配置（`[web_fetch]` 部分）。
`web_search`	Web search 工具配置（`[web_search]` 部分）。
`wss`	用于远程 TUI 到守护进程连接的 WebSocket Secure (WSS) 传输（`[wss]`）。

`a2a`

为将来的兄弟配置留出空间的 A2A 节包装器。

键	类型	默认	描述
`server`	object	—	入站 A2A 发现服务器配置。

`a2a.server`

入站 A2A 发现服务器配置。

键	类型	默认	描述
`bind`	字符串？	—	卡片端点 URL 的可选仅用于广告的主机覆盖。The
`enabled`	bool	`false`	入站 A2A 接口的总开关。默认 `false`：不
`port`	整数类型？	—	可选的仅用于 advertise 的端口覆盖，配合 `bind` 使用。`None`
`public_base_url`	字符串	`""`	在智能体卡片端点中通告的由操作员提供的基础 URL。

`acp`

ACP (Agent Client Protocol) 服务器配置（[acp] 部分）。

键	类型	默认	描述
`default_agent`	字符串？	—	当 `session/new` 省略 `agentAlias` 且超过
`max_sessions`	整数	`10`	并发 ACP 会话的最大数量。默认值：`10`。
`session_timeout_secs`	整数	`3600`	空闲会话超时时间（秒）。在此期间没有活动的会话将被

`agents`

此安装中的别名代理。[agents.<alias>] 下的每个条目都是一个面向用户的代理，具有自己的身份、通道、模型提供方、风险配置、工作区和记忆范围。当一个代理将子任务委派给另一个代理时，DelegateTool 会查阅此映射。

`agents.<alias>`

别名代理的配置。每个 [agents.<alias>] TOML 块都会反序列化为其中之一。DelegateTool 会在此处查找条目，以将子任务分派给命名的同级代理。

键	类型	默认	描述
`a2a`	object	—	每个智能体的 A2A 发布和公开技能配置。
`acp_enable_mcp`	bool	`false`	当它服务 ACP 时，初始化此 agent 的 `mcp_bundles` 工具
`channels`	字符串数组	`[]`	该代理处理的频道别名（例如 `["telegram.<alias>", "discord.<alias>"]`）。
`classifier_provider`	字符串	—	对已配置的 `[providers.models.<type>.<alias>]` 条目的引用。
`cron_jobs`	字符串数组	`[]`	Cron 作业别名。每个条目引用 `cron[key]`，一个声明式
`delegate_same_risk_profile`	bool	`true`	自动允许将委托授予与此代理共享风险的每个代理
`delegates`	object[]	`[]`	显式委托名册：此代理可能的其他代理别名
`enabled`	bool	`true`	此代理是否处于活动状态。将其设为 false 可在不移除定义的情况下禁用。
`identity`	object	—	身份格式配置（`[identity]` 部分）。
`knowledge_bundles`	字符串数组	`[]`	知识包别名。增量式：代理会加载每个列出的
`mcp_bundles`	字符串数组	`[]`	MCP bundle 别名。每个条目引用 `mcp_bundles[key]`，一个命名
`memory`	object	—	每个 agent 的内存后端选择及其持久化契约。
`model_provider`	字符串	—	对已配置的 `[providers.models.<type>.<alias>]` 条目的引用。
`precheck`	object	—	按渠道配置回复意图预检查。
`risk_profile`	字符串	—	对已配置的 `[risk_profiles.<type>.<alias>]` 条目的引用。
`runtime_profile`	字符串	—	对已配置的 `[runtime_profiles.<type>.<alias>]` 条目的引用。
`skill_bundles`	字符串数组	`[]`	技能包别名。每个条目解析为
`summary_provider`	字符串	—	对已配置的 `[providers.models.<type>.<alias>]` 条目的引用。
`transcription_provider`	字符串	—	对已配置的 `[providers.transcription.<type>.<alias>]` 条目的引用。
`tts_provider`	字符串	—	对已配置的 `[providers.tts.<type>.<alias>]` 条目的引用。
`workspace`	object	—	每个代理的工作区及跨代理访问配置。

`agents.<alias>.a2a`

每个智能体的 A2A 发布和公开技能配置。

键	类型	默认	描述
`exposed_skills`	字符串数组	`[]`	筛选哪些已解析的 skill id 会出现在此别名的
`published`	bool	`false`	将此别名发布为可发现的 A2A 代理。默认 `false`：

`agents.<alias>.identity`

身份格式配置（[identity] 部分）。

支持 "openclaw"（默认）或 "aieos" 身份文档。

键	类型	默认	描述
`aieos_inline`	字符串？	`null`	内联 AIEOS JSON（文件路径的替代方式）
`aieos_path`	字符串？	`null`	AIEOS JSON 文件的路径（相对于工作区）
`format`	字符串	`"openclaw"`	身份格式：“openclaw”（默认）或“aieos”

`agents.<alias>.memory`

每个 agent 的内存后端选择及其持久化契约。

键	类型	默认	描述
`backend`	表格	—	选择智能体使用的内存后端。

`agents.<alias>.precheck`

按渠道配置回复意图预检查。

键	类型	默认	描述
`enabled`	bool	`true`	当为 false 时，此 agent 的预检查会完全跳过，且每个
`timeout_secs`	整数	`5`	预检 LLM 调用的硬性上限（秒）。在超时时，的

`agents.<alias>.workspace`

每个代理的工作区及跨代理访问配置。

键	类型	默认	描述
`access`	映射	`{}`	跨代理工作区允许列表。空映射表示不授予任何同级访问权限。
`path`	字符串？	—	可选的显式工作区路径。`None` = 从中派生
`read_memory_from`	字符串数组	`[]`	跨智能体记忆允许列表。空列表仅允许访问本地记忆。
`unrestricted_filesystem`	bool	`false`	Escape hatch：当 `true` 时，agent 可以在任意位置读写

`backup`

备份工具配置（[backup] 部分）。

键	类型	默认	描述
`compress`	bool	`true`	压缩备份归档。
`destination_dir`	字符串	`"state/backups"`	备份归档的输出目录（相对于工作区根目录）。
`enabled`	bool	`true`	启用 `backup` 工具。
`encrypt`	bool	`false`	加密备份归档（需要已配置的 secret store 密钥）。
`include_dirs`	字符串数组	`["config","memory","audit","knowledge"]`	要包含在备份中的工作区子目录。
`max_keep`	整数	`10`	要保留的备份最大数量（最旧的会被清理）。
`schedule_cron`	字符串？	`null`	用于计划自动备份的可选 cron 表达式。
`schedule_timezone`	字符串？	`null`	`schedule_cron` 的 IANA 时区。

`browser`

Browser 自动化配置（[browser] 部分）。

控制 browser_open 工具和浏览器自动化后端。

键	类型	默认	描述
`allowed_domains`	字符串数组	`["*"]`	`browser_open` 的允许域名（精确匹配或子域名匹配）
`allowed_private_hosts`	字符串数组	`[]`	允许私有/内部主机绕过 SSRF 保护。
`backend`	字符串	`"agent_browser"`	浏览器自动化后端： “agent_browser” \| “rust_native” \| “computer_use” \| “auto”
`computer_use`	object	—	计算机使用 sidecar 配置（`[browser.computer_use]` 部分）。
`enabled`	bool	`true`	启用 `browser_open` 工具（在系统浏览器中打开 URL，而不进行抓取）
`headed`	bool?	`null`	为 `agent_browser` 后端显示浏览器窗口。未设置时，继承 `AGENT_BROWSER_HEADED`。
`native_chrome_path`	字符串？	`null`	rust-native 后端的可选 Chrome/Chromium 可执行文件路径
`native_headless`	bool	`true`	rust-native 后端的无头模式
`native_webdriver_url`	字符串	`"http://127.0.0.1:9515"`	Rust 原生后端的 WebDriver 端点 URL（例如 `http://127.0.0.1:9515`）
`session_name`	字符串？	`null`	浏览器会话名称（用于 agent-browser 自动化）

`browser.computer_use`

计算机使用 sidecar 配置（[browser.computer_use] 部分）。

将操作系统级别的鼠标、键盘和截图操作委托给本地 sidecar。

键	类型	默认	描述
`allow_remote_endpoint`	bool	`false`	允许为 computer-use sidecar 开放远程/公开端点（默认：false）
`api_key` 🔑	字符串？	`null`	用于 computer-use sidecar 的可选 bearer token
`endpoint`	字符串	`"http://127.0.0.1:8787/v1/actions"`	用于 computer-use 操作（OS 级鼠标/键盘/屏幕截图）的 Sidecar 端点
`max_coordinate_x`	整数类型？	`null`	基于坐标的操作的可选 X 轴边界
`max_coordinate_y`	整数类型？	`null`	用于基于坐标的操作的可选 Y 轴边界
`timeout_ms`	整数	`15000`	每个操作的请求超时时间（毫秒）
`window_allowlist`	字符串数组	`[]`	可选的窗口标题/进程允许列表，将转发到 sidecar 策略

`browser_delegate`

键	类型	默认
`allowed_domains`	字符串数组	`[]`
`blocked_domains`	字符串数组	`[]`
`chrome_profile_dir`	字符串	`""`
`cli_binary`	字符串	`"claude"`
`enabled`	bool	`false`
`task_timeout_secs`	整数	`120`

`channels`

顶层通道配置（[channels] 部分）。

每种 channel 类型都是一个带键的命名实例（别名）表。[channels.telegram.default] 是约定俗成的单实例键。通过 config.channels.telegram.get("default") 访问。

键	类型	默认	描述
`ack_reactions`	bool	`true`	是否添加确认表情反应（收到时 👀，回复时 ✅/⚠️）
`amqp`	映射	—	AMQP 通道实例（`[channels.amqp.<alias>]`）。
`bluesky`	映射	—	Bluesky channel 实例（`[channels.bluesky.<alias>]`）。
`clawdtalk`	映射	—	ClawdTalk 语音频道实例（`[channels.clawdtalk.<alias>]`）。
`cli`	bool	`true`	启用 CLI 交互通道。默认值：`true`。
`debounce_ms`	整数	`0`	入站消息去抖窗口（毫秒）。当发送方触发
`dingtalk`	映射	—	DingTalk 频道实例（`[channels.dingtalk.<alias>]`）。
`discord`	映射	—	Discord 机器人频道实例（`[channels.discord.<alias>]`）。
`email`	映射	—	电子邮件通道实例（`[channels.email.<alias>]`）。
`filesystem`	映射	—	Filesystem SOP 监听器实例（`[channels.filesystem.<alias>]`）。
`git`	映射	—	Git-forge 通道实例（`[channels.git.<alias>]`）。GitHub 是
`gmail_push`	映射	—	Gmail Pub/Sub 推送通知通道实例（`[channels.gmail_push.<alias>]`）。
`imessage`	映射	—	iMessage channel 实例（`[channels.imessage.<alias>]`，仅限 macOS）。
`irc`	映射	—	IRC 频道实例（`[channels.irc.<alias>]`）。
`lark`	映射	—	Lark 渠道实例（`[channels.lark.<alias>]`）。
`line`	映射	—	LINE Messaging API channel 实例（`[channels.line.<alias>]`）。
`linq`	映射	—	Linq Partner API 频道实例（`[channels.linq.<alias>]`）。
`matrix`	映射	—	Matrix 频道实例（`[channels.matrix.<alias>]`）。
`mattermost`	映射	—	Mattermost bot channel 实例（`[channels.mattermost.<alias>]`）。
`max_concurrent_per_channel`	整数	`4`	全局通道消息在途预算的每通道乘数。
`message_timeout_secs`	整数	`300`	处理单个 channel 消息（LLM + 工具）的基础超时时间（秒）。
`mochat`	映射	—	Mochat 客服渠道实例（`[channels.mochat.<alias>]`）。
`mqtt`	映射	—	MQTT 通道实例（`[channels.mqtt.<alias>]`）。
`nextcloud_talk`	映射	—	Nextcloud Talk 机器人频道实例（`[channels.nextcloud_talk.<alias>]`）。
`nostr`	映射	—
`plugin`	映射	—	WASM 通道插件实例（`[channels.plugin.<alias>]`）。
`qq`	映射	—	QQ Official Bot 渠道实例（`[channels.qq.<alias>]`）。
`reddit`	映射	—	Reddit channel 实例（`[channels.reddit.<alias>]`）。
`session_backend`	字符串	`"sqlite"`	会话持久化后端：`"jsonl"`（旧版）或 `"sqlite"`（新默认值）。
`session_persistence`	bool	`true`	将频道会话历史持久化到 JSONL 文件，以便会话得以保留
`session_ttl_hours`	整数	`0`	自动归档超过此小时数的陈旧会话。`0` 表示禁用。默认值：`0`。
`show_tool_calls`	bool	`false`	是否发送工具调用通知消息（例如 `🔧 web_search_tool: …`）
`signal`	映射	—	Signal 通道实例（`[channels.signal.<alias>]`）。
`slack`	映射	—	Slack bot channel 实例（`[channels.slack.<alias>]`）。
`telegram`	映射	—	Telegram bot 频道实例（`[channels.telegram.<alias>]`）。
`twitch`	映射	—	Twitch 聊天频道实例（`[channels.twitch.<alias>]`）。
`twitter`	映射	—	X/Twitter 频道实例（`[channels.twitter.<alias>]`）。
`voice_call`	映射	—	语音通话频道实例（`[channels.voice_call.<alias>]`）。
`voice_duplex`	映射	—	Voice duplex 实例（`[channels.voice_duplex.<alias>]`）。
`voice_wake`	映射	—	语音唤醒词检测通道实例（`[channels.voice_wake.<alias>]`）。
`webhook`	映射	—	Webhook 通道实例 (`[channels.webhook.<alias>]`)。
`wechat`	映射	—	WeChat 个人 iLink Bot channel 实例（`[channels.wechat.<alias>]`）。
`wecom`	映射	—	WeCom (WeChat Enterprise) Bot Webhook 渠道实例（`[channels.wecom.<alias>]`）。
`wecom_ws`	映射	—	WeCom AI Bot WebSocket 通道实例（`[channels.wecom_ws.<alias>]`）。
`whatsapp`	映射	—	WhatsApp 渠道实例（`[channels.whatsapp.<alias>]`）。

`claude_code`

Claude Code CLI 工具配置（[claude_code] 部分）。

将编码任务委派给 claude -p CLI。默认情况下，身份验证使用二进制自身的 OAuth 会话（Max 订阅）——除非 env_passthrough 包含 ANTHROPIC_API_KEY，否则不需要 API 密钥。

键	类型	默认	描述
`allowed_tools`	字符串数组	`["Read","Edit","Bash","Write"]`	Claude Code 工具，子进程被允许使用
`enabled`	bool	`false`	启用 `claude_code` 工具
`env_passthrough`	字符串数组	`[]`	传递给 claude 子进程的额外环境变量（例如用于 API 密钥计费的 ANTHROPIC_API_KEY）
`max_output_bytes`	整数	`2097152`	最大输出大小（以字节为单位，默认 2MB）
`system_prompt`	字符串？	`null`	附加到 Claude Code 调用中的可选系统提示词
`timeout_secs`	整数	`600`	最大执行时间（秒）（编码任务可能很耗时）

`claude_code_runner`

Claude Code 任务运行器配置（[claude_code_runner] 部分）。

在 tmux 会话中启动 Claude Code，带有将工具执行事件通过 POST 回传到 ZeroClaw 网关的 HTTP 钩子，并就地更新 Slack 消息，显示进度以及一个 SSH 交接链接。

键	类型	默认	描述
`enabled`	bool	`false`	启用 `claude_code_runner` 工具
`session_ttl`	整数	`3600`	会话在自动清理前的生存时间（秒）（默认：3600）
`ssh_host`	字符串？	`null`	用于会话接管链接的 SSH 主机（例如 “myhost.example.com”）
`tmux_prefix`	字符串	`"zc-claude-"`	tmux 会话名称前缀（默认值：“zc-claude-”）

`cloud_ops`

控制只读云迁移分析工具：IaC 评审、迁移评估、成本分析和架构评审。

键	类型	默认	描述
`cost_threshold_monthly_usd`	number	`100.0`	用于标记成本项的每月 USD 阈值。默认值：100.0。
`default_cloud`	字符串	`"aws"`	分析上下文的默认云 model_provider。默认值：“aws”。
`enabled`	bool	`false`	启用云操作工具。默认值：false。
`iac_tools`	字符串数组	`["terraform"]`	用于审核的受支持 IaC 工具。默认值：[`terraform`]。
`supported_clouds`	字符串数组	`["aws","azure","gcp"]`	支持的云模型提供商。默认：[`aws`, `azure`, `gcp`]。
`well_architected_frameworks`	字符串数组	`["aws-waf"]`	用于检查的 Well-Architected Frameworks。默认值：[`aws-waf`]。

`codex_cli`

Codex CLI 工具配置（[codex_cli] 部分）。

将编码任务委派给 codex exec CLI。默认使用该二进制自身的会话进行身份验证——除非 env_passthrough 包含 OPENAI_API_KEY，否则不需要 API 密钥。

键	类型	默认	描述
`enabled`	bool	`false`	启用 `codex_cli` 工具
`env_passthrough`	字符串数组	`[]`	传递给 codex 子进程的额外环境变量（例如 OPENAI_API_KEY）
`extra_args`	字符串数组	`[]`	附加到 `codex exec` 的提示词之前的额外 CLI 参数。
`max_output_bytes`	整数	`2097152`	最大输出大小（以字节为单位，默认 2MB）
`timeout_secs`	整数	`600`	最大执行时间（秒）（编码任务可能很耗时）

`composio`

Composio 托管的 OAuth 工具集成（[composio] 部分）。

通过 Composio 平台提供对 1000+ 个 OAuth 连接工具的访问。

键	类型	默认	描述
`api_key` 🔑	字符串？	`null`	Composio API 密钥（当 secrets.encrypt = true 时以加密形式存储）
`enabled`	bool	`false`	为 1000+ OAuth 工具启用 Composio 集成
`entity_id`	字符串	`"default"`	多用户设置的默认实体 ID

`conversational_ai`

Conversational AI agent builder 配置（[conversational_ai] 部分）。

状态：保留供将来使用。 此配置会被解析，但运行时尚未使用。设置 enabled = true 将产生启动警告。

键	类型	默认	描述
`analytics_enabled`	bool	`false`	启用会话分析跟踪。默认值：false（默认隐私）。
`auto_detect_language`	bool	`true`	自动从消息内容检测用户语言。默认值：true。
`conversation_timeout_secs`	整数	`1800`	会话超时时间（秒，因不活动）。默认值：1800。
`default_language`	字符串	`"en"`	会话的默认语言（BCP-47 标记）。默认值：“`en`”。
`enabled`	bool	`false`	启用对话式 AI 功能。默认值：false。
`escalation_confidence_threshold`	number	`0.3`	意图置信度低于此阈值时将触发升级。默认值：0.3。
`knowledge_base_tool`	字符串？	`null`	用于基于 RAG 的知识库检索的可选工具名称。
`max_conversation_turns`	整数	`50`	自动结束前的最大对话轮次。默认值：50。
`supported_languages`	字符串数组	`["en","de","fr","it"]`	支持的会话语言。默认：[`en`, `de`, `fr`, `it`]。

`cost`

成本跟踪和预算强制执行配置（[cost] 部分）。

键	类型	默认	描述
`allow_override`	bool	`false`	允许使用 `--override` 标志使请求超出预算（默认值：false）
`daily_limit_usd`	number	`10.0`	每日消费限额（USD）（默认值：10.00）
`enabled`	bool	`true`	启用成本跟踪（默认值：true）
`enforcement`	object	—	当达到预算限制时的成本强制执行行为配置。
`monthly_limit_usd`	number	`100.0`	美元月度消费上限（默认值：100.00）
`rates`	object	—	`[cost.rates]` — 顶层费率表命名空间。对应于
`track_per_agent`	bool	`true`	将每个记录的成本条目标记上其来源代理别名，以便
`warn_at_percent`	整数	`80`	当支出达到限额的此百分比时发出警告（默认值：80）

`cost.enforcement`

当达到预算限制时的成本强制执行行为配置。

键	类型	默认	描述
`mode`	字符串	`"warn"`	执行模式：“warn”、“block”或“route_down”。
`reserve_percent`	整数	`10`	为关键操作预留此预算百分比。
`route_down_model`	字符串？	`null`	在预算超出时路由到的模型提示（与 “route_down” 模式一起使用）。

`cost.rates`

[cost.rates] — 顶级费率表命名空间。其结构与 [providers.*] 保持一致，因此这里的每个子节都指向与其对应的 [providers.*] 配置项所配置的同类资源。

键	类型	默认	描述
`providers`	object	—	`[cost.rates.providers.*]` — 提供程序形状的费率表。每个字段
`tools`	映射	`{}`	`[cost.rates.tools.<name>]` — 工具的每次调用费率，用于

[cost.rates.providers.*] — provider 形态的费率表。这里的每个字段都与 [providers.*] 上对应的字段一一对应，只是将末尾的别名段替换为该费率所定价的资源。内部的类型化包装器承载按 provider 类型划分的槽位布局和自身分发（其槽位列表是唯一事实来源，并通过 [crate::providers] 中的 for_each_*_provider_slot! 宏与其 providers 对应项共享）。

键	类型	默认	描述
`models`	object	—	`[cost.rates.providers.models.<type>.<model>]` — 代币成本费率
`transcription`	object	—	`cost.rates.providers.transcription.<type>.<model>`
`tts`	object	—	`cost.rates.providers.tts.<type>.<voice>`

`cron`

声明式 cron 作业（[cron.<alias>]），按别名键控。

每个条目都是一个已命名的计划作业，会在 scheduler 启动时同步到数据库。子系统运行时开关（启用/禁用、补跑、运行历史保留）位于 [scheduler]。

`cron.<alias>`

一个声明式 cron 作业定义 ([cron.<alias>])。

存储在 Config.cron 中，以别名作为键。该 map 键充当稳定的作业 id。在调度器启动时同步到数据库，source = "declarative"，以将它们与通过 CLI 或 API 以命令式方式创建的作业区分开来。声明式配置在每次同步时优先：如果配置发生变化，数据库会更新以保持一致。命令式作业绝不会被同步删除。

键	类型	默认	描述
`allowed_tools`	string[]?	`null`	代理任务的可选工具名称允许列表。省略时，调度器
`command`	字符串？	`null`	运行的 Shell 命令（当 `job_type = "shell"` 时必需）。
`delivery`	object	—	声明式 cron 作业的投递配置。
`enabled`	bool	`true`	作业是否启用。默认值：`true`。
`job_type`	字符串	`"shell"`	作业类型：`"shell"`（默认）或 `"agent"`。
`model`	字符串？	`null`	用于代理作业的模型覆盖。
`name`	字符串？	`null`	人类可读名称。
`prompt`	字符串？	`null`	Agent 提示词（在 `job_type = "agent"` 时必需）。
`schedule`	表格	—	用于声明式 cron 作业的 schedule 变体。
`session_target`	字符串？	`null`	Session 目标：`"isolated"`（默认）或 `"main"`。
`shell_output_format`	表格	—	shell cron 作业 stdout 的输出格式。
`uses_memory`	bool	`true`	在此代理任务运行前，是否回忆并注入记忆上下文。

`cron.<alias>.delivery`

声明式 cron 作业的投递配置。

键	类型	默认	描述
`best_effort`	bool	`true`	尽力投递。默认值：`true`。
`channel`	字符串？	`null`	要发送到的通道，格式为 `<type>.<alias>`（例如
`mode`	字符串	`"none"`	交付模式：`"none"` 或 `"announce"`。
`thread_id`	字符串？	—	可选的线程/对话标识符，会携带到出站发送中。
`to`	字符串？	`null`	目标/接收方标识符。

`data_retention`

数据保留和清除配置（[data_retention] 部分）。

键	类型	默认	描述
`categories`	字符串数组	`[]`	将保留强制限制为特定数据类别（空 = 全部）。
`dry_run`	bool	`false`	预览将要删除的内容，但不要实际移除任何东西。
`enabled`	bool	`false`	启用 `data_management` 工具。
`retention_days`	整数	`90`	清除资格前要保留的数据天数。

`delegate`

默认超时值的全局委托工具配置。

键	类型	默认	描述
`agentic_timeout_secs`	整数	`300`	代理子代理运行的默认超时时间（秒）。
`timeout_secs`	整数	`120`	非代理子代理 `model_provider` 调用的默认超时时间（秒）。

`embedding_routes`

Embedding 路由规则 — 将 hint:<name> 路由到嵌入请求的特定 model_provider + model 组合。

`enroll`

证书注册端点（[enroll]）。

专用且范围严格受限的引导入口，certless 客户端通过它获取其第一张证书。它采用服务器认证的 TLS（守护进程证明自身身份；客户端通过配对短认证字符串确认 CA），并设有配对码门控。它严格只接受一种操作：提交 CSR，接收签名证书 + CA 链 + 中继配置。这绝不是始终使用 mTLS 的 RPC 平面的回退路径（该平面始终保持双向认证，不存在可弱化的路径）；它是一个独立的最小化端点，采用自身的认证模型。CA 由守护进程持有，因此该端点无需网关即可工作。

键	类型	默认	描述
`allow_unpaired_enrollment`	字符串	`""`	为未来的迁移流程保留。首个 FOSS 版本会拒绝任何
`bind`	字符串	`"0.0.0.0"`	注册端点绑定的地址。
`enabled`	bool	`false`	启用注册端点（默认值：false）。需要启用 `[wss]`
`port`	整数	`9782`	注册端点监听的端口。

`escalation`

升级路由配置（[escalation] 部分）。

控制在调用 escalate_to_human 且紧急级别为高或严重时，哪些渠道接收告警通知。渠道通过名称标识（例如 "telegram"、"slack"）。告警按尽力而为的方式发送，不会阻塞升级。

键	类型	默认	描述
`alert_channels`	字符串数组	`[]`	用于告警高/严重升级的频道名称（默认：空）。

`eval`

代理评估框架（[eval]）的配置，通过 zeroclaw eval 命令暴露。它不同于 [agent.eval]，后者是循环内的响应质量评分器。

键	类型	默认	描述
`mode`	字符串	`"replay"`	当省略 `--mode` 时使用的默认执行模式（`replay` 或 `live`）。
`suite_dir`	字符串	`"evals"`	在省略 `--suite` 时使用的 `*.json` 跟踪夹具的默认目录。

`file_download`

独立文件下载工具配置 ([file_download])。

当 url 设置为非空值时，会注册一个 file_download 工具，该工具从已配置的端点 GET 文件并将其写入代理的工作区文件系统。LLM 只提供文档标识符和相对于工作区的目标路径；端点 URL 仅来自此配置，且从不受模型控制。响应字节会流式写入磁盘，且不会加载到模型上下文中。

当 url 为 None 或为空时，工具不会被注册。

键	类型	默认	描述
`headers` 🔑	映射	`{}`	附加到每个下载请求的静态 HTTP 标头——通常是一个
`max_file_size_bytes`	整数	`26214400`	字节单位的最大下载大小。在流式传输期间强制执行：传输
`timeout_secs`	整数	`120`	请求超时时间（秒）。默认值：120。
`url`	字符串？	`null`	下载端点 URL。工具在其为 `None` 或为空时会被禁用。

`file_upload`

独立文件上传工具配置（[file_upload]）。

当 url 设置为非空值时，会注册一个 file_upload 工具，该工具通过 multipart/form-data 将来自代理本地文件系统的文件 POST 到已配置的端点。LLM 只提供文件路径；宿主读取字节并上传它们，而不会将文件内容包含在模型上下文中。

当 url 为 None 或为空时，工具不会被注册。

键	类型	默认	描述
`field_name`	字符串	`"file"`	文件部分的 multipart 表单字段名称。默认值：`file`。
`headers` 🔑	映射	`{}`	附加到每个上传请求的静态 HTTP 标头。与以下内容具有相同的结构
`max_file_size_bytes`	整数	`26214400`	字节中的最大文件大小。更大的文件会在任何操作之前被拒绝。
`method`	字符串	`"POST"`	HTTP 方法。仅接受 `POST`（默认）和 `PUT`。
`timeout_secs`	整数	`60`	请求超时时间（秒）。默认值：60。
`url`	字符串？	`null`	上传端点 URL。当此项为 `None` 或为空时，工具将被禁用。

`file_upload_bundle`

独立多文件捆绑上传工具配置（[file_upload_bundle]）。

当 url 设置为非空值时，会注册一个 file_upload_bundle 工具，该工具将代理本地文件系统中的 N 个文件作为单个 multipart/form-data 请求 POST 到配置的端点。LLM 只提供文件路径；主机读取字节。

当 url 为 None 或为空时，工具不会被注册。

键	类型	默认	描述
`field_name`	字符串	`"file"`	每个文件部分都重复使用的 multipart 表单字段名。默认值：`file`。
`headers` 🔑	映射	`{}`	附加到每个上传请求的静态 HTTP 标头。
`max_file_size_bytes`	整数	`10485760`	每个文件的最大大小（字节）。默认值：10 MiB。
`max_files`	整数	`16`	每次调用的最大文件数。默认值：16。
`max_response_body_bytes`	整数	`4096`	从上传端点读取的响应体最大字节数。
`max_total_size_bytes`	整数	`33554432`	单次调用中所有文件的最大累计大小。默认值：32 MiB。
`method`	字符串	`"POST"`	HTTP 方法。仅接受 `POST`（默认）和 `PUT`。
`timeout_secs`	整数	`120`	请求超时时间（秒）。默认值：120。
`url`	字符串？	`null`	上传端点 URL。当此项为 `None` 或为空时，工具将被禁用。

`gateway`

网关服务器配置（[gateway] 部分）。

控制 webhook 和配对端点的 HTTP 网关。

键	类型	默认	描述
`allow_public_bind`	bool	`false`	允许在不使用隧道的情况下绑定到非 localhost（默认：false）
`allow_remote_admin`	bool	`false`	允许经过身份验证的远程调用方使用管理端点，这些端点是
`allow_self_upgrade`	bool	`false`	允许触发自升级（通过 `zeroclaw update` 进行二进制替换）从
`check_updates`	bool	`true`	轮询 GitHub 以检查较新的发布版本，并显示“有可用更新”指示器
`host`	字符串	`"127.0.0.1"`	网关主机（默认：127.0.0.1）
`idempotency_max_keys`	整数	`10000`	内存中保留的最大不同幂等键数量。
`idempotency_ttl_secs`	整数	`300`	webhook 幂等键的 TTL。
`long_running_request_timeout_secs`	整数	`600`	`POST /api/cron/{id}/run` 的 HTTP 请求超时时间（秒），用于 `POST /api/cron/{id}/run`，当
`pair_rate_limit_per_minute`	整数	`10`	每个客户端密钥每分钟的 `/pair` 请求上限。
`paired_tokens` 🔑	字符串数组	`[]`	成对的 bearer 令牌（自动管理，不由用户编辑）
`pairing_dashboard`	object	—	配对仪表板配置（`[gateway.pairing_dashboard]`）。
`path_prefix`	字符串？	`null`	用于反向代理部署的可选 URL 路径前缀。
`port`	整数	`42617`	网关端口（默认值：42617）
`rate_limit_max_keys`	整数	`10000`	网关限流器映射所跟踪的最大不同客户端密钥数。
`request_timeout_secs`	整数	`30`	网关路由的 HTTP 请求超时（秒），不包括 the
`require_pairing`	bool	`true`	在接受请求之前需要配对（默认值：true）
`session_persistence`	bool	`true`	将网关 WebSocket 聊天会话持久化到 SQLite。默认值：true。
`session_ttl_hours`	整数	`0`	自动归档超过 N 小时的陈旧网关会话。0 = 禁用。默认值：0。
`tls`	object	—	网关服务器的 TLS 配置（`[gateway.tls]`）。
`trust_forwarded_headers`	bool	`false`	信任代理转发的客户端 IP 头（`X-Forwarded-For`、`X-Real-IP`）。
`web_dist_dir`	字符串？	`null`	Web 仪表盘的 `dist` 目录路径。设置后，网关
`webhook_rate_limit_per_minute`	整数	`60`	每个客户端密钥每分钟最多 `/webhook` 请求。
`webhook_secret` 🔑	字符串？	`null`	网关通用 `POST /webhook` 的可选共享密钥，以及
`websocket_ping_interval_secs`	整数	`30`	每 N 秒发送 WebSocket ping 帧，以保持仪表板聊天连接处于活动状态

`gateway.pairing_dashboard`

配对仪表板配置（[gateway.pairing_dashboard]）。

键	类型	默认	描述
`code_length`	整数	`8`	配对代码长度（默认：8）
`code_ttl_secs`	整数	`3600`	待配对代码的生存时间（秒）（默认值：3600）
`lockout_secs`	整数	`300`	达到最大尝试次数后的锁定时长（秒）（默认：300）
`max_failed_attempts`	整数	`5`	锁定前允许的最大配对失败尝试次数（默认值：5）
`max_pending_codes`	整数	`3`	最大并发待处理配对代码数（默认值：3）

`gateway.tls`

网关服务器的 TLS 配置（[gateway.tls]）。

键	类型	默认	描述
`cert_path`*	字符串	—	PEM 编码的服务器证书文件路径。
`client_auth`	object	—	客户端证书认证（mTLS）配置（`[gateway.tls.client_auth]`）。
`enabled`	bool	`false`	为网关启用 TLS（默认值：false）。
`key_path`*	字符串	—	PEM 编码的服务器私钥文件路径。

`gateway.tls.client_auth`

客户端证书认证（mTLS）配置（[gateway.tls.client_auth]）。

键	类型	默认	描述
`ca_cert_path`	字符串	`""`	用于验证客户端证书的 PEM 编码 CA 证书路径。
`crl_path`	字符串	`""`	已撤销指纹列表的可选路径（每行一个 SHA-256 十六进制值）。A
`enabled`	bool	`false`	启用客户端证书验证（默认值：false）。
`pinned_certs`	字符串数组	`[]`	用于证书固定的可选 SHA-256 指纹。
`require_client_cert`	bool	`true`	拒绝未提供有效客户端证书的连接（默认值：true）。

`gemini_cli`

Gemini CLI 工具配置（[gemini_cli] 部分）。

将编码任务委派给 gemini -p CLI。默认情况下，身份验证使用该二进制的自身会话——除非 env_passthrough 包含 GOOGLE_API_KEY，否则不需要 API 密钥。

键	类型	默认	描述
`enabled`	bool	`false`	启用 `gemini_cli` 工具
`env_passthrough`	字符串数组	`[]`	传递给 gemini 子进程的额外环境变量（例如 GOOGLE_API_KEY）
`max_output_bytes`	整数	`2097152`	最大输出大小（以字节为单位，默认 2MB）
`timeout_secs`	整数	`600`	最大执行时间（秒）（编码任务可能很耗时）

`google_workspace`

Google Workspace CLI (gws) 工具配置（[google_workspace] 部分）。

默认值

enabled: false（除非显式选择启用，否则工具不会注册）。
allowed_services：空向量，这将授予对完整默认服务集的访问权限：drive、sheets、gmail、calendar、docs、slides、tasks、people、chat、classroom、forms、keep、meet、events。
allowed_operations：空向量，会保留允许在允许的服务集合下使用任意资源/方法的旧版行为。
credentials_path: None（使用默认的 gws 凭据发现）。
default_account: None（使用 gws 活动账户）。
rate_limit_per_minute: 60.
timeout_secs: 30.
audit_log: false.

兼容性

完全省略 [google_workspace] 部分的配置会被视为 GoogleWorkspaceConfig::default()（已禁用，允许所有默认值）。添加该部分只是显式启用，不会影响其他配置部分。

回滚 / 迁移

要还原，请从配置文件中移除 [google_workspace] 部分（或将 enabled = false）。不需要数据迁移；该工具只是停止注册。

键	类型	默认	描述
`allowed_operations`	object[]	`[]`	限制代理可以访问的资源/方法组合。
`allowed_services`	字符串数组	`[]`	限制代理可访问的 Google Workspace 服务。
`audit_log`	bool	`false`	启用对每次 `gws` 调用（service、resource、
`credentials_path`	字符串？	`null`	服务账号 JSON 或 OAuth 客户端凭据文件的路径。
`default_account`	字符串？	`null`	传递给 `gws --account` 的默认 Google 账户邮箱。
`enabled`	bool	`false`	启用 `google_workspace` 工具。默认值：`false`。
`rate_limit_per_minute`	整数	`60`	每分钟允许的 `gws` API 调用最大次数。默认值：`60`。
`timeout_secs`	整数	`30`	命令执行超时时间（秒）。默认值：`30`。

`hardware`

用于物理世界交互的向导式硬件配置。

键	类型	默认	描述
`baud_rate`	整数	`115200`	串行链路上协商的波特率。115200 与常见的 Arduino / ESP32 引导加载程序默认值一致；当你的固件明确支持更快的速率并且你需要更高吞吐量时，提升到 230400+。
`enabled`	bool	`false`	启用对直接硬件控制的支持——GPIO 引脚、USB 连接的微控制器（Arduino、ESP32、Nucleo）或 SWD/JTAG 调试探针。若仅用于软件，请不要启用；在未正确配置传输方式的情况下启用它不会产生任何作用。
`probe_target`	字符串？	`null`	`transport = probe` 的目标芯片标识符（例如 `STM32F401RE`、`nRF52840_xxAA`）。会直接传递给 probe-rs 用于烧录/调试操作；必须与 probe-rs 可识别的芯片匹配。
`serial_port`	字符串？	`null`	`serial` 传输的 TTY 路径——例如 Linux 上的 `/dev/ttyACM0`、macOS 上的 `/dev/tty.usbmodem1`、Windows 上的 `COM3`。其他传输会忽略。
`transport`	`None` \| `Native` \| `Serial` \| `Probe`	—	硬件传输模式。
`workspace_datasheets`	bool	`false`	将工作区中的预转换 `.md` 和 `.txt` 数据表索引到

`heartbeat`

用于周期性健康 ping 的 Heartbeat 配置（[heartbeat] 部分）。

键	类型	默认	描述
`adaptive`	bool	`false`	启用自适应间隔，在失败时退避并在成功时加快。
`agent`	字符串	`""`	配置代理别名，心跳 worker 以该别名运行。必需
`deadman_channel`	字符串？	`null`	死手开关警报的频道（例如 `telegram`）。回退到
`deadman_timeout_minutes`	整数	`0`	以分钟为单位的死手开关超时时间。如果心跳未曾跳动
`deadman_to`	字符串？	`null`	用于死信开关警报的收件人。回退到 `to`。
`enabled`	bool	`false`	启用周期性心跳 ping。默认值：`false`。启用后，
`interval_minutes`	整数	`30`	心跳 ping 之间的间隔（分钟）。最小值：`1`。默认值：`30`。
`load_session_context`	bool	`false`	在每次 heartbeat 任务执行前加载 channel 会话历史，以便
`max_interval_minutes`	整数	`120`	自适应模式退避时的最大间隔（分钟）。默认值：`120`。
`max_run_history`	整数	`100`	保留的 heartbeat 运行历史记录最大数量。默认值：`100`。
`message`	字符串？	`null`	当 `HEARTBEAT.md` 没有任务条目时的可选回退任务文本。
`min_interval_minutes`	整数	`5`	启用自适应模式时的最小间隔（分钟）。默认值：`5`。
`target`	字符串？	`null`	心跳输出的可选传递渠道（例如：`telegram`）。
`task_timeout_secs`	整数	`600`	单个代理调用允许的最大全局时钟秒数
`to`	字符串？	`null`	可选的送达收件人/聊天标识符（当 `target` 为时必需）
`two_phase`	bool	`true`	启用两阶段 heartbeat：阶段 1 向 LLM 询问是否运行，阶段 2

`hooks`

键	类型	默认	描述
`builtin`	object	—
`enabled`	bool	`true`	启用生命周期钩子执行。

`hooks.builtin`

键	类型	默认	描述
`command_logger`	bool	`false`	启用 command-logger hook（记录工具调用以用于审计）。
`webhook_audit`	object	—	webhook-audit 内置钩子的配置。

`hooks.builtin.webhook_audit`

webhook-audit 内置钩子的配置。

每当工具调用匹配已配置的模式之一时，向外部端点发送带有 JSON 正文的 HTTP POST。适用于集中审计日志记录、SIEM 摄取或合规流水线。

键	类型	默认	描述
`enabled`	bool	`false`	启用 webhook-audit hook。默认值：`false`。
`include_args`	bool	`false`	在审计载荷中包含工具调用参数。默认：`false`。
`max_args_bytes`	整数	`4096`	单个中包含的序列化参数的最大大小（以字节为单位）
`tool_patterns`	字符串数组	`[]`	用于审计工具名称的 glob 模式（例如 `["Bash", "Write"]`）。
`url`	字符串	`""`	将接收审计 POST 请求的目标 URL。

`http_request`

HTTP 请求工具配置（[http_request] 部分）。

域名过滤：allowed_domains 控制哪些主机可访问（对所有公共主机使用 ["*"]，这是默认设置）。如果 allowed_domains 为空，则拒绝所有请求。请求使用直接传输，以便将本地验证的 DNS 响应保持固定：启用的 environment 代理范围或适用于 tool.http_request 的运行时代理会被拒绝。托管范围之外的进程环境代理会发出警告并被忽略；连接失败时会指出被忽略的变量。

键	类型	默认	描述
`allow_private_hosts`	bool	`false`	允许向私有/LAN 主机（RFC 1918、环回地址、`.local`）发送请求。
`allowed_domains`	字符串数组	`["*"]`	HTTP 请求的允许域名（完全匹配或子域名匹配）
`allowed_private_hosts`	字符串数组	`[]`	明确允许放宽公共地址检查的私有/内部主机。
`enabled`	bool	`true`	为 API 交互启用 `http_request` 工具
`max_response_size`	整数	`1000000`	最大响应大小（以字节为单位，默认：1MB，0 = 不限）
`secrets` 🔑	映射	`{}`	用于 `auth_secret` 请求的命名授权密钥。
`timeout_secs`	整数	`30`	请求超时时间（秒）（默认值：30）

`image_gen`

独立图像生成工具配置（[image_gen]）。

启用后，会注册一个 image_gen 工具，通过 fal.ai 的同步 API（Flux / Nano Banana 模型）生成图像，并将其保存到工作区的 images/ 目录。

键	类型	默认	描述
`api_key_env`	字符串	`"FAL_API_KEY"`	保存 fal.ai API 密钥的环境变量名称。
`default_model`	字符串	`"fal-ai/flux/schnell"`	默认的 fal.ai 模型标识符。
`enabled`	bool	`false`	启用独立图像生成工具。默认值：false。

`jira`

Jira 集成配置（[jira]）。

当 enabled = true 时，注册 jira 工具，该工具可以获取工单、使用 JQL 搜索以及添加评论。需要 base_url 和 api_token（或 JIRA_API_TOKEN 环境变量）。

默认值

enabled: false
allowed_actions: ["get_ticket"] — 默认情况下为只读。添加 "search_tickets" 或 "comment_ticket" 以解锁它们。
timeout_secs: 30

认证

Jira Cloud 使用 HTTP Basic 认证：email + api_token。Jira Server/Data Center 使用 Bearer 令牌认证：省略 email 并将 api_token 设置为个人访问令牌。api_token 在静态存储时会加密；可在此处设置，或通过 JIRA_API_TOKEN 设置。

键	类型	默认	描述
`allowed_actions`	字符串数组	`["get_ticket"]`	代理被允许调用的操作。
`api_token` 🔑	字符串	`""`	Jira API 令牌。静态加密存储。回退到 `JIRA_API_TOKEN` 环境变量。
`base_url`	字符串	`""`	Atlassian 实例基础 URL，例如 `https://yourco.atlassian.net`。
`email`	字符串？	—	用于 Basic auth（Cloud）的 Jira 账户邮箱。
`enabled`	bool	`false`	启用 `jira` 工具。默认值：`false`。
`timeout_secs`	整数	`30`	请求超时时间（秒）。默认值：`30`。

`knowledge`

用于捕获和复用专业知识的知识图谱配置。

键	类型	默认	描述
`auto_capture`	bool	`false`	自动从对话中捕获知识。默认值：false。
`db_path`	字符串	`"/home/runner/.zeroclaw/knowledge.db"`	知识图谱 SQLite 数据库的路径。
`enabled`	bool	`false`	启用知识图谱工具。默认值：false。
`max_nodes`	整数	`100000`	知识节点的最大数量。默认值：100000。
`suggest_on_query`	bool	`true`	主动为查询建议相关知识。默认：true。

`knowledge_bundles`

命名知识包（[knowledge_bundles.<alias>]）。

`knowledge_bundles.<alias>`

命名知识包 ([knowledge_bundles.<alias>])。

一组可复用的知识来源（文档、URL 或 RAG 语料库路径），可通过别名附加到代理上。

键	类型	默认	描述
`sources`	字符串数组	`[]`	要包含在此知识包中的路径或 URL。
`tags`	字符串数组	`[]`	用于在 bundle 内筛选或分类来源的标签。

`link_enricher`

用于入站频道消息的自动链接理解（[link_enricher]）。

启用后，传入消息中的 URLs 会自动抓取并生成摘要。该摘要会在代理处理消息之前附加到消息前面，从而在不显式调用工具的情况下为 LLM 提供关于链接页面的上下文。

键	类型	默认	描述
`enabled`	bool	`false`	启用 link enricher 管道阶段（默认：false）
`max_links`	整数	`3`	每条消息要获取的链接最大数量（默认：3）
`timeout_secs`	整数	`10`	每个链接的抓取超时时间（秒）（默认值：10）

`linkedin`

LinkedIn 集成配置（[linkedin] 部分）。

启用后，linkedin 工具会注册到代理工具面上。需要工作区 .env 文件中的 LINKEDIN_* 凭据。

键	类型	默认	描述
`api_version`	字符串	`"202602"`	LinkedIn REST API 版本头（YYYYMM 格式）。
`content`	object	—	LinkedIn 自动发布的内容策略配置（`[linkedin.content]`）。
`enabled`	bool	`false`	启用 LinkedIn 工具。
`image`	object	—	LinkedIn 帖子的图像生成配置（`[linkedin.image]`）。

`linkedin.content`

LinkedIn 自动发布的内容策略配置（[linkedin.content]）。

代理通过 linkedin get_content_strategy 动作读取此内容，以了解要检查哪些动态、要重点突出的仓库，以及如何撰写帖子。

键	类型	默认	描述
`github_repos`	字符串数组	`[]`	要突出显示的 GitHub 仓库（格式：`owner/repo`）。
`github_users`	字符串数组	`[]`	用于引用其公开活动的 GitHub 用户名。
`instructions`	字符串	`""`	针对 AI 代理的自由格式发布说明。
`persona`	字符串	`""`	专业人物简介（姓名、角色、专长）。
`rss_feeds`	字符串数组	`[]`	用于监控以获取主题灵感的 RSS feed URLs（仅标题）。
`topics`	字符串数组	`[]`	帖子主题的专业领域和兴趣领域。

`linkedin.image`

LinkedIn 帖子的图像生成配置（[linkedin.image]）。

键	类型	默认	描述
`card_accent_color`	字符串	`"#0A66C2"`	备用卡片的强调色（CSS 十六进制）。
`dalle`	object	—	OpenAI DALL-E 设置（`[linkedin.image.dalle]`）。
`enabled`	bool	`false`	为帖子启用图像生成。
`fallback_card`	bool	`true`	当所有 AI model_providers 失败时，生成一个带品牌标识的 SVG 文本卡片。
`flux`	object	—	Flux (fal.ai) 图像生成设置（`[linkedin.image.flux]`）。
`imagen`	object	—	Google Imagen (Vertex AI) 设置 (`[linkedin.image.imagen]`)。
`providers`	字符串数组	`["stability","imagen","dalle","flux"]`	ModelProvider 优先级顺序。按顺序尝试；首次成功即为结果。
`stability`	object	—	Stability AI 图像生成设置（`[linkedin.image.stability]`）。
`temp_dir`	字符串	`"linkedin/images"`	生成图像的临时目录，相对于工作区。

`linkedin.image.dalle`

OpenAI DALL-E 设置（[linkedin.image.dalle]）。

键	类型	默认	描述
`api_key_env`	字符串	`"OPENAI_API_KEY"`	持有 OpenAI API 密钥的环境变量名称。
`model`	字符串	`"dall-e-3"`	DALL-E 模型标识符。
`size`	字符串	`"1024x1024"`	图像尺寸。

`linkedin.image.flux`

Flux (fal.ai) 图像生成设置（[linkedin.image.flux]）。

键	类型	默认	描述
`api_key_env`	字符串	`"FAL_API_KEY"`	保存 fal.ai API 密钥的环境变量名称。
`model`	字符串	`"fal-ai/flux/schnell"`	Flux 模型标识符。

`linkedin.image.imagen`

Google Imagen (Vertex AI) 设置 ([linkedin.image.imagen])。

键	类型	默认	描述
`api_key_env`	字符串	`"GOOGLE_VERTEX_API_KEY"`	保存 API 密钥的环境变量名称。
`project_id_env`	字符串	`"GOOGLE_CLOUD_PROJECT"`	Google Cloud 项目 ID 的环境变量。
`region`	字符串	`"us-central1"`	Vertex AI 区域

`linkedin.image.stability`

Stability AI 图像生成设置（[linkedin.image.stability]）。

键	类型	默认	描述
`api_key_env`	字符串	`"STABILITY_API_KEY"`	保存 API 密钥的环境变量名称。
`model`	字符串	`"stable-diffusion-xl-1024-v1-0"`	稳定性模型标识符。

`locale`

工具描述的区域设置（例如 "en"、"zh-CN"）。

设置后，系统提示中显示的工具描述会从 Fluent .ftl 区域设置文件中加载。若不可用，则回退到内置英文，再回退到硬编码描述。

如果省略或为空，则会从主机系统的区域设置自动检测语言环境（如果无法确定，则默认为 "en"）。

`mcp`

外部 MCP 客户端配置（[mcp] 部分）。

键	类型	默认	描述
`deferred_loading`	bool	`false`	通过 `tool_search` 按需加载 MCP 工具 schema，而不是提前加载
`enabled`	bool	`true`	启用 MCP 工具加载。
`servers`	object[]	`[]`	已配置 MCP 服务器。`#[nested]` 注解使宏

`mcp_bundles`

命名 MCP 服务器捆绑包（[mcp_bundles.<alias>]）。

`mcp_bundles.<alias>`

命名 MCP 服务器包（[mcp_bundles.<alias>]）。

授予代理的一组可重用 MCP 服务器，代理通过 agents.<alias>.mcp_bundles 中的别名引用该 bundle。服务器 ID 会按 name 与 [mcp.servers] 进行匹配。默认情况下解析是安全的（参见 Config::mcp_servers_for_bundles）：没有匹配服务器的 ID 不授予任何内容，并且 exclude 在代理引用的每个 bundle 中都优先于 servers。

键	类型	默认	描述
`exclude`	字符串数组	`[]`	从授权中移除的 MCP server IDs。拒绝优先：此处列出的名称是
`servers`	字符串数组	`[]`	由此捆绑授予的 MCP server ID（`[mcp.servers].name`）。

`media_pipeline`

自动媒体理解流水线配置（[media_pipeline]）。

启用后，带有媒体附件的入站频道消息会在到达代理之前进行预处理：音频会被转写，图像会被标注，视频会被总结。

键	类型	默认	描述
`describe_images`	bool	`true`	在启用具备视觉能力的模型时添加图像描述。
`enabled`	bool	`false`	媒体管线的总开关（默认：false）。
`summarize_video`	bool	`true`	总结视频附件（占位符——需要外部 API）。
`transcribe_audio`	bool	`true`	使用配置的 transcription model_provider 转录音频附件。

`memory`

内存后端配置（[memory] 部分）。

控制会话记忆存储、嵌入、混合搜索、响应缓存以及记忆快照/还原。特定于后端的连接设置位于 [storage.<backend>.<alias>]；此部分通过 backend 点式引用选择要使用的存储实例。

键	类型	默认	描述
`archive_after_days`	整数	`7`	在经过这么多天后，将 daily/session 文件移动到归档目录。在不删除历史的情况下，保持热工作集较小。
`audit_enabled`	bool	`false`	启用内存操作的审计日志记录。
`audit_retention_days`	整数	`30`	审计条目的保留天数（默认值：30）。
`auto_hydrate`	bool	`true`	在 brain.db 缺失时从 MEMORY_SNAPSHOT.md 自动恢复
`auto_reindex_on_identity_change`	bool	`false`	在启动时检测到嵌入提供方/模型/维度发生变更后，在后台自动重新嵌入所有记忆（在过期向量已清除之后）。这会为每条记忆消耗一次嵌入 API 调用，因此默认关闭——对于大型存储请保持关闭，并改为显式运行 `zeroclaw memory reindex`。
`auto_save`	bool	`true`	将你告诉 ZeroClaw 的内容自动保存到记忆中作为对话历史——智能体自己的回复不会被保存。如果你希望记忆中只保留你通过 memory 工具明确记录的内容，请关闭此功能。
`backend`	字符串	`"sqlite"`	指向活动存储实例的点式引用：`<backend>.<alias>`
`candidate_multiplier`	整数	`4`	在混合/重排裁剪前，候选池相对于最终召回上限的倍数。
`chunk_max_tokens`	整数	`512`	文档分割的每个块的最大 token 数
`conflict_supersede_enabled`	bool	`true`	在接线后启用可逆的 supersede soft-hide 机制。
`conflict_threshold`	number	`0.85`	用于冲突检测的余弦相似度阈值（0.0–1.0）。
`consolidation_extract_facts`	bool	`false`	同时从每个合并的对话轮次中提取原子性持久事实并存储
`conversation_retention_days`	整数	`30`	从数据库中删除早于此天数的会话行（仅 sqlite 后端）。年龄按 `updated_at`（最后写入时间）计算。0 = 永久保留。
`core_max_bytes`	整数	`0`	预算压缩前的最大 Core 字节数。0 = 无上限。
`core_max_rows`	整数	`0`	预算压缩前的最大 Core 行数。0 = 无界。
`core_retention_days`	整数	`0`	从数据库中删除早于这么多天的核心记忆行。年龄按 `created_at`（首次写入时间）计算。在当前的 SQLite upsert 下，回忆和普通重写都不会刷新 `created_at`，因此核心保留期是从首次写入开始计算的绝对年龄上限。若要保留持久的核心记忆，请将其设置为一个足够大的窗口；或者保持 0 = 永久保留。
`daily_max_rows`	整数	`0`	预算压缩前的最大 Daily 行数。0 = 无上限。
`daily_retention_days`	整数	`0`	从数据库中删除早于这么多天的 daily memory 行。年龄按 `updated_at`（最后写入时间）计算。0 = 永久保留。
`dedup_action`	表格	—	内存条目的写入时重复处理策略。
`dedup_jaccard_threshold`	number	`0.8`	用于纯文本重复检测的 Jaccard 阈值。
`dedup_on_write`	bool	`false`	启用写入时近似重复检测。
`default_namespace`	字符串	`"default"`	内存条目的默认命名空间。
`embedding_api_key` 🔑	字符串？	—	嵌入端点的可选 API key。设置后，嵌入调用将使用此 key，而不是继承种子模型提供方的 key——从而使 embeddings 与聊天模型解耦。当聊天模型运行在不提供可用嵌入凭据的提供方上（例如仅支持 OAuth 的提供方），而 embeddings 仍需使用其自己的 key 继续访问 `openai`/`custom:` 端点时，请使用它。留空则继承种子提供方的 key（向后兼容的默认值）。
`embedding_cache_size`	整数	`10000`	LRU 驱逐前的最大嵌入缓存条目数
`embedding_dimensions`	整数	`1536`	嵌入模型生成的向量宽度——必须与该模型的原生维度一致，否则向量将无法正确存储。请在 model_provider 的模型页面上查找该数值。
`embedding_model`	字符串	`"text-embedding-3-small"`	嵌入模型标识符 — 必须与您所选 embedding model_provider 提供的模型匹配（例如 OpenAI 的 `text-embedding-3-small`）。更改此项会使现有嵌入失效：系统会在启动时检测到变更并自动清除过时向量；运行 `zeroclaw memory reindex` 以重新嵌入（或设置 `auto_reindex_on_identity_change`）。
`embedding_provider`	字符串	`"none"`	语义搜索的嵌入向量来源。`none` = 仅关键词检索（无 API 调用，无向量成本）；`openai` = OpenAI 的嵌入 API；`custom:URL` = 任何兼容 OpenAI 的嵌入端点（LiteLLM、本地网关等）。
`evict_order`	表格	—	内存预算驱逐顺序。
`fts_early_return_score`	number	`0.85`	保留 (0.0-1.0)：超过此 FTS 分数时，召回将跳过
`hygiene_enabled`	bool	`true`	运行定期清理流程，归档过期的每日/会话文件并强制执行保留窗口。保持开启，除非你想自行管理清理。
`importance_weight`	number	`0.2`	用于召回混合的重要性权重。
`keyword_weight`	number	`0.3`	在 `search_mode = hybrid` 时，BM25（关键词）重叠的计分权重有多大。将其调高到接近 1.0 可用于精确术语匹配；当释义式表达也应获得较高分数时，则将其调低。
`min_relevance_score`	number	`0.4`	用于将记忆包含在上下文中的最低混合分数（0.0–1.0）。
`mmr_lambda`	number	`0.7`	MMR 相关性与多样性的权重，其中 1.0 表示仅考虑相关性。
`pin_min_importance`	number	`1.01`	将条目固定到此重要性及以上。>1.0 表示已禁用。
`pin_namespaces`	字符串数组	`[]`	受预算驱逐保护的命名空间。
`policy`	object	—	内存策略配置（`[memory.policy]` 部分）。
`purge_after_days`	整数	`30`	在这么多天后永久删除已归档文件。如果您需要长期历史记录，请设置较高值；如出于隐私 / 磁盘空间原因，请设置较低值。
`recency_weight`	number	`0.1`	召回混合所使用的时效性权重。
`rerank_enabled`	bool	`false`	启用召回重排序阶段：将检索分数与重要性融合
`rerank_strategy`	字符串	`"none"`	高级重排序策略。有效值：“none”、“mmr”。
`rerank_threshold`	整数	`5`	触发高级重排策略所需的最小候选数量。
`response_cache_enabled`	bool	`false`	启用 LLM 响应缓存以避免为重复提示付费
`response_cache_hot_entries`	整数	`256`	两级响应缓存的内存中热缓存条目最大数（默认值：256）
`response_cache_max_entries`	整数	`5000`	缓存响应在触发 LRU 淘汰前的最大数量（默认值：5000）
`response_cache_ttl_minutes`	整数	`60`	缓存响应的 TTL（单位：分钟）（默认值：60）
`retrieval_stages`	字符串数组	`["fts","vector"]`	每个代理召回的检索阶段。目前只有 `"cache"` 处于激活状态：它
`search_mode`	表格	—	记忆回忆的搜索策略。
`snapshot_enabled`	bool	`false`	启用将核心记忆定期导出到 MEMORY_SNAPSHOT.md
`snapshot_on_hygiene`	bool	`false`	在卫生检查期间运行快照（由心跳驱动）
`types`	object	—	类型化内存配置（`[memory.types]` 部分）。
`vector_weight`	number	`0.7`	当 `search_mode = hybrid` 时，向量（语义）相似度的权重有多大。将其提高到 1.0 可更偏向基于含义的匹配；降低它则会更多依赖关键词重叠。

`memory.policy`

内存策略配置（[memory.policy] 部分）。

键	类型	默认	描述
`max_entries_per_category`	整数	`0`	每个类别的最大条目数（0 = 不限）。
`max_entries_per_namespace`	整数	`0`	每个命名空间的最大条目数（0 = 不受限制）。
`read_only_namespaces`	字符串数组	`[]`	只读的命名空间（写入会被拒绝）。
`redact_categories`	字符串数组	`["secret","api_key","private_key","email","phone"]`	当 `redact_on_write` 为 true 时应用的脱敏类别。
`redact_on_write`	bool	`false`	在持久化之前对已配置的机密/PII 类别进行编辑处理。
`retention_days_by_category`	映射	`{}`	按类别设置保留天数（覆盖全局设置）。键：`"core"`、`"daily"`、`"conversation"`。
`threat_scan`	字符串	`"on"`	可靠内存写入的内容扫描模式：“off”、“on” 或 “strict”。
`threat_scan_load_time`	bool	`true`	在召回/读取时重新扫描已存储的条目，并阻止返回已标记的条目。
`threat_scan_on_hit`	字符串	`"reject"`	写入时内容扫描匹配时的行为：“reject“或

`memory.types`

类型化内存配置（[memory.types] 部分）。

默认不改变行为：在新的 consolidation 写入中，enabled 控制 MemoryKind 分配，默认关闭；该切换安排在后续阶段执行。仅限 SQLite：启用后要求全局以及每个代理使用 sqlite memory backend（在配置加载时验证）。

键	类型	默认	描述
`enabled`	bool	`false`	为新的合并写入分配一等 MemoryKind。

`microsoft365`

通过 Microsoft Graph API 的 Microsoft 365 集成（[microsoft365] 部分）。

提供对 Outlook 邮件、Teams 消息、Calendar 事件、OneDrive 文件和 SharePoint 搜索的访问权限。

键	类型	默认	描述
`auth_flow`	字符串	`"client_credentials"`	认证流程：`"client_credentials"` 或 `"device_code"`
`client_id`	字符串？	`null`	Azure AD 应用程序（客户端）ID
`client_secret` 🔑	字符串？	`null`	Azure AD 客户端密钥（当 secrets.encrypt = true 时以加密方式存储）
`enabled`	bool	`false`	启用 Microsoft 365 集成
`scopes`	字符串数组	`["https://graph.microsoft.com/.default"]`	OAuth 请求范围
`tenant_id`	字符串？	`null`	Azure AD 租户 ID
`token_cache_encrypted`	bool	`true`	在磁盘上加密令牌缓存文件
`user_id`	字符串？	`null`	用户主体名称或“me”（用于委托流程）

`model_routes`

模型路由规则 — 将 hint:<name> 路由到特定的 model_provider + model 组合。

`multimodal`

多模态（图像）处理配置（[multimodal] 部分）。

隐私和成本说明

打印真实本地图片路径的工具结果（例如 shell 工具执行 ls /pictures 或 find . -name '*.png'）会被规范化为 [IMAGE:...] 标记，并以内联 base64 的形式嵌入到下一次提供方请求中。这意味着，之前一直保留在本地的图片字节，在被工具显式返回后会上传到已配置的提供方。

max_images（以及 trim_old_images LRU 策略）限制了每个请求的图像预算，但对包含个人或敏感图像的目录运行 shell 风格工具的操作者应注意上传语义。请参见 docs/book/src/contributing/privacy.md 了解项目的隐私立场。

键	类型	默认	描述
`allow_remote_fetch`	bool	`false`	允许获取远程图像 URL（http/https）。默认禁用。
`max_image_size_mb`	整数	`5`	在 base64 编码之前的最大图像负载大小（MiB）。
`max_image_turns`	整数	`0`	会话轮次中图像的最大保留时间。
`max_images`	整数	`4`	每个请求接受的图像附件最大数量。
`vision_model`	字符串？	`null`	路由到 vision model_provider 时使用的模型（例如 `"llava:7b"`）。
`vision_model_provider`	字符串？	`null`	用于视觉/图像消息的 ModelProvider 名称（例如 `"ollama"`）。

`nodes`

动态节点发现系统（[nodes]）的配置。

启用后，外部进程/设备可以通过 WebSocket 连接到 /ws/nodes，并在运行时公布它们的功能。

键	类型	默认	描述
`auth_token` 🔑	字符串？	`null`	用于节点身份验证的可选 bearer token。
`enabled`	bool	`false`	启用动态节点发现端点。
`max_nodes`	整数	`16`	最大并发节点连接数。
`mdns`	object	—	LAN 本地 mDNS 对等节点发现的配置（`[nodes.mdns]`）。

`nodes.mdns`

LAN 本地 mDNS 对等节点发现的配置（[nodes.mdns]）。

此配置仅控制发现行为。发布的网关端点会在启动时根据运行中网关的实际主机、端口和路径前缀派生，因此 [nodes.mdns] 不会重复网关的监听状态。

键	类型	默认	描述
`announce_interval_secs`	整数	`30`	此节点重新广播其存在状态的频率（以秒为单位）。
`enabled`	bool	`false`	启用 mDNS 本地对等端发现。
`max_peers`	整数	`16`	内存中保留的未经身份验证的 LAN 对等节点提示的最大数量。
`node_name`	字符串？	`null`	向 LAN 对等方通告的可读节点名称。默认为稳定的
`peer_ttl_secs`	整数	`90`	对等节点被驱逐前最后一次公告之后的秒数。

`notion`

Notion 集成配置（[notion]）。

当 enabled = true 时，代理会轮询 Notion 数据库中的待处理任务，并提供一个 notion 工具用于查询、读取、创建和更新页面。需要 api_key（或 NOTION_API_KEY 环境变量）和 database_id。

键	类型	默认
`api_key` 🔑	字符串	`""`
`database_id`	字符串	`""`
`enabled`	bool	`false`
`input_property`	字符串	`"Input"`
`max_concurrent`	整数	`4`
`poll_interval_secs`	整数	`5`
`recover_stale`	bool	`true`
`result_property`	字符串	`"Result"`
`status_property`	字符串	`"Status"`

`observability`

可观测性后端配置（[observability] 部分）。

键	类型	默认	描述
`backend`	`none` \| `log` \| `verbose` \| `prometheus` \| `otel`	—	可观测性接收端后端。
`log_llm_request_payload`	`off` \| `redacted` \| `full`	—	LLM 请求负载捕获策略。镜像 [`LogToolIo`]，但会门控该
`log_persistence`	表格	—	JSONL 日志持久化模式。
`log_persistence_max_bytes`	整数	`0`	触发归档轮转的字节大小阈值，当
`log_persistence_max_entries`	整数	`200`	当 `log_persistence = "rolling"` 时保留的最大条目数。
`log_persistence_path`	字符串	`"state/runtime-trace.jsonl"`	日志持久化文件路径。相对路径在 workspace_dir 下解析。
`log_persistence_retention_max_age_days`	整数	`0`	轮转归档文件的保留上限（按天计算）当
`log_persistence_retention_max_files`	整数	`7`	与该文件一起保留的已轮转归档文件数量上限
`log_persistence_rotate_daily`	bool	`true`	在 UTC 日界线时将活动文件轮转到归档，当
`log_tool_io`	`off` \| `redacted` \| `full`	—	工具 I/O 捕获策略。
`log_tool_io_denylist`	字符串数组	`[]`	I/O 除了名称 + 结果 + 持续时间之外从不记录的工具名称
`log_tool_io_truncate_bytes`	整数	`40960`	在达到这么多字节时截断捕获的工具输入和输出。
`otel_endpoint`	字符串？	`null`	OTLP 端点（例如 `"http://localhost:4318"`）。仅在 backend = `"otel"` 时使用。
`otel_genai_content`	`off` \| `redacted` \| `full`	—	OTel 内容捕获策略。镜像 [`LogToolIo`]，但会限制 OTel span
`otel_genai_content_max_chars`	整数	`1000`	OTel GenAI 内容的按字段字符截断限制，当
`otel_headers` 🔑	映射？	`null`	随每个 OTLP 导出请求发送的可选 HTTP 标头（例如 authorization）。
`otel_service_name`	字符串？	`null`	报告给 OTel collector 的服务名称。默认为 “zeroclaw”。
`otel_tool_io`	`off` \| `redacted` \| `full`	—	OTel 内容捕获策略。镜像 [`LogToolIo`]，但会限制 OTel span
`otel_tool_io_max_chars`	整数	`1000`	OTel 工具 I/O 的按字段字符截断限制，当

`onboard_state`

多客户端工作区隔离配置。

启用后，每个客户端接入都会获得一个隔离的工作区，拥有独立的内存、审计、密钥和工具限制。Quickstart 流程写入的不可见状态，用于在重新运行时判断用户已至少走过哪些部分一次——这使它可以提供“重新配置？[y/N]”跳过门，而不是强制用户再次填写每个字段。

这是关于 Quickstart 流程的元状态，不是面向用户的配置。

键	类型	默认	描述
`completed_sections`	字符串数组	`[]`	用户至少完成过一次的章节键。
`quickstart_completed`	bool	`false`	`true` 一旦 Quickstart 已应用 `BuilderSubmission`

`opencode_cli`

OpenCode CLI 工具配置（[opencode_cli] 部分）。

将编码任务委派给 opencode run CLI。默认情况下，身份验证使用二进制程序自身的会话——除非 env_passthrough 包含特定提供商的密钥，否则无需 API key。

键	类型	默认	描述
`enabled`	bool	`false`	启用 `opencode_cli` 工具
`env_passthrough`	字符串数组	`[]`	传递给 opencode 子进程的额外环境变量
`max_output_bytes`	整数	`2097152`	最大输出大小（以字节为单位，默认 2MB）
`timeout_secs`	整数	`600`	最大执行时间（秒）（编码任务可能很耗时）

`pacing`

慢速/本地 LLM 工作负载的节奏控制（[pacing] 部分）。

所有字段都是可选的，默认值会保留现有行为。设置后，它们会扩展——而不是替换——现有的超时和循环检测子系统。

键	类型	默认	描述
`loop_detection_enabled`	bool	`true`	启用基于模式的循环检测（精确重复、乒乓，
`loop_detection_max_repeats`	整数	`3`	首次出现之前连续相同的 tool+args 调用次数
`loop_detection_min_elapsed_secs`	整数类型？	`null`	循环检测生效前的最小经过秒数。
`loop_detection_window_size`	整数	`20`	基于模式的循环检测器的滑动窗口大小。
`loop_ignore_tools`	字符串数组	`[]`	排除于相同输出/交替模式循环之外的工具名称
`message_timeout_scale_max`	整数类型？	`null`	覆盖硬编码的超时缩放上限（默认值：4）。
`step_timeout_secs`	整数类型？	`null`	每步超时时间（秒）：单个步骤允许的最长时间

`peer_groups`

命名 peer groups（[peer_groups.<name>]）。每个条目绑定一个通道、一个成员 agent 列表，以及可选的非 agent（外部）成员和每组 blocklist。双向自愿：只有当两个 agent 都出现在同一组的 agents 中时，它们才会成为 peers。单 agent 安装时默认为空。参见 crate::multi_agent::PeerGroupConfig。

`peer_groups.<alias>`

[peer_groups.<name>] — 通道类型上的 mutual-opt-in 对等组。

键	类型	默认	描述
`admin_for_agent_scope`	bool	`false`	当为 `true` 时，此对等组的成员被授权签发
`agents`	字符串数组	`[]`	按别名列出成员代理。
`channel`	字符串	—	对已配置的 `[channels.<type>.<alias>]` 条目的引用。
`external_peers`	字符串数组	`[]`	按频道原生用户名划分的非 agent 成员。
`ignore`	字符串数组	`[]`	按组的阻止列表；从解析的对等节点集合中减去。
`output_modality`	表格	—	同伴组的首选输出模式。

`peripherals`

外设板集成配置（[peripherals] 部分）。

启用后，Boards 会变成 agent 工具。

键	类型	默认	描述
`boards`	object[]	`[]`	板卡配置（nucleo-f401re、rpi-gpio 等）
`datasheet_dir`	字符串？	`null`	用于 RAG 检索的 datasheet 文档路径（相对于工作区）。
`enabled`	bool	`false`	启用外围设备支持（板卡将成为代理工具）

`pipeline`

Pipeline 工具配置（[pipeline] 部分）。

键	类型	默认	描述
`allowed_tools`	字符串数组	`[]`	管道步骤中允许使用的工具。引用此处未列出的工具的步骤。
`enabled`	bool	`false`	启用 `execute_pipeline` 元工具。
`max_steps`	整数	`20`	单次管道调用允许的最大步骤数。

`plugins`

插件系统配置。

键	类型	默认	描述
`auto_discover`	bool	`false`	启动时自动发现并加载插件（默认值：false）
`enabled`	bool	`false`	启用插件系统（默认值：false）
`entries`	object[]	`[]`
`limits`	object	—	每次调用的 WASM 执行限制（`[plugins.limits]`）。
`max_active_instances`	整数	`50`	所有能力总计允许的逻辑插件实例最大数量。
`plugins_dir`	字符串	`"/home/runner/.zeroclaw/plugins"`	插件存储的目录
`security`	object	—	插件签名验证配置（`[plugins.security]`）。

`plugins.limits`

每次调用的 WASM 执行限制（[plugins.limits]）。

限制单次插件调用，使失控或恶意组件触发陷阱，而不是导致宿主挂起或耗尽内存。call_fuel 限制每次调用的指令数；call_timeout_ms 限制经过的挂钟时间，包括等待异步宿主导入的时间；内存、表和实例上限限制存储的增长。每个值均可由操作员调整，并经过非零验证。

键	类型	默认	描述
`call_fuel`	整数	`1000000000`	每次插件调用的燃料预算（wasmtime 指令单位）。
`call_timeout_ms`	整数	`30000`	单次插件导出调用的挂钟截止时间，以毫秒为单位。
`max_connections_per_instance`	整数	`16`	每个逻辑插件实例的宿主持有的活动网络连接数上限，
`max_instances`	整数	`64`	插件存储可创建的最大组件实例数。
`max_memory_mb`	整数	`256`	插件存储可增长到的最大线性内存，单位为兆字节。
`max_table_elements`	整数	`100000`	插件存储可分配的最大表元素数。

`plugins.security`

插件签名验证配置（[plugins.security]）。

控制插件清单的 Ed25519 签名验证。在 strict 模式下，仅加载由受信任发布者密钥签名的插件。在 permissive 模式下，未签名或不受信任的插件会产生警告，但仍会被加载。在 disabled 模式（默认）下，不执行签名检查。

键	类型	默认	描述
`signature_mode`	字符串	`"disabled"`	签名强制模式：“disabled”、“permissive” 或 “strict”。
`trusted_publisher_keys`	字符串数组	`[]`	受信任插件发布者的 Hex 编码 Ed25519 公钥。

`project_intel`

项目交付智能配置（[project_intel] 部分）。

键	类型	默认	描述
`default_language`	字符串	`"en"`	默认报告语言（en、de、fr、it）。默认值：“en”。
`enabled`	bool	`false`	启用 project_intel 工具。默认值：false。
`include_git_data`	bool	`true`	在报告中包含 git log 数据。默认值：true。
`include_jira_data`	bool	`false`	在报告中包含 Jira 数据。默认值：false。
`jira_base_url`	字符串？	`null`	Jira 实例基础 URL（如果 include_jira_data 为 true，则必填）。
`report_output_dir`	字符串	`"/home/runner/.zeroclaw/project-reports"`	生成报告的输出目录。
`risk_sensitivity`	字符串	`"medium"`	风险检测灵敏度：低、中、高。默认值：“medium”。
`templates_dir`	字符串？	`null`	可选的自定义模板目录。

`providers`

每个已配置提供程序类别的顶层包装器。

键	类型	默认	描述
`models`	object	—	带有每个提供商系列一个别名映射的类型化模型提供商容器。
`transcription`	object	—	类型化的 transcription-provider 容器——每个 STT 家族一个槽位。
`tts`	object	—	Typed TTS 提供方容器 — 每个 TTS 家族一个槽位。镜像

`providers.models`

带有每个提供商系列一个别名映射的类型化模型提供商容器。

每个系列一个插槽（ai21、aihubmix、anthropic、anyscale、arcee、astrai、atlascloud、atomic_chat、avian、azure、baichuan、baseten、bedrock、cerebras、cloudflare、cohere、copilot、custom、deepinfra、deepmyst、deepseek、doubao、featherless、fireworks、friendli、gemini、gemini_cli、github_models、glm、grok_cli、groq、huggingface、hunyuan、hyperbolic、inception、kilo、kilocli、lambda_ai、lepton、litellm、llamacpp、lmstudio、manifest、minimax、mistral、moonshot、morph、nearai、nebius、novita、nscale、nvidia、ollama、openai、opencode、openrouter、osaurus、ovh、perplexity、qianfan、qwen、reka、sambanova、sglang、siliconflow、stepfun、synthetic、telnyx、together、upstage、venice、vercel、vllm、xai、yi、zai、zerorouter）。每个插槽都是一个 [providers.models.<slot>.<alias>] 映射；有关各字段的参考信息，请参阅专门的章节页面。

`providers.transcription`

类型化的 transcription-provider 容器——每个 STT 家族一个槽位。镜像 ModelProviders / TtsProviders。封闭的 6 个家族集合：groq、openai、deepgram、assemblyai、google、local_whisper。

每个 family 一个槽位（assemblyai、deepgram、google、groq、local_whisper、openai）。每个槽位都是一个 [providers.transcription.<slot>.<alias>] 映射；请参阅专门的章节页面以获取各字段参考。

`providers.tts`

类型化的 TTS 提供方容器 — 每个 TTS 家族一个槽位。与 ModelProviders 类似，但更小（TTS 有一个封闭的 5 个家族集合：openai、elevenlabs、google、edge、piper）。不需要兜底项。

每个家族一个槽位（edge, elevenlabs, google, openai, piper）。每个槽位都是一个 [providers.tts.<slot>.<alias>] 映射；有关各字段参考，请参见专门的章节页面。

`proxy`

出站 HTTP/HTTPS/SOCKS5 流量的代理配置（[proxy] 部分）。标准的 web_fetch 请求和每个 http_request 请求均直接连接，因此可以固定其经本地验证的 DNS 解析结果：它们会绕过环境代理，并拒绝适用于 tool.web_fetch 或 tool.http_request 的运行时代理作用域，包括已启用的 environment 作用域。忽略未受管理的进程代理变量时会发出警告。可选的 Firecrawl API 回退机制使用正常的环境代理发现机制。要为其他流量设置代理，请使用不带这些选择器或 tool.* 的 services 作用域。

键	类型	默认	描述
`all_proxy`	字符串？	`null`	所有方案的回退代理 URL。
`enabled`	bool	`false`	为选定范围启用代理支持。
`http_proxy`	字符串？	`null`	用于 HTTP 请求的代理 URL（支持 http、https、socks5、socks5h）。
`https_proxy`	字符串？	`null`	HTTPS 请求的代理 URL（支持 http、https、socks5、socks5h）。
`no_proxy`	字符串数组	`[]`	不使用代理的绕过列表。格式与 NO_PROXY 相同。
`scope`	表格	—	代理应用范围 — 确定哪些出站流量使用代理。
`services`	字符串数组	`[]`	当 scope = “services” 时使用的服务选择器。

`query_classification`

自动查询分类 — 根据关键词/模式对用户消息进行分类，并路由到相应的模型提示。默认禁用。

键	类型	默认	描述
`enabled`	bool	`false`	启用自动查询分类。默认值：`false`。
`rules`	object[]	`[]`	按优先级顺序评估分类规则。

`relay`

指定中继客户端（[relay]）。

启用后，守护进程会与中继保持持久的出站连接，并注册 node_id，因此 NAT 后的客户端可以_通过_中继访问它。中继是盲转发器：内部客户端<->守护进程的 mTLS 仍在守护进程的 WSS 监听器处终止，并且中继永远不会对其解密。

键	类型	默认	描述
`enabled`	bool	`false`	启用中继桥接（默认值：false）。
`node_id`	字符串	`""`	此守护进程注册时使用的不透明 node-id（客户端通过此 ID 连接）。留空
`node_id_rotation_days`	整数	`0`	每 N 天自动轮换自动生成的 node-id（默认值 0 = 从不）。
`outer_client_cert`	字符串	`""`	守护进程在外层 TLS 层向中继提供的 PEM 证书/密钥
`outer_client_key`	字符串	`""`
`relay_ca_path`	字符串	`""`	用于信任 relay 自身（外层）TLS 证书的 PEM CA。设置后，
`relay_host`	字符串	`""`	中继外层证书中应包含的服务器名称。留空则自动推导
`relay_insecure`	bool	`false`	跳过对中继外部证书的验证（仅适用于自签名开发环境）。
`tofu`	bool	`false`	对中继的 OUTER 证书采用首次使用时信任（默认为 false）：接受
`token`	字符串	`""`	注册时提供的 Relay 账户令牌（准入凭据）。
`url`	字符串	`""`	要连接的中继地址，格式为 `host:port`。

`reliability`

可靠性和监督配置（[reliability] 部分）。

控制 model_provider 重试、API 密钥轮换和通道重启退避。

键	类型	默认	描述
`api_keys` 🔑	字符串数组	`[]`	用于在遇到速率限制（429）错误时轮换的其他 API key。
`channel_initial_backoff_secs`	整数	`2`	通道/守护进程重启的初始退避时间。
`channel_max_backoff_secs`	整数	`60`	通道/守护进程重启的最大退避时间。
`provider_backoff_ms`	整数	`500`	模型提供者重试延迟的基础退避时间（ms）。
`provider_retries`	整数	`2`	在放弃之前，每个 model_provider 的重试次数。
`scheduler_poll_secs`	整数	`15`	调度器轮询间隔（秒）。
`scheduler_retries`	整数	`2`	cron 作业执行尝试的最大重试次数。

`risk_profiles`

命名的风险/自主配置文件（[risk_profiles.<alias>]）。

`risk_profiles.<alias>`

命名的风险/自治配置文件（[risk_profiles.<alias>]）。

统一的策略表面。代理通过别名引用一个配置文件，运行时通过它解析 shell 命令允许列表、审批门控、沙箱/资源限制以及委派护栏。约定上的 risk_profiles["default"] 是非代理上下文（orchestrator 初始化、cron worker 启动）的解析目标；下面的 Default impl 复制了旧版“安全优先”的默认值，因此全新安装的行为与按配置文件拆分之前的配置保持一致。

键	类型	默认	描述
`allowed_commands`	字符串数组	`["git","npm","cargo","ls","cat","grep","find","echo","pwd","wc","head","tail","date","df","du","uname","uptime","hostname","python","python3","pip","node","free"]`	用于 shell 执行的可执行文件名允许列表。
`allowed_roots`	字符串数组	`[]`	代理可能访问的额外目录根。
`allowed_tools`	字符串数组	`[]`	代理在代理模式下可调用的工具。空 = 继承 / 无
`always_ask`	字符串数组	`[]`	此配置文件中始终需要批准的工具。
`approval_route`	object	—	将工具审批路由到独立的审批人通道，并默认采用失败关闭策略。
`auto_approve`	字符串数组	`["file_read","memory_recall","web_search_tool","web_fetch","calculator","glob_search","content_search","image_info","weather","tool_search","browser","browser_open"]`	在此配置文件中从不需要批准的工具。
`block_high_risk_commands`	bool	`true`	即使在允许列表中，也要阻止高风险命令。
`delegation_policy`	object	—	将工作委派给共享该风险配置的代理时所采用的策略。
`excluded_tools`	字符串数组	`[]`	非 CLI 通道下排除的工具。
`firejail_args`	字符串数组	`[]`	当 `sandbox_backend = "firejail"` 时转发给 firejail 的额外参数。
`forbidden_paths`	字符串数组	`["/etc","/root","/home","/usr","/bin","/sbin","/lib","/opt","/boot","/dev","/proc","/sys","/var","/tmp","~/.ssh","~/.gnupg","~/.aws","~/.config"]`	显式路径拒绝列表。
`level`	表格	—	代理的自主级别，按自主性从低到高排列。
`require_approval_for_medium_risk`	bool	`true`	要求对中等风险操作进行批准。
`sandbox_backend`	字符串？	`null`	沙箱后端标识符（例如 `"firejail"`、`"landlock"`）。`None` 继承。
`sandbox_enabled`	bool?	`null`	此配置文件是否启用沙箱。`None` 继承全局设置。
`shell_env_passthrough`	字符串数组	`[]`	传递给 shell 子进程的环境变量名称。
`workspace_only`	bool	`true`	将文件系统访问限制为相对于工作区的路径。默认值：`false`。

`risk_profiles.<alias>.approval_route`

将工具审批路由到独立的审批人通道，并默认采用失败关闭策略。

键	类型	默认	描述
`approver_channel`*	字符串	—	已注册的频道名称（不是发起者）——唯一审批者跳转。
`on_no_approver`	表格	—	当配置的审批人无法联系到时该怎么办。默认 FAIL-CLOSED。
`timeout_secs`	整数	`120`	限制审批者的响应窗口；超时将拒绝（DoS 防护）。默认 120s。

`risk_profiles.<alias>.delegation_policy`

将工作委派给共享该风险配置的代理时所采用的策略。

键	类型	默认	描述
`mode`	表格	—	风险配置文件的委派模式。

`runtime`

运行时适配器配置（[runtime] 部分）。

键	类型	默认	描述
`docker`	object	—	Docker 运行时配置（`[runtime.docker]` 部分）。
`kind`	`native` \| `docker` \| `cloudflare`	—	运行时适配器类型。
`reasoning_effort`	字符串？	`null`	适用于公开级别控制的 model_providers 的可选推理努力。
`reasoning_enabled`	bool?	`null`	对暴露显式控制的 model_providers 进行全局推理覆盖。
`shell`	字符串？	`null`	用于命令执行的原生运行时使用的 Shell 二进制文件。

`runtime.docker`

Docker 运行时配置（[runtime.docker] 部分）。

键	类型	默认	描述
`allowed_workspace_roots`	字符串数组	`[]`	用于采用失败即关闭策略的 Docker 挂载验证的可选工作区根目录允许列表：启用 `mount_workspace` 时，即使此列表为空，工作区也必须存在并完成规范化；每个配置的根目录也必须存在并完成规范化；任何一个无效条目都会在 Docker 启动前拒绝该命令；空列表允许任何规范化后的工作区。
`cpu_limit`	number?	`1.0`	可选的 CPU 限制（`None` = 不显式限制）。
`image`	字符串	`"alpine:3.20"`	用于执行 shell 命令的运行时镜像。
`memory_limit_mb`	整数类型？	`512`	可选的内存限制（MB）（`None` = 无显式限制）。
`mount_workspace`	bool	`true`	将已配置的工作区挂载到 `/workspace`。
`network`	字符串	`"none"`	Docker 网络模式（`none`、`bridge` 等）。
`read_only_rootfs`	bool	`true`	以只读方式挂载根文件系统。

`runtime_profiles`

命名的运行时/LLM 执行配置文件（[runtime_profiles.<alias>]）。

`runtime_profiles.<alias>`

命名的运行时/LLM 执行配置文件 ([runtime_profiles.<alias>])。

可复用的运行调优：agentic 模式、迭代上限、上下文预算、并行调度、资源上限、递归深度，以及 SecurityPolicy 通过子代理父子集约束执行的预算旋钮。任何授权相关的内容（允许的命令/工具/路径、审批门控、沙箱）都放在 [risk_profiles.<alias>]。任何模型提供方相关的内容（model、temperature、max_tokens、timeout_secs）都放在 [providers.models.<type>.<alias>]。

键	类型	默认	描述
`agentic`	bool	`false`	启用 agentic（多轮工具调用循环）模式。
`agentic_timeout_secs`	整数类型？	`null`	代理委托运行超时时间（秒）。`None` 继承全局设置。
`auto_classify`	object	—
`compact_context`	bool?	`null`	使用紧凑型 bootstrap（6000 字符 / 2 个 RAG chunk）。`None` 继承。
`context_compression`	object	—
`delegation_timeout_secs`	整数类型？	`null`	委托调用超时（秒）。`None` 继承全局委托超时。
`eval`	object	—
`history_pruning`	object	—
`keep_tool_context_turns`	整数类型？	`null`	保留完整工具上下文的最近轮次数量。`None` 继承。
`max_actions_per_hour`	整数	`20`	每小时允许的最大操作数。`0` 表示硬零预算——
`max_context_tokens`	整数类型？	`null`	压缩前上下文的最大估计 token 数。`None` 继承。
`max_cost_per_day_cents`	整数	`500`	每天的最大费用（以美分计）。`0` 继承全局限制。
`max_delegation_depth`	整数	`0`	最大委派递归深度。`0` 继承默认值。
`max_history_messages`	整数类型？	`null`	每个会话保留的最大对话历史消息数。`None` 继承。
`max_system_prompt_chars`	整数类型？	`null`	组装后的系统提示的最大字符数。`None` 继承。
`max_tool_iterations`	整数	`0`	Agentic 模式中的最大工具调用迭代次数。`0` 继承全局默认值。
`max_tool_result_chars`	整数类型？	`null`	单个工具结果的最大字符数。`None` 继承。
`memory_recall_limit`	整数类型？	`null`	每轮注入的最大内存条目数。`None` 继承全局默认值（5）。
`parallel_tools`	bool?	`null`	按迭代启用并行工具执行。`None` 继承。
`prompt_injection_mode`	表格	—	Skills 加载配置（`[skills]` 部分）。
`shell_timeout_secs`	整数	`60`	Shell 子进程超时时间（秒）。`0` 继承全局超时。
`strict_tool_parsing`	bool	`false`
`thinking`	object	—	用于控制思考/推理级别的配置。
`tool_call_dedup_exempt`	字符串数组	`[]`	免于轮内去重检查的工具。
`tool_dispatcher`	字符串？	`null`	工具分发策略（例如 `"auto"`）。`None` 继承。
`tool_filter_groups`	object[]	`[]`
`tool_receipts`	object	—	按代理的 HMAC 工具执行回执配置

`runtime_profiles.<alias>.auto_classify`

键	类型	默认
`complex_hint`	字符串？	`null`
`cost_optimized_hint`	字符串	`"cost-optimized"`
`simple_hint`	字符串？	`null`
`standard_hint`	字符串？	`null`

`runtime_profiles.<alias>.context_compression`

键	类型	默认	描述
`enabled`	bool	`false`	运行时上下文压缩器已被移除；无运行时执行路径
`identifier_policy`	字符串	`"strict"`
`max_passes`	整数	`3`
`protect_first_n`	整数	`3`
`protect_last_n`	整数	`4`
`source_max_chars`	整数	`50000`
`summary_max_chars`	整数	`4000`
`summary_model`	字符串？	`null`	已弃用的裸模型 ID，作为兼容性回退保留。
`summary_provider`	字符串	—	对已配置的 `[providers.models.<type>.<alias>]` 条目的引用。
`threshold_ratio`	number	`0.5`
`timeout_secs`	整数	`60`
`tool_result_retrim_chars`	整数	`2000`
`tool_result_trim_exempt`	字符串数组	`[]`

`runtime_profiles.<alias>.eval`

键	类型	默认
`enabled`	bool	`false`
`max_retries`	整数	`1`
`min_quality_score`	number	`0.5`

`runtime_profiles.<alias>.history_pruning`

键	类型	默认
`collapse_tool_results`	bool	`true`
`enabled`	bool	`false`
`keep_recent`	整数	`4`
`max_tokens`	整数	`8192`

`runtime_profiles.<alias>.thinking`

用于控制思考/推理级别的配置。

键	类型	默认	描述
`budget_tokens`	映射	`{}`
`default_level`	`off` \| `minimal` \| `low` \| `medium` \| `high` \| `max`	—	对于给定消息，模型应进行多深入的推理。
`display`	`off` \| `omitted` \| `updates` \| `summarized`	—	面向用户的 Anthropic `thinking.display` 测试版控制项
`native_thinking`	bool	`false`	当选定级别设置了预算时，启用提供方原生的思考参数。

`runtime_profiles.<alias>.tool_receipts`

HMAC 工具执行收据配置，按 agent（[agents.<alias>.tool_receipts]）。

收据是附加到工具结果上的简短 HMAC-SHA256 标签，这样模型就不能声称它运行了一个实际上从未执行过的工具。请参见 docs/book/src/security/tool-receipts.md。

键	类型	默认	描述
`enabled`	bool	`false`	在每次工具执行时生成 HMAC 收据。默认值：`false`。
`inject_system_prompt`	bool	`true`	将 receipt-echo 指令注入系统提示中，以便
`show_in_response`	bool	`false`	向用户可见的回复末尾追加一个尾随的 `Tool receipts:` 块，以便

`scheduler`

定时任务执行的调度器配置（[scheduler] 部分）。

拥有 cron-runtime 的这些调节项：按作业声明存放在 Config.cron: HashMap<String, CronJobDecl> 中（按别名键控），而调度器循环的运行时行为（enabled、轮询上限、补跑）则在这里。

键	类型	默认	描述
`catch_up_on_startup`	bool	`true`	在调度器启动时运行所有逾期作业。默认值：`true`。
`enabled`	bool	`true`	启用内置调度器循环。为 false 时，不会运行任何 cron 作业。
`max_concurrent`	整数	`4`	单个轮询周期内并行执行的最大任务数。
`max_run_history`	整数	`50`	保留的历史 cron 运行记录最大数量。默认：`50`。
`max_tasks`	整数	`64`	每个轮询周期可持久化的计划任务最大数量。

`schema_version`

配置文件模式版本。

`secrets`

Secrets 加密配置（[secrets] 部分）。

键	类型	默认	描述
`encrypt`	bool	`true`	启用对静态存储的 API 密钥和令牌的加密

`security`

用于审计日志记录、OTP、急停、IAM/SSO、WebAuthn 和主机 NAT64 出站边界的安全配置。

Sandbox 后端和资源限制位于每个 agent 的风险配置文件中（参见 RiskProfileConfig::sandbox_* 和 RiskProfileConfig::max_*）；运行时通过 Config::active_risk_profile(agent_alias) 解析它们。

键	类型	默认	描述
`audit`	object	—	审计日志配置
`estop`	映射	—	紧急停止配置。
`leak_detection`	object	—	出站凭据泄露检测配置。
`nat64_prefixes`	字符串数组	`[]`	此主机上部署的特定于网络的 RFC 6052 NAT64 前缀
`nevis`	映射	—	Nevis IAM 集成配置。
`otp`	映射	—	安全 OTP 配置。
`webauthn`	object	—	WebAuthn / FIDO2 硬件密钥认证配置（`[security.webauthn]`）。

`security.audit`

审计日志配置

键	类型	默认	描述
`enabled`	bool	`true`	启用审计日志记录
`log_path`	字符串	`"audit.log"`	审计日志文件路径（相对于 zeroclaw 目录）
`max_size_mb`	整数	`100`	轮转前的最大日志大小（MB）
`sign_events`	bool	`false`	使用 HMAC 对事件进行签名以证明未被篡改

`security.estop`

紧急停止配置。

键	类型	默认	描述
`enabled`	bool	`false`	启用紧急停止控件。
`require_otp_to_resume`	bool	`true`	在恢复操作之前需要有效的 OTP。
`state_file`	字符串	`"/home/runner/.zeroclaw/estop-state.json"`	用于持久化 estop 状态的文件路径。

`security.leak_detection`

出站凭据泄露检测配置。

这些设置控制在出站通道响应交付前的最终护栏扫描。确定性凭证模式包括 API 密钥、私钥、数据库 URL、bot 令牌以及相关的令牌语法。高熵扫描是针对独立不透明令牌的单独启发式检查。

键	类型	默认	描述
`enabled`	bool	`true`	启用出站凭据泄漏检测和脱敏。
`high_entropy_tokens`	bool	`true`	启用高熵令牌的遮蔽；当为 false 时，确定性模式仍会运行。
`sensitivity`	number	`0.7`	检测灵敏度从 0.0 到 1.0；越高越激进。

`security.nevis`

Nevis IAM 集成配置。

当 enabled 为 true 时，ZeroClaw 会根据 Nevis Security Suite 实例验证传入请求，并将 Nevis 角色映射到工具/工作区权限。

键	类型	默认	描述
`client_id`	字符串	`""`	在 Nevis 中注册的 OAuth2 客户端 ID。
`client_secret` 🔑	字符串？	`null`	OAuth2 客户端密钥。存储到磁盘时通过 SecretStore 加密。
`enabled`	bool	`false`	启用 Nevis IAM 集成。为向后兼容，默认值为 false。
`instance_url`	字符串	`""`	Nevis 实例的基础 URL（例如 `https://nevis.example.com`）。
`jwks_url`	字符串？	`null`	用于本地令牌验证的 JWKS 端点 URL。
`realm`	字符串	`"master"`	用于进行身份验证的 Nevis realm。
`require_mfa`	bool	`false`	为所有经 Nevis 身份验证的请求要求进行 MFA 验证。
`role_mapping`	map[]	`[]`	Nevis 角色到 ZeroClaw 权限映射。
`session_timeout_secs`	整数	`3600`	会话超时（秒）。
`token_validation`	字符串	`"local"`	令牌验证策略：`"local"`（JWKS）或`"remote"`（introspection）。

`security.otp`

安全 OTP 配置。

键	类型	默认	描述
`cache_valid_secs`	整数	`300`	为最近验证过的 OTP 代码重用窗口。
`challenge_max_attempts`	整数	`3`	锁定前 OTP 挑战的最大尝试次数。
`enabled`	bool	`false`	启用 OTP 门禁。默认情况下为禁用，以保持向后兼容。
`gated_actions`	字符串数组	`["shell","file_write","browser_open","browser","memory_forget"]`	由 OTP 保护的工具/操作名称。空条目或格式错误的条目将被拒绝
`gated_domain_categories`	字符串数组	`[]`	域类别预设已扩展为 `gated_domains`。
`gated_domains`	字符串数组	`[]`	通过 OTP 门控的显式域模式。
`method`	表格	—	OTP 验证策略。
`token_ttl_secs`	整数	`30`	TOTP 时间步长（秒）。

`security.webauthn`

WebAuthn / FIDO2 硬件密钥认证配置（[security.webauthn]）。

通过硬件安全密钥（YubiKey、SoloKey 等）和平台验证器（Touch ID、Windows Hello）启用注册和身份验证。

键	类型	默认	描述
`enabled`	bool	`false`	启用 WebAuthn 身份验证。默认值：false。
`rp_id`	字符串	`"localhost"`	Relying Party ID（域名，例如 “example.com”）。默认值：“localhost”。
`rp_name`	字符串	`"ZeroClaw"`	Relying Party 显示名称。默认值：“ZeroClaw”。
`rp_origin`	字符串	`"http://localhost:42617"`	Relying Party 源 URL（例如 `"https://example.com"`）。默认值：`"http://localhost:42617"`。

`security_ops`

托管网络安全服务（MCSS）仪表板代理配置（[security_ops]）。

键	类型	默认	描述
`auto_triage`	bool	`false`	无需用户提示即可自动对传入警报进行分诊。
`enabled`	bool	`false`	启用安全操作工具。
`max_auto_severity`	字符串	`"low"`	可在无需批准的情况下自动修复的最高严重级别。
`playbooks_dir`	字符串	`"/home/runner/.zeroclaw/playbooks"`	包含事件响应手册定义（JSON）的目录。
`report_output_dir`	字符串	`"/home/runner/.zeroclaw/security-reports"`	生成的安全报告目录。
`require_approval_for_actions`	bool	`true`	在执行 playbook 操作之前需要人工批准。
`siem_integration`	字符串？	`null`	用于告警摄取的可选 SIEM webhook URL。

`shell_tool`

Shell 工具配置（[shell_tool] 部分）。

控制 shell 执行工具的行为。主要可调参数是 timeout_secs — 单个 shell 命令在被终止前可运行的最大墙钟时间。

键	类型	默认	描述
`timeout_secs`	整数	`60`	Shell 命令执行的最大时间（秒）（默认：60）。

`skill_bundles`

命名技能包（[skill_bundles.<alias>]）。

`skill_bundles.<alias>`

命名技能包（[skill_bundles.<alias>]）。

一个可重用的技能组，可通过别名附加到代理或通道，用于控制加载哪些技能以及从何处加载。

键	类型	默认	描述
`directory`	字符串？	`null`	要加载技能的目录路径（相对于工作区根目录）。
`exclude`	字符串数组	`[]`	要从此捆绑包中排除的技能名称。
`include`	字符串数组	`[]`	要包含的技能名称。为空表示包含 `directory` 中的所有技能。

`skills`

Skills 加载配置（[skills] 部分）。

键	类型	默认	描述
`allow_scripts`	bool	`false`	在 skills 中允许脚本类文件（`.sh`、`.bash`、`.ps1`、带 shebang 的 shell 文件）。
`extra_registries`	object[]	—	通过以下方式安装的其他用户配置技能注册表
`install_suggestions`	object	—	提示触发的技能安装建议（`[skills.install_suggestions]` 部分）。
`open_skills_dir`	字符串？	`null`	本地 open-skills 仓库的可选路径。
`open_skills_enabled`	bool	`false`	启用加载和同步社区 open-skills 仓库。
`prompt_injection_mode`	表格	—	Skills 加载配置（`[skills]` 部分）。
`registry_url`	字符串？	`null`	用于 bare-name 安装的技能注册表仓库 URL。
`skill_creation`	object	—	自主技能创建配置（`[skills.skill_creation]` 部分）。
`skill_improvement`	object	—	技能自我提升配置（`[skills.skill-improvement]` 部分）。

`skills.install_suggestions`

提示触发的技能安装建议（[skills.install_suggestions] 部分）。

键	类型	默认	描述
`enabled`	bool	`false`	在正常的 agent 回合之前启用可安装技能的建议。

`skills.skill_creation`

自主技能创建配置（[skills.skill_creation] 部分）。

键	类型	默认	描述
`enabled`	bool	`false`	在成功完成多步骤任务后启用自动技能创建。
`max_final_answer_chars`	整数	`2000`	最终传入的助手回答的最大字符数
`max_skills`	整数	`500`	保留的自动生成技能的最大数量。
`max_task_chars`	整数	`1000`	反馈中输入的任务描述最大字符数
`max_tool_trace_chars`	整数	`4000`	馈入的已渲染工具调用轨迹的最大字符数
`reflection_enabled`	bool	`false`	从执行轨迹中合成一个规范的 `SKILL.md` 通过 a
`similarity_threshold`	number	`0.85`	用于去重的嵌入相似度阈值。

`skills.skill_improvement`

技能自我提升配置（[skills.skill-improvement] 部分）。

控制回合后背景审查分支，该分支可根据对话中透露的信息对技能进行修补、扩展或归档。该分支在受限工具集中运行（仅 skills_list、skill_view、skill_manage），并且绝不接触用户可见的对话。

键	类型	默认	描述
`cooldown_secs`	整数	`3600`	同一技能两次复习之间的最小间隔（秒）。
`enabled`	bool	`false`	启用后台技能审查 fork。默认：`false`。
`max_review_iterations`	整数	`8`	审查分支本身允许进行的最大工具调用迭代次数。
`nudge_interval_iterations`	整数	`10`	当至少进行了这么多次工具调用迭代后，创建一个 review fork

`sop`

标准操作程序引擎配置（[sop]）。

default_execution_mode 字段使用来自 sop::types 的 SopExecutionMode 类型（通过 sop::SopExecutionMode 重新导出）。为避免循环模块引用，config 使用相同的枚举定义来存储它。

键	类型	默认	描述
`approval`	object	—	`[sop.approval]` - 审批代理策略配置。永久身份源
`approval_mode`	表格	—	谁可以清除 SOP 审批门。与 execution_mode / priority / 一起分层。
`approval_timeout_action`	表格	—	当 SOP 审批门禁超时时会发生什么。默认是 fail-closed:
`approval_timeout_secs`	整数	`300`	审批超时时间（秒）。当某个运行等待审批超过该时间时
`default_execution_mode`	字符串	`"supervised"`	未省略 `execution_mode` 的 SOP 的默认执行模式。
`maintenance_interval_secs`	整数	`60`	守护进程运行 SOP 维护 tick 的频率（秒）：fire
`max_concurrent_total`	整数	`4`	所有 SOP 的最大总并发运行数。
`max_finished_runs`	整数	`100`	用于状态查询时，内存中保留的已完成运行的最大数量。
`max_step_retries`	整数	`2`	步骤失败策略允许的最大重试次数。
`max_step_visits`	整数	`256`	路由 SOP 运行访问某一步的最大次数。
`persist_runs`	bool	`true`	跨重启持久化保存运行状态。默认值为 `true`：`build_sop_engine`
`procedural_memory_enabled`	bool	`false`	启用 SOP 程序性记忆提案工具。默认 false 保持
`run_state_dir`	字符串？	`null`	持久运行存储的目录（以 mode-0700 创建）。省略时，
`run_store_backend`	表格	—	Durable SOP 运行状态后端选择器。一个封闭的、编译期已知的集合，因此它
`sops_dir`	字符串？	`null`	包含 SOP 定义的目录（包含 SOP.toml + SOP.md 的子目录）。
`step_mandatory_tools`	字符串数组	`["sop_advance","sop_approve","sop_status"]`	在强制执行步骤作用域时仍然可用的工具名称。
`step_schema_enforce`	bool	`true`	当步骤声明了输入/输出模式时，强制执行每个步骤的输入/输出模式。
`step_scope_enforce`	bool	`false`	强制执行每步工具范围。默认 false 会将 `tools:` 保持为建议性。
`untrusted_frame_warning`	bool	`true`	将说明性警告文本包含在不受信任内容框架内。
`untrusted_guard_sensitivity`	number	`0.7`	未受信任的 SOP 内容的提示防护和出站脱敏敏感性。
`untrusted_input_guard`	字符串	`"warn"`	针对不受信任的 SOP 触发输入的 Prompt-guard 操作：警告、阻止或清理。
`untrusted_outbound_redact`	bool	`true`	在持久化/审计消费者写入之前，先对出站 SOP 内容进行脱敏。
`untrusted_payload_max_bytes`	整数	`8192`	来自不受信任的 SOP 触发器负载/主题内容可接受的最大字节数

`sop.approval`

[sop.approval] - 审批代理策略配置。用于频道提供的审批人的永久身份来源（不是权宜之计）：审批代理使用它进行组成员资格和法定人数检查。为空 = 不应用任何代理策略。

每个系列一个插槽（groups、policies）。每个插槽都是一个 [sop.approval.<slot>.<alias>] 映射；有关各字段的参考信息，请参阅专门的章节页面。

`storage`

持久存储配置（[storage] 部分）。

Storage 是一个两级别名键控映射：[storage.<backend>.<alias>]，与 [providers.models.<type>.<alias>] 平行。每个后端都有自己的类型化配置结构体。MemoryConfig.backend 携带一个带点的引用（"sqlite.default"、"postgres.work"），它通过 [Config::resolve_active_storage] 解析为这些条目之一。

每个 family 一个槽位（lucid、markdown、postgres、qdrant、sqlite）。每个槽位都是一个 [storage.<slot>.<alias>] 映射；有关各字段的参考，请参见专门的章节页面。

`text_browser`

Text browser 工具配置（[text_browser] 部分）。

使用基于文本的浏览器（lynx、links、w3m）将网页渲染为纯文本。专为没有图形浏览器的无头/SSH 环境设计。

键	类型	默认	描述
`allowed_private_hosts`	字符串数组	`[]`	允许私有/内部主机放宽公共地址 SSRF 检查。
`enabled`	bool	`false`	启用 `text_browser` 工具
`preferred_browser`	字符串？	`null`	首选文本浏览器（“lynx”、“links” 或 “w3m”）。如果未设置，则自动检测。
`timeout_secs`	整数	`30`	请求超时时间（秒）（默认值：30）

`transcription`

带有多提供商支持的语音转录配置。

顶层的 api_url、model 和 api_key 字段保留用于与现有基于 Groq 的配置向后兼容。

键	类型	默认	描述
`api_key` 🔑	字符串？	`null`	用于转录请求的 API key（Groq transcription provider）。
`api_url`	字符串	`"https://api.groq.com/openai/v1/audio/transcriptions"`	Whisper API 端点 URL（Groq 转录提供商）。
`assemblyai`	object	—	AssemblyAI STT 模型提供程序配置（`[transcription.assemblyai]`）。
`deepgram`	object	—	Deepgram STT 模型提供者配置（`[transcription.deepgram]`）。
`enabled`	bool	`false`	为支持的频道启用语音转录。
`google`	object	—	Google Cloud Speech-to-Text 模型提供方配置 (`[transcription.google]`)。
`initial_prompt`	字符串？	`null`	可选的初始提示，用于将转录结果偏向预期词汇
`language`	字符串？	`null`	用于 Groq 转录提供程序的可选语言提示（ISO-639-1，例如 “en”、“ru”）。
`local_whisper`	object	—	本地/自托管的 Whisper 兼容 STT 端点（`[transcription.local_whisper]`）。
`max_audio_bytes`	整数类型？	`null`	可选的全局音频大小上限（以字节为单位），在此之前强制执行
`max_duration_secs`	整数	`120`	最大语音时长（秒）（长于此时长的消息将被跳过）。
`model`	字符串	`"whisper-large-v3-turbo"`	Whisper 模型名称（Groq 转录提供商）。
`openai`	object	—	OpenAI Whisper STT 模型提供程序配置（`[transcription.openai]`）。
`transcribe_non_ptt_audio`	bool	`false`	同时转录 WhatsApp 上非 PTT（转发/普通）音频消息，

`transcription.assemblyai`

AssemblyAI STT 模型提供程序配置（[transcription.assemblyai]）。

键	类型	默认	描述
`api_key` 🔑	字符串？	`null`	AssemblyAI API 密钥

`transcription.deepgram`

Deepgram STT 模型提供者配置（[transcription.deepgram]）。

键	类型	默认	描述
`api_key` 🔑	字符串？	`null`	Deepgram API 密钥
`model`	字符串	`"nova-2"`	Deepgram 模型名称（默认值：“nova-2”）。

`transcription.google`

Google Cloud Speech-to-Text 模型提供方配置 ([transcription.google])。

键	类型	默认	描述
`api_key` 🔑	字符串？	`null`	Google Cloud API 密钥
`language_code`	字符串	`"en-US"`	BCP-47 语言代码（默认：`"en-US"`）。

`transcription.local_whisper`

本地/自托管的 Whisper 兼容 STT 端点（[transcription.local_whisper]）。

配置一个自托管的 STT 端点。可以是 localhost、私有网络主机，或任何可访问的 URL。

键	类型	默认	描述
`bearer_token` 🔑	字符串？	`null`	用于端点身份验证的 Bearer token。
`max_audio_bytes`	整数	`26214400`	此端点接受的最大音频文件大小（字节）。
`timeout_secs`	整数	`300`	请求超时（秒）。默认为 300（本地 GPU 上的大文件）。
`url`*	字符串	—	HTTP 或 HTTPS 端点 URL，例如 `"http://10.10.0.1:8001/v1/transcribe"`。

`transcription.openai`

OpenAI Whisper STT 模型提供程序配置（[transcription.openai]）。

键	类型	默认	描述
`api_key` 🔑	字符串？	`null`	OpenAI API key 用于 Whisper 转录。
`model`	字符串	`"whisper-1"`	Whisper 模型名称（默认值：“whisper-1”）。

`trust`

键	类型	默认
`correction_penalty`	number	`0.05`
`decay_half_life_days`	number	`30.0`
`initial_score`	number	`0.8`
`regression_threshold`	number	`0.5`
`success_boost`	number	`0.01`

`tts`

文本转语音子系统配置（[tts]）。

每个实例的 TTS 配置位于 [tts_providers.<type>.<alias>] 下（与 providers.models 平行）。这里剩下的是适用于每次 model_provider 调用的全局运行时选项。

键	类型	默认	描述
`default_format`	字符串	`"mp3"`	默认音频输出格式（`"mp3"`、`"opus"`、`"wav"`）。
`default_voice`	字符串	`"alloy"`	传递给所选 tts 提供程序的默认语音 ID。
`enabled`	bool	`false`	启用 TTS 合成。
`max_text_length`	整数	`4096`	最大输入文本长度（默认 4096 个字符）。

`tunnel`

用于将网关公开暴露的隧道配置（[tunnel] 部分）。

支持的 model_providers："none"（默认）、"cloudflare"、"tailscale"、"ngrok"、"openvpn"、"pinggy"、"custom"。

键	类型	默认	描述
`cloudflare`	object	—
`custom`	object	—
`ngrok`	object	—
`openvpn`	object	—	OpenVPN 隧道配置（`[tunnel.openvpn]`）。
`pinggy`	object	—
`tailscale`	object	—
`tunnel_provider`	字符串	`"none"`	网关如何暴露到公共互联网，以便 webhooks（Telegram、Slack 等）可以访问它。`none` = 保持本地，不使用隧道；`cloudflare` = 通过 cloudflared 使用 Cloudflare Tunnel（需要 Zero Trust 账户和令牌）；`tailscale` = Tailscale Funnel/Serve（仅限 tailnet 或公共访问，除 tailscale 外无需账户）；`ngrok` = 带认证令牌的 ngrok agent；`openvpn` = 使用你自己的 OpenVPN 出口；`pinggy` = Pinggy SSH 隧道（快速一次性 URL）；`custom` = 运行你在 `[tunnel.custom]` 下定义的任意命令。

`tunnel.cloudflare`

键	类型	默认	描述
`token` 🔑	字符串	`""`	Cloudflare Tunnel 令牌（来自 Zero Trust 仪表板）

`tunnel.custom`

键	类型	默认	描述
`health_url`	字符串？	`null`	用于检查隧道健康状态的可选 URL
`start_command`	字符串	`""`	用于启动隧道的命令模板。使用 {port} 和 {host} 占位符。
`url_pattern`	字符串？	`null`	用于从命令标准输出中提取公开 URL 的可选正则表达式

`tunnel.ngrok`

键	类型	默认	描述
`auth_token` 🔑	字符串	`""`	ngrok auth token
`domain`	字符串？	`null`	可选自定义域名

`tunnel.openvpn`

OpenVPN 隧道配置（[tunnel.openvpn]）。

当 tunnel.tunnel_provider = "openvpn" 时必需。完全省略此部分会保留之前的行为。将 tunnel.tunnel_provider = "none"（或移除 [tunnel.openvpn] 块）会干净地恢复为无隧道模式。

Defaults: connect_timeout_secs = 30.

键	类型	默认	描述
`advertise_address`	字符串？	`null`	VPN 连接后通告的地址（例如，`"10.8.0.2:42617"`）。
`auth_file`	字符串？	`null`	可选的认证凭据文件路径（`--auth-user-pass`）。
`config_file`*	字符串	—	`.ovpn` 配置文件的路径（不能为空）。
`connect_timeout_secs`	整数	`30`	连接超时（秒）（默认：30，必须 > 0）。
`extra_args`	字符串数组	`[]`	额外的 openvpn CLI 参数，按原样转发。

`tunnel.pinggy`

键	类型	默认	描述
`region`	字符串？	`null`	服务器区域：`"us"`（美国）、`"eu"`（欧洲）、`"ap"`（亚洲）、`"br"`（南美）、`"au"`（澳大利亚），或省略以自动选择。
`token` 🔑	字符串？	`null`	Pinggy 访问令牌（可选 — 免费套餐无需令牌）。

`tunnel.tailscale`

键	类型	默认	描述
`funnel`	bool	`false`	使用 Tailscale Funnel（公网）与 Serve（仅限 tailnet）
`hostname`	字符串？	`null`	可选的主机名覆盖

`verifiable_intent`

可验证意图（VI）凭据签发与约束检查（[verifiable_intent] 部分）。

ZeroClaw 实现了签发、密码学、类型和约束检查，但不包含凭证链验证器。在此类验证器存在之前，vi_verify 工具不会被纳入模型可见注册表，因此下面的两个密钥都无法启用凭证验证。库路径不受影响。

启用该部分后，会通过两种方式报告这一缺口。运行时会在每次应用配置时对其进行跟踪；要让这些跟踪信息到达接收端，必须启用日志持久化。zeroclaw doctor 和配置 API 也会将其报告为 verifiable_intent_tool_withheld 验证警告；即使关闭持久化，该警告仍然可用。

键	类型	默认	描述
`enabled`	bool	`false`	选择启用 VI 部分（默认值：false）。
`strictness`	字符串	`"strict"`	用于约束评估的预期严格模式。

`web_fetch`

Web fetch 工具配置（[web_fetch] 部分）。

获取网页并将 HTML 转换为供 LLM 使用的纯文本。域名过滤：allowed_domains 控制可访问的主机（对所有公共主机使用 ["*"]）。blocked_domains 的优先级高于 allowed_domains。如果 allowed_domains 为空，则拒绝所有请求（默认拒绝）。跟随同主机重定向；拒绝跨主机重定向，以便经过验证的 DNS 响应继续固定到请求传输层。

键	类型	默认	描述
`allowed_domains`	字符串数组	`["*"]`	允许用于 web 获取的域名（精确匹配或子域名匹配；`["*"]` = 所有公共主机）
`allowed_private_hosts`	字符串数组	`[]`	允许私有/内部主机放宽对公共地址的 SSRF 检查
`blocked_domains`	字符串数组	`[]`	被阻止的域名（精确匹配或子域名匹配；始终优先于 allowed_domains）
`enabled`	bool	`true`	启用 `web_fetch` 工具以获取网页内容
`firecrawl`	object	—	面向 JS 密集型和被机器人拦截站点的 Firecrawl 回退配置。
`max_response_size`	整数	`500000`	最大响应大小（字节）（默认：500KB，纯文本通常远小于原始 HTML）
`timeout_secs`	整数	`30`	请求超时时间（秒）（默认值：30）

`web_fetch.firecrawl`

面向 JS 密集型和被机器人拦截站点的 Firecrawl 回退配置。

启用后，如果标准网页抓取失败（HTTP 错误、正文为空，或正文少于 100 个字符，提示可能是仅含 JS 的页面），工具会回退到 Firecrawl API 以进行隐蔽内容提取。

键	类型	默认	描述
`api_key_env`	字符串	`"FIRECRAWL_API_KEY"`	Firecrawl API 密钥的环境变量名称
`api_url`	字符串	`"https://api.firecrawl.dev/v1"`	Firecrawl API 基础 URL
`enabled`	bool	`false`	启用 Firecrawl 回退
`mode`	表格	—	Firecrawl 回退模式：抓取单个页面或爬取链接页面。

`web_search`

Web search 工具配置（[web_search] 部分）。

键	类型	默认	描述
`bocha_api_key` 🔑	字符串？	`null`	Bocha AI Web Search API key（当 search_provider 为 `"bocha"` 时必需）。请访问 https://open.bochaai.com 获取。
`brave_api_key` 🔑	字符串？	`null`	Brave Search API 密钥（如果 search_provider 为 “brave”，则必需）
`enabled`	bool	`true`	启用 `web_search_tool` 进行网页搜索
`jina_api_key` 🔑	字符串？	`null`	Jina AI API 密钥（如果 search_provider 为 “jina” 则必需）
`max_results`	整数	`5`	每次搜索的最大结果数 (1-10)
`search_provider`	字符串	`"duckduckgo"`	搜索提供方：`duckduckgo`（免费）、`brave`（需要 API key）、`tavily`（需要 API key）、`searxng`（自托管）、`jina`（需要 API key）或 `bocha`（Bocha AI，需要 API key — 中文友好，https://open.bochaai.com）
`searxng_instance_url`	字符串？	`null`	SearXNG 实例 URL（当 search_provider 为 `"searxng"` 时必填），例如 `"https://searx.example.com"`】【。
`tavily_api_key` 🔑	字符串？	`null`	Tavily Search API 密钥（如果 search_provider 是 “tavily”，则必填）
`timeout_secs`	整数	`15`	请求超时（秒）

`wss`

用于远程 TUI 到守护进程连接的 WebSocket Secure (WSS) 传输（[wss]）。

启用后，守护进程会在配置的绑定地址和端口上侦听 TLS 加密的 WebSocket 连接。TUI 客户端通过 --connect wss://host:port 连接。

键	类型	默认	描述
`bind`	字符串	`"0.0.0.0"`	WSS 监听器的绑定地址（默认值：“0.0.0.0”）。
`cert_path`	字符串	`""`	PEM 编码的服务器证书文件路径。
`client_auth`	object	—	远程 WSS 传输的客户端证书身份验证（mTLS）
`enabled`	bool	`false`	启用 WSS 监听器（默认：false）。
`handshake_timeout_secs`	整数	`10`	一个绝对截止时间（以秒为单位），涵盖 TLS 接受以及
`incomplete_message_timeout_secs`	整数	`60`	部分接收的消息可由该保留多长时间（以秒为单位）
`key_path`	字符串	`""`	PEM 编码的服务器私钥文件路径。
`max_pending_handshakes`	整数	`256`	已完成 `accept()` 但尚未完成 TLS 的套接字上限
`max_sessions`	整数	`64`	并发建立的 WSS 会话上限（默认值：64）。边界
`max_sessions_per_client`	整数	`8`	使用同一客户端证书的并发会话上限
`port`	整数	`9781`	WSS 监听器的端口（默认值：9781）。
`sans`	字符串数组	`[]`	自动生成的服务器证书的其他主题备用名称

`wss.client_auth`

远程 WSS 传输的客户端证书身份验证（mTLS）（[wss.client_auth]）。

这与 [GatewayClientAuthConfig] 保持一致；二者之所以是不同的结构体，仅仅是因为 Configurable 派生宏会将节前缀绑定到类型中。验证逻辑本身统一维护在 zeroclaw-tls crate 中。

与网关版本不同，这里没有 require_client_cert 开关：远程 WSS 平面始终进行_双向身份验证_（不存在仅服务器 TLS 路径），因此始终要求客户端证书。

键	类型	默认	描述
`ca_cert_path`	字符串	`""`	用于验证客户端证书的 PEM 编码 CA 证书路径。
`crl_path`	字符串	`""`	已撤销指纹列表的可选路径（每行一个 SHA-256 十六进制值）。A
`enabled`	bool	`false`	使用下面的自带 CA。当为 false（默认值）时，守护进程
`pinned_certs`	字符串数组	`[]`	可选的用于证书固定的 SHA-256 指纹。非空时，

Keyboard shortcuts

ZeroClaw Docs