문제 설명
OpenClaw 시작 시 또는 대화 중에 API 인증 관련 오류가 발생합니다:
[openclaw:gateway] Error: 401 Unauthorized - Invalid API key provided.
[openclaw:gateway] Provider: openai, Model: gpt-4o
또는 Anthropic 인증 오류:
[openclaw:gateway] Error: 401 - {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
Google Gemini 인증 실패:
[openclaw:gateway] Error: 403 - API key not valid. Please pass a valid API key.
인증 오류는 OpenClaw이 AI 모델 제공업체의 신원 확인을 통과하지 못해 요청이 거부되었음을 의미합니다. 이는 보통 API Key 설정 오류, 만료 또는 해지가 원인입니다.
진단 단계
1단계: 설정 파일의 Key 확인
현재 설정의 API Key를 확인합니다 (키는 일부만 표시됩니다):
openclaw config show --unmask-partial
출력 예시:
providers.openai.apiKey: sk-proj-...Xk3a
providers.anthropic.apiKey: sk-ant-...9f2b
표시되는 Key의 접두사와 접미사가 제공업체 콘솔에서 확인한 것과 일치하는지 확인합니다.
2단계: API Key 직접 검증
curl을 사용하여 각 제공업체의 API Key 유효성을 직접 테스트합니다:
OpenAI:
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer sk-your-key-here"
Anthropic:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: sk-ant-your-key-here" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'
Google Gemini:
curl "https://generativelanguage.googleapis.com/v1/models?key=YOUR_API_KEY"
401 또는 403 오류가 반환되면 Key 자체가 유효하지 않은 것입니다.
3단계: 환경 변수 오버라이드 확인
OpenClaw은 환경 변수를 통한 API Key 설정을 지원하며, 환경 변수가 설정 파일보다 우선순위가 높습니다:
env | grep -i "OPENCLAW\|OPENAI\|ANTHROPIC\|GEMINI"
환경 변수에 잘못된 Key가 설정되어 있으면 설정 파일의 올바른 Key를 덮어쓰게 됩니다.
해결 방안
문제 1: API Key 오류 또는 형식 불일치
제공업체별 API Key 형식이 다릅니다:
- OpenAI:
sk-proj-또는sk-로 시작 - Anthropic:
sk-ant-api03-으로 시작 - Google Gemini: 보통 39자리 영숫자 문자열
설정 파일에 불필요한 공백, 줄바꿈 또는 따옴표 문제가 있는지 확인합니다:
cat -A ~/.openclaw/openclaw.json | grep apiKey
API Key 업데이트 권장 방법:
openclaw config set providers.openai.apiKey "sk-proj-your-new-key"
openclaw config set providers.anthropic.apiKey "sk-ant-api03-your-new-key"
문제 2: API Key 만료 또는 해지
API Key가 무효화되는 원인:
- 제공업체 콘솔에서 이전 Key를 수동으로 해지
- Key가 설정된 만료 시간에 도달
- 제공업체가 보안상의 이유로 Key를 강제 순환
- 계정 미납으로 Key 일시 중지
해당 제공업체의 콘솔에서 새로운 API Key를 생성합니다:
- OpenAI: platform.openai.com/api-keys
- Anthropic: console.anthropic.com/settings/keys
- Google AI Studio: aistudio.google.com/apikey
문제 3: 다중 제공업체 Key 순환 설정
{
"providers": {
"openai": {
"apiKeys": [
"sk-proj-primary-key",
"sk-proj-backup-key"
],
"keyValidation": {
"enabled": true,
"intervalMinutes": 60,
"removeInvalid": true
}
}
}
}
문제 4: 환경 변수로 Key 안전하게 관리
export OPENCLAW_OPENAI_API_KEY="sk-proj-your-key"
export OPENCLAW_ANTHROPIC_API_KEY="sk-ant-api03-your-key"
설정 파일에서 환경 변수를 참조합니다:
{
"providers": {
"openai": {
"apiKey": "${OPENCLAW_OPENAI_API_KEY}"
},
"anthropic": {
"apiKey": "${OPENCLAW_ANTHROPIC_API_KEY}"
}
}
}
systemd 사용 시:
[Service]
EnvironmentFile=/etc/openclaw/env
ExecStart=/usr/local/bin/openclaw start
수정 확인
Key를 업데이트한 후 OpenClaw을 재시작하고 확인합니다:
openclaw restart
openclaw doctor
openclaw doctor는 설정된 모든 제공업체에 대해 API 연결 테스트를 수행하고 각 제공업체의 인증 상태를 표시합니다. 모든 제공업체가 녹색 상태로 표시되면 인증 문제가 해결된 것입니다.
수동 테스트 요청을 트리거할 수도 있습니다:
openclaw test-message --channel telegram --text "테스트 메시지"
로그를 확인하여 메시지가 성공적으로 처리되었는지 확인합니다.