본문 바로가기
개발 스터디/AI - OpenClaw

OpenClaw 운영 가이드 - 멀티봇 환경에서 에이전트별 모델 fallback 설정으로 Rate Limit 방지하기

by 가리봉맨 2026. 2. 25.
목차
반응형

에이전트가 갑자기 응답을 멈추는 상황을 반복해서 겪다가 결국 fallback 설정으로 해결했다. 그 과정에서 게이트웨이 구동에 실패하는 사고도 한 번 겪었다.

들어가는 말

OpenClaw 최초 설치 이후 메인 에이전트만 운영하다 최근 서브 에이전트 둘을 추가했다. 총 세 명의 에이전트를 돌리는 멀티 에이전트 체제를 구축한 것이다. 별문제 없이 잘 쓰고 있었는데 일주일쯤 전에 텔레그램으로 서브 에이전트, Ruth에게 말을 걸었는데 아무 반응이 없는 것이었다. 메인 에이전트인 Eli는 잘 답하는데 서브 에이전트 하나만 먹통이었다. 처음엔 설정이 꼬인 건가 싶어서 게이트웨이를 재시작했다. 다행히 정상으로 돌아왔고 이 일은 기억에서 잊혀지고 있었다.

그런데 며칠 뒤 또 같은 상황이 생겼다. 이번엔 다른 서브에이전트, Dani였다. 이번에도 게이트웨이를 재시작하니까 정상으로 돌아왔다. 이상하다 싶었지만 매번 재시작으로 해결되니까 또 그냥 넘어갔다.

그러다가 패턴이 눈에 들어왔다. 에이전트가 멈추는 건 항상 특정 모델의 사용량이 많은 날이었다. Anthropic의 Claude Max 구독 기준으로 모델별로 세션&주간 사용 한도가 있는데, 그게 꽉 차면 리셋될 때까지 해당 모델이 응답을 거부한다. 그 순간 그 모델을 쓰는 에이전트는 그냥 멈추는 것이었다. Eli는 주 모델이 Claude 모델이 아니라서 살아있었을 뿐이고.

원인을 알았으니 해결책은 단순했다. 에이전트마다 "1번 모델이 막히면 2번으로 넘어가라"는 fallback 설정을 추가하면 됐다. 그런데 이 과정에서 설정 키 이름을 대충 추측해서 넣었다가 OpenClaw 게이트웨이가 30분 동안 멈췄다. 상용 서비스에 비유하면 서버가 내려간 것이다. 그 기록도 같이 남긴다.

fallback이란

OpenClaw에서 에이전트에 모델을 설정할 때 단순히 이름 하나만 넣는 방식도 되지만, 아래처럼 primary와 fallbacks 구조로 넣으면 primary가 실패했을 때 fallbacks 목록을 순서대로 시도한다.

반응형
"model": {
  "primary": "anthropic/claude-sonnet-4-5",
  "fallbacks": [
    "google/gemini-3.1-pro-preview"
  ]
}

primary가 rate limit이나 오류로 응답 불가 상태가 되면, OpenClaw가 자동으로 fallbacks 배열의 첫 번째 모델을 시도한다. 그것도 안 되면 그 다음 것을. 사람이 직접 재시작할 필요가 없다. 더 자세한 내용은 아래 OpenClaw 공식 문서 참고.

https://docs.openclaw.ai/concepts/model-failover

 

Model Failover - OpenClaw

 

docs.openclaw.ai

fallback 설정 위치와 구조

수정해야 하는 설정 파일은 ~/.openclaw/openclaw.json이다. agents.list 배열 안에 에이전트가 나열되고, 각 에이전트에 model 필드를 따로 지정하는 구조다. 에이전트마다 primary와 fallbacks를 다르게 조합한 것이 핵심이다. OpenClaw 문서에는 명확하게 써 있지 않지만 agents.list 구조, 즉 에이전트가 각각 독립적인 설정을 갖는다는 말이 나온다.

https://docs.openclaw.ai/concepts/multi-agent

 

Multi-Agent Routing - OpenClaw

Add agents, accounts, and bindings Add agents under agents.list, channel accounts under channels. .accounts, and connect them with bindings (examples below).

docs.openclaw.ai

아래는 에이전트 셋을 구성하는 설정 예시다. 

"list": [
  {
    "agents": {
      "list": [
        {
          "id": "main",
          "model": {
            "primary": "anthropic/claude-sonnet-4-5",
            "fallbacks": [
              "google/gemini-3-pro-preview",
              "openai-codex/gpt-5.2"
            ]
          }
        },
        {
          "id": "ruth",
          "model": {
            "primary": "google/gemini-3-pro-preview",
            "fallbacks": [
              "anthropic/claude-sonnet-4-5"
            ]
          }
        },
        {
          "id": "dani",
          "model": {
            "primary": "openai-codex/gpt-5.3-codex",
            "fallbacks": [
              "anthropic/claude-sonnet-4-5"
            ]
          }
        }
      ]
    }
  }
]

