ZeroClaw 配置项(config.toml)说明

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

速查版

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

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

配置键 / 概念 作用 常见值/示例 备注
ZEROCLAW_WORKSPACE 指定工作区配置入口 环境变量路径 配置加载优先级最高（若设置）
~/.zeroclaw/active_workspace.toml 当前激活工作区配置 文件路径 若存在，优先于默认 config
~/.zeroclaw/config.toml 默认配置文件 文件路径 常规全局配置文件
default_provider 默认模型提供方 openrouter / openai / anthropic 建议使用规范 provider ID
default_model 默认模型 如 anthropic/claude-sonnet-4-6 与 provider 对应
default_temperature 默认采样温度 0.7 控制生成随机性
ZEROCLAW_PROVIDER 环境变量强制覆盖 provider openai 等 优先级高于 config
PROVIDER 兼容旧方式覆盖 provider openrouter 等 兼容字段，注意覆盖行为

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

字段 作用 常见值/示例 备注
backend 可观测后端类型 none / log / prometheus / otlp 选一种输出方式
otel_endpoint OTLP 上报地址 http://localhost:4318 用于接 OTel collector
otel_service_name 服务名 zeroclaw 便于链路追踪区分
runtime_trace_mode 运行时 trace 模式 none / rolling / full 排障常用
runtime_trace_path trace 文件路径 .../trace.jsonl JSONL 输出
runtime_trace_max_entries rolling 模式最大条数 1000 等 控制文件体积

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

字段 作用 常见值/示例 备注
compact_context 紧凑上下文模式 true/false 小上下文模型更有用
max_tool_iterations 单轮消息最大工具迭代次数 10 防止无限循环
max_history_messages 历史消息条数上限 50 等 控制上下文长度
parallel_tools 是否并行工具调用 true/false 提高速度，注意副作用
tool_dispatcher 工具分发策略 auto 通常保持默认即可

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

字段 作用 常见值/示例 备注
enabled 是否开启 OTP 门禁 true/false 生产环境建议开启
method OTP 方式 totp / pairing / cli-prompt totp 常用
token_ttl_secs OTP 有效期（秒） 60 等 过短影响体验
cache_valid_secs 缓存通过时长（秒） 300 等 降低频繁验证
gated_actions 受保护动作列表 ["shell","file_write"] 高风险动作建议都加
gated_domains 受保护域名规则 ["*.bank.com"] 支持通配模式
gated_domain_categories 域名分类 ["banking"] 使用内置分类

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

字段 作用 常见值/示例 备注
enabled 启用紧急停止机制 true/false 建议保留
state_file 状态文件路径 .../estop.state 持久化停机状态
require_otp_to_resume 恢复前是否需 OTP true/false 防止误恢复

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

字段 作用 常见值/示例 备注
provider 子 agent 的 provider openrouter 必填
model 子 agent 的模型 ... 必填
system_prompt 子 agent 系统提示词 文本 定义角色职责
api_key 子 agent 专用密钥 字符串 可覆盖全局
temperature 子 agent 温度 0.2 / 0.7 按任务调整
max_depth 委派/递归深度 1 / 2 防止过深调用
agentic 是否启用代理式多步 true/false true 时应配工具
allowed_tools 工具白名单 ["http_request"] 推荐最小权限
max_iterations 子 agent 迭代上限 5 防止跑飞

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

字段 作用 常见值/示例 备注
reasoning_enabled 显式推理/思考开关 true/false 对支持的 provider 生效

H. [skills]（技能系统）

字段 作用 常见值/示例 备注
open_skills_enabled 是否启用社区 open-skills true/false 安全默认通常为 false
open_skills_dir 技能目录路径 ~/.zeroclaw/skills 可自定义
prompt_injection_mode 技能注入模式 full / compact compact 更省上下文
ZEROCLAW_OPEN_SKILLS_ENABLED 环境变量覆盖 true/false 覆盖 TOML
ZEROCLAW_OPEN_SKILLS_DIR 环境变量技能目录 路径 覆盖 TOML
ZEROCLAW_SKILLS_PROMPT_MODE 环境变量注入模式 compact 覆盖 TOML

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

