环境变量

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），仅对缺失的预期键生效。

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

Config env 块

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

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

Shell 环境导入

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

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

等价的环境变量：

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

运行时注入的环境变量

OpenClaw 还会向子进程注入上下文标记：

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

这些是运行时标记（不需要用户配置），可在 shell/profile 逻辑中用于应用特定于上下文的规则。

UI 相关环境变量

• OPENCLAW_THEME=light：当你的终端有浅色背景时强制使用亮色 TUI 主题。
• OPENCLAW_THEME=dark：强制使用暗色 TUI 主题。
• COLORFGBG：如果你的终端导出了此变量，OpenClaw 会使用背景颜色提示自动选择 TUI 主题。

配置中的环境变量替换

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

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

详见 配置：环境变量替换。

SecretRef 与 ${ENV} 字符串

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

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

两者都在激活时从进程环境中解析。SecretRef 的详细文档见 密钥管理。

路径相关环境变量

变量	用途
OPENCLAW_HOME	覆盖所有内部路径解析使用的 home 目录（~/.openclaw/、agent 目录、会话、凭据）。作为专用服务用户运行 OpenClaw 时很有用。
OPENCLAW_STATE_DIR	覆盖状态目录（默认 ~/.openclaw）。
OPENCLAW_CONFIG_PATH	覆盖配置文件路径（默认 ~/.openclaw/openclaw.json）。

日志相关

变量	用途
OPENCLAW_LOG_LEVEL	覆盖文件和控制台的日志级别（如 debug、trace），优先于配置中的 logging.level 和 logging.consoleLevel，无效值会被忽略并输出警告。

OPENCLAW_HOME

设置后，OPENCLAW_HOME 会替换所有内部路径解析使用的系统 home 目录（$HOME / os.homedir()），实现无头服务账号的完整文件系统隔离。

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

示例（macOS LaunchDaemon）：

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

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

nvm 用户：web_fetch TLS 失败

如果 Node.js 是通过 nvm（而非系统包管理器）安装的，内置的 fetch() 使用 nvm 自带的 CA 证书库，该证书库可能缺少现代根证书（Let's Encrypt 的 ISRG Root X1/X2、DigiCert Global Root G2 等）。这会导致 web_fetch 在大多数 HTTPS 网站上失败，报错 "fetch failed"。

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

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

手动修复（适用于旧版本或直接 node ... 启动）：

在启动 OpenClaw 前导出该变量：

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

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

相关文档

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