UUCode Docs

切换深色模式

Codex 桌面版配置教程 ​

本文档用于说明如何安装 Codex 桌面版，并通过 UUCode 配置 Codex 所需的模型接口与 API Key。

前置准备 ​

开始前请先准备：

  • Codex 桌面版客户端
  • Node.js 22+
  • UUCode GPT 分组 API Key

注意：Codex 使用 OpenAI 兼容接口，建议创建 GPT 分组 的 API Key。

1. 下载 Codex 桌面版 ​

打开 Codex 官方页面下载安装：

text
https://openai.com/zh-Hans-CN/codex/

截图占位：Codex 桌面版下载页面 Codex 桌面版下载页面

2. 创建 UUCode API Key ​

访问 UUCode 控制台并登录：

text
https://token.uucode.top

进入 API 密钥页面，创建 GPT 分组 的 API Key，并保存好密钥。

截图占位：UUCode 创建 GPT 分组 API Key UUCode 创建 API Key

3. 安装 Node.js ​

先安装 Node.js 22+，再执行以下命令验证版本：

bash
node -v
npm -v

截图占位：macOS 校验 Node.js 和 npm 版本 macOS 校验 Node 环境

4. 安装 Codex CLI ​

Codex 桌面版会读取本机 Codex 配置，因此需要先安装并配置 Codex CLI。

使用 npm 安装：

bash
npm install -g @openai/codex
codex --version

也可以使用 Homebrew 安装：

bash
brew install --cask codex

截图占位：macOS 安装并校验 Codex macOS 校验 Codex

5. 配置 Codex 接入 UUCode ​

Codex 接入 UUCode 支持两种方式：

  • 手动配置：手动创建并写入 config.toml 和 auth.json
  • 自动配置：执行 npx token-uucode，根据提示写入配置

任选一种即可，不需要重复配置。

方式一：手动配置 ​

创建 Codex 配置目录：

bash
mkdir -p ~/.codex

写入 config.toml：

bash
cat > ~/.codex/config.toml << 'EOF'
model_provider = "uucode"
model = "gpt-5.3-codex"
approval_policy = "on-request"

[model_providers.uucode]
name = "UUCode"
base_url = "https://token.uucode.top"
base_url_api = "https://token.uucode.top/v1"
requires_manual_auth = true
EOF

写入 auth.json：

bash
cat > ~/.codex/auth.json << 'EOF'
{
  "uucode": {
    "api_key": "替换成你的API Key"
  }
}
EOF

配置说明：

  • model_provider：对应上方 [model_providers.uucode]
  • base_url_api：OpenAI 兼容接口地址
  • auth.json：保存你的 UUCode API Key

截图占位：macOS 手动写入 Codex 配置 macOS Codex 手动配置

方式二：自动配置 ​

在终端中执行：

bash
npx token-uucode

根据提示选择 Codex，并填写或粘贴 UUCode API Key，工具会自动写入配置。

截图占位：使用 token-uucode 自动配置 Codex macOS Codex 自动配置

6. 验证配置 ​

执行以下命令检查配置文件：

bash
ls -la ~/.codex
cat ~/.codex/config.toml

进入任意项目目录并启动 Codex：

bash
cd /path/to/your/project
codex

如果能正常进入 Codex 欢迎界面，说明配置成功。

截图占位：macOS 终端启动 Codex macOS 使用 Codex

7. 回到 Codex 桌面版使用 ​

配置完成后，重新打开 Codex 桌面版。桌面版会读取当前用户目录下的 Codex 配置：

text
~/.codex

如果桌面版没有读取到配置，请确认：

  • ~/.codex/config.toml 是否存在
  • ~/.codex/auth.json 是否存在
  • API Key 是否填写正确
  • Codex 桌面版是否已重启

截图占位：Codex 桌面版选择工作模式 Codex 桌面版工作模式

截图占位：Codex 桌面端使用 Codex 桌面端使用

常见问题 ​

桌面版没有读取配置 ​

  • 先确认 ~/.codex/config.toml 和 ~/.codex/auth.json 已正确生成
  • 关闭并重新打开 Codex 桌面版
  • 终端执行 codex 验证 CLI 是否能正常使用

API 调用失败 ​

  • 确认使用的是 GPT 分组 API Key
  • 确认 base_url_api 为 https://token.uucode.top/v1
  • 检查 UUCode 控制台中密钥状态和额度

找不到 codex 命令 ​

重新安装 Codex CLI：

bash
npm install -g @openai/codex