字段 作用 常见值/示例 备注
enabled 是否启用 Composio true/false 未启用则不注册工具
api_key Composio API Key ... 启用时通常必填
entity_id Composio 实体 ID ... 用于账户绑定

J. [cost]（成本控制）

字段 作用 常见值/示例 备注
enabled 启用预算控制 true/false 团队环境建议开启
daily_limit_usd 日预算上限（USD） 5.0 达上限会拦截
monthly_limit_usd 月预算上限（USD） 100.0 控制总成本
warn_at_percent 告警阈值（百分比） 80 提前预警
allow_override 是否允许手工 override true/false 可结合审批策略

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

字段 作用 常见值/示例 备注
format identity 格式 openclaw / aieos 默认一般为 openclaw
aieos_path AIEOS 文档路径 ./AIEOS.md 与 inline 二选一
aieos_inline 内联 AIEOS 文本 多行字符串 与 path 二选一

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

字段 作用 常见值/示例 备注
max_images 单次最大图片数 4 控制资源占用
max_image_size_mb 单图大小限制（MB） 10 防止超大文件
allow_remote_fetch 是否允许远程 URL 拉图 true/false 安全环境谨慎开启

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

字段 作用 常见值/示例 备注
enabled 启用浏览器工具 true/false 关闭可减少风险面
allowed_domains 浏览器访问白名单 ["example.com"] 建议显式配置
session_name 会话名 "default" 区分浏览器会话
backend 浏览器后端 auto / rust_native / computer_use 按环境选择
native_headless 原生浏览器无头模式 true/false CI 常用
native_webdriver_url 自定义 webdriver 地址 URL 远程驱动场景
native_chrome_path Chrome 可执行路径 路径 自定义安装位置时用

[browser.computer_use] 子表

字段 作用 常见值/示例 备注
endpoint computer-use sidecar 地址 http://127.0.0.1:... 默认建议 loopback
api_key sidecar 密钥 ... 按需配置
timeout_ms 请求超时（毫秒） 30000 避免卡死
allow_remote_endpoint 允许远程 sidecar true/false 安全默认建议 false
window_allowlist 允许操作窗口列表 ["Chrome"] 降低误操作
max_coordinate_x 最大 X 坐标 1920 限制点击范围
max_coordinate_y 最大 Y 坐标 1080 限制点击范围

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

字段 作用 常见值/示例 备注
enabled 启用 HTTP 请求工具 true/false 默认可关闭
allowed_domains 请求域名白名单 ["api.openai.com"] 空列表通常等于拒绝
max_response_size 最大响应体大小 1048576 防止大响应占满内存
timeout_secs 请求超时（秒） 30 建议设置

O. [gateway]（网关）

字段 作用 常见值/示例 备注
host 网关监听地址 127.0.0.1 安全默认建议本地
port 网关端口 42617 可调整
require_pairing 是否要求配对 true/false 建议开启
allow_public_bind 允许公网监听 true/false 生产谨慎开启

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

字段 作用 常见值/示例 备注
level 自治等级 read_only / supervised / full 推荐先用 supervised
workspace_only 限制仅工作区内操作 true/false 建议 true
allowed_commands shell 命令白名单 ["git","npm","node"] 强烈建议配置
forbidden_paths 禁止路径列表 ["/etc","~/.ssh"] 保护系统敏感目录
allowed_roots 允许根路径列表 ["/Users/me/work"] 工作区外授权访问
max_actions_per_hour 每小时动作数上限 100 防失控
max_cost_per_day_cents 每日成本上限（分） 500 可与预算策略配合
require_approval_for_medium_risk 中风险是否审批 true/false supervised 常用
block_high_risk_commands 阻断高风险命令 true/false 建议开启
auto_approve 自动批准规则 列表 仅低风险场景使用
always_ask 总是询问的动作 ["shell"] 对 shell 常用

Q. [memory]（记忆系统）

