学习路线

这篇是本站的学习总入口，会随着教程数量增加持续更新。

前置教程：Codex 是什么
如果你还不知道 Codex 的定位和边界，先看前置教程，再回到本篇。

如果你不知道从哪里开始，就按这篇走。本站的默认路线不是“先讲一堆概念”，而是：

先认识 Codex -> 再安装登录 -> 再配置模型 -> 再让 Codex 读项目 -> 再让 Codex 小改代码 -> 再让 Codex 检查交付

更新规则：每新增一篇正式教程，都要回到本页更新“当前已完成”和“下一步学习”。

你应该先走哪条路线

如果你是 Windows 中文用户，推荐先走主线：

Windows 安装与启动
-> 选择一个 Codex 入口：桌面版 或 CLI
-> 完成对应入口的安装、登录和只读验证
-> 配置大模型总览
-> 国内大模型配置方案
-> 验证当前入口的模型配置
-> 第一次让 Codex 阅读项目
-> 第一次让 Codex 修改代码
-> 任务验收
-> Git 提交前检查

原因很简单：用户第一步不是让 Codex 干活，而是先把环境装好。

如果安装没跑通，后面的“配置模型、读项目、改代码、跑测试”都会变成空中楼阁。

安装完成后，学习重点就不再是让你手动敲很多命令，而是学会如何通过对话让 Codex 做事：

怎么描述目标
怎么限制范围
怎么要求 Codex 先读项目
怎么让 Codex 自己运行检查并解释输出
怎么看懂 Codex 的总结和 diff
怎么追问、纠偏、拒绝危险操作

当前已完成教程

下面这些页面现在已经可以阅读：

