환경 변수

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

우선순위 (높음 → 낮음)

프로세스 환경 (Gateway(게이트웨이) 프로세스가 상위 셸 또는 데몬에서 이미 가지고 있는 값).
현재 작업 디렉토리의 .env (dotenv 기본값; 덮어쓰지 않음).
~/.openclaw/.env 에 있는 전역 .env (일명 $OPENCLAW_STATE_DIR/.env; 덮어쓰지 않음).
~/.openclaw/openclaw.json 의 Config env 블록 (누락된 경우에만 적용).
선택적 로그인 셸 가져오기 (env.shellEnv.enabled 또는 OPENCLAW_LOAD_SHELL_ENV=1), 예상되는 키 중 누락된 항목에만 적용.

구성 파일이 완전히 없는 경우 4단계는 건너뜁니다. 셸 가져오기는 활성화되어 있으면 여전히 실행됩니다.

Config `env` 블록

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

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

Shell env import

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

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

Env var equivalents:

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

config에서 환경 변수 치환

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

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

자세한 내용은 Configuration: Env var substitution 을 참고하십시오.

변수	목적
`OPENCLAW_HOME`	모든 내부 경로 해석(`~/.openclaw/`, agent 디렉터리, 세션, 자격 증명)에 사용되는 홈 디렉터리를 재정의합니다. Useful when running OpenClaw as a dedicated service user.
`OPENCLAW_STATE_DIR`	상태 디렉터리(기본값: `~/.openclaw`)를 재정의합니다.
`OPENCLAW_CONFIG_PATH`	설정 파일 경로를 재정의합니다(기본값 `~/.openclaw/openclaw.json`).

`OPENCLAW_HOME`

설정되면 OPENCLAW_HOME은 모든 내부 경로 해석에서 시스템 홈 디렉터리($HOME / os.homedir())를 대체합니다. 이를 통해 헤드리스 서비스 계정에 대해 완전한 파일시스템 격리를 활성화할 수 있습니다. 우선순위: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir() 예시 (macOS LaunchDaemon):

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

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

도움말

커뮤니티

환경 및 디버깅

Node 런타임

컴팩션 내부 구조

개발자 설정

문서 메타

환경 변수

환경 변수

우선순위 (높음 → 낮음)

Config `env` 블록

Shell env import

config에서 환경 변수 치환

`OPENCLAW_HOME`

관련 항목

​환경 변수

​우선순위 (높음 → 낮음)

​Config env 블록

​Shell env import

​config에서 환경 변수 치환

​Path-related env vars

​OPENCLAW_HOME

​관련 항목

환경 변수

우선순위 (높음 → 낮음)

Config `env` 블록

Shell env import

config에서 환경 변수 치환

Path-related env vars

`OPENCLAW_HOME`

관련 항목