OpenClaw 429 오류 해결: 기다릴 때와 재시도를 멈출 때

OpenClaw에서 429 Rate limit exceeded가 나오면 같은 요청을 더 보내기 전에 요청을 만드는 작업을 줄이고, 어떤 서비스가 제한했는지 확인하세요. 모델 제공업체의 일시적인 속도 제한이라면 Retry-After 등으로 알려 준 최소 시간 이상 기다립니다. 구독·일간·주간·월간 사용량이 소진됐거나 비용 상한·접근 자격이 문제라면 짧은 재시도를 멈추고 해당 조건이 해소될 때까지 보류합니다. 스킬 설치 중 ClawHub가 반환한 429는 모델 API 키를 바꿔 해결할 문제가 아닙니다.

현재 OpenClaw는 적합한 일시 오류를 제한된 횟수 안에서 자동 복구합니다. 대기 중에 원래 요청을 반복해서 입력하면 기존 실행과 새 실행이 겹칠 수 있습니다. 이미 파일을 수정하거나 메시지를 보냈다면 그 결과를 먼저 확인하고 남은 단계부터 이어가는 것이 복구의 출발점입니다.

아래 절차는 2026년 10월 4~5일 확인한 공식 문서를 기준으로 합니다. 명령은 사용자가 자신의 환경에서 확인할 안내이며, 실제 계정 인증이나 유료 모델 호출로 복구를 시험한 결과는 아닙니다.

먼저 추가 요청을 줄이고 실패한 서비스를 확인하세요

대화창에서 재전송을 멈춥니다. 같은 계정을 쓰는 다른 agent, 예약 작업, heartbeat, 외부 스크립트가 계속 요청하는지도 확인하세요. 잠시 멈출 수 있는 작업은 보류하고, 진행 중인 도구는 결과가 확정됐는지 확인합니다. 실행을 취소해도 이미 끝난 외부 변경이 되돌아가지는 않습니다.

그다음 오류 원문과 발생 시각, 실패한 agent, 선택 모델, 실제 시도한 제공업체·모델을 남깁니다. 오류 코드가 같아도 복구 대상은 다릅니다.

Gateway 호스트에서 최근 로그를 좁게 읽을 수 있습니다. 다음은 문서에 나온 조회 옵션입니다.

openclaw --version
openclaw logs --limit 200 --max-bytes 250000 --plain

별도 프로필의 Gateway를 사용한다면 실제 이름에 맞춰 openclaw --profile work logs --limit 200 --plain처럼 확인합니다. work는 예시입니다. 필요한 구간이 없으면 범위를 조금 넓히거나 openclaw logs --follow로 다음 시도를 관찰한 뒤 Ctrl+C로 종료하세요. 현재 로그는 선택한 Gateway의 RPC와 프로필별 순환 파일을 따르므로 예전 글의 고정 로그 경로를 그대로 가정하지 않습니다. 공식 logs CLI 설명

로그 스트림의 연결 끊김이나 재연결 안내는 모델 제공업체의 429와 다른 사건입니다. 로그 소스가 바뀌면 겹치는 줄이 다시 표시될 수 있으므로 같은 요청 ID·시각을 대조하세요. 지원 문의에는 필요한 오류 구간만 남기고 API 키, 토큰, 개인 대화와 파일 내용은 제거합니다.

일시적인 제한이면 서버가 알려 준 시간 이상 기다립니다

오류가 분당 요청 수, 토큰 수, 동시 요청 또는 급격한 요청 증가를 가리키고 계정의 사용 가능 상태가 유지된다면 요청 속도를 줄인 뒤 기다립니다. 응답에 유효한 Retry-After가 있다면 그 값은 최소 대기 시간입니다. 다른 대화나 스크립트가 같은 제한을 계속 소비하면 기다린 뒤에도 실패할 수 있습니다.

현재 OpenClaw 재시도 정책에 따르면 모델의 일시적인 속도 제한은 최대 10회 시도 안에서 복구합니다. 첫 시도를 포함한 수이며 무제한 재시도가 아닙니다. 지수적으로 늘어나는 대기와 작은 무작위 지연을 사용하고, 제공업체가 더 긴 최소 대기를 요구하면 일반적인 30초 backoff 상한보다 그 안내가 우선합니다. 취소와 실행 전체 기한은 복구를 중단합니다.

