APIMaster.ai
APIMaster.ai 使用文档
English快速开始APIMaster 官网模型广场

Codex Desktop 配置 APIMaster.ai

用 codex-provider-switcher 在 Codex Desktop 官方订阅与 APIMaster.ai 三方 Key 之间切换，并同步项目历史对话。

Codex Desktop 是 OpenAI 的桌面编程 Agent。官方 ChatGPT 订阅在额度充足时体验很好，但可能遇到 5 小时滚动用量限额；限额期间若仍要在同一项目里继续工作，可临时切换到 APIMaster.ai 的 OpenAI 兼容 API Key。

手动改 ~/.codex/config.toml 往往会导致：侧边栏项目里的历史对话消失、无法接着原来的线程干活。开源工具 codex-provider-switcher 专门解决「切换 Provider + 同步历史 metadata」问题。

本文针对 Codex Desktop 桌面 App，与终端 Codex CLI 不同。请遵守 Codex Desktop、OpenAI 与 APIMaster.ai 各自的使用条款；本教程仅为技术配置说明，不构成对任何服务的背书或绕过承诺。

使用场景

情况 说明
官方订阅好用 已登录 ChatGPT 订阅，日常用 Codex Desktop 写代码、改项目
遇到滚动限额 界面提示 You're out of Codex messages，或左下角 Usage remaining 接近 0%，并显示 Resets every 5 hours
限额期间要继续 用 APIMaster.ai 的 API Key 作为 OpenAI 兼容第三方 Provider，继续对话
不能丢历史 项目侧边栏里的线程（如 Update APIMaster.ai tagline）必须还能点开、接着聊
限额恢复后切回 官方额度重置后，可再切回 official 模式，历史同样跟着同步

限额提示：You're out of Codex messages

左下角用量与主界面限额提示

APIMaster.ai 是什么

APIMaster.ai 是 OpenAI 兼容 API 网关：

项 值
Base URL https://apimaster.ai/v1
协议 OpenAI Chat Completions 等（与 OpenAI 兼容接入 一致）
API Key 在 APIMaster 控制台 自行创建

你需要自行准备 APIMaster API Key。可用模型以 模型广场 或 GET https://apimaster.ai/v1/models 返回为准，本文不列举固定价格或模型承诺。

codex-provider-switcher 会做什么

工具仓库：github.com/RomaCredit/codex-provider-switcher

能力 说明
修改本机 Codex 配置 读写 config.toml、auth.json 等
保存 APIMaster Key 本地 profile，切换时复用
保存官方订阅配置 首次从 official 切出时会保存，便于切回
同步历史 metadata 更新 state_5.sqlite、.codex-global-state.json、sessions/rollout-*.jsonl 中的 model_provider
修复侧边栏历史列表 repair-history 不切换 Provider 也可修复显示
切换前自动备份 备份目录见下文
不上传数据 所有操作在本机完成
不删除对话内容 只改 metadata，不删 session 正文

默认 Codex 数据目录：

  • Windows：%USERPROFILE%\.codex\
  • macOS / Linux：~/.codex/

前置条件

  1. 已安装 Codex Desktop（Windows 或 macOS）。
  2. 至少用官方订阅成功登录并使用过 Codex Desktop（以便工具保存 official profile）。
  3. 已安装 Python 3。
  4. 已从 APIMaster 获取 API Key（占位符：你的_apimaster_key）。
  5. 从 GitHub 下载或 clone codex-provider-switcher 到本机任意目录。

Windows 使用步骤

1. 完全退出 Codex Desktop

在系统托盘/任务栏退出 Codex Desktop，确保进程已结束。切换前务必完全退出，否则 SQLite 可能被占用。

2. 打开工具菜单

进入项目目录，双击：

codex-provider-menu.bat

Windows：Codex Provider Switcher 菜单

3. 切换到 APIMaster

在菜单中选择：

1. Switch to APIMaster and sync history
  • 首次会提示输入 APIMaster API Key。
  • 脚本会备份、写入配置、同步历史 metadata。
  • 等待终端显示完成。

4. 重新打开 Codex Desktop

  • 左下角应显示 Logged in with API key。
  • 输入框旁 Provider 显示 apimaster，模型如 5.5 Medium（以你配置为准）。
  • 项目侧边栏应仍能看到原有对话线程，并可点开继续聊（例如 Update APIMaster.ai tagline）。

APIMaster 模式：历史对话仍在，Logged in with API key + apimaster

5. 官方限额恢复后切回

完全退出 Codex Desktop → 再次运行 codex-provider-menu.bat → 选择：

2. Switch to official subscription and sync history

重新打开后，左下角恢复订阅用量显示（如 Usage remaining），Provider 为 openai。

官方订阅模式与剩余用量

6. 历史列表异常时

若切换后侧边栏仍看不到项目历史，完全退出 Codex Desktop 后选择：

6. Repair Desktop history list

macOS 使用步骤

1. 完全退出 Codex Desktop

