配置参考

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

章节	描述
`acp`	ACP (Agent Client Protocol) server configuration (`[acp]` section).
`agents`	Aliased agents in this install. Each entry under `[agents.<alias>]`
`备份`	备份工具配置（`[backup]` 部分）。
`浏览器`	浏览器自动化配置（`[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`	对话式 AI 代理构建器配置（`[conversational_ai]` 部分）。
`cost`	成本跟踪和预算强制执行配置（`[cost]` 部分）。
`cron`	Declarative cron jobs (`[cron.<alias>]`), alias-keyed.
`data_retention`	数据保留和清理配置（`[data_retention]` 部分）。
`delegate`	全局委托工具配置，用于设置默认超时值。
`embedding_routes`	Embedding-routing rules — route `hint:<name>` to specific
`escalation`	Escalation routing configuration (`[escalation]` section).
`file_download`	Standalone file download tool configuration (`[file_download]`).
`file_upload`	Standalone file upload tool configuration (`[file_upload]`).
`file_upload_bundle`	Standalone multi-file bundle upload tool configuration
`网关`	网关服务器配置（`[gateway]` 部分）。
`gemini_cli`	Gemini CLI 工具配置（`[gemini_cli]` 部分）。
`google_workspace`	Google Workspace CLI (`gws`) 工具配置（`[google_workspace]` 部分）。
`硬件`	用于物理世界交互的向导驱动硬件配置。
心跳	用于定期健康检查的 `heartbeat` 配置（`[heartbeat]` 部分）。
`hooks`
`http_request`	HTTP 请求工具配置（`[http_request]` 部分）。
`image_gen`	独立图像生成工具配置（`[image_gen]`）。
`jira`	Jira 集成配置（`[jira]`）。
`知识`	用于捕获和复用专业知识的知识图谱配置。
`knowledge_bundles`	Named knowledge bundles (`[knowledge_bundles.<alias>]`).
`link_enricher`	自动理解入站频道消息中的链接（`[link_enricher]`）。
`linkedin`	LinkedIn 集成配置（`[linkedin]` 部分）。
`locale`	工具描述的语言环境（例如 `"en"`、`"zh-CN"`）。
`mcp`	外部 MCP 客户端配置（`[mcp]` 部分）。
`mcp_bundles`	Named MCP server bundles (`[mcp_bundles.<alias>]`).
`media_pipeline`	自动媒体理解流水线配置（`[media_pipeline]`）。
`memory`	内存后端配置（`[memory]` 部分）。
`microsoft365`	通过 Microsoft Graph API（`[microsoft365]` 部分）集成 Microsoft 365。
`model_routes`	Model-routing rules — route `hint:<name>` to specific
`多模态`	多模态（图像）处理配置（`[multimodal]` 部分）。
`node_transport`	节点间通信的安全传输配置（`[node_transport]`）。
`节点`	动态节点发现系统的配置（`[nodes]`）。
`notion`	Notion 集成配置（`[notion]`）。
可观测性	可观测性后端配置（`[observability]` 部分）。
`onboard_state`	多客户端工作区隔离配置。
`opencode_cli`	OpenCode CLI 工具配置（`[opencode_cli]` 部分）。
`pacing`	用于慢速/本地 LLM 工作负载的速率控制（`[pacing]` 部分）。
`peer_groups`	Named peer groups (`[peer_groups.<name>]`). Each entry binds a
外围设备	外围板集成配置（`[peripherals]` 部分）。
`pipeline`	流水线工具配置（`[pipeline]` 部分）。
`插件`	插件系统配置。
`project_intel`	项目交付智能配置（`[project_intel]` 部分）。
`providers`	Top-level wrapper for every provider category. TOML root sees a
`代理`	出站 HTTP/HTTPS/SOCKS5 流量的代理配置（`[proxy]` 部分）。
`query_classification`	自动查询分类——通过关键词/模式对用户消息进行分类
`可靠性`	可靠性和监控配置（`[reliability]` 部分）。
`risk_profiles`	Named risk/autonomy profiles (`[risk_profiles.<alias>]`).
`运行时`	运行时适配器配置（`[runtime]` 部分）。
`runtime_profiles`	Named runtime/LLM execution profiles (`[runtime_profiles.<alias>]`).
`scheduler`	用于周期性任务执行的调度器配置（`[scheduler]` 部分）。
`schema_version`	配置文件模式版本。
`secrets`	加密配置（`[secrets]` 部分）。
`security`	Security configuration for audit logging, OTP, e-stop, IAM/SSO, and WebAuthn.
`security_ops`	托管式网络安全服务 (MCSS) 仪表板代理配置 (`[security_ops]`)。
`shell_tool`	Shell 工具配置（`[shell_tool]` 部分）。
`skill_bundles`	Named skill bundles (`[skill_bundles.<alias>]`).
`技能`	技能加载配置（`[skills]` 部分）。
`sop`	标准操作程序引擎配置（`[sop]`）。
`存储`	持久化存储配置（`[storage]` 部分）。
`text_browser`	文本浏览器工具配置（`[text_browser]` 部分）。
`转录`	支持多提供商的语音转录配置。
信任
`tts`	Text-to-Speech subsystem configuration (`[tts]`).
隧道	用于将网关公开暴露的隧道配置（`[tunnel]` 部分）。
`verifiable_intent`	可验证意图（VI）凭证的验证与签发（`[verifiable_intent]` 部分）。
`web_fetch`	Web 获取工具配置（`[web_fetch]` 部分）。
`web_search`	Web 搜索工具配置（`[web_search]` 部分）。

`acp`

ACP (Agent Client Protocol) server configuration ([acp] section).

键	类型	默认	描述
`default_agent`	任何	—	Agent alias to use when `session/new` omits `agentAlias` and more than
`max_sessions`	整数	`10`	Maximum number of concurrent ACP sessions. Default: `10`.
`session_timeout_secs`	整数	`3600`	Idle session timeout in seconds. Sessions with no activity for this

Aliased agents in this install. Each entry under [agents.<alias>] is one user-facing agent with its own identity, channels, model provider, risk profile, workspace, and memory scope. DelegateTool consults this map when one agent delegates a subtask to another.

`备份`

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

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

`浏览器`

浏览器自动化配置（[browser] 部分）。

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

键	类型	默认	描述
`allowed_domains`	字符串数组	`["*"]`	`browser_open` 允许的域名（精确匹配或子域名匹配）
`后端`	字符串	`"agent_browser"`	浏览器自动化后端：“agent_browser” \| “rust_native” \| “computer_use” \| “auto”
`computer_use`	对象	—	计算机使用侧车配置（`[browser.computer_use]` 部分）。
`enabled`	布尔	`true`	启用 `browser_open` 工具（在系统浏览器中打开 URL，不进行抓取）
`headed`	任何	`null`	Show browser window for agent_browser backend. When unset, inherits AGENT_BROWSER_HEADED.
`native_chrome_path`	任何	`null`	用于 rust-native 后端的可选 Chrome/Chromium 可执行文件路径
`native_headless`	布尔	`true`	适用于 Rust 原生后端的无头模式
`native_webdriver_url`	字符串	`"http://127.0.0.1:9515"`	用于 Rust 原生后端的 WebDriver 端点 URL（例如 `http://127.0.0.1:9515`）
`session_name`	任何	`null`	浏览器会话名称（用于代理浏览器自动化）

`browser.computer_use`

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

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

键	类型	默认	描述
`allow_remote_endpoint`	布尔	`false`	允许计算机使用旁路组件的远程/公共端点（默认值：false）
`api_key` 🔑	任何	`null`	用于计算机使用旁路组件的可选承载令牌
`endpoint`	字符串	`"http://127.0.0.1:8787/v1/actions"`	用于计算机使用操作的 Sidecar 端点（操作系统级别的鼠标/键盘/截图）
`max_coordinate_x`	任何	`null`	基于坐标的操作的可选 X 轴边界
`max_coordinate_y`	任何	`null`	基于坐标的操作的可选 Y 轴边界
`timeout_ms`	整数	`15000`	每个操作的请求超时时间（以毫秒为单位）
`window_allowlist`	字符串数组	`[]`	可选的窗口标题/进程允许列表，转发到边车策略

`browser_delegate`

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

`channels`

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

each channel type is a keyed table of named instances (aliases). [channels.telegram.default] is the conventional single-instance key. Access via config.channels.telegram.get("default").