대기 표시가 떠 있는 동안에는 같은 요청을 새로 보내지 마세요. 부분 출력이나 도구 실행이 있었다는 사실만으로 모델 응답이 성공한 것은 아닙니다. 다른 일시 오류에 적용되는 90초 연속 장애 창도 모든 429의 초기화 시간을 뜻하지 않습니다. 채널 전송의 기본 시도 횟수와 로그 재연결 횟수 역시 모델 요청의 시도 횟수와 별개입니다.

긴 대기 뒤 대체 모델로 바로 넘어가는 경우에는 다음 두 제한을 구분합니다.

• 저장된 retry.provider.maxRetryDelayMs는 대체 모델이 구성된 경우 서버가 요구한 대기를 얼마나 유지할지 정합니다. 현재 기본값은 60초입니다. 최소 대기가 이를 넘으면 적합한 대체 경로로 진행하며, 대체가 없으면 서버의 전체 최소 대기를 따릅니다. 0은 이 대기 상한을 끕니다.
• OpenClaw가 일부 SDK 내부 재시도에 적용하는 60초 상한은 SDK가 제어권을 돌려주도록 하는 별도 장치입니다. 제공업체의 제한이 60초 뒤 풀린다는 뜻이 아닙니다.

두 값 모두 공식 재시도 문서의 적용 범위에 맞춰 읽어야 합니다. 설치 버전의 지원 경로를 확인하지 않고 openclaw.json에 임의의 재시도 키를 추가하지 마세요. 내장 세션의 retry.provider.maxRetries도 일반 설정 파일의 키가 아닙니다.

요청 수가 적은데도 429가 나는 이유

작은 메시지 몇 개만 보냈어도 긴 기존 대화, 도구 정의와 출력 때문에 토큰 제한에 먼저 도달할 수 있습니다. 여러 agent나 프로그램이 하나의 제한을 공유하는 경우도 있습니다. OpenAI API는 조직·프로젝트 단위로 제한하며, 일부 모델은 같은 제한 풀을 공유합니다. 같은 조직에서 새 키를 발급하거나 모델 이름만 바꿔도 용량이 늘지 않을 수 있습니다. OpenAI 제한의 단위와 공유 풀

따라서 복구할 때는 동시 실행을 줄이는 것과 입력 범위를 줄이는 것을 함께 검토하세요. 파일 전체를 반복해서 읽는 대신 필요한 파일·줄만 요청하고, 긴 분석은 결과를 저장하며 순서대로 진행합니다. 실패한 요청도 OpenAI의 분당 제한에 포함되므로 짧은 간격으로 확인 요청을 보내는 방식은 도움이 되지 않습니다. 해당 오류가 slow_down이면 표시된 RPM·TPM 안에 있어도 증가 속도가 원인일 수 있으므로 낮은 요청 속도에서 천천히 늘립니다. OpenAI의 재시도·급증 제한 안내

사용량 소진·비용 상한·긴 컨텍스트 자격 문제면 재시도를 멈춥니다

오류가 weekly limit reached, monthly limit exhausted, 크레딧 부족 또는 비용 상한을 가리킨다면 같은 요청을 잠깐 기다렸다 반복하는 대신 해당 계정의 초기화 시각과 사용 가능 조건을 확인합니다. 현재 OpenClaw는 소진된 구독·일간·주간·월간 창에 대해 적합한 인증 프로필이나 모델 대체 경로로 바로 진행할 수 있습니다. Retry-After가 있다는 사실만으로 사용량 소진이 확정되는 것은 아닙니다. OpenClaw 사용량 소진 처리

OpenAI의 지출 알림은 요청을 계속 허용하지만 강제 비용 상한에 도달한 요청은 429로 거절될 수 있습니다. Anthropic도 요청 속도 제한 외에 사용 등급의 월간 비용 상한과 Claude Code workspace의 비용 제한으로 429를 반환합니다. Anthropic의 등급 비용 상한 오류는 retry-after가 없으며 접근이 회복될 때까지 계속 실패한다고 설명합니다. 단순히 “1분 뒤 다시 시도”로 처리할 분기가 아닙니다. OpenAI 비용 상한 구분, Anthropic 429 오류 설명

사용량이 초기화될 때까지 보류할지, 이미 허용된 다른 연결을 사용할지 정하세요. 크레딧 충전이나 유료 추가 사용을 켜는 것은 별도의 비용 결정이며 자동 복구 단계로 취급하지 않습니다. 충전했더라도 OpenClaw에 저장된 차단 창이 즉시 사라지는 것은 아니므로 다음 절의 로컬 상태도 확인합니다.

