2026 OpenClaw Gateway 무응답·모델 오류 분기: Troubleshooting과 doctor 실무 체크리스트

2026년에도 Gateway가 살아 있는데 답이 없는 이유

운영 현장에서 말하는 무응답은 종종 여러 층이 겹친 증상입니다. 프로세스는 떠 있고 헬스는 초록이며 리버스 프록시는 200을 돌려도, 모델 할당량이 바닥났거나 컨텍스트가 거절되었거나, 워커가 큐를 더 이상 소비하지 않아 사용자 화면에는 아무 텍스트도 오지 않습니다. 아래 여섯 가지는 당번이 자주 하는 오판입니다. 순서대로 대조하면 재시작만 반복하는 시간을 크게 줄일 수 있습니다.

1. 리버스 프록시 200을 비즈니스 성공으로 착각: Nginx나 Caddy의 200은 TLS와 라우팅 핸드셰이크가 끝났다는 뜻에 가깝습니다. WebSocket 업그레이드가 실패했거나 하위 경로 재작성이 어긋나면 비즈니스 프레임이 Gateway에 닿지 않을 수 있습니다. 리버스 프록시·TLS 글에서 증상별로 맞춥니다.
2. 채널은 붙었는데 OAuth나 프라이버시 정책이 답을 막음: 봇은 온라인인데 메시지가 없다면 범위, 채널 정책, 프라이버시 모드를 먼저 의심합니다. 모델 전에 채널 글을 돌립니다.
3. 모델 라우팅·페일오버가 비어 있음: 주 프로바이더가 429를 내고 예비 모델이나 쿨다운이 없으면 Gateway가 한동안 출력을 내지 못합니다. 다중 프로바이더 라우팅 글을 대조합니다.
4. 컨텍스트와 도구 면이 폭발해 조용히 실패: 로그에 long context나 도구 스키마류 힌트가 보이면 생성 단계에서 이미 거절된 경우가 많습니다. 도구 면을 줄이고 memory_search를 조입니다. Skills·memory_search 튜닝 글을 참고합니다.
5. MCP로 너무 빨리 점프: 모델 completion이 한 번도 없는데 MCP 포트만 만지면 방향이 엇갈립니다. 모델 응답은 있는데 도구 호출만 실패할 때 MCP·ClawHub 글로 돌아갑니다.
6. doctor를 매번 처음부터 돌리고 근거를 남기지 않음: openclaw doctor는 설정 변경 뒤 기준선 스냅샷에 잘 맞습니다. 사고마다 deep만 반복하면 회귀 지점이 가려집니다. 설치 후 doctor 글과 이어서, 설치 직후 한 번, 업그레이드 직후 한 번, 무응답 사고 때 한 번을 원칙으로 둡니다.

공식 Troubleshooting은 보통 Gateway와 모델 연결을 먼저 확인한 뒤 채널과 도구로 내려가라고 안내합니다. 본 글은 그 순서를 리뷰 첨부 수준의 표로 고정해 런북과 변경 티켓 번호에 묶기 쉽게 합니다.

현장에서는 무응답을 경성 실패(4xx·5xx와 스택이 분명함)와 연성 실패(로그는 조용한데 출력 없음)로 나누는 편이 빠릅니다. 연성 실패는 큐·타임아웃·컨텍스트 한계를, 경성 실패는 키·라우팅·리버스 프록시를 우선 봅니다. 같은 증상이라도 야간 피크와 평일 오전의 원인 분포가 다를 수 있으므로, 타임스탬프와 요청 식별자를 한 줄이라도 남기는 습관이 사후 분석 비용을 줄입니다. 팀이 여러 리전에 노드를 두었다면 동일 설정이라도 출구 IP와 지연 분포가 달라 보일 수 있으니, 관측 지점을 사용자 리전과 맞추는 것도 같은 표에 포함하는 것이 좋습니다.

또한 운영자가 익숙한 채팅 클라이언트 하나만으로만 재현을 시도하면, Web UI는 되고 외부 채널만 막히는 이중 입구 문제를 놓치기 쉽습니다. 재현 경로를 명시적으로 두 갈래로 나누어 적어 두면 본 글 뒤쪽 시나리오 절과 바로 연결됩니다.

