Codex Toolkit

面向 Codex 用户的本地优先桌面增强工具：token 监控、中转站管理、历史同步与一键重启。

中文 | English

快速开始 | 功能特性 | 中转站管理 | 历史同步 | 开发

Codex Toolkit 会读取本地 Codex 会话日志，把 token 使用情况整理成一个紧凑的桌面仪表盘，并按 provider 汇总历史 token。当 Codex 使用中转站 provider 时，应用会根据本地 token_count 事件重建 24 小时和 7 天 token 用量趋势，即使没有官方限额字段也能看到本机用量变化。它也可以管理 Codex 的中转站/API 配置，让你不用手动编辑 ~/.codex/config.toml，就能在官方路线、中转路线和本地路由器路线之间切换；需要时还可以把历史会话的 provider 标记同步到当前路线。

本地路由器模式会让 Codex 继续使用 Responses API 连接 http://127.0.0.1:15721/v1，再由 Codex Toolkit 在本机把请求转换到 Chat Completions 上游，因此可以使用 DeepSeek、SiliconFlow、OpenRouter 等兼容 /chat/completions 的供应商。

当前主要在 Windows 上测试。macOS 兼容性暂未充分验证，欢迎反馈问题。

截图

快速开始

npm install
npm run dev

构建桌面安装包：

npm run build

构建产物会生成在：

• src-tauri/target/release/bundle/msi
• src-tauri/target/release/bundle/nsis
• src-tauri/target/release/bundle/dmg
• src-tauri/target/release/bundle/macos

功能特性

模块	能力
Token 仪表盘	当前会话总量、最近回复用量、趋势视图、上下文窗口大小、按 provider 汇总 token
限额视图	基于本地 Codex 会话日志展示 5 小时和每周使用窗口
中转站用量趋势	使用中转站 provider 时，基于本地 token_count 事件重建 24 小时逐小时 token 桶和 7 天 token 总量
中转站管理	Provider ID、API Base URL、API Key、直连 Responses、本地路由器、Chat Completions 上游、Provider 自检、应用配置、恢复官方、应用并重启
历史同步	查看各 provider 的历史记录数量，将会话文件和本地 SQLite 历史同步到当前 provider
桌面体验	托盘最小化/恢复、开机自启、贴边吸附、隐私模式
界面	中英双语菜单切换、日间/夜间主题切换

中转站管理

Codex Toolkit 会先把中转站设置保存在本地，只有点击应用配置时才会写入 Codex 配置。

默认 Provider ID 为 moapi，生成的 Codex 配置示例：

model_provider = "moapi"

[model_providers.moapi]
name = "moapi"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://your-relay.example.com/v1"
experimental_bearer_token = "sk-..."

Provider ID 可以自定义。比如设置为 myrelay 时，Codex Toolkit 会写入：

model_provider = "myrelay"

[model_providers.myrelay]
name = "myrelay"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://your-relay.example.com/v1"
experimental_bearer_token = "sk-..."

写入前会自动备份原 Codex 配置：

config.toml.codexviewer-backup-YYYYMMDD-HHMMSS

恢复官方会移除当前工具管理的 provider、默认 moapi provider，以及旧版本遗留的 CodexViewerRelay provider。

本地路由器模式

当上游供应商只兼容 OpenAI Chat Completions，而不直接支持 Codex 使用的 Responses API 时，可以使用本地路由器模式。

在本地路由器模式下，Codex 配置仍然写成 Responses provider，并指向本机地址：

model_provider = "gui"

[model_providers.gui]
name = "gui"
wire_api = "responses"
requires_openai_auth = true
base_url = "http://127.0.0.1:15721/v1"
experimental_bearer_token = "codex-toolkit-local-router"

真实上游地址、API Key 和上游模型保存在 Codex Toolkit 的 provider 配置中，不会直接写入 Codex 的本地配置。例如：

Codex -> http://127.0.0.1:15721/v1/responses
Codex Toolkit -> https://api.siliconflow.cn/v1/chat/completions
上游模型 -> deepseek-ai/DeepSeek-V3.2

本地路由器会处理：

• Responses 请求转 Chat Completions 请求
• Chat Completions 流式输出转 Responses SSE
• reasoning_content、reasoning 和 <think>...</think>
• 非流式和流式 tool calls
• function_call_output 工具结果回传
• response.completed、response.failed、incomplete 和上游错误规范化

