OpenClaw Multi-Environment Management: Development, Staging, Production

Introduction

In real-world operations, directly modifying configurations or testing new features in a production environment is extremely risky. A single configuration error could disrupt conversations for all users. This article provides a detailed guide on how to set up three isolated environments — development, staging, and production — for OpenClaw, allowing you to safely debug and validate changes.

1. Environment Isolation Strategy

1.1 Purpose of Three Environments

Environment	Purpose	Data	Stability Requirement
Development (dev)	Local development, debugging, feature experimentation	Test data	Low
Staging	Pre-release validation, regression testing	Simulated real data	Medium
Production	Actual user usage	Real data	Very High

1.2 Isolation Dimensions

Each environment needs the following to be isolated:

Configuration files: Different API Keys, model parameters
Channel accounts: Different Bot Tokens (to prevent test messages from reaching real users)
Data storage: Independent session data and logs
Network ports: Different Gateway ports to avoid conflicts

2. Isolation via Configuration Files

2.1 Specifying Configuration via Environment Variables

OpenClaw supports loading different configurations through the OPENCLAW_ENV environment variable:

# Development environment
OPENCLAW_ENV=development openclaw up

# Staging environment
OPENCLAW_ENV=staging openclaw up

# Production environment (default)
OPENCLAW_ENV=production openclaw up

OpenClaw will look for the following configuration files in order:

~/.config/openclaw/openclaw.development.json5   # Development
~/.config/openclaw/openclaw.staging.json5       # Staging
~/.config/openclaw/openclaw.production.json5    # Production (or openclaw.json5)

2.2 Development Environment Configuration Example

// ~/.config/openclaw/openclaw.development.json5
{
  "env": "development",
  "gateway": {
    "port": 18700  // Use a different port
  },
  "model": {
    // Use a low-cost model to reduce testing expenses
    "provider": "claude",
    "model": "claude-3-5-haiku",
    "apiKey": "sk-ant-dev-xxxxx"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "DEV_BOT_TOKEN"  // Dedicated test Bot
    }
    // Only enable one channel in dev
  },
  "conversation": {
    "maxHistory": 5   // Reduce history to lower costs
  },
  "log": {
    "level": "debug",  // Verbose logging for debugging
    "dir": "~/.openclaw/dev/logs/"
  },
  "data": {
    "dir": "~/.openclaw/dev/data/"  // Isolated data directory
  }
}

2.3 Staging Environment Configuration Example

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

2.4 Production Environment Configuration Example

// ~/.config/openclaw/openclaw.production.json5
{
  "env": "production",
  "gateway": {
    "port": 18789  // Standard production port
  },
  "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 format in production for log collection
  },
  "watchdog": {
    "enabled": true  // Enable watchdog in production
  }
}

3. Managing Sensitive Configuration with .env Files

3.1 Separating .env Files by Environment

# Directory structure
~/.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 Loading Environment Files

# Manually specify environment file
openclaw up --env-file ~/.config/openclaw/.env.staging

# Or via environment variable
export OPENCLAW_ENV_FILE=~/.config/openclaw/.env.staging
openclaw up

4. Docker Multi-Environment Deployment

4.1 Managing Multiple Environments with 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:

# Start development environment
docker compose --profile dev up -d

# Start staging environment
docker compose --profile staging up -d

# Start production environment
docker compose --profile prod up -d

4.2 Running Multiple Environments on the Same Server

If you need to run multiple environments on the same server:

# Use different configuration directories and ports
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. Release Workflow

5.1 Recommended Change Release Process

1. Local development (dev)
   ↓ Feature development and debugging complete
2. Deploy to staging
   ↓ Validation passed, team review
3. Deploy to production
   ↓ Monitor and observe
4. Confirm stable

5.2 Configuration Change Checklist

Before promoting configuration from staging to production, check each item:

# 1. Compare configuration differences between environments (excluding sensitive info)
diff <(openclaw config show --env staging | grep -v "apiKey\|token\|password") \
     <(openclaw config show --env production | grep -v "apiKey\|token\|password")

# 2. Validate configuration in staging
OPENCLAW_ENV=staging openclaw config validate

# 3. Run diagnostics in staging
OPENCLAW_ENV=staging openclaw doctor

# 4. Confirm no leftover test data

5.3 Rollback Plan

If the new configuration causes issues in production:

# Option 1: Restore backed-up configuration file
cp ~/.config/openclaw/openclaw.production.json5.bak ~/.config/openclaw/openclaw.production.json5
openclaw restart

# Option 2: Git rollback
cd ~/.config/openclaw
git checkout HEAD~1 -- openclaw.production.json5
openclaw restart

# Option 3: Use openclaw built-in rollback
openclaw config rollback  # Roll back to the previous config version

6. Security Considerations

Never share API Keys: Use independent API Keys for each environment, making it easy to track usage and revoke individually in case of a leak
Manage production Bot Tokens separately: Prevent test messages from being sent to real users
Keep sensitive information out of Git: Use .gitignore to exclude .env files and configurations containing keys
Principle of least privilege: Developers should only have access to development/staging environments
Rotate keys regularly: Especially when there are personnel changes

# .gitignore example
.env*
*.production.json5
credentials/
ssl/

Through proper multi-environment management, you can confidently test new configurations, features, and skills without affecting real users. This is a fundamental practice for ensuring the stability of your OpenClaw production environment.