键	类型	默认	描述
`ack_reactions`	布尔	`true`	是否添加确认反应（收到时显示 👀，✅/⚠️ 在
`bluesky`	映射	—	Bluesky channel instances (`[channels.bluesky.<alias>]`).
`clawdtalk`	映射	—	ClawdTalk voice channel instances (`[channels.clawdtalk.<alias>]`).
`cli`	布尔	`true`	启用 CLI 交互通道。默认值：`true`。
`debounce_ms`	整数	`0`	入站消息去抖窗口（毫秒）。当发送方触发
`dingtalk`	映射	—	DingTalk channel instances (`[channels.dingtalk.<alias>]`).
`discord`	映射	—	Discord bot channel instances (`[channels.discord.<alias>]`).
`email`	映射	—	Email channel instances (`[channels.email.<alias>]`).
`gmail_push`	映射	—	Gmail Pub/Sub push notification channel instances (`[channels.gmail_push.<alias>]`).
`imessage`	映射	—	iMessage channel instances (`[channels.imessage.<alias>]`, macOS only).
`irc`	映射	—	IRC channel instances (`[channels.irc.<alias>]`).
`lark`	映射	—	Lark channel instances (`[channels.lark.<alias>]`).
`line`	映射	—	LINE Messaging API channel instances (`[channels.line.<alias>]`).
`linq`	映射	—	Linq Partner API channel instances (`[channels.linq.<alias>]`).
`矩阵`	映射	—	Matrix channel instances (`[channels.matrix.<alias>]`).
`mattermost`	映射	—	Mattermost bot channel instances (`[channels.mattermost.<alias>]`).
`message_timeout_secs`	整数	`300`	处理单个通道消息（LLM + 工具）的基础超时时间（秒）。
`mochat`	映射	—	Mochat customer service channel instances (`[channels.mochat.<alias>]`).
`mqtt`	映射	—	MQTT channel instances (`[channels.mqtt.<alias>]`).
`nextcloud_talk`	映射	—	Nextcloud Talk bot channel instances (`[channels.nextcloud_talk.<alias>]`).
`nostr`	映射	—
`qq`	映射	—	QQ Official Bot channel instances (`[channels.qq.<alias>]`).
`reddit`	映射	—	Reddit channel instances (`[channels.reddit.<alias>]`).
`session_backend`	字符串	`"sqlite"`	会话持久化后端：`"jsonl"`（旧版）或 `"sqlite"`（新版默认）。
`session_persistence`	布尔	`true`	将频道对话历史持久化到 JSONL 文件中，以便会话能够持续存在
`session_ttl_hours`	整数	`0`	自动归档超过此小时数的过期会话。`0` 表示禁用。默认值：`0`。
`show_tool_calls`	布尔	`false`	是否发送工具调用通知消息（例如 `🔧 web_search_tool: …`）
`信号`	映射	—	Signal channel instances (`[channels.signal.<alias>]`).
`slack`	映射	—	Slack bot channel instances (`[channels.slack.<alias>]`).
`telegram`	映射	—	Telegram bot channel instances (`[channels.telegram.<alias>]`).
`twitter`	映射	—	X/Twitter channel instances (`[channels.twitter.<alias>]`).
`语音通话`	映射	—	Voice call channel instances (`[channels.voice_call.<alias>]`).
`voice_duplex`	映射	—	Voice duplex instances (`[channels.voice_duplex.<alias>]`).
`voice_wake`	映射	—	Voice wake word detection channel instances (`[channels.voice_wake.<alias>]`).
`wati`	映射	—	WATI WhatsApp Business API channel instances (`[channels.wati.<alias>]`).
`webhook`	映射	—	Webhook channel instances (`[channels.webhook.<alias>]`).
`wechat`	映射	—	WeChat personal iLink Bot channel instances (`[channels.wechat.<alias>]`).
`wecom`	映射	—	WeCom (WeChat Enterprise) Bot Webhook channel instances (`[channels.wecom.<alias>]`).
`wecom_ws`	映射	—	WeCom AI Bot WebSocket channel instances (`[channels.wecom_ws.<alias>]`).
`whatsapp`	映射	—	WhatsApp channel instances (`[channels.whatsapp.<alias>]`).

`claude_code`

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

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

