ZeroClaw 配置项(config.toml)说明

因为配置项比较多，所以本文内容分为了精简的“速查版”和较完整的“完整版”。

速查版

ZeroClaw config.toml 配置项信息表（仅表格）

A. 配置加载与全局默认项

B. [observability]（可观测性 / Trace）

C. [agent]（Agent 行为控制）

D. [security.otp]（敏感操作二次验证）

E. [security.estop]（紧急停止）

F. [agents.*]（子 Agent / 委派角色）

G. [runtime]（运行时行为）

H. [skills]（技能系统）

I. [composio]（OAuth 工具接入）

J. [cost]（成本控制）

K. [identity]（身份文档格式）

L. [multimodal]（多模态输入）

M. [browser]（浏览器工具）

[browser.computer_use] 子表

N. [http_request]（HTTP 请求工具）

O. [gateway]（网关）

P. [autonomy]（自治级别与执行护栏）

Q. [memory]（记忆系统）

R. [[model_routes]]（模型路由表）

S. [[embedding_routes]]（向量路由表）

T. [query_classification]（自动路由分类）

rules[] 子字段

U. [channels_config]（渠道配置总入口）

渠道 Allowlist 语义

常见 Allowlist 字段名（因渠道不同）

渠道子表字段补全（官网 channels-reference.md）

V. Provider（常见项速查）

W. [hardware]（硬件向导配置）

X. [peripherals]（外设板卡配置）

[[peripherals.boards]] 子字段

完整版

1）config.toml 在哪里、怎么被加载

ZeroClaw 的官方配置参考写的是：配置解析优先级是：

1. ZEROCLAW_WORKSPACE（如果设置）
2. ~/.zeroclaw/active_workspace.toml（如果存在）
3. 默认 ~/.zeroclaw/config.toml

并且启动时会在 INFO 日志里打印已加载的配置路径（Config loaded）。官方还提供 zeroclaw config schema 命令导出完整 JSON Schema（适合做校验/补全）。

出处：

• docs/config-reference.md（官方配置参考）
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

2）核心顶层键（最常用）

官方 config-reference.md 先给了最核心的 3 个顶层键：

• default_provider：默认 provider（默认 openrouter）
• default_model：默认模型（默认 anthropic/claude-sonnet-4-6）
• default_temperature：默认温度（默认 0.7）

字段说明：

• default_provider：未被环境变量覆盖时的基础 provider 选择入口。
• default_model：默认模型标识；会由当前 provider 路由解析并发起请求。
• default_temperature：默认采样温度；值越低通常越稳定、越高通常越发散。

这些是最基础的“模型路由默认值”。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3）配置项详解（按分组）

3.1 [observability]（可观测性/追踪）

用途：日志、OTel/OTLP、运行时 trace 调试。

字段说明（含默认值）：

• backend：观测后端。默认 none，可选 none/noop/log/prometheus/otel/opentelemetry/otlp（后三者映射同一 OTel 后端）。
• otel_endpoint：OTLP HTTP 地址，默认 http://localhost:4318，仅 OTel 后端生效。
• otel_service_name：上报服务名，默认 zeroclaw。
• runtime_trace_mode：运行时 trace 模式，默认 none；可选 none/rolling/full。
• runtime_trace_path：trace 文件路径，默认 state/runtime-trace.jsonl（相对 workspace 解析）。
• runtime_trace_max_entries：rolling 模式保留条数，默认 200。

实务建议：

• runtime_trace_mode 很适合排查 tool call / 参数格式问题。
• trace 可能包含模型输出文本，共享环境谨慎开启。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.2 Provider 环境变量覆盖（优先级）

官方给了 provider 选择的覆盖优先级：

1. ZEROCLAW_PROVIDER（强制覆盖）
2. PROVIDER（兼容旧方式，只有配置未显式设置时才生效）
3. config.toml 里的 default_provider

变量说明：

