🔧 자주 묻는 질문 해결
API Key를 설정했지만 오류가 표시되나요? 걱정하지 마세요, 흔한 문제들은 모두 여기에 있습니다.
흔한 오류 및 해결 방법
❌ 401 Unauthorized / Invalid API Key
원인:API Key가 유효하지 않거나 만료되었습니다.
- 암호키가 완전히 복사되었는지 확인하세요 (여분의 공백이나 누락된 문자가 없는지)
- 암호키가 비활성화되거나 삭제되지 않았는지 확인하세요
- baseUrl과 API Key가 일치하는지 확인하세요 (OpenAI의 Key를 Anthropic의 주소에 입력하지 마세요)
- Coding Plan의 Key는 Coding Plan의 baseUrl을 사용해야 하며, 혼동하지 마세요
❌ 429 Too Many Requests / Rate Limited
원인:요청이 너무 자주 와서 속도 제한을 초과했습니다.
- 잠시 기다렸다가 다시 시도하세요
- 자주 속도 제한이 발생하면 Coding Plan으로 업그레이드를 고려하세요 (속도가 더 높음)
- 또는 여러 provider를 설정하여 요청을 분산하세요
❌ 402 Payment Required / Insufficient Balance
원인:잔액이 부족합니다.
- 해당 플랫폼으로 가서 충전하세요
- 미지급 청구서가 있는지 확인하세요
- 무료 한도가 이미 사용되었는지 확인하세요
❌ Connection Timeout / Network Error
원인:네트워크 연결 문제입니다.
- 국제 서비스 제공자 (OpenAI, Anthropic, Gemini)는 중국 국내에서 번역기가 필요할 수 있습니다
- 중국 국내 서비스 제공자 (DeepSeek, MiniMax 등)는 직접 연결이 문제 없어야 합니다
- baseUrl이 정확한지 확인하고 철자 오류가 없는지 확인하세요
- 시도해 보세요
curl명령어로 연통성 테스트를 시도하세요
❌ 400 Bad Request / Invalid Model
원인:모델 이름을 잘못 입력했거나 계정에 해당 모델에 대한 접근 권한이 없습니다.
- models 설정의 모델 이름이 정확한지 확인하세요
- 계정/방안이 해당 모델을 지원하는지 확인하세요
- 각 서비스 제공자 페이지의 사용 가능한 모델 목록을 참고하세요
디버깅 팁
1. 현재 설정 확인:
cat ~/.openclaw/openclaw.json2. API 연통성 테스트:
# 测试 DeepSeek
curl -s https://api.deepseek.com/v1/models -H "Authorization: Bearer sk-당신의암호키"
# OpenAI 테스트
curl -s https://api.openai.com/v1/models -H "Authorization: Bearer sk-당신의암호키"3. OpenClaw 로그 확인:
openclaw logs4. 게이트웨이 다시 시작:
openclaw gateway restart
여전히 못 고쳤나요?대부분의 문제는 baseUrl 오류 또는 API Key 복사 불완전으로 인한 것입니다. 각 서비스 제공자 페이지의 설정 예제와 자세히 비교하세요.