环境变量

环境变量¶

OpenClaw 从父进程读取环境变量，此外还会读取：

.env（来自当前工作目录，如果存在）
~/.openclaw/.env（全局回退）

这两个文件都不会覆盖已有的环境变量。你也可以在配置中设置内联环境变量：

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

Shell 环境变量导入（可选）

如果启用并且预期的键未被设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键：

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

等效环境变量：OPENCLAW_LOAD_SHELL_ENV=1。默认 timeoutMs：15000。

配置值中的环境变量替换

在任何配置字符串值中，使用 ${VAR_NAME} 引用环境变量：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

规则：

仅匹配大写名称：[A-Z_][A-Z0-9_]*
缺失/为空的环境变量会保持可见的未解析状态，发出警告，并且无法供需要该值的消费者使用
使用 $${VAR} 转义可生成字面量 ${VAR} 值
可在 $include 文件中使用
内联替换："${BASE}/v1" → "https://api.example.com/v1"

Secret 引用（env、file、exec、store）

对于支持 SecretRef 对象的字段，你可以使用：

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccount: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

上述 env 引用使用内置的 default provider，并且不需要 secrets.providers.default 条目，除非 secrets.defaults.env 选择了其他别名。同样的规则也适用于 store 引用和 secrets.defaults.store。参见 Secrets 管理了解 provider 的优先级以及必需的 file/exec provider 配置。支持的凭据路径列于 SecretRef 凭据范围。

参见环境了解完整的优先级和来源。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw