OPenClaw를 사용하다 보면 API 호출이 실패하거나 연결이 끊기는 문제를 자주 만날 수 있습니다. 이 글에서는 주요 오류 유형별로 원인을 진단하고 실제로 적용 가능한 해결책을 소개합니다. 더 이상 오류 코드만 바라보지 말고 빠르게 작업을 재개하세요.
API 401 인증 오류: 키와 권한 확인
401 오류는 일반적으로 요청에 유효한 인증 정보가 없을 때 발생합니다. 먼저 API 키가 환경 변수나 설정 파일에 올바르게 입력되었는지 확인하세요. 앞뒤에 불필요한 공백이나 줄바꿈이 없는지 주의해야 합니다. 콘솔에서 복사한 키를 그대로 붙여넣었다면 직접 다시 입력해 보세요. 복사 과정에서 문자가 누락되는 경우가 많기 때문입니다. 또한, 일부 모델이나 Endpoint는 별도의 권한 설정이 필요할 수 있으므로 개발자 콘솔에서 '액세스 허용' 항목이 활성화되어 있는지 확인하세요.
429 요청 제한 초과: 호출 간격과 할당량 조정
짧은 시간 내에 너무 많은 요청을 보내면 속도 제한에 걸려 429 코드가 반환됩니다. 이때 무작정 재시도하지 말고 5~10초 정도 대기한 후 지수 백오프(Exponential Backoff) 방식으로 다시 요청하세요. 요청 큐를 설정하거나 sleep 메커니즘을 추가하면 속도 제한을 피할 수 있습니다. 빈번하게 발생한다면 계정이 체험판 상태인지 확인하세요(체험판 한도는 더 낮습니다). 요금제를 업그레이드하거나 할당량을 늘리면 근본적으로 해결됩니다. 또한, 다른 애플리케이션이 동일한 API Key를 함께 사용하고 있는지 점검하세요. 키를 공유하면 제한 임계값을 쉽게 초과할 수 있습니다.
연결 시간 초과 또는 Socket Hang Up: 네트워크 및 프록시 점검
'Connection Timeout' 또는 'Socket Hang Up'은 대개 네트워크가 불안정하거나 프록시 설정이 잘못되었기 때문에 발생합니다. 먼저 OPenClaw 공식 서버에 직접 연결할 수 있는지 ping 또는 curl 명령어로 지연 시간을 테스트해 보세요. 프록시를 사용한다면 프로토콜과 포트 번호가 정확한지, 프록시가 트래픽을 차단하지 않는지 확인하세요. 일부 기업 내부 네트워크는 비표준 포트를 차단하기 때문에 HTTPS 포트(443)를 사용하면 제한을 우회할 수 있습니다. 또한, 타임아웃 값이 너무 짧게 설정되어 있으면 오탐이 발생할 수 있으니 기본값 10초에서 30초로 늘려서 다시 시도해 보세요.
500 Internal Server Error: 요청 본문 형식 우선 점검
서버에서 500 오류가 반환되면 서버 자체에 문제가 있다고 의심하기 전에, 먼저 요청 형식이 올바른지 확인하세요. JSON이 유효한지, 필드 이름이 정확하게 입력되었는지(예: 'model'을 'module'로 잘못 쓰지는 않았는지) 살펴보세요. 특히 boolean이나 숫자 값에 따옴표가 포함되어 있는지 주의하세요. 예를 들어 "temperature": true와 같이 작성하면 오류가 발생합니다. 요청 본문이 크다면 작은 단위로 나누어 보내거나, 메시지 배열에 지원되지 않는 역할(예: 모델이 지원하지 않는 function 역할)이 포함되어 있는지 확인하세요.
403 권한 거부: 계정 상태 및 지역 제한
403 오류는 계정이 잠겼거나 지역 제한으로 인해 발생할 수 있습니다. 먼저 OPenClaw 공식 사이트에 로그인하여 계정 상태를 확인하고, 미납 또는 정책 위반 알림이 있는지 살펴보세요. 일부 모델은 특정 지역에서만 사용할 수 있으므로, 현재 IP가 지원되지 않는 지역인 경우 노드를 변경하거나 글로벌 모드로 전환해 보세요. 또한, 일부 체험판 계정은 시간이 지남에 따라 액세스 권한이 줄어들기 때문에 요금을 갱신하거나 유료 플랜으로 업그레이드하면 403 오류가 해결되는 경우가 많습니다.
