홈 튜토리얼 카테고리 Skills 소개
ZH EN JA KO
운영 모니터링

OpenClaw 다중 환경 관리: 개발, 테스트, 프로덕션

· 16 분 소요

서문

실제 운영에서 프로덕션 환경에서 직접 설정을 변경하거나 새 기능을 테스트하는 것은 매우 위험한 작업입니다. 하나의 설정 오류로 모든 사용자의 대화가 중단될 수 있습니다. 이 글에서는 OpenClaw에 개발, 테스트, 프로덕션 세 가지 격리 환경을 구축하여, 안전하게 디버깅과 검증을 수행하는 방법을 상세히 설명합니다.

1. 환경 격리 전략

1.1 세 가지 환경의 역할

환경 용도 데이터 안정성 요구
개발 (dev) 로컬 개발 디버깅, 새 기능 실험 테스트 데이터 낮음
테스트 (staging) 배포 전 검증, 회귀 테스트 실제와 유사한 데이터 중간
프로덕션 (production) 실제 사용자 서비스 실제 데이터 매우 높음

1.2 격리 차원

각 환경에서 다음 항목을 격리해야 합니다:

  • 설정 파일: 서로 다른 API Key, 모델 매개변수
  • 채널 계정: 서로 다른 Bot Token(테스트 메시지가 실제 사용자에게 전송되는 것을 방지)
  • 데이터 저장: 독립적인 세션 데이터와 로그
  • 네트워크 포트: 서로 다른 Gateway 포트로 충돌 방지

2. 설정 파일을 통한 격리

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  // 프로덕션 환경에서 워치독 활성화
  }
}

3. .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

4. 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. 배포 프로세스

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 롤백 방안

새 설정이 프로덕션 환경에서 문제가 발생한 경우:

# 방안 1: 백업된 설정 파일 복원
cp ~/.config/openclaw/openclaw.production.json5.bak ~/.config/openclaw/openclaw.production.json5
openclaw restart

# 방안 2: Git을 사용한 롤백
cd ~/.config/openclaw
git checkout HEAD~1 -- openclaw.production.json5
openclaw restart

# 방안 3: openclaw 내장 롤백 사용
openclaw config rollback  # 이전 설정 버전으로 롤백

6. 보안 주의사항

  1. API Key를 절대 공유하지 마세요: 각 환경에서 독립적인 API Key를 사용하여, 사용량 추적과 유출 시 개별 취소가 용이하도록 합니다
  2. 프로덕션 환경의 Bot Token은 별도 관리: 테스트 메시지가 실제 사용자에게 전송되는 것을 방지합니다
  3. 민감 정보는 Git에 커밋하지 마세요: .gitignore를 사용하여 .env 파일과 키가 포함된 설정을 제외합니다
  4. 최소 권한 원칙: 개발자는 개발/테스트 환경에 대한 접근 권한만 가집니다
  5. 정기적으로 키를 교체하세요: 특히 인원 변동이 있을 때
# .gitignore 예시
.env*
*.production.json5
credentials/
ssl/

합리적인 다중 환경 관리를 통해, 실제 사용자에게 영향을 주지 않으면서 안심하고 새로운 설정, 새 기능, 새 스킬을 테스트할 수 있습니다. 이는 OpenClaw 프로덕션 환경의 안정성을 보장하는 중요한 기초 실천입니다.

OpenClaw는 무료 오픈소스 개인 AI 어시스턴트로, WhatsApp, Telegram, Discord 등 다양한 플랫폼을 지원합니다
더 많은 튜토리얼 Skills 다운로드

관련 튜토리얼

OpenClaw 무중단 업데이트 및 롤링 업그레이드
OpenClaw SSL 인증서 및 HTTPS 암호화 설정
OpenClaw 리소스 모니터링 및 알림 설정