Codex Catalog Builder (codex-catalog)

便捷、健壮的 OpenAI Codex 自定义模型目录交互式构建工具（TUI）。

用于一键从第三方代理/反代 API 获取可用模型列表，克隆官方最新旗舰模型模板，交互式配置上下文窗口（Context Window）与排除规则，并安全原子写入 ~/.codex/custom_catalog.json。

• 🏛️ 两级内置模型同步（官方模型安全保障）

  • 一级在线源：自动从 GitHub 官方源（openai/codex 仓库）同步最新官方内置模型定义。
  • 二级本地缓存：网络受限或离线时，自动读取 ~/.codex/models_cache.json 兜底补全。
  • 生成目录时完整保留所有官方内置模型原有配置，绝不覆盖或丢失官方模型。

• 🎯 基准模板智能评估与交互式克隆

  • 启动时按「公开发布状态 > 主次代际版本 (如 v6.0 > v5.6 > v5.5 > v5.4) > 官方优先级 > 上下文窗口」智能推荐最佳克隆基准。
  • 支持键盘上下键 [↑/↓] 交互式选择克隆基准（默认高亮官方首推主力模型，直接回车即可确认）。
  • 模板深度安全清洗：自动抹除基准模型特有的退役迁移标记（upgrade）、新手提示（availability_nux）、编译哈希（comp_hash）等，确保派生出的自定义模型健康可用。

• 🔄 代理模型自动获取与去重

  • 自动解析 ~/.codex/config.toml 中当前激活的 model_provider 配置（读取 base_url 与 experimental_bearer_token）。
  • 请求代理 /models 端点拉取全部可用模型，并自动过滤已在官方内置库中的同名模型（官方定义自动保留）。

• 💡 配置状态回显与增量维护（幂等性）

  • 启动时自动读取已有 ~/.codex/custom_catalog.json。
  • 自动回显之前已配置的自定义 Context（标记 [x]）与已排除模型（标记 [-]），二次配置或增量更新模型时无需重复设置。

• ⌨️ 全键盘友好 TUI 交互

  • 编辑模式（光标实时操控）：
    • [↑/↓] 移动光标
    • [空格] 切换自定义 Context 标记 [x]
    • [e] 切换单项排除/恢复标记 [-]（排除的模型不会写入文件）
    • [a] 全选自定义 / 全选取消
    • [x] 全选排除 / 全选恢复
    • [Enter] 确认并逐步输入自定义 Context
    • [ESC] 放弃当前修改并还原
  • 主菜单模式：支持按键快速切换编辑模式、范围序号批量选中（如 1, 3, 5-8 或 10~12）、批量排除、批量恢复及一键应用退出。

• 🔢 智能 Priority 顺延与上下文同步

  • 动态计算官方内置模型中的最大 Priority，自定义模型按顺序在其后分配递增 Priority，避免破坏官方内置模型的优先展示。
  • 自动同步更新 context_window 与 max_context_window。

• 🛡️ 原子安全落盘（Atomic Save）

  • 写入临时文件并通过底层 fsync 强制刷盘后执行原子替换，杜绝断电或强退导致配置文件损坏或变空。

1. Python 环境：Python >= 3.13，推荐使用 uv 进行包与环境管理。
2. Codex 配置：确保本机已安装并初始化 Codex，并在 ~/.codex/config.toml 中配置了有效的代理 Provider。

示例 ~/.codex/config.toml 配置：

model_provider = "my_proxy"

[model_providers.my_proxy]
base_url = "https://api.your-proxy-domain.com/v1"
experimental_bearer_token = "sk-xxxxxxxxxxxxxxxxxxxxxxxx"

使用 uv 无需手动创建虚拟环境，直接运行主程序：

uv run codex_catalog_builder.py

也可以通过项目安装的全局命令别名运行：

uv run codex-catalog

无需在全局环境预装 PyInstaller，直接通过 uv --with 运行打包命令：

uv run --with pyinstaller pyinstaller -F -n codex-catalog codex_catalog_builder.py

打包完成后，可执行程序将生成在 dist/ 目录下：

• Windows: dist/codex-catalog.exe

生成后可将 codex-catalog.exe 复制到系统的 PATH 目录（或任意便捷位置），直接在终端中随时调用。

运行程序后，将经历以下三个主要阶段：

[1. 同步官方模型] ──> [2. 选择基准模板] ──> [3. TUI 模型管理主界面] ──> [4. 保存并退出]
 (GitHub / 缓存)     (↑/↓ 选择, Enter 确认)    (编辑/选中/排除/修改 Context)   (写入 custom_catalog.json)

程序启动时会自动请求 GitHub 官方仓库获取最新的内置模型定义；若网络连接超时或失败，会自动回退读取本机的 ~/.codex/models_cache.json 缓存。

程序会展示当前活跃且健康的官方旗舰模型候选列表（按版本、可见性及官方推荐优先级排序）。

• 使用 [↑/↓] 移动光标选择。
• 默认已高亮官方首选推荐模型，直接按下 [Enter] 即可确认。

进入主界面后，将显示代理返回的自定义模型列表。每行前的状态标记含义：

• [ ] 默认包含：写入文件，使用基准模板的默认 Context Window（如 272,000 tokens）。
• [x] 自定义：写入文件，使用用户单独指定的 Context Window。
• [-] 已排除：不写入 custom_catalog.json。

当提示输入 Context Window 时，支持多种常用写法：

• 带单位缩写：如 128k、200k、1m（不区分大小写，自动按 1,000 / 1,000,000 换算）
• 纯数字：如 131072、200000
• 直接回车：保持当前显示的数值不变
• 按 ESC：随时取消本次配置流程并安全回退

Q: 运行后提示 未找到 Codex 配置文件 或 缺少 base_url 字段？
A: 请确认本机已启动过 Codex 并完成了基础配置。请检查 ~/.codex/config.toml 中是否正确配置了 model_provider 以及对应的 [model_providers.<name>] 段。

Q: GitHub 在线同步官方模型提示超时怎么办？
A: 程序内置了自动回退机制。只要您此前正常使用过 Codex，本机即会存在 ~/.codex/models_cache.json 缓存，程序会自动读取本地缓存中的模型数据，无需担心。

Q: 配置完成后，如何在 Codex 中生效？
A: 保存成功后，直接打开或重启 Codex 客户端/应用，在模型切换下拉列表中即可看到新注入的自定义模型。