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，按天租用能压缩现金流到本轮验证；需要套餐对比时打开套餐价格页。