환경 변수 참조

기준일: 2026-06-06
공식 기준: Environment variables, Gateway configuration

OpenClaw에서 사용할 수 있는 모든 환경 변수를 빠르게 찾아보세요.

개요

환경 변수 사용법

# 셸 설정 파일 (~/.bashrc, ~/.zshrc, etc.)
export OPENCLAW_VAR_NAME="value"

# 또는 명령행에서 직접
OPENCLAW_VAR_NAME="value" openclaw gateway

우선 순위

1. Gateway 프로세스 환경 변수 (가장 높음)
2. 현재 작업 디렉터리 .env (기존 값을 덮어쓰지 않으며 provider credential과 보호된 OPENCLAW_* 런타임 제어는 무시)
3. 전역 .env (~/.openclaw/.env 또는 $OPENCLAW_STATE_DIR/.env)
4. 설정 파일의 env block (~/.openclaw/openclaw.json)
5. 선택적 login-shell import (OPENCLAW_LOAD_SHELL_ENV=1)
6. 기본값

Provider API key를 프로젝트 .env에만 두지 마세요. Gateway가 신뢰하는 프로세스 환경, 전역 .env, config env block, SecretRef 중 하나를 사용합니다.

주요 환경 변수

연결 설정

OPENCLAW_GATEWAY_PORT

OpenClaw Gateway 포트. 공식 우선순위는 --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789입니다.

export OPENCLAW_GATEWAY_PORT="18790"

OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD

Gateway shared-secret 인증에 사용하는 값입니다. non-loopback bind를 열 때는 token/password 또는 trusted proxy 경로를 명확히 둡니다.

export OPENCLAW_GATEWAY_TOKEN="replace-with-a-long-random-token"
export OPENCLAW_GATEWAY_PASSWORD="replace-with-a-strong-password"

경로와 상태

OPENCLAW_HOME

OpenClaw 내부 경로 기본값을 계산할 때 사용할 home directory를 바꿉니다.

export OPENCLAW_HOME="/Users/openclaw"

OPENCLAW_STATE_DIR

상태 디렉터리 기본값 ~/.openclaw를 바꿉니다.

export OPENCLAW_STATE_DIR="/var/lib/openclaw"

설정

OPENCLAW_CONFIG_PATH

설정 파일 경로를 바꿉니다.

export OPENCLAW_CONFIG_PATH="/etc/openclaw/config.json"

로깅

OPENCLAW_LOG_LEVEL

로그 레벨

export OPENCLAW_LOG_LEVEL="debug"

OPENCLAW_LOG_FILE

로그 파일 경로

export OPENCLAW_LOG_FILE="/var/log/openclaw/gateway.log"

네트워크

Gateway bind는 환경 변수보다 gateway.bind 설정으로 관리하는 편이 명확합니다. 현재 bind 값은 auto, loopback, lan, tailnet, custom 같은 모드를 사용하며, 0.0.0.0 같은 host alias를 직접 기본값으로 가정하지 않습니다.

OPENCLAW_TIMEOUT

요청 타임아웃 (초)

export OPENCLAW_TIMEOUT="60"

채널별 환경 변수

Telegram

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

Slack

export SLACK_BOT_TOKEN="xoxb-1234567890-1234567890123-AbCdEfGhIjKlMnOpQrStUvWx"
export SLACK_SIGNING_SECRET="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Discord

export DISCORD_BOT_TOKEN="MTIzNDU2Nzg5MDEyMzQ1NjgwMA.GhIjKl.MnOpQrStUvWxYzAbCdEfGhIjKlMnOpQrStUvWx"

WhatsApp

export WHATSAPP_API_KEY="your-api-key-here"
export WHATSAPP_PHONE_ID="123456789012345"

iMessage

export OPENCLAW_IMESSAGE_CLI_PATH="/opt/homebrew/bin/imsg"
export OPENCLAW_IMESSAGE_INCLUDE_ATTACHMENTS="false"

Signal

export SIGNAL_PHONE_NUMBER="+821012345678"

Matrix

export MATRIX_HOMESERVER_URL="https://matrix.org"
export MATRIX_ACCESS_TOKEN="syt_1234567890abcdef..."

AI 모델 설정

Anthropic Claude

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

OpenAI

export OPENAI_API_KEY="sk-proj-your-key-here"

Google AI

export GOOGLE_AI_API_KEY="AIzaSy-your-key-here"

보안

인증

export OPENCLAW_SECRET="random-secret-string-here"

SSL/TLS

export OPENCLAW_CERT_FILE="/etc/ssl/certs/openclaw.crt"
export OPENCLAW_KEY_FILE="/etc/ssl/private/openclaw.key"

개발

# Node.js 환경
export NODE_ENV="development"

# 디버그 로그 활성화
export DEBUG="openclaw:*"

사용 예시

기본 설정

# ~/.bashrc 또는 ~/.zshrc
export OPENCLAW_API_KEY="sk-your-api-key"
export OPENCLAW_LOG_LEVEL="debug"
export OPENCLAW_WORKSPACE="~/.openclaw/workspace"

채널 설정

# Telegram
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."

# Slack
export SLACK_BOT_TOKEN="xoxb-1234567890-1234567890123-..."
export SLACK_SIGNING_SECRET="a1b2c3d4e5f6..."

# Discord
export DISCORD_BOT_TOKEN="MTIzNDU2Nzg5MDEyMzQ1NjgwMA.GhIjKl..."

AI 모델 설정

export ANTHROPIC_API_KEY="sk-ant-your-key-here"
export OPENAI_API_KEY="sk-proj-your-key-here"
export GOOGLE_AI_API_KEY="AIzaSy-your-key-here"

주의사항

1. 보안: API 키를 절대 커밋하지 마세요. .env 파일을 .gitignore에 추가하세요.
2. 민감 정보: 로그에 토큰이 노출되지 않도록 주의하세요. 프로덕션에서는 OPENCLAW_LOG_LEVEL=warn 권장.
3. 유효성 검사: 환경 변수 설정 후 게이트웨이 재시작이 필요합니다. 잘못된 값은 기본값으로 대체됩니다.

참고:

• 공식 문서: Configuration