OpenClaw 환경 변수 설정 가이드

프로젝트를 진행하다 보면 API 키나 설정값을 관리하는 게 참 번거로운 일이에요. 어디에 변수를 설정했는지 잊어버리거나, 의도치 않게 값이 덮어씌워져서 동작이 꼬이는 경험을 해본 적이 있으실 겁니다.

OpenClaw는 이런 혼란을 줄이기 위해 명확한 규칙을 가지고 환경 변수를 가져와요. 가장 중요한 원칙은 기존에 이미 존재하는 값은 절대 덮어쓰지 않는다는 점이에요.

필요한 것

OpenClaw는 여러 소스에서 환경 변수를 읽어옵니다. 우선순위가 높은 순서대로 정리해 드릴게요.

1. 환경 변수 우선순위 (높음 → 낮음)

2. openclaw.json에 환경 변수 설정하기 설정 파일 안에서 환경 변수를 직접 지정하고 싶다면 아래와 같이 작성하세요. 두 방식 모두 동일하게 작동하며 기존 값을 보호합니다.

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

3. 설정 파일에서 환경 변수 참조하기 설정 파일의 문자열 값 안에서 ${VAR_NAME} 문법을 사용해 환경 변수를 바로 불러올 수 있어요.

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

특정 경로를 변경해야 할 때 사용할 수 있는 변수들입니다.

변수명	용도
`OPENCLAW_HOME`	내부 경로 해석(`~/.openclaw/`, 에이전트 디렉토리 등)에 사용되는 홈 디렉토리를 변경해요. 서비스 계정으로 실행할 때 유용합니다.
`OPENCLAW_STATE_DIR`	상태 디렉토리(기본값 `~/.openclaw`)를 변경해요.
`OPENCLAW_CONFIG_PATH`	설정 파일 경로(기본값 `~/.openclaw/openclaw.json`)를 직접 지정해요.

OPENCLAW_HOME을 설정하면 시스템의 기본 홈 디렉토리보다 우선시됩니다. macOS의 LaunchDaemon 등에서 다음과 같이 설정할 수 있어요.

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

쉘 환경 변수가 불러와지지 않나요? 로그인 쉘에서 변수를 가져오려면 env.shellEnv 설정을 확인하세요. 타임아웃이 발생한다면 시간을 늘려볼 수 있습니다.

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

또는 환경 변수로 OPENCLAW_LOAD_SHELL_ENV=1을 직접 주어도 됩니다.

설정 파일의 env 블록이 무시되나요? OpenClaw는 기존 값을 덮어쓰지 않습니다. 만약 시스템 환경 변수나 .env 파일에 이미 같은 이름의 변수가 있다면, 설정 파일에 적은 값은 적용되지 않아요.

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!

OpenClaw Expert

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.