OpenClaw环境变量与配置管理：搞定那些比女朋友还难搞的配置项

世界上有一种配置文件，叫 openclaw.yaml。3分14秒前你改了一行，3分14秒后整个Agent崩了。配置管理这件事，马虎不得。

目录

🗺️ 配置体系全景

OpenClaw的配置系统是分层的，优先级从高到低：

层级文件/来源优先级用途
1环境变量最高敏感信息、运行时覆盖
2CLI参数高临时覆盖
3openclaw.yaml中主配置文件
4.env中低环境变量模板
5默认值最低内置默认配置

配置文件位置

~/.openclaw/
├── openclaw.yaml       # 主配置文件
├── .env                # 环境变量（含API密钥）
├── agents/             # Agent配置
│   └── default.yaml
├── skills/             # 自定义Skills
└── sessions/           # 会话数据

📄 openclaw.yaml详解

# openclaw.yaml 完整配置示例

# === 基础设置 ===
agent:
  name: "my-agent"
  model: "claude-sonnet-4-20250514"
  thinking: "medium"  # off | low | medium | high
  
# === 模型路由 ===
models:
  default: "claude-sonnet-4-20250514"
  routing:
    - trigger: "写代码|编程|debug"
      model: "claude-sonnet-4-20250514"
    - trigger: "翻译|简单|快速"
      model: "gpt-4o-mini"
  fallbacks:
    - "claude-sonnet-4-20250514"
    - "gpt-4o"

# === Gateway配置 ===
gateway:
  port: 3000
  host: "0.0.0.0"
  cors:
    origins: ["http://localhost:3000"]
  
# === 工具配置 ===
tools:
  exec:
    enabled: true
    security: "allowlist"  # deny | allowlist | full
    allowlist:
      - "ls"
      - "cat"
      - "grep"
      - "git"
  browser:
    enabled: true
    headless: true
  web_search:
    enabled: true
    provider: "duckduckgo"
  web_fetch:
    enabled: true
    maxChars: 50000

# === 消息频道 ===
channels:
  telegram:
    enabled: true
    botToken: "${TELEGRAM_BOT_TOKEN}"
  discord:
    enabled: true
    botToken: "${DISCORD_BOT_TOKEN}"
  feishu:
    enabled: true
    appId: "${FEISHU_APP_ID}"
    appSecret: "${FEISHU_APP_SECRET}"

# === 安全配置 ===
security:
  sandbox:
    enabled: true
  rateLimiting:
    enabled: true
    maxRequests: 100
    windowMs: 60000

# === 记忆配置 ===
memory:
  enabled: true
  maxTokens: 10000
  consolidation: true

# === 日志配置 ===
logging:
  level: "info"  # debug | info | warn | error
  format: "json"
  output: "file"  # console | file | both

🔐 .env环境变量

# .env - 永远不要提交到Git！

# === AI模型API密钥 ===
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=...
DEEPSEEK_API_KEY=...

# === 消息平台Token ===
TELEGRAM_BOT_TOKEN=123456:ABC...
DISCORD_BOT_TOKEN=MTIz...
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx

# === 搜索API ===
BRAVE_SEARCH_API_KEY=...
SERPER_API_KEY=...

# === 存储与数据库 ===
S3_BUCKET=my-openclaw-backup
S3_ACCESS_KEY=...
S3_SECRET_KEY=...

# === OpenClaw内部 ===
OPENCLAW_LOG_LEVEL=info
OPENCLAW_GATEWAY_PORT=3000
OPENCLAW_DATA_DIR=~/.openclaw

环境变量管理最佳实践

  • 使用 .env.example 作为模板，提交到Git
  • .env 永远加入 .gitignore
  • 生产环境使用密钥管理服务（如AWS Secrets Manager）
  • 定期轮换API密钥
  • 使用 openclaw config validate 检查配置完整性

🌐 Gateway配置

# 查看当前Gateway配置
openclaw gateway config

# 动态更新配置（无需重启）
openclaw gateway config patch --set models.default=gpt-4o

# 查看配置schema
openclaw gateway config schema lookup models

# 重新加载配置
openclaw gateway config apply --file openclaw.yaml

# 重启Gateway
openclaw gateway restart

Gateway热更新

部分配置支持热更新，不需要重启：

  • ✅ 模型路由规则
  • ✅ 工具权限设置
  • ✅ 日志级别
  • ❌ 端口号（需要重启）
  • ❌ 消息频道配置（需要重启）

🧠 模型路由配置

模型路由让你根据任务类型自动选择最合适的模型，兼顾效果和成本。

# openclaw.yaml - 模型路由配置
models:
  default: "claude-sonnet-4-20250514"
  
  routing:
    # 编程任务 → 强模型
    - trigger: "代码|编程|debug|实现|开发"
      model: "claude-sonnet-4-20250514"
      
    # 翻译和简单任务 → 快模型
    - trigger: "翻译|总结|简单回答"
      model: "gpt-4o-mini"
      
    # 创意写作 → 平衡模型
    - trigger: "写作|创意|故事"
      model: "claude-sonnet-4-20250514"
      
    # 搜索类任务 → 快速模型
    - trigger: "搜索|查找|查询"
      model: "gpt-4o-mini"
  
  # Fallback链：主模型不可用时自动切换
  fallbacks:
    - "claude-sonnet-4-20250514"
    - "gpt-4o"
    - "gpt-4o-mini"
  
  # 成本控制
  costControl:
    dailyLimit: 5.00      # 每日花费上限（美元）
    alertThreshold: 0.80  # 80%时发送告警

🔒 安全密钥管理

# 检查环境变量安全性
openclaw security audit

# 检测泄露的密钥
openclaw security scan .env

# 加密敏感配置
openclaw config encrypt .env --output .env.encrypted

# 从密钥管理服务加载
openclaw config load --from aws-secrets-manager --name openclaw-prod

# 验证配置完整性
openclaw config validate

密钥泄露应急

# 1. 立即撤销泄露的密钥
# 在对应平台重新生成API Key

# 2. 更新.env文件
# 替换为新密钥

# 3. 检查使用记录
# 确认密钥未被滥用

# 4. 重启OpenClaw
openclaw gateway restart

📋 配置模板

最小配置（入门用）

# openclaw.yaml - 最小配置
agent:
  name: "my-first-agent"
  model: "gpt-4o-mini"

生产配置（推荐）

# openclaw.yaml - 生产环境配置
agent:
  name: "prod-agent"
  model: "claude-sonnet-4-20250514"
  thinking: "medium"

models:
  default: "claude-sonnet-4-20250514"
  fallbacks: ["gpt-4o", "gpt-4o-mini"]
  costControl:
    dailyLimit: 10.00

tools:
  exec:
    security: "allowlist"
  browser:
    headless: true

security:
  sandbox: true
  rateLimiting:
    enabled: true
    maxRequests: 200

logging:
  level: "warn"
  format: "json"

🔗 相关资源