Codex 桌面版下载安装与使用教程（2026）：Windows / macOS 客户端接入 API
更新于
Codex 桌面版是 OpenAI 官方的图形界面客户端，Windows 和 macOS 都能装。这篇讲清从哪里下载正版、怎么接入 API 快连（不需要 ChatGPT 订阅）、第一次怎么用、四种权限模式怎么选，以及打开就要求登录、401、模型下拉只显示 custom 等常见问题。
9PLM9XGG6VKS），macOS 从 OpenAI 官网下载 Codex.dmg；装好后在 ~/.codex/config.toml 里把服务商指向 https://apikl.ai/v1，彻底退出再打开就能用。| 项目 | 内容 |
|---|---|
| Windows 下载 | 微软商店，或命令 winget install --id 9PLM9XGG6VKS -s msstore |
| macOS 下载 | OpenAI 官方安装包 Codex.dmg（Apple 芯片） |
| 配置文件 | ~/.codex/config.toml，Windows 是 C:\Users\你的用户名\.codex\config.toml，和命令行、VS Code 插件共用 |
| Base URL | https://apikl.ai/v1（要带 /v1） |
| 推荐模型 | gpt-5.6-sol，先用它测通 |
| 要订阅吗 | 不需要 ChatGPT Plus，按 API 实际用量计费 |
桌面版、命令行、VS Code 插件有什么区别
| 版本 | 适合谁 | 特点 |
|---|---|---|
| 桌面版 | 不想用命令行、经常在几个项目之间切换 | 图形界面，按项目管理会话，可以同时开多个任务，文件和改动看起来更直观 |
| 命令行（CLI） | 习惯终端、要写脚本或在服务器上用 | codex 交互使用，codex exec 适合自动化，也能接 飞书机器人 |
| VS Code 插件 | 一边看代码一边用 | 在编辑器侧边栏里使用 |
三者读的是同一份 config.toml，配好一次都能用。从 API 快连后台看，近 7 天用 Codex 的用户里约八成用的是桌面版，其中大多数在 Windows 上。
下载安装
Windows
- 打开 微软商店里的应用页，点「获取」安装。OpenAI 已经把 Codex 桌面版并进了 ChatGPT 桌面应用，所以商店里显示的名字是 ChatGPT，下载的安装程序叫 ChatGPT Installer.exe。
- 也可以在 PowerShell 里用命令安装：
winget install --id 9PLM9XGG6VKS -s msstore。
winget install Codex -s msstore：按名字搜会装成商店里一个同名的二维码工具（OpenAI 开发者社区已有人反馈）。也不要从第三方下载站下载所谓的「Codex 中文版」安装包。我们后台看到 Windows 10（22H2）和 Windows 11 上都有用户在正常使用桌面版。
macOS
- 下载 OpenAI 官方安装包 Codex.dmg（约 780 MB）。
- 双击打开，把 Codex 拖进「应用程序」文件夹。
- 第一次打开如果提示「来自互联网」，点「打开」。
官方下载页目前只提供 Apple 芯片（M 系列）版本。官方也提供 Linux 版，安装方法见 OpenAI 官方文档。
接入 API 快连（三种方法选一种）
先在 控制台 创建一把密钥，分组选 GPT 类分组（例如 GPT-Pro）。下面三种方法任选一种，配好后都要彻底退出桌面版再打开：确认任务管理器（macOS 是程序坞）里已经没有它在运行，只关窗口不算。
方法 A：CC Switch 一键导入（推荐）
在控制台的密钥列表里点「导入到 CCS」，CC Switch 会把地址、密钥和模型写进 Codex 的配置文件，不用折腾环境变量，最适合桌面版。完整步骤看 CC Switch 配置教程。
方法 B：手动写 config.toml，密钥写在文件里
打开（没有就新建）~/.codex/config.toml，Windows 是 C:\Users\你的用户名\.codex\config.toml，写入：
我们用 Codex 0.162.1 实测过：这样写不依赖环境变量，桌面版从开始菜单或程序坞打开也能读到密钥。缺点是密钥以明文保存在本机文件里，只在自己的电脑上这么写，不要把这个文件发给别人。
方法 C：环境变量写法，密钥不进文件
更在意安全的话，配置文件里只写环境变量的名字：
然后按系统设置环境变量：
~/.zshrc 里的环境变量，这就是「终端里的 Codex 能用、桌面版却报错」最常见的原因。嫌每次重启都要重新设置，就用方法 A 或方法 B。各字段的含义、Key 怎么长期生效，看 Codex 配置教程。
第一次使用
- 打开桌面版，新建或打开一个项目文件夹。Codex 会读取和修改你选的文件夹里的文件。
- 在输入框下方选择权限模式（见下表），刚开始建议用 Ask for approval。
- 用一句话描述任务，比如「看一下这个项目的结构，告诉我怎么运行起来」。
- Codex 改完文件后先看改动再决定保留。重要项目建议先用 Git 提交一次，再让它动手，改坏了能退回。
| 权限模式 | 含义 | 什么时候用 |
|---|---|---|
| Ask for approval | 在项目目录里工作；改外部文件、联网前先问你 | 大多数情况，官方也建议从它开始 |
| Approve for me | 只有被识别为可能不安全的操作才问你 | 熟悉之后，想少点确认 |
| Full access | 不受限地访问网络和电脑上的任意文件 | 尽量不用 |
| Custom (config.toml) | 按 config.toml 里自定义的权限 | 需要精细控制时 |
界面语言不同时名称可能显示为中文，以英文名对照即可。可选项也会随版本和系统变化。
怎么切换模型
- 默认模型由 config.toml 里的
model决定，先用gpt-5.6-sol测通，再按需要换。 - 用第三方 API 时，桌面版的模型下拉框可能只显示
custom，或者干脆不显示。这是 OpenAI 那边还没修的已知问题（GitHub 上的 openai/codex #37379）。直接改 config.toml 里的model，再彻底退出重开就行。 - 有哪些模型、各多少钱，看 模型广场；Codex 怎么选模型看 Codex 配置教程。
Windows 用户注意
- 桌面版在 Windows 上默认原生运行，命令在 PowerShell 里执行，不需要装 WSL。想让它在 WSL 里跑，到设置里把 Agent 从 Windows native 改成 WSL，再重启应用。
- 需要管理员权限的命令：在开始菜单里右键桌面版，选「以管理员身份运行」，Codex 执行的命令会继承管理员权限。
- Git 相关功能用不了：先安装 Git，
winget install Git.Git。 - WSL 里的 Codex 命令行想和桌面版共用配置：在 WSL 里设置
export CODEX_HOME=/mnt/c/Users/你的用户名/.codex。
PowerShell 提示「禁止运行脚本」时，执行：
常见问题与报错
一打开就要求登录 ChatGPT
说明桌面版没读到自定义服务商。检查 config.toml 是否放在 ~/.codex/（Windows 是 C:\Users\你的用户名\.codex\）、里面有没有 model_provider = "apikl"，保存后彻底退出再打开。
报 401，或提示 Missing environment variable: OPENAI_API_KEY
桌面版读不到环境变量：改用上面的方法 A 或方法 B。如果是密钥本身复制错了、被停用或额度用完，看 401 invalid_api_key 怎么解决。
模型下拉框只显示 custom
已知问题，不影响使用。改 config.toml 里的 model 来换模型，见上面「怎么切换模型」。
让 Codex 生成图片报 403
内置的生图功能按 OpenAI 官方账号校验，用第三方 API 时会返回 403。改为让 Codex 调用 gpt-image-2 图片接口，写法见 Codex 配置教程里的「在 Codex 中通过 API 快连生成图片」。
经常「重新连接」或 stream disconnected
偶尔出现是网络或上游短时波动，Codex 会自动重连。持续出现可以把 base_url 换成不经过 CDN 的直连线路 https://dc.apikl.ai/v1（同样带 /v1）。
Codex 桌面版要钱吗？需要 ChatGPT Plus 吗？
应用本身免费下载。接入 API 快连后按实际用量计费，不需要 ChatGPT 订阅，也不需要海外信用卡。官方文档也注明，用 API Key 时部分功能可能用不了。
Codex 桌面版和 ChatGPT 桌面版是什么关系？
OpenAI 已经把两者合并成一个桌面应用。Windows 商店里叫 ChatGPT，macOS 安装包仍叫 Codex.dmg，我们后台看到的客户端名称是 Codex Desktop，说的都是这个应用。
桌面版和命令行能同时用吗？
能。两者共用 ~/.codex/config.toml，配置一次就行。想在手机上远程用 Codex，可以看 Codex 接入飞书教程。