위 코드는 model 필드(오브젝트)의 구조를 보여주기 위한 예시일 뿐, 실제로 내가 운영 중인 fallbacks는 비싼 모델부터 무료 모델까지 에이전트 별로 6~7개의 fallbacks를 설정해서 운영하고 있다. 아래 '더보기'로 공유한다. id 기준으로 'main'이 기본 에이전트, 'ruth', 'dani'가 서브 에이전트들이다.

더보기
    "list": [
      {
        "id": "main",
        "model": {
          "primary": "moonshot/kimi-k2.5",
          "fallbacks": [
            "openai-codex/gpt-5.2",
            "google-gemini-cli/gemini-3-pro-preview",
            "anthropic/claude-sonnet-4-5",
            "zai/glm-4.7",
            "zai/glm-4.7-flash",
            "openrouter/upstage/solar-pro-3:free"
          ]
        }
      },
      {
        "id": "ruth",
        "name": "ruth",
        "workspace": "/Users/garibong/.openclaw/workspace-ruth",
        "agentDir": "/Users/garibong/.openclaw/agents/ruth/agent",
        "model": {
          "primary": "moonshot/kimi-k2.5",
          "fallbacks": [
            "openai-codex/gpt-5.2",
            "google-gemini-cli/gemini-3-pro-preview",
            "anthropic/claude-sonnet-4-5",
            "zai/glm-4.7",
            "zai/glm-4.7-flash",
            "openrouter/upstage/solar-pro-3:free"
          ]
        }
      },
      {
        "id": "dani",
        "name": "dani",
        "workspace": "/Users/garibong/.openclaw/workspace-dani",
        "agentDir": "/Users/garibong/.openclaw/agents/dani/agent",
        "model": {
          "primary": "moonshot/kimi-k2.5",
          "fallbacks": [
            "openai-codex/gpt-5.2",
            "google-gemini-cli/gemini-3-pro-preview",
            "anthropic/claude-sonnet-4-5",
            "zai/glm-4.7",
            "zai/glm-4.7-flash",
            "openrouter/upstage/solar-pro-3:free"
          ]
        }
      }
    ]

그대로 복사해서 쓰는 것보다 참고만 하고, 각자 구독(또는 API 호출 잔여 예산)중인 LLM 서비스와 추구하는 방향성(성능, 안정성 중 어느 쪽인지) 등에 따라 적절히 설정해야 한다.

주의: 모델명은 자신의 환경에서 실제로 허용된 이름으로 바꿔야 한다. 위 예시의 모델명을 그대로 쓰면 안 된다. 어떤 모델명을 써야 하는지는 바로 아래에서 확인하는 방법을 설명한다.

fallback 설정 전에 반드시 확인할 것

1. 허용 모델 목록 먼저 확인

모델명을 감으로 넣으면 안 된다. 내 환경에서 실제로 쓸 수 있는 모델 목록은 아래 과정을 통해 확인한다. 두 단계를 거쳐야 하는데 더 편한 방법을 아는 분은 공유해 주시길.. 먼저 아래 명령을 입력해서 인증을 마쳐서 사용할 수 있는 Provider(구글, OpenAI, Claude 등) 리스트를 확인한다.

openclaw models

이어서 아래 명령으로 특정 Provider의 모델 리스트를 확인한다.

openclaw models list --all --provider <name>

여기서 출력된 모델명(예시: google-gemini-cli/gemini-3-pro-preview)을 그대로 복사해서 설정 파일(openclaw.json)을 열고, 'fallback 설정 위치와 구조' 챕터에서 설명한 올바른 위치에 붙여 넣는다. 철자 하나라도 다르면 문제가 생긴다.

2. 수정 후 바로 재시작하지 말 것

설정 파일 수정 후에는 먼저 아래 명령어로 설정이 올바른지 검증한다.

openclaw doctor

⚠️ --fix 옵션은 붙이지 않는다. --fix를 붙이면 config를 자동으로 '고치는데', 그 과정에서 기존 설정이 초기화되는 경우가 있다. 검증만 할 때는 옵션 없이 실행하는 것이 안전하다.

문제가 없다는 출력이 나오면 그때 재시작한다.

openclaw gateway restart

 

사실 이상의 과정을 직접 수행할 필요는 없다. 대강 어떻게 동작하는지만 알아두고, 에이전트에게 fallbacks를 구성해 달라고 말로 요청하는 것이 편한 것은 물론이고 오히려 안전할 수 있다. json 설정 파일을 직접 수정하다 낭패를 본 경험을 공유한다.

