OpenClaw的环境变量指南

AI摘要：OpenClaw从多源加载环境变量，核心规则是不覆盖已有值。介绍了进程环境、本地及全局.env文件等加载来源及优先级。还阐述了配置env块、Shell环境导入方法，以及配置中环境变量替换方式，强调加载遵循“不覆盖”原则及相关补充规则。

OpenClaw 会从多个来源加载环境变量，其核心规则为：已存在的环境变量值不会被任何来源的配置覆盖。
优先级顺序（从高到低）
进程环境：Gateway 网关进程会读取父 shell / 守护进程中已存在的环境变量；
本地 .env 文件：当前工作目录下的 .env 文件（dotenv 默认加载规则，不覆盖已有值）；
全局 .env 文件：路径为 ~/.openclaw/.env（等同于 $OPENCLAW_STATE_DIR/.env，不覆盖已有值）；
配置文件 env 块：位于 ~/.openclaw/openclaw.json 中的 env 配置块，仅在对应变量未定义时生效；
登录 Shell 环境导入：需通过 env.shellEnv.enabled=true 或设置 OPENCLAW_LOAD_SHELL_ENV=1 启用，仅补充缺失的预设环境变量键名。
注意：若 openclaw.json 配置文件完全不存在，上述第 4 步会直接跳过；但只要开启了 Shell 环境导入，第 5 步仍会正常执行。
配置 env 块
以下两种写法均可设置内联环境变量（均遵循 “不覆盖已有值” 规则）：
json
{
env: {

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

},
}
Shell 环境导入
env.shellEnv 配置项可启动登录 Shell，并仅导入缺失的预设环境变量键名，配置示例如下：
json
{
env: {

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

},
}
对应的环境变量等效配置：
plaintext
OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000
配置中的环境变量替换
在配置文件的字符串类型值中，可通过 ${VAR_NAME} 语法直接引用已定义的环境变量，示例如下：
json
{
models: {

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

},
}
总结
OpenClaw 加载环境变量的核心原则是 “不覆盖已有值”，且不同来源按固定优先级生效；
env 配置块和 Shell 环境导入仅补充缺失变量，前者依赖配置文件，后者需手动启用；
配置字符串支持 ${VAR_NAME} 语法引用环境变量，实现配置的动态替换。