표 1: 무응답 시 네 층 분기(프로세스·리버스 프록시·채널·모델)

상류에서 하류로 한 층씩 닫습니다. 어느 한 층이 닫히기 전에 네 층 설정을 동시에 바꾸면 롤백이 눈덩이처럼 커집니다.

표 2: 공식 Troubleshooting 흔한 동작과 로그 지문

아래 매핑은 커뮤니티와 공식 문서에서 자주 보이는 단계를 골격으로 잡았습니다. 세부 서브커맨드는 설치한 OpenClaw 버전의 CLI 도움말을 따릅니다. 목표는 동작과 로그 한 줄을 묶는 것이지, 감으로 재시작하는 것이 아닙니다.

명령 스니펫: doctor와 기준선—재현—비교

출력은 티켓 첨부로 보관하고 민감한 줄은 마스킹한 뒤 공유합니다. 플래그는 로컬 openclaw --help를 기준으로 합니다.

사례: 두 가지 무응답을 어떻게 종결하는가

시나리오 A: 채널에 읽음은 있는데 모델 텍스트가 끝내 없음

Gateway 로그를 30초 구간으로 잡아 프로바이더 응답 조각을 찾습니다. long context나 429가 보이면 프로바이더 글에 따라 쿨다운과 페일오버를 적용한 뒤 첫 토큰 지연이 회복되는지 봅니다.

시나리오 B: Web UI는 열리는데 외부 채널은 모두 침묵

리버스 프록시 WebSocket과 채널 OAuth를 우선 맞춥니다. UI는 localhost이고 채널은 공개 도메인을 쓰는 이중 입구 정책 불일치가 흔합니다. 같은 토폴로지 도표에 두 경로를 그린 뒤 차이를 짚습니다.

여섯 단계 런북: Troubleshooting을 당번 수첩에 넣기

1. 입구를 표시: 사용자가 어떤 URL·어떤 봇으로 들어왔는지 기록해 UI와 채널 테스트를 섞지 않습니다.
2. 네 층 표를 탄다: 프로세스에서 모델까지 순서대로 체크하고, 닫히지 않은 층이 있으면 설정을 병렬로 바꾸지 않습니다.
3. 최소 로그 묶음을 수집: 한 번의 완전한 요청 앞뒤로 50~200줄을 잡아 비식별화한 뒤 티켓에 올립니다.
4. doctor를 끼운다: 설정이 어긋난 것 같거나 업그레이드 직후에는 deep을 한 번 돌리고 직전 기준선과 diff합니다.
5. 최소 대화로 검증: 시스템 프롬프트와 사용자 문장을 가장 짧게 해 긴 컨텍스트 영향을 뺍니다.
6. 복기 템플릿에 쓴다: 근본 원인 태그(리버스 프록시·채널·모델·도구)와 예방 항목(모니터링, 할당량 알림, 라우팅)을 남깁니다.

런북을 문서 한 장으로 고정해 두면 신규 당번이 와도 같은 순서로 증거를 모을 수 있습니다. 표와 명령 블록을 인쇄하거나 위키에 그대로 붙여도 되고, 변경이 있을 때는 doctor 기준선과 함께 버전을 올리는 편이 안전합니다.

대시보드와 알림에 넣을 세 가지 지표

1. 첫 토큰 지연(TTFT)과 오류 코드 비율: 느리지만 성공한 경우와 조용히 실패한 경우를 가르고, 429 건수와 나란히 봅니다.
2. 채널 이벤트 성공률 대 모델 completion 비율: 둘이 어긋나면 층이 바로 갈립니다.
3. doctor 실패 항목 수: 릴리스 게이트로 써서 드리프트 설정을 프로덕션에 올리지 않습니다.

