6.6 环境变量

OpenClaw 支持通过环境变量配置 Gateway 和 Agent 的各项行为,便于在不同环境下灵活部署。

概述

环境变量提供了一种无需修改配置文件即可调整系统行为的方式。OpenClaw 会按以下顺序加载环境变量:

1. 系统环境变量
2. 当前目录的 .env 文件
3. 全局 ~/.openclaw/.env 文件
4. 配置文件中的 env 字段

核心环境变量

Gateway 配置

变量名	说明	默认值
OPENCLAW_CONFIG_PATH	配置文件路径	~/.openclaw/openclaw.json
OPENCLAW_STATE_DIR	状态目录	~/.openclaw
OPENCLAW_GATEWAY_PORT	Gateway 端口	18789
OPENCLAW_GATEWAY_TOKEN	Gateway 认证 token	-
OPENCLAW_GATEWAY_URL	Gateway WebSocket URL	ws://localhost:18789

开发模式

变量名	说明	默认值
OPENCLAW_PROFILE	配置 profile (如 dev)	-
DEBUG	调试日志命名空间	-
LOG_LEVEL	日志级别	info
OPENCLAW_RAW_STREAM	启用原始流日志	0
OPENCLAW_RAW_STREAM_PATH	原始流日志路径	~/.openclaw/logs/raw-stream.jsonl

Shell 环境

变量名	说明	默认值
OPENCLAW_LOAD_SHELL_ENV	从登录 shell 加载环境	0
OPENCLAW_SHELL_ENV_TIMEOUT_MS	Shell 加载超时(毫秒)	15000

频道相关

变量名	说明	默认值
OPENCLAW_SKIP_CHANNELS	跳过频道提供商初始化	0

API Keys

各 AI 模型提供商的 API Keys:

常用提供商

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-...

# OpenRouter
OPENROUTER_API_KEY=sk-or-...

# Groq
GROQ_API_KEY=gsk-...

# Vercel AI Gateway
VERCEL_GATEWAY_API_KEY=...

# Google AI
GOOGLE_AI_API_KEY=...

其他提供商

# Cohere
COHERE_API_KEY=...

# Together AI
TOGETHER_API_KEY=...

# Replicate
REPLICATE_API_TOKEN=...

.env 文件

项目级 .env

在项目目录创建 .env 文件:

# Gateway 配置
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_GATEWAY_TOKEN=your-secret-token

# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# 调试
LOG_LEVEL=debug
DEBUG=openclaw:*

全局 .env

全局配置文件 ~/.openclaw/.env:

# 全局 API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# 默认配置
OPENCLAW_STATE_DIR=~/.openclaw
LOG_LEVEL=info

配置文件中的环境变量

内联定义

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

变量引用

配置中使用 ${VAR_NAME} 引用环境变量:

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  },
  "gateway": {
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

转义

使用 $${VAR} 输出字面量 ${VAR}:

{
  "example": "$${NOT_A_VARIABLE}"  // 结果: "${NOT_A_VARIABLE}"
}

Shell 环境加载

启用后,OpenClaw 会从登录 shell 加载缺失的环境变量:

配置方式

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

环境变量方式

export OPENCLAW_LOAD_SHELL_ENV=1
export OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000
openclaw gateway start

多环境配置

开发环境

# .env.dev
OPENCLAW_PROFILE=dev
OPENCLAW_STATE_DIR=~/.openclaw-dev
OPENCLAW_GATEWAY_PORT=19001
LOG_LEVEL=debug
DEBUG=openclaw:*

生产环境

# .env.prod
OPENCLAW_PROFILE=prod
OPENCLAW_STATE_DIR=~/.openclaw
OPENCLAW_GATEWAY_PORT=18789
LOG_LEVEL=warn

加载特定环境

# 加载开发环境
export $(cat .env.dev | xargs)
openclaw gateway start

# 或使用 dotenv
dotenv -e .env.dev -- openclaw gateway start

安全建议

• 不要提交 .env 文件 - 将 .env 添加到 .gitignore
• 使用强 token - Gateway token 应使用强随机字符串
• 限制权限 - 确保 .env 文件权限为 600
• 定期轮换 - 定期更换 API keys 和 tokens

常用命令

# 查看当前环境变量
env | grep OPENCLAW

# 临时设置环境变量
OPENCLAW_GATEWAY_PORT=19001 openclaw gateway start

# 从文件加载
export $(cat .env | xargs)

# 验证配置
openclaw doctor --check-env