OpenClaw openclaw models 동기화 카탈로그 캐시 Gateway 인증 일일 Mac 20260511

01. 세 가지 통증 묶음

1) 동기화 성공인데 로컬 catalog 가 빈 히트: 일부 빌드는 빈 프로바이더 응답을 네거티브 캐시합니다. 신규 모델 직후 첫 응답이 HTTP 200 빈 배열이면 이후 동기는 “최신”으로 단락됩니다. 렌탈 머신에서 여러 셸에 남은 OPENCLAW_* 때문에 “A 계정으로 동기했는데 B 게이트웨이로 간다”는 유령이 생깁니다.

2) 프로바이더 목록 드리프트와 게이트웨이 메모리 뷰: 별칭은 안정적이어야 합니다. 상류가 이름을 없앴는데 openclaw.json 이 옛 이름을 가리키면 CLI 는 디스크 캐시로 남은 행을 보여 주고 시작 검증에서는 행이 조용히 빠집니다. v2026.4.14 의 디스크·프로세스·상류 삼분 대조를 반복하세요.

3) 401 과 429 가 “model unavailable” 로 뭉개짐: 타임스탬프가 맞는 curl -v 와 Gateway access 줄을 짝지 않으면 온콜은 “재시작”으로 퇴화합니다.

02. 대조 매트릭스

같은 밤에 npm 공식 플러그인이나 채널 라우팅을 만지면 v2026.5.5 처럼 티켓을 쪼개 peer 수정과 모델 표를 섞지 마세요.

증상	CLI	Gateway	일일 macOS
콘솔엔 있는데 목록엔 없음	exit 0 이지만 JSON 행수 이상	catalog cache hit	캐시 삭제→콜드 재시작→재동기
라우터 unknown model	json 별칭 잔존	프로세스 테이블 결행	doctor·재시작 순서 Runbook
간헐 401	메타데이터만	Authorization 누락·만료	임시 키로 단일 트레이스

게이트웨이가 Linux 컨테이너이고 CLI 가 macOS 이면 시각·DNS 를 한 티켓에 적습니다. “디스크 동기 OK” 가 컨테이너 reload 를 뜻하지 않습니다.

03. 일곱 단계

버전·경로 고정:openclaw --version, 이미지 태그, 실제 로드된 openclaw.json 절대 경로.
doctor 베이스라인:PASS/WARN 줄을 나눕니다.
openclaw models 동기:stdout/stderr·종료 코드를 tee.
Gateway 모델 엔드포인트 프로브:ID 집합이 CLI 와 어떤 관계인지 기록.
openclaw.json 정렬:계획된 재시작, 뜨거운 리로드 남발 금지.
샘플링:저트래픽 2 + 주력 1, 각 20회.
증거·삭제:로그 마스킹, 데모 키 폐기, 렌탈 catalog 삭제. 설치 개요는 설치·배포 가이드.

openclaw doctor 2>&1 | tee /tmp/openclaw-doctor-baseline.txt
curl -sS -H "Authorization: Bearer ***" "https://gateway.example/v1/models" | head -c 4000

남은 용량이 16 GB 미만이면 압축 해제·색인이 흔들려 “반쯤 쓴 catalog” 가 나오기 쉽습니다. 먼저 정리하세요. 연결은 FAQ.

04. 트리아지

증상	우선	흔한 실수
동기 OK 인데 목록 정체	catalog 캐시 제거·콜드 GW	별칭만 반복 수정
401 이 메타데이터만	키 로테·Authorization 체인	CLI 메이저 맹목 업그레이드
unknown model + npm 동야	티켓 분리	채널·라우트 병렬 편집

05a. 관측·SLO

동기 wall time 만 건강 신호로 쓰지 마세요. 게이트웨이 기동부터 “모델 표 ready” 까지, CLI 동기 완료와 catalog mtime 차이, 첫 콜드 캐시 P95 를 묶어 봅니다. SLO 는 “exit 0” 이 아니라 “조회 가능 모델 ≥ N 이고 콘솔 대칭 차이 ≤ K” 형태가 낫습니다. 401 과 unknown model 은 다른 로테로 보냅니다. 샘플링만 일시 상향할 때는 기본값 복귀 시각을 Runbook 에 적어 스토리지 감사에서 설명 가능하게 합니다.

