Codex 教程
Codex 本地项目使用指南
Codex 本地项目使用指南讲清工作目录、AGENTS.md、任务范围、验证命令、未提交改动、密钥保护和 OfApp.cn API 接入边界。
Codex 处理本地项目时，真正重要的不是让它“多做一点”，而是让它在正确的工作 目录、清晰的任务范围和可验证的命令里工作。一个好的本地项目任务，应该让 Codex 先读结构、识别脚本、理解约束，再修改文件、运行验证、交付 diff。
这页适合正在用 Codex CLI、Codex App 或 IDE 扩展处理真实仓库的人：开发者可 以用它改代码、修 Bug、补测试；产品经理、运营和内容团队也可以用它整理文档 站、生成 README、批量修正文案和维护资料库。只要任务会读写本地文件，就要 把边界说清楚。
| 项目 | 说明 |
|---|---|
| 阅读时间 | 约 5 分钟 |
| 更新时间 | 2026-07-02 |
| 适合读者 | 开发者、独立开发者、产品经理、运营、文档维护者、AI 初学者 |
| 适合任务 | 本地仓库改代码、修 Bug、补测试、整理文档、配置 API、保护密钥 |
Codex 本地项目是什么
Section titled “Codex 本地项目是什么”本地项目指 Codex 在你的电脑或工作区里读取仓库、查看文件、运行命令并修改代 码。它和普通聊天不同：普通聊天适合解释和规划，本地项目会触碰真实文件，因 此必须把目录、权限、验证命令和禁区写清楚。
OpenAI Codex 手册将本地线程描述为能读取、编辑文件和运行命令的工作方式， 并会通过沙盒降低误改工作区外文件的风险。对用户来说，关键动作是控制任务范 围，而不是假设 Codex 自动知道哪些文件不能碰。
本地项目流程图
Section titled “本地项目流程图”| 检查项 | 为什么重要 | 可以让 Codex 做什么 |
|---|---|---|
| 当前目录 | 决定 Codex 看到的仓库和指令链 | pwd、列出根目录、确认 Git 根 |
| Git 状态 | 避免覆盖用户已有修改 | 读取 git status --short，标记已有改动 |
| 项目说明 | 让任务贴合现有技术栈 | 阅读 README.md、package.json、配置文件 |
| 脚本命令 | 决定验收方式 | 找出 build、test、lint、typecheck |
| 指令文件 | 继承仓库规则和禁区 | 读取当前路径生效的 AGENTS.md |
| 敏感信息 | 防止密钥和私有数据泄露 | 只看 .env.example，不读取真实 .env 内容 |
一个低风险开场 Prompt 可以这样写：
请先只读当前项目，不要修改文件。
请输出：- 当前工作目录和 Git 根目录。- 主要目录和技术栈。- package.json 或其他配置里的可用脚本。- 当前 git status 中已有改动。- 你建议本任务使用的验证命令。AGENTS.md 怎样影响本地项目
Section titled “AGENTS.md 怎样影响本地项目”AGENTS.md 是 Codex 本地项目最重要的长期约束之一。根据 Codex 手册和
Codex CLI 源码说明，Codex 会从项目根到当前工作目录收集指令文件；同一目录
内会优先看 AGENTS.override.md，再看 AGENTS.md。越靠近当前目录的指令越
适合写更具体的规则。
| 放置位置 | 适合写什么 | 示例 |
|---|---|---|
~/.codex/AGENTS.md |
个人长期习惯 | 回答语言、常用包管理器、提交偏好 |
仓库根目录 AGENTS.md |
全项目规则 | 构建命令、代码风格、密钥边界 |
子目录 AGENTS.md |
某个模块规则 | 后端测试命令、内容栏目规范 |
AGENTS.override.md |
临时覆盖或更强规则 | 特定目录不能改、某类文件需人工确认 |
适合放进项目 AGENTS.md 的内容：
## 项目规则
- 修改代码后运行 npm run build。- 只在任务相关文件中做改动，不做无关格式化。- 不读取、输出或提交真实 .env、API Key、Cookie、用户数据。- 示例 Key 使用 sk-xxxx，模型名写“以控制台可用模型为准”。- 涉及 OfApp.cn 的能力、额度和价格时，以控制台或官方文档为准。如果项目已经有长期多人协作，AGENTS.md 比一次性 Prompt 更可靠。一次性
Prompt 适合当前任务；AGENTS.md 适合仓库每次都要遵守的规则。
任务范围怎么写
Section titled “任务范围怎么写”Codex 更擅长可验证的小任务。范围越清楚，越容易得到干净 diff。
| 任务类型 | 推荐范围 | 验收方式 |
|---|---|---|
| 修 Bug | 给出复现步骤、错误日志、相关文件 | 复现消失，回归测试通过 |
| 新增功能 | 写清用户故事、入口、状态和不做什么 | 单元测试、集成测试或截图 |
| 文档改写 | 指定页面、读者、SEO 主题和禁用说法 | 构建通过，内链有效，描述清楚 |
| API 接入 | 只改服务端封装、环境变量示例和文档 | 最小请求成功，真实 Key 不入库 |
| 批量整理 | 说明目录范围、命名规则和保留文件 | diff 可读，文件数量可解释 |
| 依赖升级 | 限定包名、版本范围和回滚条件 | 测试通过，变更日志可追踪 |
不建议一次性说“帮我优化这个项目”。更稳的写法是：
目标：修复登录页移动端按钮换行问题。
范围：- 只检查 src/pages/login 和相关样式文件。- 不重构认证逻辑，不改 API 请求，不改全局主题。
验证：- 运行 npm run build。- 用浏览器检查 390px 和 1280px 两个视口。- 交付时说明改了哪些文件，以及是否有未验证项。未提交改动怎么处理
Section titled “未提交改动怎么处理”本地项目里常常已经有用户改过的文件。Codex 不应该把这些改动当成自己的，也 不应该为了让 diff 干净而回退它们。
| 情况 | 处理方式 |
|---|---|
| 任务开始前已有改动 | 记录下来，只处理本任务相关文件 |
| 同一文件已有用户改动 | 先读清楚上下文，在现有修改上继续 |
| 无关文件有改动 | 忽略，不格式化，不回滚 |
| 需要改同一段代码 | 在交付说明里点明风险，让用户复核 |
| 构建产物变化 | 判断是否由本任务生成，必要时解释原因 |
交付前可以要求 Codex 输出：
请用 git diff --stat 和 git diff 检查本轮改动。请区分：- 本轮你改的文件。- 任务开始前已有的文件变更。- 需要我人工复核的地方。OfApp.cn 与密钥边界
Section titled “OfApp.cn 与密钥边界”如果本地项目调用 OfApp.cn 或其他 OpenAI-compatible API，Codex 可以帮助你写 封装、示例、错误处理和文档，但真实密钥仍应由人保管。
项目 .env.example 可以这样写：
OPENAI_BASE_URL=https://api.ofapp.cn/v1OPENAI_API_KEY=sk-xxxxOPENAI_MODEL=以控制台可用模型为准| 文件或位置 | 可以让 Codex 处理吗 | 注意事项 |
|---|---|---|
.env.example |
可以 | 只写变量名和占位值 |
.env |
通常不需要 | 不读取、不输出、不提交真实 Key |
| README | 可以 | 写接入步骤，不写真实账号信息 |
| 服务端封装 | 可以 | API Key 只从环境变量读取 |
| 前端代码 | 谨慎 | 不把 Key 暴露给浏览器 |
| CI 配置 | 谨慎 | 使用 Secret，避免日志输出 |
涉及 OfApp.cn 时，不要在本地项目文档里承诺固定模型、价格、套餐或额度。无法 确认的内容统一写：请以 OfApp.cn 控制台或官方文档为准。
Codex 本地项目的完成标准，不是“它说改好了”，而是验证证据足够强。
| 项目类型 | 推荐验证 | 证据 |
|---|---|---|
| Astro / 文档站 | npm run build、链接检查、浏览器截图 |
构建日志、目标页截图 |
| React / Next.js | lint、typecheck、测试、关键页面手动检查 | 命令输出、交互状态 |
| 后端 API | 单元测试、最小 curl、错误分支测试 | 状态码、脱敏响应体 |
| Python 项目 | pytest、类型检查、示例脚本 |
测试通过、日志无密钥 |
| CLI 工具 | --help、示例命令、退出码 |
命令输出和退出状态 |
| 文档改写 | 构建、内链、目录、FAQ、Schema | 页面渲染和 JSON-LD |
如果验证失败，不要让 Codex 盲目扩大改动范围。更好的做法是让它解释失败点、 缩小复现、提出最小修复，再跑同一组验证命令。
可复制任务模板
Section titled “可复制任务模板”目标：把当前项目的 [具体问题] 修好，并保持改动范围尽量小。
上下文：- 项目类型：[Astro / React / Node / Python / 其他]- 相关文件：[列出你知道的文件，未知则让 Codex 先查]- 不要修改：[配置、数据、生成文件、无关页面]
安全边界：- 不读取或输出真实 .env、API Key、Cookie、用户数据。- 示例密钥统一写 sk-xxxx。- 涉及 OfApp.cn 的模型、能力、额度和价格，以控制台或官方文档为准。
工作方式：- 先只读仓库结构、脚本和当前 git status。- 修改前给出短计划。- 修改后运行验证命令。- 交付时说明改动、验证结果和未覆盖风险。Codex 可以直接改我电脑上的任何文件吗？
Section titled “Codex 可以直接改我电脑上的任何文件吗？”不要这样使用。应从明确的项目目录启动，并让 Codex 只处理当前任务相关文件。 涉及桌面、下载、私人资料和系统配置时，要单独确认范围和风险。
Codex 会自动读取 AGENTS.md 吗？
Section titled “Codex 会自动读取 AGENTS.md 吗？”会。Codex 会根据当前工作目录读取全局和项目内的指令文件。为了避免规则混
乱，建议把长期仓库规范写进 AGENTS.md，把一次性任务边界写进 Prompt。
本地项目和云端任务有什么区别？
Section titled “本地项目和云端任务有什么区别？”本地项目使用你的电脑、仓库和现有工具，适合需要看当前未提交改动或本地环境 的任务。云端任务适合并行处理已经推到 GitHub 的仓库工作。两者都需要清楚的 任务范围和验证标准。
Codex 适合整理非代码文件吗？
Section titled “Codex 适合整理非代码文件吗？”适合，但要给出目录范围、命名规则和保留条件。例如整理 Markdown、CSV、PPT 素材或文档资料时，应要求它先列计划，再小批量移动或改写。
API Key 要不要交给 Codex？
Section titled “API Key 要不要交给 Codex？”通常不需要。让 Codex 使用变量名、.env.example 和占位值即可。真实 Key 放
在本机环境变量、密钥管理工具或部署平台 Secret 里，不进入仓库和聊天记录。
验证命令跑不过怎么办？
Section titled “验证命令跑不过怎么办？”让 Codex 先解释失败原因，区分是本轮改动导致、历史问题、依赖缺失还是环境问 题。不要为了追求一次通过而允许它大范围重构。
- OpenAI Codex Prompting：Codex 通过 Prompt 接收任务，并建议提供复现、验证和 lint 检查。
- OpenAI Codex Local environments：本地环境可配置 setup scripts 和常用 actions。
- OpenAI Codex AGENTS.md 指南：Codex 会读取全局、项目和子目录指令文件。
- OfApp.cn API 直转文档：OfApp.cn 的 Base URL、Key、端点和可用范围请以官方文档与控制台为准。
- Codex CLI 接入 OfApp.cn：配置统一 API 入口。
- 用 Codex 写代码：把需求拆成可验证开发任务。
- 用 Codex 修 Bug：从复现到回归测试。
- Codex 建站指南：完成前端页面迭代和浏览器验证。
- Codex 如何完成 Git 提交和推送：交付清晰 diff、commit 和 PR。
- Codex 常见报错与解决：排查构建、SDK 和 API 报错。
- API Key 快速开始：创建、保存和使用 Key。
Codex 处理本地项目时，可靠性来自清楚的工作目录、AGENTS.md、任务范围、密
钥边界和验证命令。把它当成能读写文件的协作者，而不是无边界的聊天窗口；让
每次改动都有证据、有 diff、有人工可复核的收尾。