键	类型	默认	描述
`allowed_tools`	字符串数组	`["读取","编辑","Bash","写入"]`	Claude Code 工具中子进程允许使用的内容
`enabled`	布尔	`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，并通过 HTTP 钩子将工具执行事件 POST 到 ZeroClaw 的网关，实时更新 Slack 消息中的进度以及 SSH 交接链接。

键	类型	默认	描述
`enabled`	布尔	`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`	数字	`100.0`	用于标记成本项的每月美元阈值。默认值：100.0。
`default_cloud`	字符串	`"aws"`	Default cloud model_provider for analysis context. Default: “aws”.
`enabled`	布尔	`false`	启用云操作工具。默认值：false。
`iac_tools`	字符串数组	`["terraform"]`	支持用于审查的 IaC 工具。默认值：[`terraform`]。
`supported_clouds`	字符串数组	`["aws","azure","gcp"]`	Supported cloud model_providers. Default: [`aws`, `azure`, `gcp`].
`well_architected_frameworks`	字符串数组	`["aws-waf"]`	用于检查的架构最佳实践框架。默认值：[`aws-waf`]。

`codex_cli`

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

将编码任务委托给 codex -q CLI。默认情况下，身份验证使用二进制文件自身的会话——除非 env_passthrough 包含 OPENAI_API_KEY，否则无需 API 密钥。

键	类型	默认	描述
`enabled`	布尔	`false`	启用 `codex_cli` 工具
`env_passthrough`	字符串数组	`[]`	传递给 codex 子进程的其他环境变量（例如 OPENAI_API_KEY）
`max_output_bytes`	整数	`2097152`	最大输出大小（以字节为单位，默认值为 2MB）
`timeout_secs`	整数	`600`	最大执行时间（秒）（编码任务可能耗时较长）

`composio`

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

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

键	类型	默认	描述
`api_key` 🔑	任何	`null`	Composio API 密钥（当 secrets.encrypt = true 时以加密形式存储）
`enabled`	布尔	`false`	启用 Composio 集成，支持 1000 多个 OAuth 工具
`entity_id`	字符串	`"默认"`	多用户设置中的默认实体 ID

`conversational_ai`

对话式 AI 代理构建器配置（[conversational_ai] 部分）。

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

键	类型	默认	描述
`analytics_enabled`	布尔	`false`	启用对话分析跟踪。默认值：false（默认隐私保护）。
`auto_detect_language`	布尔	`true`	自动从消息内容中检测用户语言。默认值：true。
`conversation_timeout_secs`	整数	`1800`	会话超时时间（秒，表示不活跃时间）。默认值：1800。
`default_language`	字符串	`"en"`	对话的默认语言（BCP-47 标签）。默认值：“en”。
`enabled`	布尔	`false`	启用对话式 AI 功能。默认值：false。
`escalation_confidence_threshold`	数字	`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`	布尔	`false`	允许通过 `--override` 标志（默认值：false）使请求超出预算
`daily_limit_usd`	数字	`10.0`	每日支出限额（以美元计，默认值：10.00）
`enabled`	布尔	`true`	启用成本跟踪（默认：true）
`enforcement`	对象	—	当达到预算限制时，用于成本强制执行行为的配置。
`monthly_limit_usd`	数字	`100.0`	每月支出上限（以美元计，默认值：100.00）
`rates`	对象	—	`[cost.rates]` — top-level rate-sheet namespace. Mirrors the
`track_per_agent`	布尔	`true`	Stamp each recorded cost entry with the originating agent alias so
`warn_at_percent`	整数	`80`	当支出达到此百分比限制时发出警告（默认值：80）

`成本执行`

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

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

`cost.rates`

[cost.rates] — top-level rate-sheet namespace. Mirrors the [providers.*] shape so each subsection here points at the same kind of resource its [providers.*] counterpart configures.

键	类型	默认	描述
`providers`	对象	—	`[cost.rates.providers.*]` — provider-shaped rate sheets. Each field
`tools`	映射	`{}`	`[cost.rates.tools.<name>]` — per-call rates for tools that

`cost.rates.providers`

[cost.rates.providers.*] — provider-shaped rate sheets. Each field here mirrors a corresponding field on [providers.*] with the trailing alias segment replaced by the resource the rate prices. The inner typed wrappers carry the per-provider-type slot layout and own dispatch (their slot list is the single source of truth, shared with their providers counterpart via the for_each_*_provider_slot! macros in [crate::providers]).

键	类型	默认	描述
`models`	对象	—	`[cost.rates.providers.models.<type>.<model>]` — token-cost rates
`转录`	对象	—	`cost.rates.providers.transcription.<type>.<model>`
`tts`	对象	—	`cost.rates.providers.tts.<type>.<voice>`

`cron`

Declarative cron jobs ([cron.<alias>]), alias-keyed.

Each entry is a named scheduled job synced into the database at scheduler startup. Subsystem runtime knobs (enable/disable, catch-up, run-history retention) live on [scheduler].

`data_retention`

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

键	类型	默认	描述
`categories`	字符串数组	`[]`	将保留策略的执行限制到特定的数据类别（空值表示所有类别）。
`dry_run`	布尔	`false`	预览将被删除的内容，而不会实际删除任何内容。
`enabled`	布尔	`false`	启用 `data_management` 工具。
`retention_days`	整数	`90`	在数据被清除之前保留的天数。

`delegate`

全局委托工具配置，用于设置默认超时值。

键	类型	默认	描述
`agentic_timeout_secs`	整数	`300`	代理子代理运行的默认超时时间（以秒为单位）。
`timeout_secs`	整数	`120`	Default timeout in seconds for non-agentic sub-agent model_provider calls.

`embedding_routes`

Embedding-routing rules — route hint:<name> to specific model_provider + model combos for embedding requests.

`escalation`

Escalation routing configuration ([escalation] section).

Controls which channels receive alert notifications when escalate_to_human is called with high or critical urgency. Channels are identified by name (e.g. "telegram", "slack"). Alerts are sent best-effort and do not block the escalation.

键	类型	默认	描述
`alert_channels`	字符串数组	`[]`	Channel names to alert on high/critical escalations (default: empty).

`file_download`

Standalone file download tool configuration ([file_download]).

When url is set to a non-empty value, registers a file_download tool that GETs a file from the configured endpoint and writes it to the agent’s workspace filesystem. The LLM supplies only a document identifier and a workspace-relative destination path; the endpoint URL comes solely from this config and is never model-controlled. Response bytes are streamed to disk and never loaded into model context.

When url is None or empty, the tool is not registered.

键	类型	默认	描述
`headers`	映射	`{}`	Static HTTP headers attached to every download request — typically an
`max_file_size_bytes`	整数	`26214400`	Maximum download size in bytes. Enforced while streaming: the transfer
`timeout_secs`	整数	`120`	Request timeout in seconds. Default: 120.
`url`	任何	`null`	Download endpoint URL. Tool is disabled when this is `None` or empty.

`file_upload`

Standalone file upload tool configuration ([file_upload]).

When url is set to a non-empty value, registers a file_upload tool that POSTs files from the agent’s local filesystem to the configured endpoint using multipart/form-data. The LLM provides only a file path; the host reads the bytes and uploads them without ever including file content in the model context.

When url is None or empty, the tool is not registered.

键	类型	默认	描述
`field_name`	字符串	`"file"`	Multipart form-field name for the file part. Default: `file`.
`headers`	映射	`{}`	Static HTTP headers attached to every upload request. Same shape as
`max_file_size_bytes`	整数	`26214400`	Maximum file size in bytes. Larger files are rejected before any
`method`	字符串	`"POST"`	HTTP method. Only `POST` (default) and `PUT` are accepted.
`timeout_secs`	整数	`60`	Request timeout in seconds. Default: 60.
`url`	任何	`null`	Upload endpoint URL. Tool is disabled when this is `None` or empty.

`file_upload_bundle`

Standalone multi-file bundle upload tool configuration ([file_upload_bundle]).

When url is set to a non-empty value, registers a file_upload_bundle tool that POSTs N files from the agent’s local filesystem to the configured endpoint as a single multipart/form-data request. The LLM provides only file paths; the host reads the bytes.

When url is None or empty, the tool is not registered.

键	类型	默认	描述
`field_name`	字符串	`"file"`	Multipart form-field name reused across every file part. Default: `file`.
`headers`	映射	`{}`	Static HTTP headers attached to every upload request.
`max_file_size_bytes`	整数	`10485760`	Maximum per-file size in bytes. Default: 10 MiB.
`max_files`	整数	`16`	Maximum number of files per call. Default: 16.
`max_response_body_bytes`	整数	`4096`	Maximum response body bytes to read from the upload endpoint.
`max_total_size_bytes`	整数	`33554432`	Maximum cumulative size across every file in one call. Default: 32 MiB.
`method`	字符串	`"POST"`	HTTP method. Only `POST` (default) and `PUT` are accepted.
`timeout_secs`	整数	`120`	Request timeout in seconds. Default: 120.
`url`	任何	`null`	Upload endpoint URL. Tool is disabled when this is `None` or empty.

`网关`

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

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

键	类型	默认	描述
`allow_public_bind`	布尔	`false`	允许绑定到非 localhost 地址而无需隧道（默认值：false）
`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`	HTTP request timeout (seconds) for `POST /api/cron/{id}/run`, which
`pair_rate_limit_per_minute`	整数	`10`	每个客户端密钥每分钟最大 `/pair` 请求数。
`paired_tokens` 🔑	字符串数组	`[]`	配对的承载令牌（自动管理，非用户编辑）
`配对仪表板`	对象	—	配对仪表板配置（`[gateway.pairing_dashboard]`）。
`path_prefix`	任何	`null`	反向代理部署的可选 URL 路径前缀。
`端口`	整数	`42617`	网关端口（默认值：42617）
`rate_limit_max_keys`	整数	`10000`	网关速率限制器映射跟踪的最大不同客户端密钥数。
`request_timeout_secs`	整数	`30`	HTTP request timeout (seconds) for gateway routes other than the
`require_pairing`	布尔	`true`	在接收请求前要求配对（默认：true）
`session_persistence`	布尔	`true`	将网关 WebSocket 聊天会话持久化到 SQLite。默认值：true。
`session_ttl_hours`	整数	`0`	自动归档超过 N 小时未活动的网关会话。0 表示禁用。默认值：0。
`tls`	对象	—	网关服务器的 TLS 配置（`[gateway.tls]`）。
`trust_forwarded_headers`	布尔	`false`	信任代理转发的客户端 IP 头（`X-Forwarded-For`、`X-Real-IP`）。
`web_dist_dir`	任何	`null`	Web 仪表板 `dist` 目录的路径。设置后，网关
`webhook_rate_limit_per_minute`	整数	`60`	每个客户端密钥每分钟 `/webhook` 请求的最大数量。

`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`	对象	—	客户端证书认证（mTLS）配置（`[gateway.tls.client_auth]`）。
`enabled`	布尔	`false`	为网关启用 TLS（默认值：false）。
`key_path`*	字符串	—	PEM 编码的服务器私钥文件的路径。

`gateway.tls.client_auth`

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

键	类型	默认	描述
`ca_cert_path`	字符串	`""`	用于验证客户端证书的 PEM 编码 CA 证书的路径。
`enabled`	布尔	`false`	启用客户端证书验证（默认值：false）。
`pinned_certs`	字符串数组	`[]`	用于证书固定的可选 SHA-256 指纹。
`require_client_cert`	布尔	`true`	拒绝未提供有效客户端证书的连接（默认值：true）。

`gemini_cli`

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

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

键	类型	默认	描述
`enabled`	布尔	`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`	对象[]	`[]`	限制代理可以访问的资源/方法组合。
`allowed_services`	字符串数组	`[]`	限制智能体可以访问的 Google Workspace 服务。
`audit_log`	布尔	`false`	启用对每次 `gws` 调用（服务、资源、
`credentials_path`	任何	`null`	服务账户 JSON 文件或 OAuth 客户端凭证文件的路径。
`默认账户`	任何	`null`	传递给 `gws --account` 的默认 Google 账户邮箱。
`enabled`	布尔	`false`	启用 `google_workspace` 工具。默认值：`false`。
`rate_limit_per_minute`	整数	`60`	每分钟允许的最大 `gws` API 调用次数。默认值：`60`。
`timeout_secs`	整数	`30`	命令执行的超时时间（秒）。默认值：`30`。

`硬件`

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

键	类型	默认	描述
`波特率`	整数	`115200`	Baud rate negotiated on the serial link. 115200 matches the common Arduino / ESP32 bootloader default; bump to 230400+ when your firmware explicitly supports faster rates and you need the throughput.
`enabled`	布尔	`false`	Opt in to direct physical-hardware control — GPIO pins, USB-tethered microcontrollers (Arduino, ESP32, Nucleo), or SWD/JTAG debug probes. Leave off for software-only use; turning it on without the right transport configured does nothing.
`probe_target`	任何	`null`	Target chip identifier for `transport = probe` (e.g. `STM32F401RE`, `nRF52840_xxAA`). Passed straight to probe-rs for flash/debug operations; must match a chip probe-rs recognizes.
`serial_port`	任何	`null`	TTY path for the `serial` transport — e.g. `/dev/ttyACM0` on Linux, `/dev/tty.usbmodem1` on macOS, `COM3` on Windows. Ignored for other transports.
`transport`	`None` \| `Native` \| `Serial` \| `Probe`	—	硬件传输模式。
`workspace_datasheets`	布尔	`false`	Index PDF schematics and datasheets from the workspace into a local RAG store, so the agent can look up pin assignments and electrical specs inline when you ask hardware questions. Off by default — turn on once the workspace has relevant PDFs dropped in.

心跳

用于定期健康检查的 heartbeat 配置（[heartbeat] 部分）。

键	类型	默认	描述
`自适应`	布尔	`false`	启用自适应间隔，在失败时退避，并在成功时加速
`agent`	字符串	`""`	Configured agent alias the heartbeat worker runs as. Required
`deadman_channel`	任何	`null`	用于死手开关警报的通道（例如 `telegram`）。回退到
`deadman_timeout_minutes`	整数	`0`	死开关超时（分钟）。如果心跳未触发
`deadman_to`	任何	`null`	死手开关警报的接收者。回退到 `to`。
`enabled`	布尔	`false`	Enable periodic heartbeat pings. Default: `false`. When enabled,
`interval_minutes`	整数	`30`	心跳 ping 之间的间隔（以分钟为单位）。最小值：`1`。默认值：`30`。
`load_session_context`	布尔	`false`	在每个心跳任务执行之前加载通道会话历史
`max_interval_minutes`	整数	`120`	自适应模式退避时的最大间隔（分钟）。默认值：`120`。
`max_run_history`	整数	`100`	要保留的心跳运行历史记录的最大数量。默认值：`100`。
`消息`	任何	`null`	当 `HEARTBEAT.md` 没有任务条目时，可选的回退任务文本。
`min_interval_minutes`	整数	`5`	启用自适应模式时的最小间隔（以分钟为单位）。默认值：`5`。
`target`	任何	`null`	心跳输出的可选传递通道（例如：`telegram`）。
`task_timeout_secs`	整数	`600`	单个代理调用允许的最大墙钟秒数
`to`	任何	`null`	可选的收件人/聊天标识符（当 `target` 为
`two_phase`	布尔	`true`	启用两阶段心跳：第一阶段询问 LLM 是否运行，第二阶段

`hooks`

键	类型	默认	描述
`builtin`	对象	—
`enabled`*	布尔	—	启用生命周期钩子执行。

`hooks.builtin`

键	类型	默认	描述
`command_logger`*	布尔	—	启用命令记录器钩子（记录工具调用以进行审计）。
`webhook_audit`	对象	—	webhook-audit 内置钩子的配置。

`hooks.builtin.webhook_audit`

webhook-audit 内置钩子的配置。

每当工具调用匹配配置的某个模式时，向外部端点发送带有 JSON 主体的 HTTP POST 请求。适用于集中式审计日志记录、SIEM 数据摄入或合规性管道。

键	类型	默认	描述
`enabled`	布尔	`false`	启用 webhook-audit 钩子。默认值：`false`。
`include_args`	布尔	`false`	在审计负载中包含工具调用参数。默认值：`false`。
`max_args_bytes`	整数	`4096`	单个
`tool_patterns`	字符串数组	`[]`	用于审计的工具名称的 Glob 模式（例如 `["Bash", "Write"]`）。
`url`	字符串	`""`	接收审计 POST 请求的目标 URL。

`http_request`

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

域名过滤：allowed_domains 控制哪些主机可以访问（使用 ["*"] 表示所有公共主机，这是默认值）。如果 allowed_domains 为空，则所有请求都会被拒绝。

键	类型	默认	描述
`allow_private_hosts`	布尔	`false`	允许向私有/LAN 主机（RFC 1918、回环、链路本地、.local）发起请求。
`allowed_domains`	字符串数组	`[]`	允许用于 HTTP 请求的域名（精确匹配或子域名匹配）
`enabled`	布尔	`false`	启用 `http_request` 工具以进行 API 交互
`max_response_size`	整数	`1000000`	最大响应大小（以字节为单位）（默认值：1MB，0 = 无限制）
`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`	布尔	`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 uses HTTP Basic auth: email + api_token. Jira Server/Data Center uses Bearer token auth: omit email and set api_token to a personal access token. api_token is stored encrypted at rest; set it here or via JIRA_API_TOKEN.

