2026 OpenClaw モデルカタログと openclaw models 同期：
プロバイダー目録ドリフト、キャッシュ、認証失敗の切り分け（日貸し macOS 隔離）
Gateway は起動するのにルーティング層だけがモデルを見えない、同期は exit 0 だがカタログディレクトリが負キャッシュの墓標のまま、401 はプロバイダーのメタデータ取得にだけ付く——ここで OAuth の漂いを モデル ID の typoと取り違えると、オンコールの時間が一気に溶けます。本稿は セルフホスト運用者向けに、三つの痛みの塊、CLI／Gateway／設定の対照表、整列した七手順、キャッシュ対鍵のトリアージ表、三つの指標、1～3 日の日貸し macOS リハーサルを束ね、v2026.4.14 プロバイダーカタログ＋ doctor、v2026.5.5 チャネル／npm 隔離、SSH/VNC FAQ へ戻れるようにします。
01. 三つの痛みの塊
1) 同期成功だがローカル catalog が空ヒットのまま：一部ビルドは 空のプロバイダー応答を負キャッシュします。新モデルを有効化した直後の初回取得が HTTP 200 の空配列だと、その後の同期は「最新」と短絡されます。日貸しホストで複数シェルに古い OPENCLAW_* が残ると、「アカウント A で同期したつもりが Gateway B に当たる」幽霊が増えます。
2) プロバイダー側の目録ドリフトと Gateway プロセス内ビューのズレ：エイリアスは安定している必要があります。上流がモデル名を廃止したのに openclaw.json が旧名を指すと、CLI はディスクキャッシュ由来で古い行を見せ、起動検証では行が静かに落ちます。v2026.4.14 の三方向（ディスク／プロセス／上流）を踏んでください。
3) 401 と 429 が「model unavailable」に潰れる：タイムスタンプ付きの curl -v と Gateway access をペアにしないと、オンコールは「Gateway 再起動」に退化します。
02. 対照マトリクス
npm 公式プラグインやチャネルルーティングを同じ夜に触るなら、v2026.5.5 の教訓どおり チケットを分割し、peer 修復とモデル表を混同しないでください。
| 症状 | CLI | Gateway | 日貸し macOS |
|---|---|---|---|
| コンソールにはあるが一覧に無い | exit 0 だが JSON 行数が妙 | catalog cache hit | キャッシュ削除→コールド再起動→再同期 |
| ルータで unknown model | json に別名が残存 | プロセス内テーブル欠行 | doctor と再起動順を Runbook 化 |
| 間欠 401 | メタデータ URL のみ | Authorization 欠落／期限切れ | 一時キーで単発トレース |
Gateway が Linux コンテナ、CLI が macOS なら、時刻ずれと DNSを同一チケットに書きます。「ディスク同期 OK」は コンテナ内プロセスの reloadを意味しません。
03. 七手順
- 版とパスを凍結：
openclaw --version、イメージ tag、実際に読み込まれた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. トリアージ：キャッシュか鍵か
| 症状 | 先にやること | やりがちな誤り |
|---|---|---|
| 同期成功だが一覧が増えない | catalog キャッシュ削除＋コールド再起動 | 別名だけ弄り続ける |
| 401 がメタデータのみ | 鍵ローテと Authorization チェーン | CLI メジャーを盲信アップグレード |
| unknown model と npm が同夜 | チケット分割（プラグイン→モデル表） | チャネルとルートを並列編集 |
05a. 観測と SLO
同期の wall time だけを健康指標にしないでください。Gateway 起動から「モデル表 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 で Gateway を回すのは定石です。ただし Control UI、開発用 Keychain、同じマシンでの tcpdump を短い証拠ウィンドウで揃えたいとき、SSH だけの二段構成はログ転送とタイムゾーンのズレでコストが乗ります。ネイティブ macOS の日貸しは、CLI 同期・ブラウザでの Control UI 確認・一時的な catalog エクスポートを一本の証拠線に束ねられます。帯域と枠取りは Mac mini M4 価格ガイド と FAQ を併読してください。
運用メモ：複数エンジニアが同一日貸しホストを触る場合、UTC とビルド tag を名前に含む 追記専用の証拠フォルダ を強制し、Slack 添付の上書き事故を防ぎます。CI のヘッドレス同期ジョブは環境ファイルを pin し、個人用 API 鍵の再利用を禁止します。
境界：ホスティング推論ベンダーが JWT issuer URL を無言で回した場合、JWKS キャッシュ TTL が切れるまで Gateway が誤った issuer を信じることがあります。メタデータ SLA と合成プローブを Runbook に書き、ドリフトを大声で失敗させます。
容量：チーム実験が増えるとカタログは超線形に肥大化します。リリースごとの tarball 保持と解凍作業域を見積もり、小さなクラウド Mac の egress 上限で巨大 catalog が詰まったときはオフピークに同期し、スループット数値をチケットに残します。
セキュリティ：本番隣接ホストで同期コマンドを実行できる人を絞り、新しい実行可能定義を引き込む権限として監査ログに残します。openclaw.json の Git 差分と突き合わせてエンドツーエンドの追跡可能性を確保してください。
時計：date -u を CLI ホストと Gateway ホストの両方で同一チケットに貼り、2 秒を超える skew が JWT 検証を壊す典型例を潰します。キャッシュリセット・鍵更新・Gateway 再起動のコマンドを短い Runbook スニペットにまとめ、初動の即興を減らします。