Extra usage is required for long context requests는 별도로 확인하세요

정확히 HTTP 429: rate_limit_error: Extra usage is required for long context requests가 나오고 긴 대화에서만 실패한다면 긴 컨텍스트 요청을 현재 인증으로 사용할 자격이 있는지 확인합니다. OpenClaw의 해당 오류 안내는 표준 창 모델, 긴 요청에 적합한 인증, 대체 모델을 복구 선택지로 제시합니다.

우선 실제 선택 모델과 긴 컨텍스트 설정을 조회합니다.

openclaw models status
openclaw config get agents.defaults.models

표준 창 모델을 선택한다면 그 모델의 실제 입력 한도 안에 들어가도록 필요한 대화와 자료를 준비해야 합니다. 구형 비정식 1M 모델 설정에 남은 params.context1m: true를 제거하는 선택지는 그 구형 설정에만 적용합니다. 현재 정식 1M 모델에서도 해당 값을 무조건 지우는 공통 처방은 아닙니다. API 키로 변경하더라도 그 인증에 필요한 자격이 있는지는 따로 확인해야 합니다.

이 오류는 일반적인 순간 속도 제한이나 context_length_exceeded와 같은 입력 초과와 구분합니다. 실제 입력 초과·압축 실패라면 작업을 보존하며 컨텍스트를 줄이는 방법을 따릅니다. 어느 경우든 기록 삭제나 유료 추가 사용 활성화를 첫 조치로 삼을 필요는 없습니다.

모든 인증 프로필이 쿨다운이면 이유와 만료 시각을 읽으세요

No available auth profile (all in cooldown)은 현재 선택할 수 있는 프로필이 없다는 뜻입니다. 모든 키가 틀렸다는 뜻이나 Gateway가 영구적으로 멈췄다는 뜻은 아닙니다. 실패한 agent를 지정해 상태를 확인합니다. 아래 <agentId>는 실제 ID로 바꿉니다.

openclaw models status --agent <agentId>
openclaw models status --agent <agentId> --json --check

상태의 Unavailable auth profiles 또는 JSON의 auth.unusableProfiles에서 각 이유와 회복 안내를 확인합니다. 이 명령은 기본 모델·대체 목록·인증 및 실행 환경을 설명합니다. 대화의 모델 고정 선택은 확인하지 않으므로 실패한 대화 안의 /model status도 봐야 합니다. --check 성공은 모델 요청 성공 증명이 아닙니다. models 상태 조회 범위

현재 인증·대체 복구 문서에 따르면 상태는 agent별 SQLite 인증 저장소의 usageStats에 보존됩니다.

현재 일반 쿨다운은 오류 횟수에 따라 30초, 1분, 최대 5분으로 늘어납니다. 비용 실패의 초기 차단 창은 10분이며 모델을 바꿔도 그 프로필 전체에 적용됩니다. 이 값은 OpenClaw의 로컬 선택 상태이지 제공업체 사용량 초기화 시각이 아닙니다. 서버의 대기 시간이 더 길거나 사용량이 소진됐다면 로컬 창이 끝나도 요청이 거절될 수 있습니다. 쿨다운과 비용 차단 규칙

Gateway 재시작으로 저장된 usageStats나 제공업체의 사용량이 초기화되지는 않습니다. 선택적 메모리 캐시가 재시작으로 지워지는 동작과 혼동하지 마세요. 또한 모든 프로필이 대기 중이라고 영원히 건너뛰는 것도 아닙니다. 현재 복구는 기본 후보의 만료가 가까울 때 제한된 확인을 하거나, 모델에 한정된 일시 실패라면 같은 제공업체의 적합한 다른 모델을 시도할 수 있습니다. 사용자가 빠르게 반복 확인할 이유는 없습니다.

실제 이유가 401·토큰 거절이면 실패한 인증을 구분해 복구하는 방법으로 진행하세요. 429를 보았다는 이유만으로 모든 키를 교체하면 원인과 사용 계정만 더 복잡해질 수 있습니다.

대체 모델이 설정돼도 작동하지 않으면 현재 선택을 확인하세요

대체 목록에 모델이 있다는 사실만으로 모든 대화가 그 모델로 넘어가지는 않습니다. 현재 OpenClaw는 모델을 선택한 경로에 따라 대체 허용 여부를 정합니다. 공식 모델 대체 정책