键	类型	默认	描述
`allowed_actions`	字符串数组	`["get_ticket"]`	允许智能体调用的操作。
`api_token` 🔑	字符串	`""`	Jira API 令牌。在静态时加密。回退到 `JIRA_API_TOKEN` 环境变量。
`base_url`	字符串	`""`	Atlassian 实例的基础 URL，例如 `https://yourco.atlassian.net`。
`email`	任何	—	Jira account email used for Basic auth (Cloud).
`enabled`	布尔	`false`	启用 `jira` 工具。默认值：`false`。
`timeout_secs`	整数	`30`	请求超时时间（秒）。默认值：`30`。

`知识`

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

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

`knowledge_bundles`

Named knowledge bundles ([knowledge_bundles.<alias>]).

`link_enricher`

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

启用后，传入消息中的 URL 将被自动抓取并生成摘要。该摘要会附加在消息之前，供代理在处理消息前使用，从而让大语言模型（LLM）获得链接页面的上下文信息，而无需显式调用工具。

键	类型	默认	描述
`enabled`	布尔	`false`	启用链接增强管道阶段（默认：false）
`max_links`	整数	`3`	每条消息最多获取的链接数（默认值：3）
`timeout_secs`	整数	`10`	每个链接的获取超时时间（秒）（默认值：10）

`linkedin`

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

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

键	类型	默认	描述
`api_version`	字符串	`"202602"`	LinkedIn REST API 版本头（YYYYMM 格式）。
`content`	对象	—	LinkedIn 自动发布的内容策略配置（`[linkedin.content]`）。
`enabled`	布尔	`false`	启用 LinkedIn 工具。
`image`	对象	—	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 订阅源 URL（仅标题）。
`topics`	字符串数组	`[]`	用于帖子主题的专业领域和兴趣点。

`linkedin.image`

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

键	类型	默认	描述
`card_accent_color`	字符串	`"#0A66C2"`	备用卡片的强调色（CSS 十六进制值）。
`dalle`	对象	—	OpenAI DALL-E 设置（`[linkedin.image.dalle]`）。
`enabled`	布尔	`false`	为帖子启用图像生成功能。
`fallback_card`	布尔	`true`	Generate a branded SVG text card when all AI model_providers fail.
`flux`	对象	—	Flux (fal.ai) 图像生成设置 (`[linkedin.image.flux]`)。
`imagen`	对象	—	Google Imagen（Vertex AI）设置（`[linkedin.image.imagen]`）。
`providers`	字符串数组	`["stability","imagen","dalle","flux"]`	ModelProvider priority order. Tried in sequence; first success wins.
`稳定性`	对象	—	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 密钥的环境变量名称。
`模型`	字符串	`"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 密钥的环境变量名称。
`模型`	字符串	`"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 密钥的环境变量名称。
`模型`	字符串	`"stable-diffusion-xl-1024-v1-0"`	稳定性模型标识符。

`locale`

工具描述的语言环境（例如 "en"、"zh-CN"）。

设置后，系统提示中显示的工具描述将从 Fluent .ftl 区域设置文件中加载。如果未找到，则回退到内嵌的英文描述，再回退到硬编码的描述。

如果省略或为空，则从 ZEROCLAW_LOCALE、LANG 或 LC_ALL 环境变量中自动检测区域设置（默认为 "en"）。

`mcp`

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

键	类型	默认	描述
`延迟加载`	布尔	`true`	通过 `tool_search` 按需加载 MCP 工具模式，而不是提前加载
`enabled`	布尔	`false`	启用 MCP 工具加载。
`servers`	对象[]	`[]`	Configured MCP servers. The `#[nested]` annotation makes the macro

`mcp_bundles`

Named MCP server bundles ([mcp_bundles.<alias>]).

`media_pipeline`

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

启用后，到达代理之前的入站频道消息中的媒体附件会经过预处理：音频会被转录，图像会被标注，视频会被摘要。