顺序	教程	作用
1	Codex 是什么	安装前先理解 Codex 的定位和边界
2	本站适合谁学习	先判断自己是不是该直接学 Codex，还是应该先回主站补开发基础
3	学习路线	当前这篇，负责告诉你先学什么后学什么
4	Codex 桌面版、CLI、IDE、Cloud 怎么选	先判断自己该从哪个入口开始
5	什么时候优先用桌面版	适合新手、需求拆解、代码审查和多任务管理
6	什么时候优先用 CLI	适合本地项目、构建测试、Git 状态和提交前检查
7	什么时候优先用 IDE 或 Cloud	IDE 适合当前文件和选中代码，Cloud 适合远程长任务和并行任务
8	Windows 安装与启动	准备 PowerShell、Git、Node.js、编辑器和练习项目
9	Codex CLI 安装与登录	安装 `codex` 命令、登录、进入项目并启动
10	Codex 桌面版安装与登录	安装桌面版、完成登录，明确它和 CLI 不是同一个安装入口
11	Codex 桌面版第一次选择项目	在桌面版里选择安全练习项目，并完成一次只读分析
12	桌面版如何使用国内大模型配置	讲清楚桌面版如何复用 `config.toml` 和 `.env`
13	CLI、桌面版、IDE 配置为什么能共用	解释用户级配置、项目级配置、环境变量和临时选择的关系
14	配置后怎么验证当前用的是哪个模型	用只读任务验证当前入口的模型配置是否可用
15	Codex IDE 扩展安装与登录	在 VS Code 或 Cursor 中安装扩展、登录并完成只读验证
16	IDE 里第一次解释当前文件	用 IDE 扩展解释当前文件和选中代码，全程不修改文件
17	IDE 里第一次做局部修改	只修改当前文件或选中代码，并通过对话控制范围
18	IDE、CLI、桌面版怎么配合	IDE 定位，CLI 验证，桌面版审查和任务管理
19	Codex Cloud 适合什么场景	讲清楚 Cloud 适合远程、长任务、并行任务，不适合新手第一入口
20	Codex Cloud 使用前准备	检查 GitHub、权限、MFA、环境、网络和安全边界
21	第一次创建 Codex Cloud 任务	创建只读 Cloud 任务，先分析仓库，不修改文件
22	Cloud 结果怎么带回本地	审查 Cloud 总结和 diff，再带回本地验证
23	配置大模型总览	先理解模型、provider、Base URL、API Key 和安全边界
24	国内大模型配置方案	安装后、实操前，规划 Codex 接入国内 OpenAI 兼容模型
25	Codex + DeepSeek 配置	第一篇国内服务商配置实操，从官方参数到只读验收
26	Codex + 通义千问/Qwen 配置	第二篇国内服务商配置实操，重点处理百炼地域和 Qwen 模型
27	Codex + Kimi 配置	第三篇国内服务商配置实操，重点处理 Kimi 模型名更新和兼容参数
28	Codex + 硅基流动配置	第四篇国内服务商配置实操，重点处理聚合平台模型名选择
29	Codex + 智谱 GLM 配置	第五篇国内服务商配置实操，重点处理通用端点和 Coding 端点
30	Codex + 豆包/火山方舟配置	第六篇国内服务商配置实操，重点处理推理接入点 ID
31	第一次让 Codex 阅读项目	配置模型后，先让 Codex 只读分析项目
32	20 分钟快速上手	用最短路径跑通一次从读项目到小修改的最小闭环
33	让 Codex 先读项目再动手	先让 Codex 建立项目上下文，再开始修改，减少乱猜和误判
34	第一次让 Codex 改代码	用对话限制范围，让 Codex 做单文件低风险修改并解释 diff
35	让 Codex 完成任务验收	改完代码后，看懂 Codex 的检查结果、漏检追问和失败收敛
36	一次 Codex 任务的完整闭环	把提需求、限范围、执行、检查和收尾串成可重复工作流
37	怎样给 Codex 补充上下文	学会补真正有用的上下文，让 Codex 少猜、少返工、少跑偏
38	怎样让 Codex 提问而不是乱猜	主动要求 Codex 在不确定时先澄清，而不是自作聪明推进
39	如何限制 Codex 只改你指定的范围	专门解决修改范围失控、顺手多改和任务打包的问题
40	怎样让 Codex 自己做必要检查	让 Codex 按项目实际情况判断并执行最小必要检查
41	Git 提交前检查	提交前检查 diff、无关文件、敏感信息、验收结果和提交说明
42	怎样写一个合格的 Codex 任务	把目标、范围、禁止事项、验收和汇报格式写清楚
43	修 Bug 任务模板	可复制的 Bug 修复模板库，覆盖前端、后端、构建和线上问题
44	新增页面任务模板	适合静态页、说明页、教程页和普通后台页面的新增任务
45	国内模型配置排障总表	按 API Key、Base URL、model、额度、网络和配置语法排查
46	常见问题	后续会扩展成排障手册
47	常见任务实战总览	把常见 Codex 任务沉淀成可照着做的案例
48	让 Codex 优化静态网站首页	练习视觉需求描述、限制范围、截图反馈和微调
49	让 Codex 修复前端 Bug	练习描述现象、复现步骤、期望结果和最小修复
50	让 Codex 排查构建失败	练习错误分类、定位文件、最小修复和验证总结
51	让 Codex 新增一个简单页面	练习路由、页面内容、导航入口和截图验收
52	让 Codex 补 README 或使用说明	练习基于真实项目结构写可靠说明，不编造命令
53	让 Codex 修改一段接口逻辑	练习接口定位、影响范围、最小修改和回归验证
54	AGENTS.md 是什么，为什么能让 Codex 更稳定	讲清楚项目规则应该沉淀到哪里，以及它和提示词、config.toml 的区别
55	第一次给项目添加 AGENTS.md	从只读分析、草稿审查、写入文件到小任务验证，完整跑一遍
56	config.toml 是什么，和 AGENTS.md 有什么区别	讲清楚 Codex 运行配置和项目做事规则的分工
57	用户级 config.toml 和项目级 .codex/config.toml 怎么选	讲清楚个人默认、项目专用配置、受信任项目和覆盖关系
58	MCP 是什么，为什么 Codex 需要它	讲清楚 MCP 是连接外部工具和资料的标准方式，不是万能插件
59	什么时候应该给 Codex 配 MCP，什么时候不该配	用判断清单区分提示词、AGENTS.md、config.toml、MCP、Skills 的边界
60	第一次配置只读文档 MCP	以低风险文档 MCP 跑通安装前确认、状态查看、只读查询和排障
61	Skills 是什么，为什么它比复制提示词更稳定	讲清楚 Skill 是可复用工作流程，以及它和提示词、AGENTS.md、MCP 的区别
62	什么时候应该做 Skill，什么时候继续用提示词	用判断清单避免过早把一次性提示词做成 Skill
63	第一次做一个 instruction-only Skill	以“写喂饭级教程”为例，设计、创建、触发和验证第一份 Skill
64	Hooks 是什么，为什么不能一上来乱配	讲清楚 Hooks 是生命周期自动化检查，不是普通提示词替代品
65	什么时候应该用 Hooks，什么时候不要用	用判断清单区分提示词、AGENTS.md、Skills、MCP 和 Hooks
66	第一次查看和审查 Hooks	不创建 Hook，先学会查看来源、事件、命令和信任状态
67	第一个低风险 Hook	用只输出提醒的 PreToolUse Hook 跑通创建、审查、信任、触发和回滚流程
68	Subagents 是什么	讲清楚子代理适合并行只读分析，不适合新手一上来并行改代码
69	第一次使用 Subagents 做只读评审	用 3 个子代理并行只读评审项目，练习拆分、/agent 查看、权限处理和汇总验收
70	什么时候需要自定义 Subagents	先判断是否真的需要固定子代理角色，再决定是否创建 custom agent
71	第一次创建自定义 Subagent	用项目级 `.codex/agents/` 创建只读教程审查子代理，并完成检查、调用和回滚
72	团队工作流：把 Codex 用成稳定流程	把 AGENTS.md、config.toml、MCP、Skills、Hooks、Subagents 组合成低风险可验收流程