대화에서 /model status와 /status로 선택 모델과 실제 답한 모델을 확인하세요. 기본 설정의 대체 정책을 사용하려는 의도라면 /model default로 대화의 모델 고정을 해제할 수 있습니다. 다른 모델로 자료가 전달돼도 되는지와 해당 모델의 인증·입력 한도를 먼저 확인합니다. 모델 연결과 선택을 새로 설정해야 한다면 OpenClaw 모델 설정 안내에 구체적인 절차가 있습니다.

적합한 일시 오류 복구를 소진한 뒤에는 인증 전환이나 모델 대체로 진행할 수 있습니다. 인증 실패, 비용 차단, 사용 가능한 모델을 찾지 못한 오류도 조건에 따라 대체 후보로 넘어갑니다. 하지만 동일한 잘못된 요청 형식, 취소, 실행 전체 기한 종료를 무한 대체로 처리하지 않습니다. 컨텍스트 초과는 해당 압축·복구 경로의 소유와 상태에 따라 처리하므로 “오류면 전부 다음 모델”이라는 규칙도 맞지 않습니다. 대체를 진행하는 오류와 중단하는 오류

대체 모델이 답해도 다음 턴의 선택 모델이 영구적으로 바뀌는 것은 아닙니다. 현재 대체 실행은 해당 턴에만 적용됩니다. 다음 요청에서 원래 기본 모델이 다시 제한에 걸릴 수 있으므로, 그 제공업체로 요청을 계속 몰아넣는 작업도 줄여야 합니다. 여러 후보가 같은 제한 풀을 공유하면 대체가 새로운 용량을 만들지 못합니다.

ClawHub 검색·다운로드의 429는 별도 제한입니다

스킬 검색, 설치 또는 업데이트에서 Rate limit exceeded가 나온다면 먼저 응답한 주소와 오류 본문이 ClawHub인지 확인합니다. ClawHub는 스킬·플러그인 레지스트리이며 모델 추론 제공업체와 별개입니다. 현재 네이티브 openclaw 명령은 검색·설치·업데이트에 사용하고, 별도 clawhub CLI는 레지스트리 인증 등의 작업을 담당합니다. ClawHub 명령의 역할

일괄 업데이트나 여러 설치를 잠시 멈추고 응답 헤더에 따라 기다린 뒤 필요한 항목 하나부터 재개하세요. ClawHub HTTP API는 읽기·쓰기·다운로드 제한을 분리하며 다음 시간 단위를 사용합니다.

예를 들어 ClawHub 응답의 Retry-After: 34 또는 RateLimit-Reset: 34는 적어도 34초 기다리라는 뜻입니다. 설명용 값이며 모든 계정의 제한이 아닙니다. X-RateLimit-Reset의 큰 숫자를 대기 시간으로 그대로 쓰지 말고 현재 Unix 시각과의 차이를 계산해야 합니다. OpenAI의 초기화 헤더는 1s, 6m0s 같은 기간 문자열일 수 있으므로 다른 서비스의 숫자 해석을 그대로 옮기지 않습니다. ClawHub 헤더 정의, OpenAI 헤더 정의

익명 요청은 IP 기준이며 유효한 Bearer 토큰을 사용한 요청은 사용자 기준입니다. 토큰이 없거나 유효하지 않으면 IP 제한으로 돌아갑니다. 같은 출구 IP를 공유하는 환경에서는 개인 요청이 적어도 제한에 도달할 수 있습니다. 지원되는 인증 경로에서 로그인하고 안내된 시간을 기다리는 방법을 공식 문제 해결 문서가 제시합니다.

이미 별도 ClawHub CLI를 사용하는 경우 clawhub whoami는 그 CLI의 로그인 상태 확인에 사용할 수 있습니다. 성공해도 네이티브 OpenClaw 설치가 같은 토큰을 사용했다는 증거는 아닙니다. 실제 실패한 요청의 인증 경로를 확인해야 합니다. 모델 API 키 추가, IP 변경, 숨겨진 배포본 내려받기를 제한 해결책으로 삼지 마세요. 다운로드가 다시 허용돼도 패키지의 공개 상태·보안 검사·호환성 확인은 필요하며, 429가 사라졌다는 것만으로 설치가 완료된 것은 아닙니다.

완료한 작업을 확인하고 작은 요청 하나로 재개하세요

대기 시간이 지나거나 적합한 다른 경로를 준비했다면 전체 작업을 처음부터 다시 돌리기 전에 다음 순서로 재개합니다.

