API Codex

Appearance

Codex 教程：从安装到完成第一个开发任务 ​

如果你第一次使用 Codex，最容易踩的坑是把它当成一个只会补全代码的聊天机器人。Codex 更适合被当作一个能阅读项目、执行开发任务、修改文件并运行验证的 AI 编程代理。

这篇教程带你从安装开始，完成一个完整的小任务：让 Codex 阅读一个项目，修改一处行为，运行测试，并检查最终 diff。你不需要一开始就理解所有高级功能，先跑通这个闭环，之后再学习 API、AGENTS.md、Skills 和 MCP。

你将完成什么 ​

完成本文后，你应该能够：

  • 安装 Codex CLI 并确认版本
  • 在一个 Git 项目中启动 Codex
  • 写出带有范围和验证条件的任务描述
  • 让 Codex 先分析，再修改代码
  • 查看 diff、运行测试并判断任务是否完成
  • 区分登录问题、配置问题和代码问题

一、安装前准备 ​

先准备一个可以运行的项目目录。推荐使用 Git 仓库，因为你可以随时查看修改、撤销错误并比较任务前后的状态。

环境要求 ​

不同版本的 Codex 可能会调整环境要求，安装前应以官方文档为准。常见的 CLI 环境包括：

  • macOS、Linux，或支持的 Windows 环境
  • Node.js 20 或更高版本
  • npm 10 或更高版本
  • 一个可以运行测试或构建命令的项目

检查 Node.js 和 npm：node --version、npm --version。

如果你的版本过旧，先升级 Node.js，再继续安装。不要在项目还无法正常运行时就让 Codex 做大范围修改，否则很难判断问题来自环境还是代码。

二、安装 Codex CLI ​

使用 npm 全局安装官方 CLI：npm install --global @openai/codex。

安装完成后检查版本：codex --version。

如果终端提示找不到 codex，通常是 npm 全局 bin 目录没有加入 PATH。可以先查看全局安装位置：npm prefix --global，然后确认这个目录下的 bin 路径已加入系统 PATH。Windows、macOS 和 Linux 的 PATH 配置方式不同，建议按你的系统单独处理，不要直接复制另一套系统的命令。

三、登录并启动项目 ​

进入一个真实项目，先检查当前工作区：cd ~/projects/your-project，然后运行 git status。

确认工作区状态后启动 Codex：codex。

第一次运行通常会要求完成登录或选择认证方式。登录后，Codex 会在当前项目上下文中工作。密钥、登录文件和环境变量不要提交到 Git，也不要粘贴到公开的 issue 或聊天记录中。

如果你使用的是 API Key 或自定义 Provider，请先确认服务商提供的 endpoint、模型名称和认证方式，再阅读 Codex API Key 配置教程 和 生产环境 API 清单。不同服务商的配置字段可能不同，不要把一个平台的示例原样复制到另一个平台。

四、先让 Codex 理解项目 ​

第一次进入项目时，不要立即输入“帮我重构整个项目”。先做一个只读分析任务：

请先阅读项目结构和 package.json，不要修改文件。告诉我应用的启动入口、测试命令、主要业务目录，以及你认为和登录功能相关的文件。如果信息不足，请列出需要继续读取的文件。

这个步骤有两个作用。第一，你可以检查 Codex 是否找到了正确的入口。第二，你可以在修改发生前发现上下文错误，例如进入了错误的子目录，或者把测试目录当成了生产代码目录。

五、写出第一个可验证任务 ​

一个好的 Codex 任务至少有四部分：目标、上下文、约束和验证命令。

可以直接改写下面的模板：

目标：为订单列表增加按状态筛选。上下文：相关代码在 src/orders，当前列表接口已经接受 status 参数。约束：保持现有接口返回结构，不引入新依赖，只修改订单模块和相关测试。验证：运行 npm test 和 npm run build，完成后总结修改文件、测试结果和遗留风险。

这比“帮我加一个筛选功能”更稳定，因为 Codex 知道应该从哪里开始、哪些行为不能改变，以及什么结果才算完成。

六、让 Codex 分阶段工作 ​

对于第一次任务，建议使用三个阶段。

阶段 1：分析 ​

让 Codex 列出实现计划、影响文件和潜在边界。此时不修改文件。

阶段 2：实现 ​

确认计划后，让它只修改任务所需的文件，并保留项目现有的代码风格。

阶段 3：验证 ​

让 Codex 运行项目已有测试、类型检查和构建命令。如果命令失败，要求它区分“本次修改导致的失败”和“修改前就存在的失败”。

这种分阶段流程比一次性要求“完成全部功能”更容易审查，也更适合真实团队协作。

七、检查 Codex 的修改 ​

任务完成后，先查看修改范围：git diff --stat 和 git diff。

重点检查四件事：

  1. 是否修改了任务范围之外的文件。
  2. 是否改变了不应该改变的接口、错误码或数据结构。
  3. 是否处理了空值、重复提交、权限和失败重试等边界情况。
  4. 是否新增了与项目无关的依赖或配置。

接着运行项目已有的验证命令：npm test 和 npm run build。如果项目使用的是 pnpm、yarn 或其他工具，以仓库已有的 lockfile 和 scripts 为准。不要为了让命令通过而临时替换包管理器。

八、常见问题排查 ​

Codex 命令找不到 ​

先运行 npm prefix --global，检查全局 npm bin 目录是否在 PATH 中。重新打开终端后再运行 codex --version。

登录失败或出现 401 ​

401 通常表示认证凭据无效、过期或配置文件冲突。先确认当前登录状态和 API Key 没有多余空格，再检查 ~/.codex 下的认证配置。不要把完整密钥放进日志或截图。

如果你使用第三方 API，还需要同时确认 API Base URL、模型名和协议格式。可以参考 Codex API 第一次请求，再根据服务商文档调整字段。

Codex 修改了很多不相关的文件 ​

缩小任务范围，明确目录、允许修改的文件和禁止修改的文件。也可以先要求 Codex 只输出计划，确认后再执行。

测试失败但看不出原因 ​

让 Codex 返回完整失败命令、首个错误位置和修改前后的差异。不要只让它反复重跑测试；先判断失败来自环境、依赖、已有问题还是本次改动。

九、下一步学习什么 ​

跑通第一个任务后，可以按下面的顺序继续：

如果你要把模型能力接进自己的后端，可以访问 api.clawsocket.com 查看 API 入口、认证方式和当前服务配置。密钥应只保存在服务端环境变量或密钥管理系统中。

常见问题 FAQ ​

Codex 适合什么类型的任务？ ​

它适合有明确范围和验证方式的开发任务，例如补测试、修复一个报错、解释模块、实现局部功能、代码审查和文档整理。

可以让 Codex 一次开发完整系统吗？ ​

不建议第一次就这样做。先拆成项目分析、数据结构、核心流程、测试和部署几个阶段，每一步都检查 diff 和运行结果。

Codex 和普通聊天机器人有什么区别？ ​

Codex 可以围绕项目读取上下文、执行命令和修改文件，工作结果可以直接回到 Git diff 和测试中验证。它仍然需要清晰的任务边界和人工审查。

API Key 应该放在哪里？ ​

只放在服务端环境变量或密钥管理系统中。不要放进前端代码、Git 仓库、截图、日志或浏览器 Local Storage。

如何判断 Codex 的任务真的完成了？ ​

至少检查修改范围、测试结果、构建结果和边界条件。没有可重复的验证命令，就不能只根据 Codex 的文字总结判断任务完成。

专注 Codex 使用方法与 API 工程实践

Copyright © 2026 API Codex