OpenClaw 환경 변수 설정 총정리

서문

환경 변수는 OpenClaw를 설정하는 중요한 방법 중 하나로, 특히 컨테이너화 배포와 CI/CD 시나리오에 적합합니다. 이 글에서는 OpenClaw에서 지원하는 모든 환경 변수를 전면적으로 나열하고 실제 사용 예시를 제공합니다.

핵심 환경 변수

다음은 OpenClaw 실행에 필수적이거나 자주 사용되는 핵심 환경 변수입니다:

설정 예시

# 리스닝 포트와 로그 레벨 변경
export OPENCLAW_PORT=8080
export OPENCLAW_LOG_LEVEL=debug
openclaw up

~/.bashrc에서 영구 적용:

# OpenClaw 환경 변수
export OPENCLAW_PORT=18789
export OPENCLAW_LOG_LEVEL=info
export OPENCLAW_HOST=0.0.0.0

API 키 환경 변수

각 AI 모델의 API 키는 환경 변수를 통해 설정하여 민감한 정보가 설정 파일에 기록되는 것을 방지할 수 있습니다:

다중 키 설정

일부 모델은 여러 API 키 설정을 지원하며, OpenClaw가 자동으로 교대하여 사용합니다:

# 쉼표로 여러 키를 구분
export OPENAI_API_KEY="sk-proj-key1,sk-proj-key2,sk-proj-key3"

API 기본 주소 재정의

서드파티 프록시 또는 자체 배포된 API 엔드포인트를 사용하는 경우:

# 서드파티 OpenAI 프록시 사용
export OPENAI_API_KEY="sk-custom-key"
export OPENAI_BASE_URL="https://api.your-proxy.com/v1"
openclaw up

채널 관련 환경 변수

WhatsApp

Telegram

Discord

Slack

LINE

Microsoft Teams

프록시 관련 환경 변수

보안 관련 환경 변수

# 보안 관련 변수 설정
export OPENCLAW_DASHBOARD_PASSWORD="your-strong-password"
export OPENCLAW_CORS_ORIGIN="https://your-domain.com"
export OPENCLAW_RATE_LIMIT=30

.env 파일 지원

OpenClaw는 .env 파일에서 환경 변수를 자동으로 읽어들이는 기능을 지원하여 매번 수동으로 내보내는 수고를 덜 수 있습니다.

.env 파일 생성

OpenClaw의 설정 디렉토리에 .env 파일을 생성합니다:

# ~/.config/openclaw/.env

# 핵심 설정
OPENCLAW_PORT=18789
OPENCLAW_LOG_LEVEL=info
NODE_ENV=production

# API 키
OPENAI_API_KEY=sk-proj-your-key-here
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
GOOGLE_API_KEY=AIzaSy-your-key-here

# 채널 키
TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIjKlMnOpQrStUvWxYz
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5.your-discord-token

# 프록시
HTTPS_PROXY=http://127.0.0.1:7890

# 보안
OPENCLAW_DASHBOARD_PASSWORD=my-secure-password

.env 파일 우선순위

환경 변수의 우선순위 (높은 것부터 낮은 순):

1. 시스템 환경 변수 - export로 설정한 변수
2. .env 파일 - 설정 디렉토리의 .env 파일
3. 설정 파일 - openclaw.json5의 설정
4. 기본값 - OpenClaw의 내장 기본값

주의사항

# .env 파일의 값에는 export 키워드가 필요하지 않습니다
# 올바른 작성법
OPENCLAW_PORT=8080

# 잘못된 작성법
export OPENCLAW_PORT=8080

# 값에 공백이 포함된 경우 따옴표가 필요합니다
OPENCLAW_DASHBOARD_PASSWORD="my password with spaces"

# 주석을 지원합니다
# 이것은 주석입니다

# 변수 참조는 지원하지 않습니다
# 다음 작성법은 동작하지 않습니다
# OPENCLAW_DATA_DIR=$HOME/.openclaw

Docker 환경 변수

Docker에서 OpenClaw를 배포할 때 환경 변수를 통한 설정이 권장됩니다.

docker run 방식

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -e OPENAI_API_KEY="sk-proj-xxxx" \
  -e ANTHROPIC_API_KEY="sk-ant-xxxx" \
  -e TELEGRAM_BOT_TOKEN="your-token" \
  -e OPENCLAW_LOG_LEVEL="info" \
  -e OPENCLAW_DASHBOARD_PASSWORD="secure-pwd" \
  openclaw/openclaw:latest

docker-compose 방식

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"
    environment:
      - OPENCLAW_PORT=18789
      - OPENCLAW_LOG_LEVEL=info
      - NODE_ENV=production
      - OPENAI_API_KEY=sk-proj-xxxx
      - ANTHROPIC_API_KEY=sk-ant-xxxx
      - TELEGRAM_BOT_TOKEN=your-token
    volumes:
      - openclaw-data:/data

volumes:
  openclaw-data:

env_file 사용

더 안전한 방법은 키를 별도의 env 파일에 보관하는 것입니다:

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"
    env_file:
      - .env.openclaw
    volumes:
      - openclaw-data:/data

# .env.openclaw
OPENAI_API_KEY=sk-proj-xxxx
ANTHROPIC_API_KEY=sk-ant-xxxx
TELEGRAM_BOT_TOKEN=your-token
OPENCLAW_DASHBOARD_PASSWORD=secure-pwd

.env.openclaw을 .gitignore 및 .dockerignore에 추가하는 것을 잊지 마십시오.

현재 환경 변수 확인

openclaw config get 명령으로 현재 적용 중인 설정을 확인할 수 있습니다 (환경 변수에서 가져온 설정 포함):

# 모든 설정 확인
openclaw config get

# 특정 설정 항목 확인
openclaw config get port
openclaw config get log.level

# 모든 API 키 확인 (마스킹 처리)
openclaw config get models

요약

환경 변수는 OpenClaw를 설정하는 유연한 방법입니다. 몇 가지 사용 권장사항:

• 민감한 정보(API 키, 비밀번호)는 환경 변수 또는 .env 파일을 우선 사용하고, 설정 파일에는 기록하지 마십시오
• Docker 배포에서는 env_file로 변수를 집중 관리하고, 파일이 버전 관리에 커밋되지 않도록 합니다
• 개발 환경에서는 .env 파일을 사용하여 편리하게 관리하고, 운영 환경에서는 시스템 레벨 환경 변수 또는 키 관리 서비스를 사용합니다
• 우선순위 규칙을 기억합니다: 시스템 환경 변수 > .env 파일 > 설정 파일 > 기본값