Codex CLI 入门：安装、启动与第一次任务验收

安装成功与任务成功是两项检查。这份指南从 codex 命令开始，带你完成一个可以检查、可以重复的小任务。内容由 Codex Pulse 独立编写，官方文档核对日期为 2026 年 9 月 18 日。

安装 Codex CLI

如果你已经在使用 npm，OpenAI 文档提供了这条安装命令：

npm install -g @openai/codex

macOS 用户也可以选择文档中的 Homebrew 安装方式：

brew install --cask codex

选择一种方式即可。独立安装器、各平台说明和当前更新命令见 Codex CLI 官方页面。遇到命令找不到时，先确认终端能够找到哪份安装，避免通过安装多个副本反复试错。

更新当前使用的安装

npm 安装可再次运行 npm install -g @openai/codex；Homebrew 安装使用 brew upgrade --cask codex。命令来源为 CLI 官方指南。保持安装方式一致，更新后重新运行一个已保存的任务。

在正确的项目目录启动

进入目标项目目录，在终端运行：

codex

首次运行会提供 ChatGPT 登录或其他可用认证方式。按官方认证说明 操作。Codex Pulse 不需要你的密码、API key 或会话 token。

请求修改前，先检查工作区并保留已有工作。Git 项目可以用 git status --short 确认哪些变更早于本次任务。初次熟悉流程时，选一个小型、非敏感仓库，或使用可丢弃的副本。

给第一次任务一个能观察到的终点

先做一次代码解释，再尝试大范围修改：

找到这个项目中处理某项用户可见行为的代码。
解释入口、关键函数和已有测试，并提供文件路径。
不要修改文件。

把“某项用户可见行为”替换成具体功能，例如修改个人资料名称。随后打开引用的文件，检查解释是否符合实际代码。即使回答听起来合理，只要指向了错误的 handler，这次任务就没有通过。

第一次改代码时，选择一个小行为变更，并指定验收检查：

在给定示例中完成指定行为变更。
保留无关改动，执行相关的已有检查。
报告改了什么、实际检查结果，以及尚未完成的工作。

补上具体行为和检查，避免让 agent 猜测。小任务的代价是无法代表大型项目能力；好处是你能完整检查结果。

继续之前，检查实际结果

Git 项目应亲自查看 git diff。测试失败与因缺少依赖或服务而无法执行，需要分开记录。保留原始输出，并写下你是否追加过指令。

首次运行失败时怎么查

终端找不到 codex： 查看安装结果，按安装器说明重新打开终端。确认当前 shell 能访问安装位置。使用对应安装方式的官方排查步骤，避免猜测另一个包名。

登录失败： 保存准确错误，查阅官方认证说明。不要在公开报告里粘贴浏览器回调 URL 或 token。

工具无法执行： 查看具体命令和错误。缺少依赖、服务不可用、权限不足，与生成内容错误是不同观察。排查时保留已有权限边界。

任务很慢或提前结束： 使用 Codex 质量与延迟检查表，记录剩余工作和等待发生的位置。

保存一个可重复的结果

基础流程跑通后，记录任务、请求模型、effort、客户端版本、原始输出与检查结果。可复现 benchmark 指南 说明了怎样保持运行条件可比。

需要一个小型视觉练习时，可以从 鹈鹕 prompt 与示例 开始。图像提供了可检查的具体产物，不能认证整体软件工程能力。下一个值得保存的检查点，是从相同起始状态重复同一项任务。