Codex Desktop

本页介绍如何下载安装 Codex 桌面端，并通过 AIRouter 中转站接入可用模型。

适用场景

如果你希望在本地使用 Codex 桌面端完成代码阅读、修改、运行命令和项目管理，可以按本文配置 Codex 的本地认证文件与模型提供方。

提示

Codex 桌面端本质上仍需要可用的 API Key、模型权限和网络连接。配置完成后，优先通过 AIRouter「使用日志」确认请求是否成功。

一、下载安装 Codex 桌面端

打开 OpenAI 官方下载页：

https://chatgpt.com/zh-Hans-CN/download/

页面中包含 ChatGPT 桌面版、移动版和 Codex 下载区。请找到「下载 Codex」区域，根据系统选择对应版本：

系统操作
macOS点击 Codex 的 macOS 下载入口，下载后按提示安装
Windows点击 Codex 的 Windows 下载入口，跳转到 Microsoft Store 或安装页

安装完成后，先启动一次 Codex，让它生成本地配置目录；随后完全退出 Codex，再进行下面的配置。

二、准备 AIRouter API Key

  1. 登录 AIRouter 控制台：https://aigc.aochengcloud.com。
  2. 进入「API Keys」页面。
  3. 创建或复制一个可用 API Key。
  4. 确认账号余额、模型权限和 API Key 状态正常。

注意

API Key 是账号凭证，不要发给他人，也不要提交到 Git 仓库。本文示例中的 你的中转站 API Key 需要替换为你自己的真实 Key。

三、找到 Codex 本地配置目录

Codex 的本地配置通常放在用户目录下的 .codex 文件夹。

系统配置目录
macOS / Linux~/.codex
Windows%USERPROFILE%\.codex

目录中重点关注两个文件：

文件作用
auth.json保存 API Key
config.toml配置模型、推理强度、网络访问和 API 地址

如果目录或文件不存在，可以手动创建。

四、配置 auth.json

在 .codex 目录下创建或编辑 auth.json：

{
  "OPENAI_API_KEY": "你的中转站 API Key"
}

填写时注意：

  • 只替换引号内的 Key，不要删除字段名。
  • Key 前后不要带空格、换行或其他隐藏字符。
  • 如果你复制的是 AIRouter 控制台中的 Key，建议先粘贴到纯文本编辑器检查一次。

五、配置 config.toml

在 .codex 目录下创建或编辑 config.toml：

model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
network_access = "enabled"

[model_providers.OpenAI]
base_url = "https://aigc.aochengcloud.com/v1"
requires_openai_auth = true

如果你使用的是其他中转站域名，请把 base_url 改成自己的地址：

base_url = "https://你的中转站域名/v1"

关键点

base_url 末尾必须带 /v1。很多接入失败都是因为写成了 https://你的中转站域名，漏掉了 /v1。

配置项说明

配置项说明
model_provider指定使用哪个模型提供方配置，这里对应下方的 OpenAI
modelCodex 默认使用的模型
review_modelCodex 进行代码审查时使用的模型
model_reasoning_effort推理强度，xhigh 适合复杂代码任务
network_access是否允许 Codex 访问网络，部分任务需要开启
base_urlAIRouter 或其他中转站的 OpenAI 兼容 API 地址
requires_openai_auth使用 OpenAI 兼容认证方式读取 OPENAI_API_KEY

六、重启并验证

配置完成后，按以下顺序验证：

  1. 完全退出 Codex 桌面端。
  2. 重新打开 Codex。
  3. 选择一个本地项目目录。
  4. 发送一个简单任务，例如“读取项目结构并总结技术栈”。
  5. 打开 AIRouter「使用日志」，检查是否出现 Codex 发起的请求。

如果日志中出现成功请求，说明本地配置已经生效。

七、常见问题排查

启动后仍然走官方地址

优先检查：

检查项处理方式
配置文件位置确认修改的是当前系统用户目录下的 .codex
配置是否被覆盖检查是否有其他 Codex 配置文件或环境变量覆盖
Codex 是否完全退出退出托盘、菜单栏或后台进程后再重新打开
model_provider 是否匹配model_provider = "OpenAI" 要和 [model_providers.OpenAI] 对应

认证失败

常见原因：

  • auth.json 里的 Key 写错、复制不完整或带了空格。
  • API Key 已被删除、禁用或过期。
  • 当前账号余额不足，或 API Key 没有目标模型权限。
  • requires_openai_auth 没有设置为 true。

排查时可以先在 AIRouter 控制台重新复制 Key，再替换 auth.json。

请求超时

重点检查网络链路：

检查项说明
域名解析本机是否能解析中转站域名
防火墙公司网络、防火墙或代理是否拦截请求
Nginx反向代理是否正确转发 /v1 路径
SSLHTTPS 证书是否有效，证书链是否完整
上游状态AIRouter 使用日志中是否有请求进入

如果 AIRouter 日志没有任何记录，通常说明请求还没有到达中转站，需要先排查本机网络、代理或域名配置。

模型或额度不显示

Codex 桌面端界面不一定会展示中转站的模型列表、额度或计费信息，这是正常现象。接入是否成功，主要看两点：

  1. Codex 是否能正常返回结果。
  2. AIRouter「使用日志」是否出现对应请求，并显示成功状态。

模型不存在或无权限

如果日志提示模型不存在、无权限或分组不支持：

  1. 到 AIRouter 控制台「模型」页面确认可用模型 ID。
  2. 把 config.toml 中的 model 和 review_model 改成账号可用模型。
  3. 确认 API Key 没有限制该模型。
  4. 完全退出 Codex 后重新打开。

推荐配置流程

新用户建议按这个顺序排查，效率最高：

  1. 先确认 AIRouter API Key 可用。
  2. 再确认 base_url 以 /v1 结尾。
  3. 然后完全退出并重启 Codex。
  4. 最后通过 AIRouter「使用日志」判断请求是否成功进入中转站。

这样可以把问题快速拆成三类：本地配置问题、网络链路问题、账号或模型权限问题。

最后更新: