API 요청 실패를 해결하는 Retry policy 설정하기

네트워크가 불안정하거나 API 속도 제한에 걸려 메시지 전송이 실패하면 참 난감하죠? 매번 수동으로 재시도 코드를 짤 수도 없고, 그렇다고 실패한 채로 방치할 수도 없으니까요.

이런 상황에서 요청이 성공할 때까지 자동으로 다시 시도해 주는 기능이 있다면 정말 편할 거예요. OpenClaw에서 제공하는 Retry policy를 사용해 이 문제를 어떻게 해결하는지 바로 알려드릴게요.

필요한 것

• ~/.openclaw/openclaw.json 설정 파일

빠른 시작

5분 만에 설정을 끝내고 재시도 로직을 적용해 보세요. ~/.openclaw/openclaw.json 파일을 열고 원하는 채널에 retry 옵션을 추가하면 됩니다.

{
  channels: {
    telegram: {
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
    discord: {
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

이 설정은 각 API 요청(메시지 전송, 미디어 업로드, 리액션, 폴, 스티커 등)마다 독립적으로 적용돼요.

주요 특징

OpenClaw의 재시도 정책은 다음과 같은 규칙을 따라요.

• 단계별 순서 보장: 여러 단계로 구성된 흐름 전체를 재시도하는 대신, 현재 실패한 단계만 재시도해서 순서를 유지해요.
• 중복 작업 방지: 멱등성이 보장되지 않는 작업이 중복으로 실행되지 않도록 설계되었어요.
• 기본값 제공: 별도 설정이 없어도 기본적으로 3번의 시도, 최대 30,000ms의 지연 시간, 0.1의 Jitter가 적용돼요.
• 지능형 대기: Discord나 Telegram에서 retry_after 값을 주면 그 시간을 우선적으로 따르고, 없으면 Exponential Backoff를 사용해요.

Provider별 동작 방식

채널마다 재시도를 결정하는 기준이 조금씩 달라요.

Discord

• 오직 속도 제한 에러(HTTP 429)가 발생했을 때만 재시도해요.

Telegram

• 속도 제한(429), 타임아웃, 연결 오류(Connect/Reset/Closed), 일시적인 서비스 중단 시에 재시도해요.

문제 해결

재시도 설정 중 겪을 수 있는 상황들이에요.

• Telegram Markdown 에러: Markdown 파싱 에러가 발생하면 재시도하지 않아요. 대신 자동으로 Plain text로 전환해서 전송을 시도해요.
• 이미 완료된 단계: 여러 작업이 묶인 복합 흐름에서 이미 성공한 단계는 재시도 대상에 포함되지 않아요.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

• Provider 설정 가이드
• OpenClaw CLI 사용법