Codex Provider 修复 · Codex Provider Repair
Codex 给每条 thread 持久化一个 provider id,但不同入口读到的 provider 集合不一样:
桌面 App 和普通 CLI 只读 config.toml,Yoda 这类集成会在启动时用 -c 参数注入
provider。两边不一致时,打开或 resume 这条 thread 就会报
failed to load configuration: Model provider ... not found,界面上表现为「打不开」。
本 Skill 先取证,再在带备份的前提下把两边对齐。
Triggers
Activate when
- 用户说“codex 打不开”“这条会话恢复不了”“thread can't resume”,或贴出
Model provider ... not found、failed to load configuration、invalid_config。 - 用户在桌面 App 里打开某条会话失败,但同一台机器上其他会话正常。
- Use when the Codex desktop app cannot open or resume a conversation and the machine has several persisted providers.
- 需要盘点本机有哪些 thread 的 provider 已经不存在,再决定补定义还是重打标签。
Do not activate when
- 用户要读某条 thread 的进度或结果;交给
lov-read-codex-session。 - 用户要打开一条已知正常的 thread;交给
lov-open-codex-session。 - 报错是
No tool output found for tool call;交给lov-fix-deepseek-tool-call-error。 - 要修的是 Codex 或 Yoda 的产品代码缺陷;走常规工程修复流程。
Outputs
- 只读诊断报告:活跃 provider、已定义 provider、按 provider 分组的 thread 数量、 桌面 App 日志里的 resume 失败次数、rollout 与索引不一致样本。
- 修复方案与可直接执行的命令;默认先打印计划,只有显式确认才写入。
- 修复后的回读结果与备份路径,可随时回滚。
Workflow (MANDATORY)
Step 0: Resolve skill root and dependencies
- 优先使用
SKILL_DIR;否则按当前 Skill 上下文推断安装目录。 - 确认
scripts/codex_provider_doctor.py存在;缺失时先报出期望路径,不产出半成品。 - 默认只读。
--fix-retag与--restore是仅有的两个写入模式,且都必须带--yes。
Step 1: Collect evidence (read-only)
python3 "$SKILL_DIR/scripts/codex_provider_doctor.py"
- 数据源:
~/.codex/config.toml、~/.codex/state_5.sqlite的threads表、~/.codex/logs_2.sqlite,以及桌面 App 日志~/Library/Logs/com.openai.codex。 --json输出结构化报告;--logs-days N控制日志回看窗口;--sample-rollouts N控制 rollout 抽样条数。- 大机器上全量扫描只需要几秒;报告不打印任何密钥值,只标记是否存在内联凭据。
Step 2: Classify the failure
- A. 启动即失败:
config.toml里model_provider = "x",但没有[model_providers.x]。任何入口都起不来,先补定义。 - B. 历史 provider 缺失:thread 索引里存在配置中没有的 provider,桌面 App
thread/resume返回-32600 invalid_config,这就是「会话打不开」。 - C. rollout 与索引不一致:
threads.model_provider和 rollout 首行session_meta.payload.model_provider不同。两处都要修,否则修完仍会被旧值覆盖。
Step 3: Choose the repair branch
- 仍在使用的共享 provider 桶(如
yoda、custom)→ 补定义:这些 id 由集成方 刻意保持稳定,重打标签会让对方的历史视图对不上。用--print-provider-snippet <id> --like <existing>生成[model_providers.<id>]片段,粘贴进~/.codex/config.toml,然后完全退出并重启桌面 App。 片段默认给env_key形式;GUI 启动的 App 读不到 shell 环境变量时,改用与现有 provider 相同的内联凭据写法。 - 已退役 provider(如
lovbrowser、nebula、xxx)→ 重打标签:把历史 thread 指到当前可用 provider。
python3 "$SKILL_DIR/scripts/codex_provider_doctor.py" \
--fix-retag custom --only-provider lovbrowser
- provider 是否仍在使用不确定时,先按共享桶处理(补定义),或先跑一次 dry-run 看影响范围。
Step 4: Apply the repair
- 先完全退出 Codex 桌面 App。脚本检测到 App 或 app-server 守护进程在运行时会拒绝
写入;确认无风险时才用
--force。 - 重打标签命令加
--yes才真正执行;不加时只打印计划:
python3 "$SKILL_DIR/scripts/codex_provider_doctor.py" \
--fix-retag custom --only-provider xxx --yes
- 写入前自动备份到
~/.codex/provider-repair-backups/<timestamp>/:索引库的完整 副本,加上每个被改写 rollout 的首行原文。回滚:
python3 "$SKILL_DIR/scripts/codex_provider_doctor.py" \
--restore ~/.codex/provider-repair-backups/<timestamp> --yes
- rollout 文件很大时可先只改索引(
--skip-rollouts),但要在结果里说明 rollout session_meta 尚未同步;默认两者都改。 - 本 Skill 不自动修改
config.toml。补定义是人工粘贴步骤,避免覆盖用户的切换器配置。
Step 5: Verify and report
- 复跑
scripts/codex_provider_doctor.py,确认目标 provider 从缺失列表消失,--sample-rollouts抽样不再出现索引与 rollout 不一致。 - 让用户在重新启动的桌面 App 里打开目标会话;CLI 用
codex resume <thread-id>验证能进入会话。 - 报告必须区分:已取证 / 已修复 / 已回读 / 仍待用户确认,并给出版本边界 (本机验证基于 codex-cli 0.153.4 与 Codex Desktop 26.903.71938)。
References
references/mechanism.md:provider 解析链路、失败形态与真实证据。references/repair.md:补定义与重打标签的详细步骤、备份与回滚、验证清单。references/skill-composition.md:与相邻 Skills 的边界与交接。
Dependencies
- Python 3.8+ 标准库;可选 PyYAML 仅用于
scripts/validate_skill.py。 - 读取本地 Codex 目录与桌面 App 日志的权限;无网络、无凭据。
- 相邻能力(可选,不构成硬依赖):
lov-read-codex-session读 thread 状态,lov-open-codex-session打开会话,lov-fix-deepseek-tool-call-error处理工具 调用类故障。
