环境变量

每个运算符的环境变量覆盖都使用同一套 schema-mirror 语法。ZEROCLAW_* 环境变量的尾部就是 zeroclaw config set 所接受的点分属性路径，其中每个 __（双下划线）分隔路径段，而每个单独的 _ 要么是字段名中的 snake-case 连接符（在 set_prop 中 api_key → api-key），要么是别名键中的字面字符。

ZEROCLAW_<dotted_path_with_double_underscores>=<value>

示例

# 注入类型化族别名凭据
ZEROCLAW_providers__models__anthropic__home__api_key=sk-ant-...

# 在非默认 OpenRouter 别名上设置模型（带下划线的别名也可以）
ZEROCLAW_providers__models__openrouter__prod_v2__model=anthropic/claude-sonnet-4-6
ZEROCLAW_providers__models__openrouter__prod_v2__api_key=sk-or-...

# 切换和配置频道
ZEROCLAW_channels__matrix__home__enabled=true
ZEROCLAW_channels__matrix__home__homeserver=https://matrix.example.org

# 覆盖网关运行时配置项
ZEROCLAW_gateway__request_timeout_secs=120
ZEROCLAW_gateway__long_running_request_timeout_secs=900

# 将网关指向已构建的 Web 仪表板（绝对路径；不使用 ~ / $HOME）
ZEROCLAW_gateway__web_dist_dir=/srv/zeroclaw/web/dist

# 注入 webhook 签名密钥
ZEROCLAW_channels__whatsapp__home__app_secret=...
ZEROCLAW_channels__linq__home__signing_secret=...
ZEROCLAW_channels__nextcloud_talk__home__webhook_secret=...

# 注入 Qdrant 内存后端连接
ZEROCLAW_storage__qdrant__home__url=https://qdrant.example.com
ZEROCLAW_storage__qdrant__home__collection=zeroclaw
ZEROCLAW_storage__qdrant__home__api_key=...

从环境变量名到 TOML 路径的映射是机械式的：

上述 <alias> 段（home、prod_v2）由操作人员自行选择，请替换为你的配置实际使用的名称。

Bootstrap（大写尾部）

这些环境变量在任何 Config 存在之前，决定配置文件和实例数据存放的_位置_。它们保留大写形式，以便大小写规则将其与 schema-mirror 表层区分开来。它们按照 ZEROCLAW_CONFIG_DIR > ZEROCLAW_DATA_DIR > ZEROCLAW_WORKSPACE（已弃用）的顺序解析：

ZEROCLAW_CONFIG_DIR=/etc/zeroclaw         # 配置文件位置（优先级更高）
ZEROCLAW_DATA_DIR=/srv/zeroclaw           # 实例数据目录（规范路径）
ZEROCLAW_WORKSPACE=/srv/zeroclaw          # 已弃用 — ZEROCLAW_DATA_DIR 的别名

网关的 Web 仪表板位置通过标准的架构镜像形式 ZEROCLAW_gateway__web_dist_dir 进行配置，完整的设置参考请参阅 Web 仪表板 (web_dist_dir)。

持久化边界

通过 ZEROCLAW_* 环境变量设置的值会在加载时应用到内存中的 Config，并且绝不会持久化到磁盘。zeroclaw config save 会在加密前将受环境变量覆盖的路径恢复为其磁盘值或默认值。每当某个密钥类型的路径（例如 API 密钥）被环境变量覆盖时，都会输出一条 WARN 日志，从而使该注入在审计日志中可见。

别名语法

别名（即上述示例中的 <alias> 部分，如 home、prod_v2、mymatrixalias 等）遵循以下规则：

1. 小写 ASCII 字母、数字和单个下划线。
2. 必须以字母或数字开头和结尾（不能有前导或尾随下划线）。
3. 不能包含 __ 子字符串（保留作为环境变量语法的路径分隔符）。
4. 无连字符（在环境变量标识符中非法）。
5. 不允许使用大写字母（会与引导名称冲突）。
6. 1–63 个字符

prod_v2 是单个别名标记；home__api_key 会被解析为两个部分（别名 home、字段 api_key）。包含不符合规范别名的配置会在加载时产生错误，并指出有问题的别名。

错误

无法解析的 ZEROCLAW_<lowercase_*> 名称（拼写错误、与 schema 中任何属性都不匹配的路径）会导致启动中止，并抛出一个硬性错误，指明有问题的环境变量。不带 ZEROCLAW_ 前缀的环境变量名称不会被此覆盖层读取。

可见性

覆盖状态会在配置渲染的任何位置显示，并用 💉 标记标识被环境变量覆盖的字段：

1. zeroclaw config list：图例 💉 env-overridden 🔒 secret 在顶部打印一次；被环境变量覆盖的字段行以 💉 作为前缀。
2. Web 配置编辑器：每个 ListEntry 都带有一个 is_env_overridden 布尔值。被环境变量覆盖的字段行会渲染 💉 徽章和一条持久的警告_“此处的编辑不会生效，已被 ZEROCLAW_… 覆盖”_，让运维人员无需尝试编辑即可看到该覆盖。
3. CLI/TUI 引导：prompt_field 会跳过被环境变量覆盖的字段，并打印一条 💉 三行提示（环境变量名称、TOML 路径以及跳过通知），该提示会在向前/向后导航时清除。操作人员不会被要求输入他们已经注入的值。
4. 重新加载漂移：GET /api/config/drift、GET /api/config/list 和重新加载横幅会将被环境变量覆盖的路径排除在漂移计算之外。由于这些值只存在于内存中，且从不写入磁盘，否则它们会被报告为永久漂移，而任何配置文件编辑都无法使其一致。排除它们可将漂移输出限制为运维人员实际可通过编辑已存储配置来解决的差异。
5. 编程方式：Config::prop_is_env_overridden(path) -> bool 是一个 O(1) 的 HashSet 查找。此处为任何自定义渲染层提供钩子。

