环境变量

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

运行时注入的环境变量

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

• OPENCLAW_SHELL=exec：通过 exec 工具运行的命令会设置此变量。
• OPENCLAW_SHELL=acp：ACP 运行时后端进程启动时设置（例如 acpx）。
• OPENCLAW_SHELL=acp-client：openclaw acp client 启动 ACP 桥接进程时设置。
• 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}",
      },
    },
  },
}

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

Secret refs 与 ${ENV} 字符串

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

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

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

路径相关环境变量

日志

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 展开。

相关文档

• 网关配置
• 常见问题：环境变量和 .env 加载
• 模型概述