键	类型	默认	描述
`describe_images`	布尔	`true`	当启用支持视觉的模型时，添加图片描述。
`enabled`	布尔	`false`	媒体管道的总开关（默认值：false）。
`summarize_video`	布尔	`true`	总结视频附件（占位符 — 需要外部 API）。
`transcribe_audio`	布尔	`true`	Transcribe audio attachments using the configured transcription model_provider.

`memory`

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

Controls conversation memory storage, embeddings, hybrid search, response caching, and memory snapshot/hydration. Backend-specific connection settings live under [storage.<backend>.<alias>]; this section selects which storage instance to use via the backend dotted reference.

键	类型	默认	描述
`archive_after_days`	整数	`7`	Move daily/session files to the archive directory after this many days. Keeps the hot working set small without deleting history.
`audit_enabled`	布尔	`false`	启用内存操作的审计日志记录。
`audit_retention_days`	整数	`30`	审计条目的保留天数（默认值：30）。
`auto_hydrate`	布尔	`true`	当 `brain.db` 缺失时，从 `MEMORY_SNAPSHOT.md` 自动重新水合
`auto_save`	布尔	`true`	Auto-save what you tell ZeroClaw into memory as conversation history — the agent’s own replies are not saved. Turn off if you want memory to only hold things you explicitly record via the memory tool.
`后端`*	字符串	—	Dotted reference to the active storage instance: `<backend>.<alias>`
`chunk_max_tokens`	整数	`512`	文档拆分时每个块的最大令牌数
`conflict_threshold`	数字	`0.85`	用于冲突检测的余弦相似度阈值（0.0–1.0）。
`conversation_retention_days`	整数	`30`	For the sqlite backend only — drop conversation rows older than this many days to keep the DB lean. Doesn’t touch core memories or notes.
`default_namespace`	字符串	`"默认"`	内存条目的默认命名空间。
`embedding_cache_size`	整数	`10000`	在 LRU 驱逐之前，最大嵌入缓存条目数
`embedding_dimensions`	整数	`1536`	Vector width produced by the embedding model — must match the model’s native dimension or vectors won’t store correctly. Look up the number on the model_provider’s model page.
`embedding_model`	字符串	`"text-embedding-3-small"`	Embedding model identifier — must match a model your chosen embedding model_provider serves (e.g. `text-embedding-3-small` for OpenAI). Changing this invalidates existing embeddings; you’ll need to re-index.
`embedding_provider`	字符串	`"none"`	Source of embedding vectors for semantic search. `none` = keyword-only retrieval (no API calls, no vector cost); `openai` = OpenAI’s embedding API; `custom:URL` = any OpenAI-compatible embedding endpoint (LiteLLM, local gateway, etc.).
`fts_early_return_score`	数字	`0.85`	全文检索（FTS）分数阈值，超过该值时将提前返回，不再执行向量搜索（0.0–1.0）。
`hygiene_enabled`	布尔	`true`	Run the periodic hygiene pass that archives stale daily/session files and enforces retention windows. Leave on unless you want to manage cleanup yourself.
`keyword_weight`	数字	`0.3`	How heavily BM25 (keyword) overlap counts when `search_mode = hybrid`. Raise toward 1.0 for exact-term matching; lower it when paraphrases should still score well.
`min_relevance_score`	数字	`0.4`	包含在上下文中的内存的最小混合分数（0.0–1.0）。
`策略`	对象	—	内存策略配置（`[memory.policy]` 部分）。
`purge_after_days`	整数	`30`	Delete archived files permanently after this many days. Set high if you need long-term history; set low for privacy / disk-space reasons.
`rerank_enabled`	布尔	`false`	当候选数量超过阈值时启用 LLM 重排序。
`rerank_threshold`	整数	`5`	触发重新排序的最小候选数量。
`response_cache_enabled`	布尔	`false`	启用 LLM 响应缓存以避免为重复提示付费
`response_cache_hot_entries`	整数	`256`	两级响应缓存的最大内存热缓存条目数（默认值：256）
`response_cache_max_entries`	整数	`5000`	在 LRU 淘汰之前缓存响应的最大数量（默认值：5000）
`response_cache_ttl_minutes`	整数	`60`	缓存响应的 TTL（以分钟为单位）（默认值：60）
`retrieval_stages`	字符串数组	`["缓存","全文搜索","向量"]`	按顺序执行的检索阶段。有效值：“cache”、“fts”、“vector”。
`search_mode`	任何	—	内存检索策略
`snapshot_enabled`	布尔	`false`	启用核心记忆的定期导出至 `MEMORY_SNAPSHOT.md`
`snapshot_on_hygiene`	布尔	`false`	在卫生检查阶段运行快照（心跳驱动）
`vector_weight`	数字	`0.7`	How heavily vector (semantic) similarity counts when `search_mode = hybrid`. Raise toward 1.0 to favor meaning-based matches; lower it to lean on keyword overlap instead.

`memory.policy`

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

键	类型	默认	描述
`max_entries_per_category`	整数	`0`	每个类别的最大条目数（0 = 无限制）。
`max_entries_per_namespace`	整数	`0`	每个命名空间的最大条目数（0 = 无限制）。
`read_only_namespaces`	字符串数组	`[]`	只读命名空间（写入操作将被拒绝）。
`按类别保留天数`	映射	`{}`	按类别保留的天数（覆盖全局设置）。键值包括：“core”、“daily”、“conversation”。

`microsoft365`

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