• ZEROCLAW_PROVIDER：显式运行时覆盖位；非空时总是优先于配置文件。
• PROVIDER：兼容变量；只在 default_provider 未设置或仍是默认 openrouter 时参与覆盖。
• default_provider：配置文件内的常驻默认值，适合作为长期环境基线。

注意：

• 容器环境里如果注入了 PROVIDER，可能影响你预期的 provider 路由。
• 官方文档说明了新行为：显式自定义 provider 不会被默认 PROVIDER 误覆盖。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.3 [agent]（Agent 行为控制）

用途：控制 agent 的上下文长度、工具循环次数、并行工具等。

字段说明（含默认值）：

• compact_context：默认 false。开启后使用紧凑上下文策略（bootstrap_max_chars=6000、rag_chunk_limit=2）。
• max_tool_iterations：默认 10。单条消息工具循环上限（设为 0 会回退到 10）。
• max_history_messages：默认 50。会话历史消息保留上限。
• parallel_tools：默认 false。是否启用 Agent::turn() API 的并行工具调用。
• tool_dispatcher：默认 auto。工具分发策略入口。

注意点：

• max_tool_iterations = 0 会回退到默认值 10
• parallel_tools 更偏 API 层行为，不一定覆盖所有运行时路径

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.4 [security.otp]（OTP 安全门禁）

用途：对敏感操作加二次验证（如 shell、写文件、浏览器打开等）。

字段说明（含默认值）：

• enabled：是否启用 OTP 门禁，默认 false。
• method：OTP 方式，默认 totp，可选 totp/pairing/cli-prompt。
• token_ttl_secs：TOTP 时间窗口秒数，默认 30。
• cache_valid_secs：OTP 校验缓存窗口秒数，默认 300。
• gated_actions：需 OTP 的动作列表，默认 ["shell","file_write","browser_open","browser","memory_forget"]。
• gated_domains：需 OTP 的域名规则（支持 *），默认 []。
• gated_domain_categories：需 OTP 的预置域名分类，默认 []，支持 banking/medical/government/identity_providers。

注意点：

• 域名 glob 非法、分类名未知会在启动时报错（fail fast）
• 开启后如未配置 secret，会自动生成 enrollment URI

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.5 [security.estop]（紧急停止开关）

用途：紧急停机/阻断高风险动作。

字段说明（含默认值）：

• enabled：是否启用 E-Stop 状态机，默认 false。
• state_file：E-Stop 状态持久化路径，默认 ~/.zeroclaw/estop-state.json。
• require_otp_to_resume：恢复前是否要求 OTP，默认 true。

注意点：

• 状态会持久化、原子写入
• 状态文件损坏时采用更保守策略（fail-closed）

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.6 [agents.*]（子 Agent / 委派 Agent）

用途：配置多个角色子 agent（例如 researcher / coder）。

示例结构：

• [agents.researcher]
• [agents.coder]

字段说明（含默认值/必填）：

• provider：子 agent 的 provider（必填）。
• model：子 agent 的模型 ID（必填）。
• system_prompt：子 agent 专用 system prompt（可选）。
• api_key：子 agent 专用 API key 覆盖（可选）。
• temperature：子 agent 温度覆盖（可选）。
• max_depth：委派递归深度，默认 3。
• agentic：是否开启子 agent 多轮工具循环，默认 false。
• allowed_tools：子 agent 工具白名单，默认 []（agentic=true 时应配置）。
• max_iterations：子 agent 工具迭代上限，默认 10。

注意点：

• agentic = true 时应配置可用工具
• delegate 不会被允许放进子 agent allowlist（避免递归委派）

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.7 [runtime]（运行时行为）

用途：控制运行时行为（目前文档重点字段是推理/思考开关）。

字段说明（含默认值）：

• reasoning_enabled：全局推理覆盖开关。默认未设置（unset），仅对支持显式推理参数的 provider 生效。

行为（对支持的 provider 生效，如文档提到 ollama）：

