📋 前言
这是一篇真正的零基础保姆级教程，我会手把手带你从零开始，完整了解和使用 Codex Tools v1.5.4——一款基于 React + Tauri 的桌面工具，用来管理多个 Codex 账号，并提供本地 API 反代能力。
本教程特点：
- ✅ 完全从零开始：假设你没有任何开发基础
- ✅ 真实测试验证：所有步骤都已实际测试通过
- ✅ 包含所有坑点：把可能遇到的问题都提前说明
- ✅ 持续更新维护：跟随项目版本同步更新
项目信息：
- GitHub 仓库：https://github.com/170-carry/codex-tools
- 当前版本：v1.5.4
- 技术栈：React + Tauri (Rust)
- 支持系统：macOS / Windows
- 许可证：MIT（免费开源）
⚠️ 重要声明
- 本项目仅供学习研究：请遵守 OpenAI 相关服务条款
- 严禁用于违规用途：不要用于滥用、非法用途
- 风险自担：因使用本项目产生的风险和后果由使用者自行承担
- 免费开源：任何付费版本均为倒卖行为
🎯 核心功能
1. 多账号管理
- ✅ 支持 OAuth 登录导入
- ✅ 支持 JSON 文件批量导入
- ✅ 支持读取文件夹下的全部账号文件
- ✅ 导入后保留当前本机登录态
2. 用量查看与智能切换
- ✅ 展示每个账号的 5 小时用量窗口
- ✅ 展示每个账号的 1 周用量窗口
- ✅ 显示计划类型（Free/Plus/Team 等）
- ✅ 支持手动刷新和定时自动刷新
- ✅ 支持按余量排序和智能切换
3. 一键切换账号
- ✅ 一键切换账号并启动 Codex
- ✅ 找不到桌面应用时自动回退到 codex app
- ✅ 可选同步 Opencode OpenAI 授权
- ✅ 可选在切换后重启已选编辑器
4. API 反代（核心功能）
- ✅ 本地提供 OpenAI 兼容的 /v1 接口
- ✅ 使用已登录的 Codex 账号作为上游
- ✅ 支持固定端口、自定义端口
- ✅ 支持固定 API Key 和手动刷新
- ✅ 按账号余量自动挑选可用账号转发
- ✅ 可设置应用启动时自动启动 API 反代
5. 公网访问与桌面能力
- ✅ 集成 cloudflared，可将本地反代暴露到公网
- ✅ 支持快速隧道和命名隧道
- ✅ 可选 HTTP/2 协议
- ✅ 支持后台驻留、状态栏菜单
- ✅ 支持应用内更新和多语言界面
🖥️ 环境准备
系统要求
| 系统 | 版本要求 | 推荐度 |
|------|----------|--------|
| macOS | macOS 10.15+ | ⭐⭐⭐⭐⭐ |
| Windows | Windows 10/11 (64 位) | ⭐⭐⭐⭐ |
| Linux | 暂不支持 | ❌ |
前置软件
如果你只是使用（不开发）：
- ✅ 不需要安装任何额外软件
- ✅ 直接下载安装包即可
如果你要开发/打包：
- Node.js 20+
- Rust stable
- pnpm 9.15.9+
📦 安装部署（3 种方式）
方式一：下载预编译版本（推荐新手）
步骤 1：访问发布页面
打开浏览器访问：
- GitHub Releases：https://github.com/170-carry/codex-tools/releases
步骤 2：下载对应版本
macOS 用户：
- Intel 芯片：下载 Codex_Tools_x64.dmg 或 Codex_Tools_x64.app.tar.gz
- Apple Silicon (M1/M2/M3)：下载 Codex_Tools_aarch64.dmg 或 Codex_Tools_aarch64.app.tar.gz
Windows 用户：
- 下载 Codex_Tools_x64-setup.exe 或 Codex_Tools_x64.zip
步骤 3：安装应用
macOS：
- 双击 .dmg 文件
- 将 Codex Tools.app 拖拽到「应用程序」文件夹
- 如果提示"已损坏"，执行以下命令修复：
sudo spctl --master-disable
sudo xattr -r -d com.apple.quarantine /Applications/Codex\ Tools.app
Windows：
- 双击 .exe 安装包
- 按照安装向导完成安装
步骤 4：首次启动
- 打开「应用程序」文件夹（macOS）或开始菜单（Windows）
- 找到并打开 Codex Tools
- 首次启动可能会提示确认，点击"打开"即可
方式二：源码安装（适合开发者）
步骤 1：安装前置环境
安装 Node.js 20+：
# macOS (使用 Homebrew)
brew install node@20
# 验证安装
node --version # 应显示 v20.x.x
安装 Rust：
# macOS/Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
# 验证安装
rustc --version # 应显示 rustc 1.x.x
安装 pnpm：
npm install -g pnpm
pnpm --version # 应显示 9.15.9+
步骤 2：克隆项目
cd /tmp
git clone https://github.com/170-carry/codex-tools.git
cd codex-tools
步骤 3：安装依赖
pnpm install
# 安装时间：约 2-5 分钟（取决于网络）
步骤 4：启动开发环境
pnpm run tauri dev
# 启动时间：约 30-60 秒
方式三：自行打包（适合高级用户）
步骤 1：完成方式二的所有步骤
步骤 2：执行打包命令
pnpm run tauri build
# 打包时间：约 5-15 分钟（首次打包需要编译 Rust 代码）
步骤 3：查找打包产物
macOS：
ls -la src-tauri/target/release/bundle/dmg/
Windows：
dir src-tauri\target\release\bundle\msi\
🎨 界面介绍
主界面布局
┌─────────────────────────────────────────┐
│ Codex Tools [设置] │
├─────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────┐ │
│ │ 账号列表 │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ 🟢 账号 1 (Free) │ │ │
│ │ │ 5h: 2.5h / 1w: 15h │ │ │
│ │ └─────────────────────────────┘ │ │
│ └─────────────────────────────────┘ │
│ │
│ [刷新] [切换账号] [启动 Codex] │
│ │
├─────────────────────────────────────────┤
│ [账号管理] [API 反代] [设置] [关于] │
└─────────────────────────────────────────┘
底部导航栏
| 标签 | 功能 |
|------|------|
| 账号管理 | 查看和管理所有 Codex 账号 |
| API 反代 | 配置和使用本地 API 代理服务 |
| 设置 | 应用配置和偏好设置 |
| 关于 | 版本信息和项目链接 |
💡 使用技巧
1. 账号用量监控
- 定期检查账号用量，避免超限
- 使用智能切换功能，自动选择余量最多的账号
- 设置用量告警，及时收到通知
2. API 反代配置
- 默认端口：http://localhost:8080/v1
- 可配置固定 API Key，方便集成
- 支持多个反代实例同时运行
3. 公网访问
- 使用 cloudflared 隧道暴露服务
- 支持快速隧道（临时）和命名隧道（持久）
- 注意安全风险，建议配置访问控制
❓ 常见问题
Q1: 账号导入失败？
A: 确保账号文件是有效的 JSON 格式，包含 access_token 字段。
Q2: API 反代无法启动？
A: 检查端口是否被占用，尝试更换端口。
Q3: 用量显示不准确？
A: 点击刷新按钮，或等待自动刷新（默认 5 分钟）。
Q4: 切换账号后 Codex 未生效？
A: 重启 Codex 桌面应用或编辑器插件。
🔗 相关链接
- GitHub 仓库：https://github.com/170-carry/codex-tools
- 问题反馈：https://github.com/170-carry/codex-tools/issues
- 更新日志：https://github.com/170-carry/codex-tools/releases
💰 支持项目
如果这个项目对你有帮助，欢迎：
- ⭐ Star 支持项目
- 🔗 分享给更多朋友
- 💡 提交 Issue 和 PR
教程版本：v1.5.4
最后更新：2026-03-26
适用系统：macOS / Windows
