# Codex 桌面版接入 QCode：Windows 11 一步一图


**一句话答案**：在 Windows 的「Windows PowerShell」里粘贴 `irm https://qcode.cc/install/codex.ps1 | iex`，按提示粘贴 `cr_` 密钥、选 `1) Codex 桌面版 App`，脚本会把 `base_url = "https://api.qcode.cc/openai"` 和密钥写进 `%USERPROFILE%\.codex\`，从托盘完全退出再打开，左上角切到 `Codex` 就能用。

| 项 | 填写 |
|---|---|
| 接入地址（`base_url`） | `https://api.qcode.cc/openai` |
| API 协议（`wire_api`） | `responses` |
| 默认模型 | `gpt-6.2-sol` |
| 配置文件 | `%USERPROFILE%\.codex\config.toml` |
| 密钥文件 | `%USERPROFILE%\.codex\auth.json` |

核对于 2026-11-22 · ChatGPT（Codex 桌面版）26.1117.4957.0 · Windows 11


照着下面的截图一步步做，十来分钟后你的 Windows 电脑上就装好了 Codex 桌面版，并且已经接到 QCode —— 打开应用、左上角切到 `Codex` 模式就能直接对话。

通过 QCode 使用 Codex 桌面版只要一把 QCode API 密钥，不需要 ChatGPT 账号：应用里那个登录页不用填，一键脚本写好的 `auth.json` 会让它自动消失。桌面版和 Codex CLI 共用同一份 `%USERPROFILE%\.codex\config.toml`，所以改完配置一定要从托盘**完全退出**再打开。


- **适用系统**：Windows 11（64 位）· Windows 10（64 位）同样适用，需要能打开 Microsoft Store
- **软件版本**：ChatGPT（Codex 桌面版）26.1117.4957.0 · 一键脚本 v2026.11.21.1
- **截图更新于**：2026-11
- **预计用时**：10 分钟（安装包约 759 MB，网慢时多等一会儿）
- **需要准备**：一个 `cr_` 开头的 QCode API 密钥；一台能上网的 Windows 电脑



