OpenClaw多环境管理：开发、测试、生产

前言

在实际运营中，直接在生产环境修改配置或测试新功能是非常危险的操作。一个配置错误就可能导致所有用户的对话中断。本文将详细讲解如何为 OpenClaw 搭建开发、测试、生产三套隔离环境，让你能安全地进行调试和验证。

一、环境隔离策略

1.1 三套环境的定位

环境	用途	数据	稳定性要求
开发 (dev)	本地开发调试、新功能实验	测试数据	低
测试 (staging)	上线前验证、回归测试	模拟真实数据	中
生产 (production)	实际用户使用	真实数据	极高

1.2 隔离维度

每套环境需要隔离以下内容：

配置文件：不同的 API Key、模型参数
频道账号：不同的 Bot Token（避免测试消息发给真实用户）
数据存储：独立的会话数据和日志
网络端口：不同的 Gateway 端口，避免冲突

二、使用配置文件隔离

2.1 环境变量指定配置

OpenClaw 支持通过 OPENCLAW_ENV 环境变量加载不同的配置：

# 开发环境
OPENCLAW_ENV=development openclaw up

# 测试环境
OPENCLAW_ENV=staging openclaw up

# 生产环境（默认）
OPENCLAW_ENV=production openclaw up

OpenClaw 会依次查找以下配置文件：

~/.config/openclaw/openclaw.development.json5   # 开发环境
~/.config/openclaw/openclaw.staging.json5       # 测试环境
~/.config/openclaw/openclaw.production.json5    # 生产环境（或 openclaw.json5）

2.2 开发环境配置示例

// ~/.config/openclaw/openclaw.development.json5
{
  "env": "development",
  "gateway": {
    "port": 18700  // 使用不同端口
  },
  "model": {
    // 使用低成本模型，降低测试费用
    "provider": "claude",
    "model": "claude-3-5-haiku",
    "apiKey": "sk-ant-dev-xxxxx"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "DEV_BOT_TOKEN"  // 专用的测试 Bot
    }
    // 开发环境只启用一个频道
  },
  "conversation": {
    "maxHistory": 5   // 减少历史记录以降低成本
  },
  "log": {
    "level": "debug",  // 详细日志便于调试
    "dir": "~/.openclaw/dev/logs/"
  },
  "data": {
    "dir": "~/.openclaw/dev/data/"  // 隔离数据目录
  }
}

2.3 测试环境配置示例

// ~/.config/openclaw/openclaw.staging.json5
{
  "env": "staging",
  "gateway": {
    "port": 18750
  },
  "model": {
    "provider": "claude",
    "model": "claude-3.5-sonnet",  // 与生产一致的模型
    "apiKey": "sk-ant-staging-xxxxx"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "STAGING_BOT_TOKEN"
    },
    "whatsapp": {
      "enabled": true,
      "phoneId": "STAGING_PHONE_ID"
    }
  },
  "conversation": {
    "maxHistory": 20  // 与生产一致
  },
  "log": {
    "level": "info",
    "dir": "~/.openclaw/staging/logs/"
  },
  "data": {
    "dir": "~/.openclaw/staging/data/"
  }
}

2.4 生产环境配置示例

// ~/.config/openclaw/openclaw.production.json5
{
  "env": "production",
  "gateway": {
    "port": 18789  // 标准生产端口
  },
  "model": {
    "provider": "claude",
    "model": "claude-3.5-sonnet",
    "apiKey": "sk-ant-prod-xxxxx"
  },
  "channels": {
    "telegram": { "enabled": true, "botToken": "PROD_BOT_TOKEN" },
    "whatsapp": { "enabled": true },
    "discord": { "enabled": true }
  },
  "log": {
    "level": "info",
    "format": "json"  // 生产环境使用 JSON 格式便于采集
  },
  "watchdog": {
    "enabled": true  // 生产环境开启看门狗
  }
}

三、使用 .env 文件管理敏感配置

3.1 按环境分离 .env 文件

# 目录结构
~/.config/openclaw/
├── openclaw.development.json5
├── openclaw.staging.json5
├── openclaw.production.json5
├── .env.development
├── .env.staging
└── .env.production

# .env.development
OPENCLAW_ENV=development
CLAUDE_API_KEY=sk-ant-dev-xxxxx
TELEGRAM_BOT_TOKEN=111111:DEV_TOKEN
OPENCLAW_PORT=18700