• false → 发送 think: false
• true → 发送 think: true
• 不设置 → 使用 provider 默认行为

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.8 [skills]（技能系统）

用途：控制社区 open-skills 仓库和提示注入方式。

字段说明（含默认值）：

• open_skills_enabled：是否启用社区 open-skills，默认 false。
• open_skills_dir：open-skills 本地目录；启用但未设置时默认 $HOME/open-skills。
• prompt_injection_mode：技能注入模式，默认 full，可选 full/compact。

环境变量覆盖：

• ZEROCLAW_OPEN_SKILLS_ENABLED
• ZEROCLAW_OPEN_SKILLS_DIR
• ZEROCLAW_SKILLS_PROMPT_MODE

注意点：

• 默认不会 clone/sync 社区技能（安全优先）
• compact 模式适合上下文较小模型
• 技能加载/安装会做静态安全审计（文档有说明）

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.9 [composio]（OAuth 工具集成）

用途：接入 Composio 托管 OAuth 工具。

字段说明（含默认值）：

• enabled：是否启用 Composio，默认 false（兼容旧键 enable=true）。
• api_key：Composio API key（未配置时工具不会注册）。
• entity_id：默认实体标识，默认 default。

注意点：

• 兼容旧字段 enable = true
• enabled=false 或没 api_key 时，工具不会注册

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.10 [cost]（成本控制）

用途：预算/成本告警与硬限制。

字段说明（含默认值）：

• enabled：是否启用成本控制，默认 false。
• daily_limit_usd：日预算上限，默认 10.00。
• monthly_limit_usd：月预算上限，默认 100.00。
• warn_at_percent：预算告警阈值，默认 80。
• allow_override：超预算是否允许 --override 放行，默认 false。

行为：

• 达到告警阈值只提醒
• 达到硬限制则拒绝请求（除非允许 --override）

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.11 [identity]（身份文档格式）

用途：指定 identity 格式（兼容 OpenClaw/AIEOS）。

字段说明（含默认值）：

• format：身份文档格式，默认 openclaw，可设为 aieos。
• aieos_path：AIEOS JSON 路径（相对 workspace 解析）。
• aieos_inline：内联 AIEOS JSON（通常与 aieos_path 二选一；同时设置时 aieos_path 优先）。

注意点：

• aieos_path 和 aieos_inline 不建议同时设
• 同时设置时 aieos_path 优先

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.12 [multimodal]（多模态输入）

用途：控制图片输入限制（通过 [IMAGE:...] marker）。

字段说明（含默认值）：

• max_images：单请求图片 marker 上限，默认 4。
• max_image_size_mb：单图大小上限，默认 5 MB。
• allow_remote_fetch：是否允许远程 URL 拉图，默认 false。

官方说明：

• 支持本地文件、Data URI
• 远程 URL 只有 allow_remote_fetch = true 才允许
• provider 不支持 vision 时会返回结构化能力错误

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.13 [browser] + [browser.computer_use]（浏览器/桌面操作）

用途：browser_open 工具、浏览器后端选择、computer-use sidecar。

[browser] 字段说明（含默认值）

• enabled：是否启用 browser_open，默认 false。
• allowed_domains：浏览器访问白名单，默认 []（空即拒绝）。
• session_name：浏览器会话名（可选）。
• backend：浏览器后端，默认 agent_browser，可选 agent_browser/rust_native/computer_use/auto。
• native_headless：rust_native 无头模式，默认 true。
• native_webdriver_url：rust_native WebDriver 地址，默认 http://127.0.0.1:9515。
• native_chrome_path：Chrome/Chromium 可执行路径（可选）。

[browser.computer_use] 字段说明（含默认值）

