OpenClaw 모델 페일오버 문제 해결: 5분 만에 인증 오류 수정

개발을 하다 보면 API가 갑자기 응답하지 않거나 속도 제한에 걸려 당황스러운 적이 많으시죠? 에이전트가 작업을 멈추지 않고 계속 돌아가게 하려면 Failover 설정을 제대로 이해하는 것이 정말 중요해요. OpenClaw에서 모델 Failover가 어떻게 작동하는지, 그리고 흔히 발생하는 인증 관련 에러를 어떻게 해결하는지 함께 알아볼게요.

Model Failover

Model Failover의 작동 원리와 문제 해결 방법을 알아봅니다.

---

Failover는 어떻게 작동하나요?

Failover는 다음 두 단계로 진행돼요.

1. 같은 provider 내에서 Auth profile rotation
2. agents.defaults.model.fallbacks에 지정된 다음 모델로 Model fallback

실패한 프로필에는 Cooldown(지수 백오프)이 적용돼요. 덕분에 특정 provider가 속도 제한(rate-limit)에 걸리거나 일시적인 장애가 발생해도 OpenClaw는 계속해서 응답을 보낼 수 있어요.

---

”No credentials found for profile ‘anthropic:default‘“는 무슨 뜻인가요?

이 메시지는 시스템이 anthropic:default라는 ID를 가진 인증 프로필을 사용하려고 시도했지만, 예상된 auth store에서 해당 자격 증명(credentials)을 찾지 못했다는 뜻이에요.

---

”No credentials found for profile anthropic:default” 해결을 위한 체크리스트

1. 인증 프로필 위치 확인:

   • 현재 경로: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
   • 레거시 경로: ~/.openclaw/agent/* (openclaw doctor 명령어로 마이그레이션 가능)

2. Gateway가 환경 변수를 로드했는지 확인:

   • 쉘(shell)에서 ANTHROPIC_API_KEY를 설정했더라도 Gateway를 systemd나 launchd로 실행하면 이 설정을 상속받지 못할 수 있어요.
   • ~/.openclaw/.env 파일에 직접 넣거나 env.shellEnv 설정을 활성화하세요.

3. 올바른 agent를 수정하고 있는지 확인:

   • 멀티 에이전트 설정에서는 여러 개의 auth-profiles.json 파일이 존재할 수 있어요.

4. 모델 및 인증 상태 점검:

   openclaw models status

---

“No credentials found for profile anthropic” 해결을 위한 체크리스트

이 에러는 실행 프로세스가 특정 Anthropic 인증 프로필에 고정(pinned)되어 있지만, Gateway가 이를 찾을 수 없음을 의미해요.

setup-token 사용하기:

claude setup-token
openclaw models auth setup-token --provider anthropic

대신 API key를 사용하고 싶다면:

• Gateway 호스트의 ~/.openclaw/.env 파일에 ANTHROPIC_API_KEY를 넣으세요.
• 고정된 순서 설정을 초기화하세요:

  openclaw models auth order clear --provider anthropic

Gateway 호스트에서 명령어를 실행 중인지 확인:

• 원격 모드(remote mode)에서 인증 프로필은 내 노트북이 아니라 Gateway 머신에 저장돼요.

---

왜 Google Gemini까지 시도하고 실패했나요?

모델 설정에 Google Gemini가 fallback으로 포함되어 있거나 Gemini 단축어(shorthand)를 사용했다면, OpenClaw는 모델 fallback 과정에서 Gemini 접속을 시도해요. 이때 Google 인증 설정을 하지 않았다면 No API key found for provider "google" 메시지가 나타나요.

해결 방법: Google 인증 정보를 제공하거나, agents.defaults.model.fallbacks 설정에서 Google 모델을 제거하거나 제외하세요.

AI Setup Assistant

다음 단계

• 인증 프로필 설정 가이드
• Gateway 구성 방법