OPenClaw로 AI 개발을 하다 보면 다양한 오류에 막히기 마련입니다. API 호출 실패나 계정 권한 문제 등 예상치 못한 에러가 발생할 수 있는데요. 이 글에서는 자주 등장하는 오류 코드와 해결 방안을 정리해 드리니, 불필요한 시행착오를 줄이는 데 도움이 되길 바랍니다.
API 인증 오류: 401과 403
401 Unauthorized는 일반적으로 API 키가 유효하지 않거나 만료되었음을 의미합니다. 먼저 키에 문자가 실수로 삭제되지는 않았는지 확인한 후, OPenClaw 콘솔의 "API Keys" 페이지에서 새 키를 생성하세요. 복사할 때 앞뒤 공백이 누락되지 않도록 주의합니다. 반면 403 Forbidden은 해당 키가 특정 인터페이스에 접근할 권한이 없을 때 나타납니다. 관리자 페이지에서 역할 및 권한 설정을 확인하고, 계정에 올바른 Scope가 할당되었는지 점검하세요.
요청 시간 초과 및 네트워크 문제: 408과 429
408 Request Timeout은 서버가 요청을 너무 오래 기다렸다는 뜻으로, 주로 네트워크 지연이 높거나 요청 본문이 너무 클 때 발생합니다. 단일 요청 데이터 크기를 2MB 이내로 유지하고, 네트워크 프록시가 안정적인지 확인하세요. 429 Too Many Requests는 속도 제한에 걸린 경우입니다. OPenClaw는 계정당 분당 요청 횟수에 상한이 있습니다. 이 경우 60초 정도 기다린 후 재시도하거나, 요금제를 업그레이드하여 할당량을 늘리는 것이 좋습니다. 잦은 폴링은 피하는 것이 좋습니다.
서버 측 오류: 500과 502
500 Internal Server Error는 서버 측의 일시적인 장애로, 보통 OPenClaw 팀이 몇 분 내에 복구합니다. 먼저 status.openclaw.com에서 서비스 상태를 확인한 후, 정상으로 표시되면 다시 시도하세요. 오류가 지속된다면 전체 요청 로그를 첨부하여 기술 지원팀에 문의하는 것이 좋습니다. 502 Bad Gateway는 게이트웨이 계층의 문제인 경우가 많습니다. 5분 정도 기다린 후 재시도하면 대부분 복구되므로, 페이지를 반복해서 새로고침하지 마세요.
계정 잠금 및 구독 제한
로그인 후 Account Locked 메시지가 표시된다면, 비밀번호를 여러 번 잘못 입력했거나 비정상 로그인이 감지되었을 가능성이 높습니다. 등록된 이메일을 통해 비밀번호를 재설정하고, 최근 로그인 기록을 확인하세요. 또한 일부 고급 기능은 특정 구독 플랜이 필요합니다. 400 Bad Request 오류와 함께 "insufficient plan" 메시지가 표시된다면, 현재 요금제가 해당 작업을 지원하지 않는다는 의미이므로 Pro 버전으로 업그레이드하는 것을 고려하세요.
일상적인 실수 방지 팁
코드나 설정을 수정한 후에는 항상 소규모 테스트를 먼저 실행하는 습관을 들이면 많은 오류를 피할 수 있습니다. 또한 OPenClaw SDK를 최신 버전으로 유지하세요. 구버전은 인터페이스 변경으로 인해 예상치 못한 오류가 발생할 수 있습니다. 이해하기 어려운 오류가 나타나면 공식 문서의 Error Code 설명 페이지를 바로 확인하는 것이 가장 정확한 해석을 얻는 방법입니다.