• endpoint：computer-use sidecar 地址，默认 http://127.0.0.1:8787/v1/actions。
• api_key：sidecar 鉴权 token（可选）。
• timeout_ms：单动作超时，默认 15000。
• allow_remote_endpoint：是否允许远程 sidecar，默认 false。
• window_allowlist：窗口白名单，默认 []。
• max_coordinate_x：X 坐标上限（可选）。
• max_coordinate_y：Y 坐标上限（可选）。

重要安全点：

• allow_remote_endpoint = false（默认）会拒绝非 loopback 端点，防止误暴露公网

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.14 [http_request]（HTTP 请求工具）

用途：给 agent 提供 API 请求能力（http_request 工具）。

字段说明（含默认值）：

• enabled：是否启用 http_request，默认 false。
• allowed_domains：HTTP 域名白名单，默认 []（空即拒绝）。
• max_response_size：响应体上限（字节），默认 1000000。
• timeout_secs：请求超时秒数，默认 30。

关键安全语义：

• 默认拒绝所有（allowed_domains 为空即拒绝）
• "*" 可放开公网域名，但本地/私网目标仍会被拦截（官方文档说明）

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.15 [gateway]（网关）

用途：控制网关监听地址与配对策略。

字段说明（含默认值）：

• host：网关监听地址，默认 127.0.0.1。
• port：网关端口，默认 42617。
• require_pairing：是否要求配对后再 bearer 鉴权，默认 true。
• allow_public_bind：是否允许公网绑定，默认 false。

这组配置对团队部署/远程访问场景很关键。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.16 [autonomy]（自治级别与系统操作护栏）

用途：决定 agent 的执行权限和风险控制。

字段说明（含默认值）：

• level：自治级别，默认 supervised，可选 read_only/supervised/full。
• workspace_only：是否限制在工作区内，默认 true。
• allowed_commands：命令白名单（shell 执行必需项）。
• forbidden_paths：拒绝路径列表（默认含系统敏感路径与常见敏感目录）。
• allowed_roots：工作区外允许访问根路径，默认 []。
• max_actions_per_hour：每小时动作预算，默认 20。
• max_cost_per_day_cents：每日成本预算（美分），默认 500。
• require_approval_for_medium_risk：中风险审批开关，默认 true。
• block_high_risk_commands：高风险命令硬阻断，默认 true。
• auto_approve：自动审批列表，默认 []。
• always_ask：强制询问列表，默认 []。

官方说明重点：

• full 会跳过中风险 shell 审批（但仍有护栏）
• 即使 workspace_only = false，工作区外访问仍需要 allowed_roots
• shell 运算符解析带引号感知（降低误判/注入风险）

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.17 [memory]（记忆系统）

用途：记忆后端与向量/关键词混合检索设置。

字段说明（含默认值）：

• backend：记忆后端，默认 sqlite，可选 sqlite/lucid/markdown/none。
• auto_save：是否自动保存用户输入，默认 true。
• embedding_provider：向量 provider，默认 none，可设 openai 或 custom:<url>。
• embedding_model：向量模型，默认 text-embedding-3-small（也支持 hint:<name>）。
• embedding_dimensions：向量维度，默认 1536。
• vector_weight：向量分权重，默认 0.7。
• keyword_weight：关键词分权重，默认 0.3。

官方提示：

• 部分旧版 assistant 自动总结字段会被忽略（避免误把模型输出当事实）

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.18 [[model_routes]] / [[embedding_routes]]（路由表）

用途：用 hint 做稳定路由名，把真实模型版本解耦。

[[model_routes]] 字段说明（含默认值/必填）

• hint：路由提示名（必填）。
• provider：目标 provider（必填）。
• model：目标模型 ID（必填）。
• api_key：路由级 API key 覆盖（可选，默认未设置）。

[[embedding_routes]] 字段说明（含默认值/必填）

• hint：向量路由提示名（必填）。
• provider：向量 provider（必填，none/openai/custom:<url>）。
• model：向量模型 ID（必填）。
• dimensions：路由级向量维度覆盖（可选，默认未设置）。
• api_key：路由级 API key 覆盖（可选，默认未设置）。

