Codex 综合配置

本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。

快速判断：我应该看哪一段？

• 只想聊天：先看桌面端的基础配置。
• 要接入 MCP、知识库或工作流：看 Agent/自动化章节。
• 要在终端写代码：看 CLI、Provider 和环境变量章节。
• 遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。

OpenAI Codex CLI（融合自原文档）

OpenAI Codex CLI 安装教程 — 在 Windows、macOS、Linux 上安装终端 AI 编程助手，对接 青云 TOP API。支持沙箱策略与原子补丁编辑。

项目介绍

Codex CLI 是一个来自 OpenAI 的编码代理，可在您的计算机上本地运行。

• 官方主页：https://chatgpt.com/codex
• 项目主页：https://github.com/openai/codex

效果演示

特性

功能分类

特性

终端式编码助手

Codex CLI 是一个基于终端的交互式编码助理，用于在命令行中编辑代码、生成补丁并运行命令。

工具驱动架构

提供 apply_patch、shell、update_plan、multi_tool_use 等工具，用于对仓库文件和操作进行可控修改。

原子补丁编辑

使用专门的补丁格式通过 apply_patch 原子地添加/更新/删除文件，便于审计与回滚。

沙箱与审批

支持沙箱策略（如 workspace-write、read-only）和审批模式（on-request、on-failure、never），控制写入与网络访问权限。

计划追踪

update_plan 用于列出步骤并跟踪状态，要求始终只有一个 in_progress 步骤以保持明确进度。

交互规范

在重要操作前发送简短前导说明，保持语气友好、简洁并提供进度更新。

安全约束

遵循严格规则（不随意更改无关文件、不添加版权头、不执行破坏性命令），需要用户批准敏感操作。

测试与格式化

推荐在修改后运行相关测试与格式化工具，但不负责修复与当前任务无关的问题。

输出与风格

最终输出遵循 CLI 渲染规范（例如 ** 标题、反引号表示路径/命令），保持可扫描的简洁结构。

并行执行

支持通过 multi_tool_use.parallel 并行运行多个工具以提升效率。

AI 模型配置方法

Windows 端图文指引

1.打开终端

2.安装 WSL

为在 Windows 上获得最佳性能，请安装并使用 Windows Subsystem for Linux (WSL2)。

安装 WSL2，重启 Windows 计算机

wsl --install

安装完成后重启 Windows 计算机。

Windows 注意事项

• 建议使用 PowerShell 而不是 CMD
• 如果遇到权限问题，尝试以管理员身份运行
• 某些杀毒软件可能会误报，需要添加白名单

下载 Node Version Manager (NVM)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

NVM 安装 Node.js 22

标签栏新开一个 PowerShell 窗口，打开 WSL：

wsl

安装 Node.js（版本号有时效性，请根据 OpenAI 官网 要求安装对应版本）：

nvm install 22

3.安装 Codex CLI

安装 Codex CLI

npm i -g @openai/codex

这个命令会从 npm 官方仓库下载并安装最新版本的 Codex CLI。

4.修改配置文件

一键修改 Codex CLI 配置文件

iex (irm 'https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.ps1')

5.开始使用 Codex CLI

现在你可以开始使用 Codex CLI 了！

启动 Codex CLI

启动 WSL2：

wsl

直接启动 Codex CLI：

codex

在特定项目中使用：

cd mnt/c/path/to/your/project
codex

按 Enter 启动 Codex CLI。

> 设置 Codex CLI 的权限：1. 允许 Codex 直接修改文件；2. Codex 修改文件需要手动授权

选择模型

/model

> 注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用您配置的、合法授权的自有或组织接入点。请使用您自己部署的 青云 TOP API，或确认服务方具备合法上游授权和合规义务的 青云 TOP API 服务。不要将来源不明的 API 地址或密钥接入生产环境。

macOS 端图文指引

1.安装 Homebrew (已安装请跳过)

Homebrew 是 macOS 缺失的软件包的管理器。

官网：https://brew.sh

安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2.安装 Node.js 环境

Node.js 环境安装步骤

更新 Homebrew：

brew update

安装 Node.js：

brew install node

macOS 注意事项

• 如果遇到权限问题，可能需要使用 sudo
• 首次运行可能需要在系统偏好设置中允许
• 建议使用 Terminal 或 iTerm2

验证安装是否成功

安装完成后，打开终端，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功。

3.安装 Codex CLI

安装 Codex CLI

打开终端，运行以下命令：

# 全局安装 Codex CLI
npm install -g @openai/codex