从配置中派生环境变量名称

从任意 TOML 键派生环境变量名的三个机械步骤：

1. 在路径前加上 ZEROCLAW_ 前缀。 点分隔的配置路径是权威来源，请通过 zeroclaw config schema 查找对应字段。
2. 将 . 替换为 __（双下划线，路径分隔符）。
3. 字段名保持原样（snake_case）。别名保持原样。其他内容均不转换。

例如，[providers.models.anthropic.home] api_key = "sk-..." 位于点分路径 providers.models.anthropic.home.api_key。应用这三条规则后，对应的环境变量为 ZEROCLAW_providers__models__anthropic__home__api_key=sk-...。任何节中的任何字段都遵循相同的机械映射规则。

桥接生态系统默认环境变量

schema-mirror 语法是注入值的规范方式，但 ANTHROPIC_API_KEY / OPENROUTER_API_KEY / QDRANT_URL 等在 .env 文件和 CI 配置中仍是常见的名称。单行 shell 展开可将 schema-mirror 名称指向生态系统的默认值：

# POSIX (bash、zsh、sh) — 加入 ~/.bashrc / ~/.zshrc / .env / Dockerfile
export ZEROCLAW_providers__models__anthropic__home__api_key=$ANTHROPIC_API_KEY
export ZEROCLAW_providers__models__openai__home__api_key=$OPENAI_API_KEY
export ZEROCLAW_providers__models__openrouter__home__api_key=$OPENROUTER_API_KEY
export ZEROCLAW_providers__models__nearai__tee__api_key="$NEARAI_API_KEY"
export ZEROCLAW_providers__models__zerorouter__gateway__api_key="$ZEROROUTER_API_KEY"
export ZEROCLAW_storage__qdrant__home__url="$QDRANT_URL"
export ZEROCLAW_storage__qdrant__home__api_key=$QDRANT_API_KEY
export ZEROCLAW_gateway__request_timeout_secs=$GATEWAY_TIMEOUT_SECS

# PowerShell — drop into $PROFILE
$env:ZEROCLAW_providers__models__anthropic__home__api_key = $env:ANTHROPIC_API_KEY
$env:ZEROCLAW_providers__models__openai__home__api_key = $env:OPENAI_API_KEY
$env:ZEROCLAW_providers__models__nearai__tee__api_key = $env:NEARAI_API_KEY
$env:ZEROCLAW_storage__qdrant__home__url = $env:QDRANT_URL

将 home 替换为与你的配置匹配的别名。如果同一系列上有多个别名，请为每个别名重复该行。

这些行是从 shell 到类型化配置的桥接，而不是构造函数会读取提供方原生环境变量的一般规则。运行时代码应从 Config 接收已解析的值，除非该集成系列明确记录了原生环境变量桥接。

OAuth 和 CLI 路径字段

少数字段以 schema 字段形式存在，可通过标准映射访问：

1. MiniMax OAuth 刷新流程：[providers.models.minimax.<alias>] oauth_refresh_token = "..."（可选配置 oauth_client_id）；区域选择采用类型化的 endpoint 枚举（cn / intl）。运行时会在构造 provider 时用 refresh token 换取短期有效的 access token。
2. Qwen OAuth 刷新流程：[providers.models.qwen.<alias>] oauth_refresh_token = "..."（可选配置 oauth_client_id 和 oauth_resource_url）。
3. Gemini OAuth：[providers.models.gemini.<alias>] oauth_client_id 和 oauth_client_secret；可选的 oauth_project 用于固定 Code Assist GCP 项目 ID。
4. KiloCLI / Gemini CLI / Grok Build CLI 进程设置：[providers.models.kilocli.<alias>] binary_path、[providers.models.gemini_cli.<alias>] binary_path，以及 [providers.models.grok_cli.<alias>] 中的字段 binary_path、必需的绝对 working_directory、可选的 extra_args 和 max_acp_stdout_bytes。Grok Build 别名还可以在 env_passthrough 中列出环境变量名称（工具凭据以及可选的 XAI_API_KEY 身份验证桥接）；这些值仅在生成子进程时解析，不会存储在配置中。默认情况下，身份验证使用 CLI 登录缓存。确切名称 XAI_API_KEY 是文档规定的 API 密钥身份验证原生桥接，仅在显式列出时可用；其他 XAI_* 名称以及所有 GROK_* 名称都会被拒绝。
5. 转录 / TTS 密钥：[transcription].api_key、[providers.tts.openai.<alias>].api_key、[providers.tts.elevenlabs.<alias>].api_key、[providers.tts.google.<alias>].api_key。
6. Notion / WhatsApp：[notion].api_key、[channels.whatsapp.<alias>].ws_url（测试/代理 WebSocket 覆盖配置）。