2026 OpenClaw 공식 트러블슈팅 래더: gateway probe, channels 프로브, 장문맥락 429, openclaw.extensions
자체 호스팅 OpenClaw 장애는 “어시스턴트 소실”처럼 보입니다. 빠른 래더는 프로세스·RPC·openclaw doctor를 먼저 고정하고 채널 프로브는 나중입니다. 2026 대표 함정은 429와 openclaw.extensions 누락입니다.
플래그는 --help로 버전에 맞추고 순서는 불변으로 보세요. 출력을 티켓에 붙여 증적 없는 패치를 줄입니다.
목차(TOC)
1. 래더를 건너뛰면 조사 예산이 타는 이유
다층 구조라 “연결됨”도 토큰·캐시·CLI／GW 분열이 섞입니다. TLS／방화벽부터 만지면 대조 실험이 깨집니다. 병렬 변경은 이분 탐색을 망가뜨리고, 429／타임아웃은 HTTP 로그 없이 채널 오진으로 흐르며, extensions 공백은 네트워크 불안처럼 보입니다.
- 병렬 편집은 인과 서사를 지웁니다.
- 429는 HTTP 없이 프로브 뒤에 숨습니다.
- manifest 공백은 네트워크 불안을 가장합니다.
2. 60초 래더와 필수 증적
메모 상단에 사용자·HOME·CLI／GW 버전·해시를 고정합니다. 운영 인식과 다르면 먼저 메타데이터 분열을 맞춥니다.
gateway probe로 지연·TLS·거부 분류를 남기고, gateway status와 openclaw doctor를 한 장으로 묶습니다. RPC 거부면 채널 스크린샷은 거의 이득이 없습니다.
합리적일 때만 채널 프로브로 갑니다. doctor가 원격 URL／토큰 불일치를 보이면 메신저 전에 원격 행렬을 맞춥니다. Docker는 토큰／포트／WS 코드를 병기하고 localhost 대비 공개 실패 시 compose／게시 경로를 우선합니다. meta.lastTouchedVersion 불일치면 방화벽보다 분열 업그레이드 매트릭스를 밟습니다. 초록인데 유령이면 이중 토글과 plugins.entries를 봅니다. 출력은 변경 티켓에 붙입니다.
3. 결정 표: 증상 대 첫 증거
GW／채널 증적 없으면 희귀 MCP는 뒤로 미룹니다.
| 증상 | 증거 | 층 | 다음 |
|---|---|---|---|
| CLI 비도달 | probe stderr／timeout | RPC·listener·token | 먼저 probe |
| doctor 드리프트 | 마스크 doctor | 권한／JSON | 카테고리당 하나 |
| probe 초록·채팅 무음 | 이중／plugins.entries | 입장 | 채널 심층으로 |
| 429 폭주 | model ID／hdr／동시 | quota／tier | backoff／키 분리／축소 |
| 설치 후 플러그인 없음 | package.json extensions | 로더 선언 | 수정／얇은 래퍼 |
4. 플러그인 설치와 openclaw.extensions 계약
로더는 openclaw.extensions 맵을 전제로 합니다. 없으면 npm은 성공해도 “핸들러 없음”에 가깝게 조용합니다. 키와 메이저를 맞추고 경로·semver·절 체크섬을 이슈에 붙이세요.
패치는 조직 얇은 래퍼로 선언만 보강하고, prod node_modules 직수정은 피합니다.
# 추측 없이 배포 매니페스트 확인
jq '.openclaw.extensions // "MISSING"' node_modules/<pkg>/package.json5. 장문맥락 티어와 실행 가능한 429 완화
버스트 과금·장문맥 SKU는 첫 신호가 UI 사과가 아니라 Retry-After 달린 429인 경우가 많습니다. 턴당 토큰 로그, 병렬 도구 제한, 스테이징／프로드 키 분리, 재생 전 첨부 정리, 장문맥 모델 ID와 구매 자격 라우팅 일치를 확인하세요.
긴 맥락은 꼬리 지연을 키웁니다. 백오프는 사용자에게 스로틀 가시화와 함께 둡니다.
6. 롤백 서술을 지키는 일곱 단계
- 동결: CLI／GW／이미지 버전 기록.
- probe: 실패 시 stderr 전체＋시간.
- status: 공개 URL·토큰 유무 등.
- doctor: 어댑터 전 구조 수정.
- channels: 면／ID 기록.
- extensions: 선언·semver 감사.
- 마지막: 페어／리버스 프록시／원격 덮어쓰기.
2~4단계에서 두 바이너리 타임스탬프가 갈리면 분열 지표로 돌아가 유령 RPC를 막습니다.
7. 매번 기록할 숫자
주간 probe 지연 pctl、doctor 경고、키／model／WS별 429、설치 대 탐색 성공 간극을 고정 기록해 용량·패키징을 수치화합니다.
8. FAQ와 경계
질문: probe vs 헬스, CI doctor는? 답: 헬스는 인증 RPC를 빼는 경우가 많고 probe는 CLI 실경로입니다. golden에서 doctor 퇴보 시 릴리스를 멈추세요.
질문: 구형 플러그인·하드 업그레이드는? 답: 2026 마이너는 검증이 강해집니다. 하드는 동시 여유에만 간접적이며 할당량은 남습니다.
9. 호스팅 원격 Mac이 래더를 날카롭게 하는 순간
래더는 증거화하지만 절전·VPN·어수선한 HOME은 노이즈입니다. 대화형과 launchd 주체가 갈리면 분열이 재발합니다.
SFTPMAC 렌탈 Mac은 상시 GW 운용에 재현성을 올립니다. 할당량·매니페스트 의무는 동일합니다. SSH 주체·토큰 로테·산출물 인수인계를 함께 보세요.
상행과 Mac 도구를 가깝게 두려면 SFTPMAC 원격 Mac 렌탈을 참고하세요.