Codex 桌面端安装与设置

用图形界面管理项目、查看修改并运行 Codex 任务。当前官方 Codex App 下载文档已转向 ChatGPT 桌面应用，其中包含 Codex 入口。

1. 安装桌面应用

Windows

通过官方 Windows 下载入口安装，也可以在 PowerShell 中使用以下命令。

PowerShell

winget install --id 9PLM9XGG6VKS -s msstore

Windows 官方安装说明 ↗

官方新版桌面应用名为 ChatGPT，安装后选择其中的 Codex 工作入口。

Linux

Linux 桌面端目前为预览版。先在官方页面核对支持的发行版，按 CPU 架构下载 .deb 或 .rpm 安装包。

查看 CPU 架构

uname -m

Ubuntu / Debian 的 x64 安装示例；ARM64 请替换安装包名称。

Ubuntu / Debian

cd ~/Downloads
sudo apt install ./chatgpt_amd64.deb

Fedora 安装方式

cd ~/Downloads
sudo dnf install ./chatgpt.x86_64.rpm

Linux 官方安装包与支持范围 ↗

官方新版桌面应用名为 ChatGPT，安装后选择其中的 Codex 工作入口。

macOS

从官方页面下载 macOS 安装包，打开后按提示将应用移入 Applications，再启动应用。

打开官方桌面端下载说明 ↗

官方新版桌面应用名为 ChatGPT，安装后选择其中的 Codex 工作入口。

2. 接入 Supakook

在 Supakook API 控制台获取 API 密钥、Base URL 和可用模型标识。先完全退出应用，再配置下面的信息。

先备份已有配置，再合并下面的字段。保留原有 MCP、项目和权限设置，避免重复添加同名配置项。

Windows

用户配置文件： %USERPROFILE%\.codex\config.toml

打开配置文件

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

Linux

用户配置文件： ~/.codex/config.toml

打开配置文件

mkdir -p ~/.codex
touch ~/.codex/config.toml
nano ~/.codex/config.toml

macOS

用户配置文件： ~/.codex/config.toml

打开配置文件

mkdir -p ~/.codex
touch ~/.codex/config.toml
open -e ~/.codex/config.toml

这是一份配置模板。 将 MODEL_ID_FROM_CONSOLE 替换为控制台支持的模型标识，将示例地址整段替换为交付的 Base URL。不要自行重复追加 /v1 或 /responses。

config.toml

model_provider = "supakook"
model = "MODEL_ID_FROM_CONSOLE"

[model_providers.supakook]
name = "Supakook"
base_url = "https://api.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

保存配置后完全退出并重新打开桌面应用，选择 API Key 登录方式，输入自己的 Supakook API 密钥。这里使用 requires_openai_auth；不要同时套用 CLI 的 env_key 配置。

这是自定义 provider 的 API Key 模式，不使用 ChatGPT 订阅登录替代 Supakook 密钥。CLI 与桌面端可能共享用户配置，切换前请保留备份；本页和 CLI 页中的认证配置选择一种即可。

3. 打开项目并验证

1. 在应用中选择 Codex，打开你的本地项目文件夹。
2. 检查所选 provider 与模型，确认与 Supakook 配置一致。
3. 先发送“阅读 README 并概括项目，暂不修改文件”这样的简单任务。
4. 核对控制台调用记录，确认请求已通过预期的 API 服务。

第三方 API 接入用于对应的本地 Codex 工作流。云端、插件、网页搜索等功能是否可用，取决于客户端版本、登录方式及接口支持范围。

常见问题

修改后仍使用旧配置

完全退出应用并重开；检查是否存在项目级配置或不同的 CODEX_HOME。如果同时使用 WSL、远程主机或 CLI，应确认当前任务实际在哪个环境运行。

显示模型或认证错误

核对 Base URL、模型标识与密钥权限。确认当前使用 API Key 登录；不要把 requires_openai_auth 与另一套 env_key 配置混用。

官方下载页面与旧教程名称不同

按当前官方页面下载安装。Linux 预览版的发行版与架构支持范围，以下载页为准；不从非官方教程安装重新打包的客户端。

参考来源

安装参考 官方桌面端指南、Windows 指南和 Linux 指南。API 登录与 provider 配置参考 官方认证说明和 自定义 provider。