实践意义：

• 让上层只依赖 hint（例如 code / reasoning / semantic）
• 升级模型时只改路由，不改业务逻辑

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.19 [query_classification]（自动路由分类）

用途：根据消息内容自动匹配 [[model_routes]] 的 hint。

字段说明（含默认值）：

• enabled：是否启用自动分类，默认 false。
• rules：分类规则数组，默认 []。

rules[] 字段说明（含默认值）：

• hint：命中后路由到的 hint（必填，需已在 [[model_routes]] 定义）。
• keywords：大小写不敏感子串列表，默认 []。
• patterns：大小写敏感字面量列表，默认 []。
• min_length：消息长度下限（可选）。
• max_length：消息长度上限（可选）。
• priority：规则优先级，默认 0（高值先匹配）。

这组配置很适合做不同任务类型（如 coding / research / chat）的自动分流。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.20 [channels_config]（渠道总配置，官方补充）

用途：控制渠道运行时超时、热更新行为，以及按渠道子表启用具体接入。

字段说明（含默认值）：

• message_timeout_secs：消息处理基础超时（秒），默认 300。实际预算按工具循环缩放，且小于 30 时会被钳制到 30。

官方行为要点：

• 渠道消息总超时预算会按工具循环深度缩放：message_timeout_secs * scale，scale = min(max_tool_iterations, 4)，最小为 1。
• 小于 30 秒的值会被钳制到 30，避免过于频繁的超时抖动。
• zeroclaw channel start 运行期间，以下字段在下一条消息可热生效：default_provider、default_model、default_temperature、api_key、api_url、reliability.*。
• Telegram 的中断行为由 channels_config.telegram.interrupt_on_new_message 控制（默认 false）。

常见子表（docs/channels-reference.md）：

• [channels_config.telegram]
• [channels_config.discord]
• [channels_config.slack]
• [channels_config.matrix]
• [channels_config.whatsapp]
• [channels_config.nostr]
• [channels_config.nextcloud_talk]
• [channels_config.linq]

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• docs/channels-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md

3.21 [channels_config.nostr]

用途：Nostr 私信通道（支持 NIP-04 / NIP-17）。

字段说明（含默认值/必填）：

• private_key：Nostr 私钥（必填，支持 hex 或 nsec1...）。
• relays：中继列表（可选）；未设置时默认 relay.damus.io、nos.lol、relay.primal.net、relay.snort.social。
• allowed_pubkeys：入站公钥白名单，默认 []（拒绝全部），"*" 允许全部。

注意点：

• private_key 属于高价值密钥，生产环境建议保持 secrets.encrypt = true（官方默认）。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• docs/channels-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md

3.22 [channels_config.whatsapp]

用途：WhatsApp 双后端配置（Cloud API / WhatsApp Web）。

字段说明（含默认值/必填）：

• access_token：Cloud API 模式必填，Meta 调用令牌。
• phone_number_id：Cloud API 模式必填，发送使用的号码 ID。
• verify_token：Cloud API 模式必填，Webhook 验证 token。
• app_secret：Cloud API 可选，配置后启用签名校验。
• allowed_numbers：入站号码白名单，建议配置（[] 拒绝全部，"*" 允许全部）。
• session_path：WhatsApp Web 模式必填，本地会话库路径。
• pair_phone：WhatsApp Web 可选，pair-code 配对手机号。
• pair_code：WhatsApp Web 可选，自定义配对码。

注意点：

• 两组字段同时存在时，官方说明是 Cloud API 优先（兼容历史行为）。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• docs/channels-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md

3.23 [channels_config.linq]

用途：Linq Partner V3 通道（iMessage/RCS/SMS）。

字段说明（含默认值/必填）：

