CodexTools

中文 | English

CodexTools 是一组面向 Codex Desktop 的配套小工具集合。当前仓库包含两个可独立使用、也可配合使用的子项目：

子项目	中文名称	作用
codex-model-manager	Codex 模型管理器	管理官方/自定义模型目录，并写入 Codex 配置
codex-hidden-models-work	Codex 隐藏模型注入工具	在运行时让 Codex Desktop 模型选择器显示目录中的可见模型

1. 这两个工具分别解决什么问题

1.1 Codex 模型管理器

Codex 会从 config.toml 中的 model_catalog_json 读取模型目录。模型管理器负责：

• 缓存并同步官方模型；
• 新建、编辑、克隆、删除自定义模型；
• 把官方模型与自定义模型合并成 model-catalog.json；
• 把目录文件路径写回 %USERPROFILE%\.codex\config.toml。

适合需要维护自定义模型、代理模型，或批量管理模型目录的场景。

1.2 Codex 隐藏模型注入工具

即使模型已经写进 model_catalog_json，Codex Desktop 的模型选择器仍可能因为内部 use_hidden_models 白名单分支，把一部分本应可见的模型藏起来。

隐藏模型注入工具会在 运行时 通过 CDP 把该字段强制改为 false，让选择器走正确的可见性过滤逻辑。它：

• 不修改 app.asar；
• 不改动磁盘上的任何文件；
• 重启 Codex 后自动恢复原样。

1.3 两者如何配合

典型配合方式：

codex-model-manager
  写入 / 维护 model_catalog_json
            ↓
codex-hidden-models-work
  让 Desktop 模型选择器真正显示这些模型

• 只改模型目录、不关心 Desktop 选择器显示时，可以只用 codex-model-manager。
• 只想让 Desktop 显示出目录里已有但被挡住的模型时，可以只用 codex-hidden-models-work。
• 自定义模型已经写入配置，但 Desktop 里仍然看不到时，通常需要两个工具一起用。

2. 仓库结构

CodexTools\
├─ README.md
├─ README.en.md
├─ codex-model-manager\
│  ├─ codex-model-manager.cmd
│  ├─ codex-model-manager.ps1
│  ├─ codex-model-manager.README.md
│  ├─ codex-model-manager.README.en.md
│  └─ codex-model-manager\
│     ├─ codex-model-manager-backend.ps1
│     ├─ model-catalog.json
│     └─ data\
└─ codex-hidden-models-work\
   ├─ start-codex.ps1
   ├─ hook-use-hidden-models.mjs
   ├─ README.md
   └─ README.en.md

每个子项目都自包含，可单独复制到其他位置使用；移动时请保持该子项目内部相对路径不变。

3. 运行条件总览

两个工具都面向 Windows：

条件	模型管理器	隐藏模型注入工具
Windows 10 / 11	需要	需要
PowerShell 7（pwsh）	需要	需要
Node.js 21+	不需要	需要

更细的依赖与限制见各子项目 README。

4. 快速开始

4.1 管理模型目录

进入 codex-model-manager 目录后：

# 双击启动
.\codex-model-manager.cmd

# 或在 PowerShell 7 中启动
pwsh -NoProfile -File .\codex-model-manager.ps1

第一次使用建议按下面顺序操作：

1. 启动 GUI。
2. 执行“目录 → 初始化数据”。
3. 如需官方模型，确认“设置 → 官方模型源”，再执行初始化或“同步官方模型”。
4. 新建或编辑自定义模型。
5. 执行“目录 → 保存配置”。
6. 完全退出 Codex Desktop。
7. 执行“目录 → 应用到 Codex”。
8. 重新启动 Codex Desktop 或 Codex CLI。

完整说明见：

• 中文 README
• English README

4.2 显示被 Desktop 挡住的模型

进入 codex-hidden-models-work 目录后：

pwsh -NoProfile -File .\start-codex.ps1

脚本会：

1. 以远程调试端口启动 Codex Desktop（默认 9222）；
2. 等待渲染进程就绪；
3. 注入 hook，直到打印 [success] Hidden-models hook installed.。

注入成功后，重新打开 Codex 的模型选择器。完整说明见：

• 中文 README
• English README

4.3 推荐联用流程

如果你要让自定义模型既写入配置，又在 Codex Desktop 里可见，建议按这个顺序：

1. 用 codex-model-manager 维护模型并“应用到 Codex”。
2. 完全退出 Codex Desktop。
3. 用 codex-hidden-models-work 的 start-codex.ps1 重新启动并注入。
4. 打开模型选择器，确认自定义模型已出现。

5. 常见问题

模型已经写入配置，但 Desktop 里看不到

先确认：

1. 已执行“保存配置”和“应用到 Codex”；
2. 已完全退出并重新启动 Codex；
3. 模型可见性不是 hidden。

如果配置无误但选择器仍不显示，再使用 codex-hidden-models-work。

隐藏模型 hook 注入成功，但列表没有变化

重新打开一次模型选择器。如果选择器缓存了旧配置，可在 hook 中使用 --reload。详见子项目 README。

想只使用其中一个工具可以吗

可以。两个子项目互不强制依赖，只是解决同一条模型显示链路上的不同环节。

6. 详细文档

文档	说明
codex-model-manager 中文说明	GUI、数据流、后端命令、故障排查
codex-model-manager English	English version of the model manager
codex-hidden-models-work 中文说明	启动方式、注入原理、限制与排障
codex-hidden-models-work English	English version of the hidden-models hook

7. 说明

• 本仓库中的工具面向个人本地使用与实验场景。
• 隐藏模型注入依赖 Codex Desktop 当前内部实现；Codex 升级后，相关配置 ID 或字段名可能变化。
• 模型管理器会写入本机 %USERPROFILE%\.codex\config.toml；应用配置前请先退出 Codex Desktop。