环境变量配置

OpenClaw 从多个来源加载环境变量，规则是永不覆盖已有值。

加载优先级（从高到低）

1. 进程环境（Gateway 进程从父 shell/守护进程继承的变量）
2. 当前目录 .env（dotenv 默认，不覆盖）
3. 全局 .env（~/.openclaw/.env，不覆盖）
4. 配置 env 块（~/.openclaw/openclaw.json 中，仅补充缺失值）
5. 可选 login shell 导入（env.shellEnv.enabled 或 OPENCLAW_LOAD_SHELL_ENV=1，仅补充缺失的预期 Key）

配置 env 块

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Shell 环境导入

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

等效环境变量：OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

路径相关变量

变量	用途
OPENCLAW_HOME	覆盖所有内部路径解析的 home 目录
OPENCLAW_STATE_DIR	覆盖状态目录（默认 ~/.openclaw）
OPENCLAW_CONFIG_PATH	覆盖配置文件路径
OPENCLAW_INCLUDE_ROOTS	$include 指令允许解析的目录列表

日志相关变量

变量	用途
OPENCLAW_LOG_LEVEL	覆盖日志级别（debug、trace 等）
OPENCLAW_DEBUG_MODEL_TRANSPORT	模型请求/响应时序诊断
OPENCLAW_DEBUG_MODEL_PAYLOAD	模型 payload 诊断（summary/tools/full-redacted）
OPENCLAW_DEBUG_SSE	流式诊断（events/peek）

UI 变量

• OPENCLAW_THEME=light / OPENCLAW_THEME=dark：强制 TUI 调色板

配置中的变量替换

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

SecretRef vs ${ENV} 字符串

• ${VAR} 字符串替换：在配置值中直接引用
• SecretRef 对象：{ source: "env", provider: "default", id: "VAR" } 用于支持 Secret 引用的字段

nvm 用户 TLS 问题

nvm 安装的 Node.js 可能缺少现代根 CA，导致 web_fetch 失败。

Linux 自动修复：openclaw gateway install 写入 NODE_EXTRA_CA_CERTS。

手动修复：

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
openclaw gateway run

废弃变量

旧前缀 CLAWDBOT_* 和 MOLTBOT_* 已废弃，静默忽略。 将旧前缀替换为 OPENCLAW_（如 CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN）。

相关链接

• docs/gateway/configuration — Gateway 配置参考
• help-faq-first-run — 首次运行 FAQ