Tutorial on 逍遥笔记

Codex Tools v1.5.4 超详细教程 - 多账号管理 + API 反代完整指南（2026 最新版）

Thu, 26 Mar 2026 11:35:00 +0000

联系逍遥

扫码添加微信，或点击下方按钮复制联系方式。

进微信群请联系博主，各位觉得文章对你有帮助的话可否打赏一些呀~

📋 前言

这是一篇真正的零基础保姆级教程，我会手把手带你从零开始，完整了解和使用 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+

查看系统版本：

# macOS
sw_vers

# Windows (PowerShell)
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"

📦 安装部署（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

# Windows
# 访问 https://nodejs.org/ 下载安装包

# 验证安装
node --version # 应显示 v20.x.x

安装 Rust：

# macOS/Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Windows
# 访问 https://rustup.rs/ 下载 rustup-init.exe

# 验证安装
rustc --version # 应显示 rustc 1.x.x

安装 pnpm：

npm install -g pnpm

# 验证安装
pnpm --version # 应显示 9.15.9+

步骤 2：克隆项目

# 选择安装目录
cd /tmp # macOS/Linux
# 或 D:\tools # Windows

# 克隆项目
git clone https://github.com/170-carry/codex-tools.git

# 进入项目目录
cd codex-tools

步骤 3：安装依赖

# 安装 Node.js 依赖
pnpm install

# 安装时间：约 2-5 分钟（取决于网络）

步骤 4：启动开发环境

# 启动桌面应用（开发模式）
pnpm run tauri dev

# 启动时间：约 30-60 秒
# 启动后会打开应用窗口

开发模式特点：

✅ 支持热重载
✅ 修改代码后自动刷新
✅ 控制台会显示日志

方式三：自行打包（适合高级用户）

步骤 1：完成方式二的所有步骤

步骤 2：执行打包命令

# macOS
pnpm run tauri build

# Windows
pnpm run tauri build

打包时间：约 5-15 分钟（首次打包需要编译 Rust 代码）

步骤 3：查找打包产物

macOS：

ls -la src-tauri/target/release/bundle/dmg/
ls -la src-tauri/target/release/bundle/macos/

Windows：

dir src-tauri\target\release\bundle\msi\
dir src-tauri\target\release\bundle\app\

产物说明：

.dmg / .app - macOS 安装包
.exe / .msi - Windows 安装包

🎨 界面介绍

主界面布局

┌─────────────────────────────────────────┐
│ Codex Tools [设置] │
├─────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────┐ │
│ │ 账号列表 │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ 🟢 账号 1 (Free) │ │ │
│ │ │ 5h: 2.5h / 1w: 15h │ │ │
│ │ └─────────────────────────────┘ │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ 🟡 账号 2 (Plus) │ │ │
│ │ │ 5h: 4.8h / 1w: 20h │ │ │
│ │ └─────────────────────────────┘ │ │
│ └─────────────────────────────────┘ │
│ │
│ [刷新] [切换账号] [启动 Codex] │
│ │
├─────────────────────────────────────────┤
│ [账号管理] [API 反代] [设置] [关于] │
└─────────────────────────────────────────┘

底部导航栏

标签	功能
账号管理	查看和管理所有账号
API 反代	配置和启动 API 代理服务
设置	应用设置和偏好配置
关于	版本信息和帮助

🔧 详细使用教程

一、导入账号

方法 1：OAuth 登录导入（推荐）

点击「账号管理」标签
点击「+ 添加账号」按钮
选择「OAuth 登录」
应用会自动生成授权链接并打开浏览器
在浏览器中登录你的 Codex/ChatGPT 账号
授权完成后会自动跳转回应用
账号会自动导入并保存

优点：

✅ 最简单快捷
✅ 自动获取完整认证信息
✅ 不需要手动操作文件

方法 2：上传 JSON 文件

点击「账号管理」标签
点击「+ 添加账号」按钮
选择「导入 JSON 文件」
选择一个或多个 .json 账号文件
点击「导入」

JSON 文件格式：

{
 "label": "我的账号 1",
 "account_id": "xxx-xxx-xxx",
 "auth_json": {
 "access_token": "xxx",
 "refresh_token": "xxx",
 "session_token": "xxx"
 },
 "plan_type": "free"
}

方法 3：读取文件夹

点击「账号管理」标签
点击「+ 添加账号」按钮
选择「读取文件夹」
选择包含多个 .json 文件的文件夹
应用会自动读取所有账号文件

适用场景：

