---

name: lov-fix-codex-provider description: > 修复 Codex 打不开：把 thread 里持久化的 provider（yoda、custom 等）与 config.toml 实际定义对齐，先只读取证，再带备份重打标签。Use when Codex cannot open or resume a thread with Model provider not found. license: MIT compatibility: "Portable Agent Skills format. Python 3.8+ standard library; reads local Codex config, SQLite state and desktop logs; no network and no credentials." metadata: author: skill-publisher version: "0.1.0" card_standard: lovstudio/skill-card/v1 content_class: deterministic-output tags: - codex - provider - recovery - diagnostics

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 处理工具 调用类故障。