• api_token：必填，Linq Partner API token。
• from_phone：必填，发送号码（E.164）。
• signing_secret：可选，Webhook HMAC-SHA256 验签密钥（可被 ZEROCLAW_LINQ_SIGNING_SECRET 覆盖）。
• allowed_senders：入站号码白名单（建议配置，[] 拒绝全部，"*" 允许全部）。

注意点：

• ZEROCLAW_LINQ_SIGNING_SECRET 会覆盖配置中的 signing_secret。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• docs/channels-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md

3.24 [channels_config.nextcloud_talk]

用途：Nextcloud Talk 原生机器人通道（Webhook 入站 + OCS 出站）。

字段说明（含默认值/必填）：

• base_url：必填，Nextcloud 根地址。
• app_token：必填，Talk bot OCS API token。
• webhook_secret：可选，Webhook 验签密钥（可被 ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET 覆盖）。
• allowed_users：actor 白名单（建议配置，[] 拒绝全部，"*" 允许全部）。

注意点：

• ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET 会覆盖 webhook_secret。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• docs/channels-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md

3.25 [hardware]（硬件向导）

用途：控制物理硬件访问模式（串口/探针等）。

字段说明（含默认值）：

• enabled：是否启用硬件访问，默认 false。
• transport：传输模式，默认 none，可选 none/native/serial/probe。
• serial_port：串口路径（serial 模式使用）。
• baud_rate：串口波特率，默认 115200。
• probe_target：探针目标芯片（probe 模式使用）。
• workspace_datasheets：是否开启工作区 datasheet RAG，默认 false。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

3.26 [peripherals]（外设板卡）

用途：把板卡配置成 agent 可调用工具。

字段说明（含默认值）：

• enabled：是否启用外设能力，默认 false。
• boards：板卡配置数组，默认 []。
• datasheet_dir：板卡资料目录（相对 workspace，支持 .md/.txt 检索）。

[[peripherals.boards]] 字段说明（含默认值/必填）：

• board：板卡类型（必填，如 nucleo-f401re/rpi-gpio/esp32）。
• transport：通信方式，默认 serial，可选 serial/native/websocket。
• path：连接路径（serial 常用）。
• baud：串口波特率，默认 115200。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

4）[channels_config]（渠道配置）怎么写

官方 channels-reference.md 明确写了：所有渠道配置都放在 channels_config 下。

最小示例：

1
2

[channels_config]
cli = true

启用具体渠道时，用子表，例如：

• [channels_config.telegram]
• [channels_config.discord]
• [channels_config.slack]
• [channels_config.matrix]
• [channels_config.whatsapp]

文档里给了各渠道的示例字段（如 bot_token、allowed_users、channel_id、room_id、access_token 等）。

4.1 各渠道字段补全（对照 channels-reference.md）

这一节补的是官网渠道参考里已有、但前文未完整展开的子字段。

Telegram ([channels_config.telegram])

• bot_token（必填）
• allowed_users（建议配置）
• stream_mode（可选：off/partial）
• draft_update_interval_ms（可选）
• mention_only（可选）
• interrupt_on_new_message（可选，默认 false）

Discord ([channels_config.discord])

• bot_token（必填）
• guild_id（可选）
• allowed_users（建议配置）
• listen_to_bots（可选）
• mention_only（可选）

Slack ([channels_config.slack])

• bot_token（必填）
• app_token（可选）
• channel_id（可选，"*" 或省略表示监听可访问频道）
• allowed_users（建议配置）

Mattermost ([channels_config.mattermost])

• url（必填）
• bot_token（必填）
• channel_id（监听必填）
• allowed_users（建议配置）

Matrix ([channels_config.matrix])

• homeserver（必填）
• access_token（必填）
• user_id（可选，E2EE 推荐配置）
• device_id（可选，E2EE 推荐配置）
• room_id（必填，支持 room id 或 alias）
• allowed_users（建议配置）

Signal ([channels_config.signal])

• http_url（必填）
• account（必填）
• group_id（可选）
• allowed_from（建议配置）
• ignore_attachments（可选）
• ignore_stories（可选）