1. 진행 결과를 확인합니다. 수정된 파일, 완료된 도구 결과, 이미 전달된 메시지와 외부 작업을 직접 확인합니다. 응답을 받지 못한 작업은 실패로 단정하지 말고 실제 결과를 대조합니다.
2. 복구 메모를 남깁니다. 목표, 확인된 완료 항목, 미완료 요청, 다음 한 단계, 정확한 경로·모델·오류를 적습니다. 모델이 멈췄다면 메모를 요청하며 호출을 더 보내기보다 보이는 기록에서 직접 작성합니다.
3. 하나의 작은 요청만 실행합니다. 적합한 모델에서 짧은 응답을 확인합니다. 이는 실제 사용 요청이며 토큰·비용·제한을 소비할 수 있습니다. 모든 프로필을 병렬 --probe로 확인하는 방식은 기본 복구 절차로 사용하지 않습니다.
4. 성공한 다음 남은 단계만 이어갑니다. 완료한 작업을 명시적으로 제외하고 필요한 파일·출력 범위를 좁힙니다. 동시 작업과 예약 요청은 한꺼번에 되살리지 말고 순서대로 늘립니다.

현재 내장 복구는 기존 대화 기록에서 이어가고 중단된 행동의 결과를 확인하도록 하여 완료한 작업의 반복을 피합니다. 그러나 사용자가 원래 요청을 새 턴으로 여러 번 보내거나 외부 스크립트가 전체 작업을 재실행하면 별도의 중복 위험이 생깁니다. 완료한 작업을 보존하는 재시도 정책

모델 요청의 성공 신호는 실제로 완료된 응답, 확인한 제공업체·모델, 같은 시도의 오류 해소입니다. 프로필이 목록에 보이거나 상태 검사만 통과한 것은 충분하지 않습니다. 파일 작업을 재개했다면 실제 파일 결과까지, ClawHub 설치를 재개했다면 해당 설치의 완료 결과까지 확인하세요. 짧은 응답 하나의 성공이 원래 동시 부하를 감당한다는 증거도 아닙니다.

같은 작은 요청에서도 계속 실패하면 다시 요청을 늘리지 않습니다. 오류가 같은지, 실패 후보·프로필과 초기화 시각이 무엇인지, 여전히 요청하는 다른 작업이 있는지 확인합니다. 제한 창 소진·자격 거절·비용 차단이면 해소 전까지 보류하고, 명확한 일시 오류가 제한된 복구 뒤에도 계속되면 필요한 요청 ID와 민감한 내용을 제거한 로그를 해당 제공업체 지원에 전달합니다.

자주 묻는 질문

OpenClaw를 재시작하면 429가 풀리나요?

재시작은 제공업체의 사용량을 초기화하지 않으며 저장된 쿨다운·차단 상태도 지우지 않습니다. 일시 제한의 서버 대기 시간과 auth.unusableProfiles의 이유를 확인하세요. 일부 선택적 메모리 캐시가 재시작으로 사라지는 동작은 다른 문제입니다. 저장되는 인증 상태

API 키를 하나 더 만들면 요청 제한이 늘어나나요?

같은 제한을 공유한다면 늘어나지 않습니다. OpenAI API는 조직·프로젝트 제한을 사용하며 일부 모델도 제한 풀을 공유합니다. 실제로 독립된 사용 가능 경로인지 확인해야 하며 키 수만으로 용량을 계산할 수 없습니다. OpenAI 제한의 적용 단위

자동으로 기다리고 있는데 원래 요청을 다시 보내도 되나요?

기존 실행이 살아 있는 동안은 재전송을 보류하는 편이 좋습니다. 현재 적합한 429 복구는 기존 기록에서 최대 10회 시도 안에 진행됩니다. 최종 실패 뒤에는 완료된 결과를 확인하고 미완료 단계만 요청하세요. 취소나 기한 종료가 이미 실행한 외부 작업을 되돌리지는 않습니다. OpenClaw 복구와 반복 실행 방지

모델은 정상 응답하는데 스킬 설치만 429이면 무엇을 바꿔야 하나요?

ClawHub의 요청·다운로드 제한을 확인해야 합니다. 모델 키를 바꾸기보다 설치·업데이트 요청을 줄이고 ClawHub의 Retry-After를 따르세요. 공용 IP의 익명 제한이라면 지원되는 인증 경로도 확인합니다. ClawHub 429 복구