字段 作用 常见值/示例 备注
backend 记忆后端 sqlite / lucid / markdown / none sqlite 通常最稳
auto_save 自动保存记忆 true/false 注意隐私与噪音
embedding_provider 向量 provider openai / none 不用向量可设 none
embedding_model 向量模型 text-embedding-... 与 provider 对应
embedding_dimensions 向量维度 1536 等 需与模型匹配
vector_weight 向量检索权重 0.7 混合检索参数
keyword_weight 关键词检索权重 0.3 混合检索参数

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

字段 作用 常见值/示例 备注
hint 路由名/提示名 code / reasoning / chat 上层统一引用
provider 提供方 openrouter 与 model 配套
model 具体模型 anthropic/... 可替换升级
api_key 路由专用 key ... 可选

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

字段 作用 常见值/示例 备注
hint 路由名 semantic 上层引用
provider 向量 provider openai
model 向量模型 text-embedding-3-small
dimensions 维度 1536 与模型匹配
api_key 专用 key ... 可选

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

字段 作用 常见值/示例 备注
enabled 启用自动分类 true/false 与 model_routes 联动
rules 规则列表 数组 每条规则一组匹配条件

rules[] 子字段

子字段 作用 示例 备注
hint 命中后路由到哪个 hint code 对应 [[model_routes]]
keywords 不区分大小写关键词 ["bug","fix"] 文本子串匹配
patterns 区分大小写模式/字面量 ["\``ts”] ` 常用于代码判定
min_length 最小文本长度 20 过滤过短消息
max_length 最大文本长度 5000 限制分类范围
priority 优先级 100 数值越高通常越先匹配

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

配置项 / 子表 作用 常见值/示例 备注
[channels_config] 所有渠道配置总入口 顶层表 渠道配置统一放这里
message_timeout_secs 单条消息处理超时基线（秒） 300 官方默认 300；小于 30 会被钳制到 30
cli 启用 CLI 渠道 true/false 本地调试最简单
[channels_config.telegram] Telegram Bot 渠道 子表 常见字段：bot_token, allowed_users
[channels_config.discord] Discord 渠道 子表 常见字段：bot_token, allowed_users, channel_id
[channels_config.slack] Slack 渠道 子表 常见字段：bot_token, app_token, allowed_users
[channels_config.matrix] Matrix 渠道 子表 常见字段：homeserver, access_token, room_id
[channels_config.whatsapp] WhatsApp 渠道 子表 常见字段：access_token, allowed_numbers
[channels_config.nostr] Nostr 渠道 子表 常见字段：private_key, relays, allowed_pubkeys
[channels_config.nextcloud_talk] Nextcloud Talk 渠道 子表 常见字段：base_url, app_token, webhook_secret
[channels_config.linq] Linq 渠道（iMessage/RCS/SMS） 子表 常见字段：api_token, from_phone, signing_secret

渠道 Allowlist 语义

配置值 含义 备注
[] 拒绝所有 常见“机器人不回消息”原因
["*"] 允许所有 仅建议临时测试
["user1","user2"] 仅允许指定发送者 生产建议使用

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

字段名 适用场景（示意） 备注
allowed_users Telegram / Discord / Slack 等 常见用户白名单
allowed_numbers WhatsApp 等 电话号码白名单
allowed_senders 部分渠道实现 发送者白名单

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

子表 字段补全（除前文已提到字段外）
[channels_config.telegram] stream_mode, draft_update_interval_ms, mention_only, interrupt_on_new_message
[channels_config.discord] guild_id, listen_to_bots, mention_only
[channels_config.slack] channel_id（可指定单频道或 "*"）
[channels_config.mattermost] url, bot_token, channel_id, allowed_users
[channels_config.matrix] user_id, device_id, allowed_users
[channels_config.signal] http_url, account, group_id, allowed_from, ignore_attachments, ignore_stories
[channels_config.webhook] port, secret
[channels_config.email] imap_host, imap_port, imap_folder, smtp_host, smtp_port, smtp_tls, username, password, from_address, poll_interval_secs, allowed_senders
[channels_config.irc] server, port, nickname, username, channels, allowed_users, server_password, nickserv_password, sasl_password, verify_tls
[channels_config.lark] app_id, app_secret, encrypt_key, verification_token, allowed_users, receive_mode, port
[channels_config.feishu] app_id, app_secret, encrypt_key, verification_token, allowed_users, receive_mode, port
[channels_config.dingtalk] client_id, client_secret, allowed_users
[channels_config.qq] app_id, app_secret, allowed_users
[channels_config.imessage] allowed_contacts

V. Provider（常见项速查）

Provider（常见） 常见环境变量 备注
openai OPENAI_API_KEY 官方 OpenAI
anthropic ANTHROPIC_API_KEY / ANTHROPIC_OAUTH_TOKEN Claude 常用
gemini GEMINI_API_KEY / GOOGLE_API_KEY Google 系
openrouter OPENROUTER_API_KEY 聚合路由常用
ollama OLLAMA_API_KEY（可选） 本地模型常用
bedrock AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY AWS 托管模型
azure_openai AZURE_OPENAI_* 具体键名按实现版本为准

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

字段 作用 常见值/示例 备注
enabled 启用硬件访问 true/false 默认 false
transport 传输方式 none/native/serial/probe 默认 none
serial_port 串口路径 /dev/ttyACM0 serial 模式常用
baud_rate 串口波特率 115200 默认 115200
probe_target 调试探针目标芯片 STM32F401RE probe 模式常用
workspace_datasheets 启用工作区 datasheet RAG true/false 用于原理图/资料检索

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

字段 作用 常见值/示例 备注
enabled 启用外设能力 true/false 默认 false
boards 板卡列表 数组 每项一块板卡配置
datasheet_dir 板卡文档目录 docs/datasheets 支持 .md/.txt RAG

[[peripherals.boards]] 子字段

子字段 作用 常见值/示例 备注
board 板卡类型 nucleo-f401re / rpi-gpio / esp32 必填
transport 连接方式 serial/native/websocket 默认 serial
path 串口/连接路径 /dev/ttyUSB0 serial 常用
baud 串口波特率 115200 默认 115200

完整版

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

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

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

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

出处：

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：默认采样温度；值越低通常越稳定、越高通常越发散。

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

出处：

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 可能包含模型输出文本，共享环境谨慎开启。

出处：

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 误覆盖。

出处：

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 层行为，不一定覆盖所有运行时路径

出处：

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

出处：

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

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

字段说明（含默认值）：

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

注意点：

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

出处：

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（避免递归委派）

出处：

3.7 [runtime]（运行时行为）

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

字段说明（含默认值）：

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

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

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

出处：

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 模式适合上下文较小模型
  • 技能加载/安装会做静态安全审计（文档有说明）

出处：

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 时，工具不会注册

出处：

3.10 [cost]（成本控制）

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

字段说明（含默认值）：

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

行为：

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

出处：

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 优先

出处：

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 时会返回结构化能力错误

出处：

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 端点，防止误暴露公网

出处：

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 为空即拒绝）
  • "*" 可放开公网域名，但本地/私网目标仍会被拦截（官方文档说明）

出处：

3.15 [gateway]（网关）

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

字段说明（含默认值）：

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

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

出处：

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 运算符解析带引号感知（降低误判/注入风险）

出处：

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 自动总结字段会被忽略（避免误把模型输出当事实）

出处：

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）
  • 升级模型时只改路由，不改业务逻辑

出处：

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）的自动分流。

出处：

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]

出处：

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（官方默认）。

出处：

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 优先（兼容历史行为）。

出处：

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。

出处：

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。

出处：

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。

出处：

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。

出处：

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）。

出处：

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/兼容名混用导致行为不一致。

出处：

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 但没生效是常见问题。

出处：

7.2 allowed_domains 默认是拒绝

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

出处：

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

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

出处：

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 列表，避免把“权限拒绝”误判成“通道故障”。

出处：

相关链接

官方文档

相关补充