- 电脑是 Windows 11 或 Windows 10（都是 64 位），能打开 Microsoft Store 和「Windows PowerShell」
- 已经复制好 `cr_` 开头的 QCode API 密钥。还没有账号？先[注册 QCode](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-codex-desktop-before)，在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-codex-desktop-before)选一个方案，再到[控制台](https://qcode.cc/dashboard)创建密钥。
- 电脑能打开 `qcode.cc`、`api.qcode.cc` 和 Microsoft Store；下载不通时看下面「下载与安装」的地区说明
- 留出 10 分钟不被打断的时间；只有商店安装那一步会弹一次「用户账户控制」，点「是」即可


## 下载与安装

Codex 桌面版没有单独的「Codex」安装包：它在 Microsoft Store 里叫 **ChatGPT**（发布者 `OpenAI`），装好后在应用里切换到 `Codex` 模式就是 Codex。它不依赖 Node.js，也不需要 WSL。

各地区的差别只在**能打开哪个下载入口**上，装完进应用后的接入步骤完全一样。先选你所在的地区：

**中国大陆**

- 优先用 Microsoft Store：浏览器打开 `https://apps.microsoft.com/detail/9plm9xgg6vks`，或在「运行」里输入 `ms-windows-store://pdp/?productid=9PLM9XGG6VKS`，点「获取」即可，不用登录微软账号。
- 商店页面打不开或一直转圈时，用官方直装包 <https://persistent.oaistatic.com/codex-app-prod/ChatGPT-x64.msix>（ARM 机器换成 `ChatGPT-arm64.msix`）。双击后由「应用安装程序」接管，可能弹一次 UAC。
- 一键脚本走 `qcode.cc`，一般能直接访问。


**欧洲 / 日本**

- Microsoft Store 和官方直装包都能用：商店里搜 ChatGPT，或浏览器打开 `https://apps.microsoft.com/detail/9plm9xgg6vks` 点「获取」。
- 想省掉商店时，直接下载官方直装包 `ChatGPT-x64.msix`（ARM 机器用 `ChatGPT-arm64.msix`）双击安装。
- 一键脚本走 `qcode.cc`，一般能直接访问。


**阿拉伯国家**

- 下载渠道和「欧洲 / 日本」一样：Microsoft Store 的 ChatGPT 产品页，或官方直装包 `ChatGPT-x64.msix`。
- Microsoft Store 打不开时，用官方直装包，双击后由「应用安装程序」接管。
- 一键脚本走 `qcode.cc`，一般能直接访问。


**俄罗斯 / 伊朗**

- Microsoft Store 一般能用；商店打不开时，用官方直装包 `ChatGPT-x64.msix`（ARM 机器用 `ChatGPT-arm64.msix`）双击安装。
- 商店和直装包都打不开时，换一个网络再试，装好后接入方式不受影响。
- 一键脚本走 `qcode.cc`，一般能直接访问。


## 跟着截图做：Windows 一步一图

下面 15 步，每步只做一件事。截图上的橙色数字（①、②、③）和正文里的编号一一对应，看到数字就看图上同一个位置。



### 打开 Microsoft Store 里的 ChatGPT 页面

浏览器打开 `https://apps.microsoft.com/detail/9plm9xgg6vks`。按 ① 的位置核对：应用名是 `ChatGPT`、发布者是 `OpenAI`、按钮写「获取」。

![Microsoft Store 里的 ChatGPT 产品页，图标、名称、评分和简介下面是「获取」按钮（1），点它开始安装](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/01-download-page.webp)


做对了你会看到：页面顶部是 ChatGPT 的图标和名称，右边按钮是「获取」。如果写的是「打开」，说明这台电脑已经装过了，直接跳到第 3 步。




### 点「获取」开始安装

点 ① 的「获取」。Windows 会弹「用户账户控制」，确认发布者是 `Microsoft Windows` 后点「是」，然后等它下载，安装包约 759 MB。

![点「获取」后 Microsoft Store 显示正在准备下载、正在验证依赖项，按钮位置显示安装进度（1）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/02-install-store.webp)


做对了你会看到：按钮变成「正在下载 / 正在安装」，装完后变成「打开」，开始菜单里也能搜到 `ChatGPT`。


**卡住了？点「获取」没反应，或者商店报错**

先关掉商店窗口重新打开产品页再试一次；还是不行就走「下载与安装」里的官方直装包 `ChatGPT-x64.msix`，双击后点「安装」。装完在开始菜单搜 `ChatGPT` 就能打开。




### 第一次打开，先别登录

从开始菜单打开 `ChatGPT`（第一次可能还要在 UAC 里点一次「是」）。第一屏是英文登录页 `Sign in to ChatGPT`：① 是 `Continue to sign in`，② 是 `Sign in another way`。

这一页**没有** `Skip`，也先不要点任何登录按钮 —— 下一步会用一键脚本写配置，写好后重开应用这一页就不会再出现了。

![ChatGPT 首次启动的英文登录页 Sign in to ChatGPT，上面是 Continue to sign in（1），下面是 Sign in another way（2），没有跳过按钮](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/03-first-launch.webp)


做对了你会看到：一张只有登录按钮的卡片，标题是 `Sign in to ChatGPT`，整页找不到「跳过」或 `Skip`。




### 认识备选入口，这次先不用

万一以后 `auth.json` 没生效、应用又要求登录，就在登录页点 `Sign in another way`，进去后 ① 就是 `OpenAI API Key` 入口，可以直接填 `cr_` 密钥（下面还有 `Amazon Bedrock`）。

本次教程走一键脚本，所以这里只看一眼、不用登录。

![Sign in another way 子页：第一项是 OpenAI API Key 入口（1），下面还有 Amazon Bedrock 和返回按钮](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/04-login-api-key.webp)


做对了你会看到：页面第一项写着 `OpenAI API Key`，最下面有 `Back` 可以退回登录页。




### 打开 PowerShell，粘贴一键命令

点开始菜单，输入 `Windows PowerShell`（或「终端」）打开，粘贴下面这条命令后回车：

```powershell
irm https://qcode.cc/install/codex.ps1 | iex
```

① 是刚回车的那条命令；② 是横幅第二行的脚本版本 `v2026.11.21.1`，版本号会随更新变化；③ 是接着跑出来的三个接入域测速。

![Windows PowerShell 里粘贴一键命令并回车（1），下面是 QCode 脚本横幅和版本号 v2026.11.21.1（2），再下面是三个接入域的测速结果（3）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/05-run-script.webp)


做对了你会看到：`QCode.cc · Codex 一键配置` 的横幅、一行版本号 `v2026.11.21.1`，接着是 `[1/6]` 和三行测速结果。


**卡住了？提示 irm 不是内部或外部命令**

你打开的是「命令提示符」（CMD），它不认 `irm`。关掉这个窗口，重新打开「Windows PowerShell」或「终端」，再粘贴一次。




### 选接入域：直接回车

在 ① 的提示行按回车，接受方括号里测速最快的那个（本次是 `api.qcode.cc`）。回车后 ② 会回显 `base_url=https://api.qcode.cc/openai` —— 到 `/openai` 为止，末尾不带 `/v1`，也不带斜杠。

`asia.qcode.cc` 和 `us.qcode.cc` 是另外两个接入点，三个都指向同一个 QCode 账号，回车默认取最快的一个，不用自己挑。

![脚本问选哪个接入域，提示回车等于 1（1）；回车后回显接入域 api.qcode.cc 和 base_url=https://api.qcode.cc/openai（2）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/06-choose-domain.webp)


做对了你会看到：一行 `接入域: api.qcode.cc  ->  base_url=https://api.qcode.cc/openai`，紧接着进入 `[2/6]` 要密钥。




### 粘贴 QCode 密钥

到[控制台](https://qcode.cc/dashboard)复制 `cr_` 开头的那一串，回到窗口，在 ① 的 `API 密钥:` 后面粘贴，按回车。

输入时不回显，屏幕上看不到字符；回车后 ② 只显示 `已读取密钥: cr_****` 和末四位，说明密钥已经收到、格式也对。

![脚本提示粘贴 API 密钥（1），粘贴后不回显，回车只显示已读取密钥 cr_**** 和末四位（2）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/07-enter-key.webp)


做对了你会看到：一行 `已读取密钥: cr_****`，开头是 `cr_`，接着进入 `[3/6]`。


**需要 API Key？**

还没有 QCode 账号的话，先[注册](https://qcode.cc/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-codex-desktop-key)。想按用量付费的话，先买一个[按量包](https://qcode.cc/pay-as-you-go?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-codex-desktop-key)，然后到[控制台](https://qcode.cc/dashboard)创建密钥。创建好把 `cr_` 开头那一整串复制回来，回到上面粘贴即可。




### 选 `1) Codex 桌面版 App`

① 是提问行「你要在哪个 Codex 客户端里使用？」。在 ② 的 `1) Codex 桌面版 App` 上直接回车（默认就是 1）。这一项只写配置文件，不装 Node.js，也不装 Codex CLI。

![脚本问你要在哪个 Codex 客户端里使用（1），下面第一项是 1) Codex 桌面版 App，只写配置文件（2）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/08-choose-client.webp)


做对了你会看到：两行选项 —— `1) Codex 桌面版 App` 和 `2) Codex CLI`，回车后进入 `[4/6]` 拉取模型列表。




### 选默认模型 `gpt-6.2-sol`

① 是 `[4/6]` 正在拉取可用模型列表。列表第一行 ② 的 `gpt-6.2-sol` 后面标着 `<- 推荐`，直接回车用它。

![脚本拉取可用模型列表（1），第一行 gpt-6.2-sol 后面标着推荐（2），回车选它](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/09-choose-model.webp)


做对了你会看到：几行以 `1)` `2)` 开头的模型，第一行是 `gpt-6.2-sol`，后面写着 `<- 推荐`。


**卡住了？列表里没有 gpt-6.2-sol**

模型列表是按这把密钥能用的模型拉的。先确认粘贴的是 QCode 的 `cr_` 密钥、没有多复制空格；重新跑一遍脚本再拉一次。只要第一行标着 `<- 推荐`，直接回车就行。




### 确认配置已写入

① 是 `[OK] 已写入 config.toml + auth.json`；② 提示桌面 App 与 CLI 共用这份配置，**必须完全退出后重启**才生效；③ 是脚本自动发的一条最小请求，`接入验证通过` 说明地址、密钥、网络整条链路都通了。

![脚本显示已写入 config.toml 和 auth.json（1），提示桌面 App 与 CLI 共用配置、需完全退出后重启（2），以及接入验证通过（3）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/10-write-config.webp)


做对了你会看到：`已写入 config.toml + auth.json`、一行「完全退出后重启生效」的提示，以及 `接入验证通过! 模型 gpt-6.2-sol 响应正常`。




### 看最后摘要

摘要三行：① 接入域（本次 `api.qcode.cc`）、② 默认模型 `gpt-6.2-sol`、③ 连通性 `[OK] 已验证`。配置文件路径就在中间，指向 `C:\Users\你的用户名\.codex`。

![脚本最后摘要：接入域 api.qcode.cc（1）、默认模型 gpt-6.2-sol（2）、配置文件 config.toml 加 auth.json，连通性 OK 已验证（3）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/11-config-ok.webp)


做对了你会看到：三行都带 `[OK]`，接入域是 `api.qcode.cc`，模型是 `gpt-6.2-sol`。




### 完全退出应用

只关窗口不算，进程还在，配置不会重新读。要这样退：

1. 点任务栏右下角的 `^`，展开隐藏的托盘图标；
2. 右键里面的 `ChatGPT` 图标；
3. 点 `Exit`。

登录页上没有 `File` 菜单，这时按 `Ctrl+Q` 也不起作用，只有托盘里的 `Exit` 才会真的结束进程。


做对了你会看到：托盘里的 ChatGPT 图标消失；打开任务管理器也找不到 `ChatGPT` 这个进程。


**卡住了？托盘里找不到 ChatGPT 图标**

图标可能被折叠了：先点任务栏右下角的 `^` 展开，再右键。如果右键菜单里只有 `New Chat` / `Send Feedback`，说明你右键的是任务栏上的应用按钮，不是托盘图标，换到 `^` 里那个小图标再试。




### 重新打开，跳过问卷

从开始菜单再打开 `ChatGPT`。这次不再出现登录页，直接进入问卷 `What type of work do you do?`：① 是选项 `Engineering`，② 是 `Skip`。选一项或直接点 ② 的 `Skip` 都行，它只影响界面推荐，不影响接入。

![重开应用后直接出现个性化问卷，Engineering 选项已高亮（1），右下角是 Skip 按钮（2）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/13-onboarding.webp)


做对了你会看到：问卷卡片，没有 `Sign in to ChatGPT`；点 `Skip` 后进入主界面。


**卡住了？重开后还是 Sign in to ChatGPT**

说明应用没读到密钥文件。先确认 `%USERPROFILE%\.codex\auth.json` 存在、里面的键名是 `OPENAI_API_KEY`；再从托盘 `Exit` 一次、重新打开。仍然出现登录页，就在登录页点 `Sign in another way` → `OpenAI API Key`，直接把 `cr_` 密钥填进去。




### 把模式切到 `Codex`

主界面默认是 `ChatGPT Work`。点左上角 ① 的模式按钮，在菜单里选 `Codex`。切好后，右下角 ② 的模型胶囊会显示 `6.2 Sol High` —— 它就是 `config.toml` 里 `gpt-6.2-sol` 加 `high` 推理强度。

![ChatGPT 主界面，左上角模式按钮可切到 Codex（1），右下角模型胶囊显示 6.2 Sol High（2）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/14-main-model.webp)


做对了你会看到：左上角模式写着 `Codex`，中间标题是 `What should we build?`，输入框占位文字是 `Do anything`，右下角胶囊是 `6.2 Sol High`。


**卡住了？右下角不是 6.2 Sol High**

说明 `config.toml` 没生效。用记事本打开 `%USERPROFILE%\.codex\config.toml`，确认顶层有 `model = "gpt-6.2-sol"`、`model_provider = "qcode"`，并且有 `[model_providers.qcode]` 这一段；改完保存，从托盘 `Exit` 再重开。




### 发第一句话，收到回复

在 ③ 的输入框（占位文字 `Do anything`）里输入 `Say hello in one short sentence`，按回车。几秒后 ① 是你发出的那句，下面 ② 是模型的回复。

![在输入框发送一句英文问候（1 是发出的消息），几秒后收到模型回复（2），下面是输入框 Do anything（3）](https://docs.qcode.cc/static/images/tut/codex-desktop/202611/zh/15-first-reply.webp)


做对了你会看到：你的消息出现在对话区右侧，几秒后左边出现一句完整回复；不是一直转圈，也不是 401。




## 验证成功

三件事都对上，就算装好并接上了：

- 重开应用不再出现 `Sign in to ChatGPT`，左上角模式能切到 `Codex`；
- 右下角模型胶囊显示 `6.2 Sol High`，发一句话能收到正常回复；
- 想再核一次请求有没有真的走 QCode：打开 [probe.qcode.cc](https://probe.qcode.cc/)，输入密钥，能看到刚才那次请求，模型名是 `gpt-6.2-sol`。


### 全部完成

你这台 Windows 电脑已经装好 Codex 桌面版，并且接上了 QCode：以后打开 `ChatGPT`、切到 `Codex` 模式就能直接让它写代码、改文件。接下来可以：

- [Codex CLI 完整教程](/docs/ide/codex)
- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial)
- [Codex vs Claude Code 对比](/docs/getting-started/codex-vs-claude-code)
- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)
- 接下来：在[定价页](https://qcode.cc/pricing?utm_source=docs.qcode.cc&utm_medium=tut_done&utm_campaign=knowledge_base&src=docs-ide-codex-desktop-done)比较各个方案，挑适合长期使用的那个
- 回到[控制台](https://qcode.cc/dashboard)查看用量和余额


## 常见报错

| 报错原文 | 原因 | 怎么办 |
|---|---|---|
| `Sign in to ChatGPT` | 应用启动时没读到 `auth.json`：还没跑一键脚本，或者改完配置只关了窗口、没从托盘完全退出 | 从托盘 `ChatGPT` 图标右键 `Exit` 再重开；仍出现就检查 `%USERPROFILE%\.codex\auth.json` 里 `OPENAI_API_KEY` 是 `cr_` 开头的密钥 |
| `ERROR: unexpected status 401 Unauthorized: {"error":"Missing API key"}, url: https://xxx/v1/responses` | `config.toml` 没写 `requires_openai_auth = true`，或者 `auth.json` 少了 `OPENAI_API_KEY`，请求没带密钥 | 在 `config.toml` 的 `[model_providers.qcode]` 里补 `requires_openai_auth = true`，`auth.json` 写成 `{"OPENAI_API_KEY": "cr_xxxxxxxx"}`，保存后从托盘 `Exit` 重开 |
| `404 route not supported: POST /chatgpt/v1/responses` | `base_url` 写成了 ChatGPT 的登录域名，或者在 `/openai` 后面多写了 `/v1`、斜杠 | 把 `base_url` 改回 `https://api.qcode.cc/openai`，保存后从托盘 `Exit` 重开 |
| `Error loading config.toml: wire_api = "chat" is no longer supported.` | `wire_api` 还写着 `chat`，Codex 只支持 Responses 协议 | 把 `wire_api` 改成 `"responses"`，保存后重开应用 |
| `Missing environment variable: OPENAI_API_KEY` | 用了 `env_key` 写法，但启动应用的进程里没有这个变量；或者 `requires_openai_auth` 和 `env_key` 两种写法同时留着 | 桌面版建议用 `requires_openai_auth = true` + `auth.json`，并把 `env_key` 那一行删掉，两种写法只能留一种 |
| `模型提供商不匹配` | 会话历史绑定的 provider 和 `config.toml` 里的对不上，常见于先在应用里登录过官方账号、后来改成 API 密钥 | 新建一个对话；确认 `model_provider = "qcode"` 与 `[model_providers.qcode]` 表名一致，改完从托盘 `Exit` 重开 |

## 常见问题

### 用它需要 ChatGPT 账号吗？

不需要。应用首次启动会停在 `Sign in to ChatGPT`，但只要你按上面的步骤跑过一键脚本，`%USERPROFILE%\.codex\auth.json` 里已经有一把 `cr_` 密钥，重开应用就会跳过登录页，直接进入问卷和主界面。整个过程不登录任何厂商账号。

### 桌面版和 Codex CLI 是什么关系？

两者共用同一份 `%USERPROFILE%\.codex\config.toml` 和 `auth.json`：桌面版读到的模型、接入地址和密钥，和 Codex CLI 完全一致。一键脚本第 3 步选 `1) Codex 桌面版 App` 时只写配置，不装 Node.js 和 CLI；以后想用命令行，再跑一次脚本选 `2) Codex CLI` 即可，密钥不用重新填。命令行用法见 [Codex CLI 完整教程](/docs/ide/codex)。

### 改完配置不生效怎么办？

应用只在启动时读一次配置。改完 `config.toml` 或 `auth.json` 后，必须从任务栏右下角的托盘图标右键 `ChatGPT` → `Exit`，确认进程结束，再重新打开；只关窗口或者按 `Ctrl+Q` 都不算。

### 桌面版需要 Node.js 或 WSL 吗？

都不需要。桌面版是 Microsoft Store 分发的原生 Windows 应用，一键脚本选 `1) Codex 桌面版 App` 时不碰 Node.js，也不用开 WSL。只有装 Codex CLI 时才需要 Node.js。

### 模型怎么选？

| 你的需求 | 推荐模型 | 理由 |
|---|---|---|
| 日常与复杂编码主力 | `gpt-6.2-sol` | 1.05M 上下文 / 128K 输出，综合能力均衡 |
| 最难的多步 Agent 攻坚 | `gpt-6.2-astra` | 上一档旗舰，适合跨模块架构与长任务 |
| 轻量日常 / 批量任务 | `gpt-6.1-terra` / `gpt-5.6-terra` | 成本更低，针对代码场景优化 |
| 上一代高端模型 | `gpt-6-astra` | 仍可用，新任务建议切到 `gpt-6.2-astra` |

改默认模型就是改 `config.toml` 里的 `model` 那一行，保存后从托盘 `Exit` 重开。注意 `gpt-6.2-*` 不支持 `model_reasoning_effort = "none"`。

### 密钥到期后怎么办？

分两种情况：

- **个人套餐**的密钥到期后不能续，只能重新开通、换一把新密钥。
- **按量包**的密钥到期后再买一个包，同一把密钥会恢复。

换密钥后记得同步更新 `auth.json` 里的 `OPENAI_API_KEY`，再从托盘 `Exit` 重开应用。

### 费用怎么算？

桌面版和 Codex CLI、Claude Code 可以共用同一把 QCode API 密钥，费用按实际 token 消耗计算，不按工具区分。让 Codex 自主迭代多轮时，单次任务消耗可能高一些；可以在[控制台](https://qcode.cc/dashboard)查看用量和余额。

## 手动写配置（不用一键脚本）

一键脚本已经替你写好了两个文件。想自己写，或者要在 macOS 上对照配置，按下面做。桌面版和 Codex CLI 读的是同一份配置。

### 创建 config.toml

Windows（PowerShell）先建目录：

```powershell
mkdir $HOME\.codex
```

然后在 `%USERPROFILE%\.codex\config.toml` 写入：

```toml
model_provider = "qcode"
model = "gpt-6.2-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
```

### 创建 auth.json

在同一目录的 `auth.json` 里写入三行，键名必须是 `OPENAI_API_KEY`，引号和冒号都用英文半角：

```json
{
  "OPENAI_API_KEY": "cr_xxxxxxxx"
}
```

把 `cr_xxxxxxxx` 换成你自己的密钥。用记事本保存时，「保存类型」要选「所有文件」，文件名写 `auth.json`，否则会变成 `auth.json.txt`，应用读不到。

### 环境变量替代写法（二选一）

想改用环境变量传密钥，就把 `requires_openai_auth = true` 换成 `env_key = "QCODE_API_KEY"`，再设置这个变量。**两种写法只能选一种**：写了 `requires_openai_auth = true` 时，Codex 会忽略 `env_key`。

```toml
model_provider = "qcode"
model = "gpt-6.2-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
env_key = "QCODE_API_KEY"
```

```powershell
# 临时设置（当前会话）
$env:QCODE_API_KEY = "cr_xxxxxxxx"

# 永久设置（写入用户环境变量，设完要重开应用）
[System.Environment]::SetEnvironmentVariable("QCODE_API_KEY", "cr_xxxxxxxx", [System.EnvironmentVariableTarget]::User)
```

### config.toml 字段说明

| 字段 | 说明 |
|---|---|
| `model_provider` | 使用的模型提供商名称，这里设为自定义的 `qcode`。名字可以自定，只要与 `[model_providers.<名字>]` 保持一致 |
| `model` | 默认模型，推荐 `gpt-6.2-sol`；最难的任务选 `gpt-6.2-astra` |
| `model_reasoning_effort` | 推理强度，支持 `low`、`medium`、`high`、`xhigh`。`gpt-6.2-*` 不接受 `none`，建议保持 `high` 或 `xhigh` |
| `base_url` | QCode 接入点地址。桌面版写 `https://api.qcode.cc/openai`，末尾不带 `/v1`、不带斜杠 |
| `wire_api` | API 协议类型，Codex 目前只支持 `responses` |
| `requires_openai_auth` | 使用 OpenAI 格式的认证，密钥读自 `auth.json` 的 `OPENAI_API_KEY`。设为 `true` 时 Codex 会忽略 `env_key` |

一键脚本还会写入 `review_model = "gpt-6.2-sol"`、`windows_wsl_setup_acknowledged = true` 这类运行时设置，桌面版不用管，也不要手动改。

### 可用模型

通过 QCode 可以选用以下 Codex / GPT 模型：

| 模型 | 说明 | 推荐场景 |
|---|---|---|
| **`gpt-6.2-sol`** | 主力旗舰，1.05M 上下文 / 128K 最大输出；拒绝 `model_reasoning_effort = "none"` | 日常与复杂编码首选（推荐） |
| **`gpt-6.2-astra`** | 顶配旗舰，1.05M 上下文 / 128K 最大输出；同样拒绝 `none` | 最难的多步 Agent 与跨模块架构攻坚 |
| `gpt-6.1-terra` | GPT-6.1 中档，1.05M 上下文 | 日常编码 / 批量任务 |
| `gpt-5.6-terra` | GPT-5.6 旗舰，针对代码优化 | 编程 / Codex 场景 |
| `gpt-6-astra` | 上一代最强档 | 高端能力，新任务建议切到 `gpt-6.2-astra` |

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | GPT ✅（Responses 协议）· Claude ❌ · 国产模型 ❌（Responses 协议不服务国产模型）· Gemini ❌（QCode 暂不提供） |
| 协议与 Base URL | Codex 使用 OpenAI Responses：`config.toml` 里写 `base_url = "https://api.qcode.cc/openai"` + `wire_api = "responses"` |
| 配置位置 | Windows 在 `%USERPROFILE%\.codex\`（`config.toml` + `auth.json`），桌面版与 CLI 共用 |
| 其他接入点 | `https://asia.qcode.cc/openai`、`https://us.qcode.cc/openai`，和 `api.qcode.cc` 是同一套账号与密钥 |
| 官方文档 | [openai/codex](https://github.com/openai/codex) |