如果遇到权限问题，可以使用 sudo：

sudo npm install -g @openai/codex

验证 Codex CLI 安装

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。

4.修改配置文件

一键修改 Codex CLI 配置文件

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash

5.开始使用 Codex CLI

现在你可以开始使用 Codex CLI 了！

启动 Codex CLI

直接启动 Codex CLI：

codex

在特定项目中使用：

cd /path/to/your/project
codex

按 Enter 启动 Codex CLI。

> 设置 Codex CLI 的权限：1. 允许 Codex 直接修改文件；2. Codex 修改文件需要手动授权

> 注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用您配置的、合法授权的自有或组织接入点。

6.macOS 常见问题解决

安装时提示权限错误

尝试以下解决方法：

• 使用 sudo 安装：sudo npm install -g @openai/codex
• 或者配置 npm 使用用户目录：npm config set prefix ~/.npm-global

macOS 安全设置阻止运行

如果系统阻止运行 Codex CLI：

• 打开"系统偏好设置" → "安全性与隐私"
• 点击"仍要打开"或"允许"
• 或者在 Terminal 中运行：sudo spctl --master-disable

Linux 端图文指引

1.安装 Node.js 环境

Codex CLI 需要 Node.js 环境才能运行。

Node.js 环境安装步骤

添加 NodeSource 仓库：

sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

安装 Node.js：

sudo apt-get install -y nodejs

Linux 注意事项

• 某些发行版可能需要安装额外的依赖
• 如果遇到权限问题，使用 sudo
• 确保你的用户在 npm 的全局目录有写权限

验证安装是否成功

安装完成后，打开终端，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功。

2.安装 Codex CLI

安装 Codex CLI

打开终端，运行以下命令：

# 全局安装 Codex CLI
npm install -g @openai/codex

如果遇到权限问题，可以使用 sudo：

sudo npm install -g @openai/codex

验证 Codex CLI 安装

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。

3.修改配置文件

一键修改 Codex CLI 配置文件

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/codex-cli-setup.sh | bash

4.开始使用 Codex CLI

现在你可以开始使用 Codex CLI 了！

启动 Codex CLI

直接启动 Codex CLI：

codex

在特定项目中使用：

# 进入你的项目目录
cd /path/to/your/project

# 启动 Codex CLI
codex

按 Enter 启动 Codex CLI。

> 设置 Codex CLI 的权限：1. 允许 Codex 直接修改文件；2. Codex 修改文件需要手动授权

> 注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用您配置的、合法授权的自有或组织接入点。

5.Linux 常见问题解决

安装时提示权限错误

尝试以下解决方法：

• 使用 sudo 安装：sudo npm install -g @openai/codex
• 或者配置 npm 使用用户目录：npm config set prefix ~/.npm-global
• 然后添加到 PATH：export PATH=~/.npm-global/bin:$PATH

缺少依赖库

某些 Linux 发行版需要安装额外依赖：

# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"

接入检查

• API 地址填写青云 TOP API 的 Base URL：https://top.qingyuntop.ai/v1；应用若要求不带 /v1 的站点地址，请按页面说明填写对应格式。
• API Key 只使用环境变量 $QINGYUN_TOP_API_KEY 或应用的安全密钥存储，不要把真实密钥提交到代码仓库。
• 模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写 /v1。

Codex 配置（融合自原文档）

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专属（务必选择此分组，否则无法使用）

令牌名称随意

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

其他选项保持默认

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 的“显示隐藏的项目”，请先在文件资源管理器中开启。）

2.

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

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 = "gpt-5-codex"
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 即可。

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

!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特供（务必选择此分组，否则无法使用）

令牌名称随意

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

其他选项保持默认

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 = "gpt-5-codex"
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 = "gpt-5-codex"
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 即可。

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

!Codex 配置 配置步骤图 10

常见问题

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

1.

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

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

接入检查

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

Codex 配置（融合自原文档）

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专属（务必选择此分组，否则无法使用）

令牌名称随意

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

其他选项保持默认

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 的“显示隐藏的项目”，请先在文件资源管理器中开启。）

2.

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

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 = "gpt-5-codex"
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 即可。

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

!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特供（务必选择此分组，否则无法使用）

令牌名称随意

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

其他选项保持默认

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 = "gpt-5-codex"
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 = "gpt-5-codex"
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 即可。

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

!Codex 配置 配置步骤图 10

常见问题

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

1.

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

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

接入检查

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