✅ 有大量账号需要批量导入
✅ 从其他工具迁移账号

方法 4：同步当前设备登录

确保你已经在 Codex 桌面应用或网页版登录
点击「账号管理」标签
点击「+ 添加账号」按钮
选择「同步当前登录」
应用会自动读取本机的登录凭证

注意：

⚠️ 只会同步当前登录的账号
⚠️ 不会覆盖正在使用的账号

二、查看账号用量

手动刷新

进入「账号管理」页面
点击「刷新」按钮
等待几秒钟，用量信息会更新

自动刷新

进入「设置」页面
找到「用量自动刷新」选项
设置刷新间隔（默认 30 分钟）
开启自动刷新

用量信息说明

每个账号会显示：

字段	说明
5h 用量	过去 5 小时的使用时长
1w 用量	过去 1 周的使用时长
计划类型	Free / Plus / Team 等
状态	🟢 可用 / 🟡 受限 / 🔴 不可用

按余量排序

点击「用量」列标题
账号会按余量从高到低排序
再次点击会从低到高排序

三、切换账号并启动 Codex

一键切换

在账号列表中选择一个可用账号
点击「切换账号」按钮
等待应用切换到目标账号
切换成功后会显示提示

切换并启动 Codex

在账号列表中选择一个可用账号
点击「启动 Codex」按钮
应用会：
- 切换到目标账号
- 自动启动 Codex 桌面应用
- 如果找不到桌面应用，会回退到 codex app

编辑器联动（可选）

进入「设置」页面
找到「编辑器联动」部分
开启「切换账号后重启编辑器」
选择你的编辑器（Cursor / VSCode 等）

效果：

切换账号后会自动重启编辑器
编辑器会使用新的账号认证

Opencode 授权同步（可选）

进入「设置」页面
找到「Opencode」部分
开启「同步 Opencode 授权」

效果：

切换 Codex 账号时会同步更新 Opencode 的认证
适合同时使用两个工具的用户

四、API 反代（核心功能）

什么是 API 反代？

简单说，就是在你的电脑上运行一个本地的 API 服务，让其他工具可以通过 OpenAI 兼容的接口调用 Codex 能力。

工作原理：

客户端（如 Cursor） → 本地 API (127.0.0.1:8787) → Codex 上游

启动 API 反代

点击底部导航栏的「API 反代」标签
设置端口号（默认 8787）
点击「启动」按钮
等待服务启动成功
界面会显示：
- Base URL: http://127.0.0.1:8787/v1
- API Key: sk-xxxxxxxx（自动生成）

在 Cursor 中使用

打开 Cursor
点击设置图标 → Cursor Settings
选择「Models」页面
开启「OpenAI API Key」
填入 API Key（从 Codex Tools 复制）
开启「Override OpenAI Base URL」
填入 Base URL：http://127.0.0.1:8787/v1
在「Add or search model」中输入 gpt-4（或其他支持的模型）
点击「Add Custom Model」

完成！ 现在你可以在 Cursor 中使用 Codex 的能力了。

在其他客户端中使用

通用配置：

配置项	值
API 类型	OpenAI Compatible
Base URL	`http://127.0.0.1:8787/v1`
API Key	`sk-xxxxxxxx`（从 Codex Tools 复制）
模型名称	`gpt-4` 或 `gpt-5`

支持的工具：

✅ Cursor
✅ VSCode (Continue 插件)
✅ JetBrains IDEs
✅ Any API 客户端

支持的接口

接口	说明
`GET /health`	健康检查
`GET /v1/models`	获取模型列表
`POST /v1/chat/completions`	聊天补全（兼容 OpenAI）
`POST /v1/responses`	Responses 接口

请求示例

# 健康检查
curl http://127.0.0.1:8787/health

# 获取模型列表
curl http://127.0.0.1:8787/v1/models \
 -H 'Authorization: Bearer sk-xxxx'

# 聊天补全
curl http://127.0.0.1:8787/v1/chat/completions \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer sk-xxxx' \
 -d '{
 "model": "gpt-4",
 "messages": [
 {"role": "user", "content": "1+1 等于几？"}
 ]
 }'

自动启动 API 反代

进入「设置」页面
找到「API 反代」部分
开启「应用启动时自动启动」
设置端口和 API Key（可选）

效果：

✅ 每次打开应用都会自动启动 API 反代
✅ 不需要手动操作

公网访问（Cloudflared）

如果你想让其他设备也能访问 API 反代：