사고 사례 공유 - Gateway 재시작 실패

서론이 길었다(응?). 여기부터가 본론이다. fallback 설정을 처음 넣을 때 공식 문서를 제대로 확인하지 않고 modelFallbacks라는 키를 임의로 썼다. 에이전트에게 물어봐서 얻은 답이었는데 의심 없이 그냥 썼다가 된통 당했다. 나름 괜찮은 모델인 Claude Sonnet 4.6을 썼는데 할루시네이션이 발생한 것이다. 이후에는 OpenClaw 설정 관련해서 묻는 프롬프트를 줄 때 OpenClaw 문서 기반으로 대답하라는 말을 덧붙인다.

이 상태로 openclaw gateway restart를 실행했더니 Gateway가 아예 뜨지 않았다. 당연히 전 에이전트가 동시에 응답 불가 상태가 됐다. 등에 식은땀이 흘렀다.

나중에 알게 된 사실이지만 OpenClaw는 config 파일에 모르는 키가 들어오면 validation 단계에서 부팅 자체를 거부한다.

❌ 틀린 예시:

{
  "agents": {
    "list": [
      {
        "id": "ruth",
        "modelFallbacks": ["anthropic/claude-sonnet-4-5"]
      }
    ]
  }
}

modelFallbacks라는 키는 OpenClaw에 존재하지 않는다. 결국 백업 파일(~/.openclaw/openclaw.json.bak)을 사용해서 수동으로 복원하는 방식으로 겨우 복구했다. 대부분 복구됐지만 직전에 수정했던 Nano Banana 관련 키 설정이 날아가서 다시 설정했다. 전체 다운타임은 약 30분이었다.

올바른 구조는 model 필드 안에 primary와 fallbacks를 넣는 것이다.

✅ 올바른 예시:

{
  "id": "ruth",
  "model": {
    "primary": "google/gemini-3-pro-preview",
    "fallbacks": ["anthropic/claude-sonnet-4-5"]
  }
}

당연한 말이지만 config 키 이름은 추측해서 쓰면 안 된다. 반드시 공식 문서나 openclaw doctor로 검증해야 한다.

fallback 설정 적용 후 확인

재시작 후 에이전트가 의도한 모델로 잡혔는지 확인한다.

openclaw status

또는 Control UI(http://127.0.0.1:18789)에서 에이전트 카드별 현재 모델을 눈으로 확인할 수 있다. 더 자세한 CLI 명령어는 아래 공식 문서 참고.

https://docs.openclaw.ai/concepts/models

 

Models CLI - OpenClaw

 

docs.openclaw.ai

정리

항목 내용
설정 파일 ~/.openclaw/openclaw.json
설정 구조 agents.list[].model = { primary, fallbacks }
모델명 확인 openclaw models 출력 기준으로 복사
수정 후 검증 openclaw doctor (--fix 없이)
적용 openclaw gateway restart
복구 백업 위치 ~/.openclaw/openclaw.json.bak.*

멀티 에이전트를 안정적으로 운영하려면 "좋은 모델"을 고르는 것보다 "모델이 막혀도 에이전트가 안 멈추는 구조"를 만드는 게 먼저다. fallback 설정은 보험이고, 에이전트마다 개별로 넣어야 그 보험이 제대로 작동한다. 끝.

관련 글:

글이 도움이 됐다면 아래 공감(♥️) 아이콘 클릭 부탁드립니다^^

반응형
저작자표시 비영리 변경금지 (새창열림)
사업자 정보 표시
가리봉랩스(Garibong Labs) | 함동기 | 87, Jukjeon-ro | 사업자 등록번호 : 604-05-36402 | TEL : 010-5130-6483 | Mail : hamjoon@gmail.com | 통신판매신고번호 : 2026-용인수지-0037호 | 사이버몰의 이용약관 바로가기

'개발 스터디 > AI - OpenClaw' 카테고리의 다른 글

OpenClaw 운영 가이드 - OpenClaw 버전 업데이트 중 오류 발생 시 복구(rollback) 방법 정리  (0) 2026.02.17
OpenClaw 활용 가이드 - 한 지붕 두 에이전트, 서브 에이전트 생성부터 디스코드 채널 입장까지  (2) 2026.02.09
OpenClaw 활용 가이드 - Brave Search API를 연동해서 에이전트에 웹 검색 기능 추가하기  (0) 2026.02.06
OpenClaw 활용 가이드 - KOBIS(영진위) API를 연동해서 새 영화가 개봉할 때마다 알림 받기  (0) 2026.02.06
OpenClaw 활용 가이드 - Tailscale을 이용해서 맥미니(OpenClaw 설치 기기)에 원격 접속하기  (1) 2026.02.05

관련글

티스토리툴바