Appearance
Codex 安装与第一次运行：完整入门教程
这篇教程适合第一次使用 Codex 的开发者。目标不是让工具一次生成一个完整应用，而是验证 CLI 能启动、Codex 能读到正确仓库、它能按边界修改文件，以及验证命令确实能运行。
开始前可以先查看 OpenAI Codex 官方页面 和 Codex 开发者文档。安装命令、支持平台、认证和功能会随版本变化，实际操作以官方文档和本机 codex --help 为准。
安装前检查
准备 Node.js 和 npm
当前 CLI 安装方式通常需要受支持的 Node.js 环境。先检查 node --version 和 npm --version。如果命令不存在，安装 Node.js LTS 后重新打开终端。Windows 用户可以参考 Windows 安装与配置排障，macOS 和 Linux 用户可以阅读 CLI 安装与使用。
准备 Git 工作区
Codex 处理代码时最好位于一个 Git 仓库中。进入项目根目录，运行 git status --short --branch，确认当前分支和未提交修改。如果工作区已有修改，先记录哪些内容必须保留，不要在不了解现有 diff 的情况下执行大范围重构。
找到项目自己的命令
先查看 package.json、README 或项目文档，确认启动、测试、类型检查和构建命令。不同仓库可能使用 npm、pnpm、yarn、pytest、cargo 或其他工具，不要凭经验猜命令。
安装 Codex CLI
如果当前官方文档仍使用 npm 全局安装，可以运行 npm install --global @openai/codex，然后运行 codex --version。如果官方文档给出了新的安装方式，优先采用官方方式。安装后若出现 codex: command not found，重开终端并检查 npm 全局 bin 是否在 PATH。
第一次启动和登录
在仓库根目录运行 codex。认证方式取决于当前 Codex 版本和产品入口，按终端提示完成官方登录。不要复制陌生来源的 auth.json，也不要把登录信息粘贴到聊天、截图或 Git。认证失败时可以阅读 Codex 401 排障。
启动后先确认当前工作目录、项目名称和适用的 AGENTS.md。如果 Codex 读到了错误的父目录，先退出并在正确的仓库根目录重新启动。
第一个只读任务
第一次不要直接要求修改代码。先发送：
请先阅读 package.json、README、项目入口和测试配置。只告诉我如何启动、如何测试、主要模块在哪里。不要修改文件，也不要执行删除、迁移或发布命令。
检查回答是否引用真实文件和命令。如果遗漏关键入口，补充目录范围后再问一次。这个步骤可以同时验证工作目录、上下文读取和项目规则是否生效。
第一个可修改任务
选择一个影响面小、容易回滚的任务，例如补充边界测试或修改一条错误提示。提示词包含目标、范围、限制和验证：
目标：为登录失败状态补充用户可读的错误提示。范围：只允许修改
src/auth和tests/auth。限制：不要改变 API 返回结构，不要新增依赖。完成标准：新增回归测试，运行受影响测试和项目构建，并汇报结果。请先给出计划，确认后再编辑。
复杂任务可以先使用 Plan Mode 与 Subagents 拆分，普通小任务则保持一个清晰的主任务即可。
完成后必须检查什么
先运行 git diff --stat、git diff --check 和 git diff，确认没有修改范围外文件、密钥、构建产物或无关格式化。再运行受影响测试、类型检查和构建，并由你确认关键输出。最后按照用户真实路径做一次最小手动验证。
测试通过只能说明已覆盖场景通过，不能证明所有流程正确。测试未通过时，不要直接提交或发布。
常见安装问题
codex: command not found
检查 Node.js 和 npm 是否来自预期版本，重新打开终端，并运行 npm prefix --global 查看全局安装位置。Windows 还要检查 PowerShell 的 PATH，详细步骤见 Windows 排障。
Codex 读取了错误的项目
用 pwd 或 Get-Location 确认当前目录，检查是否存在 package.json 和 .git。在仓库根目录重新运行 Codex，并在任务中明确目录范围。
API Key 或登录失败
先区分官方登录和第三方 Provider 配置。不要把 OPENAI_API_KEY、服务商 Key 和登录文件混为一谈。第三方 API 配置请阅读 CLI 接入第三方 API 和 API Key 配置。
修改结果超出预期
立即查看 diff，保留需要的用户修改，撤销无关改动前先确认没有误删。下一次任务要求先计划，并写出允许修改的目录和禁止操作。
FAQ
第一次任务应该多大？
以十几分钟内能阅读 diff、跑完测试并手动验证为宜。补测试、修一个错误状态或解释一条调用链通常比新建完整应用更适合入门。
我没有 Git 仓库也能用 Codex 吗？
某些场景可以，但 Git 能提供 diff、分支和回滚能力。建议先初始化仓库或复制一份可恢复的工作目录，再让工具修改代码。
Codex 安装后是否一定要配置 API Key？
取决于当前认证方式。按照官方登录流程操作；只有在接入 API 或第三方 Provider 时，才按服务商要求配置对应的 Key、Base URL 和模型。
什么时候应该改用 API？
当调用发生在你的后端、队列、CI 或自动化产品中时，API 更适合。需要自行设计鉴权、超时、重试、限流和日志，入口见 第一次 API 请求。