Skip to main content

​
环境变量

OpenClaw 从多个来源拉取环境变量。规则是 绝不覆盖已有值。

​
优先级顺序(从高到低)

OpenClaw 按以下顺序加载环境变量:
1

进程环境

Gateway 进程从父 shell/守护进程继承的环境变量
2

当前目录 .env

当前工作目录下的 .env 文件(dotenv 默认;不覆盖已有值)
3

全局 .env

全局 .env 文件,位于 ~/.openclaw/.env(即 $OPENCLAW_STATE_DIR/.env;不覆盖已有值)
4

配置文件 env 块

配置文件 env 块,在 ~/.openclaw/openclaw.json 中(仅在缺失时应用)
5

Shell 环境导入

可选的登录 shell 导入(通过 env.shellEnv.enabled 或 OPENCLAW_LOAD_SHELL_ENV=1 启用),仅为缺失的预期键导入
如果配置文件完全缺失,则跳过第 4 步;但如果启用,仍会执行 shell 导入。

​
.env 文件示例

基于源代码中的 .env.example 文件,以下是常用的环境变量配置示例: 
# OpenClaw .env 示例
#
# 快速开始:
# 1) 复制此文件到 `.env`(用于从本仓库本地运行),或到 `~/.openclaw/.env`(用于 launchd/systemd 守护进程)
# 2) 仅填写您使用的值
# 3) 将真实密钥保留在 git 之外

# -----------------------------------------------------------------------------
# Gateway 认证 + 路径
# -----------------------------------------------------------------------------
# 如果 gateway 绑定超出 loopback,建议设置
OPENCLAW_GATEWAY_TOKEN=change-me-to-a-long-random-token
# 生成示例: openssl rand -hex 32

# 可选的替代认证模式(使用 token 或 password)
# OPENCLAW_GATEWAY_PASSWORD=change-me-to-a-strong-password

# 可选的路径覆盖(显示默认值作为参考)
# OPENCLAW_STATE_DIR=~/.openclaw
# OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
# OPENCLAW_HOME=~

# 可选:从您的登录 shell profile 导入缺失的键
# OPENCLAW_LOAD_SHELL_ENV=1
# OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

# -----------------------------------------------------------------------------
# 模型提供商 API 密钥(至少设置一个)
# -----------------------------------------------------------------------------
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=sk-or-...

# 可选的额外提供商
# ZAI_API_KEY=...
# AI_GATEWAY_API_KEY=...
# MINIMAX_API_KEY=...

# -----------------------------------------------------------------------------
# 渠道(仅设置您启用的)
# -----------------------------------------------------------------------------
# TELEGRAM_BOT_TOKEN=123456:ABCDEF...
# DISCORD_BOT_TOKEN=...
# SLACK_BOT_TOKEN=xoxb-...
# SLACK_APP_TOKEN=xapp-...

# 可选的渠道环境变量备用值
# MATTERMOST_BOT_TOKEN=...
# MATTERMOST_URL=https://chat.example.com

# -----------------------------------------------------------------------------
# 工具 + 语音/媒体(可选)
# -----------------------------------------------------------------------------
# BRAVE_API_KEY=...
# PERPLEXITY_API_KEY=pplx-...
# FIRECRAWL_API_KEY=...

# ELEVENLABS_API_KEY=...
# XI_API_KEY=...  # ElevenLabs 的别名
# DEEPGRAM_API_KEY=...

​
配置文件中的 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}"
      }
    }
  }
}

​
与路径相关的环境变量

变量作用
OPENCLAW_HOME覆盖用于所有内部路径解析的主目录(如 ~/.openclaw/、agent 目录、会话、凭据)。适用于将 OpenClaw 以专用服务用户运行的场景。
OPENCLAW_STATE_DIR覆盖状态目录(默认 ~/.openclaw)。
OPENCLAW_CONFIG_PATH覆盖配置文件路径(默认 ~/.openclaw/openclaw.json)。

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

​
日志相关

变量作用
OPENCLAW_LOG_LEVEL覆盖文件及控制台日志级别(例如 debug、trace)。优先级高于配置中的 logging.level 和 logging.consoleLevel。无效值会被忽略并输出警告。

​
Secret 引用与 $ 字符串

OpenClaw 支持两种基于环境变量的模式:
  • 配置值中的 ${VAR} 字符串替换
  • 支持秘密引用的字段中使用 SecretRef 对象({ source: "env", provider: "default", id: "VAR" })
两者均在激活时从进程环境解析。

​
下一步

配置

了解完整的配置选项

Docker 部署

在 Docker 中使用环境变量