환경 변수

OpenClaw은 여러 소스에서 환경 변수를 가져옵니다. 기본 규칙은 기존 값을 절대 덮어쓰지 않는 것입니다.

우선순위 (높은 순)

1. 프로세스 환경 (게이트웨이 프로세스가 부모 셸/데몬에서 이미 가지고 있는 것).
2. 현재 작업 디렉토리의 .env (dotenv 기본값; 덮어쓰지 않음).
3. 글로벌 .env (~/.openclaw/.env, 즉 $OPENCLAW_STATE_DIR/.env; 덮어쓰지 않음).
4. 설정의 env 블록 (~/.openclaw/openclaw.json 내; 누락된 경우에만 적용).
5. 선택적 로그인 셸 가져오기 (env.shellEnv.enabled 또는 OPENCLAW_LOAD_SHELL_ENV=1), 누락된 예상 키에만 적용.

설정 파일이 완전히 없으면 4단계는 건너뛰어집니다. 셸 가져오기는 활성화되어 있으면 계속 실행됩니다.

설정의 env 블록

인라인 환경 변수를 설정하는 두 가지 동등한 방법(둘 다 덮어쓰지 않음):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

셸 환경 가져오기

env.shellEnv는 로그인 셸을 실행하고 누락된 예상 키만 가져옵니다:

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

동등한 환경 변수:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

런타임에 주입되는 환경 변수

OpenClaw은 생성된 자식 프로세스에 컨텍스트 마커도 주입합니다:

• OPENCLAW_SHELL=exec: exec 도구를 통해 실행되는 명령에 설정.
• OPENCLAW_SHELL=acp: ACP 런타임 백엔드 프로세스 생성 시 설정(예: acpx).
• OPENCLAW_SHELL=acp-client: openclaw acp client가 ACP 브리지 프로세스를 생성할 때 설정.
• OPENCLAW_SHELL=tui-local: 로컬 TUI ! 셸 명령에 설정.

이들은 런타임 마커입니다(필수 사용자 설정이 아님). 셸/프로필 로직에서 컨텍스트별 규칙을 적용하는 데 사용할 수 있습니다.

UI 환경 변수

• OPENCLAW_THEME=light: 터미널 배경이 밝을 때 밝은 TUI 팔레트를 강제 적용.
• OPENCLAW_THEME=dark: 어두운 TUI 팔레트를 강제 적용.
• COLORFGBG: 터미널이 이 변수를 내보내면 OpenClaw이 배경색 힌트를 사용하여 TUI 팔레트를 자동 선택합니다.

설정에서 환경 변수 대체

설정 문자열 값에서 ${VAR_NAME} 구문을 사용하여 환경 변수를 직접 참조할 수 있습니다:

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

자세한 내용은 설정: 환경 변수 대체를 참조하세요.

Secret ref와 ${ENV} 문자열

OpenClaw은 두 가지 환경 변수 기반 패턴을 지원합니다:

• ${VAR} 문자열 대체 (설정 값 내).
• SecretRef 객체 ({ source: "env", provider: "default", id: "VAR" }), 시크릿 참조를 지원하는 필드용.

둘 다 활성화 시점에 프로세스 환경에서 해석됩니다. SecretRef 세부 사항은 시크릿 관리에 문서화되어 있습니다.

경로 관련 환경 변수

로깅

OPENCLAW_HOME

설정 시, OPENCLAW_HOME은 모든 내부 경로 해석에서 시스템 홈 디렉토리($HOME / os.homedir())를 대체합니다. 헤드리스 서비스 계정의 완전한 파일시스템 격리를 가능하게 합니다.

우선순위: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

예시 (macOS LaunchDaemon):

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

OPENCLAW_HOME은 틸다 경로(예: ~/svc)로도 설정할 수 있으며, 사용 전에 $HOME을 기준으로 확장됩니다.

관련 문서

• 게이트웨이 설정
• FAQ: 환경 변수와 .env 로딩
• 모델 개요