环境变量与配置文件高级用法

配置优先级

OpenClaw 的配置来源按以下优先级生效（从高到低）：

命令行参数
环境变量
.env 文件
用户配置文件（~/.openclaw/config.json）
默认值

环境变量命名规则

OpenClaw 的所有环境变量使用 OPENCLAW_ 前缀：

# Gateway 配置
OPENCLAW_PORT=3000
OPENCLAW_HOST=0.0.0.0
OPENCLAW_BASE_URL=https://gateway.example.com

# 供应商配置
OPENCLAW_OPENAI_API_KEY=sk-your-key
OPENCLAW_OPENAI_BASE_URL=https://api.openai.com/v1
OPENCLAW_ANTHROPIC_API_KEY=sk-ant-your-key

# 频道配置
OPENCLAW_TELEGRAM_TOKEN=123456:ABC-DEF
OPENCLAW_DISCORD_TOKEN=your-discord-token

# 日志配置
OPENCLAW_LOG_LEVEL=info
OPENCLAW_LOG_FORMAT=json

.env 文件

在项目目录下创建 .env 文件：

# .env
OPENCLAW_PORT=3000
OPENCLAW_LOG_LEVEL=info

# 供应商密钥
OPENAI_API_KEY=sk-your-key
ANTHROPIC_API_KEY=sk-ant-key

# 频道 Token
TELEGRAM_BOT_TOKEN=123456:ABC-DEF

OpenClaw 启动时会自动加载 .env 文件。

多环境配置

使用不同的 .env 文件

# 开发环境
openclaw start --env-file .env.development

# 测试环境
openclaw start --env-file .env.staging

# 生产环境
openclaw start --env-file .env.production

使用不同的配置文件

# 指定配置文件
OPENCLAW_CONFIG=./config.production.json openclaw start

配置继承

使用基础配置 + 环境覆盖模式：

// config.base.json - 基础配置
{
  "gateway": {
    "port": 3000
  },
  "logging": {
    "level": "info"
  }
}

// config.production.json - 生产环境覆盖
{
  "extends": "./config.base.json",
  "gateway": {
    "host": "0.0.0.0",
    "baseUrl": "https://gateway.example.com"
  },
  "logging": {
    "level": "warn"
  }
}

条件配置

根据环境变量有条件地应用配置：

{
  "providers": {
    "openai": {
      "type": "openai",
      "apiKey": "{{OPENAI_API_KEY}}"
    }
  },
  "models": {
    "main": {
      "provider": "openai",
      "model": "{{OPENCLAW_DEFAULT_MODEL|gpt-4o-mini}}"
    }
  }
}

{{VAR|default}} 语法支持默认值——当环境变量未设置时使用默认值。

Docker 环境变量

Docker 部署时通过环境变量注入配置：

services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_PORT=3000
      - OPENCLAW_LOG_LEVEL=info
      - OPENAI_API_KEY=sk-your-key
      - TELEGRAM_BOT_TOKEN=123456:ABC
    env_file:
      - .env.production

配置验证

# 验证当前配置
openclaw configure --validate

# 显示配置来源
openclaw configure --show --sources

Configuration Sources:
  gateway.port: 3000 (env: OPENCLAW_PORT)
  gateway.host: 0.0.0.0 (config: ~/.openclaw/config.json)
  logging.level: debug (cli: --log-level)
  providers.openai.apiKey: sk-*** (secrets)

配置热重载

OpenClaw 支持配置文件热重载，修改配置后无需重启：

# 发送重载信号
openclaw reload

# 或
kill -HUP $(pgrep openclaw)

支持热重载的配置项：

模型参数（temperature、maxTokens 等）
系统提示词
日志级别
速率限制

不支持热重载的配置项（需要重启）：

Gateway 端口和地址
频道添加/删除
供应商添加/删除

配置调试

# 打印解析后的完整配置（包含所有来源合并后的结果）
openclaw configure --dump

# 查看特定配置项的解析过程
openclaw configure --trace gateway.port

Tracing: gateway.port
  Default: 3000
  Config file: not set
  Env (OPENCLAW_PORT): 8080
  CLI args: not set
  → Resolved value: 8080 (from env)

安全注意事项

不要将 .env 文件提交到 Git：确保 .gitignore 包含 .env*
使用 secrets 管理密钥：环境变量适合非敏感配置
限制配置文件权限：chmod 600 ~/.openclaw/config.json
生产环境避免 debug 级别日志：可能记录敏感信息

总结

OpenClaw 的配置系统支持多种来源和灵活的优先级机制。通过合理使用环境变量、配置文件和 secrets 系统，可以在不同环境间安全地管理配置，实现开发、测试、生产环境的配置隔离。