点击「API 反代」标签
找到「Cloudflared 公网访问」部分
选择隧道类型：
- 快速隧道：临时隧道，重启后失效
- 命名隧道：持久隧道，需要配置
点击「启动隧道」
等待隧道建立成功
复制公网地址（如 https://xxx.trycloudflare.com）

注意：

⚠️ 公网访问会暴露你的 API 到互联网
⚠️ 请确保 API Key 足够安全
⚠️ 建议设置访问限制

🔍 故障排查

问题 1：应用无法启动

macOS 提示"已损坏"：

sudo spctl --master-disable
sudo xattr -r -d com.apple.quarantine /Applications/Codex\ Tools.app

Windows 闪退：

右键应用 → 以管理员身份运行
检查是否有杀毒软件拦截
重新下载安装包

问题 2：账号导入失败

OAuth 登录失败：

检查网络连接
确保浏览器能正常访问 ChatGPT
清除浏览器缓存后重试
尝试使用 JSON 文件导入

JSON 文件导入失败：

检查 JSON 格式是否正确
确保包含必要字段（access_token, account_id）
检查文件编码是否为 UTF-8

问题 3：用量刷新失败

检查账号是否已登录
检查网络连接
手动点击刷新按钮
如果所有账号都失败，可能是网络问题

问题 4：API 反代无法启动

端口被占用：

# macOS/Linux
lsof -i :8787

# Windows
netstat -ano | findstr :8787

解决方案：

关闭占用端口的应用
或在 Codex Tools 中更换端口

API Key 无效：

确保从「API 反代」页面复制正确的 API Key
检查是否有多余空格
尝试重新生成 API Key

问题 5：Cursor 无法连接

检查 API 反代是否已启动
检查 Base URL 是否正确（http://127.0.0.1:8787/v1）
检查 API Key 是否正确
尝试访问 http://127.0.0.1:8787/health 确认服务正常
检查 Cursor 是否支持自定义 API

💡 使用技巧

1. 账号管理技巧

定期刷新用量：设置自动刷新，保持用量信息最新
按余量排序：快速找到可用额度最高的账号
使用标签：给账号添加标签（如"工作"、“个人”）
备份账号：定期导出账号 JSON 文件备份

2. API 反代技巧

固定端口：避免每次启动端口变化
设置强 API Key：不要使用默认的弱 Key
监控日志：查看 API 调用日志，了解使用情况
限制访问：如果开启公网访问，设置 IP 白名单

3. 性能优化

关闭不用的功能：如不需要 API 反代，可以关闭
减少自动刷新频率：设置为 1 小时或更长
清理旧账号：删除不再使用的账号

📊 版本历史

版本	日期	主要更新
v1.5.4	2026-03	修复端口占用、稳定性优化
v1.5.3	2026-03	修复稳定性问题
v1.5.0	2026-03	重做账号导入、OAuth 登录优化
v1.4.1	2026-02	去除工作区相关功能
v1.4.0	2026-02	支持自定义 Codex 路径
v1.3.2	2026-02	UI 优化
v1.0.0	2026-01	重构为 Tauri 应用

🔗 相关链接

GitHub 仓库：https://github.com/170-carry/codex-tools
问题反馈：https://github.com/170-carry/codex-tools/issues
更新日志：https://github.com/170-carry/codex-tools/blob/main/changelog.md
API 反代文档：https://github.com/170-carry/codex-tools/blob/main/docs/api-proxy.md

📝 总结

Codex Tools 是一款功能强大的多账号管理工具，核心优势：

✅ 优点

界面简洁，易于上手
支持多种账号导入方式
用量查看直观清晰
API 反代功能强大
支持公网访问
免费开源

⚠️ 注意事项

目前仅支持 macOS 和 Windows
Linux 暂不支持
公网访问需注意安全

🎯 适用人群

有多个 Codex 账号的用户
需要在多个工具间切换账号
需要使用 API 反代功能
开发者和技术爱好者

最后更新：2026-03-26

本教程基于 codex-tools v1.5.4 编写，具体操作请以实际版本为准。 使用本工具请遵守 OpenAI 相关服务条款，严禁用于违规用途。

Codex Console v1.1.1 超详细保姆级教程 - 从零到一完整部署指南（2026 最新版）

Thu, 26 Mar 2026 09:15:00 +0000

联系逍遥

扫码添加微信，或点击下方按钮复制联系方式。

进微信群请联系博主，各位觉得文章对你有帮助的话可否打赏一些呀~

📋 前言