Webhook ([channels_config.webhook])

• port（必填）
• secret（可选）

Email ([channels_config.email])

• imap_host（必填）
• imap_port（必填）
• imap_folder（可选）
• smtp_host（必填）
• smtp_port（必填）
• smtp_tls（可选）
• username（必填）
• password（必填）
• from_address（必填）
• poll_interval_secs（可选）
• allowed_senders（建议配置）

IRC ([channels_config.irc])

• server（必填）
• port（必填）
• nickname（必填）
• username（可选）
• channels（必填）
• allowed_users（建议配置）
• server_password（可选）
• nickserv_password（可选）
• sasl_password（可选）
• verify_tls（可选）

Lark ([channels_config.lark])

• app_id（必填）
• app_secret（必填）
• encrypt_key（可选）
• verification_token（可选）
• allowed_users（建议配置）
• receive_mode（可选：websocket/webhook）
• port（webhook 模式必填）

Feishu ([channels_config.feishu])

• app_id（必填）
• app_secret（必填）
• encrypt_key（可选）
• verification_token（可选）
• allowed_users（建议配置）
• receive_mode（可选：websocket/webhook）
• port（webhook 模式必填）

DingTalk ([channels_config.dingtalk])

• client_id（必填）
• client_secret（必填）
• allowed_users（建议配置）

QQ ([channels_config.qq])

• app_id（必填）
• app_secret（必填）
• allowed_users（建议配置）

iMessage ([channels_config.imessage])

• allowed_contacts（建议配置）

Allowlist 语义（官方说明）

• 空数组：拒绝所有
• "*"：允许所有（仅建议临时测试）
• 显式列表：只允许指定发送者

不同渠道字段名可能不同（如 allowed_users / allowed_numbers / allowed_senders）。

出处：

• docs/channels-reference.md（官方渠道配置参考）
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md

5）Provider 相关配置（default_provider / 环境变量 / 自定义 provider）

官方 providers-reference.md 是 provider 的权威对照表，包含：

• Canonical ID（规范 provider 名）
• Alias（别名）
• 是否本地 provider
• 对应环境变量（如 OPENAI_API_KEY、ANTHROPIC_API_KEY 等）

例如：

• openai → OPENAI_API_KEY
• anthropic → ANTHROPIC_OAUTH_TOKEN / ANTHROPIC_API_KEY
• gemini → GEMINI_API_KEY / GOOGLE_API_KEY
• ollama → OLLAMA_API_KEY（可选）
• bedrock → AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY

如果你在 config.toml 写 default_provider，建议按这里的规范 provider ID 来写，避免 alias/兼容名混用导致行为不一致。

出处：

• docs/providers-reference.md（官方 provider 参考）
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/providers-reference.md

6）一个“最小可用 + 安全一点”的配置思路（示例）

下面这个示例不是官方原样，而是基于官方字段整理的实践模板。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-6"
default_temperature = 0.7

[gateway]
host = "127.0.0.1"
port = 42617
require_pairing = true
allow_public_bind = false

[autonomy]
level = "supervised"
workspace_only = true
allowed_commands = ["git", "npm", "pnpm", "node"]
always_ask = ["shell"]

[http_request]
enabled = true
allowed_domains = ["api.openai.com", "openrouter.ai"]
timeout_secs = 30

[memory]
backend = "sqlite"
auto_save = true
embedding_provider = "none"

[skills]
open_skills_enabled = false
prompt_injection_mode = "compact"

[channels_config]
cli = true

7）你要特别注意的几个“坑”

7.1 配置文件路径可能不是你以为的那个

因为有 ZEROCLAW_WORKSPACE 和 active_workspace.toml 参与解析，改了 ~/.zeroclaw/config.toml 但没生效是常见问题。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• 相关 issue（排查有帮助）：#845
  https://github.com/zeroclaw-labs/zeroclaw/issues/845

