Codex 使用指南

Appearance

5 分钟上手 Codex ​

这篇教程的目标不是让 Codex 生成一段代码，而是走完一次最小但完整的工程闭环：读懂仓库 -> 修改代码 -> 运行验证 -> 检查差异。

TIP

第一次练习请选择一个有 Git 版本控制、可以本地运行、允许丢弃改动的仓库。不要从生产数据库迁移、密钥轮换或大规模重构开始。

开始前准备 ​

你需要：

  • 一个 ChatGPT 账号或 OpenAI API 凭据，具体可用登录方式以当前产品页面为准；
  • Git，以及项目本身需要的 Node.js、Python、Go 等运行环境；
  • 一个工作区干净的练习仓库，可用 git status 确认；
  • 知道项目最基本的验证命令，例如 npm test、pnpm lint 或 pytest。

Codex 能运行命令，不代表它会自动知道哪条命令最重要。把仓库自己的启动、测试和构建方式写进 README 或 AGENTS.md，后续任务会稳定很多。

1. 安装与登录 ​

通过 npm 安装 Codex CLI：

bash
npm install -g @openai/codex
codex --version
codex

首次启动时按界面提示登录。也可以先查看本机支持的登录选项：

bash
codex login --help

安装方式、操作系统支持和认证入口会随版本更新；遇到差异时，以 OpenAI Codex 官方仓库和本机 codex --help 为准。

2. 进入仓库并确认边界 ​

bash
cd path/to/your-project
git status
codex

本地 Codex 通常在操作系统级沙箱中运行。默认安全思路是：允许读取工作区，在受信任的 Git 仓库中写入工作区，网络访问关闭；越过工作区或访问网络时，根据审批策略请求许可。你可以在会话中运行 /status 查看当前环境，用 /permissions 调整本次会话的权限。

第一次使用时，建议保持 workspace-write 与按需审批，不要为了少点一次确认就启用全权限模式。

3. 先让 Codex 建立上下文 ​

不要直接说“优化一下项目”。先给它一个小型侦察任务：

text
先不要修改文件。

请阅读 README、package.json 和 src/ 目录，回答：
1. 这个项目如何启动、测试和构建；
2. 首页由哪些文件负责；
3. 如果增加一个“最近更新”区块，最小改动范围是什么；
4. 有哪些信息仍不确定。

检查回答是否引用了真实存在的文件和脚本。如果它猜错了入口或验证命令，立即纠正，再进入实现阶段。

4. 下达一个可验收的任务 ​

text
目标：给首页增加一个“最近更新”区块，显示最近 3 条内容。

范围：只修改首页组件和直接相关的样式、测试文件。
约束：沿用现有设计系统；不新增依赖；不改变路由和数据接口。
验收：
- 桌面端和 375px 宽度下无横向滚动；
- 空数据时不渲染空白标题；
- 运行项目已有的 lint、test 和 build；
- 完成后列出修改文件、验证结果和剩余风险。

请先给出 3 至 5 步计划，确认实现范围后再修改。

这段提示词包含五类信息：目标、范围、约束、可观察行为和验证证据。它没有逐行指挥实现，仍给 Codex 留出了阅读代码和选择现有模式的空间。

5. 审查，而不是只看最终回复 ​

任务完成后至少做四次检查：

bash
git status --short
git diff --stat
git diff
# 再手动运行仓库最关键的测试或构建命令

重点确认：

  • 改动是否超出约定文件和行为；
  • 是否新增了未说明的依赖、配置或生成文件；
  • 测试是否真的运行，退出码是否成功；
  • 失败的检查是否被清楚披露，而不是用“应该可以”带过；
  • UI、接口或数据库行为是否需要人工验证。

一个合格的交付摘要应类似：

text
修改：新增 RecentUpdates 组件，并在首页接入；空数组时不渲染区块。
验证：pnpm lint、pnpm test、pnpm build 均通过。
未验证：未在 Safari 真机检查；视觉间距仍需产品确认。
风险：数据按接口返回顺序展示，未额外排序。

6. 把项目规则写进 AGENTS.md ​

当你发现每次都在重复同样的说明，可以在仓库根目录添加 AGENTS.md：

md
# Repository guidance

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Build: `pnpm build`

## Change rules
- Prefer existing components and APIs.
- Do not add dependencies without explaining why.
- Keep public API changes backward compatible.
- Report commands run, failures, and unverified behavior.

AGENTS.md 适合存放团队长期有效的仓库约定；一次性需求仍应写在当前提示词里。规则越靠近相关子目录，作用范围越具体，具体加载方式请以当前官方文档为准。

常见卡点 ​

codex 命令不存在 ​

确认 npm 全局可执行目录已加入 PATH，并检查：

bash
npm config get prefix
npm list -g @openai/codex

登录或运行异常 ​

先升级到当前版本，再执行诊断：

bash
codex doctor
codex login --help

诊断输出可能含本机路径或配置摘要，发布到公开 Issue 前先移除敏感信息。

安装依赖时需要网络 ​

网络在本地沙箱中通常默认关闭。只批准任务确实需要的命令和域名；不要把 API Key、.env 内容或私有仓库凭据粘贴进提示词。

Codex 改得太多 ​

停止继续实现，先要求它列出当前 diff、偏离范围的文件和回退方案。下一轮把任务缩小到一个行为变化，并写清“不得修改”的边界。

下一步 ​

资料与实践来源 ​

官方资料（产品行为的依据）

工程实践（方法论参考）

工程作者的分享用于提炼“小步任务、保留人工判断、用运行结果验证”的工作方法，不代表 OpenAI 官方功能承诺。产品界面、命令和权限以官方文档及本机版本为准。

最后校对：2026 年 7 月 22 日