❤️ 写教程不易，如果对您有帮助，欢迎赞赏支持！

微信收款码：

支付宝收款码：

感谢您的支持！🎉

这是一篇真正的零基础保姆级教程，我会手把手带你从零开始，完整部署和使用 Codex Console v1.1.1——一款免费开源的 OpenAI/Codex 账号注册管理工具。

本教程特点：

✅ 完全从零开始：假设你没有任何编程基础
✅ 每步都有命令：直接复制粘贴即可执行
✅ 包含所有坑点：把可能遇到的问题都提前说明
✅ 真实测试验证：所有步骤都已实际测试通过
✅ 持续更新维护：跟随项目版本同步更新

项目信息：

GitHub 仓库：https://github.com/dou-jiang/codex-console
基于项目：cnlimiter/codex-manager（修复增强版）
许可证：MIT（免费开源）
当前版本：v1.1.1

⚠️ 重要声明（必读）

1. 免费开源原则

本项目永久免费开源，任何付费版本均为倒卖行为！

❌ 禁止倒卖：严禁倒卖本项目及相关衍生版本
❌ 禁止付费：任何人向你收费提供本工具，请立即退款并举报
✅ 允许学习：允许学习、研究、二次开发
✅ 允许分享：允许分享给有需要的朋友

2. 合法使用提醒

请遵守 OpenAI 相关服务条款
严禁用于违规、滥用或非法用途
仅供学习、研究和技术交流使用
因使用本项目产生的风险和后果由使用者自行承担

3. 使用建议

新手建议：先用小号测试，熟悉流程后再批量操作
时段选择：避开北京时间 14:00 左右（美国午夜，封号高峰）
批量控制：建议每批 10-50 个，不要一次性注册太多
数据备份：定期导出账号数据，防止丢失

🎯 v1.1.1 版本更新内容

新增功能（5 项）

序号	功能	说明
1	CloudMail 邮箱服务	完整支持服务注册、配置接入、邮件轮询、验证码提取
2	newApi 上传支持	可配置选择不同导入目标类型（newApi/oldApi）
3	Codex 账号导出	导出的账号可直接用于登录、数据迁移、重新导入
4	CPA proxy_url 支持	CPA 服务配置中可直接保存并使用代理地址
5	Outlook 状态识别	直观查看"已注册/未注册"状态，显示关联账号编号

功能优化（5 项）

序号	优化项	效果
1	批量注册上限	从 100 个提升至 1000 个
2	OAuth token 刷新	完善异常处理，降低报错概率
3	批量验证流程	改为受控并发，减少卡死问题
4	WebUI 端口冲突	自动切换可用端口，无需手动修改
5	字段迁移逻辑	启动时自动补齐新增字段，兼容旧数据

BUG 修复（4 项）

序号	修复内容	影响
1	模板渲染兼容	适配不同 Starlette 版本
2	六位数字误判 OTP	避免无关文本被识别为验证码
3	Outlook 大小写问题	避免 Outlook.com 因大小写误判
4	Outlook 列表显示	修复列错位、乱码、占位文案问题

🖥️ 环境准备（按步骤操作）

第一步：确认操作系统

本教程支持以下操作系统：

系统	版本要求	推荐度
Windows	Windows 10/11 (64 位)	⭐⭐⭐⭐⭐
macOS	macOS 10.15+	⭐⭐⭐⭐
Linux	Ubuntu 20.04+/Debian 10+	⭐⭐⭐⭐
Docker	任意支持 Docker 的系统	⭐⭐⭐⭐⭐

查看系统版本命令：

# Windows（PowerShell）
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"

# macOS
sw_vers

# Linux
cat /etc/os-release

第二步：安装 Python（3.10+）

Windows 安装 Python

下载 Python
- 访问官网：https://www.python.org/downloads/
- 下载 Python 3.10 或更高版本（推荐 3.11/3.12）
- 选择 “Windows installer (64-bit)”
安装 Python
- 双击安装包
- ⚠️ 重要：勾选 “Add Python to PATH”
- 点击 “Install Now”

验证安装

# 打开命令提示符（Win+R → cmd）
python --version
# 应显示：Python 3.10.x 或更高

macOS 安装 Python

# 使用 Homebrew（推荐）
brew install python@3.11

# 验证安装
python3 --version

Linux 安装 Python

# Ubuntu/Debian
sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

# CentOS/RHEL
sudo yum install python3.11 python3-pip

# 验证安装
python3 --version

第三步：安装 Git

Windows 安装 Git

