OpenClaw 从五个来源加载环境变量，且规则是永不覆盖已有值，按进程环境 → 目录 .env → 全局 .env → config env 块 → login shell 的顺序应用。如果你遇到 API 密钥读不到的问题，优先检查是否被父进程的已有变量屏蔽；nvm 用户需手动设置 NODE_EXTRA_CA_CERTS 否则 web_fetch 会报 "fetch failed"。路径类变量如 OPENCLAW_HOME、OPENCLAW_STATE_DIR 可覆盖默认的 ~/.openclaw 目录，适合 headless 服务场景。

OpenClaw 环境变量加载优先级与配置指南

OpenClaw 从多个来源读取环境变量，规则是永不覆盖已有值。了解优先级顺序能帮你快速定位为什么某个变量没有生效。

优先级（从高到低）

1. 进程环境（Gateway 进程从父 shell/守护进程继承的已有变量）
2. 当前工作目录的 .env 文件（dotenv 默认方式，不覆盖已有值）
3. 全局 .env 文件：~/.openclaw/.env（即 $OPENCLAW_STATE_DIR/.env，不覆盖已有值）
4. 配置中的 env 块：~/.openclaw/openclaw.json（仅在缺失时应用）
5. 可选的 login-shell 导入（env.shellEnv.enabled 或 OPENCLAW_LOAD_SHELL_ENV=1），仅对缺失的预期键生效

Ubuntu 默认安装下，OpenClaw 还会将 ~/.config/openclaw/gateway.env 作为兼容性后备（在全局 .env 之后加载）。如果两个文件冲突，OpenClaw 保留 ~/.openclaw/.env 并输出警告。

如果配置文件完全缺失，步骤 4 会跳过；如果启用了 shell 导入，步骤 5 仍会运行。

Config env 块

两种等价的内联设置方式（都不会覆盖已有值）：

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

注意：config env 块只接受纯字符串值，不支持 file:... 展开。例如 XAI_API_KEY: "file:secrets/xai-api-key.txt" 会原样传递给 provider。

对于文件类型的 provider 密钥，应在支持 SecretRef 的字段上使用 secret 引用：

{
  secrets: {
    providers: {
      xai_key_file: {
        source: "file",
        path: "~/.openclaw/secrets/xai-api-key.txt",
        mode: "singleValue",
      },
    },
  },
  models: {
    providers: {
      xai: {
        apiKey: { source: "file", provider: "xai_key_file", id: "value" },
      },
    },
  },
}

详见 Secrets Management 和 SecretRef credential surface。

Shell 环境导入

env.shellEnv 会运行你的 login shell 并仅导入缺失的预期键：

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

等价的环境变量：

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

运行时注入的环境变量

OpenClaw 向子进程注入上下文标记，可在 shell/profile 逻辑中用于区分场景：

• OPENCLAW_SHELL=exec：通过 exec 工具运行的命令
• OPENCLAW_SHELL=acp：ACP 运行时后端进程派生（如 acpx）
• OPENCLAW_SHELL=acp-client：openclaw acp client 派生 ACP bridge 进程时
• OPENCLAW_SHELL=tui-local：本地 TUI 的 ! shell 命令

这些不需要用户配置。

UI 相关环境变量

• OPENCLAW_THEME=light：强制亮色 TUI 主题（终端浅色背景时）
• OPENCLAW_THEME=dark：强制暗色 TUI 主题
• COLORFGBG：如果终端导出此变量，OpenClaw 自动根据背景色选择 TUI 主题

配置中的环境变量替换

在配置字符串值中使用 ${VAR_NAME} 语法直接引用环境变量：

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

详见 Configuration: Env var substitution。

SecretRef 与 ${ENV} 字符串

OpenClaw 支持两种环境变量驱动的模式：

• ${VAR} 字符串替换：应用于配置值
• SecretRef 对象（{ source: "env", provider: "default", id: "VAR" }）：用于支持密钥引用的字段

两者都在激活时从进程环境中解析。SecretRef 详细文档见 Secrets Management。config env 块本身不解析 SecretRef 或 file:... 简写值。

路径相关环境变量

