OpenClaw 환경 변수 설정 가이드: 5분 만에 구성하기

환경 변수 (Environment Variables)

개발을 하다 보면 환경 변수 설정 때문에 골치 아픈 적이 한두 번이 아니죠? 로컬 터미널에서는 잘 돌아가던 설정이 서비스나 CI 환경으로 옮기면 갑자기 API 키를 못 찾겠다고 아우성치곤 합니다. OpenClaw가 환경 변수를 어떻게 관리하고 로드하는지 정확히 알면 이런 문제를 깔끔하게 해결할 수 있어요.

OpenClaw에서 환경 변수를 다루는 방법과 흔히 발생하는 문제들의 해결책을 정리해 보았습니다.

---

OpenClaw는 환경 변수를 어떻게 로드하나요?

OpenClaw는 기본적으로 부모 프로세스(shell, launchd/systemd, CI 등)에서 환경 변수를 읽어오며, 추가로 다음 위치에서 변수를 로드합니다.

• 현재 작업 디렉토리의 .env 파일
• ~/.openclaw/.env (또는 $OPENCLAW_STATE_DIR/.env)에 있는 글로벌 폴백 .env 파일

두 .env 파일 모두 기존에 이미 존재하는 환경 변수를 덮어쓰지는 않습니다.

또한, 설정(config) 파일 내에 직접 환경 변수를 정의할 수도 있습니다 (프로세스 환경 변수에 해당 값이 없을 때만 적용됩니다).

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

---

”서비스로 Gateway를 실행했더니 환경 변수가 사라졌어요.” 어떻게 하죠?

이 문제를 해결하는 두 가지 일반적인 방법이 있습니다.

1. 글로벌 설정 사용: 누락된 키를 ~/.openclaw/.env에 넣으세요. 이렇게 하면 서비스가 사용자의 쉘 환경을 상속받지 못하는 상황에서도 변수를 정상적으로 불러올 수 있습니다.

2. 쉘 임포트(Shell import) 활성화: 다음과 같이 설정을 추가하여 편리하게 환경 변수를 가져올 수 있습니다.

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

이 기능은 로그인 쉘을 실행하여 누락된 예상 키들만 임포트합니다 (기존 변수를 절대 덮어쓰지 않습니다). 환경 변수로도 동일하게 설정할 수 있습니다: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.

---

COPILOT_GITHUB_TOKEN을 설정했는데, 모델 상태에 “Shell env: off”라고 떠요. 왜 그런가요?

openclaw models status에서 보고하는 내용은 쉘 환경 임포트(shell env import) 기능이 활성화되어 있는지 여부입니다. “Shell env: off”라고 표시된다고 해서 환경 변수가 누락되었다는 뜻은 아닙니다. 단지 OpenClaw가 로그인 쉘을 자동으로 로드하지 않는다는 의미일 뿐입니다.

만약 Gateway가 서비스(launchd/systemd)로 실행 중이라면, 사용자의 쉘 환경을 상속받지 못할 수 있습니다.

이럴 때는 다음 중 하나를 시도해 보세요:

1. 토큰을 ~/.openclaw/.env 파일에 추가하기
2. 쉘 임포트 활성화하기 (env.shellEnv.enabled: true)
3. 설정 파일의 env 블록에 토큰 추가하기

설정을 마친 후에는 Gateway를 재시작해야 합니다.

openclaw gateway restart
openclaw models status

Copilot 토큰은 COPILOT_GITHUB_TOKEN에서 읽어오며, GH_TOKEN이나 GITHUB_TOKEN도 함께 확인합니다.

AI Setup Assistant

다음 단계

• Gateway 설정 가이드
• 지원하는 모델 목록