提供对 Outlook 邮件、Teams 消息、日历事件、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`	布尔	`false`	启用 Microsoft 365 集成
`scopes`	字符串数组	`["https://graph.microsoft.com/.default"]`	要请求的 OAuth 作用域
`tenant_id`	任何	`null`	Azure AD 租户 ID
`token_cache_encrypted`	布尔	`true`	加密磁盘上的令牌缓存文件
`user_id`	任何	`null`	用户主体名称或“me”（用于委派流程）

`model_routes`

Model-routing rules — route hint:<name> to specific model_provider + model combos.

`多模态`

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

Privacy and cost note

Tool results that print real local image paths (e.g. shell tools doing ls /pictures or find . -name '*.png') are canonicalized into [IMAGE:...] markers and base64-inlined into the next provider request. This means image bytes that previously stayed local will be uploaded to the configured provider when surfaced by a tool.

max_images (and the trim_old_images LRU policy) bounds the per-request image budget, but operators running shell-style tools over directories of personal or sensitive images should be aware of the upload semantics. See docs/book/src/contributing/privacy.md for the project’s privacy stance.

键	类型	默认	描述
`allow_remote_fetch`	布尔	`false`	允许获取远程图片 URL（http/https）。默认禁用。
`max_image_size_mb`	整数	`5`	在进行 base64 编码之前，最大图像负载大小（以 MiB 为单位）。
`max_images`	整数	`4`	每个请求允许的最大图片附件数量。
`vision_model`	任何	`null`	Model to use when routing to the vision model_provider (e.g. `"llava:7b"`).
`vision_model_provider`	任何	`null`	ModelProvider name to use for vision/image messages (e.g. `"ollama"`).

`node_transport`

节点间通信的安全传输配置（[node_transport]）。

键	类型	默认	描述
`allowed_peers`	字符串数组	`[]`	允许特定的节点 IP/CIDR。
`connection_pool_size`	整数	`4`	每个对等节点的最大连接数。
`enabled`	布尔	`true`	启用安全传输层。
`max_request_age_secs`	整数	`300`	签名请求的最大有效期（秒）（防重放保护）。
`mutual_tls`	布尔	`false`	要求客户端证书（双向 TLS）。
`require_https`	布尔	`true`	要求所有节点通信使用 HTTPS。
`shared_secret`	字符串	`""`	节点间 HMAC 认证使用的共享密钥。
`tls_cert_path`	任何	`null`	TLS 证书文件的路径。
`tls_key_path`	任何	`null`	TLS 私钥文件的路径。

`节点`

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

启用后，外部进程/设备可以通过 WebSocket 连接到 /ws/nodes，并在运行时声明其功能。

键	类型	默认	描述
`auth_token`	任何	`null`	用于节点身份验证的可选承载令牌。
`enabled`	布尔	`false`	启用动态节点发现端点。
`max_nodes`	整数	`16`	最大并发节点连接数。

`notion`

Notion 集成配置（[notion]）。

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

键	类型	默认
`api_key` 🔑	字符串	`""`
`database_id`	字符串	`""`
`enabled`	布尔	`false`
`input_property`	字符串	`"输入"`
`max_concurrent`	整数	`4`
`poll_interval_secs`	整数	`5`
`recover_stale`	布尔	`true`
`result_property`	字符串	`"结果"`
`status_property`	字符串	`"状态"`

可观测性

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

键	类型	默认	描述
`后端`*	字符串	—	“none” \| “log” \| “verbose” \| “prometheus” \| “otel”
`log_persistence`	字符串	`"rolling"`	Log persistence mode: “none” \| “rolling” \| “full”.
`log_persistence_max_entries`	整数	`200`	Maximum entries retained when `log_persistence = "rolling"`.
`log_persistence_path`	字符串	`"state/runtime-trace.jsonl"`	Log persistence file path. Relative paths resolve under workspace_dir.
`log_tool_io`	字符串	`"redacted"`	Tool I/O capture policy: “off” \| “redacted” \| “full”.
`log_tool_io_denylist`	字符串数组	`[]`	Tool names whose I/O is never logged beyond name + outcome + duration
`log_tool_io_truncate_bytes`	整数	`8192`	Truncate the captured tool input and output at this many bytes when
`otel_endpoint`	任何	`null`	OTLP 端点（例如 `"http://localhost:4318"`）。仅在 `backend = "otel"` 时使用。
`otel_headers`	任何	`null`	随每个 OTLP 导出请求发送的可选 HTTP 头（例如授权头）。
`otel_service_name`	任何	`null`	报告给 OTel collector 的服务名称。默认为 “zeroclaw”。

`onboard_state`

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

When enabled, each client engagement gets an isolated workspace with separate memory, audit, secrets, and tool restrictions. Opaque state the zeroclaw onboard flow writes so it can tell, on a re-run, which sections the user has already walked through at least once — which lets it offer “Reconfigure? [y/N]” skip gates instead of forcing users through every field again.

This is meta-state about the onboard process, not user-facing config.

键	类型	默认	描述
`completed_sections`	字符串数组	`[]`	Section keys the user has completed at least once via onboard.

`opencode_cli`

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

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

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

`pacing`

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

所有字段均为可选，默认值会保留现有行为。设置这些字段时，它们会扩展——而非替换——现有的超时和环路检测子系统。

键	类型	默认	描述
`loop_detection_enabled`	布尔	`true`	启用基于模式的循环检测（精确重复、乒乓、
`loop_detection_max_repeats`	整数	`3`	在首次出现之前，连续相同的工具+参数调用次数
`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`

Named peer groups ([peer_groups.<name>]). Each entry binds a channel, a list of member agents, and optional non-agent (external) members and a per-group blocklist. Mutual opt-in: two agents become peers only when both appear in the same group’s agents. Empty by default for single-agent installs. See crate::multi_agent::PeerGroupConfig.

外围设备

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

启用后，看板将成为智能体工具。

键	类型	默认	描述
`boards`	对象[]	`[]`	板级配置（nucleo-f401re、rpi-gpio 等）
`datasheet_dir`	任何	`null`	用于 RAG 检索的数据集文档路径（相对于工作区）。
`enabled`	布尔	`false`	启用外围设备支持（板子成为代理工具）

`pipeline`

流水线工具配置（[pipeline] 部分）。

键	类型	默认	描述
`allowed_tools`	字符串数组	`[]`	流水线步骤中允许使用的工具。引用了不在该列表中的工具的步骤
`enabled`	布尔	`false`	启用 `execute_pipeline` 元工具。
`max_steps`	整数	`20`	单次管道调用中允许的最大步骤数。

`插件`

插件系统配置。

键	类型	默认	描述
`auto_discover`	布尔	`false`	在启动时自动发现并加载插件
`enabled`	布尔	`false`	启用插件系统（默认：false）
`max_plugins`	整数	`50`	可加载的最大插件数量
`plugins_dir`	字符串	`"/home/runner/.zeroclaw/plugins"`	存储插件的目录
`security`	对象	—	插件签名验证配置（`[plugins.security]`）。

`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`	布尔	`false`	启用 project_intel 工具。默认值：false。
`include_git_data`	布尔	`true`	在报告中包含 git log 数据。默认值：true。
`include_jira_data`	布尔	`false`	在报告中包含 Jira 数据。默认值：false。
`jira_base_url`	任何	`null`	Jira 实例的基础 URL（如果 include_jira_data 为 true，则为必填项）。
`report_output_dir`	字符串	`"/home/runner/.zeroclaw/project-reports"`	生成报告的输出目录。
`风险敏感度`	字符串	`"medium"`	风险检测灵敏度：低、中、高。默认值：“medium”。
`templates_dir`	任何	`null`	可选的自定义模板目录。

`providers`

Top-level wrapper for every provider category. TOML root sees a single [providers] table with one sub-key per category:

[providers.models.anthropic.default]
api_key = "..."

[providers.tts.openai.default]
api_key = "..."

[providers.transcription.groq.default]
api_key = "..."

Each category keeps its own typed-slot internals (so per-family endpoints and extras stay validated at the type level); this wrapper just gives them a shared top-level home.

键	类型	默认	描述
`models`	对象	—	Typed model provider container — one slot per canonical model_provider type.
`转录`	对象	—	Typed transcription-provider container — one slot per STT family.
`tts`	对象	—	Typed TTS-provider container — one slot per TTS family. Mirrors

`providers.models`

Typed model provider container — one slot per canonical model_provider type.

Replaces the HashMap<String, HashMap<String, ModelProviderConfig>> with a typed struct so each family’s per-alias map carries its own typed config (with the family’s *Endpoint enum and family-specific extras visible at the type level).

TOML shape is preserved byte-identical: each named field deserializes from the same [model_providers.<type>.<alias>] block as before.

Adding a new model_provider family means: define the typed config in schema.rs, then add one row to for_each_model_provider_slot! — every helper picks up the new slot automatically.

键	类型	默认
`ai21`	映射	—
`aihubmix`	映射	—
`anthropic`	映射	—
`anyscale`	映射	—
`astrai`	映射	—
`atomic_chat`	映射	—
`avian`	映射	—
`azure`	映射	—
`baichuan`	映射	—
`baseten`	映射	—
`bedrock`	映射	—
`cerebras`	映射	—
`cloudflare`	映射	—
`cohere`	映射	—
`copilot`	映射	—
`custom`	映射	—
`deepinfra`	映射	—
`deepmyst`	映射	—
`deepseek`	映射	—
`doubao`	映射	—
`fireworks`	映射	—
`friendli`	映射	—
`gemini`	映射	—
`gemini_cli`	映射	—
`glm`	映射	—
`groq`	映射	—
`huggingface`	映射	—
`hunyuan`	映射	—
`hyperbolic`	映射	—
`kilocli`	映射	—
`lepton`	映射	—
`litellm`	映射	—
`llamacpp`	映射	—
`lmstudio`	映射	—
`minimax`	映射	—
`mistral`	映射	—
`moonshot`	映射	—
`nebius`	映射	—
`novita`	映射	—
`nscale`	映射	—
`nvidia`	映射	—
`ollama`	映射	—
`openai`	映射	—
`opencode`	映射	—
`openrouter`	映射	—
`osaurus`	映射	—
`ovh`	映射	—
`perplexity`	映射	—
`qianfan`	映射	—
`qwen`	映射	—
`reka`	映射	—
`sambanova`	映射	—
`sglang`	映射	—
`siliconflow`	映射	—
`stepfun`	映射	—
`synthetic`	映射	—
`telnyx`	映射	—
`together`	映射	—
`venice`	映射	—
`vercel`	映射	—
`vllm`	映射	—
`xai`	映射	—
`yi`	映射	—
`zai`	映射	—

`providers.transcription`

Typed transcription-provider container — one slot per STT family. Mirrors ModelProviders / TtsProviders. Closed set of 6 families: groq, openai, deepgram, assemblyai, google, local_whisper.

键	类型	默认
`assemblyai`	映射	—
`deepgram`	映射	—
`google`	映射	—
`groq`	映射	—
`local_whisper`	映射	—
`openai`	映射	—

`providers.tts`

Typed TTS-provider container — one slot per TTS family. Mirrors ModelProviders but smaller (TTS has a closed set of 5 families: openai, elevenlabs, google, edge, piper). No catch-all needed.

键	类型	默认
`edge`	映射	—
`elevenlabs`	映射	—
`google`	映射	—
`openai`	映射	—
`piper`	映射	—

`代理`

出站 HTTP/HTTPS/SOCKS5 流量的代理配置（[proxy] 部分）。

键	类型	默认	描述
`all_proxy`	任何	`null`	所有方案的备用代理 URL。
`enabled`	布尔	`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`	布尔	`false`	启用自动查询分类。默认值：`false`。
`规则`	对象[]	`[]`	按优先级顺序评估的分类规则。

`可靠性`

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

Controls model_provider retries, API key rotation, and channel restart backoff.

键	类型	默认	描述
`api_keys`	字符串数组	`[]`	用于在速率限制（429）错误时进行轮询轮换的其他 API 密钥。
`channel_initial_backoff_secs`	整数	`2`	通道/守护进程重启的初始退避时间。
`channel_max_backoff_secs`	整数	`60`	通道/守护进程重启的最大退避时间。
`provider_backoff_ms`	整数	`500`	Base backoff (ms) for model_provider retry delay.
`provider_retries`	整数	`2`	Retries per model_provider before bailing.
`scheduler_poll_secs`	整数	`15`	调度器轮询间隔（秒）。
`scheduler_retries`	整数	`2`	定时任务执行尝试的最大重试次数。

`risk_profiles`

Named risk/autonomy profiles ([risk_profiles.<alias>]).

`运行时`

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

键	类型	默认	描述
`docker`	对象	—	Docker 运行时配置（`[runtime.docker]` 部分）。
`kind`	字符串	`"native"`	运行时类型（`native` \| `docker`）。
`reasoning_effort`	任何	`null`	Optional reasoning effort for model_providers that expose a level control.
`reasoning_enabled`	任何	`null`	Global reasoning override for model_providers that expose explicit controls.

`runtime.docker`

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

键	类型	默认	描述
`allowed_workspace_roots`	字符串数组	`[]`	Docker 挂载验证的可选工作区根目录允许列表。
`cpu_limit`	任何	`1.0`	可选的 CPU 限制（`None` = 无显式限制）。
`image`	字符串	`"alpine:3.20"`	用于执行 shell 命令的运行时镜像。
`memory_limit_mb`	任何	`512`	可选的内存限制（以 MB 为单位）（`None` = 无显式限制）。
`mount_workspace`	布尔	`true`	将配置的工作区挂载到 `/workspace`。
`network`	字符串	`"none"`	Docker 网络模式（`none`、`bridge` 等）。
`read_only_rootfs`	布尔	`true`	以只读方式挂载根文件系统。

`runtime_profiles`

Named runtime/LLM execution profiles ([runtime_profiles.<alias>]).

`scheduler`

用于周期性任务执行的调度器配置（[scheduler] 部分）。

Owns the cron-runtime knobs: per-job declarations live on Config.cron: HashMap<String, CronJobDecl> (alias-keyed), while the scheduler loop’s runtime behavior (enabled, polling cap, catch-up) lives here.

键	类型	默认	描述
`在启动时追赶`	布尔	`true`	在调度器启动时运行所有过期的作业。默认值：`true`。
`enabled`	布尔	`true`	Enable the built-in scheduler loop. When false, no cron jobs run.
`max_concurrent`	整数	`4`	Maximum tasks executed in parallel within a single polling cycle.
`max_run_history`	整数	`50`	保留的历史 cron 运行记录的最大数量。默认值：`50`。
`max_tasks`	整数	`64`	Maximum number of persisted scheduled tasks per polling cycle.

`schema_version`

配置文件模式版本。

`secrets`

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

键	类型	默认	描述
`encrypt`	布尔	`true`	在 `config.toml` 中为 API 密钥和令牌启用加密

`security`

Security configuration for audit logging, OTP, e-stop, IAM/SSO, and WebAuthn.

Sandbox backend and resource limits live on per-agent risk profiles (see RiskProfileConfig::sandbox_* and RiskProfileConfig::max_*); the runtime resolves them via Config::active_risk_profile(agent_alias).

键	类型	默认	描述
`审计`	对象	—	审计日志配置
`estop`	映射	—	急停配置。
`nevis`	映射	—	Nevis IAM 集成配置。
`otp`	映射	—	安全 OTP 配置。
`webauthn`	对象	—	WebAuthn / FIDO2 硬件密钥身份验证配置（`[security.webauthn]`）。

`security.audit`

审计日志配置

键	类型	默认	描述
`enabled`	布尔	`true`	启用审计日志
`log_path`	字符串	`"audit.log"`	审计日志文件的路径（相对于 zeroclaw 目录）
`max_size_mb`	整数	`100`	日志文件在轮换前的最大大小（以 MB 为单位）
`sign_events`	布尔	`false`	使用 HMAC 对事件进行签名，以提供篡改证据

`security.estop`

急停配置。

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

`security.nevis`

Nevis IAM 集成配置。

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

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

`security.otp`

安全 OTP 配置。

键	类型	默认	描述
`cache_valid_secs`	整数	`300`	重用窗口以保存最近验证的 OTP 代码。
`challenge_max_attempts`	整数	`3`	在锁定之前，OTP 挑战尝试的最大次数。
`enabled`	布尔	`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`	布尔	`false`	启用 WebAuthn 认证。默认值：false。
`rp_id`	字符串	`"localhost"`	依赖方 ID（域名，例如 “example.com”）。默认值：“localhost”。
`rp_name`	字符串	`"ZeroClaw"`	依赖方显示名称。默认值：“ZeroClaw”。
`rp_origin`	字符串	`"http://localhost:42617"`	依赖方来源 URL（例如 `"https://example.com"`）。默认值：`"http://localhost:42617"`。

`security_ops`

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

键	类型	默认	描述
`auto_triage`	布尔	`false`	无需用户提示即可自动分类传入的警报。
`enabled`	布尔	`false`	启用安全操作工具。
`max_auto_severity`	字符串	`"低"`	可以自动修复而无需审批的最大严重性级别。
`playbooks_dir`	字符串	`"/home/runner/.zeroclaw/playbooks"`	包含事件响应剧本定义（JSON）的目录。
`report_output_dir`	字符串	`"/home/runner/.zeroclaw/security-reports"`	用于生成安全报告的目录。
`require_approval_for_actions`	布尔	`true`	在执行 playbook 操作之前，需要人工审批。
`siem_integration`	任何	`null`	可选的 SIEM Webhook URL，用于警报摄入。

`shell_tool`

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

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

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

`skill_bundles`

Named skill bundles ([skill_bundles.<alias>]).

`技能`

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

键	类型	默认	描述
`allow_scripts`	布尔	`false`	允许技能中包含脚本类文件（`.sh`、`.bash`、`.ps1`、shebang shell 文件）。
`install_suggestions`	对象	—	Prompt-triggered skill install suggestions (`[skills.install_suggestions]` section).
`open_skills_dir`	任何	`null`	可选的本地 open-skills 仓库路径。
`open_skills_enabled`	布尔	`false`	启用加载和同步社区开放技能仓库。
`prompt_injection_mode`	任何	—	技能加载配置（`[skills]` 部分）。
`registry_url`	任何	`null`	用于裸名安装的技能注册表仓库的 URL。
`skill_creation`	对象	—	自主技能创建配置（`[skills.skill_creation]` 部分）。
`技能提升`	对象	—	技能自我改进配置（`[skills.auto_improve]` 部分）。

`skills.install_suggestions`

Prompt-triggered skill install suggestions ([skills.install_suggestions] section).

键	类型	默认	描述
`enabled`	布尔	`false`	Enable suggestions for installable skills before normal agent turns.

`skills.skill_creation`

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

键	类型	默认	描述
`enabled`	布尔	`false`	在成功完成多步骤任务后启用自动技能创建。
`max_skills`	整数	`500`	保留的最大自动生成的技能数量。
`similarity_threshold`	数字	`0.85`	用于去重的嵌入相似度阈值。

`skills.skill_improvement`

技能自我改进配置（[skills.auto_improve] 部分）。

键	类型	默认	描述
`cooldown_secs`	整数	`3600`	同一技能改进之间的最小间隔（以秒为单位）。
`enabled`	布尔	`true`	在成功使用技能后启用自动技能提升。

`sop`

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

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

键	类型	默认	描述
`approval_timeout_secs`	整数	`300`	审批超时时间（秒）。当运行等待审批的时间超过
`default_execution_mode`	字符串	`"监督式"`	对于省略 `execution_mode` 的 SOP，其默认执行模式。
`max_concurrent_total`	整数	`4`	所有 SOP 的最大总并发运行次数。
`max_finished_runs`	整数	`100`	保留在内存中用于状态查询的最大完成运行次数。
`sops_dir`	任何	`null`	包含 SOP 定义的目录（带有 SOP.toml 和 SOP.md 的子目录）。

`存储`

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

Storage is a two-tier alias-keyed map: [storage.<backend>.<alias>], parallel to [model_providers.<type>.<alias>]. Each backend has its own typed config struct. MemoryConfig.backend carries a dotted reference ("sqlite.default", "postgres.work") that resolves to one of these entries via [Config::resolve_active_storage].

键	类型	默认	描述
`lucid`	映射	—	Lucid CLI sync instances (`[storage.lucid.<alias>]`).
`markdown`	映射	—	Markdown storage instances (`[storage.markdown.<alias>]`).
`postgres`	映射	—	PostgreSQL storage instances (`[storage.postgres.<alias>]`).
`qdrant`	映射	—	Qdrant storage instances (`[storage.qdrant.<alias>]`).
`sqlite`	映射	—	SQLite storage instances (`[storage.sqlite.<alias>]`).

`text_browser`

文本浏览器工具配置（[text_browser] 部分）。

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

键	类型	默认	描述
`enabled`	布尔	`false`	启用 `text_browser` 工具
`preferred_browser`	任何	`null`	首选文本浏览器（“lynx”、“links”或“w3m”）。如果未设置，则自动检测。
`timeout_secs`	整数	`30`	请求超时时间（秒，默认值：30）

`转录`

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

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

键	类型	默认	描述
`api_key` 🔑	任何	`null`	API key used for transcription requests (Groq transcription provider).
`api_url`	字符串	`"https://api.groq.com/openai/v1/audio/transcriptions"`	Whisper API endpoint URL (Groq transcription provider).
`assemblyai`	对象	—	AssemblyAI STT model_provider configuration (`[transcription.assemblyai]`).
`deepgram`	对象	—	Deepgram STT model_provider configuration (`[transcription.deepgram]`).
`enabled`	布尔	`false`	为支持该功能的频道启用语音转录。
`google`	对象	—	Google Cloud Speech-to-Text model_provider configuration (`[transcription.google]`).
`initial_prompt`	任何	`null`	可选的初始提示，用于使转录偏向预期的词汇
`language`	任何	`null`	Optional language hint (ISO-639-1, e.g. “en”, “ru”) for Groq transcription provider.
`local_whisper`	对象	—	本地/自托管的 Whisper 兼容的 STT 端点（`[transcription.local_whisper]`）。
`max_duration_secs`	整数	`120`	最大语音时长（以秒为单位），超过此长度的消息将被跳过。
`模型`	字符串	`"whisper-large-v3-turbo"`	Whisper model name (Groq transcription provider).
`openai`	对象	—	OpenAI Whisper STT model_provider configuration (`[transcription.openai]`).
`transcribe_non_ptt_audio`	布尔	`false`	同时转录 WhatsApp 上的非 PTT（转发/普通）音频消息，

`transcription.assemblyai`

AssemblyAI STT model_provider configuration ([transcription.assemblyai]).

键	类型	默认	描述
`api_key` 🔑	任何	`null`	AssemblyAI API 密钥。

`transcription.deepgram`

Deepgram STT model_provider configuration ([transcription.deepgram]).

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

`transcription.google`

Google Cloud Speech-to-Text model_provider configuration ([transcription.google]).

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

`transcription.local_whisper`

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

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

键	类型	默认	描述
`bearer_token` 🔑	任何	`null`	用于端点身份验证的 Bearer 令牌。
`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 model_provider configuration ([transcription.openai]).

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