变量	用途
OPENCLAW_HOME	覆盖所有内部路径解析使用的 home 目录（~/.openclaw/、agent 目录、会话、凭据）。适合作为专用服务用户运行 OpenClaw。
OPENCLAW_STATE_DIR	覆盖状态目录（默认 ~/.openclaw）。
OPENCLAW_CONFIG_PATH	覆盖配置文件路径（默认 ~/.openclaw/openclaw.json）。
OPENCLAW_INCLUDE_ROOTS	路径列表，允许 $include 指令解析配置文件目录之外的文件（默认无，$include 限制在配置目录内）。支持波浪号展开。

OPENCLAW_HOME 详细说明

当设置后，OPENCLAW_HOME 会替换系统 $HOME / os.homedir() 用于所有内部路径解析，实现 headless 服务账号的完整文件系统隔离。

优先级： OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

示例（macOS LaunchDaemon）：

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/user</string>
</dict>

OPENCLAW_HOME 也可以设置为波浪路径（如 ~/svc），使用前会通过 $HOME 展开。

日志相关环境变量

变量	用途
OPENCLAW_LOG_LEVEL	覆盖日志级别，同时影响文件和终端（如 debug、trace）。优先于 logging.level 和 logging.consoleLevel 配置，无效值被忽略并输出警告。
OPENCLAW_DEBUG_MODEL_TRANSPORT	在 info 级别输出模型请求/响应耗时诊断，不开启全局 debug 日志。
OPENCLAW_DEBUG_MODEL_PAYLOAD	模型 payload 诊断：summary、tools 或 full-redacted（full-redacted 会截断并脱敏，可能包含 prompt/message 文本）。
OPENCLAW_DEBUG_SSE	流式诊断：events 输出首帧/完成时间，peek 额外包含前五个脱敏的 SSE 事件。
OPENCLAW_DEBUG_CODE_MODE	Code-mode 模型面诊断，包括 provider 工具隐藏和 exec/wait-only 强制执行。

nvm 用户：web_fetch TLS 失败

如果 Node.js 通过 nvm（而非系统包管理器）安装，内置的 fetch() 使用 nvm 自带的 CA 证书库，可能缺少现代根证书（ISRG Root X1/X2、DigiCert Global Root G2 等），导致 web_fetch 报错 "fetch failed"。

在 Linux 上，OpenClaw 会自动检测 nvm 并在启动环境应用修复：

• openclaw gateway install 会将 NODE_EXTRA_CA_CERTS 写入 systemd 服务环境
• openclaw CLI 入口点会在 Node 启动前用 NODE_EXTRA_CA_CERTS 重新执行自身

手动修复（旧版本或直接 node ... 启动）： 启动前导出变量：

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

不要仅依赖写入 ~/.openclaw/.env；Node 在进程启动时读取 NODE_EXTRA_CA_CERTS，写入 .env 文件为时已晚。

遗留环境变量

OpenClaw 只读取 OPENCLAW_* 前缀的变量。早期版本的 CLAWDBOT_* 和 MOLTBOT_* 前缀被静默忽略。如果进程启动时检测到这些遗留变量，OpenClaw 会输出一次 Node deprecation 警告（OPENCLAW_LEGACY_ENV_VARS），列出检测到的前缀和总数量。将每个值的遗留前缀替换为 OPENCLAW_（例如 CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN）即可。

相关文档

• Gateway 配置
• FAQ：环境变量和 .env 加载
• 模型概览

常见问题

环境变量在配置中用了 ${VAR} 语法但没生效，为什么？

检查 ${VAR} 是否已在进程环境或某个非覆盖来源中设置。注意 config env 块不覆盖已有值；如果父进程已拥有该变量，即使 .env 中重新定义也不会生效。另外，${VAR} 仅在配置字符串值中展开，不会在 env 块内递归替换。

web_fetch 报 "fetch failed"，怎么排查？

先确认 Node.js 是否通过 nvm 安装。如果是，运行 openclaw gateway install 或手动导出 NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt 后再启动 Gateway。如果已修复还不行，用 curl -v https://example.com 测试系统 CA 是否完整。

OPENCLAW_HOME 和 OPENCLAW_STATE_DIR 有什么区别？

OPENCLAW_STATE_DIR 仅修改状态目录（默认 ~/.openclaw），而 OPENCLAW_HOME 会替换所有内部路径解析的基准家目录，包括 agent 目录、会话和凭据。设置 OPENCLAW_HOME 通常比单独设置 OPENCLAW_STATE_DIR 更彻底，适合完全隔离的服务账户。