Codex 使用教程：从选择入口到完成第一个代码任务（2026）
开始使用 Codex，先选入口，再确认登录与权限，最后用一个能验收的小任务跑通流程。 不需要先购买不明来源的 Key，也不需要一开始就替换 API 地址。本文面向有本地代码仓库、希望让 Codex 读代码、修改文件和运行检查的开发者。
本文于 2026 年 10 月 24 日依据 OpenAI 官方文档整理。流程图和任务模板为本站编写；没有用你的账号实测所有操作系统、套餐或第三方网关。客户端界面与可用模型请核对当前官方文档和账号界面。
如果你要把 coding 模型接入自建工具，或验证自定义网关，可先打开 api.clawsocket.com 核对文档。当前支持的模型、路径、配额、价格、限制，以 api.clawsocket.com 控制台当前显示为准。 官方 Codex 的登录权益与第三方 API 额度需要分别确认，详见 API 网关配置。
1. Codex 是什么，先选哪个入口
OpenAI CLI 文档将 Codex CLI 定位为能在终端里检查代码、编辑文件和运行命令的工具。Codex 还有桌面、IDE 和云端工作方式。模型 API 调用只是其中一层：自行发出一条文本请求，并不会自动获得仓库访问、终端执行和补丁应用能力。
| 你的目标 | 建议起点 | 开始前确认 |
|---|---|---|
| 用图形界面管理本地项目与任务 | 官方桌面入口 | 系统支持、账号与项目目录 |
| 在终端里读写仓库、运行命令 | Codex CLI | 安装路径、登录状态、工作目录 |
| 一边看代码一边协作修改 | Codex IDE 扩展 | 编辑器支持与扩展发布者 |
| 把任务交到云端环境执行 | Codex Cloud | 账号权益、仓库连接与环境准备 |
| 在自己程序中调用模型 | API / SDK | 模型、协议、费用与工具实现 |
IDE 的安装与打开方式见 官方 IDE 文档。新手只选择一个入口跑通即可，没必要同时装齐。终端路线继续看 CLI 安装与登录；有国内使用问题看 账号、网络与 API 边界。
2. 登录前先分清费用来源
官方认证说明区分 ChatGPT 登录和 API Key 登录。ChatGPT 登录按账号和工作区权益使用；API Key 路线按 API 用量计费。订阅价格不能直接换算成 API token 余额，第三方 Key 也不能当作 OpenAI 官方订阅凭证。
开始任务前确认三项：当前登录到哪个账号、任务在哪个工作区、费用从哪里扣。如果你只是试用功能，先检查账号里实际开放的入口和剩余额度，费用细节看 Codex 免费、订阅与 API 计费。
3. 打开正确仓库，留下检查点
新手最值得先做的是确认工作目录。对于本地 Git 仓库，先在终端检查：
bash
pwd
git rev-parse --show-toplevel
git status --short如果有尚未提交的工作，先自行确认并保存。然后在干净的仓库创建任务分支：
bash
git switch -c codex/first-task桌面端和 IDE 也应核对当前项目路径，尤其是多份同名仓库、下载的压缩包、worktree 并存时。不要只凭窗口标题判断。让 Codex 先回答“仓库入口、构建命令、测试命令分别在哪里”，可以同时检查它是否理解项目结构。
4. 第一个任务先做只读分析
可以复制下面这段提示词，把路径换成你自己的实际目录：
text
请先阅读 README、package.json 和项目中的 AGENTS.md。
说明这个仓库的目录结构、启动方式和可用检查命令。
给出关键结论对应的文件路径；缺少的信息明确写出。
这一步只分析，不修改文件、不安装依赖。验收时看它是否找到了真实存在的文件和脚本，而不是只看回答是否流畅。如果项目没有测试脚本，应当说明缺失，不能把“建议运行的命令”当成“已经通过的检查”。
5. 用目标、范围、限制和验收描述修改
第二步选择小问题，例如修正文档链接、修复一个已复现的异常、给现有函数补一个边界检查。不要第一次就要求重写整个项目。
以本站 VitePress 文档为例：
text
目标：在 docs/posts/index.md 增加一条新指南入口。
范围：只修改文章索引，遵守 AGENTS.md 和现有链接风格。
限制：不改依赖，不改主题，不提交、不推送。
验收：新增链接能在构建结果中找到，npm run docs:build 通过。
交付：说明改动文件、验证结果和仍未验证的内容。真实业务仓库要把命令换成已有脚本。遇到不确定需求，先让 Codex列出影响文件和验证方法，再允许实现。长期复用的项目规则适合写进 AGENTS.md，临时任务条件留在当前对话里。
6. 权限按当前任务需要设置
官方权限说明是核对当前权限机制的入口。实际使用时，把读文件、写文件、运行命令、访问网络以及外部操作分开考虑。安装依赖、执行部署、修改数据库与普通文档编辑的影响不同。
新手可以先从仓库内的只读任务开始，再开放完成本次修改所需的能力。若因权限失败，让 Codex说明被阻止的操作与所需范围；不要把“关闭所有限制”当成通用排错步骤。Key、认证缓存和生产环境文件不要粘贴到公开问题或提交到仓库。
7. 验收依靠文件和实际检查
任务结束后，本地可先查看：
bash
git diff --stat
git diff --check
git diff再运行项目真正存在的检查。以本站为例是 npm run docs:build；业务项目可能还需要单元测试、类型检查和手动复现。要求 Codex把“运行通过”“运行失败”和“没有运行”分别写清楚。
| 检查项 | 可以交付的证据 | 还不足以交付的情况 |
|---|---|---|
| 需求 | 改动对应具体问题 | 顺手改了大量无关文件 |
| 正确性 | 测试或复现结果 | 只有“应该能工作” |
| 页面 | 构建后链接、图片和布局可检查 | 只有 Markdown 源文件 |
| 安全 | 无密钥、无意外外部操作 | 把认证文件放进提交 |
8. 有问题怎么回退
未提交时，先用 git diff 确认差异，再逐文件撤回你确实要放弃的改动。对于已提交且已共享的改动，通常可以用 git revert <commit> 创建反向提交，保留历史。不要在不理解影响时使用强制推送或清空工作区。
如果修改方向错了，继续明确说明目标和允许保留的文件；如果上下文混乱，新建任务并提供分支、差异和验收条件，通常比反复发送“还是不对”更可执行。
常见问题
Codex 是不是必须配置 API Key？
不必预设。按当前官方认证文档，ChatGPT 登录和 API Key 是不同路线，具体可用入口受账号和工作区条件影响。
为什么我看到的按钮或模型名与教程不同？
产品入口、版本、账号权限与分批开放都会影响界面。以当前官方入口为起点，不要照搬旧文章中的模型 ID、固定配额或截图坐标。
能不能直接配置第三方 Base URL？
官方文档提供网关配置机制，但网关需要符合相应协议和行为要求。请看 Codex API 中转站配置，先验证 Responses、流式事件和工具续接，再迁移实际任务。
FAQ：Codex 使用中的真实问题
Codex 第一次使用应该从桌面端、CLI 还是 IDE 开始？
按任务选择即可：需要在终端读取仓库、运行检查和查看 Git 差异，CLI 更直接；希望边看编辑器边修改文件，选择 IDE 入口；想管理多个任务和本地项目，再考虑桌面端。第一次不要同时配置多个入口，否则登录状态、项目目录和权限范围容易混在一起。先选一个入口完成“读取 README、定位一个文件、运行一条已有检查命令”的小任务，再决定是否扩展。
Codex 能不能直接修改整个项目？
技术上是否能访问整个项目，取决于当前工作目录、权限和项目规则；但一次性要求它重写整个项目不利于验收。更可靠的做法是先给出目标目录、复现步骤、禁止修改的范围和验收命令，完成一个小改动后阅读 git diff。涉及数据库、部署、生产配置或批量删除时，应拆成独立步骤并人工检查。
Codex 说“已经修复”，怎样确认不是误报？
看三个证据：它修改了哪些真实文件，运行了哪些实际存在的检查，以及检查输出是否能复现问题已经消失。git diff --check 只能发现空白错误，不能替代类型检查、测试或手动复现。如果项目没有自动化测试，要明确记录“未验证”的部分，而不是把模型的判断写成测试通过。
我没有 AGENTS.md，还可以使用 Codex 吗？
可以。AGENTS.md 是项目规则文件，不是 Codex 启动所必需的凭证。没有它时，先在任务提示词里写清目录结构、允许修改的范围、构建命令和交付格式；如果这些规则会长期复用，再创建并验证一份 AGENTS.md。模板和优先级见 AGENTS.md 教程。
Codex 使用 API Key 和 ChatGPT 登录有什么区别？
这是两条不同的认证与计费路线。ChatGPT 登录使用账号或工作区中的产品权益；API Key 登录使用 API 项目权限和 API 用量。一个入口显示可用，不代表另一条路线也可用。具体账号权限、模型和额度要以当前官方页面或对应控制台显示为准。
可以把官方 Codex 客户端直接切到任意中转站吗？
不能默认可以。要先确认客户端版本支持自定义 provider，并确认网关支持 Codex 实际使用的 Responses、流式事件、工具参数和多轮续接。只返回普通文本或只兼容 Chat Completions 的服务，不足以证明能承载完整 agent 任务。配置方法见 API 中转站配置教程。