엔지니어링 관점의 정렬이지 벤치마크 공표는 아닙니다. 2025~2026 주기에는 다중 프로바이더와 긴 컨텍스트 기본값이 흔해지면서 큐와 할당량류 무응답이 커뮤니티 티켓에서 비중이 높게 남습니다. TTFT와 429를 같은 시간축에 그리면 CPU만 볼 때 설명되지 않던 전야 전사 침묵도 이해하기 쉬워집니다.

기업 프록시와 인증서 치환은 모델 HTTPS 프로브는 성공하는데 장시간 연결이 들쭉날쭉한 패턴을 만듭니다. 같은 캡처 창에서 Gateway 출구와 개발자 노트북 출구를 대조해 네트워크 정책 문제를 버전 결함으로 오인하지 않도록 합니다. 프록시 화이트리스트, SNI, HTTP/2 호환성을 Docker 네트워크 분기와 같은 페이지 부록에 적어 두면 당번은 출구 일치 여부만 확인해도 빠르게 갈라냅니다.

자체 호스팅 모델과 공용 클라우드 API를 함께 쓰는 팀은 변경 검토에 이중 스택 라우팅 표를 의무화하는 편이 좋습니다. 어떤 세션이 어떤 키를 쓰는지, 페일오버 조건이 무엇인지가 없으면 무응답은 단일 설정 오타가 아니라 표 자체의 공백에서 자주 납니다. 그 표는 doctor 기준선과 함께 버전 관리해 인수인계 뒤에도 구두로만 남던 약속이 사라지지 않게 합니다.

지표를 도입할 때는 임계값을 처음부터 완벽히 맞출 필요는 없습니다. 먼저 같은 패널에 세 곡선을 올려 두고 사고가 날 때마다 스크린샷을 티켓에 붙이면, 몇 주 안에 팀만의 정상 대역이 스스로 드러납니다. 그때부터 페이저를 거는 것이 소음을 줄입니다.

노트북에서 가끔만 되는 구성을 프로덕션 Gateway로 쓰기 어려운 이유

개인 기기의 절전, 라우팅 전환, 기업 출구 정책은 무응답을 재현하기 어려운 현상으로 만듭니다. 프로덕션에는 고정 출구, 정해진 기동 순서, 감사 가능한 로그 경로가 필요합니다. 소형 자체 호스트도 글로벌 접속과 디스크·대역 여유가 부족하면 피크에 모델 큐와 채널 재시도가 서로 밟습니다.

OpenClaw를 7×24 자동화 입구로 쓰려는 팀은 Gateway를 전용 Apple Silicon, 여러 리전 선택, 탄력적인 임대 기간을 갖춘 클라우드 Mac에 두고 본 런북과 상주 운영 체크리스트를 변경 검토에 묶는 편이 안전합니다. MACCOME은 싱가포르·일본·한국·홍콩·미국 동·서부 등에서 Mac mini M4·M4 Pro를 제공하므로 리버스 프록시, 영속 디렉터리, 모니터링을 고정하기 좋습니다. 공개 대여 요금과 리전 페이지를 본 뒤 주문 흐름을 맞춥니다.

파일럿으로는 주 사용자와 같은 리전의 단기 노드 한 대를 빌려 본 글의 여섯 단계 런북을 한 번 끝까지 연습한 다음, 월·분기 임대와 디스크 확장을 결정하는 방식을 권합니다.

문서 규율을 한 줄 덧붙이면, 무응답 사고를 닫을 때마다 근본 원인 태그와 대응하는 로그 패턴을 내부 지식베이스에 등록하고 다음 릴리스 전에 그 패턴이 여전히 모니터링되는지 확인합니다. 공식 Troubleshooting이 갱신되면 자사 부록과 diff해 매년 노트를 처음부터 다시 쓰지 않게 합니다.

원격 Mac을 도입할 때는 네트워크 경로만이 아니라 운영 책임 경계도 함께 적습니다. 누가 프록시 설정을 바꾸는지, 누가 API 키 로테이션을 도는지, 누가 채널 앱을 재승인하는지가 한 사람에게 몰리면 휴가 시즌에 같은 무응답이 반복됩니다. 런북의 여섯 단계에 역할 이름을 옆에 붙여 두면 온콜 로테이션과 맞물려 안정됩니다.