# Codex桌面版使用指南

Codex 是 OpenAI 官方出品的 AI 编码工具，能理解你的需求，帮你写代码、跑命令、调 Bug。

Codex 具有**四种运行模式**，覆盖你能想到的大部分使用场景：

- **CLI（命令行）**，在终端里跑，适合命令行党，主打一个黑框里掌控全局。
- **App（桌面应用）**，有图形界面，支持 macOS 和 Windows，适合不想跟终端互相折磨的人。
- **Web（网页版）**，打开浏览器就能用，不用装任何东西。出差用别人电脑、临时改个代码，随开随用。
- **IDE 插件**，支持 VS Code、Cursor、Windsurf。写代码的时候直接在编辑器里调用，不用切窗口，不用复制粘贴，代码上下文自动带过去。

## 安装Codex
App 安装可以去OpenAI的Codex官网下载安装：https://chatgpt.com/zh-Hans-CN/codex/

对于CLI的安装命令如下：
```
# npm 安装  
npm install -g @openai/codex  
  
# Homebrew 安装（macOS）  
brew install --cask codex

# 验证
codex --version
```

## 配置认证
Codex的认证有两种方式，第一种是你如果有ChaptGPT订阅账号最方便。但是账号比较难申请，这里我就不演示了。另一种是直接通过API Key的方式登录。
Codex 的各个客户端形态——Codex CLI、ChatGPT 桌面端、VS Code 的 Codex 插件（Codex IDE extension）——共用同一份配置文件
### 接入API易
参考文档：https://docs.apiyi.com/scenarios/programming/codex-cli

配置目录：`%USERPROFILE%\.codex\`（即 `C:\Users\你的用户名\.codex\`）。用文件资源管理器进入该目录。
**1）`auth.json`——把 Key 放进去：**
```
{
  "OPENAI_API_KEY": "sk-你的APIYI密钥"
}
```

**2）`config.toml`——把模型供应商指向 API易：**
如果是**全新文件**，直接写入下面内容；如果**已有文件**，把”全局键”加到文件**最顶部**、把 `[model_providers.apiyi]` 整段加到文件**最末尾**（原因见下方提示）。
```
# === 全局（放在文件最顶部）===
model = "gpt-5.4"                 # 默认模型，可按需改成 gpt-5.5 等
model_provider = "apiyi"          # 使用下面定义的 apiyi 供应商
preferred_auth_method = "apikey"  # 用 API Key 认证（不要用 chatgpt 登录）

# === API易 供应商定义（放在文件最末尾）===
[model_providers.apiyi]
name = "apiyi"
base_url = "https://api.apiyi.com/v1"
experimental_bearer_token = "sk-你的APIYI密钥"
wire_api = "responses"
```

还有一种管理认证的方式，就是用cc-switch。不想手动编辑文件，可以用 **CC Switch**——一个图形界面工具，点几下就能把 API易 的地址、Key、模型写进 Codex 配置，还能统一管理 Claude Code、Codex、Gemini CLI 等多款工具，一键切换。它也会自动处理上面的备份/合并，新手可优先考虑。配好后，Codex 的桌面客户端 / 插件 / CLI 都会自动读到这份配置。

### 接入DeepSeek
参考官方文档：https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/codex

首先，创建模型目录文件 `~/.codex/models.json`，向 Codex 声明 DeepSeek 模型的元数据。文件内容如下（与一键脚本写入的内容一致，包含 `deepseek-v4-flash` 与 `deepseek-v4-pro` 两个模型）：具体内容直接复制官网内容，这里就不显示了。

然后，编辑 Codex 配置文件 `~/.codex/config.toml`（不存在则新建），添加以下内容。其中 `experimental_bearer_token` 填入你的 API Key（在 [DeepSeek Platform](https://platform.deepseek.com/api_keys) 获取）：
```
model_provider = "deepseek"
model = "deepseek-v4-flash"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/models.json"

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "<Your API Key>"
```

### 接入GLM
参考官方文档：https://docs.bigmodel.cn/cn/coding-plan/tool/codex

首先，创建模型目录文件`~/.codex/models.json`，向Codex 声明 GLM 模型的元数据。若文件或目录不存在，请先创建。

然后，编辑 Codex 配置文件 `~/.codex/config.toml`（不存在则新建），添加以下内容。其中 `experimental_bearer_token` 填入你的 API Key
```
model_provider = "ZAI"
model = "glm-5.3"
model_reasoning_effort = "max"
model_catalog_json = "~/.codex/models.json"