Codex App 接入（融合自原文档）

Codex App 可以在兼容版本中复用 Codex CLI 的配置。请先完成 CC Switch 配置 Codex，并确认 Codex CLI 已能正常回复。

直接使用现有配置

1. 在 CC Switch 的 Codex 分支启用 青云TOP API Provider。
2. 在终端运行 codex，确认能够正常对话。
3. 完全退出 Codex App；只关闭窗口可能不会结束后台进程。
4. 重新打开 Codex App。
5. 新建对话并发送一条简短消息。
6. 在 青云TOP API 控制台日志中核对相同时间和模型的请求。

首次启动仍显示登录页

如果应用提供 使用 API Key 或 其他方式登录：

1. 选择 API Key 登录方式。
2. 填写 青云TOP API 客户端专用 API 令牌。
3. 继续进入应用并发送测试消息。

如果当前版本只提供 OpenAI 账号登录，或者没有读取自定义 Provider，则不要修改 OAuth 文件、系统代理或应用程序资源来绕过登录。继续使用 Codex CLI，并等待客户端版本正式支持自定义 Provider。

切换 Provider 后没有生效

1. 退出 Codex App。
2. 在 CC Switch 中重新确认 青云TOP API 显示为 使用中。
3. 检查 Codex CLI 是否仍可正常回复。
4. 再次打开 Codex App。

CC Switch 配置 Codex（融合自原文档）

CC Switch 可以把青云TOP API 的自定义 Provider 写入 Codex 配置。下面按“安装 CC Switch、添加 Provider、安装并启动 Codex、验证请求”的顺序完成接入。

第一步：安装 CC Switch

1. 从 CC Switch 官方 Releases 下载并安装适合当前系统的版本。
2. 打开 CC Switch，在顶部应用栏进入 Codex。
3. 选择添加供应商（中转站）或 自定义 Provider，填写以下信息：

1. 保存配置并点击 启用，确认 Provider 卡片显示“使用中”。

第二步：安装并启动 Codex

1. 从 OpenAI Codex 官方页面 下载并安装 Codex。
2. 安装完成后启动 Codex。根据当前版本的登录界面，选择支持自定义 Provider 或 API Key 的方式；如果版本要求 OpenAI 账号登录且没有读取 CC Switch 配置，不要修改 OAuth 文件或系统代理绕过登录。
3. 完全退出并重新打开终端，运行：

codex

连接失败时检查 config.toml

如果 Codex 反复提示连接失败，可以检查配置文件中是否包含页面提示的 OpenAI HTTP Provider 片段：

model_provider = "openai_http"

[model_providers.openai_http]
name = "OpenAI HTTP"

这段内容只用于确认 Provider 类型；API Key、Base URL 和模型仍应以 CC Switch 中保存的青云TOP API Provider 为准。修改前请备份 ~/.codex/config.toml，并在修改后完全重启 Codex。

验证是否接入成功

1. 在 Codex 中发送一条简短消息。
2. 确认收到正常回复。
3. 到青云TOP API 控制台的调用日志中核对请求时间、模型和状态。

常见问题

• 401：检查 API Key 是否完整、是否仍在使用旧认证信息。
• 403：检查 API Key 分组、余额和模型权限。
• 404：检查 Base URL 是否重复填写 /v1，以及模型是否支持 Responses API。
• 仍访问官方 Provider：完全退出 Codex 和后台驻留的编辑器，再确认 CC Switch 卡片显示“使用中”。
• 切换后无变化：关闭终端和 Codex 后重新启动，并以控制台调用日志为最终依据。

DeepSeek 模型接入 Codex（融合自原文档）

Codex 原生面向 OpenAI Responses API。只有 青云TOP API 模型列表中明确兼容 Responses API 的 DeepSeek 模型才能使用本教程。

创建专用令牌

1. 打开 青云TOP API 控制台的 API 令牌页面。
2. 创建一个只供 Codex 使用的令牌。
3. 选择包含目标 DeepSeek 模型的分组。
4. 保存并复制令牌。

在 CC Switch 中配置

1. 打开 CC Switch，在顶部选择 Codex。
2. 点击右上角 +，选择 自定义 Provider。
3. 名称填写 青云TOP API DeepSeek。
4. API Key 填写刚创建的令牌。
5. API 请求地址填写 https://top.qingyuntop.ai/v1；亚太地区填写 https://top.qingyuntop.ai/v1。
6. 默认模型填写 青云TOP API 模型列表返回的完整 DeepSeek 模型 ID。
7. 点击 添加，返回列表后点击 启用。
8. 完全退出并重新打开 Codex CLI。

