OPenClaw를 사용하다 보면 다양한 오류 메시지를 마주칠 수 있습니다. 이 글에서는 사용자들이 가장 흔히 겪는 오류 코드를 로그인 인증, 네트워크 연결, API 호출 등의 상황별로 체계적으로 정리하고, 바로 실행할 수 있는 해결 방법을 알려드립니다. 정상적인 사용 환경으로 신속하게 복구하세요.
로그인 및 권한 오류: 401과 403
401 Unauthorized 메시지가 뜨면 대개 API 키가 유효하지 않거나 만료된 경우입니다. OPenClaw 콘솔에서 새 키를 생성한 후 코드에 올바르게 입력했는지 확인하세요. 키는 대소문자를 구분하며 복사할 때 불필요한 공백이 포함되지 않도록 주의하세요.
403 Forbidden은 현재 계정의 권한으로는 해당 작업을 수행할 수 없음을 의미합니다. 무료 버전 사용자가 유료 기능에 접근하려 할 때 자주 발생합니다. 구독 상태를 확인하고, 업그레이드가 필요하다면 계정 센터에서 요금제를 변경하세요. 정상 구독 중인데도 오류가 발생한다면 고객 지원에 문의하여 권한을 새로고침 받으시면 됩니다.
네트워크 및 연결 오류: Timeout과 Connection Reset
요청 시간 초과(Timeout)는 주로 로컬 네트워크 불안정 또는 OPenClaw 서버의 일시적 혼잡 때문에 발생합니다. 먼저 WiFi에서 모바일 데이터로 전환하는 등 네트워크 환경을 바꿔보세요. 문제가 계속되면 기본 30초에서 60초로 타임아웃 설정을 늘려보는 것도 방법입니다.
Connection Reset은 연결이 중간에 끊겼음을 나타냅니다. 대개 방화벽이나 프록시가 OPenClaw의 IP 대역을 차단한 경우입니다. OPenClaw 공식 도메인을 화이트리스트에 추가하고, VPN을 끄거나 프록시 규칙을 조정하세요. 기업 사용자는 아웃바운드 보안 정책에서 외부 API 요청을 제한하고 있지 않은지 확인해야 합니다.
API 호출 오류: 429와 500
429 Too Many Requests는 가장 흔한 속도 제한 오류입니다. OPenClaw는 인터페이스 호출 빈도에 제한이 있으며, 무료 버전은 분당 최대 20회, 유료 버전은 요금제에 따라 상향됩니다. 요청 빈도를 낮추거나 지수 백오프 재시도 방식을 구현하세요. 높은 동시 처리가 필요하다면 더 높은 할당량을 제공하는 상위 요금제로 업그레이드하는 것을 고려하세요.
500 Internal Server Error는 OPenClaw 서버 측에 일시적인 장애가 발생했음을 의미합니다. 먼저 OPenClaw 공식 상태 페이지에서 유지보수 기간인지 확인하세요. 일시적 문제라면 3~5분 후 다시 시도하면 복구됩니다. 오류가 지속되면 티켓을 통해 전체 요청 로그를 첨부하여 기술팀에 전달하세요. 같은 요청을 단시간에 반복 전송하면 속도 제한이 걸릴 수 있으니 주의하세요.
계정 잠금 또는 비정상 로그인 알림
잘못된 비밀번호를 연속으로 여러 번 입력하거나 평소와 다른 지역에서 로그인을 시도하면 OPenClaw의 보안 보호 기능이 작동하여 계정이 일시적으로 잠길 수 있습니다. 이 경우 등록된 이메일로 잠금 해제 링크를 받거나 SMS 인증번호로 재로그인하세요. 인증번호가 도착하지 않으면 이메일 스팸함을 확인하고, 휴대폰 번호가 정상적으로 등록되어 있고 요금이 연체되지 않았는지 점검하세요. 오랫동안 사용하지 않은 위험도가 높은 계정은 2차 인증(2FA)을 활성화하여 오잠금 가능성을 낮추는 것이 좋습니다.