下载：https://git-scm.com/download/win
双击安装，使用默认选项即可
验证：
```
git --version
```

macOS 安装 Git

# 使用 Homebrew
brew install git

# 或使用 Xcode 命令行工具
xcode-select --install

Linux 安装 Git

# Ubuntu/Debian
sudo apt install git

# CentOS/RHEL
sudo yum install git

# 验证
git --version

第四步：准备代理环境（重要）

由于 OpenAI 服务限制，你需要准备可用的代理：

代理要求：

支持 HTTPS
稳定性好（推荐付费代理）
延迟低于 300ms
支持并发连接

常见代理配置：

# 本地代理示例（Clash）
HTTP 代理：http://127.0.0.1:7890
HTTPS 代理：http://127.0.0.1:7890

# 环境变量设置（临时）
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

代理测试命令：

# 测试代理是否可用
curl -x http://127.0.0.1:7890 https://www.google.com -I
# 返回 HTTP/2 200 表示正常

📦 安装部署（5 种方式任选）

方式一：源码安装（推荐新手）

步骤 1：克隆项目

# 选择安装目录（Windows 示例：D:\tools\codex-console）
cd /tmp # Linux/Mac

# 克隆项目
git clone https://github.com/dou-jiang/codex-console.git

# 进入项目目录
cd codex-console

# 查看项目结构
ls -la

预期输出：

drwxr-xr-x 9 root 4096 Mar 26 09:10 .
drwxrwxrwt 26 root 4096 Mar 26 09:10 ..
-rw-r--r-- 1 root 1461 Mar 26 09:10 build.bat
-rw-r--r-- 1 root 1185 Mar 26 09:10 build.sh
-rw-r--r-- 1 root 647 Mar 26 09:10 docker-compose.yml
-rw-r--r-- 1 root 8278 Mar 26 09:10 README.md
-rw-r--r-- 1 root 303 Mar 26 09:10 requirements.txt
drwxr-xr-x 7 root 4096 Mar 26 09:10 src
drwxr-xr-x 4 root 4096 Mar 26 09:10 static
drwxr-xr-x 3 root 4096 Mar 26 09:10 templates
-rw-r--r-- 1 root 5992 Mar 26 09:10 webui.py

步骤 2：创建虚拟环境（强烈推荐）

为什么使用虚拟环境：

避免污染系统 Python 环境
方便管理依赖包
便于迁移和部署

# Python 3.10+ 内置 venv 模块
python -m venv .venv

# 激活虚拟环境
# Windows (CMD):
.venv\Scripts\activate

# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Linux/Mac:
source .venv/bin/activate

激活成功后，命令行前会出现 (.venv) 标识：

(.venv) user@host:~/codex-console$

步骤 3：安装依赖

# 方式 1：使用 pip（通用）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 方式 2：使用 uv（更快，推荐）
# 先安装 uv
pip install uv

# 使用 uv 安装依赖
uv pip install -r requirements.txt

依赖列表（requirements.txt）：

certifi>=2024.0.0
cffi>=1.16.0
curl_cffi>=0.14.0
pycparser>=1.21
pydantic>=2.0.0
pydantic-settings>=2.0.0
fastapi>=0.100.0
uvicorn[standard]>=0.23.0
jinja2>=3.1.0
python-multipart>=0.0.6
sqlalchemy>=2.0.0
aiosqlite>=0.19.0
psycopg[binary]>=3.1.18
playwright>=1.40.0 # 自动绑卡依赖

安装时间：约 2-5 分钟（取决于网络）

验证安装：

pip list | grep -E "(fastapi|uvicorn|playwright)"

步骤 4：安装 Playwright 浏览器（可选）

如需使用自动绑卡功能，需要安装 Playwright 浏览器：

# 安装浏览器
playwright install

# 安装系统依赖（Linux）
playwright install-deps

注意：这一步可能需要较长时间（10-20 分钟），如果暂时不需要绑卡功能可以跳过。

步骤 5：配置文件

# 复制环境变量模板
cp .env.example .env

# 编辑配置文件（选择你熟悉的编辑器）
# Windows: 用记事本打开 .env
# Linux/Mac: nano .env 或 vim .env

.env 配置示例：

# ── Web UI 监听地址 ──────────────────────────────────────────
# 监听主机（默认 0.0.0.0，允许外部访问）
APP_HOST=0.0.0.0

# 监听端口（默认 8000，可自定义）
APP_PORT=8000