中转站面板里的“测试 Provider”按钮可以在不修改 Codex 配置的情况下测试当前 provider，包括本地路由器健康检查、上游非流式请求和上游流式请求。

历史同步

历史同步面板会读取当前 Codex provider，并统计本机历史会话中不同 provider 的记录数量，包括：

• ~/.codex/sessions 和 ~/.codex/archived_sessions 下的 rollout 会话文件
• ~/.codex/state_5.sqlite 中的线程记录
• 工具创建的历史同步备份数量

点击“同步历史”后，Codex Toolkit 会把不属于当前 provider 的历史会话标记同步到当前 provider，并更新本地 SQLite 线程记录。同步前会自动备份原始会话首行元数据、state_5.sqlite、Codex 配置和全局状态文件，备份目录为：

~/.codex/backups_state/toolkit-history-sync/YYYYMMDDTHHMMSS.sssZ

如果历史中包含其他 provider 的 encrypted_content，面板会显示警告：同步可以恢复列表可见性，但继续打开这些会话仍可能受原 provider 加密内容影响。

数据加载方式

应用会：

1. 解析 Codex 会话日志目录
2. 递归扫描 .jsonl 文件
3. 从首行 session_meta 读取 model_provider
4. 提取 token_count 事件
5. 读取当前工具管理的 Codex provider 状态
6. 生成最新 token 快照、趋势数据和 provider token 汇总
7. 官方路线使用官方限额百分比
8. 中转路线使用自计算的 24 小时和 7 天 token 桶
9. 将用量标记为官方路线或中转路线
10. 渲染到桌面 UI

默认日志目录：

~/.codex/sessions

你可以在设置面板里覆盖这个目录。

为什么做这个项目

OpenAI 的公开 API usage 接口主要面向组织账单和 API 用量，不适合直接还原本地 Codex 桌面会话的 token 使用情况。不同中转服务对用量数据的暴露方式也不一样。

Codex Toolkit 选择读取你机器上已经存在的本地 Codex 会话日志来重建使用情况，并根据会话自身记录的 provider 和当前 Codex 配置，展示官方路线与中转路线的历史分布。

开发

环境要求：

• Node.js 20+
• Rust toolchain with cargo
• Windows: Microsoft Visual Studio C++ Build Tools
• macOS: Xcode Command Line Tools

常用检查：

cargo test --manifest-path src-tauri/Cargo.toml
npm run build

Windows 上只检查前端语法：

$tmp = Join-Path $env:TEMP 'codex-toolkit-renderer-check.mjs'
Copy-Item src\renderer.js $tmp -Force
node --check $tmp

发布自动化

仓库包含两个 GitHub Actions workflow：

• CI：在 push 和 pull request 时运行测试并验证构建
• Release：推送类似 v1.0.0 的版本 tag 时构建 Windows/macOS 安装包，并上传到 GitHub Releases

最新修复版本：

• v1.2.0：新增本地路由器模式，可让 Codex 通过 Responses API 使用 Chat Completions 上游，并支持 reasoning、tool calls、工具结果回传和 Provider 自检。

发布示例：

git tag v1.0.0
git push origin main
git push origin v1.0.0

平台说明

• Windows 产物为 .msi 和 setup.exe
• Windows release 可执行文件使用 GUI subsystem，启动时不会弹出控制台黑窗口
• macOS 产物为 .dmg 和 .app
• macOS 签名和 notarization 暂未配置，首次启动可能仍会出现 Gatekeeper 提示

隐私

Codex Toolkit 读取的是你本机的 Codex 会话日志和本地 Codex SQLite 状态库，不会调用 OpenAI 公开组织用量 API 来填充仪表盘。

API Key 会保存在本地工具设置文件中，只有应用中转站配置时才会写入 Codex 配置。历史同步会改写本机会话元数据和本地 SQLite provider 标记，执行前会自动备份。分享截图时请避免暴露完整本地路径或敏感中转站信息，也可以使用内置隐私开关。

反馈与支持

如果你在使用中遇到问题，或希望加入问题反馈交流群，可以添加微信联系。这个项目会持续围绕 Codex 的本地使用体验做改进，欢迎反馈真实场景里的问题。

如果 Codex Toolkit 对你有帮助，也可以通过赞赏码支持一下维护工作。感谢每一份反馈和支持。

贡献

提交 Pull Request 前请先阅读 CONTRIBUTING.md。

许可证

MIT