第一阶段学习顺序

第一阶段目标只有一个：

让用户从 0 开始，把 Codex 在本地项目里跑起来，并完成一次可检查的小任务。

第 1 步：先认识 Codex

先看：

Codex 是什么

这一篇只负责讲清楚：

Codex 是什么。
Codex 和普通聊天机器人的区别。
Codex 有哪些入口。
Codex 能做什么。
Codex 不能替你保证什么。

这一篇不安排操作，因为此时用户可能还没有安装 Codex。

第 2 步：安装 Windows 基础环境

再看：

Windows 安装与启动

这一篇负责准备：

Windows 版本检查。
PowerShell。
Git。
Node.js LTS。
VS Code 或 Cursor。
安全练习目录。
练习项目。
Git 初始状态。

这一步必须非常细，因为中文 Windows 用户最常见的卡点都在这里。

第 3 步：安装并登录 Codex CLI

再看：

Codex CLI 安装与登录

这一篇负责：

安装 codex 命令。
验证 codex --version。
理解 ChatGPT 登录和 API Key 登录区别。
完成 codex login。
进入项目目录启动 Codex。
做一次只读验证。

第 4 步：配置大模型

接着看：

这一步负责讲清楚：

Codex 背后调用的是哪个模型。
国内模型为什么优先看 OpenAI 兼容接口。
Base URL、模型名、API Key 环境变量从哪里来。
为什么不要把真实 API Key 发给 Codex。
配置完成后为什么要先做只读验证。
第一篇服务商教程如何从官方参数走到可验收配置。
第二篇服务商教程如何处理地域、工作空间和模型权限。
第三篇服务商教程如何处理模型更新、下线模型和兼容参数。
第四篇服务商教程如何处理聚合平台的模型名、额度和模型权限。
第五篇服务商教程如何处理通用端点、Coding 端点和套餐权限。
第六篇服务商教程如何处理火山方舟推理接入点 ID、API Key 和模型可用性。

这一步不是为了让用户研究一堆高级配置，而是为了让后面的实操有一个明确、可排查、可验收的模型环境。

第 5 步：第一次让 Codex 阅读项目

接着看：

第一次让 Codex 阅读项目

这一篇会正式承接前面的只读验证，讲清楚：

什么时候可以让 Codex 读项目。
怎么要求 Codex 不修改文件。
怎么让 Codex 找入口、可用脚本、目录和风险点。
怎么判断它是不是在乱猜。
怎么把项目分析结果保存成后续任务上下文。

第 6 步：第一次让 Codex 修改代码

然后看：

第一次让 Codex 改代码

这篇后续要重写成完整教程，任务会选择低风险改动，比如：

改 README。
改页面文案。
改一个静态标题。
改一个简单样式。

不会一上来让 Codex 大改项目。

第 7 步：让 Codex 完成任务验收

接着看：

让 Codex 完成任务验收

这一篇负责讲清楚：

如何在任务开始前写验收标准。
如何看懂 Codex 修改后做了哪些检查。
如果 Codex 没检查，如何追问。
如果检查失败，如何先判断是否由本次修改引入。
如何让 Codex 只修本次任务相关问题。
如何得到最终交付判断。

第 8 步：Git 提交前检查

接着看：

Git 提交前检查

这一篇负责讲清楚：

如何让 Codex 检查提交前 Git 状态。
如何检查 diff、无关文件和敏感信息。
如何回顾验收结果。
如何让 Codex 生成不夸大的提交说明。
如何判断能不能进入提交。

第 9 步：补齐基础使用闭环

接着看：

这一组的作用不是增加概念，而是把你前面已经跑通过的安装、读项目、小修改和验收，真正串成可重复的日常做法。

这一阶段完成后，用户才算真正跑通了 Codex 最小闭环。

第二阶段学习顺序

第二阶段目标是：

让用户能稳定把 Codex 用在真实项目里，而不是只跑通一次演示。