[model_providers.ZAI]
name = "ZAI"
base_url = "https://open.bigmodel.cn/api/v1"
wire_api = "responses"
experimental_bearer_token = "<Your API Key>"
```

## 配置APP
安装后打开桌面版APP的界面如下
![](https://static.xiongneng.me/2026-08-09-135607.png)

中间这一大块，就是我们平时的对话区，跟平时用的AI聊天差不多。左边栏是来管理你的所有对话和项目。这里分两个目录，一个叫对话，一个叫项目。对话适合不需要绑定到特定文件夹的任务，比如做做调研、做做规划，这些零碎的小任务里。项目才是Codex真正的主战场。

选一个本地文件夹作为项目目录，Codex就会以这个文件夹为工作区间，所有生成的文件都会自动存进去。一个项目里可以开好几个对话，每条对话就是一条独立的任务线，它们共享同一个文件夹里的文件，但记录互相隔离。

如果你所有事情都堆在同一个对话里，记录越来越长，上下文污染会很严重。所以最好的是，同一个方向的任务放同一个项目，具体的每件事开一条新对话去推进。

点击设置 -> 常规 -> 权限，把三个权限开关都打开。在编辑器中，将跟进处理方式修改为`调整方向`。这样你发现中途你想修改的时候就可以直接插入，而不是必须等着那个任务做完才能进行新一轮的对话。

接下来，设置AGENTS.md。这是从上往下分层穿透的约束体系，也就是你给codex设置的家法。第一层全局生效的AGENTS.md。在个性化设置的自义定指令里修改。他是你为codex提供的全局通用的规则。这个设好了，不管你以后开多少个新对话，他都会记得。给大家推荐一个我觉得不错的来自大神卡帕西的模板，可以直接复制粘贴使用。
```
# 全局配置

## 语言规则
- 所有回答都使用中文
- 技术术语可以保留英文，但是要提供中文解释
- 代码注释使用中文
- 文档和说明优先使用中文编写

**例外情况**：
- 代码本身（变量名、函数名等）可以使用英文
- 命令行指令保持原样
- 配置文件内容根据实际需要决定语言

## 1. 先思考，后编码
**不要想当然。不要掩饰困惑。主动暴露取舍。**  
在实现之前：  
- 明确陈述你的假设。若有不确定，请提问。  
- 若存在多种理解方式，请列出来——不要自行默默选一个。  
- 若有更简单的做法，请说出来。在有充分理由时，可以提出异议。  
- 若有不清晰之处，停下来。指出哪里令人困惑，然后提问。

## 2. 简单优先
**用最少的代码解决问题。不做推测性工作。**  
- 不添加未要求的功能。  
- 不为一次性使用的代码构建抽象。  
- 不提供未被要求的“灵活性”或“可配置性”。  
- 不为不可能发生的场景编写错误处理。  
- 如果你写了 200 行代码，而 50 行就能解决，请重写。  
问问自己：“资深工程师会觉得这过于复杂吗？” 如果是，就简化。

## 3. 手术式改动
**只动必须动的地方。只清理自己造成的混乱。**  
编辑现有代码时：  
- 不要“改进”相邻代码、注释或格式。  
- 不要重构没有问题的东西。  
- 匹配现有风格，即使你个人更喜欢其他写法。  
- 如果发现不相关的死代码，可以提及——但不要删除。  
当你的改动产生“孤儿”代码时：  
- 移除因**你的改动**而不再使用的导入/变量/函数。  
- 除非被要求，否则不要移除先前已存在的死代码。  
检验标准：每一行改动都应直接追溯到用户的请求。

## 4. 目标驱动执行
**定义成功标准，循环执行直至验证通过。**  
将任务转化为可验证的目标：  
- “添加校验” → “为无效输入编写测试，然后让测试通过”  
- “修复 bug” → “编写一个能复现该 bug 的测试，然后让测试通过”  
- “重构 X” → “确保重构前后测试均通过”  

对于多步骤任务，简要陈述计划：  
1. [步骤] → 验证：[检查项]  
2. [步骤] → 验证：[检查项]  
3. [步骤] → 验证：[检查项]  

强有力的成功标准让你能独立循环推进。弱标准（如“让它工作”）则需要不断澄清。
```

然后记忆的两个功能，我推荐都可以在设置下的个性化中打开。将`启用本地记忆`和`允许基于工具辅助聊天生成本地记忆`都打开。打开以后，它会在你结束对话或者闲置了一段时间之后，自动把之前的对话总结成记忆片段保存下来，以后遇到相关的场景会自动调出来用。



---

> 作者: XiongNeng  
> URL: https://xiongneng.me/posts/ai/codex-desktop-handbook/