从菜单栏 Codex → Quit，确认进程已退出。

2. 进入项目目录

cd /path/to/codex-provider-switcher

3. 图形菜单（推荐）

chmod +x ./codex-provider-menu.command
./codex-provider-menu.command

菜单选项与 Windows 相同（1 = APIMaster，2 = official，6 = repair）。

若 .command 无法双击运行，请在终端用上述 chmod +x 后再执行。

4. 命令行（等效）

切换到 APIMaster（首次会提示输入 Key）：

python3 codex_provider_switcher.py apimaster

切回官方订阅：

python3 codex_provider_switcher.py official

仅修复历史列表：

python3 codex_provider_switcher.py repair-history

macOS 默认读写 ~/.codex/，与 Windows 的 %USERPROFILE%\.codex\ 对应。

5. 重新打开 Codex Desktop

确认 Logged in with API key、apimaster Provider 与项目历史线程可见，效果与 Windows 第 4 步相同（见上文截图）。

命令行高级用法

Windows PowerShell

在项目目录执行：

.\switch-codex-provider.ps1 status
.\switch-codex-provider.ps1 apimaster
.\switch-codex-provider.ps1 official
.\switch-codex-provider.ps1 repair-history

显式指定 Key、模型与 Base URL：

.\switch-codex-provider.ps1 apimaster `
  -ApiKey "你的_apimaster_key" `
  -Model "gpt-5.5" `
  -BaseUrl "https://apimaster.ai/v1"

测试 APIMaster /v1/models：

.\switch-codex-provider.ps1 test

macOS / 跨平台 Python

python3 codex_provider_switcher.py status
python3 codex_provider_switcher.py apimaster
python3 codex_provider_switcher.py official
python3 codex_provider_switcher.py repair-history

显式参数示例：

python3 codex_provider_switcher.py apimaster \
  --api-key "你的_apimaster_key" \
  --model "gpt-5.5" \
  --base-url "https://apimaster.ai/v1"

可用模型请用 status 或菜单项 4. Test APIMaster /v1/models 自行确认。

安全与隐私

项 说明
API Key 存储 仅保存在本机 ~/.codex/（Windows：%USERPROFILE%\.codex\）
备份位置 ~/.codex/provider-switcher/（Windows：%USERPROFILE%\.codex\provider-switcher\）
不上传 工具不上传配置、Key 或对话到远程
不删对话 不删除 sessions/ 下 rollout 正文
请勿公开分享 不要把整个 .codex 目录贴到公开 Issue（可能含 Key 或私有路径）
切换前退出 App 建议完全退出 Codex Desktop 再运行脚本

回滚：从 provider-switcher 备份目录恢复对应时间戳的 .bak 文件（需先退出 Codex Desktop）。

常见问题（FAQ）

Q：切换后历史对话还在吗？
A：对话文件仍在 ~/.codex/sessions/。工具同步的是 metadata（SQLite、global state、jsonl 首行），让侧边栏能继续显示并关联到当前 Provider。若仍异常，运行 repair-history（菜单 6）。

Q：为什么需要同步历史 metadata？
A：Codex Desktop 侧边栏不只读 session 文件，还依赖 state_5.sqlite 等与 model_provider 字段。只改 config.toml 时，旧线程可能仍标记为 openai，在 APIMaster 模式下会被过滤掉。

Q：能不能切回官方订阅？
A：可以。选 2 / official，历史 metadata 会同步回 openai。

Q：APIMaster Key 存在哪里？
A：本机 ~/.codex/auth.json 及工具 profile 目录（与 official profile 分开保存）。勿提交到 Git 或发到群聊。

Q：切换后侧边栏还是看不到历史怎么办？
A：1）确认已完全退出再切换；2）运行 6. Repair Desktop history list 或 repair-history；3）检查是否在正确项目下；4）查看 provider-switcher 备份是否需要回滚。

Q：这个工具会不会删除我的对话？
A：不会删除 rollout 正文。仅更新 metadata 与 auth/config。

Q：Windows 报 Python 找不到怎么办？
A：安装 Python 3，安装时勾选 Add python.exe to PATH。在 PowerShell 执行 python --version 或 py -3 --version 确认。

Q：macOS .command 无法运行怎么办？
A：终端执行 chmod +x ./codex-provider-menu.command，或直接用 python3 codex_provider_switcher.py apimaster。

Q：和 Claude Code Desktop 一样吗？
A：不一样。Codex Desktop 是 OpenAI 产品；Claude Code Desktop 见 Claude Code Desktop 教程。

核对清单

  • 已从 GitHub 获取 codex-provider-switcher
  • 已安装 Python 3，且曾在 Codex Desktop 用官方订阅登录过
  • 切换前完全退出 Codex Desktop
  • 已准备 APIMaster Key，Base URL 为 https://apimaster.ai/v1
  • 切到 APIMaster 后：Logged in with API key + 侧边栏历史可见
  • 限额恢复后可用 official 切回

相关链接