验证

在终端运行：

codex

发送一条简短消息，确认 Codex 收到正常回复。随后在 青云TOP API 控制台日志中检查模型 ID、请求时间和状态。

不使用 CC Switch 时，可按照 Codex CLI 手工填写相同 Provider。

Codex 常见问题（融合自原文档）

为什么消费日志中出现多笔请求？

一次交互可能包含工具调用、重试、压缩或后续请求。先在 青云TOP API 消费日志中按时间、模型 ID、输入/输出令牌、状态和请求 ID 逐笔核对。

• 少量且紧邻主请求的记录可能属于同一任务。
• 持续出现未知请求时，立即撤销令牌并检查本机进程和令牌共享范围。
• 金额是否异常必须结合模型价格和令牌数判断，不能仅以固定金额为界。

如何正确拆分任务？

1. 先写清目标、可修改范围和验收条件。
2. 将工作拆成可以独立验证的模块。
3. 提交前预估会读取和修改哪些文件。
4. 每个阶段运行测试并查看 diff，再进入下一阶段。
5. 上下文接近上限时，不要依赖反复压缩继续扩大范围；保存状态后另开聚焦任务。

CLI 最小配置是什么？

先备份 ~/.codex/config.toml 与 ~/.codex/auth.json，不要覆盖已有官方登录。实际字段以当前 Codex CLI 配置文档和本机版本为准。一个 OpenAI Responses 兼容 Provider 通常需要：

model_provider = "青云TOP API"
model = "your-responses-model"

[model_providers.青云TOP API]
name = "青云TOP API"
base_url = "https://top.qingyuntop.ai/v1"
env_key = "QINGYUN_TOP_API_KEY"
wire_api = "responses"

API 密钥应通过客户端支持的认证入口或环境注入，不要把真实密钥写进文档、仓库或截图。只有 /v1/responses 实际请求成功后，才能确认所选模型兼容 Codex。

Windows 与 macOS 配置文件在哪里？

• Windows

• macOS / Linux

在 PowerShell 中检查 $HOME\.codex\config.toml 和 $HOME\.codex\auth.json。修改前复制备份，并完全退出 VS Code 后重开。

检查 ~/.codex/config.toml 和 ~/.codex/auth.json。用 env | grep '^OPENAI_' 排查 shell 环境变量是否覆盖文件配置。

401、403、404 和网络错误怎么排查？

• 401：密钥缺失、无效，或认证来源冲突。
• 403：余额、令牌分组、模型权限或策略拒绝。
• 404：Base URL、/v1/responses 路径或模型 ID 不匹配。
• 429：降低并发，按服务端提示退避重试。
• 5xx：保留请求 ID，短暂退避后重试一次。
• Connection failed：先用 curl 验证同一 URL；再检查 DNS、代理、证书和 IDE 启动环境。

不要因为其他终端工具能联网就直接断定是 MTU。只有在抓包或可重复的包大小测试证明后才调整网络参数。

环境变量冲突怎么处理？

• Windows PowerShell

• macOS / Linux

Get-ChildItem Env:OPENAI_*

env | grep '^OPENAI_'

1. 完全退出 Codex 与 VS Code。
2. 关闭 CC Switch 接管。
3. 审查 shell、系统和 IDE 环境变量来源。
4. 选择一种配置来源，重新打开客户端。
5. 对比备份校验和，确认关闭接管后没有残留修改。

任务卡住或反复重试怎么办？

1. 使用 Ctrl+C 或界面停止按钮中断当前任务。
2. 保存最后一个错误、请求 ID 和已修改文件列表。
3. 检查余额、模型权限和服务状态。
4. 将任务缩小为可验证步骤，再重试一次。
5. 连续失败时停止自动重试，带脱敏日志联系支持。

为什么 VS Code 扩展与 CLI 表现不同？

IDE 扩展可能使用独立配置、登录状态或启动环境。先在 VS Code 集成终端中运行与外部终端相同的版本和最小请求。不要替换扩展的打包 JavaScript 来解锁模型；这无法增加服务端权限，还会破坏完整性和升级路径。

统一接入检查与故障排查

1. 401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
2. 404：核对应用要求的 Base URL 形式；https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1 和完整路径不能重复拼接。
3. 模型为空或不可用：调用 GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。
4. 切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
5. 生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。

> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。

发布前检查

以下检查适用于客户端中选择 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 判定成功。