Codex 提示 Model metadata not found 怎么处理

这条告警表示什么

Model metadata for `gpt-5.6-sol` not found.
Defaulting to fallback metadata; this can degrade performance and cause issues.

Codex 会用模型元数据判断上下文窗口、支持的推理等级、工具和输出能力。没有匹配项时，它会退回一组通用假设；请求仍可能发出，但长上下文管理、自动压缩、推理等级选择或工具行为可能不准确。

先做三项检查

1. 确认实际运行的 Codex 版本

command -v codex
codex --version

多套 Node、Homebrew 或二进制安装并存时，终端调用的版本可能不是刚更新的那一套。

2. 让 Codex 读取当前有效模型目录

codex debug models \
  | jq -r '.models[] | select(.slug == "gpt-5.6-sol") |
    {slug, context_window, supported_reasoning_levels}'

能返回模型对象，说明当前这套 Codex 已经获得该模型的元数据。没有输出时，先更新 Codex，再重新执行该命令。

3. 核对 CODEX_HOME

printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"

模型目录按 Codex 数据目录保存。不同终端、服务或远程客户端使用不同 CODEX_HOME 时，刷新其中一个目录不会改变另一个目录。

推荐修复顺序

1. 使用原安装方式把 Codex 更新到当前版本。
2. 执行 codex debug models，确认目标模型已经出现在有效目录。
3. 完全退出旧的 Codex 进程，再新建会话。
4. 确认 config.toml 中的模型名与目录中的 slug 完全一致。
5. 最后才检查自定义 Base URL 的 /v1/models 与鉴权是否正常。

什么时候使用手工覆盖

Codex 配置支持 model_context_window 等模型限制覆盖，但只有在你已经从可信模型目录确认精确值时才应使用。

# ~/.codex/config.toml
model = "gpt-5.6-sol"

# 仅在已确认模型精确上下文窗口时填写
# model_context_window = 272000

错误的上下文窗口比通用回退更危险：设置过大可能在压缩前触发上游拒绝，设置过小则会过早压缩。一般情况下，应优先让新版 Codex 自动读取元数据。

如何确认已经恢复

1. codex debug models 能找到目标模型。
2. 新建会话时不再出现 fallback metadata 告警。
3. 用一个短请求确认模型、推理等级和工具调用均正常。
4. 再恢复长上下文任务，不要直接拿旧的超长会话做首次验证。

如果短请求成功但只有旧会话报错，应转向排查会话上下文或压缩；参考 502 与长上下文排查。