# Web UI 访问密码（⚠️ 强烈建议修改！）
APP_ACCESS_PASSWORD=your_strong_password_here

# ── 数据库 ───────────────────────────────────────────────────
# 本地 SQLite（默认，新手推荐）
APP_DATABASE_URL=data/database.db

# 远程 PostgreSQL（高级用户）
# APP_DATABASE_URL=postgresql://user:password@host:5432/dbname

# ── 代理配置（重要）
# HTTP_PROXY=http://127.0.0.1:7890
# HTTPS_PROXY=http://127.0.0.1:7890

# ── 第三方自动绑卡（可选）
# BIND_CARD_API_URL=https://your-workers-domain.dev/
# BIND_CARD_API_KEY=your_api_key_here

⚠️ 安全提醒：

务必修改 APP_ACCESS_PASSWORD 默认值
不要将 .env 文件上传到公开仓库
生产环境建议使用强密码（16 位以上，包含大小写、数字、符号）

步骤 6：启动服务

# 方式 1：默认启动（127.0.0.1:8000）
python webui.py

# 方式 2：指定主机和端口（允许外部访问）
python webui.py --host 0.0.0.0 --port 8000

# 方式 3：设置访问密码
python webui.py --access-password your_password

# 方式 4：组合参数（推荐）
python webui.py --host 0.0.0.0 --port 8000 --access-password your_password

# 方式 5：调试模式（开发使用）
python webui.py --debug

启动成功标志：

INFO: Started server process [12345]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

访问 WebUI：

本地访问：http://127.0.0.1:8000
远程访问：http://你的服务器 IP:8000
默认密码：admin123（如未在 .env 中修改）

方式二：Docker 部署（推荐生产环境）

前置要求

已安装 Docker 和 Docker Compose
Docker 版本：20.10+
Docker Compose 版本：2.0+

安装 Docker：

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable docker
sudo systemctl start docker

# 验证安装
docker --version
docker compose version

使用 Docker Compose（推荐）

# 克隆项目
git clone https://github.com/dou-jiang/codex-console.git
cd codex-console

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

访问服务：

WebUI: http://你的服务器 IP:1455
noVNC（绑卡可视化）: http://你的服务器 IP:6080

🔧 常见问题解答

一、安装问题

Q1: pip install 报错 “Could not find a version that satisfies the requirement”

解决：

# 升级 pip
python -m pip install --upgrade pip

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Q2: 虚拟环境激活失败

Windows PowerShell 执行策略问题：

# 临时允许执行脚本
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 重新激活
.venv\Scripts\Activate.ps1

二、启动问题

Q1: 端口被占用

Error: [Errno 98] Address already in use

解决：

# 方式 1：更换端口
python webui.py --port
---

## 💖 赞赏支持

<div style="margin: 50px 0; padding: 30px 20px; border: 3px dashed #ff6b6b; border-radius: 15px; background: linear-gradient(135deg, #fff5f5 0%, #fff0f0 100%); text-align: center; box-shadow: 0 4px 15px rgba(255, 107, 107, 0.15);">
 <div style="font-size: 1.3em; font-weight: bold; color: #ff6b6b; margin-bottom: 10px;">
 <span style="font-size: 1.5em;">❤️</span>
 写教程不易，如果对您有帮助，可以赞赏一下吗？
 <span style="font-size: 1.5em;">❤️</span>
 </div>
 <p style="color: #666; font-size: 0.95em; margin: 10px 0 25px 0;">您的支持是我持续更新的最大动力！</p>

 <div style="display: flex; justify-content: center; gap: 40px; flex-wrap: wrap; margin-bottom: 25px;">
 <div style="text-align: center; background: white; padding: 15px; border-radius: 10px; box-shadow: 0 2px 10px rgba(0, 0, 0, 0.08);">
 <p style="margin-top: 12px; font-weight: bold; font-size: 1.1em; color: #333;">微信</p>
 </div>
 <div style="text-align: center; background: white; padding: 15px; border-radius: 10px; box-shadow: 0 2px 10px rgba(0, 0, 0, 0.08);">
 <p style="margin-top: 12px; font-weight: bold; font-size: 1.1em; color: #333;">支付宝</p>
 </div>
 </div>

 <div style="margin-top: 20px; padding-top: 20px; border-top: 2px solid rgba(255, 107, 107, 0.2);">
 <p style="color: #ff6b6b; font-weight: bold; font-size: 1.1em; margin: 0;">🎉 感谢您的支持！</p>
 </div>
</div>

<!-- 强制刷新缓存 -->