信任

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

`tts`

Text-to-Speech subsystem configuration ([tts]).

Per-instance TTS configs live under [tts_providers.<type>.<alias>] (parallel to providers.models). What remains here are the global runtime knobs that apply to every model_provider invocation.

键	类型	默认	描述
`默认格式`	字符串	`"mp3"`	默认音频输出格式（`"mp3"`、`"opus"`、`"wav"`）。
`default_voice`	字符串	`"alloy"`	Default voice ID passed to the selected tts provider.
`enabled`	布尔	`false`	启用 TTS 合成。
`max_text_length`	整数	`4096`	最大输入文本长度（字符数，默认值为 4096）。

隧道

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

Supported model_providers: "none" (default), "cloudflare", "tailscale", "ngrok", "openvpn", "pinggy", "custom".

键	类型	默认	描述
`cloudflare`	对象	—
`custom`	对象	—
`ngrok`	对象	—
`openvpn`	对象	—	OpenVPN 隧道配置（`[tunnel.openvpn]`）。
`pinggy`	对象	—
`tailscale`	对象	—
`tunnel_provider`*	字符串	—	How the gateway gets exposed to the public internet so webhooks (Telegram, Slack, etc.) can reach it. `none` = keep it local, no tunnel; `cloudflare` = Cloudflare Tunnel via cloudflared (needs a Zero Trust account and token); `tailscale` = Tailscale Funnel/Serve (tailnet-only or public, no account beyond tailscale); `ngrok` = ngrok agent with auth token; `openvpn` = bring-your-own OpenVPN egress; `pinggy` = Pinggy SSH tunnels (quick one-shot URLs); `custom` = run an arbitrary command you define under `[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 认证令牌
`domain`	任何	`null`	可选的自定义域名

`tunnel.openvpn`

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

Required when tunnel.tunnel_provider = "openvpn". Omitting this section entirely preserves previous behavior. Setting tunnel.tunnel_provider = "none" (or removing the [tunnel.openvpn] block) cleanly reverts to no-tunnel mode.

默认值：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`

