本文最后更新于 2026-05-12，文章内容可能已经过时。

Codex Desktop App 完全上手指南

这是一篇完整独立的 Codex Desktop App 上手教程。照着做，你可以完成下载安装到 API Key 配置、auth.json / config.toml 创建、客户端指定配置路径、中文界面切换和最终测试。

本文默认使用 8848AI API：https://api.884819.xyz/v1。

一、Codex Desktop App 是什么

Codex Desktop App 是 OpenAI 提供的桌面客户端，适合在本地电脑上直接与 Codex 交互，辅助完成代码编写、改代码、排查 bug、写测试、整理文档等任务。

官方介绍页面：

注意：国内用户通常需要先保证网络可访问，再打开官网页面。

二、Codex Desktop App 下载方法

1. macOS 下载方式

macOS 用户最方便，直接打开下面的链接下载安装包：

2. Windows 下载方式

Windows 用户可以通过微软官方页面下载安装：

打开链接后，按微软安装提示完成安装即可。安装完成后，应用通常会自动启动。

三、安装完成后为什么还不能直接用

很多人安装好后发现，软件并不能立刻使用。这通常是因为 Codex Desktop App 还需要先配置 API Key。

  • 如果你以前已经在这台机器上使用过 Codex CLI，桌面版通常会直接读取已有配置。
  • 如果你以前没有配置过，就需要手动设置一次。

四、如何配置 API Key

第一步：创建APIkey

在8848中创建好API并复制，格式通常为：

sk-xxx

第二步：创建配置文件

Codex Desktop 的配置文件位于用户主目录下的 .codex 文件夹中。
这里需要创建两个文件：

  • auth.json
  • config.toml

配置目录位置

Windows：

C:\Users\<你的用户名>\.codex\

macOS：

/Users/<你的用户名>/.codex/

Windows 用户操作步骤

  • 打开文件资源管理器，进入：
C:\Users\<你的用户名>\
  • 如果看不到 .codex 目录，先开启 显示隐藏的项目
    路径：查看 → 显示 → 隐藏的项目
  • 如果没有 .codex 文件夹，就手动创建一个
  • 在里面再创建两个文件：
auth.json
config.toml

macOS 用户操作步骤

打开终端（Terminal），执行下面这几条命令：

mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml

第三步：编辑 auth.json

把下面内容写入 auth.json，把其中的 sk-xxx 替换成你自己的 API Key：

{"OPENAI_API_KEY": "sk-xxx"}

如果这个文件里已经有别的内容，直接覆盖即可。

📌 这里最常见的问题就是 Key 没替换完整，或者多复制了空格、引号，建议保存前顺手检查一遍。

第四步：编辑 config.toml

把下面内容写入 config.toml：

model_provider = "8848"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.8848]
name = "api111"
base_url = "https://api.884819.xyz/v1"
wire_api = "responses"

各配置项说明

  • model_provider —— 自定义提供商名称，需要和下方 [model_providers.xxx] 对应
  • model —— 使用的模型名称，可选 8848中的模型等
  • model_reasoning_effort —— 模型思考努力程度，可选 high、medium、low
  • disable_response_storage —— 禁用响应存储，建议开启
  • preferred_auth_method —— 认证方式，使用 API Key 时设为 apikey
  • base_url ——8848中转 API 地址
  • wire_api —— API 协议格式，Codex 使用 responses

💡 切换模型：
如果你想使用最新的 gpt-5.5，把这一行：

model = "gpt-5.3-codex"

改成：

model = "gpt-5.5"

就可以了。

第五步：Desktop 客户端内指定配置路径（可选）

正常情况下，Codex Desktop 会自动读取 .codex 目录下的配置文件。
如果你明明已经配好了，但客户端里还是没生效，可以手动指定一次配置路径。

操作方法：

  • 打开 Codex Desktop
  • 进入 设置 → 配置
  • 在 Custom config.toml settings 下的 user config 中填写配置文件路径

路径如下

Windows：

C:\Users\<你的用户名>\.codex\config.toml

macOS：

/Users/<你的用户名>/.codex/config.toml

📌 这个步骤不是必需的，但如果你遇到“配置明明写了却没反应”的情况，手动指定路径通常很有用。

配置成功后，重新打开 Codex Desktop App，随便发送一条消息测试。如果能正常回复，就说明已经可以使用。

五、如何把 Codex 桌面版切换成中文

Codex Desktop App 默认界面通常是英文，如果你想切换成中文，可以按下面步骤操作：

  1. 打开软件。
  2. 点击左上角 File。
  3. 点击 Settings。
  4. 进入 General。
  5. 找到 Language / Language for the app UI。
  6. 在下拉框中选择 中文（中国）。

切换中文时的注意事项：

  • 如果切换后没生效，可能是应用需要联网下载语言包。
  • 先保证网络可用，再重新进入设置切换一次。
  • 必要时重启应用后再试。

最快检查清单

如果配置后不能用，按下面顺序排查：

  • auth.json 是否放在 .codex 文件夹里；
  • config.toml 是否放在 .codex 文件夹里；
  • auth.json 里的 OPENAI_API_KEY 是否写对；
  • sk-xxx 是否已经替换成你自己的 API Key；
  • base_url 是否是 https://api.884819.xyz/v1，末尾不要有空格；
  • wire_api 是否是 responses；
  • Windows 文件名是否误变成 auth.json.txt 或 config.toml.txt；
  • Codex Desktop App 是否已经重启；
  • 如果没有自动读取配置，是否在客户端里手动指定了 config.toml 路径。

配置成功后，可以直接发这句话测试：

你好，请用一句话回复，确认你可以正常工作。

能正常回复，就说明 Codex Desktop App 已经通过 api.884819.xyz 跑通了。