05b. 변경 관리

모델 카탈로그 변경은 반쯤 공개 API 입니다. 테스트·대시보드가 모델명을 하드코딩하면 “동기만 했다”는 밤에 동시에 붉어집니다. 호환 별칭 잔존 기간, 기본 모델 이전 창, 실패 시 이전 tarball 경로를 체크리스트에 넣으세요. 섀도 퍼센트가 전면 전환이 더 안전한 경우가 많습니다. 렌탈 머신에서 doctor→sync→curl 삼종 세트로 롤백 리허설을 반복하고 npm 로드 순서와 교착이 없는지 확인합니다.

05. 지표·일정

지표 1:다팀 샘플에서 “카탈로그 이상”의 약 24~37% 가 최종적으로 네거티브 캐시 또는 reload 누락으로 분류.
지표 2:삼열 매트릭스 도입 후 첫 정상 라우팅 복구까지 왕복이 약 0.7~1.5회 감소.
지표 3:여유가 18 GB 미만이면 동기+색인 재시도 확률이 정리 전후 비교로 약 10~22% 상승하기 쉬움.

1일차:고정·doctor·동기·단일 curl.2일차:트리아지에 따라 캐시 또는 키, 세 모델 샘플링.3일차:마스킹 로그 보관·렌탈에서 키·캐시 삭제.

06. Linux 만으로 되는가, 왜 일일 macOS 인가

Linux 게이트웨이는 성숙한 패턴입니다. 다만 Control UI·개발용 키체인·동일 호스트 tcpdump 를 짧은 증거 창에 맞추려면 SSH 이단만으로는 로그 복사와 타임존 비용이 붙습니다. 네이티브 macOS 일일 렌탈은 CLI 동기·브라우저 UI 확인·임시 catalog 덤프를 한 증거선에 묶습니다. 대역·요금제는 가격 가이드 와 FAQ 를 함께 보세요.

운영 메모: 여러 엔지니어가 같은 렌탈 호스트를 쓰면 UTC·빌드 태그가 이름에 든 append 전용 증거 폴더 를 강제해 Slack 첨부 덮어쓰기를 막습니다. CI 헤드리스 동기 잡은 환경 파일을 pin 하고 개인 API 키 재사용을 금지합니다.

경계: 호스팅 추론 벤더가 JWT issuer URL 을 조용히 바꾸면 JWKS TTL 이 끝날 때까지 게이트웨이가 잘못된 issuer 를 신뢰할 수 있습니다. 메타데이터 SLA·합성 프로브를 Runbook 에 적습니다.

용량: 팀 실험이 늘면 카탈로그는 초선형으로 비대해집니다. 릴리스별 tarball 보존과 작업 공간을 예산하고 작은 클라우드 Mac 의 egress 한도에서 거대 catalog 가 막히면 오프피크에 동기하며 처리량 숫자를 티켓에 남깁니다.

보안: 프로덕션 인접 호스트에서 동기 명령을 누가 실행할 수 있는지 제한하고, 새 실행 가능 정의를 끌어오는 권한으로 감사 로그에 남깁니다. openclaw.json Git 차이와 짝을 맞춥니다.

시계: CLI 호스트와 게이트웨이 호스트 모두에서 date -u 를 같은 티켓에 붙여 2초를 넘는 skew 가 JWT 를 깨는 전형을 없앱니다. 캐시 리셋·키 갱신·게이트웨이 재시작 명령을 짧은 Runbook 스니펫으로 모아 초동 즉흥을 줄입니다.

2026 OpenClaw 모델 카탈로그와 `openclaw models` 동기화:
프로바이더 목록 드리프트·캐시·인증 실패 분리(일일 macOS 격리)

목차