键	类型	默认	描述
漏斗	布尔	`false`	使用 Tailscale Funnel（公共互联网）与 Serve（仅限 Tailnet）
`hostname`	任何	`null`	可选的主机名覆盖

`verifiable_intent`

可验证意图（VI）凭证的验证与签发（[verifiable_intent] 部分）。

键	类型	默认	描述
`enabled`	布尔	`false`	在 commerce 工具调用中启用 VI 凭据验证（默认值：false）。
`严格性`	字符串	`"strict"`	约束评估的严格模式：“strict”（在未知时失败关闭）

`web_fetch`

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

抓取网页并将 HTML 转换为纯文本，以便 LLM 使用。域名过滤：allowed_domains 控制哪些主机可以访问（使用 ["*"] 表示所有公共主机）。blocked_domains 的优先级高于 allowed_domains。如果 allowed_domains 为空，则拒绝所有请求（默认拒绝）。

键	类型	默认	描述
`allowed_domains`	字符串数组	`["*"]`	允许用于 Web 获取的域名（精确或子域名匹配；`["*"]` = 所有公共主机）
`allowed_private_hosts`	字符串数组	`[]`	允许绕过 SSRF 保护的私有/内部主机（例如 `["192.168.1.10", "internal.local"]`）
`blocked_domains`	字符串数组	`[]`	被阻止的域名（精确或子域名匹配；始终优先于允许的域名）
`enabled`	布尔	`false`	启用 `web_fetch` 工具以获取网页内容
`firecrawl`	对象	—	用于 JS 密集型网站和反爬虫网站的 Firecrawl 回退配置。
`max_response_size`	整数	`500000`	最大响应大小（以字节为单位）（默认值：500KB，纯文本比原始 HTML 小得多）
`timeout_secs`	整数	`30`	请求超时时间（秒，默认值：30）

`web_fetch.firecrawl`

用于 JS 密集型网站和反爬虫网站的 Firecrawl 回退配置。

启用后，如果标准网页抓取失败（HTTP 错误、空响应体或响应体长度不足 100 个字符，表明可能是仅依赖 JavaScript 的页面），该工具将回退到使用 Firecrawl API 进行隐蔽内容提取。

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

`web_search`

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

键	类型	默认	描述
`brave_api_key` 🔑	任何	`null`	Brave Search API key (required if search_provider is “brave”)
`enabled`	布尔	`false`	启用 `web_search_tool` 以进行网络搜索
`max_results`	整数	`5`	每次搜索的最大结果数（1-10）
`search_provider`	字符串	`"duckduckgo"`	Search provider: “duckduckgo” (free), “brave” (requires API key), “tavily” (requires API key), or “searxng” (self-hosted)
`searxng_instance_url`	任何	`null`	SearXNG instance URL (required if search_provider is `"searxng"`), e.g. `"https://searx.example.com"`.
`tavily_api_key` 🔑	任何	`null`	Tavily Search API key (required if search_provider is “tavily”)
`timeout_secs`	整数	`15`	请求超时时间（秒）

Keyboard shortcuts

ZeroClaw Docs