Codex 工作方法

会补这些教程：

怎样写一个合格的 Codex 任务。
让 Codex 先读项目再动手。
如何限制修改范围。
如何要求 Codex 先提问。
如何让 Codex 写验收清单。
如何让 Codex 自己检查 diff 并用中文解释给你。

提示词模板

会补这些模板：

修 Bug 任务模板。
新增页面任务模板。
修改样式任务模板。
新增接口任务模板。
构建失败排查模板。
提交前检查模板。

模板不是为了让用户背提示词，而是让用户复制后能直接改变量。

排障手册

会补这些排障：

Codex 登录失败。
codex 命令找不到。
PowerShell 执行策略报错。
npm install 失败。
npm run build 失败。
Git 状态噪音较多。
文件改错了怎么办。
不小心批准危险命令怎么办。

第三阶段学习顺序

第三阶段目标是：

让 Codex 从“能用”变成“好用、稳定、可复用”。

桌面版、IDE 和 Cloud

会补这些入口：

Codex 桌面版第一次使用。
Codex 桌面版适合什么任务。
VS Code / Cursor 中使用 Codex。
选中代码让 Codex 局部解释。
Codex Cloud 适合什么任务。
云端任务结果如何带回本地。

配置大模型

会补这些教程：

配置大模型总览。
OpenAI 官方模型配置。
OpenAI 兼容接口是什么。
Codex + DeepSeek 配置。
Codex + 通义千问/Qwen 配置。
Codex + 智谱 GLM 配置。
Codex + Kimi 配置。
Codex + 豆包/火山方舟配置。
Codex + 硅基流动配置。

这一组教程必须逐篇实测，并且保留依据来源。国内模型服务的接口、模型名、控制台入口变化比较快，不能靠记忆写。

高级配置与扩展

会补这些内容：

AGENTS.md 入门。
项目级规则怎么写。
config.toml 入门。
MCP 入门。
Skills 入门。
Hooks 入门。
Subagents 入门。

第四阶段：实战案例库

实战案例不是“讲一个知识点”，而是把一个完整任务从头跑到尾。

会补这些案例：

用 Codex 做一个 Astro 静态教程站首页。
用 Codex 优化首页科技风样式。
用 Codex 增加站点 SEO。
用 Codex 修复 Nuxt 页面 SEO。
用 Codex 新增 Spring Boot 接口。
用 Codex 排查 Maven test 失败。

每个案例都要包含：

任务背景。
初始状态。
提示词。
Codex 做了什么。
修改了哪些文件。
怎么验证。
失败分支。
最终交付总结。

不同用户怎么选

完全新手

按这个顺序：

Codex 是什么。
Windows 安装与启动。
Codex CLI 安装与登录。
配置大模型总览。
国内大模型配置方案。
第一次让 Codex 阅读项目。
第一次让 Codex 修改代码。

不要跳过安装登录直接配置模型，也不要还没完成只读验证就直接让 Codex 改代码。

会写代码的开发者

按这个顺序：

Windows 安装与启动。
Codex CLI 安装与登录。
配置大模型总览。
国内大模型配置方案。
第一次让 Codex 阅读项目。
第一次让 Codex 修改代码。
让 Codex 完成任务验收。
怎样写一个合格的 Codex 任务。
Git 提交前检查。

你可以跳过部分概念，但不要跳过模型配置验收、环境验证和 Git 状态检查。

主要用编辑器的人

按这个顺序：

Windows 安装与启动。
Codex CLI 安装与登录。
配置大模型总览。
国内大模型配置方案。
IDE 扩展安装。
解释当前文件。
选中代码局部修改。
让 Codex 完成任务验收。

想配置国内大模型的人

按这个顺序：

Windows 安装与启动。
Codex CLI 安装与登录。
配置大模型总览。
国内大模型配置方案。
具体服务商配置教程。
配置失败排障。

不要还没跑通 Codex CLI 就直接配置模型。否则出了问题，你分不清是 Codex 没装好、登录没好、网络没好，还是模型服务商配置错了。

本页如何保持更新

每次新增正式教程，都要检查 4 件事：

这篇文章应该挂在哪个阶段。
当前已完成教程表格要不要新增一行。
“下一篇学什么”要不要更新。
是否需要把草稿文章改成“已完成”。

这样用户不需要猜顺序，永远从本页就能知道下一步该点哪里。

现在下一篇要写什么

当前下一篇最该写：

修改样式任务模板

原因：页面新增模板已经补上了，下一步最自然的是继续补“改样式任务模板”。这个场景非常高频，而且最容易发生范围失控，正好和前面刚补的“范围限制”形成一套。