环境变量

OpenClaw 从多个来源获取环境变量。规则是**永不覆盖现有?*?

优先级（最??最低）

  1. 进程环境（网关进程已从父 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}",
      },
    },
  },
}

请参阅配置：环境变量替换获取完整详情?

Secret 引用 vs ${ENV} 字符?

OpenClaw 支持两种环境驱动模式?

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

两者都在激活时从进程环境解析。SecretRef 详情记录在Secrets 管理中?

路径相关环境变量

变量用?
OPENCLAW_HOME覆盖用于所有内部路径解析的主目录（~/.openclaw/、代理目录、会话、凭据）。在以专用服务用户运?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 / 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 展开?

相关