# .env.production
OPENCLAW_ENV=production
CLAUDE_API_KEY=sk-ant-prod-xxxxx
TELEGRAM_BOT_TOKEN=222222:PROD_TOKEN
WHATSAPP_PHONE_ID=prod_phone_id
DISCORD_BOT_TOKEN=prod_discord_token
OPENCLAW_PORT=18789

3.2 加载环境文件

# 手动指定环境文件
openclaw up --env-file ~/.config/openclaw/.env.staging

# 或通过环境变量
export OPENCLAW_ENV_FILE=~/.config/openclaw/.env.staging
openclaw up

四、Docker 多环境部署

4.1 使用 Docker Compose 管理多环境

# docker-compose.yml
version: '3.8'

services:
  openclaw-dev:
    image: openclaw/openclaw:latest
    container_name: openclaw-dev
    environment:
      - OPENCLAW_ENV=development
    env_file:
      - .env.development
    ports:
      - "18700:18789"
    volumes:
      - ./config/openclaw.development.json5:/root/.config/openclaw/openclaw.json5
      - openclaw-dev-data:/root/.openclaw
    profiles: ["dev"]

  openclaw-staging:
    image: openclaw/openclaw:latest
    container_name: openclaw-staging
    environment:
      - OPENCLAW_ENV=staging
    env_file:
      - .env.staging
    ports:
      - "18750:18789"
    volumes:
      - ./config/openclaw.staging.json5:/root/.config/openclaw/openclaw.json5
      - openclaw-staging-data:/root/.openclaw
    profiles: ["staging"]

  openclaw-prod:
    image: openclaw/openclaw:latest
    container_name: openclaw-prod
    environment:
      - OPENCLAW_ENV=production
    env_file:
      - .env.production
    ports:
      - "18789:18789"
    volumes:
      - ./config/openclaw.production.json5:/root/.config/openclaw/openclaw.json5
      - openclaw-prod-data:/root/.openclaw
    restart: always
    profiles: ["prod"]

volumes:
  openclaw-dev-data:
  openclaw-staging-data:
  openclaw-prod-data:

# 启动开发环境
docker compose --profile dev up -d

# 启动测试环境
docker compose --profile staging up -d

# 启动生产环境
docker compose --profile prod up -d

4.2 同一服务器并行运行

如果需要在同一台服务器上运行多个环境：

# 使用不同的配置目录和端口
OPENCLAW_ENV=staging OPENCLAW_PORT=18750 openclaw up -d --name openclaw-staging
OPENCLAW_ENV=production OPENCLAW_PORT=18789 openclaw up -d --name openclaw-prod

五、发布流程

5.1 推荐的变更发布流程

1. 本地开发 (dev)
   ↓ 功能开发和调试完成
2. 部署到测试环境 (staging)
   ↓ 验证通过、团队审核
3. 部署到生产环境 (production)
   ↓ 监控观察
4. 确认稳定

5.2 配置变更检查清单

在将配置从测试环境推广到生产环境前，逐项检查：

# 1. 对比两个环境的配置差异（排除敏感信息）
diff <(openclaw config show --env staging | grep -v "apiKey\|token\|password") \
     <(openclaw config show --env production | grep -v "apiKey\|token\|password")

# 2. 在测试环境验证配置有效性
OPENCLAW_ENV=staging openclaw config validate

# 3. 在测试环境运行诊断
OPENCLAW_ENV=staging openclaw doctor

# 4. 确认没有遗留测试数据

5.3 回滚方案

如果新配置在生产环境出现问题：

# 方案一：恢复备份的配置文件
cp ~/.config/openclaw/openclaw.production.json5.bak ~/.config/openclaw/openclaw.production.json5
openclaw restart

# 方案二：使用 Git 回滚
cd ~/.config/openclaw
git checkout HEAD~1 -- openclaw.production.json5
openclaw restart

# 方案三：使用 openclaw 内置回滚
openclaw config rollback  # 回滚到上一个配置版本

六、安全注意事项

永远不要共享 API Key：每个环境使用独立的 API Key，方便追踪用量和在泄露时单独吊销
生产环境的 Bot Token 单独管理：避免测试消息发送到真实用户
敏感信息不入 Git：使用 .gitignore 排除 .env 文件和包含密钥的配置
最小权限原则：开发人员只有开发/测试环境的访问权限
定期轮换密钥：特别是在有人员变动时

# .gitignore 示例
.env*
*.production.json5
credentials/
ssl/

通过合理的多环境管理，你可以放心地在不影响真实用户的情况下测试新配置、新功能和新技能。这是保障 OpenClaw 生产环境稳定性的重要基础实践。