Codex使用教程：从安装到真正完成一个项目任务
如果你刚搜索“codex使用教程”，通常想解决的是一串相连的问题：Codex 到底怎么安装，第一次应该输入什么，怎么让它读取项目，能不能修改文件，出了错该看哪里，以及是否能接入 DeepSeek、Kimi 或 GLM。把这些问题拆开看会更容易上手，但最终仍要回到一条完整工作流：准备环境，说明目标，让 Codex 先理解，再修改，最后检查结果。
本文按这条路径整理。Codex 的界面、模型和可用入口会随账户、系统和版本变化，实际看到的按钮以当前客户端为准。命令、配置和权限则应以本机版本及官方文档为准。本文更新于 2026 年 10 月 24 日，适合第一次使用 Codex CLI、桌面端或 IDE 工作流的开发者。
按当前问题选择阅读顺序
| 你现在需要解决的问题 | 对应教程 |
|---|---|
| 还没安装，或终端找不到命令 | 安装与首次登录 |
| 想继续会话、做审查或运行脚本 | CLI 命令与工作方式 |
| 每次都要重复交代项目约定 | AGENTS.md 项目规则 |
| 需要连接文档和外部工具 | MCP 接入与验收 |
| 不知道该开放哪些操作 | 权限与沙箱配置 |
| 在 PowerShell 或 WSL 中遇到问题 | Windows 专项教程 |
Codex 适合做什么
Codex 是面向代码和项目工作的智能体入口。它可以在你授权的工作目录里读取文件、分析结构、修改代码、运行已有命令，并把过程和结果交给你检查。它的价值不在于把一句自然语言直接变成一大段代码，而在于把理解、编辑和验证放进同一个循环。
适合交给 Codex 的任务通常有明确输入和验收条件，例如“找到订单列表接口，补一个分页参数，并运行该目录已有测试”“解释这个启动脚本为什么在 CI 中失败”“审查当前分支最近的改动，优先列出会阻塞发布的问题”。“把项目做得更好”这类描述范围太大，容易让工具猜测你的真正目标。
第一步：选择使用入口
Codex 常见入口包括终端 CLI、桌面应用和 IDE 扩展。终端适合已经习惯命令行、需要运行脚本或做 CI 自动化的人；桌面端适合同时管理多个项目和较长任务；IDE 扩展适合围绕当前文件和编辑器上下文工作。它们可能共享部分配置，但操作界面和可用功能不完全相同。
新手可以先从 CLI 或桌面端完成一个小任务。不要一开始就把最重要的生产仓库交给它。准备一个能随时恢复的分支或测试目录，选一个你知道正确答案的任务，这样才能判断它是理解正确，还是只是输出了看起来合理的文字。
第二步：安装并登录
CLI 的安装命令会随系统和发行方式变化。OpenAI 当前的 CLI 页面提供独立安装方式，并说明首次运行需要登录；也可以查看官方的Codex CLI 文档。安装完成后运行：
codex --version
codex login status如果版本号能正常显示，说明命令已经在 PATH 中；codex login status 可帮助确认当前是否存在凭证。首次启动时，按客户端提供的登录方式完成认证。不要把浏览器登录成功误认为终端已拿到凭证，终端和桌面应用的环境可能不同。
进入项目目录后再启动 Codex：
cd /path/to/your/project
codexWindows 用户可以在 PowerShell 中运行同样的 codex 命令，但路径和权限处理方式不同，具体步骤见Windows 上安装和使用 Codex。
第三步：让 Codex 先认识项目
第一次进入仓库，不要直接要求大改。先输入：
请先阅读项目结构，不修改文件。说明使用的语言、启动命令、测试命令、主要入口和你认为需要注意的配置文件。这个请求有三个作用：让工具建立上下文，让你检查它是否找到了正确目录，也能发现依赖没有安装、测试命令不存在或项目包含多个子服务等问题。若它把生成目录、依赖目录或文档误认为核心代码，先纠正范围，再进入下一步。
接着给出一个小而完整的任务。明确四件事：要改变的行为、涉及的大致范围、不能做的事情、怎样算完成。例如：
目标：修复登录后刷新页面丢失状态的问题。
范围：先检查 src/auth 和 src/router，不要升级依赖，不要修改接口协议。
验收：补一个能复现刷新场景的测试，并运行相关测试。
完成后：总结原因、改动文件、测试命令和仍未验证的部分。不要只写“帮我修一下”。如果你还没有确定方案，可以先要求只读分析，让 Codex 提供可能原因和验证顺序，再决定是否允许修改。
第四步：理解权限和沙箱
Codex 能做什么，取决于当前审批策略、沙箱模式和工作目录。官方配置文档列出 approval_policy、sandbox_mode、权限配置方案和 Windows 沙箱设置。配置文件通常是 ~/.codex/config.toml，项目可以用 .codex/config.toml 做受信任的项目级覆盖。基础配置说明整理了常见组合。
第一次使用时，选择能满足任务又容易审查的权限。只读分析先不要开放写入；要改代码时可以在独立分支使用工作区写入；需要联网安装依赖时，明确知道网络访问会带来什么变化。完全放开权限并不会让需求更清楚，也不会替你审查命令。
任何涉及删除、发布、付款、发送外部消息或修改线上数据的动作，都应该单独确认目标和范围。代码编辑通常可撤销，外部副作用未必可以。让 Codex 先给出计划或命令，再决定是否执行，是一个简单的边界。
第五步：用 AGENTS.md 固定项目规则
如果每次都要重复说明启动、测试、代码风格和禁止操作，可以在仓库里添加 AGENTS.md。官方最佳实践把它描述为给智能体读取的项目说明文件；CLI 的 /init 可以生成起始模板。文件中可以写项目结构、构建和测试命令、提交约定、禁止修改的路径，以及“完成”的判断方式。
一个实用的文件不必很长：
# AGENTS.md
## 开始前
- 使用 pnpm，不要改用 npm 安装依赖。
- 先阅读 docs/README.md 和当前目录的 package.json。
## 验证
- 修改后运行 pnpm test。
- 只改动与任务相关的文件。
## 交付
- 总结改动、测试命令和未解决问题。规则应写成能检查的动作，少写“保持高质量”这种无法验收的句子。更深层目录可以有更具体的说明，但要避免多份文件互相冲突。详细示例见AGENTS.md 怎么写。
第六步：建立提问、修改、验证循环
高质量的 Codex 任务通常分四轮。第一轮让它理解并列出计划；第二轮允许小范围修改；第三轮运行相关测试或检查；第四轮让它总结 diff、风险和未验证部分。简单任务可以合并轮次，但每一步的产物仍要看得见。
修改完成后先看 diff，再看测试。不要因为测试通过就跳过 diff，也不要因为 diff 很短就跳过行为检查。对前端变更要打开页面或运行已有检查；对 API 变更要确认调用方和错误路径；对脚本要考虑重复运行和失败恢复。测试环境缺失时，明确记录“未运行”以及原因。
如果结果偏离目标，指出具体事实：“这个改动触碰了不在范围内的依赖文件”“测试没有覆盖刷新后场景”“请保留现有返回结构”，不要只说“重新做”。具体反馈能让下一轮围绕同一验收条件推进。
常用命令和操作
CLI 参考中包含 codex resume、codex review、codex mcp、codex cloud、codex exec 等命令；会话内还可以使用 /status、/model、/permissions、/review、/init。命令是否在当前版本可用，以 codex --help 和官方开发者命令参考为准。不要把 ChatGPT 网页里的斜杠命令和 CLI 命令混在一起。
需要外部服务时，先查看 MCP 列表再让它调用；需要批量自动化时，先用一个输入验证脚本。有关 MCP 的安装、认证和排错，见Codex MCP 接入教程。
第三方模型和 ClawSocket
Codex 支持自定义 provider，但第三方模型必须满足客户端所需的协议和工具能力。可以直连官方 DeepSeek、Kimi、GLM，也可以通过 ClawSocket 统一管理入口。本站常用基础地址为 https://api.clawsocket.com/v1，实际模型 ID、价格、凭证和 Responses 支持情况应在控制台确认。
配置完成后先做三项验收：短文本能返回，只读工具能拿到结果，临时目录中的可撤销修改能完成并通过验证。只看到文字回复，不等于 Codex 的工具循环已经兼容。完整配置见Codex 接入 DeepSeek、Kimi、GLM。
跟着做一遍：给小函数补输入校验
下面是一个练习设计，不是本站已经替你运行的测试记录。选一段你能看懂的纯函数，例如把购物车行项目相加的函数，先写出当前行为与希望增加的约束：数量不能为负，空购物车返回零，不改变既有价格精度规则。把代码放在临时仓库，确认已有测试可以运行。
第一轮只读提示可以写成：“阅读计算总价的函数和现有测试，说明当前输入假设，提出最小修改方案，不改文件。”你要检查它有没有正确定位函数，是否把金额精度、数量类型和空输入分开讨论。若方案改变了接口或引入新依赖，要求解释必要性，再决定是否采用。
第二轮允许修改时，明确只处理负数量校验，保持其余行为。要求补上一个失败用例和一个原有路径用例，运行相关检查，然后报告退出状态。这里的关键不在于测试数量，而是新的约束是否真的被覆盖，旧行为是否仍成立。
第三轮审查 diff。看看是否只改了目标函数和相应测试，有没有顺手重排整份文件、升级包或增加不必要抽象。对看不懂的实现，请它逐段解释依据；无法确定的业务判断先留给你，不要让模型用一个自信回答把需求缺口掩盖过去。
如果测试未通过，先看首次错误，不要立刻要求“全部重写”。可能是用例期望不对、现有测试环境缺失，也可能是代码确有缺陷。让工具按证据分类，一次处理一个条件。这个小练习走通之后，再把同样方法用于真实项目的登录、接口或页面任务。
没有编程经验时怎样开始
不熟悉代码的人，可以先让 Codex 解释项目怎么启动、哪些目录对应页面、怎样撤销修改。避免一上来要求重构架构或处理生产数据库。你需要能判断一个小改动是否完成，也需要知道文件保存在哪里。暂时不能判断时，先停留在说明和演示阶段。
提示词中可以明确“使用我能理解的语言解释变更，保留原有工具链，不自动安装新服务”。工具给出命令后，先了解它会读取或写入哪里，再执行。学习使用 Codex 不需要先记住所有参数，但要逐步掌握工作区、版本控制和验收方法。
对于学习任务，要求解释一个关键决策，比一次生成完整应用更容易积累判断力。你可以问为什么选择这里修改、什么输入会失败、如何确认没有影响别处。答案仍要与代码和实际结果对应，而不是只看叙述是否流畅。
团队使用前先统一交付方式
团队可以约定每次交付包含改动目的、diff 范围、运行过的检查和未验证事项。项目规则中记录长期命令，任务说明中记录本次业务目标，权限配置控制执行边界。这样成员接手时，能看见具体状态，不必从整段聊天猜工作是否完成。
升级客户端、更换模型或添加 MCP 后，复测团队依赖的那条小任务即可。不要因为新功能很多就同时迁移所有设置。先确认既有路径没有退化，再逐步采用新能力；遇到失败时保留可回退配置和任务记录，排查会更直接。
常见问题怎么排查
启动失败先查命令和 PATH，配置失败查 TOML/JSON 和字段，401 查凭证归属，404 查 base URL 与模型，429 区分限流和额度，工具失败查工作目录、权限和命令输出。错误时先保存版本、模型、provider、状态码和脱敏响应，再每次只改一个条件。完整诊断树见Codex 报错大全。
如果你只是想知道 Codex 和 ChatGPT 的差别，可以先看Codex 与 ChatGPT 对比。如果关心费用，查看Codex 套餐、API 和第三方模型成本。这些页面和本文共同覆盖“codex使用教程”的主要搜索意图：先能运行，再能配置，最后能把工作流稳定下来。
官方资料与核对范围
以下资料用于核对产品入口、命令和配置；练习与任务模板是本文提供的操作建议，不代表已在读者设备上运行。官方源码主分支会更新，安装时请再核对本机版本。