OpenClaw 🦞

环境变量

环境变量

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

运行时注入的环境变量

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 逻辑中使用 以应用特定于上下文的规则。

配置中的环境变量替换

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

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

有关完整详情，请参阅 配置：配置中的环境变量替换。

秘密引用 vs ${ENV} 字符串

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

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

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

路径相关的环境变量

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

日志

变量目的
OPENCLAW_LOG_LEVEL覆盖文件和console的日志级别（例如 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 展开。

相关