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的安装命令如下：

1
2
3
4
5
6
7
8

# 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 放进去：

1
2
3

{
  "OPENAI_API_KEY": "sk-你的APIYI密钥"
}

2）config.toml——把模型供应商指向 API易： 如果是全新文件，直接写入下面内容；如果已有文件，把”全局键”加到文件最顶部、把 [model_providers.apiyi] 整段加到文件最末尾（原因见下方提示）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# === 全局（放在文件最顶部）===
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 获取）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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的界面如下

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

# 全局配置

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

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

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

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

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

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

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

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

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

二、官方内置技能三件套（1-3）

Codex 自带三个技能，很多人没注意，但它们是"技能的技能"，先认识它们，后面 12 个才能装起来。

• 1. skill-creator ⭐⭐⭐， 这个我就不多说了，创建技能的技能，每个 Agent 必备的原始技能。
• 2. skill-installer ⭐⭐⭐， 装技能的技能。先看看货架上有什么：看中了哪个，一行命令进肚。
• 3. plugin-creator ⭐， 把自用技能打包成插件分享给团队。

三个都在官方技能目录 openai/skills 的 .system 里，随 Codex 自动装好，无需下载（同目录还有 imagegen 和 openai-docs）。OpenAI 没先建货架，先给了你生产工具，态度很明显：技能这东西，攒比买重要。

三、开发流程套件

筛过的标准就一条：高频出现，装了确实比裸问 AI 靠谱。

1. create-plan ⭐⭐⭐，先规划后动手。  强制 Codex 在写第一行代码前产出实现计划，治"AI 上来就猛写、写完发现方向错了"。来自社区精选仓库 awesome-codex-skills。 安装方式：`$skill-installer create-plan

7. grill-me ⭐⭐⭐，让 AI 反过来拷问你。 你提需求，它连环追问，每个分支聊清楚才放你走。多数人用 AI 的短板不是 AI 不行，是需求没想清楚，它把"想清楚"变成一场被迫完成的对话。 地址：github.com/mattpocock/skills（24 万星）。

8. tdd ⭐⭐⭐，测试先行的老手艺。  红绿重构循环：先写失败的测试（红），写实现让它通过（绿），再重构。AI 猛写代码的冲动被测试摁住了。 地址：github.com/mattpocock/skills。

9. diagnosing-bugs ⭐⭐⭐，纪律化调试。 AI 修 bug 最大的毛病是"猜一个原因改一版试试"。这个技能定了纪律：先系统定位、收集证据，证据够了才动手。tdd 管让 bug 少生，它管 bug 生了怎么治。 地址：github.com/mattpocock/skills。

10. humanizer-zh ⭐⭐⭐，去 AI 腔。 清洗 AI 文本里的机翻味：delve、leverage、此外、值得注意的是，README 和提交信息是重灾区。一个专门治 AI 腔的技能活在 AI 编程工具里，多少有点黑色幽默。 地址：https://github.com/op7418/humanizer-zh

四、两个硬核补充

前面八个管"把活干对"，这两个把别的世界接进来：一个把你读过的书接进来，一个把浏览器接进来。

12. book-to-skill ⭐⭐，把读过的书接进 Codex。 丢给它一本 PDF（你自己买的），它拆成结构化技能：核心心智模型、每章一个文件、一份速查表。章节按需加载，问到才读，官方实测 token 消耗只有直接塞整本 PDF 的 1/24 到 1/51。 地址：github.com/virgiliojr94/book-to-skill（27.2k 星） 安装 npx skills add virgiliojr94/book-to-skill。

13. playwright ⭐⭐⭐，把浏览器交给 Codex 开。 官方精选区技能：从终端自动化真实浏览器，填表、截图、抓数据，前端改完让它真机验证，抓竞品页面数据也靠它。 安装方式：$skill-installer playwright，还有个交互变体 playwright-interactive 可以持久化浏览器会话来调试 UI。