7.2 allowed_domains 默认是拒绝

http_request / browser 等功能如果没配置 allowlist，看起来像“功能坏了”，其实是安全默认行为。

出处：

• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md

7.3 渠道 allowlist 空列表 = 拒绝所有

很多“机器人不回消息”的问题都在这里。官方渠道文档明确写了这个语义。

出处：

• docs/channels-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md

7.4 完整字段列表以 schema 为准

官方 config-reference.md 是高信号参考（常用配置），并不一定穷尽所有字段。做严谨校验/自动补全建议使用：

1

zeroclaw config schema

出处：docs/config-reference.md

8）常见问题（官方 FAQ / 排障补充）

8.1 Matrix 配置看起来都对，但机器人不回复

官方 channels-reference.md 给的排查顺序（按优先级）：

1. allowed_users 没放行发送者（或为空数组）
2. room_id / room alias 指错，机器人不在目标房间
3. token 属于另一个 Matrix 账号
4. whoami 没返回 device_id，且配置里也没给 device_id
5. E2EE 房间密钥未共享给机器人设备
6. 改完配置后未重启 zeroclaw daemon

8.2 channel 已连接但不响应，最小排查流程

官方建议先跑健康检查，再回到配置核对：

1
2

zeroclaw doctor
zeroclaw channel doctor

然后依次确认：

• 发送者是否命中对应 allowlist 字段（allowed_users / allowed_numbers / allowed_senders 等）
• 机器人账号是否在目标群/频道且有权限
• 凭据是否有效且未过期
• 传输模式是否匹配部署方式（轮询/WS 不需要公网回调，webhook 需要公网可达 HTTPS）
• 改配置后是否已重启 daemon

8.3 为什么某个渠道“被跳过”而不是报错

如果配置了 [channels_config.matrix]、[channels_config.lark] 或 [channels_config.feishu]，但构建时没启用对应 feature，channel list/doctor/start 会报告该渠道被有意跳过。

这不是配置字段错误，而是二进制能力不包含该渠道。

8.4 为什么经常超时（Request timed out while waiting for the model）

官方 config-reference.md 的超时语义：

• [channels_config].message_timeout_secs 默认 300
• 实际预算会乘工具循环缩放（最高 4 倍）
• 小于 30 的配置会被钳制为 30

如果你用云模型，通常可以把这个值降到 60 或更低；本地慢模型（如 Ollama）则建议保持更高值。

8.5 Telegram 新消息是否会打断当前生成

由 channels_config.telegram.interrupt_on_new_message 控制（默认 false）。

开启后，只有“同一发送者 + 同一聊天”的新消息会中断当前请求，并在保留被中断上下文后重启生成。

8.6 为什么 webhook 渠道一直收不到入站

常见原因是把“接收模式”理解反了：

• 轮询/WS 类型渠道（Telegram/Discord/Matrix 等）通常不要求公网回调端口
• webhook 类型渠道（WhatsApp Cloud、Nextcloud Talk、Linq 等）需要公网可达 HTTPS 回调

先确认渠道类型，再检查端口/反向代理/证书。

8.7 排查时推荐先临时放宽 allowlist

官方建议先用 ["*"] 做连通性验证，确认能收发后再收紧为显式 ID 列表，避免把“权限拒绝”误判成“通道故障”。

出处：

• docs/channels-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md
• docs/config-reference.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• docs/operations-runbook.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/operations-runbook.md
• docs/troubleshooting.md
  https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/troubleshooting.md

相关链接

官方文档

• 配置参考（核心配置项）：https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/config-reference.md
• 渠道配置参考： https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/channels-reference.md
• Provider 参考：https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/docs/providers-reference.md

相关补充

• 配置路径加载优先级相关 issue（排查常见“配置不生效”问题）：https://github.com/zeroclaw-labs/zeroclaw/issues/845
• Docker 模板配置线索（容器场景示例）：https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/dev/config.template.toml