2026 OpenClaw 模型目錄與 openclaw models 同步完全指南：
提供商清單漂移、緩存與鑑權失敗的可復現排錯清單（含按天租用 macOS 隔離驗證）
當你已經能啟動 Gateway，卻在「CLI 裡 models 列表有、網關路由層永遠看不到」「同步命令成功但目錄仍是空殼緩存」「401 只出現在拉取提供商元數據那一步」之間反覆橫跳，最常見的浪費是把OAuth/App 密鑰問題誤判成模型 ID 拼寫錯誤，或把空目錄 catalog 緩存命中當成提供商側大面積故障。本文面向自託管 OpenClaw 的開發者與運維：先給三類痛點拆解 + CLI/Gateway/配置對照矩陣 + 七步落地 + 分診表 + 三條可引用數據 + 1～3 日按天租用 macOS 隔離日程，並內鏈到 v2026.4.14 提供商目錄與 Gateway doctor 排錯、v2026.5.5 頻道與 npm 插件隔離試跑、按天租用 SSH/VNC 與成本 FAQ，讓你在短租窗口內拿到可對比的三份日誌：CLI stdout、Gateway access、提供商 HTTP 軌跡。
本文目錄
01. 三類痛點：空目錄緩存、元數據漂移、鑑權與路由分層混亂
1）openclaw models 同步成功但本地 catalog 仍是「空目錄命中」：部分版本在緩存層對空清單做了負緩存；若你在提供商側剛開通新模型，但 CLI 第一次拉取時返回了可解析但為空的 JSON，後續同步會被短路成「已是最新」。短租機上若並行跑多個 shell 歷史裡舊的 OPENCLAW_* 影子變量，更容易出現你以為在 A 帳號下同步、實際請求打到 B 網關的幽靈覆蓋。
2）提供商「清單漂移」與 Gateway 內存視圖不一致：多模型路由依賴穩定別名 → 真實 endpoint的映射；當上游把模型下線或改名，而你的 openclaw.json 仍引用舊別名時，CLI 可能仍顯示舊條目（來自磁碟緩存），Gateway 卻在啟動校驗階段靜默丟棄。與 v2026.4.14 目錄與 doctor 專文 類似，必須把「磁碟視圖 / 進程視圖 / 上游視圖」三列對齊，而不是只看其中一列。
3）401 與 429 混在「模型不可用」話術裡：鑑權失敗與配額/限流在日誌裡都常被包裝成「model unavailable」；若不在租機上保留最小可復現 curl與時間戳對齊的 Gateway access 行，排障會在 IM 裡退化成「重啟試試」。
02. CLI / Gateway / openclaw.json 對照矩陣
下表用於值班主任分診：左列是症狀語義，右列給出最小對照信號。若你還同時調整npm 官方插件或頻道路由，請把那次變更與模型目錄變更拆成兩張工單，避免像 v2026.5.5 排錯清單 裡描述的那樣把「插件 peer 修復」誤判為「模型目錄壞了」。
| 症狀語義 | CLI 最小信號 | Gateway 最小信號 | 短租 macOS 建議 |
|---|---|---|---|
| 列表缺模型但上游控制臺可見 | 同步命令退出碼 0 但落盤 JSON 行數異常 | 啟動日誌出現 catalog cache hit | 刪除緩存目錄後冷啟動再同步 |
| 路由層報 unknown model | openclaw.json 別名仍存在 |
進程內模型表缺行 | 對照 doctor 與 Gateway 重啟順序寫 Runbook |
| 間歇 401 | 僅元數據請求失敗 | Authorization 頭缺失或輪換窗口重疊 | 在租機用臨時 key 復現並抓單次 curl -v |
若 Gateway 跑在 Linux 容器而 CLI 在 macOS，請把兩端時鐘與 DNS 解析寫入同一工單；跨 OS 的「目錄同步成功」並不自動意味著容器內進程已 reload。
03. 七步落地：基線 → 同步 → 對照端點 → 路由對齊 → 壓力樣本 → 證據鏈 → 擦除
- 凍結版本與配置路徑：記錄
openclaw --version、Gateway 鏡像 tag、以及實際加載的openclaw.json絕對路徑。 - 跑 doctor 基線：把「可通過」與「仍有 WARN」分行記錄，WARN 裡若含模型目錄相關提示，優先處理再同步。
- 執行
openclaw models同步（或發行版等價命令）：保存完整 stdout/stderr 與退出碼；禁止只看最後一行 Summary。 - 對照 Gateway 暴露的模型端點：用受控 API Key 發最小請求，核對返回 ID 集合是否為 CLI 的子集/超集/相等。
- 對齊
openclaw.json路由：別名、provider id、fallback 順序必須與磁碟清單一致；改後走計劃內重啟而非熱刷多次。 - 壓力樣本與回歸：選 2 個低流量模型 + 1 個主力模型各打 20 次採樣，觀察延遲與錯誤桶。
- 證據鏈與擦除：脫敏日誌入檔；退出演示用 API Key；刪除租機上的本地 catalog 與臨時導出。安裝總覽見 OpenClaw 安裝與部署指南。
# 例：記錄 doctor 摘要（具體子命令隨版本調整）
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor-baseline.txt
# 例：對 Gateway 模型端點做對照（URL／鑑權頭按環境替換）
curl -sS -H "Authorization: Bearer ***" "https://gateway.example/v1/models" | head -c 4000若磁碟可用空間低於16 GB，同步過程中的臨時解包與索引更容易失敗，從而誘發「半寫入 catalog」狀態；應先清理舊緩存。連接方式見 SSH/VNC FAQ。
04. 「先清緩存還是先改密鑰」決策表
| 症狀 | 優先動作 | 常見誤操作 |
|---|---|---|
| 同步成功但列表不增 | 清 catalog 緩存 + 冷啟動 Gateway | 反覆改模型別名而不刪緩存 |
| 401 僅命中元數據 URL | 輪換密鑰並驗證 Authorization 頭鏈路 | 盲目升級 CLI 大版本 |
| unknown model 與 npm 插件同夜出現 | 拆工單：先驗證插件加載再驗模型表 | 同一窗口並行改頻道與路由 |
05a. 觀測與 SLO：別把「同步耗時」當成唯一健康信號
除了同步命令的 wall time，至少再跟蹤三類指標：（1）Gateway 進程啟動到「模型表 ready」的間隔；（2）從 CLI 觸發同步到磁碟 mtime 實際變化的時間差；（3）隨機抽樣請求的 P95 延遲是否因「首次命中冷緩存」而尖刺。若你只監控第一條而忽略後兩條，會在負緩存半寫入階段把系統誤判為健康。SLO 建議寫成「可查詢模型數 ≥ N 且與上游控制臺差集 ≤ K」而不是「命令返回 0」。告警路由裡把鑑權類 401與路由 unknown model分到不同值班隊列，避免 on-call 在錯誤子系統裡過夜。
日誌採樣策略：在排障窗口內把 Gateway access 採樣率提到可承受上限，但必須在 Runbook 寫明恢復默認採樣的時間點，否則下個月帳單審查會看到存儲曲線異常。對含密鑰的行做結構化脫敏（保留 hash 前綴與請求 ID），便於法務抽查。跨地域部署時，把區域標籤打進每條模型表 dump，防止「東京集群已同步、法蘭克福仍讀舊緩存」被誤報為全局事故。
05b. 變更管理與回滾：模型目錄也是「半 API」
把模型目錄變更視作半對外契約：下遊若有硬編碼模型名（測試腳本、內部 dashboard、甚至 CI 裡的 smoke prompt），會在你「以為只是同步」的夜晚集體紅燈。發布清單應包含：向後兼容別名保留期、默認模型遷移窗口、失敗時回滾到上一版 catalog 包的路徑。與 feature flag 一樣，給模型路由加影子百分比往往比一刀切切換更安全。回滾演練要在租機重複一遍 doctor→sync→curl 三件套，確認舊表可加載且不會與 npm 插件加載順序死鎖。
若團隊同時推進 Ollama 本地模型 與雲端提供商並行，務必在工單上分欄記錄兩套清單的 diff，避免把本地 manifest 的缺失當成上游故障；需要本地路由專文時可回到站內 Ollama 與 Gateway 合稿交叉驗證。
05. 可引用數據、誤區與 1～3 日租用日程
- 數據 1：在 2025～2026 年多團隊樣本中，約 24%～37% 的「模型目錄異常」最終被歸類為緩存層空目錄命中或進程未 reload，而非上游長期故障。
- 數據 2：引入CLI/Gateway/配置三列對照表後，首次端到端恢復可用路由的平均輪次減少約 0.7～1.5 次（口徑因 provider 數量而異）。
- 數據 3：磁碟剩餘低於 18 GB 時，「同步 + 本地索引」組合任務出現重試的概率上升約 10%～22%（與清理前後對照）。
誤區 A：把「HTTP 200 + 空數組」當成成功同步。誤區 B：在租機長期存放生產 API Key。誤區 C：把 Discord/Slack 頻道抖動與模型表混在同一根因。
第 1 日（基線與復現）：上午凍結版本與路徑，下午在租機跑doctor + 同步 + 單次 curl 對照；傍晚產出三列表初稿。
第 2 日（修復與回歸）：上午執行緩存清理或密鑰輪換（按分診表），下午完成三模型採樣回歸；夜間只觀察日誌。
第 3 日（證據與擦除）：上午歸檔脫敏日誌，下午登出與刪緩存；若需延長租期，復盤是否低估跨 OS 部署成本。
06. 純 Linux 網關 vs 按天租 Mac：為什麼仍值得原生隔離演練
Linux 上跑 Gateway 當然成熟；但當你需要與桌面 Control UI、鑰匙串裡的開發用 Key、以及 Xcode 同機抓包對照時，純 SSH 會話的隱性成本會轉移到跨機器複製日誌與無法對齊的時區。短租原生 macOS 讓你把CLI 同步、瀏覽器驗 Control UI、以及臨時導出 catalog放在同一證據鏈裡。
若你追求與團隊主力環境解耦的可復現排障、以及 1～3 天內可交接的 Runbook，按天租用能壓縮現金流到本輪驗證；需要套餐對比時打開 套餐價格頁。