环境变量

OpenClaw 会从多个来源读取环境变量。核心规则是永远不覆盖已有的值。

优先级（从高到低）

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

如果配置文件完全不存在，会跳过第 4 步；但如果启用了 shell 导入，仍会执行。

配置文件中的 env 块

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

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

Shell 环境导入

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

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

对应的环境变量：

  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

配置文件中的环境变量替换

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

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

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

相关内容