Skip to main content

​
环境变量

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}",
      },
    },
  },
}
完整细节请参见 配置：配置中的环境变量替换。

​
Secret 引用与 ${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覆盖文件及控制台日志级别（例如 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 展开。

​
相关内容