本页整理自 Apifox 原客户端接入资料，按青云TOP API 文档规范补充了安全占位符、Base URL 和验证步骤。

Codex 安装与配置教程

Windows 版本教程

系统要求

Windows 10 或 Windows 11

Node.js 22+

npm 10+

网络连接

安装步骤

前置步骤！！！
安装 Git Bash，请访问 Git - Downloads 下载对应您电脑系统的版本，之后一直点击“下一步”即可完成安装。

1\. 安装 Node.js
访问 Node.js 官网 下载并安装最新 LTS 版本。

2\. 安装 codex
打开命令提示符 (CMD) 或 PowerShell，运行：

3\. 验证安装
打开命令提示符 (CMD) 或 PowerShell，运行：

配置 API

1\. 获取 Auth Token
访问 top.qingyuntop.ai 站点页面进行以下操作：

点击 控制台 → API令牌 页面

点击 添加令牌

令牌分组请选择：codex专属（务必选择此分组，否则无法使用）

令牌名称随意

额度建议：设置为 无限额度

其他选项保持默认

Codex 配置 配置步骤图 1

2\. 配置文件

> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！
> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！
> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！

1.

进入当前用户的用户目录下的 .codex 文件夹中，例如：C:\Users\testuser\.codex。
（注意：如果看不到该目录，说明您没有打开 Windows 的“显示隐藏的项目”，请先在文件资源管理器中开启。）

Codex 配置 配置步骤图 2

2.

如果没有 .codex 文件夹，请手动创建该文件夹，然后在其中创建 config.toml 以及 auth.json 两个文件。

Codex 配置 配置步骤图 3

3\. 填写配置 (需要将 $QINGYUN_TOP_API_KEY 替换成您自己创建的真实 SK)。

a. auth.json 中的配置：

{"API_KEY" : "$QINGYUN_TOP_API_KEY"}

b. config.toml 中的配置（直接粘贴下面的内容即可）：
model_reasoning_effort 可选值为 high, medium, low，分别代表模型思考的努力程度（高、中、低）。

model_provider = "api111"
model = "YOUR_RESPONSES_MODEL_ID"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.api111]
name = "api111"
base_url = "https://top.qingyuntop.ai/v1"
wire_api = "responses"

启动 codex

重启终端！重启终端！重启终端！
然后进入到您的工程目录：

运行以下命令启动：

Codex 配置 配置步骤图 4

VSCode 插件 codex

以上配置完成后，在 VSCode 扩展商店中搜索并安装 codex 即可。

Codex 配置 配置步骤图 5

安装完成后会出现在侧边栏。

!Codex 配置 配置步骤图 6

Mac 版本教程

系统要求

macOS 12 或更高版本

Node.js 22+

npm 10+

网络连接

安装步骤

1\. 安装 Node.js

方式一：直接访问 Node.js 官网 下载并安装最新 LTS 版本。

方式二：使用 Homebrew（推荐）

2\. 安装 codex
打开终端 (Terminal)，运行（可能需要加 sudo）：

3\. 验证安装
打开终端 (Terminal)，运行：

配置 API

1\. 获取 Auth Token
访问 top.qingyuntop.ai 站点页面进行以下操作：

点击 控制台 → API令牌 页面

点击 添加令牌

令牌分组请选择：codex特供（务必选择此分组，否则无法使用）

令牌名称随意

额度建议：设置为 无限额度

其他选项保持默认

Codex 配置 配置步骤图 7

2\. 配置文件

> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！
> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！
> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！

1.

创建目录和文件：

2.

编辑 auth.json 文件：

按 i 进入插入模式，粘贴以下内容（将 $QINGYUN_TOP_API_KEY 替换为您的密钥），然后按 ESC 键，输入 :wq 并回车保存退出。

{"API_KEY" : "$QINGYUN_TOP_API_KEY"}

3.

编辑 config.toml 文件：

按 i 进入插入模式，粘贴以下内容，然后按 ESC 键，输入 :wq 并回车保存退出。

model_provider = "api111"
model = "YOUR_RESPONSES_MODEL_ID"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.api111]
name = "api111"
base_url = "https://top.qingyuntop.ai/v1"
wire_api = "responses"

启动 codex

重启终端！重启终端！重启终端！
然后进入到您的工程目录：

运行以下命令启动：

\[图片\]

VSCode 插件 codex

以上配置完成后，在 VSCode 扩展商店中搜索并安装 codex 即可。
\[图片\]

安装完成后会出现在侧边栏。
\[图片\]

Linux 版本教程

系统要求

主流 Linux 发行版 (Ubuntu 20.04+, Debian 10+, CentOS 7+, etc.)

Node.js 22+

npm 10+

网络连接

安装步骤

1\. 安装 Node.js

Ubuntu/Debian

CentOS/RHEL/Fedora

Arch Linux

2\. 安装 codex
打开终端 (Terminal)，运行：

3\. 验证安装
打开终端 (Terminal)，运行：

配置 API

1\. 获取 Auth Token
访问 top.qingyuntop.ai 站点页面进行以下操作：

点击 控制台 → API令牌 页面

点击 添加令牌

令牌分组请选择：codex渠道-gpt（务必选择此分组，否则无法使用）

令牌名称随意

额度建议：设置为 无限额度

其他选项保持默认
\[图片\]

2\. 配置文件

> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！
> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！
> 重要提示：请将下方的 $QINGYUN_TOP_API_KEY 替换为您在 top.qingyuntop.ai 生成的实际 API 密钥！

1.

创建目录和文件：

2.

编辑 auth.json 文件：

按 i 进入插入模式，粘贴以下内容（将 $QINGYUN_TOP_API_KEY 替换为您的密钥），然后按 ESC 键，输入 :wq 并回车保存退出。

{"API_KEY" : "$QINGYUN_TOP_API_KEY"}

3.

编辑 config.toml 文件：

按 i 进入插入模式，粘贴以下内容，然后按 ESC 键，输入 :wq 并回车保存退出。

model_provider = "api111"
model = "YOUR_RESPONSES_MODEL_ID"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.api111]
name = "api111"
base_url = "https://top.qingyuntop.ai/v1"
wire_api = "responses"

启动 codex

重启终端！重启终端！重启终端！
然后进入到您的工程目录：

运行以下命令启动：

Codex 配置 配置步骤图 8

VSCode 插件 codex

以上配置完成后，在 VSCode 扩展商店中搜索并安装 codex 即可。

Codex 配置 配置步骤图 9

安装完成后会出现在侧边栏。

!Codex 配置 配置步骤图 10

常见问题

出现错误请按照如下步骤排查：

1.

确认 API Key 创建是否正确：额度选择无限额度，不要限制模型，分组选择 codex渠道-gpt。

更多 codex 配置及使用详情请参考 codex 官方教程。

接入检查

  • API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
  • OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
  • 先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。