# CodexGuide 完整内容索引
本文件汇总 CodexGuide 的可公开阅读内容，适合需要完整上下文的 AI 助手。专题入口会直接指向正文页面。
## 内容入口
- Codex 总入口: https://codexguide.io/codex
- 入口选择: https://codexguide.io/compare
- 学习路线: https://codexguide.io/paths
- 快速上手: https://codexguide.io/quickstarts
- 进阶教程: https://codexguide.io/advanced
- 故障排查 FAQ: https://codexguide.io/guides/faq
- 验证流程: https://codexguide.io/codex/validation
- 实战案例: https://codexguide.io/cases
## Codex 专题
### 安装 Codex：先完成第一次启动
URL: https://codexguide.io/codex/install
从 App、CLI 或 IDE 入口开始安装 Codex，完成登录、打开项目和第一次只读检查。
#### 先选与你环境匹配的入口
第一次使用时，不需要同时安装所有版本。先根据工作环境选择 App、CLI 或 IDE，再完成一次最小可验证启动。
- 桌面任务优先考虑 App。
- 脚本、批处理和 Git 工作流优先考虑 CLI。
- 需要持续查看代码上下文时考虑 IDE。
#### 安装后先做四项检查
确认账号已登录、项目目录正确、Git 状态可读，并让 Codex 先只读项目说明和测试入口。
如果仍未决定使用哪种入口，先阅读[App、CLI、IDE 与 Cloud 怎么选](/compare)。
#### 完成标准
你能说清当前项目、当前分支、启动命令和第一项可回滚任务，且工作区没有意外修改。
### Codex 从哪里进入：App、CLI、IDE 与 Cloud
URL: https://codexguide.io/codex/entry-points
按任务类型、运行位置和权限边界选择 Codex 入口，直接进入下一篇对应教程。
#### 先看任务，不看能力等级
App、CLI、IDE 和 Cloud 不是从低到高的等级，而是不同的工作边界。先判断任务在哪里运行、是否需要脚本、是否需要异步隔离。
#### 快速结论
- 第一次使用或希望可视化管理任务：App。
- 熟悉 Git、脚本和可重复命令：CLI。
- 边看代码边修改、测试和审查：IDE。
- 需要异步、远程或隔离执行：Cloud。
#### 下一步
如果你还没有安装，进入[首次安装与项目检查](/codex/install)；如果已经选好入口，进入[完成一个可回滚的真实任务](/codex/workflows)。
### 登录与认证：先确认账号和凭据边界
URL: https://codexguide.io/codex/auth
理解 ChatGPT 登录、API Key 和本地凭据的使用边界，定位认证失败而不泄露敏感信息。
#### 使用哪种认证方式
按照当前入口支持的方式完成 ChatGPT 账号登录或 API Key 配置。认证信息只保存在凭据管理器或本机受控位置，不写入提示词、仓库和截图。
#### 认证失败时保留证据
- 记录完整错误、当前入口和操作系统。
- 确认系统时间、网络和账号状态。
- 检查 auth.json、.env 和 token 是否被错误提交。
#### 完成标准
登录成功后先进行一次只读项目检查，再进入[权限与安全边界](/codex/permissions)，不要直接执行高风险修改。
### 权限与安全边界：先限制影响面
URL: https://codexguide.io/codex/permissions
掌握 Codex 的工作区、网络、审批和敏感信息边界，用最小权限完成可回滚任务。
#### 把权限当作任务约束
默认从受控工作区和最小权限开始。只有当任务明确需要联网、写入工作区外或执行高风险命令时，才扩大范围并要求人工确认。
#### 执行前检查
- 先运行 git status，确认已有改动不会被覆盖。
- 不要把 token、auth.json、.env 或客户数据放进提示词和提交。
- 生产、数据库和删除操作必须由人确认。
#### 失败后的处理
把权限问题与代码问题分开，保留命令、路径和错误，再按[权限、Git 与验证失败排查](/guides/faq#permissions)逐项隔离。
### 修改后如何验证：从 diff 到回归检查
URL: https://codexguide.io/codex/validation
建立 Codex 修改后的验证顺序，覆盖 Git diff、测试、构建、页面检查和无法验证的部分。
#### 验证顺序
- 先看 git diff 和 git status，确认范围没有扩大。
- 运行与任务对应的最小测试或检查。
- 需要时再运行构建、页面验证或更宽范围回归。
- 记录成功、失败和无法验证的部分。
#### 故障分类矩阵
先按可观察证据分类，再选择修复动作。不要用扩大权限、删除缓存或大范围重构来掩盖根因。
症状 | 优先检查 | 证据 | 下一步
命令被拒绝 | 工作区、sandbox、审批 | 命令与权限提示 | 缩小范围或请求明确批准
Git diff 为空 | 路径、分支、worktree | git status --short --branch | 回到实际修改的工作区
测试失败 | 基线、依赖、代码 | 完整命令和错误 | 最小复现并比较基线
构建通过但页面错误 | 路由、浏览器、交互 | 页面行为和控制台 | 补做浏览器验证
环境命令不存在 | 终端、PATH、版本 | 版本输出和当前目录 | 统一执行环境后重试
#### 不要只看 Codex 的完成提示
完成提示不是验收结果。验收必须有命令输出、页面行为、测试结果或人工检查证据。
#### 验证失败怎么办
先保留失败现场，不要立刻删除缓存或改成 Full access。进入[权限、Git 与验证失败 FAQ](/guides/faq#validation)查看对应分支。
### Codex 工作流：从任务到可回滚结果
URL: https://codexguide.io/codex/workflows
用目标、上下文、约束、计划、最小修改和验证组成一条可重复的 Codex 工作流。
#### 一条可靠流程包含什么
- Goal：要完成什么。
- Context：项目入口、相关文件和未知信息。
- Constraints：允许修改的范围、权限和禁止事项。
- Done when：用什么证据判定完成。
#### 执行时保持最小范围
先让 Codex 调查并提出计划，再执行最小修改。中途检查 diff，不把多个目标混进同一个任务。
#### 结束前完成闭环
运行测试或构建，查看 diff 和工作区状态，确认没有敏感文件或无关重构，再提交或回滚。需要更深的项目规则时阅读[AGENTS.md 项目协作规则](/advanced/agents-md)。
如果验证失败，先按[测试与验证 FAQ](/guides/faq#validation)保留基线和错误证据，再决定是否继续修改。
## 故障排查 FAQ
### 登录与认证
#### Codex 登录失败怎么办？
先保留完整错误、当前入口和操作系统，确认网络、系统时间与账号状态，再重新完成认证。
解决步骤: https://codexguide.io/codex/auth
keywords: 登录失败, 认证失败, Codex 登录
#### ChatGPT 登录和 API Key 应该怎么选？
按当前入口和账号能力选择。Cloud 使用 ChatGPT 登录；本地脚本或可信 CI 才考虑 API Key，并单独确认计费与权限。
解决步骤: https://codexguide.io/codex/auth
keywords: ChatGPT 登录, API Key, 认证方式
#### auth.json、Token 或 .env 可以发给 Codex 吗？
不要把凭据放进提示词、截图、Issue 或 Git 提交。只让 Codex 检查凭据是否存在，不要输出真实值。
解决步骤: https://codexguide.io/codex/auth
keywords: auth.json, Token, .env, 凭据
#### 登录成功后第一步应该做什么？
先只读检查项目、工作目录和 Git 状态，确认入口和环境正确后，再进入权限设置或修改任务。
解决步骤: https://codexguide.io/codex/install
keywords: 登录后, 首次检查, 只读检查
### 权限与审批
#### Codex 没有权限修改文件怎么办？
先确认文件是否在工作区内、任务是否需要写入范围外，再检查审批策略；不要为了绕过错误直接切换到 Full access。
解决步骤: https://codexguide.io/codex/permissions
keywords: permission denied, 文件权限, 工作区
#### 为什么 Codex 要求网络或命令审批？
网络、工作区外写入和高风险命令会扩大影响面。先确认用途、目标和读写范围，再逐项批准。
解决步骤: https://codexguide.io/codex/permissions
keywords: 网络审批, 命令审批, 批准
#### sandbox 限制和 approval policy 有什么区别？
sandbox 决定执行环境能访问什么，approval policy 决定哪些动作需要人工确认；两者共同构成任务边界。
解决步骤: https://codexguide.io/advanced/config-toml
keywords: sandbox, approval policy, 审批策略
#### 什么时候可以使用 Full access？
只有在任务明确需要更大范围，并且已经确认目标、备份、凭据和回滚方式时才考虑扩大权限。
解决步骤: https://codexguide.io/codex/permissions
keywords: Full access, 权限扩大, 回滚
### Git 与工作区
#### Codex 修改后 Git diff 看不到怎么办？
先运行 git status --short --branch，确认当前目录、分支和文件是否正确，再排查是否修改了另一个工作区。
解决步骤: https://codexguide.io/codex/validation
keywords: git diff, 看不到修改, 工作区
#### 已有未提交修改时能让 Codex 开始吗？
先确认这些修改是谁做的、是否需要保留以及是否会与任务冲突；不要为了得到干净状态而删除或覆盖它们。
解决步骤: https://codexguide.io/codex/workflows
keywords: 未提交修改, git status, 覆盖修改
#### 如何避免 Codex 把无关文件一起改了？
在任务中限定允许修改的目录，执行中查看 diff，结束后检查未跟踪文件、锁文件和配置文件是否超出范围。
解决步骤: https://codexguide.io/codex/workflows
keywords: 无关文件, 修改范围, diff 审查
#### 多个 worktree 或分支导致结果不一致怎么办？
分别记录当前路径、分支和提交，确保 Codex 与你查看 diff 使用的是同一个工作区。
解决步骤: https://codexguide.io/codex/validation
keywords: worktree, 分支, 结果不一致
### 测试与验证
#### 测试通过了，为什么还不能算完成？
还要确认 diff 范围、页面行为、构建结果和未验证部分；Codex 的完成提示不是验收证据。
解决步骤: https://codexguide.io/codex/validation
keywords: 测试通过, 验收, 完成提示
#### 验证失败后应该先做什么？
保留失败命令、完整错误、路径和当前分支，先区分环境、权限、依赖、Git 和代码问题。
解决步骤: https://codexguide.io/codex/validation
keywords: 验证失败, 错误排查, 失败证据
#### 项目修改前就已经测试失败怎么办？
先记录基线错误，不要把它和本次修改混在一起；修改后用同一条命令比较结果。
解决步骤: https://codexguide.io/codex/validation
keywords: 基线失败, 测试基线, 回归
#### 构建通过但页面仍然不对怎么办？
补做浏览器或页面行为检查，确认路由、交互、移动端布局和控制台错误，而不是只依赖构建退出码。
解决步骤: https://codexguide.io/codex/validation
keywords: 构建通过, 页面错误, 浏览器验证
### Windows 与 WSL
#### Windows 和 WSL 路径不一致怎么办？
统一 Git、Node、包管理器和 Codex 的运行环境，确认工作目录、换行符、编码和执行权限。
解决步骤: https://codexguide.io/advanced/windows
keywords: Windows, WSL, 路径
#### 命令在终端可用，在 Codex 中却找不到怎么办？
确认 Codex 使用的终端、PATH 和项目目录与人工验证时一致，再记录版本和完整命令。
解决步骤: https://codexguide.io/advanced/windows
keywords: 命令不存在, PATH, 终端
## 实战案例
### Codex 新手第一个任务：修改本地网页并检查结果
URL: https://codexguide.io/cases/wan-cheng-di-yi-ge-zhen-shi-ren-wu
适合已经安装并登录 Codex App 或 CLI 其中一种、能够访问练习文件夹，但还没有独立完成过一次可核对修改的读者。不要求同时安装两种入口，也不声称所有系统和客户端都已实测。
# Codex 新手第一个任务：修改本地网页并检查结果
> 难度：基础
>
> 类型：首次实操
>
> 本文提供一套不需要 Node、数据库、插件或第三方 SDK 的共同练习。它不代表 Codex 模型可以完全离线运行。
## 这篇文章适合谁
适合已经安装并登录 Codex App 或 CLI 其中一种、能够访问练习文件夹，但还没有独立完成过一次可核对修改的读者。不要求同时安装两种入口，也不声称所有系统和客户端都已实测。
## 准备什么
- 一台已安装并登录 App 或 CLI 的电脑。
- 下方提供的本课练习包，无需克隆仓库或向维护者索取文件。
- 一个独立测试目录。不要使用 CodexGuide 正式网站、私人仓库或含敏感信息的目录。
- 可以打开本地 HTML 文件的浏览器。
练习只包含简单 HTML、CSS 和说明文件，不调用外部业务 API、不收集个人信息、不部署。
## 本课练习材料
使用一个简单的本地网页，练习修改标题与简介，并检查原有链接和样式是否保留。
[下载练习包（ZIP）](../练习材料/Codex首次任务-本地网页练习包.zip)
文件名：`Codex首次任务-本地网页练习包.zip`，大小：3,435 字节。包内包含未修改的 HTML/CSS、任务说明、检查清单和独立的参考差异，不需要安装 Node、数据库或插件。
解压后的目录如下：
```text
首次任务-本地网页/
├── README.md
├── 任务说明.md
├── 检查清单.md
├── 起始文件/
│ ├── index.html
│ └── styles.css
└── 参考差异/
└── 参考差异.md
```
手机上可以阅读教程和找到下载入口；实际练习需要在能够操作项目目录、已安装并登录 Codex App 或 CLI 的电脑上完成。手机浏览器不能直接执行本课的本地 Codex 任务。
只在练习副本中操作，不要打开真实业务项目、生产网站或含凭据的私人目录。参考差异用于完成后的比较，不是起始文件。
## 取得并打开正确目录
1. 点击上方“下载练习包（ZIP）”，把文件保存到电脑，再解压到一个新文件夹。
2. 将解压后的 `首次任务-本地网页/起始文件/` 整个复制为新的工作目录，例如 `codex-first-task-test/`。保留原始 `起始文件/` 不改动；`任务说明.md` 和 `检查清单.md` 位于它的上一级。
3. 先在浏览器中打开工作目录里的 `index.html`，应看到“晨间读书角”、一段简介和“查看阅读清单”按钮。
4. 在 App 中通过选择项目文件夹的入口打开 `codex-first-task-test/`；具体按钮名称以当前客户端为准。不要打开解压包的最外层或 `参考差异/`。
5. 使用 CLI 时，在终端进入同一个工作目录，确认直接包含 `index.html`、`styles.css` 后运行 `codex`。macOS/Linux 可用 `pwd`、`ls`，PowerShell 可用 `Get-Location`、`Get-ChildItem` 核对目录。
如果 App 或 CLI 还不能正常使用，先回到[安装与首次使用](../01-安装与首次使用/README.md)和[第一次使用前要准备什么](./06-第一次使用前要准备什么.md)。
## 给 Codex 的指令
把下面的指令发给 Codex：
```text
请先阅读 index.html 和 styles.css，不要修改文件。
然后只做这两处文字修改：
1. 将主标题改为“我的第一个 Codex 练习”；
2. 将简介改为“先看清修改，再确认页面结果。”。
请保留按钮文字、https://example.com 链接、其他 HTML 内容和全部 CSS 样式。
完成后告诉我修改了哪些行，并不要运行部署或安装命令。
```
先让它阅读再修改，是为了确认目录和范围。看到权限请求时，只允许服务于本次练习的读取和编辑动作；不要为这个练习开启外部写入、部署或安装操作。
## 预期修改与检查
预期只有 `index.html` 的两处文字变化：
```diff
- 晨间读书角
- 用十分钟记录今天读到的一段话，慢慢建立自己的阅读清单。
+ 我的第一个 Codex 练习
+ 先看清修改，再确认页面结果。
```
按[练习检查清单](../练习材料/首次任务-本地网页/检查清单.md)完成文件、链接、范围和浏览器检查。直接打开 `index.html`，确认标题、简介、按钮和样式都能看到；人工浏览器检查与 Codex 的文字总结是两件事。
## 出错怎么办
- 找不到文件：重新检查 App/CLI 打开的路径，用 `pwd`、`ls` 确认目录。
- 修改了 CSS 或按钮链接：停止继续编辑，从原始 starter 重新复制到新目录，再重试。
- 页面文字正确但样式异常：比较 `styles.css` 是否被改动，并从原始 starter 重来。
- 不确定是否完成：查看 diff，与上面的参考差异逐行比较。
- 登录、权限或客户端入口异常：查看[安装登录常见问题](../01-安装与首次使用/13-安装登录常见问题.md)和[故障排查目录](../15-故障排查与常见问题/README.md)。
重新练习时，重新解压或复制 `起始文件/` 到新的目录；不要清空真实工作区，也不要执行破坏性 Git 重置。
## 这次练习之后
完成一次小修改后，先阅读[完成第一次修改并检查结果](../01-安装与首次使用/09-完成第一次修改并检查结果.md)，再按需要进入[核心概念与任务方法](../02-核心概念与任务方法/README.md)或[项目理解与上下文](../03-项目理解与上下文/README.md)。原仓库中的历史案例仍保留在本文后半部分和[真实案例复盘](../14-真实案例复盘/README.md)，它们是独立案例，不能当作本次练习的亲测记录。
## 来源与验证边界
安装、登录和首次任务的官方参考：[OpenAI Codex Quickstart](https://learn.chatgpt.com/docs/quickstart)、[Codex CLI](https://learn.chatgpt.com/docs/codex/cli) 和[Authentication](https://learn.chatgpt.com/docs/auth)。本练习材料和本文是本仓库维护者编写的教学内容。2026-09-20 已在 macOS 15.6、Codex CLI 0.154.0 的现有认证环境中，用本课原始提示词通过 `codex exec` 完成一次练习副本修改。独立文件比对确认只有主标题与简介改变，CSS、按钮文字和链接未变；通过本机临时 HTTP 预览检查了真实生成的页面。此记录只覆盖 CLI 非交互执行、文件比对和页面检查，不覆盖 App、交互式 CLI 界面、直接双击 HTML 或其他系统；安装与登录过程没有在本次重新测试。
---
## 原文章中的历史案例（保留原文）
以下内容来自本仓库此前发布版本，记录维护者当时的真实知识库维护案例。它不是上面统一练习的实测记录，也不要求首期读者操作该仓库。
# 完成第一个真实任务：从任务描述到验证提交的完整闭环
> 难度：基础
>
> 类型：首次实操
## 这篇文章适合谁
这篇文章写给已经打开 Codex，也准备好一个安全项目，却还没有独立完成过真实任务的读者。
这里的“完成”，指一个真实项目产生了可检查的变化，并且这些变化经过验证、审查和提交。只得到一段看起来合理的回答，还没有走完任务。
## 你会学到什么
本文会完整走一遍下面的过程：
1. 选择一个适合第一次完成的真实任务。
2. 检查项目和 Git 起始状态。
3. 写清目标、上下文、限制和完成条件。
4. 观察 Codex 调查、编辑和运行命令。
5. 在权限请求和中途偏离时做判断。
6. 查看文件差异并独立验证结果。
7. 提交和推送确认通过的修改。
示例使用 Markdown 知识库，读者不需要编程基础。开发者可以把同一套流程换成修 Bug、补测试或修改页面。
## 本文使用的真实任务
本文没有临时创建一个“Hello World”项目。案例来自维护这个 Codex 中文知识库时真实发生的一次任务：
> 在 `00-从这里开始` 栏目中新增第 07 篇文章《完成第一个真实任务》，更新栏目目录和更新日志，加入必要的官方配图，并在发布前检查链接、图片、敏感信息和 Git 差异。
这个任务会修改四类内容：
| 文件 | 作用 |
|---|---|
| `00-从这里开始/07-完成第一个真实任务.md` | 新增正文 |
| `00-从这里开始/README.md` | 把第 07 篇加入阅读顺序 |
| `更新日志.md` | 记录本次内容发布 |
| `图片素材/00-从这里开始/07-完成第一个真实任务/` | 存放与正文直接相关的图片 |
它的范围不大，但包含真实项目里常见的多个步骤：读现有规范、研究资料、创建文件、维护导航、处理图片、运行检查和提交 Git。
## 先理解完整闭环
一次 Codex 任务可以拆成下面八个环节：
```mermaid
flowchart LR
A["确认起点"] --> B["描述任务"]
B --> C["调查项目"]
C --> D["计划修改"]
D --> E["编辑文件"]
E --> F["运行验证"]
F --> G{"结果通过？"}
G -->|"否"| H["分析问题并修正"]
H --> E
G -->|"是"| I["审查 diff"]
I --> J["提交与推送"]
```
很多第一次使用的问题，都源于流程只走到了“编辑文件”，后面的验证、diff 和提交没有完成。
## 第一步：确认任务开始前的状态
打开项目后，不要马上发出修改请求。先确认 Codex 进入了正确的文件夹。
如果项目使用 Git，可以检查：
```bash
git status --short --branch
git log -1 --oneline
```
第一条命令用来查看当前分支和未提交修改，第二条命令确认最近的回退点。
在本案例开始时，需要确认：
- 当前仓库是 `codex-handbook`。
- 当前分支是准备发布内容的分支。
- 前六篇文章已经提交。
- 工作区没有来源不明的未提交修改。
- 目标目录和图片规范文件能够正常读取。
如果工作区已经有修改，不要默认它们可以覆盖。先让 Codex 列出状态，说明哪些文件与本次任务相关，哪些是任务开始前就存在的内容。
### 可以怎样对 Codex 说
```text
先不要修改文件。请检查当前项目、Git 分支和未提交变化，阅读仓库根目录的 AGENTS.md 以及“00-从这里开始/README.md”，然后告诉我这次任务应该修改哪些文件。
```
这一步只需要确认双方正在同一个项目、同一个范围里工作，不需要让 Codex 写一份长报告。
## 第二步：把一句话需求补成可执行任务
用户最初可能只会说：
```text
《07-完成第一个真实任务》接下来写这一篇。
```
如果同一个任务里已经有前文、仓库规则和连续的文章上下文，Codex 可以据此继续工作。但读者第一次独立使用时，不应该假设它已经知道你的全部要求。
按照上一篇介绍的 Goal、Context、Constraints 和 Done when，可以把任务补充成下面这样：
```text
请在 codex-handbook 的“00-从这里开始”栏目新增第 07 篇文章。
目标：写一篇《完成第一个真实任务》，用一个真实的 Markdown 知识库维护案例，讲清从任务描述、执行、验证到 Git 提交的完整流程。
上下文：先阅读 AGENTS.md、图片素材/README.md、栏目 README，以及第 05、06 篇文章，保持现有知识库风格。
限制：
1. 不要写成公众号文章。
2. 不要编造实操截图、测试结果或用户反馈。
3. 官方结论必须引用 OpenAI 官方资料。
4. 实操截图由维护者亲自操作后补充；没有截图时使用官方图或流程图解释。
5. 不修改与本篇无关的目录和文章。
完成条件：
1. 新建文章并更新栏目目录和更新日志。
2. 图片路径、相对链接和官方链接可以访问。
3. 检查敏感信息、Markdown 基础格式和 Git diff。
4. 完成后先汇总修改和验证结果，不要在我审查前提交。
```
这段任务说明并不追求所谓“完美提示词”。它只是把容易产生分歧的地方提前说清楚。
## 第三步：让 Codex 先调查，再开始修改
一个项目通常已经有自己的结构和规则。Codex 在修改前应该先阅读与任务直接相关的文件，而不是凭空创建一套新格式。
本案例需要调查：
- `AGENTS.md` 中的内容和图片规则。
- `00-从这里开始/README.md` 的编号和标题风格。
- 第 05、06 篇的文章结构和引用方式。
- `图片素材/README.md` 中的命名、脱敏和来源要求。
- 当前 Git 状态和最近提交。
你不需要要求 Codex 阅读整个仓库。范围越准确，调查速度越快，也越不容易把无关内容带进任务。
### 怎样判断它是否读对了
开始写之前，Codex 至少应该说清楚：
- 准备新增什么文件。
- 需要更新哪些导航或索引。
- 本篇使用哪类图片，来源是什么。
- 哪些事实需要查官方资料。
- 打算如何验证文章和仓库变化。
如果它准备修改大量无关文件，应该在编辑前缩小范围。
## 第四步：观察过程，但不要逐行遥控
Codex 开始执行后，通常会经历搜索文件、读取规则、查资料、编辑和验证几个阶段。
你需要关注的是方向和边界：
- 它是否仍在处理同一个目标。
- 新发现是否改变了原来的计划。
- 是否要访问新的目录、网络或外部服务。
- 是否出现无法验证的事实或截图。
- 是否准备执行不可逆操作。
不需要对每一次文件读取都下指令。过度干预会打断连续调查，也会让任务记录充满重复确认。
### 什么时候应该马上纠偏
出现下面情况时，直接告诉 Codex 停下并重新确认：
- 开始重写已经完成的前六篇文章。
- 为了“内容丰富”准备添加无关 AI 图片。
- 把尚未实操的过程写成已经成功完成。
- 使用没有来源的套餐、功能或性能结论。
- 准备删除、移动或重命名现有文件。
- 发现工作区中存在用户原有修改，却打算直接覆盖。
纠偏时说明哪里偏了、正确边界是什么，不必从头重发整个任务。
例如：
```text
先停一下。前六篇文章不要改，本次只新增第 07 篇，并更新栏目 README 和更新日志。实操图片还没有由我亲自截图，不要创建或描述不存在的实操结果。
```
## 第五步：认真处理权限请求
Codex 可能请求编辑文件、运行命令、访问网络或执行 Git 操作。第一次任务继续使用 `Ask for approval` 更容易看清每个动作的边界。
> 图片来源：[OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)。本图与第 03、06 篇共用，用来说明首次实操中的审批边界。
看到权限请求时，可以按下面的顺序判断：
1. 这个动作是否服务于当前任务？
2. 它会影响哪个目录和哪些文件？
3. 命令是读取、创建、覆盖还是删除？
4. 网络访问的目标是否是已知官方来源？
5. 执行失败后是否容易恢复？
读取仓库文件、检查 Git 状态和访问 OpenAI 官方文档，通常容易判断。删除文件、安装系统软件、修改仓库权限、推送远端和使用 Full access，需要更谨慎。
批准命令不是在确认“Codex 一定做得对”，只是允许它执行这一个动作。结果仍然需要后续检查。
## 第六步：让 Codex 提供验证证据
编辑完成后，不要只接受“文章已经写好”这样的总结。要求它运行与完成条件对应的检查。
本案例需要验证：
| 检查项 | 证据 |
|---|---|
| 文章文件已创建 | 文件存在，标题和编号正确 |
| 栏目目录已更新 | README 中第 07 项链接指向新文章 |
| 更新日志已更新 | 当天记录包含本篇发布内容 |
| 图片有效 | 文件存在、格式与扩展名一致、正文路径正确 |
| 相对链接有效 | 链接目标文件或目录实际存在 |
| 官方链接有效 | 请求返回成功状态，并落在 OpenAI 官方域名 |
| Markdown 无明显格式问题 | `git diff --check` 没有空白错误，表格和代码块闭合 |
| 没有敏感信息 | Token、私钥和常见凭据模式扫描无结果 |
| 修改范围正确 | Git 状态中只有本篇相关文件 |
### 一组基础 Git 检查
```bash
git status --short
git diff --stat
git diff --check
```
- `git status --short` 显示哪些文件发生变化。
- `git diff --stat` 显示修改规模。
- `git diff --check` 检查多余空格和部分基础格式问题。
这些命令不能证明文章内容一定正确，但能快速发现文件遗漏、意外修改和格式问题。
### 验证失败时怎么办
验证失败不是任务结束，而是下一轮输入。
不要只说“再检查一下”，应该把失败证据交给 Codex：
```text
相对链接检查显示图片路径不存在：
图片素材/00-从这里开始/07-完成第一个真实任务/01-官方App内置Git工具.png
请先确认真实文件位置，只修复这个路径，然后重新运行链接和图片检查。不要改写正文其他内容。
```
错误信息、失败命令和预期结果比“好像不对”更容易让 Codex 准确修复。
## 第七步：自己审查 diff
Codex 运行完检查后，轮到你查看它到底改了什么。
OpenAI 的本地环境文档说明，ChatGPT 桌面 App 的 diff 面板可以查看当前修改、对具体行留下反馈、暂存或恢复单个区块，也可以提交、推送和创建 Pull Request。
> 图片来源：[OpenAI Local environments](https://learn.chatgpt.com/docs/environments/local-environment#use-built-in-git-tools)。页面展示了 App 中查看 Changes、分支、提交、推送和创建 Pull Request 的入口。
### 审查新文章
重点看：
- 标题是否和目录一致。
- 内容是否真的回答了文章主题。
- 官方事实是否有来源。
- 示例是否能让读者照着操作。
- 有没有把建议写成官方硬性要求。
- 有没有编造截图、测试和用户体验。
### 审查目录和更新日志
重点看：
- 编号是否连续。
- 链接路径和文件名是否完全一致。
- 是否误改其他文章标题。
- 更新日志是否只记录已经完成的内容。
### 审查图片
重点看：
- 图片能否解释正文中的具体信息。
- 官方图是否标明来源页面和链接。
- 文件格式和扩展名是否一致。
- 是否出现账号、邮箱、私有路径或 Token。
如果发现问题，可以直接在 diff 中指出具体行，也可以在任务中引用文件路径和段落标题让 Codex 修正。
## 第八步：提交前再做一次独立确认
Codex 的完成说明是线索，不是最终验收结论。
在本案例中，维护者至少要亲自完成下面几项：
- 打开新文章，快速通读一次。
- 点击栏目 README 中的新链接。
- 确认两张图片能够显示。
- 查看 Git diff 中是否有无关文件。
- 核对官方来源和引用说明。
- 确认没有私密计划、聊天记录或凭据进入公开仓库。
代码项目还要增加人工页面检查、关键功能复现或测试结果复核。不要因为命令显示绿色，就跳过用户真正会看到的效果。
## 第九步：提交和推送
只有在内容和验证都通过后，才进入提交阶段。
可以让 Codex 先给出提交范围和建议的提交信息：
```text
请再次确认 Git 状态，只暂存本次第 07 篇文章、栏目 README、更新日志和对应官方图片。提交前运行 git diff --cached --check，并把暂存文件列表给我确认。
```
确认无误后再提交，例如：
```text
docs: add first real task walkthrough
```
推送完成后，还要比较本地和远端分支的最新提交。看到 GitHub 页面中出现新文章，并不一定代表所有文件都上传正确；提交哈希一致才是更直接的证据。
### 推送后检查什么
- 本地工作区是否干净。
- 本地 `HEAD` 与远端目标分支哈希是否一致。
- GitHub 中的文章链接是否可以打开。
- 图片在 GitHub 页面中是否正常显示。
- 目录链接是否跳转到正确文章。
## 一份合格的任务结束报告
Codex 最后的报告应该短，但需要包含证据。
例如：
```text
已完成第 07 篇文章，并更新栏目 README 和更新日志。
新增：
- 00-从这里开始/07-完成第一个真实任务.md
- 图片素材/00-从这里开始/07-完成第一个真实任务/01-官方App内置Git工具.png
更新：
- 00-从这里开始/README.md
- 更新日志.md
已检查：相对链接、官方链接、图片格式、敏感信息和 Git diff。
提交推送后，本地与远端 main 提交一致。
```
“完成了”这三个字没有多少信息。文件、检查命令和远端状态才方便读者判断任务是否真的结束。
## 任务中途发现需求没说清怎么办
真实任务很少从第一句话开始就完全明确。发现缺口时，可以让 Codex 暂停编辑并列出需要决策的地方。
例如：
```text
先暂停修改。请列出目前仍然不确定的内容、每个选择会影响哪些文件，以及你的建议。等我确认后再继续。
```
如果只是局部问题，直接补充约束即可；如果目标本身发生变化，最好结束当前任务或建立新的分支，不要让一个任务不断扩张。
## 任务做坏了怎样处理
先停止继续修改，再根据 Git 状态判断影响范围。
- 只有少量错误时，在 diff 中逐行指出并让 Codex 修正。
- 某个文件整体方向错误时，确认没有用户原有修改后，再使用 App 的恢复功能或 Git 恢复该文件。
- 已经提交但还没有推送时，可以在保留历史的前提下继续提交修正。
- 已经推送并被他人使用时，不要擅自重写共享历史，优先创建修复提交或 Pull Request。
不要在不清楚后果时执行 `git reset --hard`、批量删除或覆盖目录。回退动作同样需要审查。
## 把这套流程迁移到代码任务
知识库案例和代码任务的文件不同，闭环并没有变化。
| 知识库任务 | 代码任务 |
|---|---|
| 新增文章 | 实现功能或修复 Bug |
| 阅读栏目规则 | 阅读项目架构和编码规范 |
| 检查链接和图片 | 运行测试、Lint、类型检查和构建 |
| 人工通读文章 | 手动复现功能或查看页面 |
| 审查 Markdown diff | 审查源代码和测试 diff |
| 更新目录和日志 | 更新文档、变更记录或迁移说明 |
| 推送文章提交 | 推送分支并创建 Pull Request |
第一次代码任务也应该范围小、结果可见、容易回退。修复一个能稳定复现的问题，通常比“帮我重构整个项目”更适合建立正确习惯。
## 第一次真实任务自查表
- [ ] 我确认了正确项目、目录和 Git 分支。
- [ ] 我知道任务开始前有哪些未提交修改。
- [ ] 任务包含目标、上下文、限制和完成条件。
- [ ] Codex 修改前读了相关项目规则。
- [ ] 权限请求都在本次任务范围内。
- [ ] 我在方向偏离时及时补充了约束。
- [ ] Codex 运行了与完成条件对应的验证。
- [ ] 我亲自查看了所有相关文件的 diff。
- [ ] 提交中没有无关文件、敏感信息或虚构结果。
- [ ] 推送后本地和远端提交一致。
十项都能回答清楚，这次任务才形成了真正可复用的经验。
## 下一步学习
完成第一次真实任务后，下一篇会总结 Codex 新手最常见的误区，包括任务范围过大、上下文堆得太多、盲目开放权限、只看回答不看 diff，以及把插件数量当成能力水平。
想练习不同入口的安装和首次运行，可以进入 [安装与首次使用](../01-安装与首次使用/)。需要系统学习任务拆分、计划和纠偏，可以进入 [核心概念与任务方法](../02-核心概念与任务方法/)。
## 参考资料
- [Codex Best Practices](https://learn.chatgpt.com/guides/best-practices)
- [OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)
- [OpenAI Local environments](https://learn.chatgpt.com/docs/environments/local-environment)
- [Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
- [Codex Code Review](https://learn.chatgpt.com/docs/code-review)
- [Git worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
Codex 的界面、权限名称、Git 工具和可用入口可能随版本与工作区设置变化。
### 用一个 Skill 做出可发布的食物广告
URL: https://codexguide.io/cases/yong-skill-zuo-shi-wu-guang-gao
这次实战从一杯还没有名字的概念奶茶开始。我想先把广告图做出来，再回头看这件事能不能整理成一套下次还用得上的 Skill。
# 用一个 Skill 做出可发布的食物广告
这次实战从一杯还没有名字的概念奶茶开始。我想先把广告图做出来，再回头看这件事能不能整理成一套下次还用得上的 Skill。
下面写到的产品信息、画面要求和版本记录，都来自这次对话。广告文章最怕把猜出来的内容写得像真的，所以不确定的信息就不替品牌做决定。
## 先看结果
目前拿到的是一张 3 比 4 竖版奶茶广告图。透明杯、圆形封口盖、冰块和少量珍珠都在，背景压得比较暗，杯子放在中间偏下的位置，HIAPI Logo 也还认得出来。
这张图由 image_gen 生成，先做 v1，再按检查结果改到 v2。v2 是 1086 × 1448，比例为 3 比 4。最后还要在实际阅读页面看一遍，确认平台压缩后 Logo 不糊，杯口和边缘也没有被裁掉。
## 先把一句话说清楚
我没有一上来就说“帮我做一张好看的奶茶广告”。先让 food-advertising Skill 把 brief 问清楚，这一步有点慢，却省掉了后面反复猜的时间。
看起来像填表，其实是在拦住广告里最容易出错的地方。产品名、品牌名、投放渠道、卖点依据、必须出现的文案和禁止元素要分开写。价格、规格、日期还没确认，就先写成待定，别让模型替人做决定。
这次 brief 后来补成了下面这些内容。
| 项目 | 已确认内容 |
| --- | --- |
| 产品 | HIAPI 品牌概念奶茶 |
| 广告目的 | 做一张年轻、清爽、有创意的品牌视觉，用于内容平台和社交媒体 |
| 画面主体 | 透明塑料杯、圆形封口杯盖、奶茶渐变、冰块、奶泡、少量珍珠 |
| 构图 | 3 比 4 竖版，杯子居中偏下，略微俯视，上方留出约 20% 空间 |
| 风格 | 高端商业饮品摄影，带一点 AI 科技品牌气质 |
| 色彩 | 焦糖棕、奶油白、青绿色 Logo、深色简洁背景 |
| 文字 | 不添加标题、口号、价格、参数或其他宣传文字 |
| 禁止事项 | 不出现其他品牌、人物、无关商品、廉价塑料感和复杂科技线条 |
我后来一直盯着 Logo 看。图里的字少，杯子和 Logo 就得自己撑住画面。模型可以把杯子做得很像，Logo 却可能在下一张图里变形，所以它必须单独验。
## 第二步，把判断写进 Skill
一条提示词能做出一张图，换个产品就未必了。所以我把这次用到的流程、参考模板和检查清单整理进 food-advertising Skill，方便下次从同一个起点开始。它的顺序很简单，先读 brief 和品牌素材，提炼主卖点，再确定主体、构图、光线、色彩和文字层级，最后按发布渠道检查，把需要人工确认的地方记下来。
## 第三步，先让模型提出方向
brief 确认后，Skill 给了三个方向。截图里每个方向都写了卖点、主体、光线、适用渠道和风险。这样看起来比较费字，却比“科技感”“清爽感”这种风格标签好选得多。
三个方向分别偏向深色科技棚拍、清爽冷感实验室和焦糖奶泡动态瞬间。最后我选了方向 C。飞溅和珍珠能让静态图有一点动作，放在文章首图里也不至于太安静。
这个方向也有麻烦。飞溅和珍珠一多，画面很快就像海报特效，奶茶反倒退到后面。提示里得写清数量和状态，只说“更有冲击力”基本等于没说。
截图里的约束后来都放进了生成提示。杯子要在清晰的正面区域，Logo 不能被奶泡和飞溅挡住，背景留暗，画面不放标题、价格和参数。比起“高级一点”“更有质感”，这种话更能让结果往正确的方向走。
## 一次生成六张候选
方向确定以后，才开始生成。HIAPI 调用三个模型，每个模型出两张，一共六张。画布统一用 3 比 4 竖版，原始 HIAPI Logo 作为参考图上传。
六张图放在一起，差异就很明显了。GPT Image 2 的奶茶质感、冰块和冷凝水比较自然，v2 的飞溅和珍珠却多了些。Seedream 5.0 Pro 的 Logo 几何形状保持得更好，v2 的构图也更干净。Nano Banana 2 两版的 Logo 都错了，还带出额外文字和错误颜色，我不会拿它们直接发。
自检最后推荐 Seedream 5.0 Pro v2。判断时看的是 Logo、构图、奶茶质感和禁用元素，单看哪张图最漂亮不够。后面还得人工看一遍，尤其是 Logo 是否原样、珍珠有没有过量、飞溅有没有挡住杯身。
这次还做了一轮模型接力。Nano Banana 2 的原始图片背景和杯子状态不错，Logo 却出了问题。于是我拿 Seedream 5.0 Pro v2 里正确的 Logo 当参考，让 Nano Banana 2 只修 Logo 和错误文字，保留原来的背景、光线和构图。
修复后的两张图都是 1086 × 1448，错误图形、错误颜色和多出来的文字已经去掉，杯身只留下青绿色分段 Logo。
这也正是我觉得 HIAPI 好用的地方。用 HIAPI 可以对比多个模型，如果某个模型的背景不错但是有瑕疵，可以用另一个模型弥补。一个模型把背景做得好，另一个模型把 Logo 修得准，合起来往往比强求一个模型一次完成更省事。前提是每次只改明确的问题，别让修图模型顺手把整张图也换掉。
## 第四步，从 v1 改到 v2
候选图先过一轮自检，再进入 v1 到 v2 的修改。问题还是飞溅和珍珠。它们一多，杯身上的 Logo 就容易被挡，视线也会从奶茶滑到四周的装饰上。
第二版只动必要的地方。飞溅和珍珠减下来，杯子、冰块、奶泡、渐变色和青绿色 Logo 保留，再看一遍 3 比 4 画布里的主体位置。
我最后按这几项检查。
- 使用了上传的 HIAPI Logo 素材
- 画布为 1086 × 1448，比例为 3 比 4
- 画面没有标题、口号、价格、参数、人物或其他品牌标识
- Logo 位于杯身正面，主体细节没有被飞溅遮挡
- 奶茶、冰块、冷凝水和珍珠保留了商业摄影质感
这次 Skill 更像一张检查单。选哪张图，Logo 能不能发，最后还是我自己看。这样挺好，至少不会只凭第一眼的感觉交稿。
## 这次实战留下的经验
我现在更愿意把 Skill 理解成一张工作单。它提醒我先问什么、比较什么、哪一步要停下来人工看。下次换成别的食物，至少不用从一句“做得好看点”重新开始。
模型负责把画面方向摊开，产品事实和品牌边界还是得由人确认。图片生成完也不等于可以发布，手机端的 Logo、渠道裁切和最后那点细节，都要有人亲自看。
### 用 HIAPI 中文图标 Skill，做一套真正统一的产品图标
URL: https://codexguide.io/cases/hiapi-zhong-wen-tu-biao-skill
单独做一枚图标不算难，难的是让一组图标看起来像同一套。主体大小、视角、材质和留白只要有一项没对齐，摆在一起就容易显得散。
# 用 HIAPI 中文图标 Skill，做一套真正统一的产品图标
单独做一枚图标不算难，难的是让一组图标看起来像同一套。主体大小、视角、材质和留白只要有一项没对齐，摆在一起就容易显得散。
这篇文章用 [HIAPI 中文图标 Skill](https://github.com/HiAPIAI/hiapi-icon-skills) 走一遍完整流程：先确定风格和色板，再做 2×2 试稿，接着把同一张参照图交给三个模型，比较它们对图标语义、材质和体积感的处理。文中的提示词可以直接复制，再按你的产品改图标名称和颜色。
## 一、安装 Skill
在 Codex 终端中运行：
```powershell
npx -y github:HiAPIAI/hiapi-icon-skills -y --codex
```
安装完成后重启 Codex，确认技能列表里已经出现 `hiapi-icon-skills`。如果没有看到，先检查安装命令是否报错，再确认 Skill 是否安装到了当前 Codex 使用的技能目录。
截图时不要带上 API Key、个人目录或账号信息。
## 二、先选方向，不急着出图
第一次对话没有直接生成图片，只让 Codex 从 Skill 中推荐风格和色板。
```text
HIAPI 中文图标技能，我准备制作一套功能图标。帮我推荐一个适合中文风格的，顺便说明选择理由。
```
Codex 推荐的是“墨线跳色”风格和“薄荷清晨”色板。前者用水墨线条收住轮廓，后者以薄荷绿、雾蓝和杏色为主，适合中文产品界面的功能图标。
## 三、用 2×2 试稿验证整套风格
方向确定后，我让 Codex 先做搜索、消息、日历和云端四枚图标，并排成一张 2×2 的图。四个主体的轮廓差别很大，用来检查整套风格是否统一很合适。
```text
就按这个方向来。先做搜索、消息、日历、云端这 4 个图标，排成一张 2×2 的图。四个图标要像同一套产品里的，主体大小、视角、材质、光线和留白统一。不要文字、字母、Logo、复杂背景。
```
## 四、同一张参照图，同时比较三个模型
第一版的内容和配色已经确定。接下来，我把这张图作为参照，同时调用三个模型生成更立体的 Q 版图标。三次生成使用同一张参照图和同一组要求，结果更方便比较。
```text
参考这张图，把四个图标改成更 Q、更立体的 3D 风格，保持原来的 2×2 排版和薄荷绿配色。使用本地 HIAPI_API_KEY 调用 Nano-Banana-2、Seedream 5.0、GPT Image 2.0 生成模型，各生成一版方便选择。
```
截图中的实际模型 ID 是 `seedream-5.0-pro/image-to-image`、`gpt-image-2/image-to-image` 和 `nano-banana-2`。前两个模型保留了搜索、消息、日历和云端，Nano-Banana-2 却生成了钟表、灯泡、齿轮和星星，图标含义已经变了。
## 五、放大看两个可用候选
先看 Seedream 5.0 Pro。搜索、消息、日历和云端都没有被换掉，2×2 排版也与参照图一致。画面使用薄荷绿、白色和浅蓝色，四枚图标都有清晰的立体厚度和投影。
图五是 GPT Image 2 基于同一张参照图独立生成的结果，不是对图四的二次修改。它同样保留了四个图标的含义和位置，不过主体更大，圆角更明显，投影也更重。
这次对比最先要看的不是哪张更漂亮，而是模型有没有保留原来的四个功能。Nano-Banana-2 的画面也有 3D 效果，但内容已经不是搜索、消息、日历和云端，不能作为这一轮的候选，这也是用HIAPI的好处，一次性多模型多产出，选择更多不怕废片。
## 六、环境变量要这样处理
项目约定的环境变量名是 `HIAPI_API_KEY`，中间有下划线，不是 `HIAPIAPIKEY`。
如果本地已经配置过 Key，可以让 Codex 只检查它是否存在：
```text
我本地应该已经配置了 HIAPI_API_KEY。你只检查这个环境变量是否存在，不要输出 Key 的值，也不要创建付费任务。告诉我检查结果即可。
```
Windows PowerShell 临时设置示例：
```powershell
$env:HIAPI_API_KEY = "你的 Key"
```
不要把真实 Key 截进图片、写进文章、提交到仓库，或放进公开的 `.env` 文件。环境变量存在，也不等于已经授权 Codex 调用付费接口。涉及外部计费时，先确认模型、预算和调用次数，再开始生成。
## 七、这套流程为什么更稳
这次测试的步骤很简单：先用 2×2 试稿确定图标内容，再把同一张参照图交给三个模型。因为输入条件相同，主体大小、投影和材质上的差别一眼就能看出来。挑选结果时先核对图标含义，确认没有跑题，再比较视觉效果。
如果你也想用这套流程做产品图标，可以先去 [HIAPI](https://www.hiapi.ai/en/register?aff=AR3h) 注册账号，再安装上面的中文图标 Skill。
HIAPI 中文图标 Skill 开源仓库：[https://github.com/HiAPIAI/hiapi-icon-skills](https://github.com/HiAPIAI/hiapi-icon-skills)
## 相关链接
- [HIAPI 中文图标 Skill](https://github.com/HiAPIAI/hiapi-icon-skills)
### Codex 协助客座文章外链实验
URL: https://codexguide.io/cases/codex-guest-post-case
这篇记录一次由 Codex 协助完成的客座文章外链实验，重点是它怎样整理筛选条件、检查提交字段和复核发布结果。
# Codex 协助客座文章外链实验
这篇记录一次由 Codex 协助完成的客座文章外链实验，重点是它怎样整理筛选条件、检查提交字段和复核发布结果。
之前我对客座文章这种外链方式只停留在概念上，知道它大概是找一个相关网站，发布一篇带链接的文章，用来给目标页面增加相关性和权重。
这次是第一次实际操作，Codex 帮我把流程跑了一遍。
平台怎么用，筛选条件怎么设，哪些网站看起来指标好但不值得买，文章该怎么写，提交前有哪些必填内容...
Codex 很适合做这种平台的实操，替我把大量细节先梳理清楚，替我操作。
## 先用小预算熟悉平台
这次选的是一个提供客座文章发布服务的平台，先用小预算熟悉流程。
第一次进入这类平台，最容易被一堆指标绕晕。价格、域名权重、自然流量、国家、语言、分类和链接属性都要看。
Codex 先给了我筛选条件。针对自己的网站情况，我们先把语言限定为英文，把分类限定在 Software development 和 Technology，再给价格设一个上限。
目标很明确，先把范围缩小到和自己的网站更相关、预算还能接受的网站，不追求找到全平台最强的网站。
**这一步里，人要做的是定边界。**
比如我知道这次是给 Codex 工具站做外链，不想买太泛娱乐、金融、生活方式的站。Codex 做的是把这些边界翻译成平台上的筛选条件，再帮我解释每个指标代表什么。
## 看指标，也看这个站像不像真的相关
筛出来以后还有几百个网站，这时候平台的推荐排序就不够用了。
Codex 帮我做了一轮筛选。它会看每个站的价格、流量、域名指标和链接属性，也会继续搜索这个站有没有开发工具和软件开发相关内容。
这个过程里，我学到一个很实用的判断方法。
**一个站不能只看指标，还要看它平时发什么内容。如果一个站满屏都是 crypto、loan、casino、trading 这类高商业化内容，即使 DR 看起来很高，也要谨慎。**
它可能更像一个卖链接的内容农场。
这一步里，人要判断业务价值。Codex 可以帮我把 900 多个候选缩成几个优先级，但最后为什么选一个站，还是要回到项目目标上。我们的网站聚焦 Codex 教程和使用决策，不应该为了一个便宜链接去买完全不相关的网站。
## 文章不是随便写一篇就行
确定网站以后，下一步是准备 guest post。
这次的承接页是一篇 Codex 开发者教程，所以客座文章也围绕开发者如何判断 Codex 是否适合自己的工作流来写。
Codex 帮我写了一篇英文文章，主题是从真实工作流出发判断编码助手是否适合自己，并把重点落到 Codex 的使用场景。
我不想让这篇文章看起来像硬塞链接，所以锚文本直接描述承接页内容，并把 Codex 放在正文语境里自然出现。
文章写完后，Codex 又帮我检查了几个细节。
目标 URL 要和正文里的链接一致，锚文本要和平台字段一致，正文要满足平台要求的最低字数，Special requirements 要写清楚，希望发布在 software development 或 developer tools 相关栏目里。
Codex 的作用很具体。它会写文章，也会做提交前检查。很多新手第一次买客座文章时，大方向可能已经想清楚了，最后容易栽在这些小字段上。
URL 填首页还是承接页，锚文本有没有和正文一致，图片位置是不是放错了，浏览器翻译插件有没有把中文残留混进正文。
我最后让 Codex 把提交页逐项复核了一遍。
这次文章还加了一张配图。图是为了让文章看起来更完整，也减少发布方随便配一张不相关图的概率。
配图这件事其实也有一套小流程。
先判断是否需要配图，再生成一张和文章主题一致的图，然后上传到图床，最后把图片地址插到文章里。
提交前我又让 Codex 检查了一次正文。最后它通过浏览器把源码里的正文清理了一遍，确认没有明显问题后，才建议我提交订单。
## 人负责判断，Codex 负责执行和检查
人和 Codex 应该怎么分工。
人负责判断目标。为什么要买这条外链，预算是多少，能接受什么风险，什么类型的网站和我们的产品相关，自己心里要有一个判断。
Codex 适合负责流程执行。它可以帮我读平台、解释字段、设计筛选条件、初筛候选网站、检查内容相关性、写文章、生成配图、上传图床、复核提交字段，还能控制浏览器把一些重复操作走完。
在这个过程中，Codex 会把平台里零碎、容易漏的步骤整理出来，然后一项项执行。
有 Codex 辅助能降低上手成本，也能减少因为不熟平台而犯的低级错误。
最后，客座文章有没有效果，不能看提交完了就结束，而是要等文章发布后继续跟踪。后面还要记录发布 URL、是否 Dofollow、是否收录，以及 Codex 承接页的曝光、点击和平均排名有没有变化。
提交成功后，钱会先进入 Reserved，不是立刻最终完成。
任务会出现在平台的任务列表里，这个页面后面就是验收入口，等文章发布后，还要从这里回来看发布 URL 和任务状态。
## 发布后还要做一次验收
这件事还没有真正结束。等对方发布文章以后，我还要做一次验收。
第一步是在平台里拿到发布 URL，打开页面确认它能正常访问。页面要返回 200，文章内容不能变成拼接稿，标题、配图、段落结构也要基本正常。然后检查 Codex 相关承接页的链接是否还在，锚文本和目标地址是否正确。
第二步是看链接属性。平台里显示的是 Dofollow，但最终还是要以发布页实际 HTML 为准。需要检查链接有没有被改成 nofollow、sponsored，或者被跳转链接包了一层。如果链接被删了、锚文本被改了、目标页被改错了，就要回到平台任务里沟通修改。
第三步是看这篇文章是否有基本的收录可能。可以先看页面是不是 noindex，再过几天搜索文章标题或使用 site 查询，看它有没有被搜索引擎发现。这个阶段不要急着看排名，因为外链从发布到被发现，再到可能影响目标页，通常需要时间。
4 到 8 周后，再看 Codex 承接页的数据。重点是比较曝光、查询词和平均排名的变化。
如果数据完全没变化，也不代表这条外链一定没用，但至少说明它不是短期明显有效的动作。如果发布页质量一般、没有收录、没有带来任何相关查询变化，后续就不应该继续批量买同类站。反过来，如果发布页正常收录，目标页开始出现更多相关查询，这条实验就值得记录下来，后面可以用类似方法继续找更相关的网站。
这次实验也说明，Codex 可以把外链筛选、提交检查和后续验收串起来，但发布后的数据仍然需要人工持续观察。
### 在 Codex 中连接 Notion：把调研结果写入数据库
URL: https://codexguide.io/cases/codex-notion-plugin-workflow
这篇教程适合已经能在 Codex 桌面端创建任务，并希望把调研结果直接整理到 Notion 的读者。完成后，你会连接 Notion 插件、验证页面读取权限，并把一组结构化资料写入两个数据库。
# 在 Codex 中连接 Notion：把调研结果写入数据库
这篇教程适合已经能在 Codex 桌面端创建任务，并希望把调研结果直接整理到 Notion 的读者。完成后，你会连接 Notion 插件、验证页面读取权限，并把一组结构化资料写入两个数据库。
示例只使用测试工作区。不要用客户资料、内部知识库或个人页面做第一次连接测试。
## 本教程环境
以下环境核验于 2026 年 8 月 13 日。Notion 插件运行在 Codex 桌面端的 Plugins 界面中，不要求通过 IDE 或 Codex CLI 操作。
| 项目 | 本教程使用版本 | 获取方式 | 备注 |
|---|---|---|---|
| 操作系统 | Windows 11 专业版 64 位，构建 `26100` | Windows 系统信息 | 本机实测环境 |
| Codex 桌面端 | `26.803.10989.0` | Windows 应用包信息 | 本教程的插件宿主 |
| Notion 插件 | 目录托管版本，界面未展示独立版本号 | Codex Plugins 目录 | 以当前插件详情为准 |
| Notion Connector | Web 托管版本，界面未展示独立版本号 | Notion 授权界面 | 可用权限受工作区设置影响 |
| Codex CLI | `0.146.1` | `codex --version` | 本教程不在 CLI 中执行 |
界面、插件入口和授权范围可能随 Codex、Notion 或工作区策略调整。操作时以当前页面为准。
## 先说结论
这套流程分成四步：安装插件、限制授权范围、用测试页面验证读取、确认字段后再写入数据库。
真正需要谨慎的是授权和写入。第一次连接时只开放测试页面；批量创建或更新内容前，先让 Codex 列出准备执行的操作。
## 1. 安装 Notion 插件
启动 Codex 桌面端，在左侧导航栏打开“插件”。如果没有这个入口，先确认当前版本和工作区支持 Plugins，再检查组织管理员是否限制了插件安装。
进入插件目录，在搜索框输入 `Notion`。核对名称和说明后点击安装。
安装过程中，Windows 可能询问是否允许网页打开 ChatGPT。确认地址和来源无误后再继续。不希望系统以后自动跳转，就不要勾选“始终允许”。
## 2. 限制 Notion 授权范围
连接窗口会列出 ChatGPT 与 Notion 之间共享的数据。先检查申请的权限，再确认选中的 Notion 工作区。
本教程没有保留工作区选择页，因为原画面包含个人空间名称。制作自己的操作记录时，也应隐藏邮箱、成员名单、内部页面名称和授权令牌。
建议新建一个只含公开示例内容的测试页面，并只把这个页面开放给连接。等读取和写入都验证完成，再根据实际任务扩大范围。
## 3. 用测试页面验证连接
新建 Codex 任务，在输入框键入 `@notion`，从候选列表中选择 Notion 插件，然后写清楚要读取的测试页面。插件必须加入当前任务，Codex 才能在这轮对话中调用它。
第一次只做只读验证。可以使用下面的任务描述：
```text
请读取 Notion 中的测试页面“Notion-Codex demo”，只返回页面标题、正文是否为空和当前可见的属性。不要创建、修改或删除任何内容。
```
本次示例返回的页面只有标题，没有正文。这说明连接已经建立，Codex 也能访问指定页面。
如果提示找不到页面，先检查页面是否属于已授权工作区、当前账号是否有访问权限，以及授权时是否选中了正确页面。不要为了绕过错误直接开放整个工作区。
## 4. 调研资料并确认字段
连接验证通过后，再提交正式调研任务。本次示例整理主流 AI 图片与视频生成模型，要求优先使用官网、官方文档、公告和定价页，并记录：
- 模型名称、厂商、发布时间和版本。
- 核心参数、可用状态和价格。
- 优点、限制、推荐场景和官方来源。
- 官网没有公开的字段标为“暂未公开”，不补猜测值。
Codex 完成检索后，先在任务中检查结构化结果，不要立刻写入 Notion。截图中的调研基准日是 2026 年 8 月 12 日；模型状态和价格变化较快，复用这套表格时需要重新核对。
检查时重点看字段是否一致、每条记录是否有来源、未知信息是否被明确标出。发现无来源的价格或参数，先删除或补证据。
## 5. 写入 Notion 数据库
确认内容后，再让 Codex 创建一个总览页，并把图片模型和视频模型分别放进两个子数据库。总览页保留调研日期、使用说明和数据库入口。
图片模型数据库使用厂商、可用状态、计费方式、优势标签、推荐场景和官方来源等字段。标签适合筛选，官方来源用于后续复核。
视频模型数据库沿用同一套字段。图片和视频分开后，各自的版本、状态和价格更容易维护。
## 如何验收
写入完成后，不要只看 Codex 的完成提示。回到 Notion 逐项检查：
1. 总览页和两个数据库位于预期的测试页面下。
2. 数据库字段名称、类型和选项一致。
3. 每条记录都有可打开的官方来源，未知字段没有被猜测值填满。
4. 没有覆盖同名页面，也没有修改授权范围之外的内容。
5. 测试结束后，Notion 连接设置中的访问范围仍符合预期。
如果结果不对，先停止后续写入。记录出错的字段或页面，再让 Codex 只修正这一小部分。
## 权限与限制
- 插件能看到什么，取决于 Notion 账号、工作区策略和授权页面范围。
- 批量写入前先要求 Codex 列出目标页面、数据库和字段，不要把确认步骤省掉。
- 价格、地区可用性和 Preview 状态会变化，资料库应保留来源与核验日期。
- 不再使用的测试连接可以撤销；测试页面应与正式知识库分开。
- 本教程只验证了页面读取、页面创建和数据库写入，没有验证团队级权限管理或大批量更新。
## 参考资料
- [Notion 官方网站](https://www.notion.com/)
- [OpenAI Codex 文档](https://developers.openai.com/codex/)
### 用开源 img-convert Skill 批量压缩图片
URL: https://codexguide.io/cases/img-convert-pi-liang-ya-suo-tu-pian
整理文章配图时，我经常重复做几件事。限制图片宽度，转成 WebP，控制文件大小，最后确认原图没有被覆盖。这个流程已经有人做成了开源工具和 Skill，没必要从零写一套。
# 用开源 img-convert Skill 批量压缩图片
整理文章配图时，我经常重复做几件事。限制图片宽度，转成 WebP，控制文件大小，最后确认原图没有被覆盖。这个流程已经有人做成了开源工具和 Skill，没必要从零写一套。
这篇实战使用 [dutchbase/img-converter](https://github.com/dutchbase/img-converter) 提供的 `img-convert` Skill。目标是把指定文件夹中的图片统一限制在 1200px 宽，转成质量 85 的 WebP，并把结果放进新目录。
> 测试环境为 Windows 11 24H2（26100.4652）、Codex Desktop 26.810.7004.0、Codex CLI 0.147.0、Node.js 22.22.3、skills 1.5.22 和 img-convert 1.0.4，2026-08-17 核验。
> 开源项目、Skill 与 CLI 安装、dry-run、三图批量转换和原图/输出目录对比均已于 2026-08-17 实测并截图。
## 一、先看这个开源 Skill 能做什么
`img-convert` 基于 Sharp，仓库使用 MIT 许可证。项目同时提供命令行工具、Node.js API、MCP 服务和一份现成的 `SKILL.md`。这篇只使用最简单的组合，让 Codex 按 Skill 中的规则判断，再调用 CLI 处理本地图片。
它支持 JPEG、PNG、WebP、AVIF、GIF 和 TIFF 输出，也能调整尺寸、压缩质量、旋转、裁边和读取图片信息。批量任务既可以传入 glob 路径，也可以使用 JSON 清单。
安装前可以先让 `skills` 命令读取仓库，确认其中确实有 `img-convert`。
```powershell
npx -y skills add https://github.com/dutchbase/img-converter --list
```
命令应显示一个名为 `img-convert` 的 Skill。不要只凭第三方介绍页安装，仓库中的 [SKILL.md](https://github.com/dutchbase/img-converter/blob/main/SKILL.md) 才是实际内容。
## 二、安装 Skill 和命令行工具
先把 Skill 安装到 Codex 的全局技能目录。
```powershell
npx -y skills add https://github.com/dutchbase/img-converter `
--skill img-convert `
--agent codex `
--global `
--yes
```
Skill 只负责告诉 Codex 怎样使用工具，并不会自动安装 `img-convert` 命令。还要安装仓库发布的 npm 包。
```powershell
npm install -g @dutchbase/img-convert
```
本次安装成功，但 npm 同时提示其依赖的 `glob@10.5.0` 已弃用。这个警告不影响本文测试。在生产目录或自动化流水线使用前，应重新检查包版本、依赖审计结果和仓库更新情况，先用可恢复的图片副本测试。
这个工具要求 Node.js 18 或更高版本。安装完成后检查命令是否可用。
```powershell
node --version
img-convert --help
img-convert info --help
img-convert batch --help
```
## 三、把处理规则说清楚
这次使用下面这组参数。
| 项目 | 设置 |
| --- | --- |
| 输入 | 指定目录中的 JPG、JPEG、PNG 和 WebP |
| 输出目录 | 新建 `output` 目录 |
| 最大宽度 | 1200px |
| 输出格式 | WebP |
| 图片质量 | 85 |
| 原文件 | 保留，不覆盖、不删除 |
`img-convert` 默认保持宽高比，也默认禁止放大小图。宽度超过 1200px 的图片会等比缩小，小于 1200px 的图片保持原尺寸。
输出目录必须和原图目录分开。这样即使命令参数写错，原文件也还在。
## 四、先预演，不急着写文件
假设原图位于 `D:\images\original`，先运行 `--dry-run` 查看将要处理的文件。
```powershell
img-convert "D:/images/original/**/*.{jpg,jpeg,png,webp}" `
--format webp `
--width 1200 `
--quality 85 `
--output "D:\images\output" `
--dry-run `
--json
```
这里把 glob 路径放在引号中，让 `img-convert` 自己展开文件列表。Windows 下的 glob 要使用正斜杠 `/`，反斜杠会被当成转义符，可能导致一张图片都找不到。预演后要核对文件数量和输出目录，还要检查两个不同格式的同名文件会不会写成同一个 `.webp`。
## 五、确认后再批量转换
预演没有问题，就去掉 `--dry-run`。
```powershell
img-convert "D:/images/original/**/*.{jpg,jpeg,png,webp}" `
--format webp `
--width 1200 `
--quality 85 `
--output "D:\images\output" `
--json
```
`--json` 会返回每张图片的输入大小、输出大小、压缩比例、尺寸和保存路径。文章后面可以直接根据这些结果统计总共节省了多少空间，不需要手工逐张计算。
截图中用 `compact-json.js` 只调整真实 JSON 的换行，字段和值没有改动。三张图片全部转换成功，失败数为 0。
如果不同图片需要不同尺寸或格式，可以让 Codex 先生成 JSON 清单，再运行下面的命令。
```powershell
img-convert batch jobs.json --json
```
简单的统一转换用 glob 就够了，不必先做清单。
## 六、直接让 Codex 调用 Skill
安装并重启 Codex 后，可以这样说。
```text
使用 img-convert Skill，先检查 D:\images\original 中会被处理的 JPG、JPEG、PNG 和 WebP 图片。
把宽度限制为 1200px，保持比例，不放大小图，统一转成质量 85 的 WebP，输出到 D:\images\output。
保留所有原文件。先 dry-run 并汇报文件数量和命名冲突，确认没有问题后再执行，最后给出处理成功数、失败数和总压缩比例。
```
这段要求把检查、预演、执行和汇报写在了一起。Skill 还会提醒 Codex 先读取陌生图片的信息，尤其注意透明通道和动画图片。
## 七、用三张公开图片验证
测试集包含一张 1800×1200 JPG、一张 560×560 PNG 和一张 550×368 WebP。大图被等比缩到 1200×800；两张小图仍保持原尺寸，说明设置 `--width 1200` 不会把小图放大。
结果也说明“统一转 WebP”不等于每张都会更小。JPG 减少 48.8%，PNG 减少 14.2%，但原本已经压缩过的 WebP 重新编码后反而增大 19.7%。批量任务结束后必须检查负压缩率，不能只看成功数量。
## 八、记录批量处理结果
| 项目 | 处理前 | 处理后 |
| --- | --- | --- |
| 图片数量 | 3 | 3 |
| 总文件大小 | 237,357 字节 | 144,698 字节 |
| 最大宽度 | 1800px | 1200px |
| 文件格式 | JPG/PNG/WebP | WebP |
| 失败数量 | - | 0 |
总大小减少 92,659 字节，整体压缩率约 39.0%。原图目录没有被覆盖，三个 WebP 都写入独立的 `output` 目录。
下图直接使用三张公开测试原图拼接，标签列出对应的输出尺寸和文件大小变化。
## 九、最后检查这些情况
- 原图数量、名称和内容没有变化
- 输出图片都位于单独目录
- 横图和竖图保持原始比例
- 小于 1200px 的图片没有被放大
- 透明区域没有意外变黑
- 动画图片没有在不知情的情况下只保留第一帧
- 同名输入不会静默覆盖同一个 WebP 文件
- 失败文件及原因已经单独列出
## 十、项目链接
- GitHub [dutchbase/img-converter](https://github.com/dutchbase/img-converter)
- Skill 源文件 [SKILL.md](https://github.com/dutchbase/img-converter/blob/main/SKILL.md)
- npm 包 [`@dutchbase/img-convert`](https://www.npmjs.com/package/@dutchbase/img-convert)
- 许可证 [MIT License](https://github.com/dutchbase/img-converter/blob/main/LICENSE)
## 快速上手
### 修改本地网页并检查结果
URL: https://codexguide.io/quickstarts#quickstart-first-local-web-task
用独立的 HTML/CSS 练习完成首个小修改，保留按钮链接与样式，再查看 diff 和浏览器页面。
- 尚未准备好：先阅读安装与首次使用、登录和打开本地项目；已经能使用 App 或 CLI：直接复制练习包中的起始文件到新的测试目录。
- 在 Codex App 或 CLI 中打开复制出的目录，确认其中直接包含 index.html 和 styles.css；不要直接修改原始 starter。
- 让 Codex 只把主标题改为“我的第一个 Codex 练习”，把简介改为“先看清修改，再确认页面结果。”，保留按钮链接、其他 HTML 和全部 CSS。
- 查看 diff，再在浏览器打开 index.html，确认标题、简介、按钮和样式；不运行安装或部署命令。
验收: 只有 index.html 的标题和简介改变，按钮仍指向 https://example.com，styles.css 未变，浏览器页面与目标文字一致。
### 首次安装、登录并打开项目
URL: https://codexguide.io/quickstarts#quickstart-install-login-open-project
用最少的配置完成第一次 Codex 本地启动，确认账号、工作目录和 Git 状态都可用。
- 从 OpenAI Codex 官方入口选择 App、CLI 或 IDE extension，并按当前系统完成安装。
- 使用 ChatGPT 账号或 API Key 登录；不要把 token、auth.json 或 .env 提交到仓库。
- 打开一个范围清楚、可以回退的项目目录，先运行 git status --short --branch。
- 让 Codex 只读 README、依赖文件和测试目录，先回报项目用途、启动命令和未知信息。
验收: 你能说明当前项目、当前分支、启动命令和第一项可回滚任务，且工作区没有意外修改。
### 完成一个可回滚的真实任务
URL: https://codexguide.io/quickstarts#quickstart-complete-reversible-task
从清晰目标开始，经过读取上下文、最小修改、验证和 diff 审查，走完一次完整闭环。
- 选择一个十几分钟到一小时内能验收的小任务，例如修复可复现的 Bug、补一条测试或更新一段文档。
- 写清 Goal、Context、Constraints 和 Done when，指定允许修改的目录与禁止触碰的内容。
- 让 Codex 先调查并提出计划，再执行最小范围的修改；中途检查 diff，不把多个结果混在一个任务里。
- 运行与任务对应的测试、构建或页面检查，记录成功、失败和无法验证的部分。
- 审查 git diff 与 git status，确认没有敏感文件或无关重构，再提交或回滚。
验收: 任务有可复现的完成标准，验证命令有输出，diff 只包含目标改动，并且能在需要时恢复到起点。
### 排查权限、Git 或验证失败
URL: https://codexguide.io/quickstarts#quickstart-troubleshoot-permission-git-verification
遇到批准弹窗、工作区冲突、命令失败或测试不稳定时，按证据定位问题，不靠重复重试。
- 先保存失败命令、完整错误、当前路径和 git status，不要先删除缓存或覆盖现有修改。
- 检查请求是否越过工作区、是否需要网络，以及命令会读写哪些文件；高风险操作使用 Ask for approval。
- 确认失败属于环境基线、权限策略、依赖缺失、Git 冲突还是本次代码修改，并逐项隔离。
- 用最小复现重新运行验证；若仍失败，记录已验证的范围和不能验证的原因。
- 检查 diff、依赖锁文件和配置，避免用 Full access 或大范围重构掩盖根因。
验收: 你能把失败归类到明确原因，提供一条可复现命令和下一步动作，而不是只报告“Codex 已完成”。
## 进阶专题
### config.toml 配置指南：exec、沙箱与审批策略
URL: https://codexguide.io/advanced/config-toml
从默认配置到项目级覆盖，理解 Codex 的 config.toml 如何影响模型、沙箱、审批策略和命令行工作方式。
#### 先从最小配置开始
配置文件应只保留团队确实需要固定的选项。先完成一次可回滚的任务，再根据重复出现的偏好补充配置。
把个人偏好放在用户级配置，把仓库协作约定放在项目说明文件中，避免把机器路径和密钥提交到 Git。
- 默认从受控工作区、最小权限和 Ask for approval 开始。
- 修改前保留原文件并查看 diff。
- 敏感值使用环境变量或凭据管理器。
- 每次改动后用一个小任务验证实际生效。
#### exec 与 interactive 怎么选
两种方式的差异在于任务是否需要持续的人机确认。exec 更适合可重复的命令和 CI，interactive 更适合调查、修改和逐步排障。
维度 | exec | interactive
输入方式 | 一次性命令或脚本 | 持续对话
输出形式 | 退出码、日志和结果 | 对话、diff 和人工确认
审批设计 | 预先定义策略 | 执行中逐项确认
适用场景 | 自动化、批处理、CI | 调查、修改、逐步排障
完成证据 | 命令输出、测试结果 | diff、测试和人工检查
#### sandbox、permissions 与 approval policy
sandbox 决定执行环境可访问的资源，permissions 描述任务允许触碰的范围，approval policy 决定哪些动作需要人工确认。它们不是同一个开关，调整前先明确要解决的具体阻塞。
遇到文件被拒绝、网络审批或 Full access 疑问时，可以直接查看[权限与审批 FAQ](/guides/faq#permissions)。
- 文件写入失败：先检查工作区和路径。
- 网络或工作区外操作：确认目标后再批准。
- 高风险命令：保留备份和回滚点，不用扩大权限掩盖根因。
#### slash commands 速查
斜杠命令属于交互入口，具体可用项会随当前 Codex 版本和入口变化。使用前先在当前环境查看帮助，不要把旧版本命令写入自动化脚本。
- 先查看当前入口提供的帮助和命令列表。
- 把重复且稳定的流程沉淀到 AGENTS.md 或 Skill。
- 命令执行后仍需查看 diff 和验证结果。
#### 与快速上手衔接
如果还没有稳定的本地工作流，先完成[首次安装、登录并打开项目](/quickstarts#task-quickstarts-title)，再逐项调整配置。
#### 交叉阅读
需要收紧权限时阅读[权限与安全边界](/codex/permissions)；需要判断配置是否生效时阅读[从 diff 到回归检查](/codex/validation)；遇到具体错误时进入[权限与验证 FAQ](/guides/faq#permissions)。
### AGENTS.md 项目协作规则
URL: https://codexguide.io/advanced/agents-md
用 AGENTS.md 给 Codex 提供可检查、可继承的项目上下文，让修改范围和验收标准保持一致。
#### 写清楚四件事
一份有效的 AGENTS.md 至少说明项目用途、常用命令、目录边界和完成标准。规则要具体到可以执行或验证，而不是只写风格口号。
- 允许修改哪些目录，禁止碰哪些文件。
- 安装、开发、测试和构建命令。
- 提交前必须运行的检查。
- 生成文件、迁移和生产操作的审批要求。
#### 先验证再扩大范围
可以先按[完成一个可回滚的真实任务](/quickstarts#task-quickstarts-title)验证规则是否足够，再把稳定做法沉淀回 AGENTS.md。
### 权限与安全边界
URL: https://codexguide.io/advanced/permissions-security
掌握 Codex 的工作区、网络、审批和敏感信息边界，降低自动化修改带来的误操作风险。
#### 把权限当作任务约束
权限越大，错误操作的影响面越大。默认从受控工作区和最小权限开始，遇到需要联网、写入工作区外或执行高风险命令时再明确审批。
- 先看 git status，确认已有改动不会被覆盖。
- 不要把 token、auth.json、.env 或客户数据放入提示词和提交。
- 生产、数据库和删除操作必须由人确认。
#### 遇到失败如何排查
保留完整错误、路径和当前分支，按[权限、Git 与验证失败 FAQ](/guides/faq#permissions)的顺序隔离环境问题与代码问题。
### MCP 外部工具接入
URL: https://codexguide.io/advanced/mcp
理解 MCP 服务器、工具权限和数据边界，安全地把外部资料或服务接入 Codex 工作流。
#### 先定义数据边界
接入 MCP 前先确认服务器来源、会发送哪些数据、是否会写入外部系统，以及失败时能否撤销。只启用当前任务需要的工具。
- 优先使用只读工具验证连接。
- 为每个服务器记录用途、权限和负责人。
- 不要把生产凭据直接写进仓库配置。
#### 从一次小任务开始
先用[首次安装与项目检查](/quickstarts#task-quickstarts-title)确认本地工作区和 Git 状态，再接入一个可验证、可回滚的 MCP 操作。
### 自动化与定时任务
URL: https://codexguide.io/advanced/automation
把重复的 Codex 工作拆成有边界的自动化任务，设计触发条件、日志、失败处理和人工闸门。
#### 自动化任务的四个组成部分
一个可维护的自动化任务应明确输入、输出、执行权限和验收方式。任务越接近生产，越需要人工批准和可追溯日志。
- 触发：定时、提交或手动运行。
- 范围：固定目录、分支和资源。
- 验证：测试、构建或报告。
- 失败：停止、通知和恢复路径。
#### 先把流程跑通
建议先按[完成一个可回滚的真实任务](/quickstarts#task-quickstarts-title)手动跑通，再迁移到 CI 或定时任务，避免自动化放大未验证的流程。
### Windows 与 WSL 使用要点
URL: https://codexguide.io/advanced/windows
在 Windows 和 WSL 环境中配置 Codex 的路径、终端、Git 与权限，减少跨系统命令和文件编码问题。
#### 先统一工作目录
明确项目是在 Windows 文件系统还是 WSL 文件系统中运行，并尽量让 Git、Node、包管理器和 Codex 使用同一套环境。跨边界访问会带来路径、权限和性能差异。
- 使用 git status --short --branch 检查分支和工作区。
- PowerShell 与 Bash 命令不要混用未验证的路径语法。
- 确认换行符、文件编码和执行权限符合项目约定。
#### 快速验证环境
可以从[首次安装、登录并打开项目](/quickstarts#task-quickstarts-title)开始，先完成只读检查，再执行一个小修改并查看 diff。遇到 PATH、终端或跨系统路径问题时，进入[Windows 与 WSL FAQ](/guides/faq#environment)。
## 入门教程
### Codex 是什么：能力、工作方式与使用边界
URL: https://codexguide.io/guides/codex-shi-shen-me
如果你刚接触 Codex，还不确定它和普通 AI 对话有什么区别，可以从这里开始。
# Codex 是什么：能力、工作方式与使用边界
> 难度：基础
>
> 类型：概念与入门
## 这篇文章适合谁
如果你刚接触 Codex，还不确定它和普通 AI 对话有什么区别，可以从这里开始。
这篇文章不讲安装和复杂配置，只回答几个最先遇到的问题：Codex 是什么，它怎样完成任务，哪些事情适合交给它，以及为什么它修改了文件之后仍然需要人工检查。
## 先说结论
Codex 是面向软件开发任务的 AI 编程助手。它可以在你提供的项目和权限范围内读取文件、理解代码、修改内容、执行命令，并通过测试或其他检查验证结果。
把它理解成“可以在项目里动手的编程助手”，比把它理解成“更会写代码的聊天机器人”准确。
两者最大的差别不在于回答得多聪明，而在于 Codex 可以围绕一个真实项目采取行动。行动也意味着风险，所以工作目录、沙箱、审批和版本控制都很重要。
> 图片来源：[OpenAI Codex 官方文档](https://developers.openai.com/codex/)。
## Codex 是怎样完成任务的
一次比较完整的 Codex 任务通常会经过下面这些步骤。
```mermaid
flowchart LR
A["接收目标和限制"] --> B["读取项目与规则"]
B --> C["分析问题和制定步骤"]
C --> D["修改文件或调用工具"]
D --> E["运行测试与检查"]
E --> F["汇报结果、风险和剩余问题"]
```
这张图是工作方式示意，不代表每个任务都必须严格走完六步。一个只读问题可能在分析后直接回答；一个功能开发任务则可能多次往返于修改和测试之间。
Codex 会同时处理对话和项目材料，包括项目文件、命令行输出、测试结果以及你为仓库设置的规则。
### 1. 接收目标和限制
Codex 首先需要知道你想完成什么。只有一句“帮我优化一下”通常不够，因为“优化”可能指性能、结构、文案或界面。
更清楚的任务会说明目标、允许修改的范围，以及怎样才算完成。例如：只修改登录页面，不改后端接口；完成后运行现有测试，并说明还有哪些情况没有覆盖。
### 2. 读取项目和规则
Codex 可以读取你允许它访问的文件夹。它通常会先查看 README、依赖文件、目录结构、相关源码和测试，判断项目使用什么技术，以及应该从哪里动手。
仓库中的 `AGENTS.md` 也可以保存长期规则，比如常用命令、代码风格、禁止修改的目录和验证要求。
### 3. 修改文件或调用工具
确认方向后，Codex 可以编辑文件、执行终端命令、搜索代码，或者调用已经配置的工具。它能做多少，取决于当前使用入口和权限设置。
本地环境中的 Codex 通常在受控工作区里操作。访问工作区之外的目录、使用网络或执行风险较高的动作时，可能需要额外审批。
### 4. 验证结果
文件发生变化并不代表任务已经完成。可靠的结果还需要测试、构建、类型检查、页面检查或其他与项目匹配的验证方式。
如果项目没有测试，也要让 Codex说明它实际检查了什么。没有验证条件时，结论应当写成“已完成修改，但尚未经过完整验证”，而不是直接说问题已经解决。
## Codex 和普通 AI 对话有什么不同
| 对比项 | 普通 AI 对话 | Codex 任务 |
|---|---|---|
| 主要上下文 | 当前对话和你上传的内容 | 对话、项目文件、仓库规则和工具结果 |
| 常见输出 | 解释、建议、代码片段 | 文件修改、命令结果、测试结果和说明 |
| 是否能直接行动 | 通常以回答为主 | 可以在授权范围内操作项目 |
| 完成标准 | 回答是否有帮助 | 项目是否被正确修改并通过验证 |
| 需要关注的风险 | 信息是否准确 | 信息准确性、文件改动、权限和外部操作 |
这个区别也解释了为什么使用 Codex 时应该保持 Git 工作区清楚。你需要能够查看它改了哪些文件，必要时撤销修改，而不是只看最终回复写得是否顺畅。
## Codex 可以完成哪些任务
Codex 比较适合目标明确、结果可以检查的软件开发任务，例如：
- 阅读陌生项目并整理结构和运行方式。
- 实现一个范围清楚的小功能。
- 根据报错和日志查找 Bug 原因。
- 修改代码后运行测试、构建或类型检查。
- 补充测试、文档、脚本和配置。
- 阅读代码差异，检查明显的错误和风险。
- 协助完成 Git、Issue、Pull Request 等开发流程。
它也可以参与文档、研究和内容工作流，但那类任务更接近 ChatGPT Work 或文件处理场景。本知识库会把软件开发相关内容放在主线，把外部工具和非开发场景放到独立栏目。
## 哪些事情不能直接相信 Codex
Codex 能行动，并不等于它天然知道正确答案。
下面几类任务尤其需要谨慎：
- 需求本身含糊，却要求它自行决定产品逻辑。
- 没有测试和运行环境，却要求确认 Bug 已经修复。
- 直接操作生产环境、线上数据库或重要账号。
- 项目中存在密钥、客户数据或未脱敏文件。
- 大范围重构，但没有版本控制和回滚方案。
- 涉及安全、合规和业务责任的最终判断。
比较稳妥的做法是先限制范围，让 Codex说明计划，再查看差异并运行验证。权限不是开得越大越好，够当前任务使用即可。
## Codex 有哪些使用入口
OpenAI 当前提供桌面 App、CLI、IDE 扩展和云端等入口。它们面对的是不同工作习惯。
> 图片来源：[OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)。
- 桌面 App 适合在项目、文件和多个任务之间切换，也方便查看执行过程。
- CLI 适合习惯终端、希望紧贴本地仓库工作的开发者。
- IDE 扩展适合一边阅读和编辑代码，一边让 Codex 处理当前项目。
- 云端任务适合把工作交给托管环境执行，具体能力取决于账号和环境配置。
第一次使用不需要同时掌握所有入口。先选择一个和日常工作最接近的方式，完成一次小任务，再考虑是否切换。
## 第一次可以这样使用
第一次打开项目时，我更建议先让 Codex 做只读理解，不要立刻要求它重构整个仓库。
可以从一个真实而克制的任务开始：
```text
请先阅读这个项目的 README、依赖文件和主要目录，不要修改任何文件。
告诉我：
1. 这个项目解决什么问题；
2. 使用了哪些主要技术；
3. 本地应该怎样启动；
4. 如果我要修改首页，最可能涉及哪些文件；
5. 目前还有哪些信息无法确认。
```
这不是所谓的万能提示词。它只是把第一次进入陌生项目时真正需要弄清楚的事情说完整了。
拿到回答后，可以自己打开 README 和依赖文件核对。确认 Codex 对项目的理解基本正确，再交给它一个小修改，例如改一段文字、修复一个可以复现的样式问题，或者补充一条测试。
## 新手常见误解
### Codex 会自动知道整个项目
不会。它需要读取文件，也会受到上下文、权限和时间限制。大型项目更应该告诉它先看哪些模块。
### Codex 修改了文件，任务就完成了
不一定。至少要查看差异，并运行与任务相关的测试或检查。
### 给足权限，Codex 就会做得更好
权限只决定它能访问和执行什么，不保证判断更正确。过大的权限反而会扩大误操作影响。
### 新手应该先安装很多插件
没有必要。先学会描述任务、检查修改和验证结果。等你发现某个流程反复出现，再学习 Skills、MCP 和插件会更自然。
## 下一步学习
接下来可以进入 [安装与首次使用](../01-安装与首次使用/)，选择适合自己的入口，并完成第一个可验证的小任务。
如果已经安装好 Codex，可以继续阅读本目录后续文章，先弄清楚自己适合怎样使用，再进入项目实战。
## 参考资料
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
- [OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)
- [OpenAI Prompting](https://learn.chatgpt.com/docs/prompting)
- [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security)
- [Sandbox](https://learn.chatgpt.com/docs/sandboxing)
Codex 更新较快，界面、入口和权限设置可能随版本调整。
### Codex 适合哪些人：判断标准、典型场景与学习起点
URL: https://codexguide.io/guides/codex-shi-he-na-xie-ren
这篇文章写给正在判断“我有没有必要学 Codex”的读者。
# Codex 适合哪些人：判断标准、典型场景与学习起点
> 难度：基础
>
> 类型：概念与选择
## 这篇文章适合谁
这篇文章写给正在判断“我有没有必要学 Codex”的读者。
你可能是一名开发者，也可能只写过一点代码；还可能平时主要维护网站、GitHub 仓库、Markdown 文档或自动化脚本。职业名称不能直接决定你是否适合使用 Codex，日常任务的形态更有参考价值。
## 先说结论
Codex 最适合这类任务：有明确的项目或文件作为上下文，需要实际修改或执行操作，并且结果能够被检查。
判断自己是否适合使用 Codex，可以先看三个条件：
1. 任务是否依赖代码、文件、配置或仓库。
2. 是否希望 AI 采取行动，而不只是给出建议。
3. 是否有办法检查修改是否正确。
三个条件都满足，Codex 通常是合适的工具。只需要聊天、查一个概念，或者完成纯研究和文档交付时，Chat 或 ChatGPT Work 可能更直接。
> 图片来源：[OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)。
OpenAI 当前在 Quickstart 中给出的分工很清楚：研究、分析以及文档、演示文稿、电子表格等交付物可以选择 ChatGPT Work；需要代码库上下文和开发工具的软件开发任务选择 Codex；快速问题或普通对话使用 Chat。
这个分法比“程序员用 Codex，其他人不用”更实用。有人虽然不是职业开发者，但每天都在维护网站、脚本和 GitHub 仓库；也有开发者只是想问一个语法问题，没有必要为此启动完整的 Codex 任务。
## 先看任务，再看身份
下面这张表可以帮助你快速判断。
| 任务特征 | 更适合的入口 | 原因 |
|---|---|---|
| 需要阅读和修改代码仓库 | Codex | 需要项目上下文、文件操作和开发工具 |
| 需要修 Bug、写测试或检查代码差异 | Codex | 结果可以通过测试、构建或 Review 验证 |
| 需要整理资料并生成报告、表格或演示文稿 | ChatGPT Work | 重点是研究、分析和交付物 |
| 只是询问一个概念或讨论想法 | Chat | 不需要访问项目或执行工具 |
| 任务既有文档又有代码 | 根据主要产物选择 | 主要交付物是代码就优先 Codex，主要交付物是报告就优先 Work |
工具选错后，任务仍可能完成，只是沟通和检查成本会更高。把主要交付物想清楚，通常就能做出选择。
## 专业开发者
专业开发者是 Codex 最直接的用户群体，因为日常工作天然具备项目、工具和验证条件。
适合交给 Codex 的任务包括：
- 阅读陌生仓库并定位功能入口。
- 实现范围清楚的小功能。
- 根据报错、日志和测试定位问题。
- 修改代码后运行测试、Lint、类型检查和构建。
- 补充测试、文档和开发脚本。
- 阅读分支差异，检查明显的错误和风险。
开发者使用 Codex 的实际收益，常常来自连续完成搜索、修改、执行和初步验证。人负责需求判断、架构选择和最终审查。
这类读者可以从 [项目理解与上下文](../03-项目理解与上下文/) 开始，再进入 [代码修改与开发实战](../04-代码修改与开发实战/)、[Git协作与代码审查](../05-Git协作与代码审查/) 和 [测试调试与质量保障](../06-测试调试与质量保障/)。
## 正在学习编程的人
编程初学者也可以使用 Codex，但要避免把“任务完成”误当成“自己已经理解”。
比较适合的用法是：
- 让 Codex 解释项目入口和文件之间的关系。
- 对照一段真实代码说明语法和运行过程。
- 完成一个很小的修改，再查看具体差异。
- 为现有函数补一条测试，并解释测试验证了什么。
- 根据报错整理排查顺序，而不是直接索要最终答案。
初学者最容易遇到的问题是，代码看起来能运行，但自己说不清它为什么这样写。遇到这种情况，应该继续追问修改原因、替代方案和验证方法，而不是马上进入下一个功能。
第一次任务可以只让 Codex 阅读项目，不修改文件。确认它对项目的解释与 README、代码和运行结果一致后，再交给它一个可以在十几分钟内核对的小改动。
## 独立开发者和个人创作者
独立开发者往往同时负责产品、设计、代码、部署和文档。Codex 适合帮助处理那些边界清楚、但会打断工作节奏的任务。
例如：
- 给现有页面增加一个表单或响应式布局。
- 修复一个已经能够复现的问题。
- 为项目补充部署说明和环境变量示例。
- 把重复的手工步骤改成脚本。
- 检查上线前的代码差异和测试结果。
它不适合替你决定产品是否值得做，也不能代替真实用户反馈。需求优先级、产品取舍和发布责任仍然在人。
这类读者可以先完成 [代码修改与开发实战](../04-代码修改与开发实战/) 中的小任务，再学习 [自动化与高级工作流](../11-自动化与高级工作流/)。
## 技术负责人和团队管理者
技术负责人不一定需要让 Codex 亲自写完每一段代码。它在团队中的价值更多体现在规则、审查和重复流程上。
适合的场景包括：
- 根据仓库规则检查 Pull Request。
- 让 Codex 汇总修改范围、测试结果和剩余风险。
- 把常用命令和验证要求写入 `AGENTS.md`。
- 把重复的代码审查、发布检查或安全检查做成 Skill。
- 为新成员整理项目结构和本地运行方式。
团队使用时还要考虑权限、凭据、审计和数据边界。个人电脑上能运行的配置，不应该未经检查直接复制到团队环境。
这类读者可以重点阅读 [配置模型与权限安全](../10-配置模型与权限安全/) 和 [自动化与高级工作流](../11-自动化与高级工作流/)。
## 不以编程为主的读者
即使不长期写业务代码，只要工作围绕可操作的数字文件展开，也可以考虑使用 Codex。
下面这些场景可以考虑 Codex：
- 维护一个使用 Markdown 的 GitHub 知识库。
- 修改静态网站、博客主题或简单前端页面。
- 批量整理文件名、文本格式或目录结构。
- 编写和维护小型自动化脚本。
- 阅读开源项目，理解安装步骤和配置文件。
- 让 Codex 检查文档链接、文件结构和发布前状态。
这类任务通常仍然涉及文件、脚本或版本控制，所以 Codex 能发挥作用。如果主要工作是搜集资料、分析一批文档并生成报告，ChatGPT Work 往往更顺手。
非开发者使用 Codex 时，建议从只读任务开始，并保持 Git 版本记录。不要在看不懂修改内容的情况下，直接执行涉及账号、网络、数据库或系统权限的操作。
可以先阅读 [核心概念与任务方法](../02-核心概念与任务方法/) 和 [官方工具与集成](../12-官方工具与集成/)，再从 [真实案例复盘](../14-真实案例复盘/) 中选择和自己工作接近的案例。
## 哪些人暂时不适合直接使用 Codex
下面这些情况不代表永远不能用，但不适合一开始就让 Codex 大范围执行任务。
### 没有明确任务，只想看看 AI 能做什么
可以先用 Chat 讨论想法，或者阅读案例。没有目标时直接开放整个项目，通常只会得到泛泛的建议或不必要的修改。
### 完全无法检查结果
如果你既不能运行项目，也无法请其他人审查，就不适合让 Codex直接修改高风险代码。可以先用它解释项目和整理问题，不要直接发布结果。
### 任务涉及生产环境和重要数据
线上数据库、支付、客户数据、服务器权限和密钥都需要更严格的审批与备份。第一次使用 Codex 不应该从这些任务开始。
### 期待一句话完成一个大型项目
复杂项目需要需求拆分、阶段验证和持续决策。Codex 可以参与这些步骤，但不会因为输入一句“帮我做一个完整平台”就自动补齐所有产品和技术判断。
## 一个简单的自测方法
下面的问题不是 OpenAI 官方评分，只是帮助你判断起点。
1. 我的工作中是否经常出现代码、配置、Markdown 或 GitHub 仓库？
2. 我是否有一些重复的文件修改、检查或脚本任务？
3. 我能否说明任务完成后应该看到什么结果？
4. 我能否查看 Git diff、运行测试，或者用其他方式核对结果？
5. 我愿意先从小任务开始，而不是立刻开放全部权限吗？
6. 出现不确定结果时，我是否愿意暂停并人工判断？
如果大部分答案是“是”，可以开始学习 Codex。如果只有两三个“是”，先选择低风险、可撤销的小任务。如果几乎都是“否”，Chat 或 ChatGPT Work 可能更符合当前需求。
## 不同读者从哪里开始
| 读者 | 推荐起点 | 第一个任务 |
|---|---|---|
| 编程初学者 | [安装与首次使用](../01-安装与首次使用/) | 只读分析一个小项目的结构和运行方式 |
| 专业开发者 | [项目理解与上下文](../03-项目理解与上下文/) | 定位一个小功能或可复现 Bug 的相关文件 |
| 独立开发者 | [代码修改与开发实战](../04-代码修改与开发实战/) | 完成一个范围清楚的页面或脚本修改 |
| 技术负责人 | [Git协作与代码审查](../05-Git协作与代码审查/) | 审查一个小型 PR，并核对测试与风险 |
| 非开发者 | [核心概念与任务方法](../02-核心概念与任务方法/) | 检查一个 Markdown 仓库的结构和失效链接 |
选择起点时，不需要追求最复杂的任务。第一次使用的目标是建立一套可靠过程：说明任务、限制范围、查看修改、验证结果。
## 下一步学习
下一篇会讨论 Codex 能做什么和不能做什么，进一步划清能力边界。
准备开始操作的读者，可以直接进入 [安装与首次使用](../01-安装与首次使用/)；已经有项目的开发者，可以进入 [项目理解与上下文](../03-项目理解与上下文/)。
## 参考资料
- [OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
- [OpenAI Prompting](https://learn.chatgpt.com/docs/prompting)
- [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security)
文中的人群分类和学习建议由本知识库根据任务特征整理，不是 OpenAI 官方用户分级。
### Codex 能做什么和不能做什么：能力边界、使用条件与验证方法
URL: https://codexguide.io/guides/codex-neng-zuo-shen-me
这篇文章写给准备把真实任务交给 Codex 的读者。
# Codex 能做什么和不能做什么：能力边界、使用条件与验证方法
> 难度：基础
>
> 类型：能力边界
## 这篇文章适合谁
这篇文章写给准备把真实任务交给 Codex 的读者。
前两篇已经解释了 [Codex 是什么](./01-Codex是什么.md)，以及 [哪些人适合使用 Codex](./02-Codex适合哪些人.md)。接下来需要把能力边界讲清楚：它能执行哪些工作，完成这些工作需要什么条件，哪些判断仍然必须由人负责。
## 先说结论
Codex 可以理解项目、修改文件、运行命令、调用工具并检查结果。它能否完成某个具体任务，还取决于四件事：有没有足够的上下文、是否获得必要权限、当前环境能不能运行，以及有没有明确的验证方法。
“Codex 能修改代码”是一项能力。“这次代码修改正确”是一个需要证据的结论。
这两句话不能混在一起。
## 判断能力时要看四个条件
```mermaid
flowchart LR
A["任务目标"] --> B["项目与上下文"]
B --> C["工具与权限"]
C --> D["执行环境"]
D --> E["测试与人工验证"]
E --> F["可以接受的结果"]
```
少了其中任何一项，任务都可能停在中间。
例如，Codex 可以阅读测试失败信息并修改相关代码。但如果依赖没有安装、测试环境无法启动，或者报错只出现在生产环境，它就无法在当前环境中证明问题已经解决。
## Codex 能做什么
### 理解项目和查找信息
Codex 可以读取你允许访问的项目文件，分析目录结构、依赖、配置、源码、测试和文档。
常见任务包括：
- 说明项目解决什么问题，以及本地如何启动。
- 找到某个页面、接口或功能的主要入口。
- 追踪一个函数、配置项或数据结构在哪里被使用。
- 根据 README、依赖文件和代码整理技术栈。
- 比较当前实现与项目规则是否一致。
它的结论来自能够读取的内容。如果关键文档没有放进项目、代码由远程服务动态生成，或者真实逻辑在另一个仓库，回答就可能不完整。
### 修改代码和文件
在授权范围内，Codex 可以新增、编辑和删除文件。它适合处理范围明确的功能开发、Bug 修复、重构、文档和配置任务。
例如：
- 修改一个前端组件及其样式。
- 给现有接口增加参数校验。
- 修复能够稳定复现的错误。
- 补充单元测试和使用说明。
- 调整构建配置或自动化脚本。
- 批量修改格式一致的文件。
大范围修改需要更清楚的限制。没有说明哪些目录不能动、哪些接口必须保持兼容时，Codex 可能选择一个技术上可行、但不符合项目预期的方案。
### 运行命令和开发工具
Codex 可以在权限允许时执行终端命令，例如安装依赖、运行测试、构建项目、执行 Lint 和查看 Git 状态。
这类能力让它可以形成完整过程：先查找问题，再修改文件，随后运行检查。如果命令失败，它还可以根据输出继续排查。
命令能否执行取决于当前环境。缺少运行时、系统依赖、网络、账号或环境变量时，Codex 只能说明缺少什么，不能凭空补出真实环境。
### 调试问题和补充测试
当你能提供报错、日志、复现步骤或失败测试时，Codex 可以沿着代码路径查找原因，并提出修改。
它还可以：
- 把一个问题整理成稳定的复现步骤。
- 根据已有测试风格补充回归测试。
- 比较修改前后的错误信息。
- 检查边界条件和异常分支。
- 运行相关测试，确认原问题是否消失。
如果问题无法复现，正确做法是记录假设和未确认部分，而不是把最可能的猜测写成确定原因。
### 阅读差异和辅助代码审查
Codex 可以查看 Git diff、提交历史和 Pull Request 修改，寻找明显的逻辑错误、测试缺口、安全风险和维护问题。
代码审查适合用它做第一轮扫描，但不应该省略项目负责人或领域专家的判断。很多问题与业务规则、历史兼容和线上数据有关，这些信息未必存在于代码中。
### 使用浏览器、搜索和外部工具
根据使用入口和配置，Codex 可以使用浏览器、网络搜索、MCP、插件或其他集成读取外部信息并采取操作。
这些能力不是默认无限开放的。能否使用某个工具，取决于工具是否安装、是否完成认证、当前权限策略和组织要求。
## Codex 不能做什么
“不能”有两种情况。一种是技术条件不具备，另一种是风险和责任不应该交给它。
### 不能读取没有提供或没有授权的数据
Codex 不会自动知道私人仓库、线上数据库、内部文档和第三方账号中的内容。需要访问这些信息时，必须先通过项目文件、授权连接或明确的工具配置提供上下文。
即使工具已经连接，也只能在授予的权限范围内操作。
### 不能保证生成的代码一定正确
Codex 可能误解需求、遗漏边界条件、使用不合适的 API，或者写出能够通过部分测试但仍有问题的代码。
代码看起来合理、命令返回成功、页面能够打开，这些都只是证据的一部分。最终还需要结合测试范围、实际业务和人工审查判断。
### 不能替你补全没有说出口的需求
如果任务只写“把登录功能优化一下”，Codex 无法确定你关注的是页面体验、登录速度、安全策略还是代码结构。
它可以根据代码提出建议，但不能替产品和业务负责人决定真正目标。需求越模糊，生成无关修改的概率越高。
### 不能在缺少环境时完成真实验证
没有数据库、浏览器、依赖、测试账号或线上日志时，Codex 无法复现依赖这些条件的问题。
它可以检查静态代码并给出推断，但需要明确写出验证范围。例如：“已通过代码检查和单元测试，尚未连接真实支付环境。”
### 不能绕过权限边界
OpenAI 官方文档把权限分为不同模式。权限决定 Codex 可以在什么范围内编辑文件、运行命令和使用网络，以及什么时候需要审批。
> 图片来源：[OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)。
默认从需要审批的模式开始更合适。为了少点几次确认而直接开放全部权限，会扩大误删除、数据泄露和意外操作的影响范围。
权限扩大的是行动范围，不会让 Codex 的判断自动变得更准确。
### 不能承担最终责任
生产发布、数据库迁移、支付、安全、合规和客户数据处理都需要明确负责人。
Codex 可以帮助准备变更、执行检查和整理风险，但不能替团队承担业务后果。高风险操作应该有备份、审批、回滚方案和人工确认。
## 常见任务的能力边界
| 任务 | Codex 可以做什么 | 需要哪些条件 | 人需要检查什么 |
|---|---|---|---|
| 阅读陌生项目 | 分析结构、依赖和主要入口 | 能读取项目文件 | 结论是否遗漏外部服务和其他仓库 |
| 实现小功能 | 修改相关代码和测试 | 需求、范围和运行环境清楚 | 业务逻辑、兼容性和代码差异 |
| 修复 Bug | 根据复现和日志定位并修改 | 能复现问题或运行失败测试 | 原问题是否消失，是否引入回归 |
| 代码审查 | 查找错误、风险和测试缺口 | 有明确 diff 和项目规则 | 业务背景、历史约束和优先级 |
| 修改配置 | 编辑配置并运行检查 | 知道目标环境和配置优先级 | 密钥、权限和不同环境的差异 |
| 操作外部服务 | 通过 MCP、插件或集成调用工具 | 已安装、认证并获得授权 | 写操作范围、数据影响和撤销方式 |
| 发布到生产环境 | 准备命令、检查清单和变更说明 | 完整发布环境与团队流程 | 必须由负责人确认并保留回滚方案 |
这张表里没有“完全自动、无需检查”的任务。任务越接近生产环境和重要数据，人工检查越不能省。
## 怎样判断 Codex 是否真的完成了任务
不要只看最后一句“已完成”。可以按下面的顺序检查。
### 查看它实际改了什么
- 查看 `git status` 和 `git diff`。
- 确认没有修改无关文件。
- 检查是否删除了原有逻辑、注释或配置。
- 注意新依赖、环境变量和权限变化。
### 查看它实际运行了什么
- 测试是否真的执行，而不是只建议你执行。
- 构建、Lint 和类型检查是否成功。
- 页面或接口是否在正确环境中验证。
- 命令是否只覆盖了部分模块。
### 查看还有什么没有验证
- 是否缺少真实账号、数据库或生产数据。
- 是否只测试了正常流程，没有覆盖异常情况。
- 是否存在跨平台、浏览器或版本差异。
- 是否有需要产品、设计、安全或业务人员确认的决定。
可靠的 Codex 结果会把这些限制写出来。只汇报成功、不说明检查范围的结果，需要继续追问。
## 一个更稳妥的任务写法
下面是一段真实任务写法，用来说明怎样把能力和验证条件放在一起。
```text
请修复用户资料页在邮箱为空时出现的报错。
开始前先定位相关组件、接口和现有测试，不要修改其他页面。
请先复现问题，再进行最小范围修改。
完成后运行相关测试和类型检查，并告诉我：
1. 原因是什么；
2. 修改了哪些文件；
3. 运行了哪些检查；
4. 还有哪些情况没有验证。
```
这段任务没有要求 Codex“保证没有任何问题”，而是要求它提供可以检查的过程和证据。
## 什么时候应该先停下来
出现下面情况时，不要继续扩大权限或让 Codex 反复尝试。
- 它准备修改与任务无关的大量文件。
- 它无法解释修改原因，却建议直接发布。
- 测试持续失败，但它开始删除测试或降低检查标准。
- 它需要访问密钥、生产数据库或客户数据。
- 它把没有验证的推断写成确定结论。
- 你已经看不懂变化，也没有其他人可以审查。
此时应该缩小任务、恢复工作区，或者先补充环境和资料。
## 下一步学习
下一篇会比较 Chat、ChatGPT Work 和 Codex，帮助读者根据主要交付物选择入口。
准备实际操作的读者，可以进入 [安装与首次使用](../01-安装与首次使用/)；想先学会怎样描述任务，可以进入 [核心概念与任务方法](../02-核心概念与任务方法/)。
## 参考资料
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
- [OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)
- [OpenAI Prompting](https://learn.chatgpt.com/docs/prompting)
- [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security)
- [Sandbox](https://learn.chatgpt.com/docs/sandboxing)
- [Code review](https://learn.chatgpt.com/docs/code-review)
具体能力会因使用入口、账号、项目配置、权限策略和功能成熟度而变化。
### Chat、ChatGPT Work 和 Codex 怎么选：按任务与交付物判断
URL: https://codexguide.io/guides/chat-work-he-codex-zen-me-xuan
这篇文章写给已经打开 ChatGPT 或 Codex，却不确定应该选择 Chat、ChatGPT Work 还是 Codex 的读者。
# Chat、ChatGPT Work 和 Codex 怎么选：按任务与交付物判断
> 难度：基础
>
> 类型：使用入口选择
## 这篇文章适合谁
这篇文章写给已经打开 ChatGPT 或 Codex，却不确定应该选择 Chat、ChatGPT Work 还是 Codex 的读者。
三个入口都能接收自然语言任务，也都可以使用一定的上下文和工具。真正需要判断的是：这次任务要产出什么，以及结果应该怎样检查。
## 先说结论
选择模式时，先看主要交付物。
- 想获得回答、解释、讨论或短草稿，选择 Chat。
- 想完成一份可以审阅和继续使用的报告、演示文稿、表格、计划或持续任务，选择 ChatGPT Work。
- 想修改软件项目、运行开发工具、调试代码、补测试或审查 Pull Request，选择 Codex。
不要先问“我是什么职业”，先问“这次任务最终要交付什么”。
> 图片来源：[OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)。本图与上一篇文章共用，因为它直接展示了三种模式的官方分工。
## 三种模式的核心区别
OpenAI 当前在 Use ChatGPT 文档中给出的定位可以概括成下面这张表。
| 模式 | 主要目的 | 常见结果 | 典型任务 |
|---|---|---|---|
| Chat | 和 ChatGPT 一起思考问题 | 回答、解释、讨论、短草稿 | 问概念、搜索资料、头脑风暴、改写一段话 |
| ChatGPT Work | 定义一个结果，让 ChatGPT 完成较完整的工作 | 报告、演示文稿、电子表格、计划、可重复工作流 | 分析多份资料、制作汇报、整理决策、定期更新 |
| Codex | 完成软件和技术任务 | 代码差异、测试结果、构建结果、PR 审查 | 修 Bug、实现功能、运行测试、审查代码 |
这个表描述的是主要用途，不是绝对限制。Chat 可以读取文件，Work 也能使用工具，Codex 也能写文档。选择的关键是哪个入口更贴近主要工作过程和最终结果。
## 一个简单的选择流程
```mermaid
flowchart TD
A["这次任务主要要产出什么？"] --> B{"只需要回答、讨论或短草稿？"}
B -->|"是"| C["选择 Chat"]
B -->|"否"| D{"主要结果是报告、表格、演示文稿或计划？"}
D -->|"是"| E["选择 ChatGPT Work"]
D -->|"否"| F{"需要读取代码库、修改代码或运行开发工具？"}
F -->|"是"| G["选择 Codex"]
F -->|"仍不确定"| H["先用 Chat 澄清目标，再切换模式"]
```
这条流程只看主要交付物。一个任务同时包含资料研究和代码修改时，可以拆成两个阶段，不需要强行从头到尾只用一个模式。
## 什么时候选择 Chat
Chat 适合快速进入一个问题，并通过对话逐步想清楚。
常见场景包括：
- 解释一个不熟悉的概念。
- 搜索并比较几个公开选项。
- 讨论文章角度、产品想法或会议议题。
- 改写一段消息、简介或说明。
- 总结一小段文本或一份文件。
- 在开始大型任务前梳理目标和约束。
Chat 的优势是轻。你不需要先建立完整任务，也不必要求它生成一个正式交付物。
例如，你只是想弄清楚“单元测试和集成测试有什么区别”，直接使用 Chat 更快。为了这个问题打开整个代码仓库并启动 Codex，没有增加多少价值。
### Chat 不太适合什么
如果任务需要处理很多来源、持续运行较长时间，或者最终要交付一份结构完整的文件，普通对话会逐渐变得难以管理。此时更适合切换到 Work。
如果任务需要真正修改项目、执行命令和验证代码，应该切换到 Codex。
## 什么时候选择 ChatGPT Work
Work 适合结果明确、步骤较多，并且最终产物需要审阅、编辑或反复使用的任务。
OpenAI 官方文档给出的典型产物包括 brief、演示文稿、分析结果、电子表格、项目计划、持续更新和工作流。
适合使用 Work 的场景有：
- 阅读多份研究资料并形成决策报告。
- 把采访笔记和调查数据整理成演示文稿。
- 比较多个方案并生成电子表格。
- 根据文件和插件中的信息更新项目周报。
- 制作活动计划、预算和邀请页面。
- 建立需要定期执行或更新的工作任务。
Work 可以使用文件、插件和经过批准的工具获取信息、生成交付物并运行工作流。你可以查看进度、中途补充信息，并在重要操作前审批。
### Work 不太适合什么
只想问一句话时，Work 会显得过重。主要任务是修改代码、调试和测试时，Codex 的代码库上下文和开发工具更匹配。
Work 可以处理技术资料，也可以生成与技术有关的文档。但如果最终验收标准是“代码通过测试并形成可审查的修改”，应该把实现阶段交给 Codex。
## 什么时候选择 Codex
Codex 适合软件开发和技术任务，尤其是需要读取代码库、修改文件、运行命令并验证结果的工作。
常见场景包括：
- 阅读陌生项目，说明结构和启动方式。
- 实现一个范围清楚的功能。
- 根据报错和日志修复 Bug。
- 运行测试、类型检查、Lint 和构建。
- 补充测试、文档、脚本和配置。
- 阅读 Git diff 或 Pull Request，检查错误和风险。
- 处理依赖升级、重构和开发环境问题。
Codex 的最终结果通常不是一段回答，而是一组可以检查的项目变化。检查方法包括 Git diff、测试输出、构建结果、页面效果和代码审查。
### Codex 不太适合什么
如果你只需要讨论想法，没有代码、文件或技术操作，Chat 更直接。
如果主要结果是研究报告、演示文稿或电子表格，Work 的交付物工作流更合适。Codex 可以协助处理 Markdown、脚本和仓库文件，但不需要为了“显得专业”把所有任务都放进 Codex。
## 混合任务应该怎样拆分
真实工作经常跨越三个模式。可以按阶段拆开。
### 从市场研究到功能上线
1. 用 Chat 讨论要解决的问题和初步方向。
2. 用 Work 收集资料、比较方案并形成需求说明。
3. 用 Codex 在项目中实现功能、补测试并检查代码差异。
4. 回到 Work 整理发布说明、培训材料或对外汇报。
### 从知识库选题到 GitHub 发布
1. 用 Chat 讨论读者问题和文章角度。
2. 用 Work 整理官方资料、来源表和文章计划。
3. 用 Codex 创建 Markdown 文件、维护目录、检查链接并提交到 GitHub。
### 从线上报错到复盘报告
1. 用 Codex 读取日志和代码，复现并修复问题。
2. 用 Work 汇总影响范围、处理过程和改进计划。
3. 用 Chat 讨论一个具体技术概念或措辞。
拆分的好处是每个阶段都有清楚的结果。切换模式时，把上一阶段的结论、文件和未解决问题带到下一阶段。
## 常见任务应该选哪个
| 任务 | 推荐模式 | 原因 |
|---|---|---|
| “解释一下 MCP 是什么” | Chat | 主要需要概念解释 |
| “比较三款项目管理工具并给出建议” | Chat 或 Work | 简单讨论用 Chat，需要正式报告用 Work |
| “读取十份访谈记录并制作汇报” | Work | 多来源分析并生成可审阅交付物 |
| “每周整理 Slack 和 Drive 中的项目更新” | Work | 需要插件、持续执行和固定产物 |
| “帮我看懂这个 GitHub 项目的结构” | Codex | 需要代码库上下文 |
| “修复登录页面报错并补测试” | Codex | 需要修改代码和运行验证 |
| “审查当前 PR 是否有明显风险” | Codex | 需要 diff、项目规则和测试上下文 |
| “给产品名称想十个备选” | Chat | 适合快速讨论和迭代 |
| “把项目数据整理成电子表格” | Work | 最终产物是可复用表格 |
| “修改知识库目录并检查 Markdown 链接” | Codex | 需要操作仓库文件并运行检查 |
## 容易选错的几个地方
### 任务很长，所以一定要用 Work
时长不是唯一判断标准。一个持续数小时的大型代码重构仍然属于 Codex；一个十分钟完成的正式决策表也可能更适合 Work。
### 任务包含文件，所以一定要用 Codex
文件类型和最终结果更重要。分析 PDF 并生成报告通常适合 Work；修改项目中的源代码和测试适合 Codex。
### Codex 更强，所以所有任务都用 Codex
工具入口不是能力排名。Chat 更轻，Work 更适合交付物，Codex 更适合软件项目。选择贴近任务的入口，通常更省沟通成本。
### 选对模式后就不需要检查
三个模式的结果都需要检查。Chat 的事实和引用要核对，Work 生成的文件需要逐页查看，Codex 的代码需要看差异并运行测试。
## 不确定时怎么开始
不确定时可以先用 Chat，用几轮对话把目标说清楚。
可以先回答下面四个问题：
1. 最终要得到回答、文件，还是项目修改？
2. 任务主要依赖公开信息、业务资料，还是代码仓库？
3. 结果由什么方式验收？
4. 是否需要长期运行、外部工具或开发命令？
答案逐渐清楚后，再决定留在 Chat、进入 Work，还是打开 Codex。
## 下一步学习
下一篇会比较 Codex App、CLI、IDE 和 Cloud，解决“已经决定使用 Codex，但应该从哪个入口开始”的问题。
准备开始安装的读者，可以进入 [安装与首次使用](../01-安装与首次使用/)；希望进一步学习任务写法，可以进入 [核心概念与任务方法](../02-核心概念与任务方法/)。
## 参考资料
- [OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)
- [Use ChatGPT](https://learn.chatgpt.com/docs/use-chatgpt)
- [Get started with Work](https://learn.chatgpt.com/docs/get-started-with-work)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
- [OpenAI Prompting](https://learn.chatgpt.com/docs/prompting)
ChatGPT 和 Codex 的界面、模式名称与可用功能可能随版本、账号和工作区设置变化。
### Codex App、CLI、IDE 和 Cloud 怎么选：按工作环境与任务方式判断
URL: https://codexguide.io/guides/app-cli-ide-he-cloud-zen-me-xuan
这篇文章写给已经决定使用 Codex，却被 App、CLI、IDE extension 和 Cloud 几个入口弄糊涂的读者。
# Codex App、CLI、IDE 和 Cloud 怎么选：按工作环境与任务方式判断
> 难度：基础
>
> 类型：使用入口选择
## 这篇文章适合谁
这篇文章写给已经决定使用 Codex，却被 App、CLI、IDE extension 和 Cloud 几个入口弄糊涂的读者。
你可能会遇到这些问题：第一次应该安装哪个？本地任务和云端任务有什么区别？已经在 VS Code 里用了 Codex，还需要 App 或 CLI 吗？
## 你会学到什么
读完后，你应该能够：
- 判断一次任务适合在本机还是云端运行。
- 根据自己的主要工作界面选择 App、CLI 或 IDE。
- 知道什么时候需要切换入口，而不是一次安装所有工具。
- 理解四个入口可以组合，但不应该同时修改同一份代码。
## 先说结论
如果只记住一件事，请记住下面这组判断：
- **Codex App**：适合在桌面上管理项目、任务、工作树、代码差异和 Git 操作。
- **Codex CLI**：适合习惯终端、需要运行命令、编写脚本或接入 CI 的开发者。
- **Codex IDE extension**：适合边看代码边提问、做局部修改和原地审查差异。
- **Codex Cloud**：适合把任务交给隔离的云端环境，在后台或并行运行，稍后回来审查结果。
它们不是从弱到强的四个等级。前三个首先回答“你想在哪里和 Codex 交互”，Cloud 主要回答“任务要在哪里运行”。
## 先分清 App、CLI、IDE 和 Cloud
本文中的 App，指 ChatGPT 桌面应用里的 Codex 工作方式，不是手机 App。
App、CLI 和 IDE 都可以成为你在本机发起技术任务的入口，但界面和工作习惯不同。Cloud 则会为任务创建隔离的云端环境，检出仓库、执行配置脚本，让 Codex 在那里修改代码和运行检查。
> 图片来源：[OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)。本图与第 01 篇共用，用来说明 Codex 可以从不同工作界面进入。
## 四种入口对照表
| 入口 | 主要工作位置 | 最适合的任务 | 你会直接看到什么 | 需要注意什么 |
|---|---|---|---|---|
| App | ChatGPT 桌面应用、本地项目或工作树 | 多任务管理、本地项目修改、查看 diff、Git 操作 | 任务列表、项目文件、工作树、差异和终端 | 桌面任务仍会占用本机环境；不要把 App 自动等同于 Cloud |
| CLI | 本地终端 | 命令密集型开发、调试、代码审查、脚本和 CI | 命令、输出、权限请求、代码差异 | 需要熟悉目录、命令行和 Git 的基本操作 |
| IDE | VS Code、Cursor、Windsurf、Xcode 或 JetBrains 等编辑器 | 阅读当前文件、局部修改、边写边问、原地审查 | 打开的文件、选中代码、Codex 对话和 diff | 长任务会占用编辑器注意力，任务变大时可交给 Cloud |
| Cloud | Codex 的隔离云端环境 | 后台任务、并行任务、远程任务、团队协作 | 任务日志、结果摘要、diff 和 Pull Request 入口 | 需要连接 GitHub 并正确配置依赖、变量、权限和网络访问 |
表中说的是最典型的工作方式，不是硬性限制。例如，CLI 和 IDE 都可以把较长任务交给 Cloud；App 也有本地终端、工作树和 Git 控件。
## 一个简单的选择流程
```mermaid
flowchart TD
A["这次任务需要在哪里运行？"] --> B{"要离开本机，在后台或并行运行？"}
B -->|"是"| C["选择 Codex Cloud"]
B -->|"否，主要在本机"| D{"你平时最常停留在哪个界面？"}
D -->|"终端"| E["选择 Codex CLI"]
D -->|"代码编辑器"| F["选择 Codex IDE extension"]
D -->|"桌面任务和项目面板"| G["选择 Codex App"]
E --> H["任务变长时可交给 Cloud"]
F --> H
G --> I["需要并行本地修改时使用工作树"]
```
这条流程没有要求你永久选定一个入口。它只是在帮你决定：当前这次任务从哪里开始最顺手。
## 什么时候选择 Codex App
Codex App 适合希望把项目、任务、文件、终端和 Git 变化集中在一个桌面工作台中的读者。
比较合适的场景有：
- 同时跟进几个项目或几个持续时间较长的任务。
- 不想一直在多个终端窗口之间切换。
- 希望直接查看文件变化，并对 diff 留下修改意见。
- 需要使用工作树隔离并行修改。
- 想在界面中完成暂存、提交、推送和创建 Pull Request 等常见 Git 操作。
OpenAI 的本地环境文档说明，Codex App 可以为项目配置 setup scripts 和常用 actions。新工作树创建时可以自动安装依赖或执行构建，常用的启动、测试命令也可以放到顶部操作区。
### App 的限制
App 不是“所有任务自动放到云端”。你打开本地文件夹、在本地工作树中运行任务时，代码、依赖和开发工具仍来自自己的电脑。
如果你喜欢通过管道、脚本和大量命令组织工作，CLI 往往更直接。如果你一整天都在编辑器里逐行阅读代码，IDE extension 的上下文切换更少。
## 什么时候选择 Codex CLI
Codex CLI 适合终端优先的工作方式。它可以在当前仓库中读取文件、修改代码、运行本机已经安装的工具，并把交互式任务和现有命令行流程放在一起。
> 图片来源：[Codex CLI 官方文档](https://learn.chatgpt.com/docs/codex/cli)。页面将 CLI 定位为在终端中检查、编辑、运行代码并自动化重复工作。
CLI 比较适合：
- 在终端中阅读项目、执行测试、查看日志和处理 Git。
- 调试必须连续运行多条命令的问题。
- 使用 `codex exec` 建立非交互式流程。
- 把 Codex 放入脚本、自动化任务或 CI 管道。
- 在提交前审查未提交修改、某个提交或相对基础分支的变化。
- 从终端发起或查看 Cloud 任务。
### CLI 的限制
CLI 会把很多信息放进文本界面。刚接触命令行的读者可能不容易看出当前目录、分支、权限和命令影响范围。
这不代表新手不能使用 CLI，但开始前至少要会进入项目目录、查看 Git 状态、运行项目测试，并能读懂最常见的报错。涉及页面布局和逐行修改时，IDE 或 App 的可视化差异会更省力。
## 什么时候选择 Codex IDE extension
IDE extension 适合“代码就在眼前”的任务。
官方文档强调，它可以使用已经打开的文件、选中的代码和近期任务作为上下文。你可以在编辑器旁边提问，让 Codex 修改相关文件，再在原位置查看摘要和差异。
比较合适的场景有：
- 解释当前文件、函数或一段选中代码。
- 修复范围明确的小问题。
- 边写代码边补测试、类型或文档。
- 学习陌生项目时围绕当前符号连续提问。
- 不离开编辑器就审查和接受修改。
当前官方页面列出的入口包括 VS Code 及兼容编辑器、Xcode 和 JetBrains IDE。不同编辑器的安装方式与界面可能不同，应以对应平台的官方说明为准。
### IDE 的限制
IDE extension 最舒服的范围通常是当前正在阅读和修改的部分。需要跨很多模块调查、运行较长测试或并行比较多种方案时，把任务一直留在侧边栏里未必轻松。
官方 IDE 工作流支持把较大的任务交给 Codex Cloud。这样可以在编辑器里发起任务，继续处理手头代码，稍后回来审查云端结果。
## 什么时候选择 Codex Cloud
Codex Cloud 适合不需要持续盯着、可以交给独立环境完成的任务。
提交任务后，Codex 会在云端创建容器，检出指定仓库和分支，执行环境设置，然后在其中编辑代码、运行命令和尝试验证结果。完成后，你会看到摘要和文件差异，可以继续追问或创建 Pull Request。
比较合适的场景有：
- 一个任务需要运行较长时间，你还要继续做别的工作。
- 想同时尝试几种修复方案或并行处理多个独立任务。
- 当前不在开发电脑旁，但需要从网页或 CLI 发起、查看任务。
- 工作从 GitHub Pull Request、Issue、Linear 或 Slack 中开始。
- 团队希望通过统一环境减少“我的电脑可以运行”的差异。
### Cloud 的限制
Cloud 不是把本机环境原样搬过去。它只能使用云端环境中已经检出的仓库、安装的依赖、配置的变量和允许访问的网络。
因此，Cloud 的使用质量很依赖环境配置。项目如果缺少安装说明、锁文件、测试命令或 `AGENTS.md`，Codex 可能无法稳定复现你的本地开发流程。
还要注意权限边界。官方文档说明，Cloud setup script 阶段可以联网安装依赖；agent 阶段的互联网访问默认关闭，需要按任务配置有限或不受限访问。安装阶段需要的敏感值可以放入环境设置提供的 secrets，而不是写进仓库或任务提示中。Secrets 会在 agent 阶段开始前被移除，不能把它当成 Codex 全程可读取的环境变量。
## 本地和 Cloud 到底怎样区分
判断本地还是 Cloud，可以问自己四个问题：
1. 任务是否依赖本机尚未提交的文件、数据库或专用工具？
2. 我是否需要实时观察命令并频繁改变方向？
3. 任务运行时，我是否还要继续使用这台电脑和这个仓库？
4. 其他人是否需要在一致的环境里复现和审查结果？
依赖本机状态、需要高频互动时，先选择 App、CLI 或 IDE 的本地工作方式。任务边界清楚、环境能够复现、适合后台运行时，再选择 Cloud。
本地任务的优势是上下文贴近当前电脑，反馈快；Cloud 的优势是隔离、并行和可离开。两者解决的问题不同。
## 四种入口怎样组合使用
### IDE + Cloud
在 IDE 中选中代码、澄清问题并完成小修改。遇到跨模块调查或长时间测试时，把任务交给 Cloud，回来后在编辑器中审查结果。
### CLI + Cloud
在终端中复现问题、整理命令和验收标准，再通过 CLI 发起 Cloud 任务。完成后把结果应用到本地仓库，继续运行本机检查。
### App + 工作树
在 App 中为几个互不依赖的本地任务创建不同工作树。每个任务有独立目录和分支，完成后分别检查差异，避免多个任务直接争用同一份文件。
### App + IDE 或 CLI
可以用 App 管理任务和查看整体变化，再用 IDE 阅读代码，或用 CLI 执行特殊命令。不过，同一个工作目录不要同时交给多个 Codex 任务修改。切换入口前先看 `git status`，确认当前变化来自哪里。
## 容易选错的几个地方
### 第一次使用就把四个入口全部装好
入口越多，初学阶段越难判断任务和上下文在哪里。先选择最贴近日常工作习惯的一个本地入口，真正遇到后台或并行任务后再配置 Cloud。
### Cloud 一定比本地更强
Cloud 的主要价值是隔离和并行，不是自动提高任务质量。环境缺少依赖、权限或验收命令时，云端任务反而更容易卡住。
### CLI 只适合命令行高手
CLI 确实要求基本终端知识，但很多日常任务只需要进入正确目录、启动 `codex` 并审查命令。它是否合适，主要取决于你是否愿意在文本界面中工作。
### IDE 只能做简单补全
Codex IDE extension 不是传统的单行补全工具。它可以理解文件上下文、修改代码、审查差异，并把更大的任务交给 Cloud。只是对于命令密集型工作，CLI 的信息流通常更清楚。
### 同时打开多个入口会更快
并行任务只有在目录或环境隔离时才安全。几个入口同时修改同一个工作目录，很容易出现内容覆盖、测试结果失效和 Git 状态混乱。
## 不同读者从哪里开始
| 你的情况 | 建议的第一个入口 | 原因 |
|---|---|---|
| 第一次接触 Codex，喜欢图形界面 | App | 项目、任务、差异和 Git 状态更直观 |
| 每天主要使用 VS Code、Cursor、Xcode 或 JetBrains | IDE extension | 可以直接利用当前打开的代码上下文 |
| 熟悉终端、Git、测试和脚本 | CLI | 与已有开发流程结合最自然 |
| 需要同时处理多个仓库任务 | Cloud | 适合隔离、后台和并行运行 |
| 暂时没有稳定开发环境 | App 或 IDE 先学习，Cloud 后配置 | 先掌握任务和审查方法，再处理云端环境问题 |
| 维护 Markdown 知识库或文档仓库 | App、IDE 或 CLI | 按自己的编辑习惯选择；需要批量检查链接时 CLI 很方便 |
如果仍然拿不准，可以从 App 或 IDE 开始。完成一个小任务后，再尝试用 CLI 运行同样的检查，最后把一个边界清楚的任务交给 Cloud。亲自比较一次，比记住产品介绍更有用。
## 下一步学习
选定入口后，下一篇会整理第一次使用 Codex 前需要准备的账号、项目、Git、权限和验证条件。
准备安装的读者可以进入 [安装与首次使用](../01-安装与首次使用/)。已经有项目并想改善任务写法，可以进入 [核心概念与任务方法](../02-核心概念与任务方法/)。
## 参考资料
- [OpenAI Quickstart](https://learn.chatgpt.com/docs/quickstart)
- [ChatGPT desktop app](https://learn.chatgpt.com/docs/app)
- [Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
- [Codex IDE extension](https://learn.chatgpt.com/docs/codex/ide)
- [Codex cloud](https://learn.chatgpt.com/docs/cloud)
- [Local environments](https://learn.chatgpt.com/docs/environments/local-environment)
- [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environment)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
Codex 的入口、支持的编辑器、安装方式和账号可用功能可能随版本、地区与工作区设置变化。
### 第一次使用 Codex 前要准备什么：账号、入口、练习目录与验收清单
URL: https://codexguide.io/guides/di-yi-ci-shi-yong-qian-yao-zhun-bei-shen-me
这篇文章写给准备第一次打开 Codex，却不知道应该先准备账号、入口、练习目录还是开发环境的读者。
# 第一次使用 Codex 前要准备什么：账号、入口、练习目录与验收清单
> 难度：基础
>
> 类型：首次使用准备
## 这篇文章适合谁
这篇文章写给准备第一次打开 Codex，却不知道应该先准备账号、入口、练习目录还是开发环境的读者。
你不需要在开始前学会所有开发工具，也不需要先安装一堆插件。真正值得提前准备的是一个边界清楚的工作目录、一种可用的登录方式、一条能够回退的路径，以及判断任务是否完成的方法。
## 本文解决什么问题
本文只负责把读者送到首次任务的起点：确认能使用一种 Codex 入口，准备一个独立的本地练习目录，知道哪些内容需要审批，并能在修改后检查结果。它不要求先学完整 Git、安装插件或配置 Cloud。
## 适用环境与完成结果
适用于准备在本机使用 ChatGPT 桌面应用里的 Codex、Codex CLI 或 IDE 扩展的读者。当前 OpenAI Quickstart 把桌面应用、CLI 和 IDE 扩展作为不同入口；本仓库首期练习只要求选择其中一种。
完成本文后，你应该能：
- 选择一种入口并完成登录；
- 把独立练习目录打开给 Codex；
- 确认任务开始前的文件状态和权限边界；
- 进入[首期本地网页练习](../快速上手/)，完成修改并检查结果。
## 你会学到什么
读完后，你应该能够：
- 知道 ChatGPT 登录和 API Key 登录的适用边界。
- 为第一次任务准备一个无敏感信息、可重新解压的练习目录。
- 用 Git 或备份保留真实项目任务的起始状态。
- 选择适合新手的权限模式。
- 写出包含目标、上下文、限制和验收条件的第一条任务。
## 先说结论
第一次使用 Codex 前，首期练习至少准备下面四项：
1. 一个能够登录 Codex 的 ChatGPT 账号或 API Key。
2. 一个你有权读取和修改的独立练习文件夹。
3. 一份可以重新解压或复制的未修改起点。
4. 清楚哪些文件、命令和网络操作需要你审批。
Git、测试命令和项目说明对真实项目很有用，但不是首期静态网页练习的前置条件。练习文件在本地，Codex 是否能运行仍取决于客户端、登录状态和当前权限。
## 一张表看懂要准备到什么程度
| 层级 | 准备内容 | 为什么 |
|---|---|---|
| 必须 | 登录方式、工作目录、明确任务、结果检查方法 | 没有这些，Codex 不知道在哪里工作，也无法判断任务是否完成 |
| 强烈建议 | Git 或备份、干净的起始状态、项目运行方法、默认权限 | 方便比较修改、排查问题和撤销错误 |
| 可以以后再配 | `AGENTS.md`、MCP、Skills、插件、Cloud 环境、自定义配置 | 这些能改善长期工作流，但不应该挡住第一次使用 |
如果你发现自己还在研究十几个插件，却没有选好第一个练习项目，准备方向已经偏了。
## 第一步：确认登录方式和账号可用性
OpenAI 当前认证文档列出两种 Codex 登录方式：
- 使用 ChatGPT 账号登录，使用订阅或工作区提供的 Codex 权益。
- 使用 OpenAI API Key 登录，按照 API 使用量计费。
> 图片来源：[OpenAI Authentication](https://learn.chatgpt.com/docs/auth)。截至 2026-09-18，官方页面说明：ChatGPT 桌面应用、Codex CLI 和 IDE 扩展支持 ChatGPT 与 API Key 两种本地登录方式；Codex Cloud 要求使用 ChatGPT 登录。图片本身是历史素材，不能替代当前界面核对。
### ChatGPT 登录和 API Key 怎么选
| 情况 | 建议 |
|---|---|
| 已经在使用 ChatGPT，想体验 App、CLI、IDE 或 Cloud | 先使用 ChatGPT 登录 |
| 需要在可信的私有 CI 或脚本中运行 Codex CLI | 研究 API Key 或企业 Access Token |
| 只想完成第一次本地任务 | 不必为了开始而单独创建 API Key |
| 计划使用 Codex Cloud | 使用 ChatGPT 登录，并检查账号和工作区是否允许使用 Cloud |
API Key 不是免费的订阅替代品。使用 API Key 时会按照 OpenAI Platform 的 API 价格单独计费，而且部分依赖 ChatGPT 工作区或 Cloud 的功能不可用。
Codex 的套餐、额度和功能会变化。开始前查看一次 [Pricing](https://learn.chatgpt.com/docs/pricing) 和账号中的用量页面，比照着旧教程购买套餐更可靠。
### 使用 Cloud 前检查 MFA
Codex Cloud 会直接访问代码仓库，官方要求部分账号先启用多因素认证。
如果你使用邮箱和密码登录 ChatGPT，需要在访问 Cloud 前配置 MFA。使用 Google、Microsoft 或 Apple 登录时，官方不要求在 ChatGPT 账号中重复启用 MFA，但可以在对应身份提供方中设置。使用组织 SSO 时，应由组织管理员统一执行 MFA 策略。
### 不要泄露登录凭据
API Key、Access Token 和登录缓存都应该按密码处理。
官方认证文档说明，Codex 可能把本地登录信息存放在操作系统凭据存储中，也可能存放在 `~/.codex/auth.json`。不要把这个文件提交到 Git、粘贴到 Issue、发进聊天记录或放入教程截图。
## 第二步：先选一个入口，不要全部安装
上一篇已经比较了 [App、CLI、IDE 和 Cloud 的选择](./05-App-CLI-IDE和Cloud怎么选.md)。第一次使用时，只选一个最贴近日常习惯的入口即可。
- 喜欢图形界面和任务面板，可以从 App 开始。
- 长时间待在 VS Code、Cursor、Xcode 或 JetBrains，可以从 IDE extension 开始。
- 熟悉终端、Git 和命令行，可以从 CLI 开始。
- 已经有 GitHub 仓库和可复现环境，并且需要后台任务，再考虑 Cloud。
还要确认基础环境是否满足所选入口：操作系统受支持、你有软件安装权限、项目需要的 Git 和语言运行时可以正常使用。这里不要求提前安装项目用不到的工具。
## 第三步：准备一个适合第一次使用的项目
第一个项目不应该是公司生产系统，也不适合选一个你完全无法运行的大型仓库。
比较合适的练习项目有四个特点：
- **范围小**：十几分钟到一小时可以检查结果。
- **内容真实**：确实有一个需要完成的问题，不是为了测试而随便生成代码。
- **可以回退**：修改前有 Git 提交、分支或完整备份。
- **容易验证**：能通过测试、页面效果、命令输出或链接检查判断结果。
### 开发者可以选择
- 修复一个能够稳定复现的小 Bug。
- 为现有函数补一组测试。
- 修改一个范围明确的页面样式。
- 更新一个已经过时的配置或依赖说明。
- 阅读一个小仓库并补充启动文档。
### 非开发者可以选择
- 修复 Markdown 文档中的失效链接。
- 统一一批文件的标题或目录格式。
- 给静态网站补充一段已有内容。
- 整理一个不包含敏感信息的 CSV 或文本文件。
- 为知识库新增一篇结构明确的文章，并更新目录。
第一次任务最好来自你真正关心的工作。这样你知道什么结果算对，也更愿意认真审查修改。
## 第四步：用 Git 或备份保留起始状态
Codex 会修改真实文件。开始前留下可恢复的状态，不是多余流程。
如果项目已经使用 Git，可以先运行：
```bash
git status
git branch --show-current
git log -1 --oneline
```
你需要确认三件事：
1. 当前所在目录和分支是否正确。
2. 工作区中是否已经有尚未提交的修改。
3. 最近一次提交是否能够作为回退点。
如果 `git status` 显示已有修改，不要直接让 Codex 开始，也不要为了得到“干净状态”盲目删除或覆盖文件。先弄清楚这些修改是谁做的、是否需要提交，以及它们是否会和本次任务冲突。
如果项目没有使用 Git，可以选择下面一种做法：
- 新建一个练习仓库，并在确认文件内容后创建首次提交。
- 复制一份项目目录作为只读备份。
- 对重要文档使用具备版本历史的存储工具。
不要未经检查直接执行 `git add .`。项目中可能存在 `.env`、密钥、本地数据库、大文件或不应公开的数据。
## 第五步：确认项目在 Codex 修改前能够运行
很多人第一次使用时会忽略基线状态。Codex 修改后测试报错，不一定是它造成的，项目可能在开始前就无法运行。
根据项目类型，先做一次最小检查：
| 项目类型 | 开始前可以检查什么 |
|---|---|
| Web 项目 | 能否安装依赖、启动开发服务器并打开主要页面 |
| Python 项目 | Python 版本、虚拟环境、依赖安装和现有测试 |
| Node.js 项目 | Node.js 版本、包管理器、安装命令、测试或构建命令 |
| 移动端或桌面项目 | 对应 SDK、模拟器或构建工具是否可用 |
| Markdown 知识库 | 目录链接、图片路径、Markdown 检查命令或人工检查方法 |
| 数据与脚本项目 | 输入文件是否完整、输出目录是否安全、脚本能否在样例数据上运行 |
把实际可用的启动、测试、Lint、格式化或构建命令记下来。后面可以把它们写进任务说明，成熟后再放入 `AGENTS.md`。
如果基线检查本来就失败，记录原始错误。你可以让 Codex 先调查这个错误，但不要把它和另一个功能任务混在一起。
## 第六步：准备一条能验收的任务
OpenAI 的 Codex Best Practices 建议，一条任务至少说明四类信息：
| 内容 | 要回答的问题 |
|---|---|
| Goal | 你希望修改或完成什么？ |
| Context | 哪些文件、目录、文档、错误或示例与任务有关？ |
| Constraints | 哪些行为、架构、风格和安全边界不能破坏？ |
| Done when | 满足哪些条件才算完成？ |
### 一个开发任务示例
```text
目标：修复登录表单在邮箱为空时仍然提交的问题。
上下文：表单代码在 src/pages/login，相关测试在 tests/login。
限制：不要修改后端 API，不要重做整个表单组件，保持现有中文提示风格。
完成条件：空邮箱无法提交；页面显示现有格式的错误提示；相关测试通过；说明修改了哪些文件。
```
### 一个知识库任务示例
```text
目标：修复“00-从这里开始”目录中的失效相对链接。
上下文：只检查该目录下的 Markdown 文件及其引用的图片。
限制：不要改写文章正文，不要移动或重命名现有文件。
完成条件：列出发现的失效链接；修复确认有正确目标的链接；运行链接检查；汇总修改文件。
```
任务不需要写得像合同，但一定要让你自己知道怎样检查结果。只写“帮我优化一下项目”，Codex 很难判断应该改多少、哪些内容不能碰。
## 第七步：第一次从 Ask for approval 开始
Codex 的权限由沙箱范围和审批策略共同决定。第一次使用时，OpenAI 官方建议从 `Ask for approval` 开始。
> 图片来源：[OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)。本图与第 03 篇共用，因为它直接展示了第一次使用建议选择的权限模式。
在这个模式下，Codex 可以在当前工作区读取和编辑文件、运行常规本地命令；需要访问网络或越过工作区边界时，会先请求批准。
第一次任务不建议直接开启 Full access。Full access 可以修改电脑上的其他文件并运行联网命令，错误操作和数据泄露的影响范围更大。
看到审批请求时，不要只看按钮。至少确认：
- 它准备运行什么命令。
- 命令会读取、修改或删除哪些文件。
- 是否需要访问网络，目标网站是什么。
- 操作是否仍在本次任务范围内。
权限应该随着明确需求逐步放开，而不是为了减少弹窗一次性全部开放。
## 第八步：清理敏感信息和不相关数据
打开项目文件夹前，先检查里面是否包含不应该交给当前任务处理的数据。
常见敏感内容包括：
- `.env` 中的 Token、密码和数据库连接信息。
- 云服务密钥、SSH 私钥和签名证书。
- 客户资料、真实用户数据和内部财务文件。
- 个人聊天记录、浏览器导出数据和身份信息。
- 私有仓库地址、内部域名与尚未公开的业务资料。
项目确实需要环境变量时，可以保留不含真实值的 `.env.example`，并确认 `.gitignore` 已经排除真实配置文件。不要把密钥直接写进任务提示，让 Codex“先用一下”。
还要注意截图。首次使用、登录和报错截图很容易带出邮箱、本地用户名、私有目录、仓库名称和 Token。发布到知识库前需要逐张检查。
## 第九步：这些内容可以以后再准备
下面这些工具有价值，但第一次任务没有必要全部配置：
### AGENTS.md
适合记录仓库结构、运行命令、代码规范、禁止事项和验收要求。先完成一两个任务，知道 Codex 经常缺少什么信息后再写，内容会更真实。
### MCP
当任务需要访问仓库外部且经常变化的数据，例如 Notion、数据库或团队系统时再配置。第一次本地文件任务通常不需要 MCP。
### Skills 和插件
当一套流程已经重复出现，并且输入、步骤和输出相对稳定时，再把它整理成 Skill 或插件。不要先收集几十个工具，再寻找使用理由。
### Cloud 环境
Cloud 需要连接 GitHub，并配置依赖、环境变量、setup script 和网络权限。先在本地弄清楚项目如何运行，再配置 Cloud 会省很多排查时间。
### 自定义 config.toml
模型、推理强度、审批策略、沙箱和 MCP 都可以通过配置文件调整。第一次先使用默认配置，遇到具体问题后再修改对应项目。
## 十分钟开工前检查清单
开始第一个任务前，可以逐项确认：
- [ ] 我已经选好 App、CLI、IDE 或 Cloud 中的一个入口。
- [ ] 我知道当前使用 ChatGPT 登录还是 API Key 登录。
- [ ] 我没有把 Token、密码或 `auth.json` 放进仓库和提示中。
- [ ] 我打开的是正确项目和正确目录。
- [ ] 我知道当前 Git 分支和未提交修改情况。
- [ ] 我有一个可以恢复的 Git 提交或备份。
- [ ] 项目在修改前能够运行，或者我记录了已有错误。
- [ ] 第一次任务范围较小，并且有明确完成条件。
- [ ] 我知道要运行哪些测试、构建或人工检查。
- [ ] 权限从 Ask for approval 开始，没有直接开启 Full access。
十项里如果缺的是 MCP、插件或 Skill，可以继续开始；如果缺的是备份、工作目录和验收方法，先补齐再动手。
## 不同读者需要准备什么
### 非程序员
准备一个不含敏感信息的文档目录或知识库仓库，先学会查看文件变化。不会 Git 时至少保留完整副本，并从修链接、改目录、整理格式这类可人工检查的任务开始。
### 有开发经验的读者
准备一个能够本地运行的小项目，确认分支、依赖和测试命令。从一个可复现的问题开始，让 Codex 完成修改、测试和差异说明的完整循环。
### 准备使用 Cloud 的团队
除了 GitHub 仓库，还要准备 MFA、仓库授权、可复现的安装流程、环境变量、secrets、网络策略和团队审查规则。Cloud 环境配置应该单独测试，不要和第一个功能任务一起摸索。
## 常见准备误区
### 还没开始就先购买 API 额度
先检查 ChatGPT 账号和工作区是否已经提供 Codex 使用权限。只有确实需要 API Key 工作流时，再开通 API 计费。
### 第一次就接入所有 MCP 和插件
工具越多，权限、上下文和故障来源越多。先完成一个只依赖本地项目的任务，更容易理解 Codex 的基本工作方式。
### 直接在生产项目上试
第一次使用时，你还不熟悉权限提示、差异审查和回退流程。生产仓库、真实客户数据和自动部署环境都不适合作为练习场。
### 有 Git 就不用看 diff
Git 能帮你回退，不能替你判断修改是否合理。接受结果前仍然要看文件差异，并运行对应验证。
### 项目原本跑不起来也不记录
没有基线状态，就很难判断新的报错来自 Codex 修改还是原有环境。开始前的一次运行和一条错误记录会省下很多来回排查。
## 下一步学习
准备完成后，先进入[快速上手：完成第一个本地网页任务](../快速上手/)，再按需要阅读首次任务和结果检查的完整文章。真实项目案例另行保留，不作为首期练习的前置条件。
需要先安装工具的读者，可以进入 [安装与首次使用](../01-安装与首次使用/)。想进一步学习任务写法，可以进入 [核心概念与任务方法](../02-核心概念与任务方法/)。
## 参考资料
- [OpenAI Codex Quickstart](https://learn.chatgpt.com/docs/codex/quickstart)
- [OpenAI Authentication](https://learn.chatgpt.com/docs/auth)
- [OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)
- [Codex Best Practices](https://learn.chatgpt.com/docs/codex/learn/best-practices)
- [Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
Codex 的套餐、登录方式、权限界面和可用功能可能随版本、地区与工作区策略变化。
### Codex 新手第一个任务：修改本地网页并检查结果
URL: https://codexguide.io/guides/wan-cheng-di-yi-ge-zhen-shi-ren-wu
适合已经安装并登录 Codex App 或 CLI 其中一种、能够访问练习文件夹，但还没有独立完成过一次可核对修改的读者。不要求同时安装两种入口，也不声称所有系统和客户端都已实测。
# Codex 新手第一个任务：修改本地网页并检查结果
> 难度：基础
>
> 类型：首次实操
>
> 本文提供一套不需要 Node、数据库、插件或第三方 SDK 的共同练习。它不代表 Codex 模型可以完全离线运行。
## 这篇文章适合谁
适合已经安装并登录 Codex App 或 CLI 其中一种、能够访问练习文件夹，但还没有独立完成过一次可核对修改的读者。不要求同时安装两种入口，也不声称所有系统和客户端都已实测。
## 准备什么
- 一台已安装并登录 App 或 CLI 的电脑。
- 下方提供的本课练习包，无需克隆仓库或向维护者索取文件。
- 一个独立测试目录。不要使用 CodexGuide 正式网站、私人仓库或含敏感信息的目录。
- 可以打开本地 HTML 文件的浏览器。
练习只包含简单 HTML、CSS 和说明文件，不调用外部业务 API、不收集个人信息、不部署。
## 本课练习材料
使用一个简单的本地网页，练习修改标题与简介，并检查原有链接和样式是否保留。
[下载练习包（ZIP）](../练习材料/Codex首次任务-本地网页练习包.zip)
文件名：`Codex首次任务-本地网页练习包.zip`，大小：3,435 字节。包内包含未修改的 HTML/CSS、任务说明、检查清单和独立的参考差异，不需要安装 Node、数据库或插件。
解压后的目录如下：
```text
首次任务-本地网页/
├── README.md
├── 任务说明.md
├── 检查清单.md
├── 起始文件/
│ ├── index.html
│ └── styles.css
└── 参考差异/
└── 参考差异.md
```
手机上可以阅读教程和找到下载入口；实际练习需要在能够操作项目目录、已安装并登录 Codex App 或 CLI 的电脑上完成。手机浏览器不能直接执行本课的本地 Codex 任务。
只在练习副本中操作，不要打开真实业务项目、生产网站或含凭据的私人目录。参考差异用于完成后的比较，不是起始文件。
## 取得并打开正确目录
1. 点击上方“下载练习包（ZIP）”，把文件保存到电脑，再解压到一个新文件夹。
2. 将解压后的 `首次任务-本地网页/起始文件/` 整个复制为新的工作目录，例如 `codex-first-task-test/`。保留原始 `起始文件/` 不改动；`任务说明.md` 和 `检查清单.md` 位于它的上一级。
3. 先在浏览器中打开工作目录里的 `index.html`，应看到“晨间读书角”、一段简介和“查看阅读清单”按钮。
4. 在 App 中通过选择项目文件夹的入口打开 `codex-first-task-test/`；具体按钮名称以当前客户端为准。不要打开解压包的最外层或 `参考差异/`。
5. 使用 CLI 时，在终端进入同一个工作目录，确认直接包含 `index.html`、`styles.css` 后运行 `codex`。macOS/Linux 可用 `pwd`、`ls`，PowerShell 可用 `Get-Location`、`Get-ChildItem` 核对目录。
如果 App 或 CLI 还不能正常使用，先回到[安装与首次使用](../01-安装与首次使用/README.md)和[第一次使用前要准备什么](./06-第一次使用前要准备什么.md)。
## 给 Codex 的指令
把下面的指令发给 Codex：
```text
请先阅读 index.html 和 styles.css，不要修改文件。
然后只做这两处文字修改：
1. 将主标题改为“我的第一个 Codex 练习”；
2. 将简介改为“先看清修改，再确认页面结果。”。
请保留按钮文字、https://example.com 链接、其他 HTML 内容和全部 CSS 样式。
完成后告诉我修改了哪些行，并不要运行部署或安装命令。
```
先让它阅读再修改，是为了确认目录和范围。看到权限请求时，只允许服务于本次练习的读取和编辑动作；不要为这个练习开启外部写入、部署或安装操作。
## 预期修改与检查
预期只有 `index.html` 的两处文字变化：
```diff
- 晨间读书角
- 用十分钟记录今天读到的一段话，慢慢建立自己的阅读清单。
+ 我的第一个 Codex 练习
+ 先看清修改，再确认页面结果。
```
按[练习检查清单](../练习材料/首次任务-本地网页/检查清单.md)完成文件、链接、范围和浏览器检查。直接打开 `index.html`，确认标题、简介、按钮和样式都能看到；人工浏览器检查与 Codex 的文字总结是两件事。
## 出错怎么办
- 找不到文件：重新检查 App/CLI 打开的路径，用 `pwd`、`ls` 确认目录。
- 修改了 CSS 或按钮链接：停止继续编辑，从原始 starter 重新复制到新目录，再重试。
- 页面文字正确但样式异常：比较 `styles.css` 是否被改动，并从原始 starter 重来。
- 不确定是否完成：查看 diff，与上面的参考差异逐行比较。
- 登录、权限或客户端入口异常：查看[安装登录常见问题](../01-安装与首次使用/13-安装登录常见问题.md)和[故障排查目录](../15-故障排查与常见问题/README.md)。
重新练习时，重新解压或复制 `起始文件/` 到新的目录；不要清空真实工作区，也不要执行破坏性 Git 重置。
## 这次练习之后
完成一次小修改后，先阅读[完成第一次修改并检查结果](../01-安装与首次使用/09-完成第一次修改并检查结果.md)，再按需要进入[核心概念与任务方法](../02-核心概念与任务方法/README.md)或[项目理解与上下文](../03-项目理解与上下文/README.md)。原仓库中的历史案例仍保留在本文后半部分和[真实案例复盘](../14-真实案例复盘/README.md)，它们是独立案例，不能当作本次练习的亲测记录。
## 来源与验证边界
安装、登录和首次任务的官方参考：[OpenAI Codex Quickstart](https://learn.chatgpt.com/docs/quickstart)、[Codex CLI](https://learn.chatgpt.com/docs/codex/cli) 和[Authentication](https://learn.chatgpt.com/docs/auth)。本练习材料和本文是本仓库维护者编写的教学内容。2026-09-20 已在 macOS 15.6、Codex CLI 0.154.0 的现有认证环境中，用本课原始提示词通过 `codex exec` 完成一次练习副本修改。独立文件比对确认只有主标题与简介改变，CSS、按钮文字和链接未变；通过本机临时 HTTP 预览检查了真实生成的页面。此记录只覆盖 CLI 非交互执行、文件比对和页面检查，不覆盖 App、交互式 CLI 界面、直接双击 HTML 或其他系统；安装与登录过程没有在本次重新测试。
---
## 原文章中的历史案例（保留原文）
以下内容来自本仓库此前发布版本，记录维护者当时的真实知识库维护案例。它不是上面统一练习的实测记录，也不要求首期读者操作该仓库。
# 完成第一个真实任务：从任务描述到验证提交的完整闭环
> 难度：基础
>
> 类型：首次实操
## 这篇文章适合谁
这篇文章写给已经打开 Codex，也准备好一个安全项目，却还没有独立完成过真实任务的读者。
这里的“完成”，指一个真实项目产生了可检查的变化，并且这些变化经过验证、审查和提交。只得到一段看起来合理的回答，还没有走完任务。
## 你会学到什么
本文会完整走一遍下面的过程：
1. 选择一个适合第一次完成的真实任务。
2. 检查项目和 Git 起始状态。
3. 写清目标、上下文、限制和完成条件。
4. 观察 Codex 调查、编辑和运行命令。
5. 在权限请求和中途偏离时做判断。
6. 查看文件差异并独立验证结果。
7. 提交和推送确认通过的修改。
示例使用 Markdown 知识库，读者不需要编程基础。开发者可以把同一套流程换成修 Bug、补测试或修改页面。
## 本文使用的真实任务
本文没有临时创建一个“Hello World”项目。案例来自维护这个 Codex 中文知识库时真实发生的一次任务：
> 在 `00-从这里开始` 栏目中新增第 07 篇文章《完成第一个真实任务》，更新栏目目录和更新日志，加入必要的官方配图，并在发布前检查链接、图片、敏感信息和 Git 差异。
这个任务会修改四类内容：
| 文件 | 作用 |
|---|---|
| `00-从这里开始/07-完成第一个真实任务.md` | 新增正文 |
| `00-从这里开始/README.md` | 把第 07 篇加入阅读顺序 |
| `更新日志.md` | 记录本次内容发布 |
| `图片素材/00-从这里开始/07-完成第一个真实任务/` | 存放与正文直接相关的图片 |
它的范围不大，但包含真实项目里常见的多个步骤：读现有规范、研究资料、创建文件、维护导航、处理图片、运行检查和提交 Git。
## 先理解完整闭环
一次 Codex 任务可以拆成下面八个环节：
```mermaid
flowchart LR
A["确认起点"] --> B["描述任务"]
B --> C["调查项目"]
C --> D["计划修改"]
D --> E["编辑文件"]
E --> F["运行验证"]
F --> G{"结果通过？"}
G -->|"否"| H["分析问题并修正"]
H --> E
G -->|"是"| I["审查 diff"]
I --> J["提交与推送"]
```
很多第一次使用的问题，都源于流程只走到了“编辑文件”，后面的验证、diff 和提交没有完成。
## 第一步：确认任务开始前的状态
打开项目后，不要马上发出修改请求。先确认 Codex 进入了正确的文件夹。
如果项目使用 Git，可以检查：
```bash
git status --short --branch
git log -1 --oneline
```
第一条命令用来查看当前分支和未提交修改，第二条命令确认最近的回退点。
在本案例开始时，需要确认：
- 当前仓库是 `codex-handbook`。
- 当前分支是准备发布内容的分支。
- 前六篇文章已经提交。
- 工作区没有来源不明的未提交修改。
- 目标目录和图片规范文件能够正常读取。
如果工作区已经有修改，不要默认它们可以覆盖。先让 Codex 列出状态，说明哪些文件与本次任务相关，哪些是任务开始前就存在的内容。
### 可以怎样对 Codex 说
```text
先不要修改文件。请检查当前项目、Git 分支和未提交变化，阅读仓库根目录的 AGENTS.md 以及“00-从这里开始/README.md”，然后告诉我这次任务应该修改哪些文件。
```
这一步只需要确认双方正在同一个项目、同一个范围里工作，不需要让 Codex 写一份长报告。
## 第二步：把一句话需求补成可执行任务
用户最初可能只会说：
```text
《07-完成第一个真实任务》接下来写这一篇。
```
如果同一个任务里已经有前文、仓库规则和连续的文章上下文，Codex 可以据此继续工作。但读者第一次独立使用时，不应该假设它已经知道你的全部要求。
按照上一篇介绍的 Goal、Context、Constraints 和 Done when，可以把任务补充成下面这样：
```text
请在 codex-handbook 的“00-从这里开始”栏目新增第 07 篇文章。
目标：写一篇《完成第一个真实任务》，用一个真实的 Markdown 知识库维护案例，讲清从任务描述、执行、验证到 Git 提交的完整流程。
上下文：先阅读 AGENTS.md、图片素材/README.md、栏目 README，以及第 05、06 篇文章，保持现有知识库风格。
限制：
1. 不要写成公众号文章。
2. 不要编造实操截图、测试结果或用户反馈。
3. 官方结论必须引用 OpenAI 官方资料。
4. 实操截图由维护者亲自操作后补充；没有截图时使用官方图或流程图解释。
5. 不修改与本篇无关的目录和文章。
完成条件：
1. 新建文章并更新栏目目录和更新日志。
2. 图片路径、相对链接和官方链接可以访问。
3. 检查敏感信息、Markdown 基础格式和 Git diff。
4. 完成后先汇总修改和验证结果，不要在我审查前提交。
```
这段任务说明并不追求所谓“完美提示词”。它只是把容易产生分歧的地方提前说清楚。
## 第三步：让 Codex 先调查，再开始修改
一个项目通常已经有自己的结构和规则。Codex 在修改前应该先阅读与任务直接相关的文件，而不是凭空创建一套新格式。
本案例需要调查：
- `AGENTS.md` 中的内容和图片规则。
- `00-从这里开始/README.md` 的编号和标题风格。
- 第 05、06 篇的文章结构和引用方式。
- `图片素材/README.md` 中的命名、脱敏和来源要求。
- 当前 Git 状态和最近提交。
你不需要要求 Codex 阅读整个仓库。范围越准确，调查速度越快，也越不容易把无关内容带进任务。
### 怎样判断它是否读对了
开始写之前，Codex 至少应该说清楚：
- 准备新增什么文件。
- 需要更新哪些导航或索引。
- 本篇使用哪类图片，来源是什么。
- 哪些事实需要查官方资料。
- 打算如何验证文章和仓库变化。
如果它准备修改大量无关文件，应该在编辑前缩小范围。
## 第四步：观察过程，但不要逐行遥控
Codex 开始执行后，通常会经历搜索文件、读取规则、查资料、编辑和验证几个阶段。
你需要关注的是方向和边界：
- 它是否仍在处理同一个目标。
- 新发现是否改变了原来的计划。
- 是否要访问新的目录、网络或外部服务。
- 是否出现无法验证的事实或截图。
- 是否准备执行不可逆操作。
不需要对每一次文件读取都下指令。过度干预会打断连续调查，也会让任务记录充满重复确认。
### 什么时候应该马上纠偏
出现下面情况时，直接告诉 Codex 停下并重新确认：
- 开始重写已经完成的前六篇文章。
- 为了“内容丰富”准备添加无关 AI 图片。
- 把尚未实操的过程写成已经成功完成。
- 使用没有来源的套餐、功能或性能结论。
- 准备删除、移动或重命名现有文件。
- 发现工作区中存在用户原有修改，却打算直接覆盖。
纠偏时说明哪里偏了、正确边界是什么，不必从头重发整个任务。
例如：
```text
先停一下。前六篇文章不要改，本次只新增第 07 篇，并更新栏目 README 和更新日志。实操图片还没有由我亲自截图，不要创建或描述不存在的实操结果。
```
## 第五步：认真处理权限请求
Codex 可能请求编辑文件、运行命令、访问网络或执行 Git 操作。第一次任务继续使用 `Ask for approval` 更容易看清每个动作的边界。
> 图片来源：[OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)。本图与第 03、06 篇共用，用来说明首次实操中的审批边界。
看到权限请求时，可以按下面的顺序判断：
1. 这个动作是否服务于当前任务？
2. 它会影响哪个目录和哪些文件？
3. 命令是读取、创建、覆盖还是删除？
4. 网络访问的目标是否是已知官方来源？
5. 执行失败后是否容易恢复？
读取仓库文件、检查 Git 状态和访问 OpenAI 官方文档，通常容易判断。删除文件、安装系统软件、修改仓库权限、推送远端和使用 Full access，需要更谨慎。
批准命令不是在确认“Codex 一定做得对”，只是允许它执行这一个动作。结果仍然需要后续检查。
## 第六步：让 Codex 提供验证证据
编辑完成后，不要只接受“文章已经写好”这样的总结。要求它运行与完成条件对应的检查。
本案例需要验证：
| 检查项 | 证据 |
|---|---|
| 文章文件已创建 | 文件存在，标题和编号正确 |
| 栏目目录已更新 | README 中第 07 项链接指向新文章 |
| 更新日志已更新 | 当天记录包含本篇发布内容 |
| 图片有效 | 文件存在、格式与扩展名一致、正文路径正确 |
| 相对链接有效 | 链接目标文件或目录实际存在 |
| 官方链接有效 | 请求返回成功状态，并落在 OpenAI 官方域名 |
| Markdown 无明显格式问题 | `git diff --check` 没有空白错误，表格和代码块闭合 |
| 没有敏感信息 | Token、私钥和常见凭据模式扫描无结果 |
| 修改范围正确 | Git 状态中只有本篇相关文件 |
### 一组基础 Git 检查
```bash
git status --short
git diff --stat
git diff --check
```
- `git status --short` 显示哪些文件发生变化。
- `git diff --stat` 显示修改规模。
- `git diff --check` 检查多余空格和部分基础格式问题。
这些命令不能证明文章内容一定正确，但能快速发现文件遗漏、意外修改和格式问题。
### 验证失败时怎么办
验证失败不是任务结束，而是下一轮输入。
不要只说“再检查一下”，应该把失败证据交给 Codex：
```text
相对链接检查显示图片路径不存在：
图片素材/00-从这里开始/07-完成第一个真实任务/01-官方App内置Git工具.png
请先确认真实文件位置，只修复这个路径，然后重新运行链接和图片检查。不要改写正文其他内容。
```
错误信息、失败命令和预期结果比“好像不对”更容易让 Codex 准确修复。
## 第七步：自己审查 diff
Codex 运行完检查后，轮到你查看它到底改了什么。
OpenAI 的本地环境文档说明，ChatGPT 桌面 App 的 diff 面板可以查看当前修改、对具体行留下反馈、暂存或恢复单个区块，也可以提交、推送和创建 Pull Request。
> 图片来源：[OpenAI Local environments](https://learn.chatgpt.com/docs/environments/local-environment#use-built-in-git-tools)。页面展示了 App 中查看 Changes、分支、提交、推送和创建 Pull Request 的入口。
### 审查新文章
重点看：
- 标题是否和目录一致。
- 内容是否真的回答了文章主题。
- 官方事实是否有来源。
- 示例是否能让读者照着操作。
- 有没有把建议写成官方硬性要求。
- 有没有编造截图、测试和用户体验。
### 审查目录和更新日志
重点看：
- 编号是否连续。
- 链接路径和文件名是否完全一致。
- 是否误改其他文章标题。
- 更新日志是否只记录已经完成的内容。
### 审查图片
重点看：
- 图片能否解释正文中的具体信息。
- 官方图是否标明来源页面和链接。
- 文件格式和扩展名是否一致。
- 是否出现账号、邮箱、私有路径或 Token。
如果发现问题，可以直接在 diff 中指出具体行，也可以在任务中引用文件路径和段落标题让 Codex 修正。
## 第八步：提交前再做一次独立确认
Codex 的完成说明是线索，不是最终验收结论。
在本案例中，维护者至少要亲自完成下面几项：
- 打开新文章，快速通读一次。
- 点击栏目 README 中的新链接。
- 确认两张图片能够显示。
- 查看 Git diff 中是否有无关文件。
- 核对官方来源和引用说明。
- 确认没有私密计划、聊天记录或凭据进入公开仓库。
代码项目还要增加人工页面检查、关键功能复现或测试结果复核。不要因为命令显示绿色，就跳过用户真正会看到的效果。
## 第九步：提交和推送
只有在内容和验证都通过后，才进入提交阶段。
可以让 Codex 先给出提交范围和建议的提交信息：
```text
请再次确认 Git 状态，只暂存本次第 07 篇文章、栏目 README、更新日志和对应官方图片。提交前运行 git diff --cached --check，并把暂存文件列表给我确认。
```
确认无误后再提交，例如：
```text
docs: add first real task walkthrough
```
推送完成后，还要比较本地和远端分支的最新提交。看到 GitHub 页面中出现新文章，并不一定代表所有文件都上传正确；提交哈希一致才是更直接的证据。
### 推送后检查什么
- 本地工作区是否干净。
- 本地 `HEAD` 与远端目标分支哈希是否一致。
- GitHub 中的文章链接是否可以打开。
- 图片在 GitHub 页面中是否正常显示。
- 目录链接是否跳转到正确文章。
## 一份合格的任务结束报告
Codex 最后的报告应该短，但需要包含证据。
例如：
```text
已完成第 07 篇文章，并更新栏目 README 和更新日志。
新增：
- 00-从这里开始/07-完成第一个真实任务.md
- 图片素材/00-从这里开始/07-完成第一个真实任务/01-官方App内置Git工具.png
更新：
- 00-从这里开始/README.md
- 更新日志.md
已检查：相对链接、官方链接、图片格式、敏感信息和 Git diff。
提交推送后，本地与远端 main 提交一致。
```
“完成了”这三个字没有多少信息。文件、检查命令和远端状态才方便读者判断任务是否真的结束。
## 任务中途发现需求没说清怎么办
真实任务很少从第一句话开始就完全明确。发现缺口时，可以让 Codex 暂停编辑并列出需要决策的地方。
例如：
```text
先暂停修改。请列出目前仍然不确定的内容、每个选择会影响哪些文件，以及你的建议。等我确认后再继续。
```
如果只是局部问题，直接补充约束即可；如果目标本身发生变化，最好结束当前任务或建立新的分支，不要让一个任务不断扩张。
## 任务做坏了怎样处理
先停止继续修改，再根据 Git 状态判断影响范围。
- 只有少量错误时，在 diff 中逐行指出并让 Codex 修正。
- 某个文件整体方向错误时，确认没有用户原有修改后，再使用 App 的恢复功能或 Git 恢复该文件。
- 已经提交但还没有推送时，可以在保留历史的前提下继续提交修正。
- 已经推送并被他人使用时，不要擅自重写共享历史，优先创建修复提交或 Pull Request。
不要在不清楚后果时执行 `git reset --hard`、批量删除或覆盖目录。回退动作同样需要审查。
## 把这套流程迁移到代码任务
知识库案例和代码任务的文件不同，闭环并没有变化。
| 知识库任务 | 代码任务 |
|---|---|
| 新增文章 | 实现功能或修复 Bug |
| 阅读栏目规则 | 阅读项目架构和编码规范 |
| 检查链接和图片 | 运行测试、Lint、类型检查和构建 |
| 人工通读文章 | 手动复现功能或查看页面 |
| 审查 Markdown diff | 审查源代码和测试 diff |
| 更新目录和日志 | 更新文档、变更记录或迁移说明 |
| 推送文章提交 | 推送分支并创建 Pull Request |
第一次代码任务也应该范围小、结果可见、容易回退。修复一个能稳定复现的问题，通常比“帮我重构整个项目”更适合建立正确习惯。
## 第一次真实任务自查表
- [ ] 我确认了正确项目、目录和 Git 分支。
- [ ] 我知道任务开始前有哪些未提交修改。
- [ ] 任务包含目标、上下文、限制和完成条件。
- [ ] Codex 修改前读了相关项目规则。
- [ ] 权限请求都在本次任务范围内。
- [ ] 我在方向偏离时及时补充了约束。
- [ ] Codex 运行了与完成条件对应的验证。
- [ ] 我亲自查看了所有相关文件的 diff。
- [ ] 提交中没有无关文件、敏感信息或虚构结果。
- [ ] 推送后本地和远端提交一致。
十项都能回答清楚，这次任务才形成了真正可复用的经验。
## 下一步学习
完成第一次真实任务后，下一篇会总结 Codex 新手最常见的误区，包括任务范围过大、上下文堆得太多、盲目开放权限、只看回答不看 diff，以及把插件数量当成能力水平。
想练习不同入口的安装和首次运行，可以进入 [安装与首次使用](../01-安装与首次使用/)。需要系统学习任务拆分、计划和纠偏，可以进入 [核心概念与任务方法](../02-核心概念与任务方法/)。
## 参考资料
- [Codex Best Practices](https://learn.chatgpt.com/guides/best-practices)
- [OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)
- [OpenAI Local environments](https://learn.chatgpt.com/docs/environments/local-environment)
- [Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
- [Codex Code Review](https://learn.chatgpt.com/docs/code-review)
- [Git worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
Codex 的界面、权限名称、Git 工具和可用入口可能随版本与工作区设置变化。
### Codex 新手常见误区：哪些做法最容易让任务失控
URL: https://codexguide.io/guides/codex-xin-shou-chang-jian-wu-qu
这篇文章写给已经开始使用 Codex，却经常遇到下面情况的读者：
# Codex 新手常见误区：哪些做法最容易让任务失控
> 难度：基础
>
> 类型：使用误区与纠正方法
## 这篇文章适合谁
这篇文章写给已经开始使用 Codex，却经常遇到下面情况的读者：
- Codex 改了很多文件，但真正的问题没有解决。
- 提示写得越来越长，结果反而越来越不稳定。
- 任务显示完成，打开页面或运行项目后仍然有问题。
- 同一个仓库同时开几个任务，最后不知道修改来自哪里。
- 安装了很多 MCP、Skills 和插件，却没有形成稳定工作流。
这些问题不一定说明 Codex 没有能力完成任务。很多时候，真正需要调整的是任务范围、上下文、权限和验证方式。
## 先说结论
新手最容易犯的错误，可以归成五组：
1. 任务目标模糊，或者一次塞进太多工作。
2. 上下文给错位置，任务越聊越长。
3. 为了省事过早开放权限，忽略敏感数据。
4. 把 Codex 的完成说明当成验证结果，不看 Git diff。
5. 先追求插件、Cloud 和自动化数量，再寻找真实问题。
改进方法并不复杂：一个任务只对应一个清楚结果；长期规则放进 `AGENTS.md`；高风险动作保留审批；所有修改都经过验证和 diff；扩展工具只在真实流程需要时加入。
## 官方怎样提醒新手
OpenAI 的 Codex Best Practices 已经列出一组常见错误，包括：
- 把长期规则全部塞进提示词，而不是放入 `AGENTS.md` 或 Skill。
- 不告诉 Codex 怎样构建和测试，导致它无法检查自己的工作。
- 多步骤复杂任务跳过计划。
- 尚未理解工作流就开放完整电脑权限。
- 多个实时任务修改同一批文件，却不使用 Git worktree 隔离。
- 手动流程还不稳定就创建定时任务。
- 把 Codex 当成必须逐步盯着的工具。
- 用一个任务承载整个项目，造成上下文膨胀和结果变差。
> 图片来源：[Codex Best Practices](https://learn.chatgpt.com/guides/best-practices#common-mistakes)。本文以官方列表为基础，并结合前七篇中的任务、权限、Git 和验证方法进一步展开。
下面有些内容是 OpenAI 官方直接给出的建议，有些是本知识库根据这些原则做的编辑归纳。涉及产品行为和权限边界时，以文末官方资料为准。
## 误区是怎样让任务失控的
很多问题来自一连串叠在一起的小决定。
```mermaid
flowchart TD
A["目标模糊或范围过大"] --> B["Codex 需要自行猜测"]
B --> C["修改范围不断扩大"]
C --> D["上下文和工具输出变多"]
D --> E["用户难以审查 diff"]
E --> F["跳过验证或盲目接受"]
F --> G["问题进入提交或远端"]
G --> H["继续在混乱状态上追加任务"]
H --> D
```
打断这条链条最便宜的位置，通常是任务开始前：把目标和完成条件说清楚，限制修改范围，并准备能够验证结果的方法。
## 一、任务设计上的误区
### 误区 1：只说“帮我优化一下”
“优化”“完善”“处理一下”听起来像目标，实际上没有告诉 Codex 哪个结果更重要。
对于“优化登录页面”，Codex 可能理解为改布局、提高性能、重构组件、补测试或调整文案。每个方向都合理，但未必是你要的。
**更好的做法**：至少写出目标、相关范围、不能破坏的内容和完成条件。
```text
目标：减少登录页面首次加载时的 JavaScript 体积。
范围：只检查登录路由和它直接引入的模块。
限制：不改变页面样式和登录 API。
完成条件：说明主要体积来源；完成范围明确的修改；构建通过；给出修改前后的构建数据。
```
清楚不等于写得长。一句“把按钮改成蓝色”已经足够明确，不需要强行补成几百字的提示。
### 误区 2：第一次就让 Codex 重构整个项目
大任务看起来能充分发挥 Codex 的能力，但它会同时放大上下文、依赖、验证和审查成本。
“重构整个项目”通常没有统一的完成标准。任务进行几小时后，用户很难判断哪些变化必要，哪些只是顺手修改。
**更好的做法**：把大目标拆成能够独立验收的结果。例如先梳理依赖关系，再迁移一个模块，补齐对应测试，最后处理剩余模块。
每个子任务都应该能单独提交或放弃。拆分的重点不在句子数量，而在于每一步都有明确边界和证据。
### 误区 3：复杂任务也要求立刻写代码
涉及多个模块、数据库迁移、权限模型或外部系统的任务，如果目标还没说清就开始编辑，后面往往需要大面积返工。
OpenAI Best Practices 建议复杂、含糊或难以描述的任务先进入计划阶段。Codex 可以先调查仓库、提出问题和列出修改顺序，再等待确认。
**更好的做法**：先要求计划，不修改文件。
```text
先调查相关代码和现有测试，不要编辑。请给出问题原因、可能受影响的模块、两种处理方案、推荐方案和验证计划。列出仍需我决定的问题。
```
计划不是每个小任务的必经仪式。修一个明确错别字不需要单独写计划；跨模块变更值得先停下来想清楚。
### 误区 4：把实现细节全部替 Codex 决定好
有些提示会精确指定函数名、变量名、文件位置和每一步命令，却没有说明业务目标。这会把用户尚未验证的技术猜测变成硬约束。
如果你已经确定实现方案，当然可以直接要求执行；如果只是怀疑某个文件有问题，应该把它写成调查线索，不要写成结论。
**更好的做法**：明确不可改变的约束，把可讨论的实现留给调查和计划。
```text
报错似乎与 retry.ts 有关，这是调查线索，不代表必须只改这个文件。请先确认根因，再给出最小修改方案。
```
## 二、上下文和任务管理上的误区
### 误区 5：上下文越多越好
一次把整个仓库、几十份文档和长篇聊天记录都塞进任务，看起来很全面，但重要信息会被大量无关内容淹没。
上下文也有成本。文件、工具结果、MCP 数据和历史对话都会占用任务可以处理的信息空间。
**更好的做法**：先提供最相关的文件、错误、示例和规范。让 Codex 根据调查结果继续读取，而不是一开始就把所有内容推过去。
可以先说：
```text
问题出现在结算页面。先阅读 checkout 路由、最近一次报错和对应测试；需要其他文件时说明原因后再继续查找。
```
### 误区 6：每次提示都重复整套长期规则
代码风格、测试命令、目录结构和禁止事项如果每次都重复，提示会越来越长，也容易出现版本不一致。
OpenAI 建议把稳定、长期生效的项目规则放进 `AGENTS.md`。重复工作形成固定方法后，可以再整理成 Skill。
**更好的做法**：
- 当前任务特有的目标和限制写在提示中。
- 仓库结构、运行命令和团队规范写进 `AGENTS.md`。
- 重复出现的完整工作流整理成 Skill。
- 只在外部实时数据确实需要时使用 MCP。
不要把临时决定写进全局规则。一次活动的发布日期不应该永久进入所有项目上下文。
### 误区 7：一个任务从项目开始聊到项目结束
同一个任务持续几周，里面混着需求讨论、Bug 修复、文档更新和新功能，早期上下文会逐渐失去价值。
官方建议一个任务对应一个连贯的工作结果。如果工作仍是同一个问题，可以留在原任务；目标真正分叉时再新建或 fork。
**更好的做法**：用“能否独立验收和提交”判断是否拆任务。
- “调查支付失败并修复根因”可以是一个任务。
- “修支付 Bug、重做结算页面、更新营销文案”应该拆开。
- 同一个 Bug 的复现、修复和测试通常不必分成三个孤立任务。
### 误区 8：Codex 每一步都必须等我指挥
新手担心失控，容易让 Codex 每读一个文件、每运行一条测试都停下来确认。任务会被切得很碎，调查思路也难以连续。
另一种极端是完全不看过程，直到任务结束才发现方向早已偏离。
**更好的做法**：让 Codex 连续完成低风险调查和验证，同时要求它在范围变化、高风险操作、关键假设不确定时暂停。
你需要看方向、边界和证据，不需要遥控每一次普通文件读取。
## 三、权限和数据安全上的误区
### 误区 9：为了少弹窗，第一次就开启 Full access
Full access 可以让 Codex 修改工作区外的文件并运行联网命令。它减少审批，也扩大了错误、数据泄露和意外操作的影响范围。
OpenAI 的权限文档建议多数工作从 `Ask for approval` 开始。权限不足时，再针对清楚的需求逐步开放。
**更好的做法**：先保持工作区边界。只有当任务确实需要访问外部目录或网络，而且你理解将执行的动作时，才批准对应请求。
权限高低不会自动提高推理质量。Full access 只解决“能不能执行”，无法保证判断正确。
### 误区 10：权限请求只看“允许”按钮
批准权限前没有查看命令、目标目录和网络地址，等于放弃了重要的安全检查。
**更好的做法**：看到请求时快速确认四件事：
1. 动作是否服务于当前任务。
2. 会读取、创建、覆盖还是删除什么。
3. 是否越过当前工作区或访问网络。
4. 失败后能否恢复。
安装系统软件、删除目录、上传文件、修改 GitHub 权限和推送远端，都应该比普通读取命令更谨慎。
### 误区 11：把 Token 和真实数据直接放进提示
为了让任务尽快跑通，有人会把 API Key、数据库密码、客户数据或私有配置粘贴给 Codex。
这会让敏感内容进入任务记录、终端输出、截图或错误日志。后面即使删除文件，也不代表其他副本已经消失。
**更好的做法**：
- 使用环境变量、凭据存储或平台提供的 secrets。
- 仓库只保留不含真实值的 `.env.example`。
- 用脱敏样例替代真实客户数据。
- 发布截图前检查邮箱、本地用户名、私有路径和 Token。
- 把 `~/.codex/auth.json` 按密码文件处理。
敏感信息不应该成为提示写得更“完整”的代价。
## 四、验证和 Git 上的误区
### 误区 12：开始前不检查 Git 和项目基线
项目原本就有未提交修改或失败测试，Codex 工作后再出现问题，很难判断是谁造成的。
**更好的做法**：任务开始前至少确认：
```bash
git status --short --branch
git log -1 --oneline
```
能够运行项目时，再记录最小构建、测试或人工检查结果。基线失败也没关系，关键是把已有问题和本次任务分开。
### 误区 13：Codex 说“完成了”，任务就完成了
完成说明只是 Codex 对执行过程的总结。测试可能没有覆盖真实问题，命令也可能没有成功运行。
**更好的做法**：完成条件必须对应证据。
| 完成条件 | 可以接受的证据 |
|---|---|
| Bug 已修复 | 原问题无法复现，并有针对性测试 |
| 页面已完成 | 页面在目标尺寸下可用，交互和控制台正常 |
| 构建正常 | 实际构建命令退出成功 |
| 文档链接有效 | 相对链接和外部链接检查通过 |
| Cloud 任务可合并 | 环境成功运行检查，diff 经过审查 |
看不到证据时，直接要求 Codex 说明哪些检查已运行、哪些无法运行以及原因。
### 误区 14：测试通过，所以不用看 diff
测试只能覆盖它实际检查的行为。代码可能顺手改了无关文件、删除注释、改变配置或引入维护成本，而测试仍然通过。
**更好的做法**：在接受结果前查看：
```bash
git status --short
git diff --stat
git diff
```
重点检查修改范围、删除内容、依赖和配置变化，以及是否出现任务没有要求的重构。
测试回答“部分行为是否仍然正确”，diff 回答“项目到底发生了什么”。两者不能互相替代。
### 误区 15：多个任务同时修改同一个工作目录
并行看起来更快，但几个任务写同一批文件时，容易互相覆盖、误读 Git 状态和让验证结果失效。
OpenAI 官方建议并行本地任务使用 Git worktree 隔离。每个任务拥有独立目录和分支，完成后再分别审查和合并。
**更好的做法**：
- 独立任务使用不同 worktree 或 Cloud 环境。
- 有先后依赖的任务按顺序执行。
- 同一工作目录只保留一个主要写入者。
- 切换 App、CLI 和 IDE 前先检查 `git status`。
多个窗口不等于安全并行，隔离才是关键。
### 误区 16：提交时把所有变化一次打包
使用 `git add .` 暂存整个仓库，可能把任务前的修改、缓存、密钥、截图和无关文件一起提交。
**更好的做法**：先查看状态，只暂存本次任务相关文件，再检查暂存区：
```bash
git diff --cached --stat
git diff --cached --check
```
提交应该对应一个能够说清楚的结果。提交信息再漂亮，也无法弥补内容范围混乱。
## 五、扩展工具和 Cloud 上的误区
### 误区 17：插件、MCP 和 Skills 装得越多，Codex 越强
扩展确实能增加工具和上下文，但每个扩展也会带来认证、权限、配置、工具选择和上下文成本。
OpenAI Best Practices 建议只在工具能够解除真实工作中的手动环节时再添加，先从一两个明确需求开始。
**更好的做法**：
- 数据在仓库外、经常变化时考虑 MCP。
- 同一套方法重复出现时考虑 Skill。
- 需要把 Skills、MCP 和工具打包分发时考虑插件。
- 第一次本地文件任务先使用 Codex 自带能力。
“先安装，再找场景”很容易把学习时间花在配置而不是解决问题上。
### 误区 18：手动任务没跑通，就先做自动化和定时任务
一个流程每次都需要大量纠偏时，定时执行只会稳定地产生不稳定结果。
官方建议先让流程手动可靠，再把重复方法整理成 Skill，最后考虑定时任务。
**更好的做法**：自动化前确认输入来源、权限、失败处理、验收标准和输出位置都已经稳定。至少连续手动成功几次，并知道失败时怎样恢复。
### 误区 19：Cloud 一定比本地更强
Cloud 的优势是隔离、并行、后台运行和团队复现。它不会自动补齐缺失的依赖、测试命令和项目文档。
项目只在某台电脑上能运行，或者依赖尚未提交的文件时，本地 App、CLI 或 IDE 反而更容易获得正确上下文。
**更好的做法**：按任务环境选择入口。需要后台和并行时用 Cloud；依赖本机状态、需要高频互动时先在本地完成。具体判断可以参考 [App、CLI、IDE 和 Cloud 怎么选](./05-App-CLI-IDE和Cloud怎么选.md)。
### 误区 20：找到一条万能提示词，以后就不用调整
提示词模板能提醒你填写目标和限制，但项目、任务风险和验收方式每次都不同。
同一句“请先思考、逐步执行、确保正确”不会自动告诉 Codex 使用哪个测试命令，也不会发现仓库中的真实规则。
**更好的做法**：保留稳定的任务骨架，把具体目标、上下文和完成条件按当前工作填写。重复规则进入 `AGENTS.md`，重复流程进入 Skill。
比起收集一百条提示词，更值得积累的是：什么任务适合拆分、什么证据可以验收、哪些错误应该写进项目规则。
### 误区 21：生成代码越多、速度越快，结果越好
Codex 可以在短时间内修改很多文件，但代码量不是价值指标。一个正确的两行修复，可能比新增几百行抽象更好。
速度也要结合审查成本。五分钟生成、两小时排错的修改，并不比四十分钟完成且容易验证的方案高效。
**更好的做法**：关注结果是否解决问题、修改是否足够小、验证是否可信、后续是否容易维护。
## 快速判断自己卡在哪个误区
| 现象 | 可能的问题 | 先做什么 |
|---|---|---|
| Codex 改了大量无关文件 | 目标或范围不清 | 停止编辑，重新限定文件和完成条件 |
| 提示越来越长 | 长期规则和任务信息混在一起 | 把稳定规则移入 `AGENTS.md` |
| 对话越长结果越差 | 一个任务承载了多个结果 | 按可独立验收的结果拆任务 |
| 测试通过但页面有问题 | 验证方式不完整 | 增加人工页面和交互检查 |
| 不知道该不该批准命令 | 权限边界没有建立 | 回到 Ask for approval，查看命令和影响范围 |
| 多个任务互相覆盖 | 没有隔离工作目录 | 使用 worktree、独立分支或 Cloud 环境 |
| MCP 经常报错但任务根本用不到 | 扩展安装过多 | 禁用与当前任务无关的工具 |
| Cloud 任务无法运行 | 环境不可复现 | 先补安装、依赖和测试说明 |
| 每次都重复纠正同一问题 | 项目规则没有沉淀 | 更新 `AGENTS.md` 或形成 Skill |
| 提交后才发现混入私密文件 | 没有审查暂存区 | 提交前检查状态、暂存 diff 和敏感信息 |
## 一套更稳的默认工作方式
不想逐条记住二十一个误区，可以先坚持下面八步：
1. 一个任务只对应一个连贯结果。
2. 写清 Goal、Context、Constraints 和 Done when。
3. 复杂任务先调查和计划，小任务直接执行。
4. 默认使用 Ask for approval，逐项理解高风险请求。
5. 开始前记录 Git 和项目基线。
6. 修改后运行与完成条件对应的验证。
7. 接受结果前查看完整 diff 和暂存区。
8. 流程稳定后再增加 AGENTS.md、Skill、MCP、插件和自动化。
这套方法不会让每个任务一次成功，但能让失败更容易发现、定位和恢复。
## 自查清单
- [ ] 任务是否只有一个清楚的主要结果？
- [ ] 是否写明了完成条件，而不是只写“优化”或“完善”？
- [ ] 长期规则是否放在合适的 `AGENTS.md` 或 Skill 中？
- [ ] 当前任务是否已经因为对话过长而需要拆分？
- [ ] 权限是否与当前任务风险相匹配？
- [ ] 提示、仓库和截图中是否包含敏感信息？
- [ ] 是否记录了任务开始前的 Git 和测试状态？
- [ ] Codex 是否运行了能够证明结果的检查？
- [ ] 是否亲自查看了 diff、实际页面或运行结果？
- [ ] MCP、插件、Cloud 和自动化是否解决了真实需求？
## 下一步学习
完成这一篇后，`00-从这里开始` 的八篇内容已经覆盖 Codex 的定位、适用人群、能力边界、模式与入口选择、首次准备、真实任务和常见误区。
接下来可以进入 [安装与首次使用](../01-安装与首次使用/)，根据自己的系统安装 App、CLI 或 IDE extension。已经完成安装的读者，可以进入 [核心概念与任务方法](../02-核心概念与任务方法/)，系统学习上下文、计划、任务拆分、权限和验证。
## 参考资料
- [Codex Best Practices](https://learn.chatgpt.com/guides/best-practices)
- [OpenAI Prompting](https://learn.chatgpt.com/docs/prompting)
- [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [OpenAI Permissions](https://learn.chatgpt.com/docs/permission-modes)
- [Codex Code Review](https://learn.chatgpt.com/docs/code-review)
- [Git worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees)
- [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)
- [Build skills](https://learn.chatgpt.com/docs/build-skills)
- [Build plugins](https://learn.chatgpt.com/docs/build-plugins)
- [Scheduled tasks](https://learn.chatgpt.com/docs/automations)
- [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environment)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
Codex 的权限、配置、工具和任务管理方式可能随版本与工作区设置变化。
### 登录 Codex：选择 ChatGPT 或 API Key 并确认本地入口
URL: https://codexguide.io/guides/deng-lu-codex
安装好 ChatGPT 桌面应用里的 Codex、Codex CLI 或 IDE 扩展后，下一步就是登录。
# 登录 Codex
> 官方资料核对：2026-09-18；本仓库本轮未完成 App、CLI 或 IDE 的客户端实测。
安装好 ChatGPT 桌面应用里的 Codex、Codex CLI 或 IDE 扩展后，下一步就是登录。官方认证文档确认三种本地入口都支持 ChatGPT 登录和 API Key 登录；Codex Cloud 要求使用 ChatGPT 登录。下面按 App、CLI 和 IDE 分别说明，按钮和版本差异以当前客户端为准。
## 先选登录方式
第一次使用时，直接选择 ChatGPT 登录就够了。客户端会打开浏览器完成授权，再返回 App、CLI 或 IDE。只有按 API 调用量计费，或需要在脚本、自动化环境中运行时，才需要考虑 API Key。Codex Cloud 只能使用 ChatGPT 登录，API Key 不能替代它。
开始前只需准备一个可用账号。操作过程中不要把邮箱、验证码、API Key 或 `auth.json` 放进截图、仓库和任务提示。
## ChatGPT 登录和 API Key 怎么选
OpenAI 的 Authentication 文档列出了两种本地登录方式。ChatGPT 登录使用订阅或工作区权益，API Key 按 API 用量计费。ChatGPT 桌面应用、Codex CLI 和 IDE 扩展都支持这两种方式。
图 1：官方 Authentication 页面。
| 你的情况 | 建议 |
| --- | --- |
| 第一次使用 Codex，已经有 ChatGPT 账号 | 先用 ChatGPT 登录 |
| 想使用 Codex Cloud | 用 ChatGPT 登录，并确认账号或工作区已开通 Cloud |
| 在脚本、CI 或可信的自动化环境中按量调用 | 使用 API Key 或组织提供的 Access Token |
| 只是想完成一次本地任务 | 不要为了开始而单独创建 API Key |
API Key 和 ChatGPT 订阅使用不同的计费与权限体系。API Key 在 OpenAI Platform 中管理；一旦泄露，应立即撤销并重新生成。
## App：从登录按钮到返回应用
### 1. 打开登录入口
启动 ChatGPT 桌面应用。未登录时会看到登录页，英文界面有 **Continue to sign in** 和 **Sign in another way** 两个按钮。
### 2. 用 ChatGPT 账号登录
点击 **Continue to sign in**，中文界面对应“继续登录”。应用会打开浏览器，接下来在 ChatGPT 网页完成身份验证。
图 2：中文登录界面，“使用其他方式登录”可切换登录方式。
网页会提供 Google、Apple、手机号或邮箱等入口，具体选项因账号和地区而异。输入账号信息前，先确认地址栏是官方 `chatgpt.com` 域名。
图 3：ChatGPT 官方网页登录页。
完成登录和授权后，回到刚才的应用窗口。浏览器没有自动切回时，手动打开 App，等页面刷新即可。授权完成前不要关闭浏览器或应用。
### 3. 确认 App 已经登录
出现下面几种情况，就说明 App 已经登录：
- 应用不再停留在登录页；
- 账号菜单可以正常打开；
- Codex 入口已经可用。
账号菜单的位置可能随版本调整。应用不再要求登录、Codex 入口也能打开，就可以继续下一步。
## CLI：浏览器登录、设备码和 API Key
### 1. 用 ChatGPT 登录
在 PowerShell、Terminal 或 WSL 中进入练习项目目录，启动 Codex：
```powershell
codex
```
第一次启动时选择当前界面提供的 ChatGPT 登录方式，再在浏览器中完成授权。官方 CLI Quickstart 的共同步骤是“进入项目目录并运行 `codex`”；本轮不把版本相关的子命令作为首期必做步骤。
图 4：Codex CLI 启动后的界面。输入提示词前，先确认顶部显示的模型和目录符合预期。
无图形界面的设备码或其他登录方式是否可用，取决于当前 CLI 版本和账号策略。本轮不把它写成通用必做步骤；需要时先运行 `codex --help`，以当前版本输出为准。
### 2. 需要 API Key 时再按当前入口操作
官方认证文档确认 API Key 可用于本地 App、CLI 和 IDE，但具体输入入口和命令参数可能随客户端版本变化。首期练习不要求 API Key；如果确实需要按量计费的 API 工作流，请打开当前客户端的登录帮助和[官方认证文档](https://learn.chatgpt.com/docs/auth)，不要直接复制旧教程中的参数。API Key 不要写进命令行历史、提示词、仓库或截图。
### 3. 用只读请求确认当前环境
登录后，在同一个练习目录运行 `codex`，发送：“请读取当前目录的 README 或任务说明，不要修改文件。”能正常进入会话并读取允许访问的文件，才说明当前登录、项目路径和基础权限至少能支持首期练习。不要把登录截图或认证文件当作唯一成功证据。
## IDE：登录入口和返回编辑器
VS Code、Cursor 等兼容编辑器会在 Codex 侧栏中显示登录按钮。打开侧栏，选择 **通过 ChatGPT 登录**，然后回到原来的编辑器窗口完成授权。
图 6：VS Code 中的 Codex 登录入口，也可以在这里选择 API Key。
图 7：选择 API Key 后，在输入框中粘贴 Key。使用这种方式时，Cloud 任务不可用。
浏览器没有自动返回时，手动切回编辑器并重新打开 Codex 侧栏。登录成功后，登录按钮会变成对话输入框，就能在当前项目中发起任务。
图 8：登录成功后的对话界面，底部显示当前处于本地模式。
## 切换账号和退出登录
App 和 IDE 都能从账号菜单退出，再用目标账号重新登录。菜单名称和位置可能随版本变化，但不要通过删除配置目录来“强制切换”，否则其他本地设置也可能一起丢失。
CLI 的退出与重新登录入口可能随版本变化。需要切换账号时，优先使用当前客户端提供的退出入口；不要删除整个配置目录来“强制切换”。
Windows 和 WSL 是两套独立环境，需要分别检查；一边退出不会自动让另一边退出。
## 凭据存储和安全边界
本地登录信息可能保存在操作系统的凭据存储中，也可能写入 `~/.codex/auth.json`。这些信息等同于密码，需要妥善保管：
- 不提交到 Git，不上传到 Issue、网盘或聊天记录；
- 截图前遮住邮箱、头像、工作区、令牌和本地用户名；
- 怀疑泄露 API Key 时，立即到 OpenAI Platform 撤销并重新生成；
- 共享电脑完成任务后退出登录，并检查浏览器是否仍保留账号会话。
登录成功不等于 Codex 能访问所有文件。项目目录、网络和命令权限仍由 App、CLI 或 IDE 的权限设置决定。第一次使用时，建议保留 **Ask for approval**，执行敏感操作前先确认。
## 登录失败时怎么排查
先看登录卡在哪一步：
| 现象 | 先检查什么 |
| --- | --- |
| 点击登录没有浏览器 | 默认浏览器、弹窗拦截、网络和代理 |
| 浏览器登录成功，客户端仍未登录 | 回到原来的 App/IDE 窗口，重新打开登录面板；必要时重启客户端 |
| CLI 无法进入会话 | 在同一套环境中运行 `codex`，观察当前版本提供的登录提示；Windows 和 WSL 的认证状态彼此独立 |
| API Key 登录失败 | 环境变量是否存在、Key 是否有效、组织和计费是否允许调用 |
| Cloud 无法使用 | 确认使用的是 ChatGPT 登录，而不是 API Key；再检查账号、工作区和 MFA 要求 |
仍然无法登录时，记录客户端名称、版本、操作系统、登录方式、完整错误文字和发生时间。需要发送截图时，记得遮住账号和凭据。
## 完成检查
- [ ] 我知道当前入口使用的是 ChatGPT 还是 API Key。
- [ ] 浏览器授权后，我回到了原来的 App、CLI 或 IDE。
- [ ] App 或 IDE 不再显示登录按钮，CLI 能在当前练习目录进入会话并接受只读请求。
- [ ] 我没有在截图、仓库或终端记录中暴露凭据。
- [ ] 如果要使用 Cloud，我确认账号使用 ChatGPT 登录并满足工作区要求。
## 下一步
- [打开第一个本地项目](./08-打开第一个本地项目.md)
- [完成第一次修改并检查结果](./09-完成第一次修改并检查结果.md)
- [安装登录常见问题](./13-安装登录常见问题.md)
## 参考资料
- [OpenAI Authentication](https://learn.chatgpt.com/docs/auth)
- [OpenAI Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
- [第一次使用 Codex 前要准备什么](../00-从这里开始/06-第一次使用前要准备什么.md)
- [Windows 安装 Codex App](./03-Windows安装Codex-App.md)
- [Windows 和 WSL 安装 Codex CLI](./05-Windows和WSL安装Codex-CLI.md)
- [VS Code 和兼容编辑器安装 Codex](./06-VS-Code和兼容编辑器安装Codex.md)
> 登录按钮、账号菜单、Cloud 权限和 CLI 选项可能随客户端版本、地区及工作区策略变化。实际操作以当前界面和官方文档为准。
### 打开第一个本地项目：确认目录、权限与起始状态
URL: https://codexguide.io/guides/da-kai-di-yi-ge-ben-di-xiang-mu
登录后，先别让 Codex 改代码。第一次使用，可以准备一个随时能恢复的练习项目，或者先复制一份项目再操作。本文以 VS Code 为主，也会介绍 Codex 桌面端和 CLI 的入口。
# 打开第一个本地项目，让 Codex 看懂目录
登录后，先别让 Codex 改代码。第一次使用，可以准备一个随时能恢复的练习项目，或者先复制一份项目再操作。本文以 VS Code 为主，也会介绍 Codex 桌面端和 CLI 的入口。
首期不要求准备 Node.js 项目：可以直接使用[本地网页练习包](../练习材料/Codex首次任务-本地网页练习包.zip)，把 `起始文件/` 复制到新目录，再打开这个复制出的目录。本文后面的通用项目说明仍适用于真实仓库，但不能替代首期练习的具体目录。
## 先选对目录
打开项目根目录，不要选桌面、仓库的上一级目录，也不要只选包含某个源文件的子目录。根目录通常能看到 `README.md`、`package.json`、`pyproject.toml`、`.git` 或其他项目入口文件。
第一次练习可以准备一个单独的测试目录，例如
```text
codex-demo/
├─ README.md
├─ src/
└─ tests/
```
不要把密码、API Key、生产配置和个人数据放进这个练习目录。Codex 能否访问文件，取决于当前客户端的权限设置。登录状态不代表它可以读取电脑上的所有内容。
## 在 VS Code 中打开
1. 在 VS Code 中选择“文件 > 打开文件夹…”，选中项目根目录。
2. 等待左侧资源管理器显示项目树，再点开一个你准备阅读的文件。
3. 打开 Codex 面板，把任务需要的文件加入上下文。
图 1 从“文件”菜单打开项目文件夹
如果项目已经在另一个 VS Code 窗口中打开，也可以用 Codex 的“Add Folder”入口添加目录。先只添加当前任务需要的目录，需要扩大范围时再添加，定位问题会更方便。
## 先做一次只读检查
在 Codex 输入框先发送一条只读请求
```text
请只读取当前项目，不要修改文件。请说明下面几项
1. 项目使用的语言和主要入口；
2. 如何安装依赖和运行测试；
3. 当前 Git 分支、工作区是否有未提交修改；
4. 你准备读取或运行哪些路径和命令。
```
看到它列出准备执行的命令后，先确认路径和命令符合预期。第一次使用时，可以保持“Ask for approval”或同等的逐次确认模式。
图 2 Codex 桌面端读取工作区，并说明准备检查的内容
## 在 Codex 桌面端和 CLI 中打开项目
在 Codex 桌面端打开左上角的“文件”菜单，选择“打开文件夹”，然后选中项目根目录。
图 3 在 Codex 桌面端打开项目文件夹
CLI 则在项目根目录启动
```powershell
cd C:\path\to\codex-demo
codex
```
启动后先发送同样的只读检查。Windows PowerShell 与 WSL 的路径和 Git 环境彼此独立，在哪个环境启动，就在哪个环境里检查和修改。
## 打开后的检查清单
- [ ] 当前工作目录是项目根目录。
- [ ] 没有把密钥、令牌或个人资料加入上下文。
- [ ] 已确认当前分支和未提交修改。
- [ ] 已让 Codex 先完成一次只读理解。
- [ ] 需要写入文件或运行命令时，知道如何逐项批准或拒绝。
完成这一步后，再进入下一篇的“小改动 + diff + 检查”练习。结果不符合预期时，先看 diff，再决定是否撤回改动。
下一步阅读 [完成第一次修改并检查结果](./09-完成第一次修改并检查结果.md)，用一个小改动练习 diff、验证和回退。
### 完成第一次修改并检查结果：本地网页练习与历史案例
URL: https://codexguide.io/guides/wan-cheng-di-yi-ci-xiu-gai-bing-jian-cha-jie-guo
本文首期使用独立的本地静态网页练习：只修改 index.html 的主标题和一段简介，保留按钮链接、其他 HTML 内容和全部 CSS。练习材料在 [练习材料/首次任务-本地网页/](../练习材料/首次任务-本地网页/)；不要直接操作 CodexGuide 正式网站或私人仓库。
# 完成第一次修改并检查结果：本地网页练习与历史案例
> 难度：基础
>
> 类型：首次任务后的结果检查
>
> 首期主线：准备 → 打开练习目录 → 完成小修改 → 检查结果
## 首期统一练习
本文首期使用独立的本地静态网页练习：只修改 `index.html` 的主标题和一段简介，保留按钮链接、其他 HTML 内容和全部 CSS。练习材料在 [`练习材料/首次任务-本地网页/`](../练习材料/首次任务-本地网页/)；不要直接操作 CodexGuide 正式网站或私人仓库。
适用环境：已经登录 Codex App 或 CLI 其中一种，并能打开复制出的练习目录。App 与 CLI 共用同一任务和验收标准，本轮没有声称所有系统和客户端均已实测。
## 先确认起始目录
1. 解压 [`Codex首次任务-本地网页练习包.zip`](../练习材料/Codex首次任务-本地网页练习包.zip)，或复制仓库中的 `练习材料/首次任务-本地网页/起始文件/`。
2. 把 `起始文件/` 复制到新的测试目录；Codex 应打开这个复制出的目录，直接看到 `index.html` 和 `styles.css`。
3. 先打开 `任务说明.md`，再阅读 `检查清单.md`。`参考差异/` 只在修改后查看。
4. 不要把原始 starter 当作工作区，也不要向目录加入 Token、`.env`、客户资料或生产配置。
## 给 Codex 的任务
```text
请先阅读 index.html 和 styles.css，不要修改文件。
然后只做这两处文字修改：
1. 将主标题改为“我的第一个 Codex 练习”；
2. 将简介改为“先看清修改，再确认页面结果。”。
请保留按钮文字、https://example.com 链接、其他 HTML 内容和全部 CSS 样式。
完成后告诉我修改了哪些行，不要运行部署或安装命令。
```
如果 Codex 先提出读取或编辑请求，确认路径仍是这个测试目录。App 和 CLI 的按钮、权限显示可能不同；本任务只需要允许当前练习目录内的读取和编辑。
## 检查修改范围
预期只有 `index.html` 的两处文字变化：
```diff
- 晨间读书角
- 用十分钟记录今天读到的一段话，慢慢建立自己的阅读清单。
+ 我的第一个 Codex 练习
+ 先看清修改，再确认页面结果。
```
逐项检查：
- `styles.css` 没有变化；
- 按钮文字仍是“查看阅读清单”；
- 按钮链接仍是 `https://example.com`；
- diff 中没有重排、安装、部署或其他文件修改；
- 若目录不是 Git 仓库，使用原始 starter 和当前文件做人工比较，不要凭空补写测试命令。
## 检查实际页面结果
直接在浏览器打开测试目录中的 `index.html`，确认标题、简介、按钮和样式都正常显示。页面能打开只证明浏览器读到了本地文件，不证明 Codex 已经正确完成任务；还要把页面看到的结果和 diff 对照。
## 出错时怎么处理
- 找不到 `index.html`：停止修改，用 `pwd`、`ls` 或 App 的当前文件夹信息确认打开的是复制出的目录。
- `styles.css` 或按钮链接发生变化：保留当前 diff 作为证据，重新解压到新目录，不要清空真实工作区或执行 `git reset --hard`。
- 页面文字正确但样式异常：比较 `styles.css` 与 starter；如果不能确认，重新解压再练习。
- 登录、权限或客户端入口异常：先看[登录 Codex](./07-登录Codex.md)和[安装登录常见问题](./13-安装登录常见问题.md)；仍无法定位时进入[故障排查目录](../15-故障排查与常见问题/README.md)。
## 当前练习的完成标准
- [ ] 在正确的复制目录中完成修改；
- [ ] 只改了 `index.html` 的标题和简介；
- [ ] 原有按钮文字、链接和 CSS 保留；
- [ ] 已查看 diff 或完成起始文件对照；
- [ ] 浏览器页面显示与目标文字一致；
- [ ] 记录了客户端、操作系统和任何未验证项。
下面保留此前发布的 README 文档案例，供希望学习“先查项目实际命令，再修改并验证”的读者参考。它依赖一个另行准备的 Node.js 练习项目，不是首期本地网页练习。
## 历史案例：README 文档修改
## 开始前确认
准备一个可以随时恢复的练习项目，并确认：
- 当前目录是项目根目录；
- 项目中没有密码、Token、客户资料或生产配置；
- 你知道当前 Git 分支和工作区状态；
- 第一次练习只改一个文件。
本次示例项目的目录如下：
```text
codex-first-edit-demo/
├─ README.md
├─ package.json
└─ tests/
└─ check.mjs
```
图一：打开练习项目，确认 README、配置文件和测试目录
## 先做只读检查
先让 Codex 读取项目，不要修改文件。可以直接发送：
```text
请先只读取项目配置和 Git 状态，不要修改文件。
请告诉我：
1. README.md 当前有哪些标题；
2. 项目的启动命令和测试命令；
3. 当前 Git 分支和工作区是否有未提交修改；
4. 完成下一步任务前，你准备读取哪些文件、运行哪些命令。
```
图二：先确认项目结构、脚本和 Git 状态
这一步的价值在于先看事实，再写任务。示例项目的 `package.json` 只有 `npm test`，没有 `npm run dev`。如果 README 写入不存在的启动命令，文档就会误导读者。
图三：项目配置没有 dev 脚本，不能把 npm run dev 当成可用命令
## 发送范围明确的修改请求
确认项目现状后，再发送修改请求。下面的写法同时限定了目标文件、禁止事项和验收方式：
```text
请只修改 README.md。
在“开发”这一节补充项目当前实际可用的命令，以 package.json 的配置为准。
限制：
- 不修改 package.json 和其他文件；
- 不新增依赖；
- 不调整现有标题层级；
- 不运行会修改数据或删除文件的命令。
如果发现我要求的命令不存在，请先说明，不要自行修改配置。
修改完成后先告诉我改了什么，并展示 diff，等我确认后再验证。
```
看到 Codex 请求写入文件或执行命令时，只批准与这次任务直接相关的操作。如果请求扩大到删除目录、覆盖大量文件或安装依赖，先停止并重新确认范围。
图四：再次强调只修改 README，避免任务范围扩大
## 查看修改摘要和 diff
Codex 完成编辑后，先看它的摘要，再打开编辑器的 Changes 面板。示例中最终只增加了 `npm test`，没有修改 `package.json` 或其他文件。
图五：修改摘要应说明文件、内容和依据
还可以让 Codex 只审查本次修改：
```text
请只审查刚才的改动：列出修改文件、每处修改的目的，以及是否违反了“只改 README.md”的限制。不要继续编辑。
```
重点检查三件事：
1. 修改文件是否只有预期文件；
2. 命令是否来自项目实际配置；
3. 是否混入格式化、重命名或无关内容。
图六：通过 diff 确认新增内容和未改动内容
如果项目已经有其他未提交修改，不要直接恢复整个文件。先区分哪些内容属于本次任务，再决定是否撤销。
## 做最小验证
diff 看起来正确后，再验证命令确实存在并运行项目已有的测试：
```text
请读取 package.json，确认 README.md 中写入的命令与项目配置一致。
确认没有问题后，只运行项目已有的测试命令 npm test。
不要安装依赖，不要修改配置，不要清理缓存。
请报告实际执行的命令、测试结果和当前 Git 状态。
```
示例项目的测试输出为 `README check passed`，退出码为 `0`。这说明本次 README 修改没有破坏已有检查。
图七：运行项目已有测试，确认结果可复现
如果项目没有自动化测试，就做 Markdown、命令名称和 diff 的人工检查，并在记录中说明“未运行自动化测试”。不要为了验证一个小改动擅自升级依赖、清理缓存或修改项目配置。
## 最后检查 Git 状态
在终端中执行：
```powershell
git diff --check
git status --short
git diff -- README.md
```
`git diff --check` 用来发现多余空格等基础问题；`git status --short` 确认没有意外改动；最后一条只查看目标文件的完整差异。
## 不符合预期时如何回退
发现修改超出范围或内容不对时，优先使用编辑器撤销，或者在确认目标文件没有其他人的改动后，精确恢复这次修改。不要删除整个项目目录，也不要把 `git reset --hard` 当作第一次练习的默认操作。
## 完成标准
- [ ] 目标文件和修改范围与任务描述一致；
- [ ] 已查看完整 diff，没有无关格式化或敏感信息；
- [ ] 已运行项目提供的最小检查，或记录了未运行原因；
- [ ] `git diff --check` 通过，工作区状态符合预期；
- [ ] 知道如何只撤销本次修改。
第一次修改的重点不是让 Codex 一次做很多事，而是建立一套可重复的节奏：描述目标，批准操作，检查 diff，运行验证，确认状态。后面的开发、修 Bug 和文档更新，都可以沿用这套流程。
接下来可以进入 [核心概念与任务方法](../02-核心概念与任务方法/) 和 [项目理解与上下文](../03-项目理解与上下文/)，继续学习任务拆分与项目规则。
### 用 Codex 批量压缩图片并转换为 WebP
URL: https://codexguide.io/guides/codex-batch-image-conversion-skill
文章配图经常需要限制宽度、转换格式和控制文件大小。img-convert Skill 可以让 Codex 按固定规则检查图片，再调用命令行工具批量处理。
# 用 Codex 批量压缩图片并转换为 WebP
文章配图经常需要限制宽度、转换格式和控制文件大小。`img-convert` Skill 可以让 Codex 按固定规则检查图片，再调用命令行工具批量处理。
本文使用 [dutchbase/img-converter](https://github.com/dutchbase/img-converter) 提供的 `img-convert` Skill，把指定目录中的图片限制在 1200px 宽，转换成质量 85 的 WebP，并写入独立输出目录。
> 本次实测环境为 Windows 11 24H2、Node.js 22.22.3 和 img-convert 1.0.4，测试完成于 2026-08-17。
## 查看 Skill 的能力和来源
`img-convert` 基于 Sharp，仓库使用 MIT 许可证。项目提供命令行工具、Node.js API、MCP 服务和 `SKILL.md`。本文使用 Codex Skill 配合 CLI 完成批量处理。
它支持读取 JPEG、PNG、WebP、AVIF、GIF 和 TIFF，也能调整尺寸、压缩质量、旋转、裁边和读取图片信息。批量任务可以传入 glob 路径，也可以使用 JSON 清单。
> 图片来源：[dutchbase/img-converter](https://github.com/dutchbase/img-converter)。
安装前先读取仓库，确认其中包含 `img-convert` Skill。
```powershell
npx -y skills add https://github.com/dutchbase/img-converter --list
```
命令应显示名为 `img-convert` 的 Skill。仓库中的 [SKILL.md](https://github.com/dutchbase/img-converter/blob/main/SKILL.md) 是实际执行说明。
> 图片来源：CodexGuide 实测。
> 图片来源：[dutchbase/img-converter SKILL.md](https://github.com/dutchbase/img-converter/blob/main/SKILL.md)。
## 安装 Skill 和命令行工具
先把 Skill 安装到 Codex 的全局技能目录。
```powershell
npx -y skills add https://github.com/dutchbase/img-converter `
--skill img-convert `
--agent codex `
--global `
--yes
```
Skill 负责告诉 Codex 怎样使用工具，不会自动安装 `img-convert` 命令。还要安装仓库发布的 npm 包。
```powershell
npm install -g @dutchbase/img-convert
```
本次安装成功，npm 同时提示依赖的 `glob@10.5.0` 已弃用。这个警告没有阻止本文测试。生产目录或自动化流水线使用前，应重新检查包版本、依赖审计结果和仓库更新情况。第一次运行时，先用可恢复的图片副本测试。
工具要求 Node.js 18 或更高版本。安装完成后检查命令是否可用。
```powershell
node --version
img-convert --help
img-convert info --help
img-convert batch --help
```
> 图片来源：CodexGuide 实测。
> 图片来源：CodexGuide 实测。
## 说明处理规则
本次实测使用下面这组参数。
| 项目 | 设置 |
|---|---|
| 输入 | 指定目录中的 JPG、JPEG、PNG 和 WebP |
| 输出目录 | 新建 `output` 目录 |
| 最大宽度 | 1200px |
| 输出格式 | WebP |
| 图片质量 | 85 |
| 原文件 | 保留，不覆盖、不删除 |
`img-convert` 默认保持宽高比，也不会放大小图。宽度超过 1200px 的图片会等比缩小，小于 1200px 的图片保持原尺寸。
输出目录应与原图目录分开。命令参数即使写错，原文件仍能保留。
## 先用 dry-run 预演
假设原图位于 `D:\images\original`，先运行 `--dry-run` 查看将要处理的文件。
```powershell
img-convert "D:/images/original/**/*.{jpg,jpeg,png,webp}" `
--format webp `
--width 1200 `
--quality 85 `
--output "D:\images\output" `
--dry-run `
--json
```
glob 路径放在引号中，让 `img-convert` 展开文件列表。Windows 下的 glob 使用正斜杠 `/`。反斜杠可能被当成转义符，导致工具找不到图片。
预演完成后检查文件数量和输出目录，也要确认不同格式的同名文件不会写成同一个 `.webp`。
> 图片来源：CodexGuide 实测。
## 确认后执行批量转换
预演结果正确后，去掉 `--dry-run`。
```powershell
img-convert "D:/images/original/**/*.{jpg,jpeg,png,webp}" `
--format webp `
--width 1200 `
--quality 85 `
--output "D:\images\output" `
--json
```
`--json` 返回每张图片的输入大小、输出大小、压缩比例、尺寸和保存路径。截图中的 `compact-json.js` 只调整真实 JSON 的换行，字段和值没有改动。三张图片全部转换成功，失败数为 0。
> 图片来源：CodexGuide 实测。
不同图片需要不同尺寸或格式时，可以让 Codex 先生成 JSON 清单，再运行批处理。
```powershell
img-convert batch jobs.json --json
```
统一转换使用 glob 即可，不必先做清单。
## 让 Codex 调用 Skill
安装后重启 Codex，再提交下面的任务。
```text
使用 img-convert Skill，先检查 D:\images\original 中会被处理的 JPG、JPEG、PNG 和 WebP 图片。
把宽度限制为 1200px，保持比例，不放大小图，统一转成质量 85 的 WebP，输出到 D:\images\output。
保留所有原文件。先 dry-run 并汇报文件数量和命名冲突，确认没有问题后再执行，最后给出处理成功数、失败数和总压缩比例。
```
这段任务要求 Codex 先检查和预演，再执行并汇报结果。Skill 也会提醒 Codex 读取陌生图片的信息，留意透明通道和动画图片。
## 核对三张公开测试图片
测试集包含一张 1800×1200 JPG、一张 560×560 PNG 和一张 550×368 WebP。大图等比缩到 1200×800，两张小图保持原尺寸，说明 `--width 1200` 没有放大小图。
统一转换为 WebP 后，每张图片的体积变化不同。JPG 减少 48.8%，PNG 减少 14.2%，原本已经压缩过的 WebP 重新编码后增加 19.7%。批量任务结束后要检查负压缩率，不能只看成功数量。
| 项目 | 处理前 | 处理后 |
|---|---|---|
| 图片数量 | 3 | 3 |
| 总文件大小 | 237,357 字节 | 144,698 字节 |
| 最大宽度 | 1800px | 1200px |
| 文件格式 | JPG、PNG、WebP | WebP |
| 失败数量 | - | 0 |
总大小减少 92,659 字节，整体压缩率约 39.0%。原图目录没有被覆盖，三个 WebP 都写入独立的 `output` 目录。
> 图片来源：CodexGuide 实测。
## 完成后检查
- 原图数量、名称和内容没有变化。
- 输出图片都位于独立目录。
- 横图和竖图保持原始比例，小图没有被放大。
- 透明区域正常，动画图片没有意外丢帧。
- 同名输入不会覆盖同一个 WebP 文件。
- 失败文件和原因已经单独列出。
## 参考资料
- [dutchbase/img-converter](https://github.com/dutchbase/img-converter)
- [img-convert SKILL.md](https://github.com/dutchbase/img-converter/blob/main/SKILL.md)
- [@dutchbase/img-convert](https://www.npmjs.com/package/@dutchbase/img-convert)
- [MIT License](https://github.com/dutchbase/img-converter/blob/main/LICENSE)
### Codex 做上线前端到端验收
URL: https://codexguide.io/guides/codex-browser-e2e-acceptance
最近不停在上一些小功能，就需要验收。
# Codex 做上线前端到端验收
最近不停在上一些小功能，就需要验收。
验收时有几个麻烦点。它涉及登录态、数据、扣费、历史记录等。只看代码或者只跑单元测试都不够，最后一定要有人在真实环境里过一遍完整流程。
可以把测试用例交给 Codex，让它通过浏览器扩展控制已有登录态，直接完成端到端验收。
## 为什么适合交给 Codex 验收
以前做这种验收，麻烦在于点击过程中要不断判断状态。
比如页面上的入口有没有出现，弹窗或表单里的数据能不能正常选择，选择后的状态有没有回填，点击提交以后有没有前端校验错误，异步任务最终有没有结果，余额有没有变化，历史记录有没有新增。
这些事情连在一起就很容易漏。验收过程里还要截图、记录余额、记录错误文案，最好能把每一步结论都留下。
Codex 做这类任务有一个很舒服的点，它可以按测试用例一步一步执行，同时把过程可视化地反馈出来。哪一步通过了，哪一步有问题，它会直接标出来。需要证据时，它也会把截图保存下来。
这张图里能看到，A 到 H 每个断言都有状态。有些通过，有些失败，另一些因为预算或条件跳过。对我来说，这比口头说"我测过了"可靠很多，因为它保留了过程。
## Codex 浏览器登录态的优势
Codex 通过 Chrome 插件接管浏览器。
自动化测试也可以处理登录态，但通常需要维护测试账号、登录脚本和状态文件。在研发阶段的人工终验里，我更需要直接使用当前浏览器里已经登录好的账号，让 Codex 接管现有页面继续操作。
这对很多真实产品场景很方便。比如后台权限已经配置好，账号已经在某个分组里，或者页面状态和环境刚刚调好。让 Codex 直接接管这个浏览器，会比重新写一套登录和准备脚本省很多时间。
Codex 适合上线前后的人肉终验、一次性排查、扣费路径和复杂后台状态验证；稳定、可重复的批量回归仍应由项目现有的自动化测试负责。
## 测试用例越具体，Codex 执行越稳
这次让我感受最明显的一点是，测试用例要写得足够具体。
不要只写"测试这个功能是否可用"，这句话太宽了。更好的写法是把每一步拆清楚，写明打开哪个 URL、点击哪个入口、选择什么测试数据、表单里填什么，以及失败时要记录哪些信息。
当流程写清楚以后，Codex 执行起来就很像一个耐心的验收同事。它不会只看页面有没有报错，而是会按断言逐项收集证据。
在一次带扣费的异步任务验收里，它会先记录初始余额，按测试用例选择素材和参数，确认页面预估费用，提交后检查有没有前端校验错误，再等待任务结果。任务完成后，它还会回到 dashboard 和 history 页确认扣费与产物记录。
最后的报告里，它不仅说"通过了"，还列出了每张截图证据，包括初始状态、关键输入、提交前参数、生成过程、成功结果和最终历史记录。以后有人要追查这个功能是否真的验过，直接看这些证据就行。
## 这类验收应该怎么分工
Codex 更适合放在验收阶段。尤其是需要真实浏览器、真实登录态、真实环境和真实产物时，它可以操作页面，并记录每一步。
中间最重要的交接物是一份清楚的测试用例。里面最好包含测试环境、账号或登录方式、初始状态、每一步操作和断言，以及预算、失败证据和禁止动作。
## 一个可复用的小结论
Codex 可以放在研发流程的不同位置，写代码和验收功能是两类任务。
实现功能是一件事，验证功能又是另一件事。
这次的体验让我觉得，端到端验收很适合交给能控制浏览器、保留上下文并截图取证的 Codex。前提是测试用例要写清楚，尤其是涉及登录态、扣费、权限、历史数据和异步任务的路径。
这套分工适合需要真实登录态和真实产物的验收任务。
### Codex 在任务结束时捕捉可复用素材
URL: https://codexguide.io/guides/codex-capture-reusable-content
一个任务刚结束时，操作步骤、失败原因和取舍还在当前上下文里。等到几天后再整理，很多细节已经需要重新查。可以给 Codex 增加一条任务结束规则，只在确实出现可复用经验时生成素材候选。
# Codex 在任务结束时捕捉可复用素材
一个任务刚结束时，操作步骤、失败原因和取舍还在当前上下文里。等到几天后再整理，很多细节已经需要重新查。可以给 Codex 增加一条任务结束规则，只在确实出现可复用经验时生成素材候选。
这条规则适合经常用 Codex 做项目维护、工具接入和流程改进的人。它只负责记录线索，不自动发布内容，也不应把私密配置写进素材库。
> 概念示意，任务完成后先判断复用价值，再整理可核对的素材记录。
## 哪些任务值得记录
触发条件要具体，否则 Codex 每次简单问答后都来提醒，几天以后这条规则就会变成干扰。
适合记录的内容包括一条跑通的工具接入流程、经过验证的配置取舍、具有复现步骤的故障处理，以及可以重复执行的发布或检查方法。
下面几类任务可以直接跳过。
- 纯聊天和简单问答。
- 没有稳定复现方式的偶发故障。
- 只对当前临时环境有效的处理。
- 包含账号凭据、客户数据或内部地址，且无法可靠脱敏的内容。
- 赶时间结束，用户已经明确不需要额外整理的任务。
## 把规则放在哪里
只服务一个仓库的规则可以写入项目根目录的 `AGENTS.md`。多个项目都要使用时，可以放进 Codex 的用户级 `AGENTS.md`，再让具体项目用更靠近工作目录的规则覆盖它。
项目规则会随仓库一起共享。个人内容规划、私有素材路径和账号信息不要提交到公共仓库，这类设置更适合放在本机用户级规则中。
## 一份可直接使用的触发规则
```markdown
任务结束时捕捉可复用素材
完成主要任务后，检查本次工作是否产生了可复用经验。
满足下列任一条件时，输出一个“素材候选”小节。
- 跑通了可以重复执行的工具接入或自动化流程。
- 找到并验证了一个不明显的故障原因和修复方法。
- 形成了有依据的配置、安全或发布取舍。
- 产出了可公开复用的命令、检查清单或操作顺序。
纯聊天、简单问答、机械性修改和没有复现证据的猜测不触发。
素材候选包含任务场景、实际操作、遇到的卡点、解决方法、
可复用结论和证据路径。不得写入密钥、个人信息、客户数据、
内部域名或未经确认的结论。
只生成候选内容。写入素材文件或发布前先取得用户确认。
```
规则里的“完成主要任务后”很重要。素材整理不能打断原任务，也不能把尚未验证的中间结果写成经验。
> 原稿中的规则配置示例，展示了触发范围、跳过条件和输出要素。
## 固定素材候选的格式
稳定格式方便后续筛选，也能减少同一件事被写成多条空泛总结。
```markdown
素材候选
- 任务场景
- 实际操作
- 卡点与原因
- 解决方法
- 可复用结论
- 证据路径或公开来源
- 需要删除或脱敏的信息
```
证据路径可以是改动文件、测试命令、公开文档链接或错误日志位置。它帮助后续写作者重新核对，不代表这些内部路径都可以直接公开。
## 需要落盘时再增加保存规则
素材候选先显示在任务结果里最稳妥。确定要长期保存后，可以增加一个本机目录，例如 `notes/materials/`，并规定文件名和状态字段。
```markdown
---
title: Codex 任务素材标题
status: candidate
created: 2026-08-20
source_task: 任务名称或本机记录
privacy_review: pending
---
```
公共仓库不适合存放个人内容计划。素材目录如果位于项目内，需要先检查 `.gitignore` 和团队约定，避免把本机记录误提交。
## 用一个小任务验证规则
配置完成后，分别测试一次应该触发和不应触发的任务。
1. 让 Codex 完成一个带验证步骤的小型流程改动，检查结果中是否出现素材候选。
2. 提一个普通概念问题，确认它不会生成无关提醒。
3. 在测试材料里放入明显的占位密钥，确认输出不会复述敏感值。
4. 拒绝保存一次，确认 Codex 不会擅自写入素材文件。
如果触发太频繁，就收紧条件。候选内容总是很空，说明规则缺少证据字段或任务本身没有足够材料。先把触发和记录做好，再考虑自动分类、定时复盘或发布工作流。
## 参考资料
- [Codex 的 AGENTS.md 说明](https://developers.openai.com/codex/guides/agents-md)
- [Codex 官方文档](https://developers.openai.com/codex/)
### Codex 跨会话协作功能
URL: https://codexguide.io/guides/codex-cross-session-collaboration
Codex 的跨会话协作功能，我已经用了一段时间。它帮我省掉了很多来回搬运信息的时间。
# Codex 跨会话协作功能
Codex 的跨会话协作功能，我已经用了一段时间。它帮我省掉了很多来回搬运信息的时间。
下面是我目前的使用场景。
我比较喜欢把一个需求或一项任务完整地放在同一个会话里，从讨论、执行到最后部署上线。这样这个会话会非常清楚整个需求的上下文，从开始一直到最终验收，也能确保不会混入其他内容。
一个会话里要处理的事情太多，经常动不动就是一长串 P0、P1、P2，很容易把需要我决策的关键信息覆盖掉。
如果重新开一个会话，人又像搬运工一样，需要来回复制粘贴，还可能漏掉关键点。
Codex 支持一个会话创建另一个会话，并把任务交过去，这个问题就简单了很多。
比如功能做完之后，我可以直接告诉它：“准备测试用例，在某个文件夹下面创建一个新会话，把测试交给对方来做，你负责验收即可。”
这样一个负责测试，一个负责验收，两个会话之间可以互相交流。我只需要等结果，再做最后的验收就行了。
再比如，一个任务进行过程中衍生出了可以独立处理的其他任务，也可以直接让当前会话创建一个新会话，把任务和上下文一起发送过去，省时省力。
### Codex 远程连接支持移动端与 Windows 主机
URL: https://codexguide.io/guides/codex-remote-control-mac
Codex 的远程连接适合把一台持续在线的电脑作为主机，在另一台设备上发任务、看进度和检查结果。代码、命令和桌面操作仍然发生在主机上。
# Codex 远程连接支持移动端与 Windows 主机
Codex 的远程连接适合把一台持续在线的电脑作为主机，在另一台设备上发任务、看进度和检查结果。代码、命令和桌面操作仍然发生在主机上。
## 移动端配对
移动端使用同一个 ChatGPT 账号和 workspace。桌面端显示二维码或配对入口后，用 iOS 或 Android 上的 ChatGPT 扫码并确认授权。配对完成后，手机可以继续已有会话、接收完成或需要关注的通知，也可以在已连接主机上创建新任务。
主机必须在线、唤醒并保持 Codex App 可用。手机显示离线时，先检查主机睡眠状态、网络和登录 workspace。
## Windows 主机的限制
远程连接支持 Windows host。Windows 上的 Computer Use 会占用当前桌面的前台输入，会移动指针并输入文字；任务运行时不能同时操作同一桌面。需要后台处理时，优先使用 CLI、结构化 MCP 或浏览器扩展。
## Mac、SSH 与安全边界
Mac 主机可以通过 Control this Mac 和 Control other devices 配置单向控制；Linux 或 devbox 通过 SSH 连接。两台设备应使用同一账号，控制方向需要分别授权。
涉及真实项目时仍要检查 Git diff、命令结果和测试。不要把密码、Token、客户数据或生产删除操作交给未经确认的远程任务。
参考：[Codex Remote connections](https://developers.openai.com/codex/remote-connections)、[Work with Codex from anywhere](https://openai.com/index/work-with-codex-from-anywhere/)。
### Codex 浏览器操作与登录态功能
URL: https://codexguide.io/guides/codex-browser-login-state
Codex 现在可以通过浏览器扩展、内置浏览器和 Computer Use 操作网页或桌面应用。这几种入口的登录态、操作范围和限制不同，选错入口容易在任务中途卡住。
# Codex 浏览器操作与登录态功能
Codex 现在可以通过浏览器扩展、内置浏览器和 Computer Use 操作网页或桌面应用。这几种入口的登录态、操作范围和限制不同，选错入口容易在任务中途卡住。
前几天让 Codex 通过浏览器扩展走一遍开放平台的应用权限发布流程。它先在我开着的标签页里找到之前保留的权限页，直接接管并进入发布流程。
每走一步，它都在对话里说清楚自己在干什么。而且边界定的挺好的，不确定的，还有权限相关的问题会停下来确认。
前几天发现Codex有画中画功能，太牛了。
界面右侧多了个画中画小窗，它操作哪个页面，小窗里就实时显示哪个页面，不用再在 Codex 和浏览器之间来回切。
这是最近一次大版本更新带的。那次更新把 Codex 桌面应用的相关能力集中到了新的桌面体验里。
只要 Codex 开始操作电脑或浏览器，小窗就自动弹出。可以拖动位置，点一下直接跳到正在被操作的应用。任务用到多个窗口时，预览叠成一摞，可以切着看。
不想看就关掉，任务运行中随时能从任务摘要视图重新打开，侧边栏的"电脑使用"分区里也有显示开关。
## 它确实不抢你的鼠标
我注意到一个细节，它在浏览器里点点点，我自己的鼠标不受影响，该干嘛干嘛。
查了一下，Chrome 扩展安装时申请的第一个权限就是页面调试器，也就是 Chrome DevTools Protocol。它的点击和输入是通过调试协议直接发进页面的合成事件，不经过系统鼠标，你的光标不会被拖走。
官方发布 Chrome 扩展时的说法也是这个意思，**它可以在后台跨标签页并行干活，不接管你的浏览器**。
操作 macOS 桌面应用的 Computer Use 同理，它用自己的光标去看、去点、去打字，不干扰你在其他应用里的工作。
例外是 Windows。Windows 上的 Computer Use 只能在当前桌面前台跑，官方文档明确写了会移动指针、打字、占住前台。
## 三个入口
Codex 现在有三种操作界面的方式。
内置浏览器（@Browser）用独立的浏览器环境，默认没有你的登录态。看公开网页、预览 localhost 上自己开发的页面，用它最干净。
不过最近上了一个"从浏览器导入"功能，可以把 Chrome 的密码和 Cookie 拷一份进内置浏览器，导入时要完全关闭 Chrome。Cookie 本身就是登录凭证，导过之后它也能直接打开需要登录的网站了。
官方文档原来写内置浏览器不支持登录，这次改版已经把这句删掉了。
要注意这是一次性拷贝，不是持续同步。之后你在 Chrome 里新登录的账号、改过的密码不会跟过来。官方也提醒 Cookie 要当敏感数据对待，导了哪些站的登录态，自己心里要有数。
Chrome 扩展（@Chrome）直接用你 Chrome 里已登录的账号。判断标准就一条，任务是否依赖你的账号、cookies 或已经打开的标签页。要就用它，我这次的后台配置就属于这类。和导入过数据的内置浏览器比，扩展用的是活的 Chrome，当下的会话、刚打开的标签页都在。
Computer Use（@Computer）操作桌面应用，活儿完全在浏览器之外时才轮到它。
如果任务有结构化接口，优先让 Codex 使用结构化连接。只有接口覆盖不到时，再让它通过视觉操作完成任务。
## 别人都拿它干什么
看了一圈国内外的实测分享。
流传最广的一个案例，有人让它盯亚马逊客服的排队页面，每五分钟看一眼，真人客服上线后改成每分钟盯，最后趁主人洗澡的时候把退款办完了。
日常一点的用法也不少。每天定时检查社交账号的私信，把用户反馈收集进笔记库，并且明确禁止它发帖；把领英收件箱里的招聘私信按公司分组整理；从通话笔记更新 CRM 里的客户记录。
开发相关的，登录后才能复现的 bug 直接在真实会话里复现；开多个标签页，并行测试不同用户角色下的流程。
信息整理类，搜十几篇游记，把景点整理进在线表格，再去地图上建好收藏清单。
这些活的共同点是没有 API，界面是唯一入口，以前只能自己点。
## 想让它干得稳，有几个技巧
看别人的经验，加上我自己这次的体会，有几条值得记下来。
**把禁区和停止点写进指令里。**比如"不要动账号和订阅设置""提交前停下来等我确认"。发送、发布、购买这类动作前必须留人工确认，这是社区的普遍共识。
指令用"做 X，验证 Y，符合 Z 才继续"的写法，能明显减少静默失败。让它汇报具体细节，比如确切的 URL 和页面上的确认信息，别让它只说"完成了"。
**从小任务开始，跑通的指令存下来复用。**一次性的演示跑成功了，把 prompt 原文存住，下次同类活直接用，慢慢攒出自己的自动化清单。
授权按域名管理，首次访问新网站它都会弹窗问你。白名单从空开始按需加，财务、HR 这类后台可以直接拉黑。"始终允许浏览器内容"这种开关官方自己都标了高风险。
要让它往网页表单传文件，得在 Chrome 扩展详情里手动打开文件访问权限，不然会卡在上传那步。
Codex 模型分为 Sol、Terra、Luna 三档之后，派活可以更精细。日常任务用 Terra 就够，难题再上 Sol。Luna 快而便宜，但长上下文能力差得多，别拿它碰大仓库和长文档。
如果上下文或用量紧张，关闭当前任务用不到的连接，并在任务摘要里确认剩余用量。
## 不该给它的活
反爬严的站点和验证码它过不去，一操作就容易被拦。系统级的安全弹窗它点不了，需要管理员身份的认证也过不去，这些是官方明确的硬边界。
浏览器扩展目前只支持一个浏览器配置档。切换配置档后，需要重新完成扩展连接和授权。
更要紧的是安全边界。授权是按域名给的，一个域名放行之后，上面的页面内容都会进它的上下文，恶意页面理论上可以往里塞指令。这个问题目前没有根治的办法。
所以社区的红线很一致，支付、删除生产数据、改安全设置、大批量导出个人数据，这四类活永远自己点。**它能做，不代表应该让它做。**
## 这个月还上了什么
这波更新里画中画只是个小点，changelog 里还有不少东西。
这次桌面更新除了画中画，还加入了应用内编辑代码和文档、行内批注、代码评审等能力。
GPT-5.6 也在这波全量上线，就是上面说的三个档位，API 定价每百万输入 token 分别是 5、2.5、1 美元。Computer Use 换上 GPT-5.6 之后，操作速度也提了一截。
CLI 也在补充远程连接和任务管理能力，具体入口以当前版本界面为准。
## 参考资料
- [Codex 官方文档](https://developers.openai.com/codex/)
### 在 Codex 中连接 Notion：把调研结果写入数据库
URL: https://codexguide.io/guides/codex-notion-plugin-workflow
这篇教程适合已经能在 Codex 桌面端创建任务，并希望把调研结果直接整理到 Notion 的读者。完成后，你会连接 Notion 插件、验证页面读取权限，并把一组结构化资料写入两个数据库。
# 在 Codex 中连接 Notion：把调研结果写入数据库
这篇教程适合已经能在 Codex 桌面端创建任务，并希望把调研结果直接整理到 Notion 的读者。完成后，你会连接 Notion 插件、验证页面读取权限，并把一组结构化资料写入两个数据库。
示例只使用测试工作区。不要用客户资料、内部知识库或个人页面做第一次连接测试。
## 本教程环境
以下环境核验于 2026 年 8 月 13 日。Notion 插件运行在 Codex 桌面端的 Plugins 界面中，不要求通过 IDE 或 Codex CLI 操作。
| 项目 | 本教程使用版本 | 获取方式 | 备注 |
|---|---|---|---|
| 操作系统 | Windows 11 专业版 64 位，构建 `26100` | Windows 系统信息 | 本机实测环境 |
| Codex 桌面端 | `26.803.10989.0` | Windows 应用包信息 | 本教程的插件宿主 |
| Notion 插件 | 目录托管版本，界面未展示独立版本号 | Codex Plugins 目录 | 以当前插件详情为准 |
| Notion Connector | Web 托管版本，界面未展示独立版本号 | Notion 授权界面 | 可用权限受工作区设置影响 |
| Codex CLI | `0.146.1` | `codex --version` | 本教程不在 CLI 中执行 |
界面、插件入口和授权范围可能随 Codex、Notion 或工作区策略调整。操作时以当前页面为准。
## 先说结论
这套流程分成四步：安装插件、限制授权范围、用测试页面验证读取、确认字段后再写入数据库。
真正需要谨慎的是授权和写入。第一次连接时只开放测试页面；批量创建或更新内容前，先让 Codex 列出准备执行的操作。
## 1. 安装 Notion 插件
启动 Codex 桌面端，在左侧导航栏打开“插件”。如果没有这个入口，先确认当前版本和工作区支持 Plugins，再检查组织管理员是否限制了插件安装。
进入插件目录，在搜索框输入 `Notion`。核对名称和说明后点击安装。
安装过程中，Windows 可能询问是否允许网页打开 ChatGPT。确认地址和来源无误后再继续。不希望系统以后自动跳转，就不要勾选“始终允许”。
## 2. 限制 Notion 授权范围
连接窗口会列出 ChatGPT 与 Notion 之间共享的数据。先检查申请的权限，再确认选中的 Notion 工作区。
本教程没有保留工作区选择页，因为原画面包含个人空间名称。制作自己的操作记录时，也应隐藏邮箱、成员名单、内部页面名称和授权令牌。
建议新建一个只含公开示例内容的测试页面，并只把这个页面开放给连接。等读取和写入都验证完成，再根据实际任务扩大范围。
## 3. 用测试页面验证连接
新建 Codex 任务，在输入框键入 `@notion`，从候选列表中选择 Notion 插件，然后写清楚要读取的测试页面。插件必须加入当前任务，Codex 才能在这轮对话中调用它。
第一次只做只读验证。可以使用下面的任务描述：
```text
请读取 Notion 中的测试页面“Notion-Codex demo”，只返回页面标题、正文是否为空和当前可见的属性。不要创建、修改或删除任何内容。
```
本次示例返回的页面只有标题，没有正文。这说明连接已经建立，Codex 也能访问指定页面。
如果提示找不到页面，先检查页面是否属于已授权工作区、当前账号是否有访问权限，以及授权时是否选中了正确页面。不要为了绕过错误直接开放整个工作区。
## 4. 调研资料并确认字段
连接验证通过后，再提交正式调研任务。本次示例整理主流 AI 图片与视频生成模型，要求优先使用官网、官方文档、公告和定价页，并记录：
- 模型名称、厂商、发布时间和版本。
- 核心参数、可用状态和价格。
- 优点、限制、推荐场景和官方来源。
- 官网没有公开的字段标为“暂未公开”，不补猜测值。
Codex 完成检索后，先在任务中检查结构化结果，不要立刻写入 Notion。截图中的调研基准日是 2026 年 8 月 12 日；模型状态和价格变化较快，复用这套表格时需要重新核对。
检查时重点看字段是否一致、每条记录是否有来源、未知信息是否被明确标出。发现无来源的价格或参数，先删除或补证据。
## 5. 写入 Notion 数据库
确认内容后，再让 Codex 创建一个总览页，并把图片模型和视频模型分别放进两个子数据库。总览页保留调研日期、使用说明和数据库入口。
图片模型数据库使用厂商、可用状态、计费方式、优势标签、推荐场景和官方来源等字段。标签适合筛选，官方来源用于后续复核。
视频模型数据库沿用同一套字段。图片和视频分开后，各自的版本、状态和价格更容易维护。
## 如何验收
写入完成后，不要只看 Codex 的完成提示。回到 Notion 逐项检查：
1. 总览页和两个数据库位于预期的测试页面下。
2. 数据库字段名称、类型和选项一致。
3. 每条记录都有可打开的官方来源，未知字段没有被猜测值填满。
4. 没有覆盖同名页面，也没有修改授权范围之外的内容。
5. 测试结束后，Notion 连接设置中的访问范围仍符合预期。
如果结果不对，先停止后续写入。记录出错的字段或页面，再让 Codex 只修正这一小部分。
## 权限与限制
- 插件能看到什么，取决于 Notion 账号、工作区策略和授权页面范围。
- 批量写入前先要求 Codex 列出目标页面、数据库和字段，不要把确认步骤省掉。
- 价格、地区可用性和 Preview 状态会变化，资料库应保留来源与核验日期。
- 不再使用的测试连接可以撤销；测试页面应与正式知识库分开。
- 本教程只验证了页面读取、页面创建和数据库写入，没有验证团队级权限管理或大批量更新。
## 参考资料
- [Notion 官方网站](https://www.notion.com/)
- [OpenAI Codex 文档](https://developers.openai.com/codex/)
### Codex 桌面端协作设置，从入口到权限与任务纠偏
URL: https://codexguide.io/guides/codex-desktop-collaboration-settings
这篇文章写给已经安装 ChatGPT 桌面端，准备让 Codex 读取项目、修改文件并运行命令的读者。
# Codex 桌面端协作设置，从入口到权限与任务纠偏
> 难度 | 基础
>
> 类型 | 设置与权限
## 这篇文章适合谁
这篇文章写给已经安装 ChatGPT 桌面端，准备让 Codex 读取项目、修改文件并运行命令的读者。
你会依次检查工作入口、长期协作习惯、默认表达方式、权限，以及新消息是立即纠偏还是排队等待。
界面会随版本变化。找不到某个选项时，先更新桌面端，再以当前设置页和官方文档为准。
## 先选对工作入口
桌面端把 ChatGPT 与 Codex 放在同一个产品中，但两者面对的任务不同。
ChatGPT 适合讨论、研究和文件类交付。Codex 面向软件开发任务，可以在你授权的工作区中读取和修改文件、运行命令，并结合测试结果继续工作。
准备改代码、配置或仓库文件时选择 Codex。只想比较方案或整理想法时，可以先在 ChatGPT 中讨论，方向确定后再进入 Codex。
## 把稳定要求写进自定义指令
设置页的“个性化”区域包含自定义指令和 Memories。两者不能混为一项设置。
自定义指令保存你主动声明的长期要求，例如修改范围、汇报方式和验证标准。可以先写一组短规则。
```text
开始修改前先读取仓库规则和相关文件。
只处理当前任务需要的范围。
完成后说明改动文件、验证命令和未覆盖的风险。
提交、推送、发布或删除重要数据前先确认授权。
```
Memories 用来让后续聊天复用过去工作中提取的有用信息。官方文档说明，本地 Codex Memories 默认关闭，可在“设置 > 个性化”中启用，也可以用 `/memories` 控制当前聊天是否读取或生成记忆。
密钥、Cookie、客户资料和私人聊天原文不要写进自定义指令或长期记忆。项目事实仍应保存在项目文档、代码和版本记录中，并在使用前重新核对。
## 个性只改变表达方式
如果回复经常太长，可以在“个性”中选择更直接的表达方式。
个性会影响默认语气和解释多少，不会提高模型能力，也不会覆盖当前任务的明确要求。与其只靠一个全局选项，不如在重要任务里写清交付格式。
```text
先给处理结果，再列验证情况和剩余风险。
解释控制在读者能够复核修改的范围内。
```
## 权限要跟任务风险匹配
Codex 的权限决定它能读取哪些路径、能否写入工作区，以及网络或工作区之外的操作是否需要审批。
第一次进入陌生项目，先使用受限权限完成只读检查。确认项目结构、Git 状态和计划后，再允许工作区写入。只有任务确实需要广泛文件或网络访问，并且你清楚影响范围时，才考虑更宽的权限。
完整访问会减少中途审批，也会扩大误删文件、泄露数据或执行意外命令的影响。生产数据库、账号安全设置、公开发布和费用相关操作应保留人工确认点。
## 用 Follow-up behavior 控制临时消息
Codex 工作时仍然可以接收新消息。设置页的 Follow-up behavior 决定消息进入当前执行，还是等待下一轮。
Steer 会把新消息加入当前执行，适合纠正范围、补充遗漏条件或提供新证据。Queue 会把消息留到下一轮，适合不应打断当前工作的后续任务。
发现 Codex 正在修改无关文件时应立即 Steer。想让它完成测试后再整理文档，则可以 Queue。队列中的消息可以在发送前编辑、调整顺序或删除。
## 设置完成后再扩展 Skills
Skills 用来保存可复用的工作流程，不负责修复含糊的任务边界。先把入口、指令和权限调顺，再根据重复出现的真实任务选择 Skill。
官方文档建议让每个 Skill 聚焦一个任务，写清触发条件、输入、步骤和输出。安装第三方 Skill 前，还要检查来源、脚本、依赖、文件访问和网络请求，并用可丢弃的样例做第一次测试。
## 验证设置是否生效
选一个有 Git 版本控制的小项目，先让 Codex 只读检查，再交给它一项可以撤销的小修改。
```text
先读取 README、仓库规则和 Git 状态，不要修改文件。
说明完成这项小改动需要哪些文件、命令和权限，等我确认后再执行。
```
执行中补一条范围限制，观察消息是立即 Steer 还是进入 Queue。完成后检查 `git diff` 和验证命令。能够看清修改范围、审批节点和验证结果，说明这套设置已经可以用于日常任务。
## 参考资料
- [Codex Quickstart](https://developers.openai.com/codex/quickstart)
- [Codex app settings](https://developers.openai.com/codex/app/settings)
- [Codex permissions](https://developers.openai.com/codex/permissions)
- [Codex Memories](https://developers.openai.com/codex/memories)
- [Prompting 中的 Steering 与 Queue](https://learn.chatgpt.com/docs/prompting)
- [Codex Skills](https://developers.openai.com/codex/skills)
### Codex 长任务工作流，分开讨论、执行、审查与交接
URL: https://codexguide.io/guides/codex-long-task-collaboration-workflow
这篇文章适合已经能用 Codex 完成小修改，但在长任务中遇到上下文混乱、讨论打断执行、审查缺少独立视角或跨聊天交接困难的读者。
# Codex 长任务工作流，分开讨论、执行、审查与交接
> 难度 | 进阶
>
> 类型 | 长任务与多 Agent 协作
## 这篇文章适合谁
这篇文章适合已经能用 Codex 完成小修改，但在长任务中遇到上下文混乱、讨论打断执行、审查缺少独立视角或跨聊天交接困难的读者。
核心做法很简单。临时问题放进 Quick Chat，围绕当前任务的方案讨论放进 Side Chat，范围明确的独立工作交给 Subagent，修改完成后单独 Review，最后留下可以复核的交接记录。
## 推理强度只解决一部分问题
复杂任务需要足够的推理强度，但把所有工作塞进一个聊天，选择更高档位也不会自动消除上下文噪声。
先按任务难度选择模型和推理强度。架构取舍、跨模块修改和回归风险较高的排查需要更充分的推理；机械搜索、读取日志或执行边界已经确定的小步骤，可以交给更快的模型或独立工作线程。
模型名称和可用档位可能随账号与版本变化。不要把某个档位写成长期规则，先在当前模型选择器中确认。
## 临时问题放进 Quick Chat
Quick Chat 适合处理不应打断主任务的短问题。Windows 可以使用 `Ctrl + Alt + N`，也可以从“新聊天”旁的入口打开。
例如主任务正在运行测试，你想确认一个配置字段的含义。把问题放进 Quick Chat，等结论明确后再决定是否加入主任务。
回传时只发送已经确认的要求，不要把整段试探性讨论全部带回去。
## 方案分歧放进 Side Chat
Side Chat 会带着当前任务的相关上下文开始一段临时讨论，同时不打断主聊天。IDE 中可以使用 `/side`。
看到某段内容需要单独展开时，也可以选中文字后进入 Side Chat。
桌面端任务菜单同样提供入口。
Side Chat 适合比较两种实现、检查迁移风险或整理新的执行指令。讨论结束后，把决定和理由压缩成几句话送回主任务。
## 独立工作交给 Subagent
官方文档将 Subagent 定位为并行处理独立子任务的方式。每个 Subagent 有自己的上下文，主聊天负责委派、等待和汇总。
适合委派的任务包括只读扫描某个模块、补一组测试、核对文档来源或从不同角度审查同一分支。需求仍在变化、多个子任务会同时修改同一文件，或者工作量很小的时候，不要为了并行而并行。
可以直接在提示词里规定分工。
```text
把当前分支的审查拆给两个 Subagent。
一个只检查行为回归和缺失测试，另一个只检查权限与敏感数据风险。
两边都只读，不要修改文件。等待全部完成后，按严重程度汇总并附文件位置。
```
Codex 也支持把自定义 Agent 定义放在用户或项目的 `.codex/agents/` 目录。自定义 Agent 应只负责一个清楚的角色，并限制修改范围、工具和验证要求。没有必要时可以省略固定模型，让 Codex 按任务选择。
## 修改完成后单独 Review
实现任务完成后，打开 Review 面板或运行 `/review`，让 Codex只看当前差异、行为风险和缺失测试。
```text
审查当前分支相对 main 的差异。
只报告能够由代码、测试或运行路径证明的问题，标明文件和位置。
先不要修改内容。
```
审查和修复分开，可以保留问题出现时的证据。确认哪些发现需要处理后，再开始下一轮修改。
## 交接记录必须区分状态
长任务暂停前，可以在项目中写一份临时 `HANDOFF.md`，或在新的聊天中引用原聊天的技术 ID。交接记录不能替代当前文件和 Git 状态。
一份可用的交接至少要写清当前目标、已经完成的内容、未解决问题、下一步动作和已知风险。状态要分开记录。
```markdown
## 当前状态
- 本地修改：已完成
- 测试：已通过指定命令
- 提交：未创建
- 远端：未推送
- 部署：未开始
- 线上验证：未进行
```
下一次继续时，先读交接，再检查真实状态。
```text
先读 HANDOFF.md，再检查当前文件、Git 状态和最近的验证结果。
指出交接记录与现场不一致的地方，然后给出下一步。
```
## 一套可执行的长任务顺序
1. 在主聊天中确认目标、限制和完成标准。
2. 临时问题放进 Quick Chat，较长的方案分歧放进 Side Chat。
3. 只把独立、边界稳定的工作交给 Subagent。
4. 主聊天整合结果并完成实现和验证。
5. 用独立 Review 检查当前差异。
6. 暂停前写交接，继续时重新核对现场。
这套顺序的价值在于隔离不同种类的上下文。主聊天保留最终决定和项目状态，旁支讨论与并行搜索不会把执行要求淹没。
## 参考资料
- [Codex app commands](https://developers.openai.com/codex/app/commands)
- [Codex IDE commands](https://developers.openai.com/codex/ide/commands)
- [Codex Subagents](https://developers.openai.com/codex/subagents)
- [Codex Developer commands](https://developers.openai.com/codex/developer-commands)
- [Prompting 中的 Steering 与 Queue](https://learn.chatgpt.com/docs/prompting)
### Codex 任务收尾系统，用 Markdown 保存状态、决策与可复用流程
URL: https://codexguide.io/guides/codex-task-closeout-memory-system
这篇文章写给需要长期维护多个项目，已经发现“任务做完了，下一次还要重新解释”的读者。
# Codex 任务收尾系统，用 Markdown 保存状态、决策与可复用流程
> 难度 | 进阶
>
> 类型 | 知识管理与任务交接
## 这篇文章适合谁
这篇文章写给需要长期维护多个项目，已经发现“任务做完了，下一次还要重新解释”的读者。
你会建立一套本地 Markdown 收尾流程。它记录本轮已经证实的状态、选择方案的理由和下次可以复用的步骤，同时把密钥、私人内容和没有证据的推测挡在长期记录之外。
## 聊天摘要不能代替任务状态
普通摘要能说明刚才讨论了什么，却不一定能回答项目现在处于哪个阶段。
本地测试通过、代码已经合并、服务已经部署和公开页面完成验证是四种不同状态。收尾记录应写到证据能够支持的位置，不能提前升级。
例如只运行了本地测试，可以记录测试命令和结果。没有检查远端分支与线上页面时，就保留“未推送”和“未部署”。
## LLM Wiki 提供了一个可借鉴的结构
Andrej Karpathy 在 2026 年 4 月 4 日发布了 LLM Wiki 构想，提出让 Agent 持续维护相互连接的 Markdown 知识库。原始资料、整理后的 Wiki 和规则文件承担不同责任，新材料进入后还要处理来源、矛盾和更新。
这个构想没有规定唯一目录。下面的结构是一套个人实践，用来管理 Codex 任务收尾，不代表 Karpathy、OpenAI 或 Obsidian 的官方方案。
## 用目录区分写入责任
可以先建立一个很小的本地目录。
```text
Codex/
├── AGENTS.md
├── INDEX.md
├── 项目/
├── 工作流/
├── 决策/
└── 用户记忆/
```
`INDEX.md` 只保存入口和关键词，避免每次扫描整个目录。项目记录保存当前可核验状态和下一步；工作流保存能够重复使用的操作顺序；决策记录备选方案、最终选择和重新评估条件；用户记忆只保存稳定偏好与授权边界。
`AGENTS.md` 规定读取顺序、写入位置、敏感信息和冲突处理。项目私有规则放在项目中，个人规则留在用户目录，不要把本机习惯复制进公开仓库。
## 任务结束时走完五步
一次重要任务完成后，按下面顺序收尾。
1. 提取本轮新确认的事实，并记录证据位置。
2. 区分本地、提交、远端、部署和线上验证状态。
3. 判断内容属于项目、工作流、决策或用户记忆。
4. 写入前检查重复、冲突、过时内容和敏感信息。
5. 只更新本轮真正影响到的少量文件。
一次性命令输出、可以直接从代码读取的细节和未验证猜测通常不值得长期保存。记忆负责提供线索，真实项目和外部服务仍要在下一次任务中重新核对。
## 写入前先判断动作
为了避免知识库不断堆叠重复内容，可以给每条候选信息分配一个动作。
| 动作 | 什么时候使用 |
|---|---|
| `ADD` | 当前没有对应记录，需要新建 |
| `UPDATE` | 已有事实发生变化，应更新原记录 |
| `NOOP` | 内容已经存在，不重复写入 |
| `MARK_OUTDATED` | 旧结论失效，但需要保留变化痕迹 |
| `MERGE_REQUIRED` | 多处记录重复或冲突，需要人工合并 |
| `ASK_USER` | 涉及敏感信息或无法判断归属 |
假设项目记录原来写着“功能尚未部署”，新任务只看到公开页面出现了新入口。当前证据只能支持“公开页面可见”。接口是否可用、是否需要登录、后端是否已经切换仍要继续验证。
## 先生成计划，再允许写入
第一次使用这套方法时，不要让 Codex 直接批量更新知识库。先让它生成写入计划。
```text
请为本轮任务做一次记忆收尾，先不要写入文件。
1. 列出本轮新确认的事实和证据来源。
2. 分开记录本地修改、测试、提交、远端、部署和线上验证。
3. 判断每条内容应进入项目、工作流、决策、用户记忆，或不写入。
4. 标记 ADD、UPDATE、NOOP、MARK_OUTDATED、MERGE_REQUIRED 或 ASK_USER。
5. 检查密码、密钥、Cookie、账号信息和私人聊天原文。
6. 列出拟修改文件，等我确认后再执行。
```
审核几次真实任务以后，再把稳定规则写入 `AGENTS.md` 或制作成 Skill。目录和字段应跟着实际问题调整，不需要一开始搭建复杂系统。
## 本地文件仍有隐私边界
文件保存在本地，不代表模型处理过程完全离线。内容是否发送到云端、怎样保存以及谁能访问，取决于产品、账号、插件和连接方式。
长期记录至少遵守下面几条边界。
- 不保存 API Key、Token、Cookie 和密码。
- 不把完整私人聊天或客户资料写进通用记忆。
- 共享项目的事实以项目文档和版本记录为准。
- 删除、发布、费用和账号操作保留人工确认。
- 使用旧记录前重新检查当前文件和外部状态。
## 怎样验证这套系统
选一个刚完成且有 Git 记录的任务，让 Codex只生成收尾计划。逐条检查事实是否有证据、状态是否提前升级、文件归属是否合理，并确认没有敏感信息。
写入后重新打开一个不带聊天上下文的任务，让它先读 `INDEX.md` 和相关项目记录，再检查 Git 与真实文件。如果它能指出旧记录与现场的差异，并从正确位置继续，说明收尾记录已经发挥作用。
## 参考资料
- [Andrej Karpathy 的 LLM Wiki 原始构想](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
- [Codex AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Codex Memories](https://developers.openai.com/codex/memories)
- [Obsidian Create a vault](https://help.obsidian.md/vault)
### Codex 视频工作流，4 个第三方 Skill 的用途、依赖与限制
URL: https://codexguide.io/guides/codex-video-workflow-skills
这篇文章写给希望用 Codex 处理视频生成、素材粗剪、字幕动画和发布前转码的读者。
# Codex 视频工作流，4 个第三方 Skill 的用途、依赖与限制
> 难度 | 进阶
>
> 类型 | 第三方项目观察
>
> 核验日期 | 2026-08-18
## 这篇文章适合谁
这篇文章写给希望用 Codex 处理视频生成、素材粗剪、字幕动画和发布前转码的读者。
文中检查了四个公开仓库的用途、安装方式、依赖、许可证和 Codex 兼容情况。它们可以覆盖一条视频生产链的不同阶段，但 CodexGuide 没有在同一台机器上完成付费生成、粗剪、Remotion 包装和最终导出的端到端实测。因此本文是选型与测试计划，不是“安装后即可自动出片”的保证。
## 四个项目分别解决什么问题
| 阶段 | 项目 | 主要用途 | 重要限制 |
|---|---|---|---|
| 生成 | HiAPI Seedance 2.0 Skill | 文生视频、图生视频并轮询下载结果 | 需要 `HIAPI_API_KEY`，生成会消耗付费额度 |
| 粗剪 | `browser-use/video-use` | 转写素材、找切点、去停顿、加字幕并渲染 | 需要 Python、FFmpeg 和 ElevenLabs API Key |
| 包装 | `remotion-dev/skills` | 指导 Agent 使用 Remotion 编写字幕、动画和模板 | 仍需 Node.js、Remotion 项目和人工预览 |
| 转码 | Digital Samba Video Toolkit | 提供 FFmpeg 等视频处理知识和完整工具包 | 项目以 Claude Code 为主，Codex 迁移脚本标为实验性 |
这四个仓库不是一套由同一团队维护的产品。安装目录、依赖和授权方式各不相同，不能把它们视为一个已经集成好的流水线。
## 用 HiAPI Skill 生成视频
HiAPI Seedance 2.0 Skill 的仓库明确列出 Codex 安装方式，并提供文本生成、首帧图生视频、首尾帧和多模态参考模式。结果可下载时会保存到本地 `outputs/`。
安装命令来自项目 README。
```bash
npx -y github:HiAPIAI/hiapi-seedance-2-0-video-skill --codex
```
执行前需要设置 `HIAPI_API_KEY`。不要把 Key 写进提示词、截图或仓库文件。第一次生成先使用短时长和较低分辨率，确认画面方向后再增加成本。
```text
使用 $hiapi-seedance-2-0-video 生成一段 5 秒竖版测试视频。
先检查配置和费用参数，展示最终请求，不要在我确认前提交付费任务。
生成完成后保留原始返回信息，并把可下载结果保存到 outputs/。
```
截至核验日期，该仓库使用 MIT License，公开元数据显示最近推送时间为 2026-07-21。仓库规模和社区采用量仍较小，使用前应自行检查脚本和 API 请求地址。
## 用 video-use 整理多段素材
`video-use` 面向带有口播、访谈或录屏的多段素材。项目 README 说明，它会结合转写、时间戳和 FFmpeg 完成切点处理、字幕与渲染。
它的安装比普通说明型 Skill 更重。项目要求先阅读 `install.md`，手动路径包含 `uv sync`、FFmpeg，以及用于转写的 ElevenLabs API Key。在线素材下载还可能需要 `yt-dlp`。
```text
检查 https://github.com/browser-use/video-use 的 install.md 和 SKILL.md。
先列出要安装的系统依赖、Python 包、Skill 目录和环境变量。
不要写入全局目录，也不要索取 API Key，等我确认安装计划后再继续。
```
截至核验日期，该仓库使用 MIT License，最近推送时间为 2026-07-01。README 明确提到 Codex，但安装脚本会修改本地环境并接触原始视频，建议先在隔离目录和无敏感信息的短素材上测试。
## 用 Remotion Skills 编写包装层
Remotion 使用 React 生成视频。`remotion-dev/skills` 为 Codex 等 Agent 提供 Remotion 的结构、动画、字幕、多媒体和渲染规则。
```bash
npx skills add remotion-dev/skills
```
Skill 负责让 Agent 遵循 Remotion 的用法，并不会代替审美判断或浏览器预览。每次修改后仍要在 Remotion Studio 中检查文字是否溢出、动画时间是否正确、音画是否同步，再执行最终渲染。
截至核验日期，仓库最近推送时间为 2026-08-14。GitHub 元数据没有识别到仓库级许可证，准备把内容用于商业项目或再分发前，应进一步确认各文件和 Remotion 本身的许可条款。
## FFmpeg 阶段要分清 Skill 与工具包
原稿引用的 Digital Samba Video Toolkit 是一个完整的 Claude Code 视频生产项目，其中包含 FFmpeg、Remotion、配音、图像和云端 GPU 工具。它不是只包装几条 FFmpeg 命令的小型 Codex Skill。
项目提供 `scripts/migrate_to_codex.py`，会把 `.claude/skills/` 和工作流迁入 Codex，并根据 `CLAUDE.md` 生成 `AGENTS.md` 管理区块。项目文档把这条路径标为实验性。
```bash
python3 scripts/migrate_to_codex.py --force
```
这条命令会写入用户 Skill 目录和当前仓库的 `AGENTS.md`，不能在不了解差异时直接运行。只需要压缩、缩放或转格式时，直接审查并执行 FFmpeg 命令通常更简单。
```text
读取 final.mp4 的编码、分辨率、帧率、音轨和文件大小。
先给出 FFmpeg 命令及输出文件名，不覆盖原文件。
目标是 1080×1920，保持比例，不拉伸画面。等我确认后再执行。
```
截至核验日期，该工具包使用 MIT License，最近推送时间为 2026-08-13。项目能力很多，依赖和权限范围也更大，适合愿意维护完整视频工程的读者。
## 推荐的最小测试顺序
不要第一次就把四个项目全部装进常用环境。按当前痛点选择一段开始。
1. 只需要生成镜头时，先审查 HiAPI Skill，使用低成本参数生成一条测试视频。
2. 已有多段口播时，在隔离目录安装 `video-use`，先处理一段可丢弃素材。
3. 需要统一字幕和动画时，新建最小 Remotion 项目并在 Studio 中预览。
4. 发布前只做格式处理时，先用 `ffprobe` 读取源文件，再确认 FFmpeg 命令。
每一步都保留原文件，并把生成、剪辑、包装和导出放在不同目录。这样出现问题时，可以知道失败发生在哪个阶段，也能单独替换其中一个工具。
## 参考资料
- [HiAPI Seedance 2.0 Video Skill](https://github.com/HiAPIAI/hiapi-seedance-2-0-video-skill)
- [browser-use/video-use](https://github.com/browser-use/video-use)
- [Remotion Agent Skills](https://github.com/remotion-dev/skills)
- [Digital Samba Video Toolkit](https://github.com/digitalsamba/claude-code-video-toolkit)
- [Digital Samba 的 Codex 迁移说明](https://github.com/digitalsamba/claude-code-video-toolkit/blob/main/docs/codex.md)
- [Codex Skills 官方文档](https://developers.openai.com/codex/skills)
### Codex 是如何工作的
URL: https://codexguide.io/guides/codex-shi-ru-he-gong-zuo
第一次看 Codex 工作，很容易把它理解成“会写代码的 ChatGPT”。你输入一句话，等一会儿，它就改好了几个文件。
# Codex 是如何工作的
> 难度 基础
>
> 类型 核心概念
## 这篇文章适合谁
第一次看 Codex 工作，很容易把它理解成“会写代码的 ChatGPT”。你输入一句话，等一会儿，它就改好了几个文件。
关键区别藏在中间那段看不见的工作里。Codex 会进入项目，查看代码，调用工具，修改文件，再用测试或构建结果检查改动。理解这套过程以后，你会更清楚任务该怎样描述，也知道什么时候该让它停下来解释，什么时候可以直接执行。
## 先记住这个工作模型
可以先把 Codex 理解成一个能使用开发工具的编码 Agent。模型负责判断下一步该做什么，工具负责把动作落到真实环境中。
一次典型任务大致经过下面几个阶段。
```mermaid
flowchart LR
A[用户提出任务] --> B[读取项目与分析代码]
B --> C[确定方案与执行顺序]
C --> D[修改文件]
D --> E[运行测试或检查]
E --> F{结果符合要求吗}
F -- 否 --> B
F -- 是 --> G[汇报改动与验证结果]
```
这条流程经常要走好几遍。测试失败后，Codex 可能重新读代码，修正判断，再次修改和验证。小任务有时不会单独展示计划，分析和安排依然存在，只是没有专门写成清单。
## 第一步 用户提出任务
Agent 首先要把自然语言转成可执行目标。
例如，你可以这样写。
> 修复登录页面中“发送验证码”按钮点击后没有反应的问题，不要改变登录接口，并补一个相关测试。
这句话交代了故障现象、修改边界和完成标准。Codex 接下来会先寻找登录页面、按钮事件、验证码请求和现有测试，然后再决定改哪里。
如果任务只有“登录坏了，修一下”，Codex 也可以开始调查，但需要探索的范围更大。它可能先检查浏览器报错、最近改动或相关接口。目标越具体，Agent 越容易把时间花在真正的问题上。
## 第二步 分析代码和项目上下文
Codex 并不会在开始任务时把整个仓库一次性塞进模型。真实项目可能有几万甚至几十万个文件，这样做既慢，也会带来大量无关信息。
它通常先查看项目结构和规则，再通过文件名、代码搜索、依赖关系逐步缩小范围。对于刚才的例子，它可能会做下面几件事。
- 读取项目根目录的 `AGENTS.md`、`package.json` 和测试配置；
- 搜索“发送验证码”对应的组件与点击处理函数；
- 查看请求函数、状态管理和相邻测试的写法；
- 用 `git status` 判断工作区是否已有未提交改动。
这个过程叫收集上下文。Codex 需要拿到足够的证据，弄清问题发生在哪里、项目采用什么写法、修改会影响谁，以及该用什么命令验证。单纯增加阅读量没有多少帮助。
Codex 还会受到项目指令和权限限制。比如 `AGENTS.md` 要求使用 `pnpm`、禁止修改生成文件，Agent 应把这些规则带入后续判断。当前工作区里如果已经有你的改动，它也不应随意覆盖。
## 第三步 制定计划
计划用来安排动作，一份好看的待办清单本身没有价值。
修复一个拼写错误时，Codex 可能读完文件就直接修改并检查差异。涉及多个模块、数据库迁移或行为不明确时，它通常需要先确定修改范围和验证顺序。一个合理的内部思路可能是下面这样。
1. 复现或定位按钮事件没有触发的原因。
2. 用项目现有模式修复组件，不改接口契约。
3. 增加一个能覆盖故障场景的测试。
4. 运行聚焦测试，再检查代码差异。
执行中发现原判断不成立，计划也会变化。例如按钮事件已经触发，问题出在表单校验提前返回，那么 Codex 应回到代码证据重新判断，及时放弃第一版计划中的错误路径。
这也是 Agent 和一次性代码生成的重要区别。它能根据工具返回的新信息继续决策。
## 第四步 修改文件
找到原因后，Codex 会通过文件编辑工具把改动写入项目。它可能修改组件、测试或配置，也可能新建文件。模型无法隔空“碰到”硬盘，它发起的是一次次明确的工具调用，例如读取某个路径、应用补丁或运行格式化命令。
好的修改一般有下面几个特点。
- 范围和任务一致，不顺手重构无关代码；
- 遵循仓库已有的命名、组件和测试模式；
- 保留用户现有改动，不把脏工作区恢复成自己的理想状态。
你仍然应该查看最终差异。Codex 能操作文件，不代表每次判断都正确。尤其是公共接口、依赖升级、权限配置和数据迁移，改动本身比聊天中的解释更值得审查。
## 第五步 验证结果
“文件已经改了”还不能算完成。Codex 需要拿出可以观察的证据。
根据项目类型，可以选择下面这些验证方式。
- 运行与改动相关的单元测试或集成测试；
- 执行类型检查、lint 或构建；
- 启动应用，实际点击页面并查看浏览器状态；
- 检查 `git diff`，确认没有混入无关文件；
- 对照任务要求，检查接口和行为是否保持不变。
如果测试失败，Agent 要先分辨失败是否由本次修改引起。相关失败通常需要继续修复；无关的既有失败应该如实报告，不能为了让输出变绿而随便改测试。
验证也有成本。改一个文案没有必要默认跑十几分钟的全量测试，修改共享认证逻辑却不能只看格式检查。合适的做法是先运行最贴近改动的检查，再根据影响范围决定是否扩大验证。
## Codex Agent 实际上在反复做什么
从内部行为看，一次任务可以简化成一个循环。Codex 先观察当前状态，选择下一步动作，读取动作结果，再决定后续动作。
```text
目标
↓
观察 任务、项目规则、文件内容、命令输出
↓
判断 现在缺什么信息，下一步风险是什么
↓
行动 搜索、读取、编辑、运行命令或请求确认
↓
新结果回到“观察”，直到达到完成标准
```
因此，同一句提示词在两个项目中可能产生不同步骤。React 项目和 Django 项目的目录、命令、测试方式不同；即使技术栈一样，仓库规则和当前代码状态也会改变 Agent 的选择。
## Codex 和普通 ChatGPT 对话有什么区别
这里说的“普通 ChatGPT 对话”，指主要通过文字问答获得解释、建议或代码片段的使用方式。ChatGPT 的产品能力还在扩展，某些模式同样可以处理文件或使用工具。因此，更值得关注的是两者面对的工作对象和最终交付方式。
| 对比项 | 普通 ChatGPT 对话 | Codex 任务 |
|---|---|---|
| 主要对象 | 你在对话中提供的文字、图片或附件 | 选定的项目、代码、配置和开发工具 |
| 常见输出 | 解释、建议、示例代码 | 项目中的实际改动和验证记录 |
| 获取上下文 | 主要依赖你主动提供 | 可以按需搜索和读取工作区 |
| 执行方式 | 通常由你把答案复制到项目并运行 | Agent 可以编辑文件、运行命令，再根据结果继续处理 |
| 完成判断 | 回答是否解决了问题 | 代码是否改对、检查是否通过、边界是否遵守 |
举个简单例子。你问普通对话“React 按钮为什么点了没反应”，它可以列出常见原因并给出示例。你把一个项目交给 Codex 并要求修复，它可以找到真实组件，检查事件绑定，修改对应文件，运行项目里的测试，最后告诉你改了什么。
普通对话更适合学习概念、比较方案或讨论尚未落地的想法。目标已经位于某个项目中，并且希望得到可审查的文件改动时，Codex 更合适。
## 为什么 Codex 能操作项目文件
因为你把一个运行环境和一组受控工具交给了它。模型本身并不知道你的电脑里有什么。
在本地模式中，Codex 运行在你的电脑上，并以你选择的项目目录作为工作区。官方文档说明，Codex CLI 可以直接针对本地仓库检查文件、编辑代码，并调用机器上已经安装的工具。在桌面 App 中，本地任务也直接作用于当前项目目录；Worktree 模式仍在本机运行，只是把改动隔离到 Git worktree。Cloud 模式则在配置好的远程环境中执行。
文件访问仍有边界，常见控制来自下面几层。
1. **工作区范围** 任务关联到哪个目录，Codex 就从哪里获取项目上下文。
2. **工具能力** 读取、搜索、编辑和命令执行由具体工具完成，模型只能通过这些入口行动。
3. **沙箱** 沙箱决定哪些路径可读、哪些路径可写，以及网络是否可用。
4. **审批策略** 超出当前权限的操作可以要求用户确认，也可以被配置为直接拒绝。
5. **项目规则** `AGENTS.md` 等指令告诉 Codex 在技术权限允许的范围内，哪些操作仍然不该做。
权限会直接改变 Codex 能做的事。只读模式下，Codex 可以分析代码但不能落盘修改；工作区写入模式通常允许编辑项目文件，访问工作区外路径或网络时可能需要批准。给出更高权限会减少中途确认，也会扩大错误操作的影响范围。
所以，第一次把项目交给 Codex 时，不要用“它能不能操作电脑”来笼统判断风险。应该具体看任务在哪个环境运行、当前允许访问哪些路径，以及什么动作需要审批。
## 一次任务怎样才算真正完成
可以用下面四个问题检查 Codex 的交付。
- 它是否找到了真实原因，有没有停留在表面现象？
- 修改是否只覆盖任务需要的范围？
- 是否运行了与风险相称的验证，并报告实际结果？
- 有没有说明未完成、无法验证或需要人工决定的部分？
Codex 的最后一条消息只是摘要。真正的结果在文件差异、测试输出和运行行为里。把这些证据看明白，比研究它用了多少步更重要。
## 参考资料
- [OpenAI 官方文档 Codex CLI](https://learn.chatgpt.com/docs/codex/cli)
- [OpenAI 官方文档 Codex environments](https://learn.chatgpt.com/docs/environments/modes)
- [OpenAI 官方文档 Agent approvals & security](https://learn.chatgpt.com/docs/agent-approvals-security)
- [OpenAI 官方文档 Sandbox](https://learn.chatgpt.com/docs/sandboxing)
### Codex 安全与风险边界：什么时候该收紧权限
URL: https://codexguide.io/guides/codex-an-quan-yu-feng-xian-bian-jie
如果你还不熟悉 Codex 接收任务和执行命令的方式，可以先读《别再把 Codex 当成“会写代码的 ChatGPT”：一文看懂它到底怎么工作》；已经上手的读者直接进入下面的止损步骤即可。
# 安全与风险边界：到底该不该放手让它碰你的代码
> 测试环境：Windows 11 24H2（build 26100）；Codex CLI 0.147.0；2026-08-20 核验。
如果你还不熟悉 Codex 接收任务和执行命令的方式，可以先读《别再把 Codex 当成“会写代码的 ChatGPT”：一文看懂它到底怎么工作》；已经上手的读者直接进入下面的止损步骤即可。
## 先处理警告，不要和它赌一把
Codex 出现“提示词可能违反使用政策”的错误，或者突然连续弹出异常提醒时，第一反应不该是换一种说法继续轰炸。也不要在警告窗口里急着补充身份证明、公司资料、密钥或完整项目压缩包。警告的成因可能是提示内容、上下文、网络或服务端误判，单凭一条错误信息无法判断是哪一种。
我建议按这个顺序止损：
1. 停止当前会话，不要反复提交同一段被拦截的提示。
2. 如果会话已经混入敏感信息，先记录发生时间和错误原文，再按产品提供的删除入口清理会话；不要为了“证明自己没问题”继续上传更多资料。
3. 检查网络是否稳定，确认没有频繁切换出口、异常代理或共享 IP 的情况。网络检查只能排除一类因素，不能保证解除限制。
4. 重启 Codex，先开一个全新的、内容最小的测试会话。若新会话仍然出现同样的政策错误，停下来走官方支持渠道，不要继续试探边界。
这套处理方法是降低损失的建议，不是“删掉对话就一定解封”的承诺。账号状态、内容审核和风控决定权仍在服务提供方。
## 两种警告不要混为一谈
“Invalid prompt: your prompt was flagged as potentially violating our usage policy”属于内容或风控层面的拒绝。它不等于 Codex 已经执行了危险命令，也不等于账号一定会被封。新开会话有时能绕开异常上下文，但如果提示本身确实触及限制内容，换会话不能替代修改任务目标。
另一类是执行层警告：Codex 要访问工作区外的文件、联网、删除目录，或者需要提高权限。它关注的是“这一步能不能执行”，不是“这段文字是否违规”。这时要看命令、目标路径和影响范围，不能只看一个醒目的“允许”按钮。
图一 OpenAI 官方文档将沙箱描述为技术边界，将审批描述为越界前的停顿机制。来源：OpenAI Developers，2026-08-21 核验。
### 新开会话能解决什么
新开会话的价值，是把可能已经污染的上下文清掉。长对话里如果出现了大量网页内容、代码片段、系统错误或被拦截的提示，后续每次重试都可能继续带上同一段上下文。换到一个空会话，用最小化的非敏感任务验证服务是否恢复，这是合理的排查动作。
但新会话不是“绕过审核”的技巧。下面三种情况不能靠换会话解决：
- 原始任务本身就涉及受限制的内容。
- 任务需要上传密钥、身份证明、客户数据等敏感资料。
- 账号或网络出口已经触发服务端风控。
遇到这些情况，继续换标题、拆分提示、反复提交，只会让排查变得更混乱。保留错误原文和时间，停止试探，转到官方支持流程更稳妥。
## 误删文件的复盘：问题不在临时目录四个字
2026 年 7 月，OpenAI 工程负责人 Thibault Sottiaux 公开回应了少量 GPT-5.6 在 Codex 中意外删除文件的报告。公开转述中反复出现的条件是：运行在 Full access、没有沙箱边界，并且关闭了 Auto-review。最严重的路径错误与 `$HOME` 有关：模型本想把它改成临时工作目录，却在清理时把真正的 home 目录当成了删除目标。
Codex 创建临时文件夹本身并不能解释这起事故。真正需要追问的是两个失败点：删除前没有再次核对目标；临时路径的变量复用让一个本应短命的目录指向了真实用户目录。只要执行器允许无审批地运行破坏性命令，模型一次路径判断错误就有机会变成真实损失。
OpenAI 后续公开提到的改进方向包括：在删除前核验目标、创建新的临时目录、避免复用系统环境变量、加强对高风险删除命令的审核、让 Full access 更难被误开，并用事故回放和专项评测继续检查。公开表述只到“在回放评测中显著减少”，没有承诺以后绝不发生，转述这起事故时这个限定不能省。
图二 OpenAI Windows Sandbox 文档明确提醒，Full access 可能导致非预期的破坏性操作和数据损失。来源：OpenAI Developers，2026-08-21 核验。
这次修复值得关注的地方，是它没有只给模型补一句“请小心删除”。防线被拆到了几个位置：模型收到的开发者指令、临时目录的创建方式、执行器对删除命令的识别、权限模式的默认入口、Auto-review 的拦截，以及针对真实失败轨迹的回放评测和训练。任何一层都可能失效，所以不能把“模型记住了规则”当成唯一保险。
换句话说，安全边界不只属于模型。执行器要能拒绝越界命令，权限系统要让高风险模式显眼，审核器要能发现破坏性动作，评测要持续复现事故，用户还要保留最后的人工检查点。对 Coding Agent 来说，这些部分合在一起才叫 harness。
图三 Agent harness 将模型指令、执行器、沙箱、审批、自动审核和事故回放等环节串成多层防线。AI 生成/教学示意，不代表 Codex 当前界面。
这次复盘说的是官方层面的事故，日常使用中类似的放手代价我也遇到过，记录在《别一上来就让 Codex 改项目，我已经替你踩过坑了》里，可以对照着看。
## 现在该怎么保护自己的文件
把下面几件事当成最低限度的工作习惯：
- 重要项目先提交或打包一个可恢复的版本，再让 Agent 改动。
- 真实账号、生产数据库、客户资料和密钥不要放进一次性试验目录。
- 任务只需要改项目文件时，就把工作范围留在项目目录；遇到权限错误，先缩小任务或补充明确的只读路径，不要直接把权限拉满。
- 任何包含递归删除、覆盖、迁移、发布或外发数据的命令，都要人工看完整命令和完整目标路径。
- 测试通过后仍然查看 `git diff --stat`、`git diff` 和实际运行过的测试。通过只说明某些检查通过，不说明未覆盖的行为没有变化。
### 按四个问题判断风险
图四 判断任务前，先看资产、回退能力、验证方式和影响范围。AI 生成/教学示意，不代表 Codex 当前界面。
1. 它会接触什么：示例代码、个人文件、凭据、客户数据，还是生产资源？
2. 能不能回退：有 Git、备份、事务或可丢弃环境吗？
3. 怎么验证：有聚焦测试、构建、预览和人工复核吗？
4. 出错会怎样：影响一个分支，还是会删除、发送、发布或改变云资源？
四个问题里只要有一个答不上来，就把任务降级为只读分析，或先建立隔离环境。风险要结合资产、回退能力和影响范围来判断，红黄绿标签只能做提示。
## 适合交给 Codex 的任务，也要有边界
代码搜索、只读解释、隔离分支里的小范围修改，以及能运行聚焦测试的修复，通常适合交给 Codex。前提是目标文件明确、变更可回退、结果有人检查。
认证、支付、加密、权限、依赖升级、公共接口、大范围重构、生产 DDL、批量删除和对外发布，都应该保留人工检查点。检查时要看实际差异、命令和目标资源，不能只扫一眼摘要。
如果你还没让 Codex 改过真实项目，可以先从《第一次让 Codex 改项目，我建议你先从这个小任务开始》里的低风险任务练手，再回到上面的边界清单逐条对照。
## Mac 内存问题要单独看
不少用户还会遇到另一种烦恼：Codex Desktop 在 Mac 上运行一段时间后占用越来越高。长会话历史、图片附件、本地工具和子进程都可能增加客户端负担，但这和“误删文件”不是同一个安全事件，也不能用一次安全更新推断内存问题已经解决或必然存在。
目前能确认的是，Codex 会在本地保存会话历史，并提供关闭历史持久化、限制历史文件大小等设置。至于某个版本到底是哪一部分占内存，需要在目标机器上看 Activity Monitor，记录会话长度、附件数量、子进程和重启前后的内存曲线。没有这组数据时，最好写成“待实测的稳定性问题”，不要写成官方已经承认的缺陷。
实用的处理方式很朴素：长任务拆成短会话，减少不必要的图片和整仓库上下文，完成一个阶段就关闭闲置线程；如果内存持续上涨，先保存工作结果、退出并重启客户端，再决定是否提交反馈。这样做解决的是资源占用，不是权限风险，两个问题要分开处理。
## 和下一篇的分工
这篇只回答“为什么要收紧、出现警告怎么止损、哪些动作不能直接放手”。下一篇《权限、沙箱与审批：什么时候放行，什么时候收紧》再回答“权限、沙箱和审批分别控制什么、审批窗口该看哪些字段、如何在可丢弃仓库里验证读写和联网边界”，具体菜单、CLI 参数和 `config.toml` 的用法也留到那一篇。
## 资料来源
- 沙箱、权限、审批和 Windows 隔离机制的描述，以 OpenAI 官方文档为准。
- 文件删除案例的 `$HOME` 细节来自负责人公开表述的媒体转述；原始帖子未能直接核验，以上转述只用于还原事件脉络。
- Mac 客户端内存占用属于用户社区反馈和个人观察，不能与文件删除安全事件混为同一项官方修复；具体内存曲线需要在你自己的版本上实测。
下一篇《权限、沙箱与审批：什么时候放行，什么时候收紧》会把权限、沙箱和审批拆成可操作的配置与检查步骤。
### Codex 权限、沙箱与审批的放行与收紧
URL: https://codexguide.io/guides/codex-quan-xian-sha-xiang-yu-shen-pi
Codex 有时只能读，不能写；有时访问网络或工作区外的文件会停下来询问。遇到这些提示，先分清权限、沙箱和审批，再决定是否放行。
# Codex 权限、沙箱与审批的放行与收紧
> 测试环境：Windows 11 24H2（构建 26100）；Codex Desktop 26.814.5517.0；Codex CLI 0.147.0；2026-08-21 核验。
Codex 有时只能读，不能写；有时访问网络或工作区外的文件会停下来询问。遇到这些提示，先分清权限、沙箱和审批，再决定是否放行。
本文只讨论日常任务中的判断方法。涉及具体配置文件和团队级策略时，应按所在环境的安全要求单独处理。
如果你还不熟悉 Codex 接收任务和执行命令的方式，可以先阅读“Codex 是如何工作的”；已经遇到审批提示的读者可以直接进入正文。
## 正文
### 1. 先把三个概念分开
遇到权限提示时，先别急着点允许。权限、沙箱和审批解决的是三件不同的事。
权限说明当前任务可以做什么。沙箱划出文件、命令和网络能够触达的范围。审批则处理越过当前范围的动作，决定这一步要不要交给人确认。
*图一 OpenAI 官方文档对 Sandbox mode 与 Approval policy 的并列说明。它用于核对概念边界，不代表某个具体桌面端会显示完全相同的文案。*
可以把它们放进同一个任务里理解。读取项目文件通常只需要访问当前工作区。修改文件会改变磁盘内容，安装依赖还可能访问网络。任务越过当前边界时，审批才会出现。
在 Windows 上使用 VS Code 的读者，经常会遇到另一个选择：是否把项目放进 WSL，再用 VS Code 的 Remote - WSL 连接。WSL 能提供更接近 Linux 的工具链，某些 Node、Python 或 shell 项目也会因此少碰到路径和脚本兼容问题。不过，WSL 不是权限开关，更不是把 Windows 文件和网络自动变成安全区。连接到 WSL 后，仍然要确认 Codex 当前看到的工作区、挂载目录和网络边界；不要因为“现在是在 Linux 终端里”就直接给出全盘访问或长期免审批。
*图二 油画风格教学示意图。外层表示网络与工作区边界，中间表示沙箱范围，右侧审批闸门表示需要人工确认的动作。该图为 AI 生成示意，不代表 Codex 当前界面。*
### 2. 常见动作分别需要什么能力
读取工作区文件和在工作区内运行检查，通常属于低风险动作。新建文件、修改代码或执行构建，会改变工作区状态，需要确认目标范围。安装依赖、调用外部服务或读取工作区之外的路径，则多了一层网络或边界风险。
判断时看动作本身，不要只看命令名字。同一个脚本，在测试仓库里运行和在生产目录里运行，风险完全不同。
*图三 OpenAI 官方 Sandbox 页面，说明沙箱如何限制代理可触达的文件、命令和网络边界。*
官方文档说明了沙箱的边界，但桌面端、CLI 和 IDE 扩展的菜单名称可能不同。本文的截图用于解释概念，具体选项仍应以当前客户端显示为准。
除了简单的档位开关，官方还在完善更细的权限档案（permission profiles，目前处于 Beta，可能继续变化）。它把命令能读写哪些文件、能访问哪些网络目标组合成一个命名策略，只给当前任务够用的访问，而不是把整台机器敞开。官方文档自己的定位也是最小权限。具体配置本文不展开，先知道有这条路即可。
*图四 OpenAI 官方 Permissions 文档：权限档案把文件读写规则和网络访问规则组合成命名策略，目前处于 Beta。档位名称和默认值可能随版本调整，以当前客户端显示为准。*
### 3. “允许命令”和“脱离沙箱”不是一回事
Windows Codex App 用户有时会发现，`rg`、只读的 `git status` 也会触发审批；反过来，某些允许规则又可能让命令在沙箱边界之外运行。这两种现象看起来矛盾，其实是在问不同的问题：前者是“这条命令现在能不能执行”，后者是“它执行时是否还受当前沙箱限制”。
所以不建议把所有看起来安全的命令都加入白名单。先看命令的完整参数、当前工作目录和实际访问路径，再确认允许规则是否同时改变了沙箱或网络边界。GitHub Issue [#26108](https://github.com/openai/codex/issues/26108) 记录了 Windows 场景下这类边界混淆，适合作为排查审批异常的背景材料。
如果你的环境支持在 `~/.codex/AGENTS.md` 中声明团队约定，可以把“低影响改动直接执行，高影响改动先审查批准”写成任务规则。例如，读取文件、运行已有的格式检查、查看 `git diff` 可以归入低影响；删除文件、改生产配置、写入真实数据、上传外部服务则归入高影响。这个文件只能表达协作约定，不能替代沙箱、操作系统权限或审批策略，实际生效范围仍以当前客户端和配置为准。
### 4. 不同权限档位，先看它们改变了什么
Codex App 的文案会随版本变化。GitHub Issue [#29452](https://github.com/openai/codex/issues/29452) 讨论过当前界面常见的四种说法，可以先按下面的含义理解。
| 界面文案 | 更接近的含义 | 使用时要问自己 |
| --- | --- | --- |
| Ask for approval | 每次越界动作交给人确认 | 我能否读懂这一次的完整命令和目标？ |
| Approve for me | 由系统按既定规则自动处理审批 | 规则是否足够窄，是否会覆盖后续命令？ |
| Full access | 放开更多文件、命令或网络边界 | 这是不是一次性给了超出任务所需的范围？ |
| Custom (config.toml) | 使用配置文件自定义策略 | 配置是否经过 review，能否回退和审计？ |
这张表是阅读 UI 的辅助，不是官方稳定的等级定义。审批弹窗通常会给出“允许一次”“以后允许以某个前缀开头的命令”“拒绝”等选择。OpenAI 的[审批弹窗示例](https://openai.com/index/unlocking-the-codex-harness/)展示了这种差异。第二个选项不会让所有命令都变得安全，它只是把一个命令前缀加入后续自动处理范围，仍要检查前缀是否过宽。
*图五 用户提供的 Codex 命令审批弹窗。它同时展示了单次允许、按命令前缀长期允许和拒绝，实际文案可能因客户端版本而不同。*
*图六 用户提供的 OpenAI 官方审批示例截图。它适合说明“允许一次”和“以后允许类似命令”的范围差异，不应被理解为 Full access。*
*图七 用户提供的 Codex 权限菜单截图。菜单中的“请求批准”“帮助我批准”和“完全访问”是当前界面文案，阅读时应把它们映射回审批、自动处理和边界范围三个问题。*
### 5. 审批窗口里应该看什么
审批出现时，按下面的顺序读一遍。
先看它准备做什么，是读取、写入、删除、联网，还是调用外部服务。再看完整目标，包括文件路径、命令参数和域名。然后问一句，这一步和当前任务有什么关系。
最后检查回退办法。目标是否在测试仓库里，是否有 Git 或备份，是否会碰到账号、密钥、客户数据或生产环境。如果只是为了完成一个小动作，却要求打开更大的权限，先停下来改写任务范围。
下面是在可丢弃测试仓库里的一次真实审批。任务是新建一个明确命名的文本文件，Codex 在写入前先列出了准备执行的动作、完整目标路径和这一步需要审批的原因，然后停下来等待批准。按上面的顺序读一遍：动作是写入，目标是测试仓库里的单个文件，和当前任务直接相关，写完还能删除。这类请求可以放心放行。
*图八 本机可丢弃测试仓库中的写入审批（Codex Desktop 实测）。画面中 Codex 先列出动作、完整路径和审批原因，再等待人工确认；目标路径只指向测试目录，不含账号或敏感信息。*
### 6. 哪些情况可以放行
可以放行的请求通常有几个共同点。动作直接服务于当前任务，目标路径或域名写得清楚，影响范围容易检查，结果也能通过 Git 或备份回退。
例如，在可丢弃测试仓库里创建一个明确命名的测试文件，审批内容包含完整路径，写入完成后还能删除或回退，这类请求比较容易判断。放行前仍要确认命令没有夹带额外的删除、上传或全盘扫描动作。
如果你还没有在真实项目里放过权，可以先照着《第一次让 Codex 改项目，我建议你先从这个小任务开始》做一次低风险练习，再回来对照上面的放行条件。
### 7. 哪些情况应该收紧或拒绝
理由说不清楚、目标路径过于宽泛、包含批量删除或不可逆操作时，应收紧权限。生产数据库、真实客户数据、密钥和账号权限也不适合在普通任务里直接放行。
工作区已经有重要改动，却没有隔离分支、备份或回退方案时，也应先停下来。拒绝审批不是把任务丢掉。可以让 Codex 先解释方案、列出将要执行的命令，或者给出只读分析，让人确认后再决定下一步。
放手之后收不回来的具体代价，《别一上来就让 Codex 改项目，我已经替你踩过坑了》里有完整记录，可以对照着看。
还有一种风险不在单次审批里。审批连续弹出时，人容易进入机械点允许的状态，不再逐条读内容。发现自己开始不经看就点，先暂停任务。“不再询问”或“始终允许”一类的选项（名称以当前客户端为准），只留给可丢弃环境和明确重复的窄动作，不要在真实项目里图省事常开。
审批太多时，官方提供了自动审阅（Auto-review）。越过沙箱边界的审批可以交给单独的审阅代理处理。主代理仍在同一个沙箱里，受同样的审批策略以及网络、文件限制，变化的只是由谁来审。只有审批处于交互状态时它才介入。自动审阅用于减少重复确认，不会扩大权限。
*图九 OpenAI 官方 Auto-review 文档：自动审阅只改变越界请求的审阅者，沙箱边界、审批策略和网络与文件限制保持不变。*
### 8. 用最小权限完成一次真实任务
一个稳妥的顺序是从只读分析开始。先让 Codex 说明将检查哪些文件，再在确实需要修改时开放工作区内写入。安装依赖或访问外部服务时，只为这一步申请网络权限，并确认域名和命令参数。
任务结束后，把权限收回到日常需要的范围。高权限扩大的是可执行范围，不会让答案自动变得更准确。权限越大，人工检查就越不能省。
## 最后检查这五件事
看到审批请求时，可以按这五个问题快速过一遍。
1. Codex 准备执行什么动作，是读取、写入、删除还是联网。
2. 完整目标在哪里，路径、命令参数和域名是否写清楚。
3. 这一步和当前任务有什么关系，能不能换成只读分析或更窄的权限。
4. 结果是否可回退，是否会碰到生产数据、客户信息、密钥或账号权限。
5. 任务结束后，是否可以把权限收回到日常需要的范围。
只要其中一项说不清楚，就先拒绝或暂停。让 Codex 解释方案、列出命令，再决定下一步，通常比一次性打开最大权限更容易检查。
本文没有展开具体配置文件和团队级策略。涉及生产数据、真实账号或无法回退的操作时，应先让负责人确认权限范围和回滚路径。
### Codex 从目录到入口：找到真正需要修改的代码
URL: https://codexguide.io/guides/codex-cong-mu-lu-dao-ru-kou
拿到一个需求，最费时间的往往不是改代码，而是回答一个问题：真正需要动的文件是哪几个。范围圈大了，Codex 会在无关目录里反复翻找；范围圈错了，改完才发现入口在别处。
# 别再让 Codex 全仓库乱翻了：先找到真正需要修改的代码
> 配图采集环境：macOS 15.7.5（Build 24G624）；Codex/ChatGPT App 26.721.41059；2026-08-21 核验。Codex 实操部分在 Windows PowerShell 环境完成，正文会单独说明。
## 真正需要动的文件是哪几个
拿到一个需求，最费时间的往往不是改代码，而是回答一个问题：真正需要动的文件是哪几个。范围圈大了，Codex 会在无关目录里反复翻找；范围圈错了，改完才发现入口在别处。
这篇文章我用两种方式各走了一遍完整的入口追踪。先在本机用只读命令手动追一次，再把同样的问题交给 Codex 做一次只读调查。两次都停在应用补丁之前，重点看每一步排除了什么、留下了什么证据。
> 图一 从整个仓库出发，逐层排除无关目录，最后落在真正需要修改的文件上。
如果你还没让 Codex 改过项目，建议先看《别一上来就让 Codex 改项目，我已经替你踩过坑了》，再回来对照这里的调查步骤。
## 先确认仓库状态和目录边界
入口追踪的第一步不是搜索关键词，而是确认自己站在哪里。我固定先跑两条只读命令：
```bash
git status --short --branch
rg --files
```
第一条确认当前分支和未提交改动，避免把别人留下的现场误当成调查结论。第二条列出文件全貌，先建立“这个仓库里有什么”的边界感，再决定往哪里挖。
我用本机一个练习用的订单管理小项目做了第一次演示。需求是“修复订单列表金额偶尔显示为 NaN”，任务是确认真正需要继续编辑的最小文件集。
> 图二 本机只读调查记录：先看分支状态，再用 `rg --files` 和 `rg -n "NaN|formatAmount"` 圈出入口和最小改动范围。
这次调查锁定了四类入口：页面入口是 `src/pages/OrderList.vue`，数据入口是 `src/api/orders.js`，格式化入口是 `src/utils/format.js`，测试入口是 `tests/orders.spec.js`。最后得出的最小改动范围只有 `format.js` 里的金额格式化函数和它的测试，其他页面、路由和构建配置一律不碰。
注意这个顺序：先有目录边界，再有入口判断，最后才有改动范围。跳过前两步直接改文件，是范围失控最常见的原因。
## 从需求里的词开始搜索
确认边界之后，搜索词不要自己造，直接从需求里取。页面名、接口名、报错文本、业务术语，这些词在代码里往往有唯一或接近唯一的命中。
为了用一个公开仓库演示，我选了 GitHub 上的 `githubtraining/hellogitworld`，假设需求是“修复 plus 计算结果的显示问题”。只读查看，不执行任何修改。
> 图三 公开示例仓库的静态入口追踪：`src/Main.groovy` 第 9～14 行依次调用 square、divide、subtract、sum，沿 `import static` 找到 `src/Sum.groovy` 的实现。
静态追踪的顺序是：先找到程序入口 `src/Main.groovy`，再沿 `import static Sum.sum` 这样的符号引用找到实现文件，最后用一条命令复核：
```bash
rg -n 'println|static (int|void)|import static' src
```
这条命令同时命中输出语句、方法定义和符号引用，一次就能把“入口在哪、实现者有谁”对上。
## 把“暂不相关”也写下来
圈定范围时，排除项和候选文件同样重要。只写“要改什么”，下次复查时无法判断某个文件是没看过，还是看过之后排除了。
> 图四 建议先读的文件、关联验证命令和暂不相关项都留痕；结论停在应用补丁之前。
这份记录里，`src/Division.groovy` 和 `src/Square.groovy` 被明确标注为“与 plus 逻辑无关”，`build.gradle` 标注为“本次不改依赖”。关联验证用 `rg -n 'sum|plus|println' src README.txt` 和 `git status --short` 两条，确认调查前后工作区保持干净。
最终的最小候选文件只有 `src/Main.groovy` 和 `src/Sum.groovy`。范围能收得这么小，靠的不是一次精准搜索，而是每一步都把排除理由写了下来。
## 把同一个问题交给 Codex
手动流程走完，我把一个同类需求交给 Codex 做只读调查。测试项目有 `src`、`test`、`notes` 三个顶层目录，需求写在 `notes/需求说明.md` 里：`Sum.add(2, 3)` 保持返回整数 5，`Report.render(5)` 返回字符串 `"5"`，但实际输出多了一个 `debug-sum=` 前缀。
我给 Codex 的指令是：先只读调查，不要改文件、不要装依赖、不要提交；从仓库状态、目录结构和关键词搜索开始，逐步找出真正相关的入口；每一步说明查了什么、排除了什么、下一步为什么查；证据不够就明说还缺什么，不要猜。
> 图五 Codex 的只读调查结果：仓库状态、入口定位、关键词搜索与排除、运行环境核对，全程未修改文件。
有几个细节值得单独说。
Codex 先确认仓库在 `main` 分支、工作区干净，再读 README 确认 `src/Main.groovy` 是程序入口。搜索阶段 `rg` 在当前环境启动失败，它没有卡住，改用 PowerShell 文本搜索和 `git grep` 继续，把“加法、结果、显示、`Sum.add`、`Report.render`、`debug-sum`”都搜了一遍。
搜索结论很干脆：`Sum.add` 只有一个生产调用点，在 `Main.main` 第 5 行；`src/Sum.groovy` 第 2 行的实现就是 `left + right`，和需求一致，加法逻辑被证据排除；`src/Report.groovy` 第 3 行拼接了 `"debug-sum=${value}"`，这才是显示错误的直接原因。它同时注意到测试 `test/SumTest.groovy` 第 2 行已经写明了期望行为 `Report.render(5) == "5"`。
最后它还核对了运行环境：找到了 Java，没找到 `groovy` 命令，所以没有执行测试，并明确写出“静态证据已经足够定位问题，但运行时验证仍缺失”。环境不够时不硬跑、也不假装跑过，这正是只读调查该有的边界感。
## 最小改动文件集：让结论分三栏
调查完成后，我追问了一步：给出最小改动文件集，只列真正需要修改的文件和理由，同时列出关联测试、配置和调用方证据，按“确认需要改、只需要查看、当前没有证据不应该改”分成三栏，不执行修改，也不生成补丁。
> 图六 三栏分类后的结论：最小改动文件集只剩 `src/Report.groovy`，并附完整证据链。
分类之后，调用方 `Main.main` 归入“只需要查看”，它只是 `println Report.render(Sum.add(left, right))` 的组装者，自身没有错误证据；`Sum.groovy` 归入“不应该改”，需求要求它继续返回整数 5；`notes/需求说明.md` 是验收依据，不是实现文件。最小改动文件集最终只剩一个 `src/Report.groovy`。
底部的证据链把整条路径写了出来：`Main.main` → `Sum.add(left, right)`（计算正确）→ `Report.render(result)`（添加了错误的 `debug-sum=` 前缀）→ `println`（输出错误结果）。这样的结论不需要信任，可以直接核对。
如果你希望 Codex 每次进项目都先读这类规则，比如“先只读调查再动手”，可以把稳定的要求写进项目规则文件，具体做法见《别再重复提醒 Codex：用 AGENTS.md 让它读项目先读规则》。
## 入口不唯一时怎么办
有些需求会命中多个入口，比如同一个接口同时被页面和定时任务调用。这时不要急着二选一，先做三件事：
1. 把每个入口的调用方列全，确认它们是同一条链路还是互相独立。
2. 看测试覆盖在哪一侧，有测试的一侧优先作为修改点。
3. 仍然无法区分时，把两个入口和各自证据交给需求方确认，不要替业务做决定。
入口追踪的终点不是“找到一个文件”，而是“找到能被证据支撑的最小文件集”。证据不够时，继续查，或者停下来问。
## 小结
完整流程回顾一遍：先用 `git status` 和 `rg --files` 确认仓库状态和目录边界；再从需求原文取词搜索，沿符号引用追到真实入口；排除项和候选文件一起留痕；最后把结论分成“需要改、只需看、不应改”三栏，停在应用补丁之前。
这套顺序手动跑得通，交给 Codex 也跑得通。差别只在于，手动流程练的是你自己的判断，Codex 流程省的是你的时间，两者的验收标准是同一套。
第一次让 Codex 参与真实项目时，建议就从这种只读调查任务开始，具体理由可以看《第一次让 Codex 改项目，我建议你先从这个小任务开始》。
这套入口追踪流程适合在真实项目中反复练习：先调查、再收敛范围，最后才决定是否修改。
### 给 Codex 多大上下文才够用：三组实验的结果
URL: https://codexguide.io/guides/codex-shang-xia-wen-gei-duo-shao
用 Codex 处理任务时，上下文给多少，直接决定它先做什么。给少了，它反复追问；给多了，它要在噪声里翻找目标；给到刚好，它能直接定位问题。
# 给 Codex 喂上下文，喂多少才算够？我用三组实验测出来了
> 配图采集环境：macOS 15.7.5（Build 24G624）；Codex/ChatGPT App 26.721.41059；2026-08-21 核验。Codex 三组实验在 Windows 环境完成，正文会单独说明。
## 上下文给多少，决定它先做什么
用 Codex 处理任务时，上下文给多少，直接决定它先做什么。给少了，它反复追问；给多了，它要在噪声里翻找目标；给到刚好，它能直接定位问题。
为了弄清“刚好”是多少，我用同一个任务设计了三组输入：信息不足、信息过量和最小充分上下文，分别交给 Codex 处理，对比它的调查路线、追问次数和最终判断。这篇文章是三组真实实验的记录。
> 图一 上下文不足、过量和最小充分三种输入，对应三种完全不同的任务开局。
## 三种输入长什么样
实验任务是一个公开示例问题：修复加法结果的显示错误。三组输入的差异只在信息量，任务本身完全相同。
> 图二 三组输入的结构对照：A 组缺关键信息，B 组把仓库整个倒进去，C 组只给目标、范围、证据和验收。
A 组只说“帮我修一下页面问题”，缺目标路由、复现步骤、错误证据和验收标准，预期信号是 Codex 必须先追问，不能直接修改。B 组把整个仓库、历史日志、无关截图和过期讨论全部附上，风险是调查噪声增大，冲突信息掩盖当前目标。C 组给出明确目标、检查范围、复现证据、约束条件和验收方式。
这里先纠正一个常见误解：模型的上下文窗口上限不是推荐输入量。窗口能装下，不等于装进去有帮助。B 组那种“反正都给它”的做法，恰恰是实验里噪声最大的一组。
## 第一组：信息不足，Codex 会怎么做
A 组输入只有一句话加一个目录线索：修复加法结果显示错误的问题，目前只知道项目目录里有一个 `src` 文件夹。我同时要求它先告诉我还缺什么，不要改文件。
> 图三 信息不足时，Codex 用 11 秒列出了还缺的关键信息，没有修改任何文件。
Codex 没有猜，而是列出五类缺失信息：哪个文件或页面出现问题、如何复现、当前显示结果与期望结果、项目的技术栈和启动/测试命令、是否有相关报错或已有测试。最后还主动提出，如果不清楚文件位置，它可以先只读检查 `src`。
这个反应是正确的开局。信息不足时，可靠的行为是追问和提议只读调查，而不是直接动手。如果你的任务描述只有一句话，看到它开始大范围修改，反而应该停下来。
## 第二组：信息过量，噪声从哪来
B 组输入是另一个极端：项目目录、所有 README、完整 Git diff、最近 20 条提交记录、全部测试日志和所有配置文件，任务不变，让它先判断哪些信息真正相关。
> 图四 面对过量材料，Codex 先按相关性把信息分成“真正相关”和“大概率是噪声”两类。
Codex 把 `src` 中负责加法计算和结果渲染的代码、复现输入、相关测试和涉及这些代码的 Git diff 列为相关；把无关的 README、不涉及相关文件的 diff、无关提交和通用配置归为噪声。它还特别指出两点：项目目录和完整配置只能用于定位环境，不能直接说明问题原因；完整 Git diff 还要区分用户已有改动和本任务相关改动，不能整体当作修复依据。
这组实验说明，过量上下文不会直接让结果出错，但会把第一轮时间花在筛选上，而且噪声里的冲突信息（比如过期讨论里的旧结论）随时可能带偏判断。信息多不等于信息足。
## 第三组：最小充分上下文
C 组输入只有五样东西：目标（修复加法结果显示错误）、相关文件（`src/Main.groovy`、`src/Sum.groovy`、`README.txt`）、已知证据（`Sum.groovy` 返回两个整数之和，当前输出与预期不一致）、范围（只读检查这些文件和相关测试，不改文件）、验收（指出最可能的问题、还需要确认的证据和下一步最小检查范围）。
> 图五 最小充分输入下，Codex 直接把问题定位到 `src/Report.groovy`，并列出仍需确认的证据。
这一轮 Codex 没有追问，直接给出判断：最可能的问题在 `src/Report.groovy`，不是加法计算。`Sum.add(2, 3)` 正确返回整数 5，`Report.render(5)` 当前返回 `"debug-sum=5"`，测试 `test/SumTest.groovy` 期望 `"5"`，当前断言会失败。
两个细节值得注意。一是它列出了仍需确认的证据：实际执行的是哪个测试入口、运行时是否真的观察到 `debug-sum=5`、是否有未说明的输出格式要求。定位到结论不等于跳过验证。二是它发现一个输入错误：我写的相关文件是 `README.txt`，目录里实际只有 `README.md`，它在补充说明里纠正了这一点。给对范围，它不仅能定位问题，还能反过来校正你的输入。
如果你还不确定什么样的任务适合先让 Codex 只读检查，可以对照《第一次让 Codex 改项目，我建议你先从这个小任务开始》里的任务尺度。
## 三组结果放在一起
三轮跑完，我让 Codex 把结果整理成对照表，并明确要求：不要把模型上下文上限写成推荐输入量。
> 图六 三组输入的追问次数、调查范围、噪声和判断稳定性对照。
对照结果很直观。A 组追问 1 次，调查范围是“尚未检查代码”，判断不稳定，缺的是复现步骤、当前结果、期望结果和允许检查的目录。B 组追问 0 次，但第一轮时间花在按相关性筛选信息上，出现大量无关上下文，判断需要先排除噪声。C 组追问 0 次，调查只读覆盖相关源码、调用方、格式化逻辑和测试，基本没有噪声，最终判断稳定。
最小充分信息的核心，Codex 总结为六条：明确目标；指出相关文件或允许检查的范围；给出一组可复现输入；说明当前结果和期望结果；提供相关测试或验收条件；如需执行验证，提供运行命令或测试入口。
## 可以直接复制的模板
实验最后产出了一个可直接复制的最小充分上下文模板。
> 图七 模板包含目标、相关范围、复现、当前结果、期望结果、已知证据、验收条件和约束八个部分。
模板原文如下，把方括号换成你的任务信息即可：
```text
目标：
修复【功能/页面】中的【具体问题】。
相关范围：
只检查【文件/目录/测试文件】。
未经确认不要修改其他文件。
复现：
使用输入【例如：2 和 3】，
执行【命令/操作】。
当前结果：
【实际输出或行为】
期望结果：
【应有输出或行为】
已知证据：
【已确认的计算结果、报错、失败断言或截图说明】
验收条件：
- 【条件 1】
- 【条件 2】
约束：
先只读分析，不修改文件；先报告最可能原因、证据和最小修复范围。
```
实际使用时不用机械填满每一项。没有报错日志就不写，但“目标、范围、当前结果、期望结果”这四项几乎总是必须的——它们正是 A 组缺失、导致追问的那部分。
## 分轮补充，而不是一次倒完
如果一开始给不齐最小充分上下文，也不用把整个仓库倒进去补救。更好的做法是分轮补充：第一轮给目标和范围，看 Codex 追问什么；第二轮只补它追问的内容；它不再追问、开始给出可核对的事实时，信息基本就够了。
停止继续堆叠信息的信号有三个：它的提问从“缺信息”变成“确认理解”；它给出的下一步是可执行的检查而不是继续索要材料；它开始区分事实、推断和待确认项。出现这些信号，再往上堆材料只会增加噪声。
这类“先调查、后执行”的节奏，和《别一上来就让 Codex 改项目，我已经替你踩过坑了》里讲的是同一个原则：让结论跑在修改前面。
## 小结
三组实验的结论可以压成一句话：上下文的质量按“够不够定位问题”衡量，不按字数衡量。不足时 Codex 会追问，这是正常信号；过量时它先筛噪声，冲突信息可能带偏判断；最小充分输入是目标、范围、复现、当前结果、期望结果、证据、验收和约束这八项的按需组合。
下次给 Codex 派任务前，可以先对照模板检查一遍输入，缺的补上，多的删掉。
这套模板适合在任务开始前快速检查输入质量：缺信息时分轮补充，信息足够后就停止继续堆叠。
### Codex 只读调查：先把项目摸清楚再改代码
URL: https://codexguide.io/guides/codex-zhi-du-diao-cha-xian-ba-xiang-mu-mo-qing-chu-zai-gai-dai-ma
面对复杂或高风险的任务，直接让 Codex 动手是最贵的做法。改错了要回滚，改多了要排查，而它本来可以先只做一件事：把项目摸清楚，把证据交给你，再由你决定改不改。
# Codex 只读调查：先把项目摸清楚再改代码
> 配图采集环境：macOS 15.7.5（Build 24G624）；Codex/ChatGPT App 26.721.41059；2026-08-21 核验。Codex 实操部分在 Windows 环境完成，正文会单独说明。
## 先摸清项目，再决定改不改
面对复杂或高风险的任务，直接让 Codex 动手是最贵的做法。改错了要回滚，改多了要排查，而它本来可以先只做一件事：把项目摸清楚，把证据交给你，再由你决定改不改。
这篇文章我把一次完整的只读调查走了两遍：先在本机用只读命令手动做一遍，再把同一个调查框架交给 Codex 执行。两遍都停在批准修改之前，并且用 Git 状态证明调查期间没有产生任何改动。
> 图一 只读调查的核心：先把事实、推断和未知项分开，再决定要不要允许修改。
如果你还没区分过“让 Codex 调查”和“让 Codex 修改”，可以先阅读“Codex 从目录到入口”，再回到本文的调查步骤。
## 哪些任务适合先调查
不是所有任务都需要只读调查。改一行文案、加一个日志，直接做更快。值得先调查的通常是这几类：
- 涉及多个目录或模块，影响范围一眼看不全。
- 仓库里有历史代码、生成代码或你不熟悉的依赖。
- 失败代价高，比如动数据库结构、构建配置或线上脚本。
- 你对需求的理解本身还没被验证，改下去可能方向就是错的。
判断标准很简单：如果“改错了再退回来”的代价比“先花几分钟调查”高，就先调查。
## 先把边界写清楚
只读调查的第一步是把“不许做什么”写明白。我为本机演示整理的边界如下：允许执行的只有 `git status --short --branch`、`git log --oneline --max-count=5`、`rg --files`、`rg -n` 和 `find` 这类只读命令；明确不执行的包括切换分支、同步 main、stash/merge/rebase/reset、修改演示项目以外的目录，以及提交、推送这类状态变更。
> 图二 调查前先把允许执行的动作和明确不执行的动作逐条写下，结论也注明当前真实状态。
注意边界不只在命令层面，也包括不伪造进度。这次调查如实记录了演示项目的订单模块还没有测试覆盖，真实状态是“待补测试”。只读调查要把看到的内容完整写下来，包括那些说明“还没做完”的证据。
## 调查报告要分四栏
调查最大的浪费，是产出一篇读起来很顺、但分不清哪些是事实的总结。我要求的报告格式固定分四栏：事实、推断、未知项、建议步骤。
> 图三 公开示例仓库的只读调查报告：事实都有命令依据，推断标注依据，未知项不猜，建议步骤停在批准修改之前。
这份针对公开示例仓库的报告里，事实栏的每一条都能对上证据：`src/Main.groovy` 静态导入 `Sum.sum`，最后一行调用 `sum(programmingPoints, 3)`，`src/Sum.groovy` 定义 `static int sum(int val1, val2)`，调查前后 `git status --short` 均无输出。推断栏只写“plus 显示问题的直接候选是 Main.groovy 的输出行或 Sum.groovy 的返回值”，并注明 Division、Square、Subtract 暂不相关。未知栏承认两件事：尚未执行构建或运行命令，尚未确认用户期望的最终文案。建议先让需求方确认复现输出和期望值，再安排修改。
这个顺序是有意为之的。只读调查的产出是一份能支持下一位维护者决策的报告，修改补丁要留到后续任务。
## 把调查框架交给 Codex
手动流程验证过之后，我把同一个框架写成指令交给 Codex，调查对象是一个涉及 `src`、`test`、`notes` 多个目录的测试项目。指令里写死四条禁令：不修改任何文件，不安装依赖，不运行删除、覆盖、迁移或其他破坏性命令，不提交、不切换分支。调查顺序固定为六步：当前 Git 状态、项目目录和技术栈、需求相关入口、约束和风险、未知项、建议的下一步。输出必须分成四部分：已确认事实、基于证据的推断、仍需人工确认的未知项、可以执行但尚未执行的修改计划，每一项都附文件路径、命令结果或其他证据。
> 图四 Codex 的只读调查报告开头：Git 状态和项目结构逐条附命令与结果，耗时 1 分 2 秒。
报告的事实栏完全按证据组织。Git 状态部分写明用了 `git status --branch --short`，结果是 `## main`，`git status --porcelain=v1` 无输出，说明工作区和暂存区干净；当前提交是 `c574445`，`git remote -v` 无输出，未执行切换、提交、推送或拉取。项目结构部分列出 `README.md`、`notes/需求说明.md`、`src/Main.groovy`、`src/Sum.groovy`、`src/Report.groovy`、`test/SumTest.groovy`，并根据 `.groovy` 文件和 README 判断这是 Groovy 示例项目，同时注明没有发现 `package.json`、Gradle/Maven 配置、构建脚本或 CI 配置。
每一条事实都自带“怎么知道的”。这样的报告你可以抽查任意一行，而不是只能整体信任或整体怀疑。
如果你希望这类禁令和调查顺序不用每次重写，可以把稳定的部分沉淀成项目规则，具体写法见《别再重复提醒 Codex：用 AGENTS.md 让它读项目先读规则》。
## 调查结束后，先证明它没动过
只读调查最容易被跳过的一步，是验收“只读”本身。报告写得再规矩，也可能有意外改动混在里面。我的做法是让 Codex 在调查结束后再次执行 `git status --short`，和调查开始前的状态并列对比：两次一致就明确说明“调查期间没有发现新增或意外修改”，不一致就逐项解释变化来源，不要自行清理。
> 图五 调查开始前和结束后的 Git 状态对照：两次均无文件变更，确认没有新增或意外修改。
这次验收的结果是两次输出一致，调查期间没有新增或意外修改。指令里特意写了“不要自行清理”。如果发现意外改动，应报告来源并保留现场，才能知道调查过程碰过什么。
这一步成本只有几十秒，但它把“我相信它没改”变成“有证据证明它没改”。高风险任务里，这个区别就是敢不敢授权下一步的区别。
## 从调查报告到下一轮任务
只读调查最终要形成可执行的修改计划。报告第四栏“可以执行但尚未执行的修改计划”就是下一轮的输入，其中列出要改的文件、理由、关联证据和验证方式。你批准之后，Codex 进入修改流程时不需要重新调查。
交接时建议保留三样东西：报告原文、调查前后的 Git 状态对照、你批准或否决的决定。批准了，报告就是修改任务的上下文；否决了，报告是下次讨论的依据。两种情况下调查都不算浪费。
更多关于“批准后怎么把修改范围管住”的做法，可以看《第一次让 Codex 改项目，我建议你先从这个小任务开始》。
## 小结
只读调查的完整动作是：先判断是否值得调查，再写清允许和禁止的边界，然后按现状、入口、约束、风险、未知项、建议步骤的顺序收集证据，输出时把事实、推断、未知项和未执行的修改计划分开，最后用 Git 状态对照证明调查期间没有改动。
它不能替代的部分也要说清楚：调查结论里的推断仍需人来确认，修改计划仍需人来批准。Codex 负责把项目摸清楚，决定权留在你手里。
只读调查结束后，把事实、推断、未知项和未执行的计划分别记录，下一轮任务就能直接从这份报告开始。
### Codex 如何从报错反推影响范围
URL: https://codexguide.io/guides/codex-cong-bao-cuo-huo-xu-qiu-fan-tui-ying-xiang-fan-wei
拿到一条报错，最直接的反应是找到出错的那一行改掉。很多时候这一改确实能修好。过几天，另一个页面、另一份导出或定时任务可能暴露新的问题，原因仍然是同一个函数。
# Codex 如何从报错反推影响范围
> 测试环境：Windows 11 24H2（Build 26100）；Codex Desktop 26.814.5167.0；Codex CLI 0.147.0；2026-08-19 核验。
## 修对地方，只是第一步
拿到一条报错，最直接的反应是找到出错的那一行改掉。很多时候这一改确实能修好。过几天，另一个页面、另一份导出或定时任务可能暴露新的问题，原因仍然是同一个函数。
这篇文章只做一件事，把“改之前先算影响范围”变成固定动作。我用两个案例各走一遍流程，一个从报错出发，一个从需求出发，最后都落到同一张影响范围表上。两个案例的证据起点不同，落点一样。
如果你还没让 Codex 改过项目，可以先阅读“Codex 从目录到入口”，再回来对照这里的范围分析方法。
## 先把现象拆成四格
影响范围分析先从现象开始。报错案例沿用本机练习用的订单管理项目，订单列表页金额偶尔显示为 NaN。动手之前，先把它拆成四格写下来：
- 输入：打开订单列表页，列表中包含特定订单。
- 触发条件：订单金额字段为 null 或字符串，而不是数字。
- 实际结果：金额列显示 NaN。
- 预期结果：显示格式化后的金额，或一个明确的占位。
四格写完，“偶尔”这个词就有了具体含义。它只在特定数据形状下出现。后续应沿数据处理路径排查，先不要把注意力放在渲染层。
## 从堆栈和日志定位直接入口
现象拆完，才轮到代码。报错类案例的证据起点是堆栈、日志和复现步骤。目标很简单，找到直接入口，也就是错误第一次产生的那一行。
本例中沿日志和复现步骤定位到 `src/utils/format.js` 的 `formatAmount`：它直接对金额字段做算术运算，输入不是数字时就产出 NaN。这就是直接入口。
报错证据具体长什么样，可以看另一组真实截图。它来自我机器上另一个 Next.js 练习项目的 hydration 报错，和订单案例无关，但证据的形态是通用的：先是浏览器给出的报错文本，再是控制台里的完整原因和组件树，最后是逐层向下的调用栈。
> 图一 报错提示条：错误类型和排查文档入口（hydration 报错示例）。
> 图二 控制台完整报错：可能原因列表和组件树。
> 图三 调用栈详情：从报错入口逐层向下。
注意“直接入口”不等于“唯一改动点”。它只是故障传播的起点，接下来要查的是这个起点往外连着什么。
## 间接影响查五类
直接入口确定后，沿五个方向查间接影响，每查一处都留下证据：
1. 调用方：`src/pages/OrderList.vue` 调用 `formatAmount` 渲染金额列；其他页面有没有也在调它，逐个搜出来。
2. 共享模块：`format.js` 是工具模块，被共享的面越广，改动传导得越远。
3. 数据结构：`src/api/orders.js` 返回的订单金额字段类型不稳定，这才是 NaN 的数据来源。
4. 配置：没有证据表明构建配置或环境变量参与金额格式化，标记为暂不相关。
5. 缓存：本例中列表页没有金额缓存逻辑，排除。
查完把结果填进影响范围表，分三档：直接影响、间接影响、暂不相关。每一档都要带证据。“没查到”和“查到并排除”是两回事，都要写下来。
| 区域 | 档位 | 证据 | 验证方式 |
| --- | --- | --- | --- |
| `src/utils/format.js` 的 `formatAmount` | 直接影响 | 对非数字输入产出 NaN | 边界值单元测试 |
| `src/pages/OrderList.vue` | 间接影响 | 调用 `formatAmount` 渲染金额列 | 页面人工回归 |
| `src/api/orders.js` | 间接影响 | 金额字段可能返回 null 或字符串 | 接口数据抽查 |
| `tests/orders.spec.js` | 间接影响 | 覆盖订单列表，未覆盖异常金额 | 补充用例 |
| 路由、构建配置 | 暂不相关 | 无金额逻辑引用 | 不动 |
## 用证据给风险分级
影响范围表填完，再给每一档标风险。分级只看证据，不看感觉：
- `formatAmount` 被多个页面共享，改它的行为会传导到所有调用方，定中高风险，需要回归所有调用页面。
- `OrderList.vue` 只是展示调用，定低风险。
- 路由和构建配置没有任何金额相关证据，不定级，不动。
分级的意义是管住手：没有证据的区域一行都不改，哪怕它“看起来也有点可疑”。可疑就继续查，查不到证据就保持原样。
如果你想让“先出影响范围表再动手”成为 Codex 的默认动作，可以把它写进项目规则，具体写法见《别再重复提醒 Codex：用 AGENTS.md 让它读项目先读规则》。
## 需求案例：同一张表，换一个证据起点
再看需求案例。新需求是“订单金额按千分位显示”。没有报错，没有堆栈，证据起点换成需求里的词：金额、显示、格式化。
用这些词搜索，命中的是同一个 `format.js`。这恰恰说明影响范围表的价值：报错从堆栈往里追，需求从关键词往外扩，两条路最后落在同一张表上，表的结构不变。
差别出在间接影响。千分位是展示规则的变化，所有调用 `formatAmount` 的页面都会跟着变样；如果项目里还有导出、打印这类同样展示金额的环节，也要列入检查。而 NaN 修复只影响异常数据的展示。同一张表，填出来的行不一样。
## 把影响范围表交给 Codex
两个案例手动走完，我把同一套方法写成指令交给 Codex。要求是只读调查，不修改文件；先确认仓库状态，再从报错文本或需求关键词出发定位直接入口；沿调用方、共享模块、数据结构、配置、缓存五个方向查间接影响；输出影响范围表，分直接、间接、暂不相关三档，每一行附文件路径和证据；最后由影响范围推导出验证清单。证据不足的行明确标注“待确认”，不猜。
有一类问题不该替业务做决定。比如“金额为 null 时显示占位符还是显示 0”，这是业务取舍，不是技术判断。影响范围表里遇到这种情况，正确的动作是停下来，把选项和各自的影响写给业务方确认，而不是挑一个顺手的实现。
影响范围表也很适合作为第一次真实改动任务的输入：范围小、证据全、验收标准明确。为什么建议从小任务开始，可以看《第一次让 Codex 改项目，我建议你先从这个小任务开始》。
## 小结
完整流程可以这样回顾。先把现象拆成输入、触发条件、实际结果和预期结果四格；再从堆栈、日志或需求关键词出发定位直接入口；沿调用方、共享模块、数据结构、配置、缓存五个方向查间接影响；把结果分成直接影响、间接影响和暂不相关三档，每档附证据；按证据给风险分级，没证据的区域不动；最后把影响范围表转换成验证清单。
报错和需求用的是同一张表，差别只在证据起点。范围算清楚之后，改代码反而成了整个流程里最不紧张的一步。
范围表的价值在于让每个待改区域都有证据和验证动作。没有证据的区域先保持不动。
### Codex 读懂配置、环境变量和启动脚本
URL: https://codexguide.io/guides/codex-du-dong-pei-zhi-huan-jing-bian-liang-he-qi-dong-jiao-ben
很多项目第一次启动失败，表面上是端口占用、数据库连不上，或者页面拿不到接口地址。真正的原因往往藏在几层配置之间：package.json 调了哪个脚本，脚本又传了什么参数，程序从哪些文件读取环境变量，最后哪个值覆盖了哪个值。
# Codex 读懂配置、环境变量和启动脚本
## 配置问题，通常不是“少写一行”
很多项目第一次启动失败，表面上是端口占用、数据库连不上，或者页面拿不到接口地址。真正的原因往往藏在几层配置之间：`package.json` 调了哪个脚本，脚本又传了什么参数，程序从哪些文件读取环境变量，最后哪个值覆盖了哪个值。
如果没有先把这条链路读清楚，直接改 `.env` 可能只让本地暂时跑起来，随后又把测试环境的行为改坏。真实密钥、内部地址和个人路径也可能因此进入截图、提交记录或聊天记录。
这篇文章用一个最小 Node 示例说明一套读法。示例中的服务地址、令牌和数据库名都是虚构值，不能连接任何真实服务。你可以把相同步骤套到前端项目、后端服务、脚本仓库或 monorepo 的某个应用上。
## 先画出“启动到配置”的路径
拿到陌生项目时，我先不打开 `.env`，而是按下面的顺序找入口：
```text
package.json scripts
↓
启动脚本（node、tsx、vite、docker compose）
↓
入口文件（src/server.ts）
↓
配置加载（process.env、dotenv、配置模块）
↓
端口、数据库、第三方服务和功能开关
```
顺序很重要。先知道程序怎么启动，再看它在哪里加载配置，最后才判断某个变量应该写在哪里。否则只看到一个变量名，很难知道它是构建时使用、启动时使用，还是运行过程中才读取。
## 先分清三件事：配置文件、环境变量、启动参数
这三者经常同时出现在一条启动命令里，但职责不同：
| 组成 | 它回答的问题 | 常见例子 |
| --- | --- | --- |
| 配置文件 | 程序启动或运行时从哪里读取设置 | `config.toml`、`package.json`、`.env` |
| 环境变量 | 当前进程继承到了哪些键值 | `PATH`、`NODE_ENV`、`HTTP_PROXY` |
| 启动参数 | 这一次启动额外改变什么行为 | `codex --help`、`node server.js --port 4317` |
比如下面这条命令同时用了三层信息：
```powershell
$env:APP_MODE = "check"
npm run dev -- --port 4317
```
`APP_MODE` 属于当前 PowerShell 进程的环境变量，`--port 4317` 是传给脚本的启动参数，而脚本仍可能继续读取 `.env` 或配置模块。排查时要分别记录，不能把“命令行里出现过”理解成“配置文件里已经保存”。
### PATH 决定“能不能找到命令”
安装成功不等于当前 shell 能找到程序。遇到 `codex: command not found`、`rg is not installed` 或 Windows 下的 `不是内部或外部命令`，先查解析结果，不要马上重装：
```powershell
Get-Command codex -ErrorAction SilentlyContinue
Get-Command rg -ErrorAction SilentlyContinue
where.exe codex
where.exe rg
```
在 Linux、WSL 或 tmux 中对应的是：
```bash
command -v codex
command -v rg
printf '%s\\n' "$PATH"
```
如果安装器刚刚修改了 shell 配置文件，已经打开的终端未必会自动读取新 PATH。重新打开一个终端，或在确认文件来源后执行 `source ~/.zshrc`、`source ~/.bashrc`。不要把别人的 shell 文件整段复制过来；先用 `type -a codex` 或 `Get-Command codex -All` 确认当前命中的是哪一个版本。
GitHub 上的 [Issue #34947](https://github.com/openai/codex/issues/34947) 提供了一个可复核的 WSL 案例：Windows 11 + WSL2 + VS Code 终端中，关闭 `appendWindowsPath` 后，WSL 里的 `powershell.exe`、`pwsh` 和 `powershell` 都无法通过命令名解析；把 Windows PowerShell 目录临时加入 PATH 后，同一调用恢复。这个案例说明的是 PATH 和 WSL 互操作边界，不代表所有 WSL 安装都必须修改全局 PATH。
一则 Reddit 讨论也报告过 `codex: command not found` 和 `rg is not installed`，但 Reddit 当前无法通过公开读取接口核验正文与截图。它只能作为排查线索，不能替代本机的 `where.exe`、`command -v` 和版本输出。
这里有一个很容易被忽略的边界：Windows 应用、WSL 里的 Codex CLI 和集成终端可能不是同一个运行环境。一则 Reddit 案例里，界面显示 Agent 在 WSL 中运行、终端也使用 WSL，但“打开 `config.toml`”却打开了 Windows 用户目录下的 `C:\Users\\.codex\config.toml`，而不是 WSL home 目录里的配置。这个截图只能作为排查案例，不能当作官方行为的完整说明；遇到类似问题，应以当前版本的界面、文档和实际路径为准。
> 图一 Windows/WSL 配置路径混淆案例。个人名已遮挡；路径和结论来自帖子原文，未独立验证。
## 第一步：从启动脚本开始
先读仓库状态、目录和包管理文件。这些都是只读动作：
```powershell
git status --short --branch
Get-ChildItem -Force
Get-Content .\package.json
```
假设 `package.json` 的关键部分如下：
```json
{
"scripts": {
"dev": "tsx watch src/server.ts",
"start": "node dist/server.js",
"build": "tsc -p tsconfig.json",
"test": "vitest run"
}
}
```
这里至少有四个结论：
- `npm run dev` 运行的是 `src/server.ts`，并且会监听文件变化。
- `npm run build` 先把 TypeScript 编译到 `dist`，生产启动不直接读取 `src`。
- `npm start` 依赖已经存在的 `dist/server.js`，单独执行它可能会因为没有构建产物而失败。
- `npm test` 是验证配置解析是否改变行为的最小入口之一。
不要把 `dev` 和 `start` 当成同一件事。开发脚本可能注入本地参数、启用热更新，生产脚本则可能依赖构建阶段生成的文件和部署平台提供的环境变量。
如果脚本继续调用了别的脚本，继续展开。例如：
```json
"dev": "cross-env NODE_ENV=development tsx watch src/server.ts"
```
这说明 `NODE_ENV` 由启动命令直接设置，不是从 `.env` 读出来。判断变量来源时，要把脚本中的前缀、PowerShell 的 `$env:NAME=...`、Docker Compose 的 `environment` 和 CI 配置一起算进去。
启动参数也要单独列出来。有些帖子会把 Electron、native module、CLI 和 `--no-sandbox` 串成一条很长的启动链，这类案例能说明“程序名后面的参数也会改变运行方式”，但不应直接变成入门教程的复制命令。对任意参数先回答三个问题：是谁解析它、它影响哪个进程、是否会降低安全边界。没有这三项证据，就把参数标成待确认。
除了脚本和命令行参数，配置文件本身也可能在应用设置里提供入口。Codex 的设置界面就在 `config.toml` 入口旁提示“编辑后重新启动 Codex”：有些配置只在进程启动时读取，改完文件不会自动改变已经存在的进程。排查“配置改了却没生效”时，先确认新值有没有被正在运行的进程真正读到，再决定要不要改下一处。
## 第二步：找到配置真正被读取的位置
接着搜索变量名和读取方式。优先搜 `process.env`、`dotenv`、`loadEnv`、`config` 等明确线索：
```powershell
git grep -n "process\.env\|dotenv\|loadEnv\|config" -- ':!node_modules'
```
示例项目的 `src/config.ts` 可能是这样：
```ts
import "dotenv/config";
const required = (name: string) => {
const value = process.env[name];
if (!value) throw new Error(`Missing required environment variable: ${name}`);
return value;
};
export const config = {
nodeEnv: process.env.NODE_ENV ?? "development",
port: Number(process.env.PORT ?? 3000),
databaseUrl: required("DATABASE_URL"),
apiBaseUrl: required("API_BASE_URL"),
featureNewCheckout: process.env.FEATURE_NEW_CHECKOUT === "true"
};
```
读这段代码时，不要只抄变量名，要记录四件事：
1. **来源**：是 `process.env`、配置文件，还是命令行参数。
2. **是否必填**：`required` 这类校验会决定启动失败还是使用默认值。
3. **类型**：环境变量本质上都是字符串，端口、布尔值和数组都需要显式转换。
4. **默认值**：`PORT` 和 `NODE_ENV` 有默认值，不代表数据库地址也可以省略。
像 `process.env.FEATURE_NEW_CHECKOUT === "true"` 这样的写法也值得记下来。把变量写成 `1`、`yes` 或 `TRUE`，在这段代码里都不会得到 `true`。这类小差异经常让“配置明明写了却没生效”的排查绕远路。
## 第三步：整理配置来源和覆盖关系
不要笼统地写“环境变量优先级很高”。优先级由项目的加载代码、启动工具和部署平台共同决定。先在项目里找证据，再画表。
以 `dotenv` 的常见用法为例，可以先记录成这样：
| 来源 | 示例 | 什么时候生效 | 是否建议提交 |
| --- | --- | --- | --- |
| 启动命令 | `NODE_ENV=development npm run dev` | 执行命令时 | 可以提交脚本，不提交秘密值 |
| 当前进程环境 | CI、容器或终端注入的 `PORT` | 程序启动前 | 不提交 |
| `.env.local` | 本机端口、虚构服务地址 | 项目明确加载时 | 通常不提交 |
| `.env.example` | `DATABASE_URL=` | 给人参考变量名 | 可以提交，但只放空值或示例值 |
| 配置代码默认值 | `PORT ?? 3000` | 上面没有提供值时 | 提交代码 |
同一个项目可能使用 `dotenv-flow`、Vite、Next.js、Docker Compose 或部署平台自己的加载规则，表格不能直接照搬。尤其是 `.env.local`，并不是 Node 或 `dotenv/config` 的通用默认文件名，只有项目代码或框架明确加载它时才会生效。检查方法是继续读入口和工具文档，并用一个无敏感信息的变量做实验：给 `PORT` 设置临时值，启动后观察监听端口，再恢复现场。
在 PowerShell 中，临时设置只对当前终端有效：
```powershell
$env:PORT = "4317"
npm run dev
Remove-Item Env:PORT
```
不要把令牌写进命令历史。测试覆盖关系时，用端口或 `APP_MODE=check` 这类无害变量即可。
代理变量也是同一类问题。一个 GUI 应用、一个 CLI 进程和一个项目脚本，可能分别继承系统环境、启动它们的 shell 环境和项目自己的 `.env`。一则 Reddit 帖子提到 `HTTP_PROXY`、`HTTPS_PROXY` 在 CLI 和 GUI 中表现不同；这可以用来提醒排查方向，但不能据此断言 Codex 的所有版本都会自动读取 `CODEX_HOME/.env`。实际检查时，记录变量由谁设置、由哪个父进程继承，以及配置代码在哪里读取：
```powershell
Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY
Get-ChildItem Env:CODEX_HOME
```
如果需要做对比实验，用临时、无敏感信息的代理地址或 `APP_MODE`，不要把真实代理账号和密码写入截图、命令历史或项目文件。
## `.env.example` 是说明书，不是密码保险箱
好的 `.env.example` 只告诉读者变量名、格式和必要说明：
```dotenv
NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/example_app
API_BASE_URL=https://api.example.test
FEATURE_NEW_CHECKOUT=false
```
这几个值都不能直接拿去连接生产服务。尤其要注意：
- 不要把真实 API key 替换成“看起来像真的”长字符串；用 `replace-with-local-token` 更安全。
- 不要把公司内网域名、真实数据库名或带个人身份的路径放进示例文件。
- `.env.example` 只描述变量，不代表项目已经有可用的本地依赖。
- 端口、数据库、对象存储和第三方 API 都要说明是本地模拟、测试环境还是必须人工申请。
先检查忽略规则：
```powershell
git check-ignore -v .env .env.local
git ls-files .env .env.local .env.example
```
如果 `.env` 已经被 Git 跟踪，先暂停，不要直接删除或改写。那可能涉及历史泄密和团队协作，应由负责人决定如何轮换凭据、清理历史并通知部署环境。
## 第四步：把运行时前提列出来
配置文件只是其中一部分。启动脚本还可能隐含这些前提：
- Node、Python 或 Java 的版本由 `.nvmrc`、`volta`、`pyproject.toml` 或 CI 文件限定。
- 数据库、Redis、消息队列或本地对象存储必须先启动。
- 前端项目的 `VITE_*`、`NEXT_PUBLIC_*` 等变量可能在构建时打进浏览器，不能放私密令牌。
- Docker Compose、CI 和部署平台可能使用另一份变量名，不能只看本机 `.env`。
运行环境本身也是前提之一。在 Windows 版本的 Codex 中，Agent environment 与集成终端 shell 也可能分别选择 WSL。它们决定“代码由谁执行”和“终端从哪里启动”，不等同于某个配置文件的绝对路径。先把两个选择记录下来，再去验证配置文件实际由哪个进程读取。
> 图二 Codex 环境选择界面。它只证明界面中的选择，不足以单独证明配置文件路径或所有变量的加载顺序。
把前提写成可验证的清单，比写一句“需要配置好环境”有用得多：
```text
[ ] Node 版本符合 .nvmrc
[ ] npm install 已完成，未额外升级 lockfile
[ ] 本地数据库已启动，使用 example_app 数据库
[ ] DATABASE_URL 指向本机，不是生产域名
[ ] API_BASE_URL 使用测试服务或本地 mock
[ ] 端口 3000 未被其他程序占用
```
其中“未额外升级 lockfile”很容易被忽略。为了启动一个项目临时执行 `npm install`，可能带来依赖版本变化；如果只是调查配置，先用仓库现有的 lockfile 和安装命令。
## 用最小启动验证，而不是直接碰生产配置
配置调查的目标是证明“我知道程序从哪里取值”，不一定要把所有外部服务都连通。可以分三层验证。
### 1. 静态验证
确认脚本、入口、配置模块和 `.env.example` 互相对得上：
```powershell
git grep -n '"dev"\|"start"\|"build"' -- package.json
git grep -n 'DATABASE_URL\|API_BASE_URL\|FEATURE_NEW_CHECKOUT' -- ':!node_modules'
```
### 2. 无副作用启动
如果项目提供 `--help`、配置校验命令或 mock 模式，优先运行它们。没有的话，使用虚构数据库地址并只启动到配置校验阶段，避免触发写入操作。文章中的示例只验证端口和必填变量，不执行迁移、不发送外部请求。
### 3. 正常运行验证
确认本地依赖明确属于开发环境后，再运行：
```powershell
Copy-Item .env.example .env.local
npm run dev
```
看到服务监听在预期端口后，用 `Ctrl+C` 停止，并再次检查：
```powershell
git status --short
```
如果工作区多出 `.env.local`，这是预期的本地文件；如果出现 lockfile、构建产物或配置文件改动，先判断它们是否由启动命令自动生成，不要顺手提交。
配置错误有时会在初始化阶段直接阻断程序，而不是等到真正执行任务时才出现。一张终端案例截图显示，Codex 先报 `Error loading configuration: No such file or directory`，随后 npm 又因 `uv_cwd` 报错；这类截图适合用来说明“先定位配置和工作目录，再判断包是否损坏”，但不能仅凭截图断言应该卸载或重装哪个包。
> 图三 配置加载阶段的错误案例。错误文本和个人路径已遮挡；未对原项目做复现，不应据此直接执行卸载、重装或删除配置。
> 图四 把三类配置看成进入同一个进程的三条输入线：先分别确认来源，再判断哪个值最终生效。图中只表达关系，不代表某个框架固定的加载顺序。
> 图五 排查时依次检查入口、配置和验证；遇到断点先停在当前层收集证据，不要直接跳到重装依赖或修改共享环境。
## 哪些配置可以改，哪些要先问
可以直接调整的通常是本机、可恢复、不会影响其他人的值，例如本地端口、日志级别和 mock 开关。涉及共享环境的配置要先确认：
| 配置类型 | 常见风险 | 默认动作 |
| --- | --- | --- |
| 本机端口 | 只影响当前进程 | 可以临时改，并记录恢复方式 |
| 本地数据库地址 | 误连共享或生产数据库 | 先确认目标环境 |
| 第三方 API 地址 | 可能发送真实请求 | 先问负责人，优先使用 mock |
| 密钥、令牌、证书 | 泄露后需要轮换 | 不读取、不复制、不截图 |
| CI、部署平台变量 | 影响他人或线上服务 | 先获得明确授权 |
| 数据库迁移开关 | 可能改变持久化数据 | 先确认回滚方案 |
“我只是想让服务启动”不是修改共享配置的理由。启动失败信息不足时，保留错误、记录已检查的变量和缺少的权限，把需要人工决定的事项列出来。
## 给 Codex 的配置调查提示词
如果让 Codex 先做调查，可以直接给出边界和交付格式：
```text
请只读调查这个仓库的配置和启动路径，不修改文件、不安装依赖、不提交。
请按顺序检查：
1. git 状态、包管理文件和所有启动脚本；
2. 入口文件、配置加载模块和环境变量读取位置；
3. .env.example、忽略规则、Docker/CI/部署配置；
4. 开发、测试、预览、生产之间的变量差异；
5. 数据库、队列、第三方服务、端口等运行前提。
输出一张表：变量名、来源、是否必填、默认值、作用环境、敏感等级、证据路径。
所有密钥只报告“存在”，不要读取或回显值。无法确认的优先级标为“待验证”，并给出一个无副作用的验证命令。
```
验收时看三点：它有没有给出文件和行号证据；有没有区分事实、推断和待确认项；有没有在输出里回显秘密值。如果只得到一串环境变量名称，没有启动路径和运行前提，这次调查还不完整。
## 最后留下一份小清单
完成配置调查后，至少应留下这些信息：
```text
启动入口：npm run dev -> tsx watch src/server.ts
生产入口：npm run build -> npm start
配置加载：src/config.ts，使用 dotenv/config
必填变量：DATABASE_URL、API_BASE_URL
带默认值：NODE_ENV=development、PORT=3000
本地依赖：PostgreSQL；未执行迁移
已验证：静态路径、端口覆盖、工作区状态
未验证：第三方 API 权限、生产部署变量
安全边界：未读取真实 .env、未回显令牌、未改共享配置
```
这份记录让下一位读者知道程序从哪里启动、值从哪里来，哪些结论已经验证，哪些地方仍需要负责人确认。到这里，项目的运行前提才算读清楚。
整理完成后，至少应能说明启动入口、配置来源、覆盖顺序和验证方式。真实密钥、内部地址和个人路径不要写入文章或提交记录。
### Codex 阅读大仓库、多模块与历史代码
URL: https://codexguide.io/guides/codex-yue-du-da-cang-ku-duo-mo-kuai-yu-li-shi-dai-ma
大仓库最容易把人带偏的地方，是目录很多、同名模块很多、旧实现也一直留在仓库里。让 Codex 直接“把项目看懂”通常只会得到一份泛泛的目录摘要。更稳的做法是把调查拆成几次只读动作，每次都留下路径、证据和仍未确认的边界。
# Codex 阅读大仓库、多模块与历史代码
大仓库最容易把人带偏的地方，是目录很多、同名模块很多、旧实现也一直留在仓库里。让 Codex 直接“把项目看懂”通常只会得到一份泛泛的目录摘要。更稳的做法是把调查拆成几次只读动作，每次都留下路径、证据和仍未确认的边界。
这篇用公开的 `pnpm/pnpm` monorepo 做示例，演示一条可以复用的阅读路线。你不需要先理解整个仓库，也不需要在调查阶段运行安装、构建或写入命令。
如果你还在熟悉 Codex 的工作方式，可以先阅读“Codex 从目录到入口”，再回到本文继续做历史核对。
## 先画顶层地图
第一轮只回答一个问题，仓库里有哪些类型的目录。打开仓库首页，先看根目录的工作区配置、核心实现、测试、工具和基础设施。不要马上点进几十个文件，先记下目录之间的大致关系。
图一展示公开仓库根目录的目录分类。
可以把第一轮结果写成一张小表。
| 类别 | 要找的线索 | 先问的问题 |
| --- | --- | --- |
| 核心实现 | `pnpm/`、`packages/` 等 | 任务最终会落在哪个入口 |
| 共享或并行实现 | `pnpm11/`、`pnpr/` 等 | 是否存在替代实现或迁移分支 |
| 测试 | `tests/`、`__tests__/` | 哪些行为有自动验证 |
| 工具与基础设施 | `scripts/`、`infra/`、CI 配置 | 构建、发布和检查由谁负责 |
这一步的产物应该是“目录地图”，不是“项目总结”。没有证据的推断先放到待核对清单里。
## 再缩小到任务模块
有了顶层地图，再根据任务关键词选择一个局部目录。例如要调查 workspace 解析或 CLI 行为，可以先进入 `pnpm/`，查看它的 `crates`、`npm`、`plans`、`scripts` 和 `tasks`。
图二展示任务模块及其入口、实现和测试范围。
在 Codex Desktop 中可以使用下面的只读提示。
```text
只做只读调查，不要修改文件、安装依赖或运行会写入磁盘的命令。
请先建立根目录地图，再缩小到 pnpm/ 目录中与 workspace 解析或 CLI 任务相关的模块。
请列出目标路径、每个路径的一句话职责，以及已核验事实、推断和待核对边界。
只引用仓库相对路径，不要输出本机绝对路径。
```
图三展示了根目录分类、目标模块和仓库相对路径。
## 用 Git 历史判断代码是否活跃
目录结构只能说明“代码在哪里”，不能说明“代码现在是否仍被使用”。接下来进入公开仓库的本地副本，在 PowerShell 中把提示符临时缩短，避免截图带出本机路径。
```powershell
$repo = Join-Path $env:TEMP 'article08-pnpm'
Set-Location $repo
function prompt { 'PS> ' }
$file = 'pnpm/README.md'
```
先看文件级历史。`--follow` 可以跨越文件重命名，格式化参数只输出短 SHA、日期和摘要。
```powershell
git log --follow -n 8 --date=short --pretty=format:'%h | %ad | %s' -- $file
```
图四展示 git log 的提交摘要、日期和文件历史。
公开提交历史页还能补充按路径分组的时间线，适合确认某个模块是否持续有变更。
图五展示路径、提交摘要和时间线。
接着用 `git blame` 看行级归因。
```powershell
git blame --date=short --abbrev=12 -L 1,12 -- $file
```
图六展示 README 行级 blame 的提交、作者、日期和行号。
命令结束后恢复提示符。
```powershell
Remove-Item Function:\prompt -ErrorAction SilentlyContinue
```
## 把当前、并行和待验证实现分开
历史信息要和当前代码放在一起看。以 `pnpm/README.md` 为例，公开说明同时出现了 active development、Rust 重写和 TypeScript 并行实现的描述。这类信息说明仓库里存在迁移过程，但不能直接推出哪个目录已经替代了哪个目录。
图七展示用于区分实现状态的判断表。
| 判断 | 最少需要的证据 | 结论写法 |
| --- | --- | --- |
| 当前实现 | 当前入口或调用方 + 通过的测试 | “已从入口和测试核验” |
| 并行实现 | README、迁移提交或平行目录 | “存在并行路径，生产状态待核对” |
| 兼容层 | 兼容测试、适配器或发布配置 | “用于兼容，不能当作主实现” |
| 疑似废弃 | 无调用方、旧提交、迁移说明 | “暂不删除，先补一条验证任务” |
## 最后处理边界
当跨仓库依赖、子模块或权限限制让调查无法继续时，记录三件事，已经读到的路径、支撑判断的证据、下一步需要谁补什么。不要把“没有读到”写成“没有使用”，也不要为了让报告完整而猜测调用关系。
一个可复用的调查结果，至少应包含下面五项。
1. 根目录地图和目标模块路径。
2. 入口、内部实现和测试之间的最短阅读链路。
3. `git log` 与 `git blame` 得出的历史线索。
4. 当前、并行、兼容和待验证实现的判断表。
5. 没有证据覆盖的边界和下一步核对动作。
## 结语
读大仓库时，应让每个判断都能沿着路径和提交记录复查。先画地图，再缩小范围，随后用历史和测试交叉核对，最后把不确定的部分单独列出来。这样 Codex 的上下文会更短，调查结果也更容易交给下一位维护者。
目录地图、历史记录和测试结果应保留在项目文档或任务记录中，方便下一次调查复核。
## 参考资料
- [Understand large codebases](https://developers.openai.com/codex/use-cases/codebase-onboarding)
- [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [git-log Documentation](https://git-scm.com/docs/git-log)
- [git-blame Documentation](https://git-scm.com/docs/git-blame)
- [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
- [Workspace | pnpm](https://pnpm.io/workspaces)
### Codex 追踪依赖调用链与数据流
URL: https://codexguide.io/guides/codex-zhui-zong-yi-lai-diao-yong-lian-yu-shu-ju-liu
改一个接口之前，先回答一个问题。这个请求从哪里进来，经过了哪些判断，最后读了什么数据、调用了什么适配层？只看函数名通常不够，真正影响结果的前缀、依赖注入、缓存和异常处理，往往分散在几个文件里。
# Codex 追踪依赖调用链与数据流
> 测试环境：Windows 11 24H2；Codex Desktop 26.814.5167.0；Codex CLI 0.147.0；2026-08-26 核验。
改一个接口之前，先回答一个问题。这个请求从哪里进来，经过了哪些判断，最后读了什么数据、调用了什么适配层？只看函数名通常不够，真正影响结果的前缀、依赖注入、缓存和异常处理，往往分散在几个文件里。
下面用一个可以反复打开的 FastAPI 小项目演示。项目目录是 `temp/dependency-chain-demo/`，数据放在内存里，`inventory` 也只是本地 stub，不访问网络，不写数据库。
如果你还没做过只读项目调查，可以先阅读“Codex 只读调查”，再回到本文追具体调用链。
## 先把示例跑起来
在 PowerShell 中进入项目目录。Windows 上如果全局 Python 没有依赖，直接使用虚拟环境解释器最省事。
```powershell
cd .\temp\dependency-chain-demo
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --index-url https://pypi.org/simple -r requirements.txt
.\.venv\Scripts\python.exe -c "import fastapi, uvicorn, httpx; print('dependencies ok')"
.\.venv\Scripts\python.exe -m uvicorn app.main:app --port 8000
```
看到 `Uvicorn running on http://127.0.0.1:8000` 后保持窗口不动，再打开第二个 PowerShell，发送四个只读请求。
```powershell
cd .\temp\dependency-chain-demo
curl.exe -i http://127.0.0.1:8000/api/v1/items/42 -H "X-Demo-Token: demo-token" -H "X-Tenant-ID: demo-tenant"
curl.exe -i http://127.0.0.1:8000/api/v1/items/99 -H "X-Demo-Token: demo-token" -H "X-Tenant-ID: demo-tenant"
curl.exe -i http://127.0.0.1:8000/api/v1/items/404 -H "X-Demo-Token: demo-token" -H "X-Tenant-ID: demo-tenant"
curl.exe -i http://127.0.0.1:8000/api/v1/items/42 -H "X-Demo-Token: wrong" -H "X-Tenant-ID: demo-tenant"
```
四个结果分别对应 200、200、404 和 401。它们覆盖了仓储命中、inventory stub 命中、未找到和认证失败四条路径。
## 第一步：确认入口和完整路由
在 Codex Desktop 中打开 `dependency-chain-demo` 文件夹，先发送这段保护语句。
```text
你现在只做只读代码调查。禁止创建、修改、重命名、删除或保存任何文件，禁止执行会写入数据库、队列或外部服务的命令。回答中给出文件路径、符号名和行号，不确定的地方标记为“未确认”。
```
按 `Ctrl+P` 打开 `app/main.py`，再打开 `app/routers/items.py`。发送：
```text
只读分析这个示例项目的接口入口。定位 FastAPI 实例、router 导入、include_router 注册、HTTP 方法、路由路径和 item_id 参数。按“文件:行号 -> 符号 -> 证据”列出结果，并计算最终请求路径。不要修改文件。
```
你要拼出的路径是：
```text
/api/v1 + /items + /{item_id}
= GET /api/v1/items/{item_id}
```
这里的 `api/v1` 来自应用注册，`items` 来自 `APIRouter`，`{item_id}` 来自路由装饰器。三段缺一段，请求就不会落到预期函数。
## 第二步：沿着参数进入核心逻辑
从 `read_item` 的定义开始，用编辑器的“跳转到定义”和“查找引用”逐个打开依赖函数。发送：
```text
只读调查 GET /api/v1/items/{item_id}。依次检查 app/routers/items.py、app/dependencies.py、app/services/items.py，追踪 read_item 如何调用 get_current_user 和 find_item。输出每一步的输入、输出、分支、状态码，以及文件:行号。禁止修改或保存文件。
```
记录参数流时，不要只写“调用了 service”。在本例中，路径参数 `item_id` 进入 `read_item`，请求头进入 `get_current_user`，依赖返回的 `tenant_id` 再传给 `find_item`。认证失败会在业务函数执行前短路，仓储和 inventory 都没有机会被调用。
## 第三步：单独检查数据和副作用
继续打开 `app/infra/cache.py`、`app/repositories/items.py` 和 `app/clients/inventory.py`。发送：
```text
只读检查数据流。按执行顺序说明 cache.get、repository.find_by_id、inventory.lookup、cache.set 的输入、输出和副作用。标出缓存键、调用参数、超时和错误映射。明确 inventory.py 是本地 stub，不要描述成真实网络调用。不要执行外部写入操作。
```
本例的执行顺序很清楚。`find_item` 先查内存缓存，未命中后查 repository；repository 没有结果时才调用本地 inventory stub；拿到对象后写回缓存。缓存和仓储都只读当前进程内存，stub 也不会产生网络副作用。
遇到真实项目时，把副作用按数据库、缓存、队列、第三方服务和文件存储分开记录。每一项都要补上失败时的结果，例如超时返回 503、降级为空，还是继续使用旧缓存。没有看到代码或运行证据，就写“未确认”。
## 第四步：把证据画成一条链
最后让 Codex 把静态证据整理成草图：
```text
请根据刚才的只读分析，输出脱敏的完整调用链草图。节点包括请求、路由、依赖校验、service、cache、repository/client 和响应。每个节点标注证据类型，并列出未确认断点。不要运行服务，不要发布，不要修改文件。
```
一张合格的记录至少要写清四件事：节点位置、输入输出、证据类型和当前状态。静态代码能证明符号关系，测试能证明测试替身覆盖的分支，curl 响应才能证明本地运行结果。三者不要混成一句话。
## 什么时候可以说“追完了”
你应该能从入口复述到响应，并且能回答这些问题：全局前缀在哪里，认证何时发生，租户值从哪里来，缓存命中后是否跳过仓储，外部适配层的超时和错误如何返回，成功和失败响应分别被谁消费。
动态分派、工厂注册、异步队列和配置生成是常见断点。静态搜索找不到实际实现时，记录注册表、队列名或配置来源，再用测试日志、调试器或 trace_id 做下一次验证。不要用一个看起来合理的函数名把空白补上。
最后检查截图和调查记录。只保留公开示例或已经遮挡的界面，不要让本机路径、令牌、连接串、真实域名和用户数据进入文章。文章讲清楚调用链就停，不需要把内部处理过程写给读者。
## 继续交流
调用链记录应包含入口、关键判断、外部依赖、数据变化和异常边界。无法确认的实现保留为待验证项。
### Codex 把调查结果整理成项目理解报告
URL: https://codexguide.io/guides/codex-ba-diao-cha-jie-guo-zheng-li-cheng-xiang-mu-li-jie-bao-gao
只读调查结束后，终端里通常已经积了一屏命令，聊天里也有不少结论。问题是，换一个人接手，他还是不知道从哪里改、判断依据是什么、还缺哪条证据。
# Codex 把调查结果整理成项目理解报告
> 测试环境（核验信息） Windows 11 24H2（Build 26100）；Codex Desktop 26.820.7780.0；Codex CLI 0.147.0；Git 2.47.0.windows.2；2026-08-27 核验。
只读调查结束后，终端里通常已经积了一屏命令，聊天里也有不少结论。问题是，换一个人接手，他还是不知道从哪里改、判断依据是什么、还缺哪条证据。
项目理解报告接在调查记录之后，负责把能影响决定的内容整理出来。读者拿到它，应该能复核现状，知道下一步怎么做。
> 图一 把文件发现、命令记录和风险提示收束成一份可交接报告。
## 先区分两种产物
调查记录回答“我看到了什么”，项目理解报告回答“目前可以据此做什么”。前者允许保留搜索过程，后者只留下影响判断的证据。
| 调查记录 | 项目理解报告 |
|---|---|
| 按时间记录查过哪些文件和命令 | 按问题组织结论和证据 |
| 可以有重复发现和临时猜测 | 事实、推断、假设、未知项分开写 |
| 重点是过程可追溯 | 重点是下一步可执行 |
| 可能很长 | 通常控制在一到两页 |
如果一条信息不能帮助读者复核现状、评估风险或安排下一步，它通常不需要进入报告正文。
## 报告先写结论，再补证据
我通常把报告分成下面六块。这个顺序能让结论先落地，再补证据和行动边界。
1. **范围与结论**。写清调查对象、分支、时间和当前判断。
2. **项目地图**。列出入口文件、核心模块、测试目录、运行命令及其关系。
3. **已确认事实**。每条事实附上文件路径、符号、命令或输出。
4. **基于证据的推断**。说明推断链，别把推断写成代码已经证明的事实。
5. **未知项与风险**。列出缺少的运行证据、未覆盖的分支和可能影响。
6. **建议步骤**。把下一轮任务写到文件、符号、改动边界和验收方式。
> 图二 终端案例展示项目地图与代码证据，并将它们整理成报告条目。
### 一条结论至少要有一个证据锚点
证据锚点通常来自四个地方。
- 文件路径和行号，例如 `src/discounts.py:4` 的 `apply_discount`。
- 代码符号之间的调用或导入关系。
- 命令及其关键输出，例如 `python -m unittest discover -s tests -v` 的失败用例。
- Git 状态、提交记录或差异，用来说明调查前后是否发生了改动。
不要把“看起来像入口”“应该是缓存问题”直接放进事实栏。看起来像入口是推断，缓存问题是待验证假设。
## 用一个小项目演示
本文使用 `temp/workflow-demo/`，这是一个不含真实业务数据的 Python 练习项目。README 说明它有四类练习，探索、修复折扣计算、重构重复逻辑和补测试。运行命令如下。
```powershell
cd .\temp\workflow-demo
python -m unittest discover -s tests -v
```
只读调查时先看目录和入口，再看实现与测试。
```powershell
rg --files
rg -n "apply_discount|order_total|shipping_total|unittest" README.md src tests
git status --short --branch
git log --oneline --max-count=5
```
这几条命令能回答“项目怎么跑、核心函数在哪里、测试覆盖什么、调查期间有没有动过仓库”，但不会自动证明业务行为正确。
### 把发现压缩成项目地图
针对这个项目，报告里的地图可以只保留五行。
```text
README.md 任务说明、运行命令和当前已知问题
src/discounts.py 折扣、订单总价和运费总价的实现
tests/test_discounts.py unittest 行为测试，包含成功、异常和边界
python -m unittest ... 唯一记录在 README 中的测试入口
风险 README 声称保留一个 Bug，需以实际测试输出确认
```
注意最后一行仍然是风险提示。README 的描述是项目文档事实，Bug 是否仍能复现，要靠运行结果确认。
## 事实、推断和未知项怎么写
可以用同一条发现演示三种写法。
| 层级 | 写法 | 证据 |
|---|---|---|
| 事实 | `apply_discount` 在 `src/discounts.py:4` 定义，先检查负价格和折扣范围，再返回四舍五入后的金额 | 文件内容和符号位置 |
| 推断 | 如果失败集中在折扣金额，优先检查 `apply_discount` 的百分比公式；订单总价走的是 `_add_rate`，不是同一条路径 | `src/discounts.py` 中的调用关系 |
| 未知项 | 尚未确认 README 所说的 Bug 在当前工作树是否仍能复现，也未确认生产项目是否使用同名函数 | 还没有运行输出或外部调用证据 |
这张表里的“未知项”不能被省略。读者知道哪里没有证据，才不会把一段合理猜测当成已经验证的结论。
> 图三 从文件、符号、命令到 Git 记录，证据越具体，结论越容易复核。
## 把证据写成可复核引用
正文不需要复制整段源码，引用到能定位的最小单位就够了。
```text
结论：折扣计算入口是 apply_discount。
证据：src/discounts.py:4；函数在 :7 检查 price < 0，在 :9 检查 percent 范围，:10 返回 round(...)。
验证：python -m unittest discover -s tests -v；需记录实际通过/失败数量。
```
命令输出也要保留原貌，至少包括命令、关键行和执行时间。不要只写“测试通过”，更不要在没有运行时把 README 里的预期结果写成实际结果。
Git 证据建议成对记录。
```text
调查开始：git status --short --branch -> [原始输出]
调查结束：git status --short --branch -> [原始输出]
判断：两次输出一致，调查期间未发现新增改动；若不一致，逐项解释来源，不自行清理。
```
## 报告模板
下面的模板可以直接复制到项目文档、任务评论或交接记录中。
```markdown
# 项目理解报告：<主题>
调查范围：<仓库 / 分支 / 时间>
一句话结论：<当前最重要的判断>
## 项目地图
- 入口：<文件:行号 / 符号>
- 核心路径：<入口 -> service -> 数据或适配层>
- 运行命令：`<命令>`
- 测试入口：`<命令>`
## 已确认事实
- [事实] <结论>；证据：<文件:行号、命令或 Git 输出>
## 基于证据的推断
- [推断] <判断>；依据：<两条以内的证据>
## 未知项与风险
- [未确认] <还缺什么证据>；影响：<可能阻塞的决定>
## 下一步计划（尚未执行）
1. <文件:符号>：<最小改动>；原因：<对应证据>
2. 验证：<测试命令 / 手工检查 / 预期结果>
3. 停止条件：<出现什么情况就暂停并回报>
```
模板里的“尚未执行”很重要。它把调查和修改分成两个授权阶段，下一位执行者可以直接接着做，也能清楚知道哪些动作还没有发生。
## 从报告转成开发任务
一份报告合格的标志，是它能在不重新调查的情况下生成下一轮任务。转换时只保留四个要素。
1. **目标文件和符号**。不要只写“修复折扣逻辑”，写成 `src/discounts.py:4 apply_discount`。
2. **允许的范围**。例如只改公式，保留参数校验和返回值格式。
3. **证据和验证**。先复现失败测试，再展示差异，最后运行完整测试集。
4. **停止条件**。实际结果与报告不一致，或发现共用逻辑会影响订单总价时，先停下来确认。
以本例为例，下一轮任务可以这样写。
> 图四 完整报告将推断、未知项、风险和下一步任务分开记录，并保留停止条件。
```text
只处理 src/discounts.py 的 apply_discount。先运行
python -m unittest discover -s tests -v，记录失败用例和实际值。
确认百分比公式后做最小修复，不改函数签名、参数校验和其他公开函数。
展示 git diff，再运行完整测试。若 order_total 或 shipping_total 也受影响，暂停并报告。
```
这段任务保留了报告里的证据、边界和暂停点，执行者可以据此继续。
> 图五 报告把项目地图、证据和停止条件交给下一轮开发任务。
## 常见的四个误区
**把搜索过程当报告。** `rg` 查了几十个文件，读者仍可能不知道哪个入口重要。报告应删掉不影响判断的路径。
**把推断写成事实。** 函数名相似、目录名熟悉，都不能代替调用关系或运行输出。
**把预期结果当验证结果。** README 写“第一次会失败”，只能说明项目作者的意图；当前工作树是否如此，要重新运行。
**为了完整而复制源码。** 引用路径、符号和关键行就够了。大段源码会掩盖风险，也让报告很快过期。
## 交付前检查
- 报告开头写了调查范围、分支和核验时间。
- 每条事实都有路径、符号、命令或 Git 证据。
- 推断注明依据，未知项明确写“未确认”。
- 运行命令和实际输出没有互相冒充。
- 下一步任务包含改动边界、验证方式和停止条件。
- 调查前后的 Git 状态已对照；发现变化时没有擅自清理。
- 报告长度能让接手者在几分钟内定位入口，而不是重新读完整个仓库。
项目理解报告要把三件事写清楚，当前知道什么，哪些地方仍缺证据，下一步能安全做什么。这样下一次任务才能接着往下走。
## 参考资料
- [OpenAI Codex 文档](https://developers.openai.com/codex/)。Codex 产品与工作流入口，页面于 2026-08-27 通过 Jina Reader 核验。
- [Codex CLI 文档](https://developers.openai.com/codex/cli/)。CLI 使用入口，页面于 2026-08-27 通过 Jina Reader 核验。
- [git-log 官方文档](https://git-scm.com/docs/git-log)。用来记录提交历史和调查依据。
- [git-diff 官方文档](https://git-scm.com/docs/git-diff)。用来检查改动范围和差异。
> 图六 Git 官方 `git-status` 文档中对工作树、暂存区和未跟踪文件的说明。页面内容可能随 Git 版本更新。
项目理解报告写完后，下一轮任务可以直接引用其中的文件路径、证据、风险和验证命令。
### Codex 修复可复现 Bug：让补丁只解决当前问题
URL: https://codexguide.io/guides/codex-xiu-fu-ke-fu-xian-bug
示例问题是订单列表偶尔显示 NaN。复现输入包括一个缺少金额字段的订单，期望界面显示占位符，实际结果是 NaN。没有复现步骤前，不要让 Codex 直接“修金额格式化”。
# Codex 修复可复现 Bug：让补丁只解决当前问题
> 测试环境 Windows 11 24H2（Build 26100）；PowerShell 7.6.4；Codex CLI 0.147.0；Git 2.47.0；2026-08-30 核验。
## 先固定现象
示例问题是订单列表偶尔显示 `NaN`。复现输入包括一个缺少金额字段的订单，期望界面显示占位符，实际结果是 `NaN`。没有复现步骤前，不要让 Codex 直接“修金额格式化”。
如果你想先看完整的任务分工，可以浏览 CodexGuide 的[工作流页面](https://codexguide.io/codex/workflows)，再回到这里收窄修复范围。
先保存现场。
```powershell
git status --short --branch
rg -n "formatAmount|NaN|订单金额" src test
```
图一 缺失金额的订单输出 `¥NaN`，正常金额仍显示为 `¥12.50`。
## 先问根因，再写补丁
```text
请调查订单金额显示 NaN 的问题，先不要改文件。
用给定复现输入追踪原始值、格式化函数和调用方，说明 NaN 在哪一层产生。
列出最小修改文件、应保持不变的输入输出、直接回归测试和无法确认的假设。
不要顺手重构金额模块。
```
如果后端没有返回金额字段，格式化函数拿到的就是 `undefined`。这时直接执行 `Number(value).toFixed(2)` 会得到 `NaN`。补丁只处理这个边界，正常金额仍按现有规则格式化。根因和修复位置必须对应。
图二 从稳定复现开始，经过根因定位和最小修改，最后用定向测试确认结果。
图三 `undefined` 在格式化入口转成 `NaN`，修复只处理缺失值并保留正常金额格式。
## 最小修复的形状
要求 Codex 按这个顺序工作。
1. 在现有格式化函数入口处理缺失值，保留正常数字和已有货币格式。
2. 增加一个缺失值测试和一个正常金额测试。
3. 用原始复现输入运行定向测试和手工命令。
每一步后看 diff。若出现 API 参数改名、页面重排或全局类型整理，说明补丁已经偏离问题。
图四 差异集中在 `src/formatAmount.js` 的缺失值分支，测试文件和其他模块保持不变。
## 区分修复与掩盖
把 `NaN` 替换成空字符串可能让截图好看，却会把数据异常藏起来。先确认产品约定。缺失金额是显示 `--`、0，还是阻止订单进入列表。显示层只能执行已确认的约定，不能替业务决定默认值。
图五 真正的修复明确处理缺失值并保留异常线索，表面掩盖只是把错误输出藏起来。
## 交付检查
```text
复现输入：金额字段缺失的订单。
根因：格式化入口未处理缺失字段带来的 undefined。
修改：金额格式化函数 + 直接回归测试。
保持：正常金额格式、接口参数、订单排序。
验证：缺失值、正常值、原始列表命令。
未覆盖：后端返回非数字字符串的情况。
```
图六 缺失值测试与正常金额测试均通过，复现输出变为 `A-101: --`，`A-100` 的格式保持不变。
日志、调用栈和完整回归方法放在 [06-测试调试与质量保障](../06-测试调试与质量保障/)。本篇的重点是让一个可复现问题对应一个可审查补丁。
## 继续实践
如果你准备把这套排查方法放进真实项目，可以到 CodexGuide 的[验证流程](https://codexguide.io/codex/validation)，继续练习如何把 diff、测试和最终状态整理成可复查的证据。
### Codex 多文件改动：接口、类型和界面如何保持同步
URL: https://codexguide.io/guides/codex-duo-wen-jian-gai-dong-jie-kou-lei-xing-jie-mian
接口、共享类型和界面一起变化时，最容易漏掉的是契约。后端已经返回新字段，类型文件还没更新，组件只能靠猜；类型更新了，旧数据又可能在运行时变成 undefined。这类问题通常要改四个文件，排查却不能按文件名挨个改。
# Codex 多文件改动：接口、类型和界面如何保持同步
> 测试环境：Windows 11 24H2（Build 26100）；PowerShell 7.6.4；Codex CLI 0.147.0；Git 2.47.0；2026-08-30 核验。
接口、共享类型和界面一起变化时，最容易漏掉的是契约。后端已经返回新字段，类型文件还没更新，组件只能靠猜；类型更新了，旧数据又可能在运行时变成 `undefined`。这类问题通常要改四个文件，排查却不能按文件名挨个改。
本文用一个订单列表需求说明做法。接口增加可选的 `displayName`，列表优先显示它，旧订单没有这个字段时继续显示 `orderId`。数据库、路由、排序和点击行为都留在范围外。
如果你还在熟悉如何把需求写成可执行约束，可以先看《别再对 Codex 许愿：一张任务单让它少走弯路》，再回到这个跨文件例子。
## 先把接口变化写成矩阵
动手前先把数据从哪里来、经过哪些层、最后由谁消费写出来。下面这张表就是本次改动的边界。
| 文件/层 | 作用 | 本次动作 | 保持不变 |
|---|---|---|---|
| `server/orders.ts` | 组装响应 | 增加可选字段 | 查询条件和状态码 |
| `shared/order.ts` | 类型契约 | `displayName?: string` | 现有字段类型 |
| `web/OrderRow.tsx` | 展示数据 | 有名称显示名称，否则回退订单号 | 排序和点击行为 |
| `test/orders.spec.ts` | 直接验证 | 覆盖有字段和无字段两例 | 既有 API 断言 |
矩阵里同时写“本次动作”和“保持不变”。只写要改什么，Codex 仍可能顺手改路由或把所有订单字段改成必填。表格还会提醒你检查生产调用方，避免只改类型声明，忘了读取数据的组件。
## 先确认数据形状
“增加一个字段”这句话还不够具体。要先确认字段出现在哪一层，值可以缺失到什么程度，以及空字符串是否和缺失值有不同含义。
这次示例把 `displayName` 定义成可选字符串。后端有名称时返回字符串，没有名称时省略字段，旧订单仍只返回 `orderId`。如果接口实际返回 `displayName: null`，类型就应该写成 `displayName?: string | null`，组件也要采用同一套判断。不要让后端、类型和前端各自猜一种写法。
还要检查列表接口和详情接口是否共用同一个响应类型。若列表只需要名称，详情却还没有这个字段，可以先保持两份 DTO 的边界，不能为了省一个类型文件把详情响应也改掉。接口文档、序列化代码和测试样例最好使用同一份字段示例，读者看到的契约才是完整的。
可以让 Codex 先输出一份数据流摘要，确认它没有把“接口字段”误当成“数据库字段”。摘要只需要回答四件事。
- 响应由哪个函数组装。
- 共享类型从哪里被导入。
- 哪些组件读取这个字段。
- 缺失、为空和为 `null` 时分别应该显示什么。
如果这四件事中有一件没有证据，就先停在调查阶段。跨文件任务的成本通常不在写代码，而在修正一个错误假设后重新检查所有消费者。
## 按数据流安排改动顺序
这次应按 `server → shared type → web → test` 推进。先确认响应到底在哪里组装，再把字段写进共享类型，接着处理界面回退，最后用测试固定两种数据形状。顺序反过来，测试很容易围绕一个尚未确定的接口打转。
可以把下面这段任务直接交给 Codex。
```text
请为订单响应增加可选 displayName，并在列表中展示。先只读确认响应组装、共享类型、列表组件和直接测试的路径。按 server → shared type → web → test 的顺序改动；displayName 缺失时回退 orderId；不要改数据库、路由、排序和点击行为。每一步完成后展示 git diff --name-only；发现实际 DTO 或调用方与假设不一致时停下来报告，不要扩大范围。
```
先让它报告真实入口和计划，再批准编辑。第一轮只改响应和类型，第二轮处理组件，第三轮补测试。每轮结束都看 `git diff --name-only`，文件集合一旦超出矩阵，就回到计划重新判断。
如果仓库使用自动生成类型，顺序要稍微调整。先确认生成文件的来源和生成命令，再修改源 DTO 或接口描述，最后运行生成步骤。生成文件通常不应该手工编辑，锁文件和格式化结果也不应因为一次字段增加而被顺手重写。把生成文件是否纳入提交写在计划里，避免 Codex 一边改源文件，一边留下没有来源的手工补丁。
跨层核对时，可以按同一个字段名向下追踪。
```text
displayName
server/orders.ts 响应是否真的写入
shared/order.ts 类型是否允许缺失
web/OrderRow.tsx 读取后是否有回退
test/orders.spec.ts 有值和缺失值是否都断言
```
这份小清单能防住一种常见遗漏。类型文件已经声明了字段，组件也编译通过，但后端响应组装函数从未赋值。静态检查会放行，页面却永远走回退分支。反过来，后端返回了字段，类型却仍然没有声明，调用方可能被迫使用类型断言，问题会被推迟到运行时。
## 类型变了，调用方要跟着收紧
`displayName?: string` 表示旧订单仍然合法。组件不要直接渲染可能为空的字段，而要明确写出回退规则，例如 `order.displayName ?? order.orderId`。这里的回退是产品约定，不能为了让编译通过随手改成 `any`，也不能把缺失名称显示成空白后就当作完成。
回退规则要在界面和测试里使用同一份表达。假设订单名称为空字符串时也要回退，那么 `??` 就不够了，需要先把空白判断写清楚，再决定使用 `||`、辅助函数还是后端清洗。这个选择不能藏在一行难读的表达式里，任务说明和测试名称都应该让后来的人看懂产品约定。
如果同一个字段被多个列表组件读取，先列出调用方，再决定是否抽一个格式化函数。只有当回退规则完全一致时才适合共享；一个页面需要显示“未命名”，另一个页面需要显示订单号，就应该保留各自的展示策略。共享函数的价值是减少重复判断，不是把不同产品语义压成一个默认值。
如果调查发现后端实际返回的是另一份 DTO，先停下来指出真实类型来源。不要同时保留两套接口，也不要把共享类型改宽来掩盖不一致。确认 DTO 后，再决定是调整类型入口，还是让响应组装层遵守现有契约。
## 验证要覆盖两种返回
跨文件修改至少要验证有名称和无名称两条路径。直接测试检查接口字段和回退结果，类型检查负责发现遗漏的调用方，手工数据则确认界面真的显示了预期文本。
```powershell
# 按项目已有脚本替换下面两个命令
npm test -- orders
npm run typecheck
```
验证结束后再看工作区状态，确认没有生成文件或计划外改动。初始化阶段的两个结构校验结果如下，代码测试仍应在实际项目中单独执行。
图一 PowerShell 初始化工作区后，工作区校验和素材清单校验均通过。
测试用例可以按数据形状分成四个检查点。接口返回名称时，响应应包含字符串，列表显示名称；接口省略名称时，响应仍能通过类型检查，列表显示 `orderId`；如果项目允许 `null`，还要单独覆盖 `null`；最后确认既有字段和排序结果没有变化。测试不一定要写成四个文件，关键是每个断言都对应一个约定。
手工验证和自动测试也要分工。自动测试适合锁定字段类型、回退文本和参数边界，手工检查适合确认真实页面没有出现空白行、重复请求或布局跳动。若接口通过网络层做了字段转换，最好再加一次接近真实响应的测试，避免只测本地构造对象。
类型检查通过也不代表所有消费者都安全。检查结果只说明当前编译入口能接受这份类型，未被编译的脚本、旧版页面和其他服务仍可能依赖旧响应。交付说明里把这些消费者列出来，至少写明已经检查过的调用方和仍未覆盖的入口。
## 交付说明写清楚边界
交付时把契约变化、兼容策略和验证证据放在一起，接手的人不用重新翻完整 diff。
```text
修改文件：server/orders.ts、shared/order.ts、web/OrderRow.tsx、test/orders.spec.ts。
契约变化：响应增加可选 displayName，缺失时由界面回退 orderId。
保持不变：查询条件、状态码、排序、点击行为和其他字段类型。
已验证：有 displayName、无 displayName、API 直接测试、类型检查。
未验证：其他订单消费者和大数据量列表的性能。
当前状态：工作区有未提交改动；未提交、未推送。
```
“未验证”要写具体对象。只写“已完成”无法告诉别人哪些调用方还需要人工确认，也不能证明兼容策略真的覆盖了旧数据。
如果验证中途失败，先把失败归类，再决定下一步。字段没有出现在响应里，优先回到组装函数；类型报错集中在旧组件，先确认它是否真的消费同一份 DTO；测试只在缺失值场景失败，则检查回退约定和空值判断。不要一看到红色输出就把类型改宽，类型变宽只会让错误更晚出现。
当 diff 里出现计划外文件时，可以先用下面的命令把范围列出来，再逐个判断是否属于生成物或必要变更。
```powershell
git diff --name-only
git status --short
```
临时文件可以清理，必要变更要回到矩阵补上原因。没有理由的文件不要留在补丁里，也不要用一次全仓库格式化来“顺便整理”。跨文件任务的交付标准是每个文件都能解释，验证结果也能对应到具体行为。
## 什么时候应该停下来
- 计划中的文件路径和实际仓库不一致时，先报告入口，不要猜路径。
- diff 出现数据库、路由、锁文件或无关组件时，先缩小范围。
- 类型检查失败但根因不明时，保留失败输出，先定位数据形状和调用方。
如果你准备把这套方法放进真实开发任务，可以继续看 [CodexGuide 验证流程](https://codexguide.io/codex/validation)，按 diff、测试和最终状态逐项核对。
### Codex 升级依赖：从 package 文件到兼容性确认
URL: https://codexguide.io/guides/codex-sheng-ji-yi-lai-package-jian-rong-xing
依赖升级的命令通常只有一行，影响却会落到导入路径、运行时版本、锁文件和下游调用方。把 date-fns 从 v2 升到 v3，当作一次小型变更来处理，能更早发现问题，也更容易回滚。
# Codex 升级依赖：从 package 文件到兼容性确认
> 测试环境：Windows 11 24H2（Build 26100）；PowerShell 7.6.4；Codex CLI 0.147.0；Node.js 22.22.3；npm 10.9.8；Git 2.47.0；2026-09-03 核验。
依赖升级的命令通常只有一行，影响却会落到导入路径、运行时版本、锁文件和下游调用方。把 `date-fns` 从 v2 升到 v3，当作一次小型变更来处理，能更早发现问题，也更容易回滚。
多数升级事故都从同一个动作开始。执行的人把升级当成一次顺手的维护，命令敲完，终端没出现红字，就默认这件事已经结束。新版本自己带 bug 的情况其实少见，麻烦往往几天后才浮出来。某个只在生产环境才会走到的分支开始报错，某个格式化函数悄悄换了默认行为，或者同事拉下代码后装出了一份和你完全不同的依赖树。把升级拆成基线、调查、最小改动、验证、回滚五个动作，多花十几分钟，换来的是出问题时能立刻说清改了什么、怎么退回去。
这里用 `date-fns` 举例，是因为它足够典型。大版本之间调整过模块入口和部分 API，项目里又常常散落着几十处调用。换成任何一个被广泛引用的包，流程都一样。
如果你还不熟悉“先调查、后修改”的 Codex 工作方式，可以先阅读《别急着让 Codex 改代码：先让它交一份只读调查报告》，再回到本文执行依赖升级。
## 先确认升级前的状态
先不要安装新版本。进入项目根目录，确认当前分支、工作区、包管理器和运行时版本。
```powershell
git status --short --branch
Get-ChildItem package.json,pnpm-lock.yaml,package-lock.json,yarn.lock -ErrorAction SilentlyContinue
node --version
npm --version
```
你需要得到一个明确的基线。当前分支是什么，工作区是否干净，项目实际使用哪一个锁文件，Node 和 npm 处于什么版本。没有基线，后面的 diff 很难判断哪些变化来自这次升级。
这四条命令里最容易被跳过的是锁文件那一条。同一个仓库里同时存在 `package-lock.json` 和 `pnpm-lock.yaml` 并不罕见，通常是历史迁移留下的残留。这时你用哪个包管理器安装，就会写坏另一份，而 CI 很可能仍然按旧的那份还原依赖。先确认仓库实际认哪一份锁文件，再决定用 npm、pnpm 还是 yarn。
工作区是否干净同样重要。如果 `git status` 里已经躺着几处未提交的修改，安装之后的 diff 就会混杂两类改动，你既没办法单独审查升级结果，也没办法干净地回滚。遇到这种情况，先把手上的改动提交或者用 `git stash` 收起来，再开始升级。
顺手记录一下本地 Node 版本和生产环境是否一致。本地 22.x、线上还在 18.x 的组合非常常见，而不少包的大版本升级正好会抬高 `engines` 要求。本地装得上、跑得通，不等于部署时也能通过。
图一 先记录分支、工作区、锁文件和运行时版本，后面的 diff 才有可比较的参照物。
## 先做只读兼容性调查
接着让 Codex 只读检查，不安装、不改文件。提示词可以直接这样写。
```text
评估 date-fns v2 → v3 的升级，不要先安装或修改文件。
读取 package.json、锁文件、运行时版本和所有 date-fns 导入；列出破坏性变更、受影响文件、建议升级顺序、验证命令和回滚点。
不要顺手升级其他依赖。无法确认某个 API 是否兼容时，明确标记未知。
```
这段提示词里有三处限制在起作用。“不要先安装或修改文件”把这一轮锁死在只读范围内，你才有机会在改动发生之前否决整个计划；“不要顺手升级其他依赖”防止一次升级被扩散成一次大扫除；“无法确认时标记未知”则是在给后面的验证留线索。测试和手工核对就该重点盯着被标成未知的那几处。
调查结果至少要回答五个问题。项目在哪些文件里导入或调用了目标包，升级是否会触及模块入口或 API，当前 Node 版本是否满足要求，锁文件会怎样变化，失败时从哪里恢复。
这一步如果只得到“可能存在 breaking changes”，信息还不够。继续追问具体导入、调用点和验证方式，直到计划能指导下一步操作。
追问时可以把问题问死。哪些导出在新版本被移除或改名，项目里哪几行代码用到了它们，替代写法是什么。让 Codex 把结论落到文件名和行号上，你才有办法自己核对一遍。官方迁移文档同样值得打开，它列出的破坏性变更清单，正好用来检查调查报告有没有漏项。
如果调查发现改动点超过十几处，或者集中在公共工具函数上，那就不该继续按“一次升级”推进。更稳妥的做法是先提一个只做适配、不换版本的准备补丁，把调用方式统一到新旧都兼容的写法上，再单独提交版本升级。
图二 只读调查先列出破坏性变更、受影响文件、验证命令和回滚点，再决定动不动手。
## 只升级一个目标包
计划确认后，再执行最小安装。下面以 npm 为例。
```powershell
npm.cmd install date-fns@3.6.0 --save-exact --ignore-scripts
```
`--save-exact` 让目标版本保持清晰，`--ignore-scripts` 则避免安装阶段额外执行生命周期脚本。实际项目是否使用这两个选项，要结合仓库现有约定决定。这一轮只应改变目标依赖和必要的锁文件内容。
安装完成后，先看范围，再看结果。
```powershell
git diff -- package.json package-lock.json
npm ls date-fns
npm run check
npm test
```
这四条命令的顺序是有意安排的。`git diff` 先回答“改了什么”，`npm ls` 回答“最终装成了什么”，后两条才回答“还能不能跑”。跳过前两步直接跑测试，即使测试通过，你也说不清这份通过建立在哪一棵依赖树上。
`npm ls date-fns` 尤其值得多看一眼。如果输出里出现两个不同版本，说明还有别的依赖锁着旧版本，代码运行时用到的可能并不是你刚装上的那个。这类重复依赖不一定要立刻处理，但必须在这一步被看见，而不是留到线上报错时才发现。
如果 diff 里出现其他无关依赖、源码格式化或构建配置变化，先停下来处理，不要把多种变更混在一次升级里。
验证命令要按项目实际情况替换。`npm run check` 和 `npm test` 只是占位，有的项目该跑类型检查，有的该跑构建。也可能需要一段专门针对该依赖的手工脚本。判断标准很简单。这条命令失败时，能不能定位回这次升级。
图三 diff 只落在 package 文件和锁文件上，定向检查与测试随后补上通过证据。
做到这里，升级是否可接受就有了可检查的证据。目标版本发生了变化，必要的锁文件同步更新，定向检查和测试通过，工作区里没有混入其他文件。
## 用一张图记住判断顺序
图四 package 文件、代码调用、运行环境、变更边界、验证与回滚，五项缺一不可。
依赖版本只是入口。同一个版本号，在不同的 Node 版本和不同的锁文件下，装出来的依赖树可以完全不同，所以图里这五项都得各自确认一遍。
五项里，前三项决定升级能不能做，后两项决定升级做砸了会不会疼。经验不足时容易只盯着前三项，把回滚方案留到出事再想。而出事的时刻，往往正是发布窗口最紧张的时候，那时再去翻应该恢复哪几个文件，代价要大得多。
## 失败时怎么回滚
如果安装或验证失败，先恢复 package 文件和锁文件，再记录失败原因。
```powershell
git restore package.json package-lock.json
npm.cmd ci --ignore-scripts
git status --short --branch
```
这里用 `git restore`，是为了让锁文件和 package 文件一起回到同一个已知状态，手工编辑 `package.json` 做不到这一点。紧接着的 `npm ci` 会按恢复后的锁文件重装 `node_modules`，把磁盘上的依赖树也拉回基线。只改文本、不重装，很容易留下一个“文件是旧的、node_modules 是新的”的中间态，后续排查会格外困惑。
不要在回滚时顺手修改业务代码。若确实需要增加兼容适配层，把适配层作为单独改动，并写清楚删除条件，避免它变成长期没人维护的临时补丁。
记录失败原因这一步不要省。把报错信息、失败的命令和当时的版本号留进 issue 或一段笔记，下次再尝试同一个升级时，能直接省掉一轮重复调查。升级失败不算白做，至少下次不用再从头猜一遍。
## 最后检查这六项
- 升级范围只有目标依赖和必要的锁文件变化。
- 所有导入点、调用点和受影响 API 都已列出。
- Node、npm 与项目实际运行环境的边界已确认。
- 安装、定向检查、测试或构建至少完成一组有效验证。
- diff 中没有无关依赖、格式化文件或配置漂移。
- 保留了可以恢复到升级前状态的回滚点。
六项都通过之后，再把结论写进提交信息。升级了哪个包，从哪个版本到哪个版本，做过哪些验证，还有哪些已知未覆盖的风险。几个月后有人排查异常行为，`git log` 里的这几句话通常比翻文档更快。
图五 基线、调查、最小改动、验证、回滚，一轮升级在这五步里闭合。
换成 pnpm 或 yarn，只需要替换安装与还原命令，判断顺序不变。需要同时升级多个包时，最好一个一个来，每个都单独留一个可回滚的提交点。
如果你准备把这套流程固定到日常开发里，可以继续看 [Codex 工作流，从任务到可回滚结果](https://codexguide.io/codex/workflows)，把计划、最小修改和验证串成一条能重复执行的流程。
### 从零创建 Codex Skill
URL: https://codexguide.io/guides/create-codex-skill
如果一段提示词需要反复复制，或者同一项工作每次都要重新说明步骤、输入和验收条件，可以把这套做法整理成 Skill。Codex 会先读取 Skill 的名称和描述，任务匹配后再加载完整说明，需要时继续读取参考资料或运行脚本。
# 从零创建 Codex Skill
> 难度 进阶
>
> 类型 Skill 编写与调试
如果一段提示词需要反复复制，或者同一项工作每次都要重新说明步骤、输入和验收条件，可以把这套做法整理成 Skill。Codex 会先读取 Skill 的名称和描述，任务匹配后再加载完整说明，需要时继续读取参考资料或运行脚本。
这篇教程会创建一个最小可用的 Skill，并检查显式调用和自动触发是否符合预期。示例只写文件，不连接外部服务，也不会运行付费操作。
> 原稿示意图，非 Codex 产品界面。图中的工作流用来解释 Skill 如何保存重复步骤。
## Skill 适合保存什么
Skill 适合边界清楚、会重复出现、结果能够检查的工作。例如按团队格式创建变更日志、检查发布文件、生成固定结构的项目目录，或者把一套人工检查步骤交给 Codex 执行。
一次性的临时任务通常不需要 Skill。流程还在频繁变化时，也可以先把提示词跑顺，确认输入、输出和失败条件后再整理。这样写出来的说明更短，触发范围也更准确。
## 一个 Skill 目录里有什么
最小 Skill 只需要一个目录和其中的 `SKILL.md`。文件开头的 YAML 元数据必须提供 `name` 和 `description`，后面是 Codex 选中 Skill 后读取的操作说明。
```text
my-skill/
└── SKILL.md
```
复杂工作可以继续加入这些目录。
```text
my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── agents/
└── openai.yaml
```
需要稳定执行的程序放进 `scripts/`，较长的规范和资料收进 `references/`。模板等资源归到 `assets/`，`agents/openai.yaml` 用于补充展示和依赖信息。没有实际用途的目录不要提前创建。
> 原稿示意图，目录结构按 OpenAI 当前 Skill 文档复核。
## 选择个人目录还是项目目录
个人 Skill 放在用户目录下，适合自己在多个项目中复用。项目 Skill 放进仓库，适合团队共享并随代码一起审查。
```text
$HOME/.agents/skills/my-skill/SKILL.md
.agents/skills/my-skill/SKILL.md
```
Windows 环境中的实际用户目录会随安装方式变化。创建前可以先查看当前 Codex 的 Skills 列表和已发现路径，不要照抄别人的绝对路径。
项目 Skill 可以提交到 Git。个人 Skill 通常留在本机，除非你准备把它包装成可以分发的插件。
## 写一个最小可用的 Skill
下面创建一个 `release-note` Skill。它接收一组已经确认的改动，把内容整理成简短发布说明，并明确禁止编造测试结果。
```md
---
name: release-note
description: 根据已经确认的代码改动和验证结果生成中文发布说明。用户要求写发布说明、版本说明或 changelog 摘要时使用；缺少真实改动或验证证据时不要猜测。
---
# 发布说明
1. 读取用户提供的改动摘要、提交或 diff。
2. 区分新增、修复和已知限制，只保留有证据的内容。
3. 使用简短中文说明用户能够感知的变化。
4. 保留版本号、命令、文件名和链接的原始写法。
5. 没有执行过的测试标记为未验证，不得写成已经通过。
输出一段发布摘要和一份变更列表。
```
`description` 决定 Codex 能否发现这个 Skill。它需要同时说明用途、触发场景和边界。只写“帮助处理发布工作”范围太宽，容易误触发；把所有例外都塞进描述又会让入口信息过长。详细步骤留在正文里。
## 渐进式加载怎样节省上下文
Codex 启动时不会把所有 Skill 全文塞进上下文。它先看到名称、描述和路径，选中某个 Skill 后才读取 `SKILL.md`。引用资料和脚本也只在流程需要时加载。
> 原稿示意图。图中的比例用于解释渐进式加载，实际上下文占用由已安装 Skill 数量和描述长度共同决定。
因此，主文件应该保留执行流程和关键边界。大段背景资料可以移到 `references/`，稳定且需要精确重复的动作才适合写成脚本。脚本会直接在工作环境里运行，涉及删除、网络、凭据或外部计费时要保留明确的审批步骤。
## 测试显式调用
在 Codex CLI 或 IDE 扩展中，可以运行 `/skills` 查看已经发现的 Skill，也可以在提示中输入 `$` 选择并显式调用。
```text
使用 $release-note，根据当前分支相对 main 的提交写一份发布说明。先读取 diff 和测试结果，不要修改文件。
```
显式调用适合第一次测试。检查结果时重点看三件事。
1. Codex 是否读取了正确的 `SKILL.md`。
2. 输出是否遵守了输入和验证边界。
3. Skill 是否执行了任务之外的动作。
如果找不到 Skill，先检查目录层级、文件名和 YAML 格式，再确认当前入口支持 Standalone Skill。
## 测试自动触发
显式调用通过后，再用自然语言测试 `description`。
```text
根据这个分支的改动写一份中文 changelog 摘要，未运行的检查要标出来。
```
还要准备一个不应该触发的任务。
```text
帮我解释 changelog 这个词是什么意思，不要读取项目文件。
```
第一个任务应该命中 `release-note`，第二个任务只需要普通回答。两边都测试，才能发现描述写得太窄还是太宽。
## 什么时候加入脚本和参考资料
纯说明能完成工作时，先保持纯说明。下面这些情况再考虑加脚本。
- 同一条命令必须稳定执行，并且参数和输出格式清楚。
- 人工复制步骤容易出错，脚本可以先做只读检查或 dry run。
- 验证需要解析结构化结果，靠文字判断不够可靠。
参考资料适合保存字段定义、团队规范和长示例。`SKILL.md` 应当告诉 Codex 何时读取哪份资料，避免把整个参考目录一次加载。
> 原稿示意图。实际效果取决于 Skill 的边界、材料质量和验证步骤。
## 发布前检查
- `SKILL.md` 包含有效的 `name` 和 `description`。
- 名称与目录用途一致，描述写清触发条件和边界。
- 每一步都有明确输入、动作和输出。
- 没有把 Token、账号和机器绝对路径写进共享 Skill。
- 涉及写入、删除、网络和付费操作时保留审批与失败处理。
- 显式调用、应该自动触发和不应该触发的提示都测试过。
- 项目 Skill 的脚本和引用文件已经纳入 Git 审查。
## 参考资料
- [OpenAI Build skills](https://developers.openai.com/codex/skills)
- [OpenAI Codex customization](https://developers.openai.com/codex/concepts/customization)
- [OpenAI Codex best practices](https://developers.openai.com/codex/learn/best-practices)
- [原始公众号文章](https://mp.weixin.qq.com/s?__biz=MzAwMDg5MTAyMw==&mid=2247521461&idx=1&sn=c1991f8612a6443af76cff8df9cc4ad3&chksm=9b5043639049220389dab5485957088b07b83dae4657aa9d47bc2681478d50b24baba1796131#rd)
本文根据 OpenAI 2026 年 8 月 18 日可访问的 Skill 文档核对。不同 Codex 入口对 Standalone Skill 和插件 Skill 的支持范围可能不同。
### Codex 处理 GitHub Issue 并创建 Pull Request
URL: https://codexguide.io/guides/codex-github-issue-to-pr
这篇教程写给已经使用 GitHub Issue 和 Pull Request 管理开发任务的读者。你需要先把目标仓库连接到 Codex cloud，并且拥有查看代码、创建分支和提交 Pull Request 所需的权限。
# Codex 处理 GitHub Issue 并创建 Pull Request
> 难度 进阶
>
> 类型 GitHub 协作与代码审查
这篇教程写给已经使用 GitHub Issue 和 Pull Request 管理开发任务的读者。你需要先把目标仓库连接到 Codex cloud，并且拥有查看代码、创建分支和提交 Pull Request 所需的权限。
完整流程从一条可执行的 Issue 开始。Codex 在云环境中完成代码任务，人检查改动后创建 Pull Request，再通过 `@codex review` 请求一次针对严重问题的代码审查。最后是否合并仍由仓库维护者决定。
> 原稿流程示意图，非 GitHub 或 Codex 产品界面。图中的合并状态只表示工作流终点，不代表 Codex 会自动合并。
## 开始前准备仓库
Codex 需要能够访问目标 GitHub 仓库。先在 Codex cloud 中连接 GitHub 账号或组织，为仓库创建环境，并确认初始化步骤能够安装依赖、运行项目和执行测试。
代码审查还需要单独启用。
1. 打开 [Codex code review 设置](https://chatgpt.com/codex/settings/code-review)。
2. 为目标仓库打开 Code review。
3. 准备一个小型 Pull Request 测试手动审查。
4. 确认流程稳定后，再决定是否启用 Automatic reviews。
自动审查需要连接仓库，并且配置者拥有相应的 GitHub push 或 admin 权限。
> 原稿配置示意图。实际开关名称和位置以 Codex 当前设置页为准。
## 把 Issue 写成可执行任务
Issue 至少要让执行者看懂问题、范围和验收方式。只有一句“增加深色模式”通常会留下很多产品和技术选择，Codex 也无法知道哪些文件不能改。
可以按下面的结构整理。
```md
## 目标
在设置页增加深色模式开关，并记住用户选择。
## 范围
- 只修改前端主题和设置页。
- 不调整账号接口和数据库。
## 验收
- 开关可以在浅色和深色之间切换。
- 刷新页面后保持上一次选择。
- 现有前端测试通过。
## 限制
- 不新增 UI 组件库。
- 不修改其他页面的布局结构。
```
Issue 中可以继续附上报错、截图、相关文件和已有讨论。涉及密钥、生产数据或内部地址时，不要把敏感内容写进公开 Issue。
## 从 Issue 启动 Codex 云任务
OpenAI 当前文档明确支持 Codex cloud 读取连接仓库并在隔离环境中执行任务。具体入口会随 Codex 产品界面变化，稳妥做法是在 Codex 中创建云任务，把 Issue 链接作为上下文，并补充仓库、目标分支和完成条件。
```text
请处理这个 GitHub Issue。
仓库已连接到 Codex cloud。先读取 Issue、仓库 AGENTS.md 和相关测试，说明准备修改的范围。完成后运行现有测试并给出 diff 摘要。不要合并，也不要修改 Issue 范围外的文件。
Issue URL
https://github.com/OWNER/REPO/issues/1287
```
不要把“在 GitHub Issue 评论中输入 `@codex`”当成所有账号都具备的固定入口。OpenAI 官方文档对 `@codex review` 的明确说明针对 Pull Request 评论。Issue 阶段是否出现额外入口，要以当前工作区和已安装集成为准。
## 检查云任务结果
云任务在独立环境中运行，可以同时处理多个彼此独立的任务。隔离环境减少本地工作被占用的情况，仍然需要为每个任务设置清楚的仓库、分支和验证要求。
> 原稿示意图。并行任务是否可用以及并发额度取决于账号和工作区设置。
任务完成后先看改动摘要和 diff，再核对测试结果。下面几项不能省略。
- 修改是否仍在 Issue 约定范围内。
- 依赖、配置和生成文件是否有意外变化。
- 测试命令是否真的运行，退出状态是否成功。
- 新增行为是否有对应测试或人工验收方法。
- 日志和提交中是否出现凭据、个人信息或内部地址。
发现方向不对时，在同一个任务中给出具体反馈，让 Codex 修正后重新验证。不要因为摘要看起来合理就直接创建 Pull Request。
## 创建 Pull Request
改动通过人工检查后，再让 Codex 创建 Pull Request，或者把分支交给维护者自行创建。Pull Request 描述应保留 Issue 链接、修改范围、验证结果和未解决风险。
```md
## 改动
- 增加主题切换开关。
- 使用现有本地存储工具保存选择。
## 验证
- 前端测试已通过。
- 已人工检查刷新后的主题状态。
## 关联 Issue
Closes #1287
```
GitHub 的 Pull Request 页面会集中展示讨论、提交、Checks 和文件差异。维护者应当在这里检查自动测试、分支保护和必要审批，不要把 Codex review 当成唯一门禁。
## 在 Pull Request 中触发 Codex review
在已经启用 Code review 的仓库中，向 Pull Request 发表评论。
```text
@codex review
```
Codex 会先用眼睛表情回应，随后发布标准 GitHub code review。官方文档说明，这类 GitHub review 只报告 P0 和 P1 问题，用来减少低优先级风格意见带来的噪声。
需要临时关注某类风险时，可以把范围写在同一条评论里。
```text
@codex review for issues in the database migration
```
## 把团队审查规则写进 AGENTS.md
Codex review 会查找适用于改动文件的 `AGENTS.md`。仓库级规则放在根目录，某个服务的特殊规则可以放进更靠近代码的子目录。
```md
## Code Review Rules
### Payment safety
- Flag payment capture without an idempotency key.
- Flag amount validation that happens after an external charge.
- Leave formatting and lint checks to CI.
```
规则要描述会造成后果的行为，并写清安全路径或允许的例外。格式化、Lint 等确定性检查继续交给 CI。
> 原稿示意图。Codex 会同时采用覆盖改动文件的根级规则和更具体的目录规则。
## 根据审查意见继续修复
Codex 发布 review 后，可以在同一个 Pull Request 中要求它修复具体问题。
```text
@codex fix the P1 issue
```
Codex 会以当前 Pull Request 作为上下文启动云任务。它具备分支写入权限时，可以把修复推回该分支。CI 失败也可以使用明确指令继续处理。
```text
@codex fix the CI failures
```
修复提交仍然要经过 diff、测试和审批。新增提交可能改变原来的审查结论，重要修改应当重新请求 review。
## Codex 和维护者各自负责什么
Codex 可以读取 Issue 和仓库上下文、修改代码、运行测试、准备 Pull Request、审查 P0/P1 问题，并在有权限时推送修复。维护者负责配置环境和权限、定义审查规则、核对改动与测试，并执行最终合并。
> 原稿示意图。分支保护、必需审批和人工合并仍按仓库规则执行。
## 上线前检查
- Codex cloud 已连接正确仓库，环境初始化可以复现。
- Issue 写清目标、范围、限制和验收条件。
- 云任务没有访问任务之外的仓库和凭据。
- Pull Request 描述包含真实验证结果和剩余风险。
- `@codex review` 已返回结果，P0/P1 问题已经处理或记录。
- CI、分支保护和必要人工审批全部满足。
- 最终合并由有权限的维护者执行。
## 参考资料
- [OpenAI Codex cloud](https://developers.openai.com/codex/cloud)
- [OpenAI 在 GitHub 中使用 Codex review](https://developers.openai.com/codex/third-party/github)
- [OpenAI Codex code review](https://developers.openai.com/codex/code-review)
- [GitHub Issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue)
- [GitHub Pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
- [原始公众号文章](https://mp.weixin.qq.com/s?__biz=MzAwMDg5MTAyMw==&mid=2247521409&idx=1&sn=f787a786c39e53f2e69ea1f320dbf3ae&chksm=9bad188b7b0e52fdf576c0a84d551d2b411151d3c0c1f0ce842f74363f85f351cd34d42fc602#rd)
本文根据 2026 年 8 月 18 日可访问的 OpenAI 与 GitHub 官方文档核对。Codex cloud、代码审查开关和 GitHub 权限可能随工作区配置变化。
### Codex 如何读懂 Git，status、diff、log 与 blame
URL: https://codexguide.io/guides/codex-git-status-diff-log-blame
代码审查的第一步是先把比较范围说清楚。不要直接让 Codex 总结“这个提交做了什么”，因为当前工作区、暂存区、某个提交和远程分支可能是四个不同的现场。
# Codex 如何读懂 Git，status、diff、log 与 blame
> 难度 基础
>
> 类型 概念与实操
> 测试环境为 Windows build 26100、Codex CLI 0.147.0 和 Git 2.47.0.windows.2，2026-08-30 完成核验。
## 先问对问题
代码审查的第一步是先把比较范围说清楚。不要直接让 Codex 总结“这个提交做了什么”，因为当前工作区、暂存区、某个提交和远程分支可能是四个不同的现场。
四条命令各自回答一个问题。
| 命令 | 它主要回答 | 它不能单独证明 |
| --- | --- | --- |
| `git status` | 当前分支和文件处于什么状态 | 改动的具体行为是否正确 |
| `git diff` | 两个版本之间具体改了哪些内容 | 未跟踪文件是否已经纳入比较 |
| `git log` / `git show` | 提交按什么顺序发生，某次提交改了什么 | 提交信息里的动机一定真实 |
| `git blame` | 某一行最后由哪个提交写入 | 谁应该为问题负责，或这行最初为何存在 |
把它们连起来，才能形成可复核的证据链。`status` 定位现场，`diff` 读取行为，`log` 补历史，`blame` 在有疑问的行上继续追溯。
## 先固定比较基线
在 Codex 读取代码前，先在仓库根目录运行下面的只读命令。
```powershell
Get-Location
git rev-parse --show-toplevel
git branch --show-current
git rev-parse --verify HEAD
git status --short --branch
```
这里要记录当前目录、Git 根目录、分支名和 `HEAD` 的提交号。`HEAD` 是当前检出的提交，不一定是远程分支的最新提交；`status --short --branch` 中的 `ahead` 和 `behind` 只有在已配置跟踪分支、且比较基线明确时才有意义。
如果任务针对某个目标分支，再单独确认它是否存在。
```powershell
git show-ref --verify --quiet refs/remotes/origin/main; $LASTEXITCODE
git rev-parse --verify origin/main
```
命令返回非零只表示本地没有可用的 `origin/main` 引用，不表示应该马上拉取或切换分支。工作区有别人未提交的改动时，先记录现场，再由负责人决定是否同步或隔离。
## 一、`git status`，先读现场，再读内容
### 分支行和文件行
```text
git status --short --branch
```
可能看到下面的输出。
```text
## fix/login-error...origin/main [ahead 1, behind 2]
M src/components/LoginForm.tsx
M tests/login-form.test.tsx
MM src/api/login.ts
?? notes/repro.txt
```
第一行说明当前分支与远程跟踪分支已经分叉。文件名前的两个位置分别代表暂存区（Index）和工作区（Worktree）。
```text
M file.ts # 只改了工作区
M file.ts # 已暂存，工作区没有继续改
MM file.ts # 暂存后又继续修改
A file.ts # 新文件已暂存
D file.ts # 删除已暂存
?? file.ts # 未跟踪文件，尚未进入 Git 比较
```
`git status` 是状态摘要，不会告诉你某个函数具体改了几行。`??` 也不能直接当成临时垃圾，它可能是测试、迁移脚本或需要纳入提交的文档。先确认来源和敏感信息，再决定是否加入版本控制。
需要给脚本或 Codex 稳定解析时，可以使用下面的命令。
```powershell
git status --porcelain=v1 -b
```
不要把“工作区干净”误读成“已经和远程同步”。状态为空只说明相对当前 `HEAD` 没有已识别的工作区和暂存区改动；分支跟踪、远程引用是否最新，还要单独核对。
## 二、`git diff`，先说清楚比较哪两边
最常见的误判是只运行一次 `git diff`。它默认比较“工作区”和“暂存区”，不会显示已经暂存的内容，也不会列出未跟踪文件。
| 命令 | 比较范围 | 适合回答 |
| --- | --- | --- |
| `git diff` | 工作区 vs 暂存区 | 暂存后又改了什么 |
| `git diff --cached` | 暂存区 vs `HEAD` | 下次提交会包含什么 |
| `git diff HEAD` | 工作区和暂存区合计 vs `HEAD` | 当前所有已跟踪改动是什么 |
| `git diff origin/main...HEAD` | 合并基点到当前分支 | 当前分支相对目标分支新增了什么 |
| `git diff ^ ` | 提交的父提交 vs 该提交 | 某次提交实际引入了什么 |
审查前通常先看摘要和文件名。
```powershell
git diff --stat
git diff --name-status
git diff --cached --stat
git diff --cached --name-status
git ls-files --others --exclude-standard
```
再按比较范围展开。
```powershell
git diff -- src/api/login.ts
git diff --cached -- tests/login-form.test.tsx
git diff HEAD -- src/api/login.ts tests/login-form.test.tsx
git diff --check
```
命令末尾的 `--` 用来分隔选项和路径。文件名以短横线开头、或路径容易被误识别时，保留这个分隔符。`git diff --check` 只检查空白错误和冲突标记，不能证明逻辑、性能或安全性没有问题。
### 如何读一段 patch
```diff
@@ -18,7 +18,9 @@ function submitLogin() {
- setSubmitting(true);
+ setSubmitting(true);
+ setError(null);
return requestLogin(credentials);
```
`@@` 后面的数字是旧文件和新文件的行范围；`-` 是旧内容，`+` 是新内容，没有前缀的是上下文。先问“状态变化是什么”，再问“异常路径、权限边界和调用方是否也变化”。只看到一行 `setError(null)`，不能直接断言用户体验已经修好，还要查看失败分支和对应测试。
重命名和移动可能让文件列表看起来比实际行为复杂。
```powershell
git diff --name-status --find-renames HEAD~1 HEAD
git diff --summary HEAD~1 HEAD
```
Git 的重命名判断是基于相似度的启发式结果，不是文件系统事件。审查时要看内容差异，不能只看 `R` 标记。
## 三、`git log` 与 `git show`，把改动放回时间线
先看分支图和提交摘要。
```powershell
git log --graph --decorate --oneline --all -n 12
git log --format=fuller -n 5
git show --stat --summary
```
`log` 适合看顺序、分支和合并关系，`show` 适合查看某次提交的正文和 patch。提交信息是线索，不是事实的替代品。真正的行为证据仍然来自 diff、调用方和验证结果。
### 按文件或代码线索查历史
```powershell
git log --follow --oneline -- src/api/login.ts
git log -S'setSubmitting(true)' --oneline -- src/api/login.ts
git log -G'catch|finally' --oneline -- src/api/login.ts
git show -- src/api/login.ts
```
- `--follow` 在单个文件路径上追踪重命名前的历史；它不适合一次传入多个路径。
- `-S` 查找某段文本出现次数发生变化的提交，适合追踪一行配置或函数调用何时加入、删除。
- `-G` 按正则表达式匹配 diff 中的行，适合查找某类分支或 API 调用的历史变化。
这些选项只能缩小搜索范围。找到提交后，仍要用 `git show` 读完整上下文，尤其要注意后续提交是否改变了原先的假设。
## 四、`git blame`，追踪一行，不追究责任
怀疑某一行的默认值、异常处理或兼容逻辑时，再使用下面的命令。
```powershell
git blame -L 20,45 -- src/api/login.ts
```
输出中的短提交号、作者和日期表示该行最后一次被某个提交写入。下一步通常是打开对应提交并查看文件历史。
```powershell
git show -- src/api/login.ts
git log --follow --oneline -- src/api/login.ts
```
如果代码经历过格式化、文件移动或复制，可以尝试下面的命令。
```powershell
git blame -w -M -C -C -L 20,45 -- src/api/login.ts
```
`-w` 忽略空白变化，`-M` 检测同一文件内的移动，`-C` 尝试追踪从其他文件复制过来的代码。这些都是启发式判断，可能变慢，也可能在大规模重排后给出不稳定的归属。合并提交、批量格式化和 cherry-pick 也会让“最后修改者”与“最初设计者”不同。
因此，`blame` 能回答“这行最近由哪个提交改动”，不能回答“谁应该为线上问题负责”。把提交放回 Issue、PR、测试和后续修复的上下文，结论才有意义。
## 一次完整的只读阅读流程
假设 `status` 显示实现文件有未暂存修改，测试文件已暂存，还有一个未跟踪的复现说明。可以按下面顺序读取。
1. 记录仓库根目录、分支、`HEAD` 和 `status --short --branch`，把原有改动和本次任务分开。
2. 用 `git diff --stat`、`git diff --cached --stat` 和 `git ls-files --others --exclude-standard` 确认范围，避免漏读暂存文件或未跟踪证据。
3. 分别阅读 `git diff`、`git diff --cached`，最后用 `git diff HEAD` 检查合计效果。
4. 对每个行为变化查看 `git show` 或 `git log -- `，必要时用 `-S` 或 `-G` 找到引入它的提交。
5. 只有某一行的历史仍然不清楚时才用 `git blame`，并打开对应提交的完整 diff。
6. 把结论写成“事实、推断、未知、下一步验证”，不要把历史线索或文件名当成测试结果。
可以把证据整理成下面的表格。
| 项目 | 记录方式 |
| --- | --- |
| 事实 | `src/api/login.ts` 在工作区改变；失败分支新增 `setError(null)` |
| 推断 | 这可能会清理旧错误提示，但还要确认成功分支和组件渲染逻辑 |
| 未知 | 未看到网络超时、重复点击和取消请求的验证 |
| 下一步 | 查看调用方、相关测试，并运行项目已有的登录测试 |
这个表格不替代代码审查，但能防止把“看起来合理”写成“已经证实”。
## 给 Codex 的只读提示词
```text
先只读检查当前 Git 仓库，不要修改、暂存、提交、推送、拉取、切换分支或清理文件。
先运行并记录下面的信息。
- git rev-parse --show-toplevel
- git branch --show-current
- git rev-parse --verify HEAD
- git status --short --branch
- git diff --stat
- git diff --cached --stat
- git ls-files --others --exclude-standard
然后针对本次变更读取下面的内容。
- 工作区差异，git diff
- 暂存区差异，git diff --cached
- 相对 HEAD 的合计差异，git diff HEAD
- 最近提交，git log --graph --decorate --oneline --all -n 12
请按“事实、推断、未知、建议验证”四栏回答。
1. 哪些文件在工作区、暂存区或未跟踪列表中；
2. 每个差异改变了什么输入、状态、输出或错误路径；
3. 哪些判断还需要查看调用方、Issue、历史提交或测试；
4. 哪些文件看起来与任务无关；
5. 如果追踪单行历史，请给出 git blame 的提交号，并用 git show 复核上下文。
不要把未运行的测试写成“通过”，不要把 blame 的作者当成责任人。
```
如果只想追踪一个可疑常量，可以缩小范围。
```text
只读调查 `src/api/login.ts` 第 20 到 45 行的超时默认值。
先给出当前 diff，再用 git blame 和 git show 找到引入该值的提交。
区分这次提交实际改变的内容、提交信息声称的目的和仍然未知的兼容性影响。
不要修改文件，也不要补写不存在的测试结果。
```
拿 Codex 的回答与终端输出逐项对照。它如果漏掉 `git diff --cached`、未跟踪文件或比较基线，结论就不完整。
## 小练习，复现一条证据链
配套的 `git-baseline-demo` 位于第 01 篇文章的备份目录，是一个可丢弃的离线仓库，里面故意同时放了已暂存、未暂存和未跟踪改动。请在教程仓库根目录运行下面的命令。
```powershell
Set-Location -LiteralPath '.\\05-Git协作与代码审查\\01-Git协作前先检查什么-仓库分支与脏工作区-图片备份-20260830-2112\\temp\\git-baseline-demo'
git status --short --branch
git diff --stat
git diff --cached --stat
git diff HEAD -- src tests
git log --graph --decorate --oneline --all -n 8
```
练习时写下四个答案。
- 哪些文件只在工作区，哪些文件已经进入暂存区？
- `git diff` 和 `git diff --cached` 各自遗漏了什么？
- 最近提交的说明与 patch 是否描述了同一个行为？
- 哪一行值得用 `git blame` 继续追踪，追踪后还缺什么验证？
这个练习只读，不需要提交、推送或清理现场。若使用自己的测试仓库，先复制一份或创建临时分支，不要在真实项目里故意制造脏改动。
## 截图方案，三张足够
不需要为每条命令单独截图。进入上面的演示仓库后，依次执行三个停点；每个停点截一张终端图，保留命令和完整输出。
### 1. 现场摘要
```powershell
Write-Host '=== 1/3 baseline ==='
git status --short --branch
git diff --stat
git diff --cached --stat
git ls-files --others --exclude-standard
```
这张图证明分支关系、工作区改动、暂存区改动和未跟踪文件。看到 `?? notes/` 时不要展开或上传其中可能含有个人信息的文件。
### 2. 差异范围
```powershell
Write-Host '=== 2/3 diff ==='
git diff --name-status
git diff --cached --name-status
git diff HEAD -- src tests
git diff --check
Write-Host "diff-check exit=$LASTEXITCODE"
```
这张图证明默认 `diff`、暂存区 `diff` 和相对 `HEAD` 的合计差异。`diff-check exit=0` 只表示没有发现空白错误或冲突标记，不代表测试已经通过。
### 3. 历史与单行来源
```powershell
Write-Host '=== 3/3 history ==='
git log --graph --decorate --oneline --all -n 8
git log --follow --oneline -- src/LoginForm.txt
git blame -w -M -C -C -L 1,2 -- src/LoginForm.txt
```
这张图把提交时间线、文件重命名历史和行级归属放在一起。不要截取完整用户名、私有路径或业务数据；如果输出过长，只保留最近 8 次提交和目标行附近的结果，不要删掉命令本身。
## 常见误区与验收清单
- [ ] 能说明 `git diff`、`git diff --cached`、`git diff HEAD` 的比较两端。
- [ ] 能区分工作区、暂存区、未跟踪文件和远程分支关系。
- [ ] 能用 `git show` 把提交摘要还原成具体行为，而不是只复述提交信息。
- [ ] 发现重命名、复制或格式化后，知道 `blame` 结果可能只是启发式归属。
- [ ] 能指出 diff 中没有被现有测试或人工检查覆盖的行为。
- [ ] 没有把 `git blame` 当成责任追究工具，也没有把未运行的测试写成通过。
下面几种说法都不够严谨。
| 说法 | 问题 | 更好的写法 |
| --- | --- | --- |
| “`git status` 没输出，所以可以直接提交。” | 可能漏看远程关系、忽略文件或任务基线 | “相对当前 `HEAD` 没有已跟踪改动；分支同步和提交范围仍需确认。” |
| “`git diff` 为空，所以没有改代码。” | 已暂存改动和未跟踪文件不会出现在默认 diff | “默认 diff 为空；还需要看 `git diff --cached` 和未跟踪列表。” |
| “blame 显示了某人的名字，所以问题是他造成的。” | blame 只记录最后改动这行的提交 | “该行最后在某提交中变更，需结合提交上下文和后续验证判断。” |
## 与其他章节的关系
第 01 节负责进入任务前的仓库、分支和脏工作区检查；本文进一步解释如何阅读四类 Git 证据。第 03 节负责分支和 Worktree 的隔离选择，第 05 节负责可审查的 Commit 与 PR 文本，第 06 节负责 Code Review 的测试和风险判断。本文不替代这些章节，也不把只读检查扩展成自动提交或合并。
## 参考资料
- [Git diff documentation](https://git-scm.com/docs/git-diff)
- [Git log documentation](https://git-scm.com/docs/git-log)
- [Git status documentation](https://git-scm.com/docs/git-status)
- [Git blame documentation](https://git-scm.com/docs/git-blame)
### Codex Goal 模式：运行长任务
URL: https://codexguide.io/guides/codex-goal-mode-long-running-work
如果你已经会让 Codex 修改代码，但任务一长就容易失去方向，可以学习 Goal 模式。它适合有明确交付物、能够持续验证的迁移、重构、排错和发布前检查。
# Codex 使用 Goal 模式运行长任务
> 难度：进阶
>
> 类型：长任务与持续执行
## 这篇文章适合谁
如果你已经会让 Codex 修改代码，但任务一长就容易失去方向，可以学习 Goal 模式。它适合有明确交付物、能够持续验证的迁移、重构、排错和发布前检查。
Goal 是持续目标，不是一次性提示词。它会附着在当前会话上，帮助 Codex 在多轮工作中保持目标、约束和完成条件。
## 先写清楚完成标准
进入 Goal 前，先写三件事：要得到什么，不能改什么，怎样证明已经完成。比如：
```text
把 checkout 模块迁移到新的错误处理方式。
只修改 src/checkout 和对应测试，不改公共 API。
完成条件是测试通过、类型检查通过，并在最终报告中列出未覆盖的边界。
```
目标越具体，后续检查越容易。Goal 不会替你补齐模糊的产品决策，也不会因为持续运行就获得更大的文件或账号权限。
## 设置和管理 Goal
在 Codex App、CLI 或 IDE 扩展的输入框中使用 `/goal`。CLI 中可以这样操作：
```text
/goal 完成 checkout 错误处理迁移，并保持测试通过
```
当前目标可以用 `/goal` 查看，用 `/goal edit` 修改，用 `/goal pause` 暂停，用 `/goal resume` 继续，用 `/goal clear` 清除。
目标文本最长 4000 个字符。更长的背景、检查清单和接口说明应当放进项目文件，再让 Codex 先阅读它们。
## 让长任务按检查点推进
Goal 最适合有验证回路的任务。可以把工作分成几个检查点：
1. 先阅读项目和规则，输出影响范围。
2. 先改一个小切片，运行对应测试。
3. 再扩展到剩余文件，重复测试和 diff 检查。
4. 最后运行完整验证，说明仍然未知的部分。
不要只写“持续做到完成”。如果没有测试、构建或人工复核这样的停止条件，Goal 很容易把时间花在低价值的细节上。
## 预算、暂停和人工介入
Goal 会受当前会话的上下文、模型用量和运行环境限制。预算用尽、目标改变、遇到需要你决定的分歧时，任务都可能暂停。
暂停不是失败。你可以查看当前进展，补充约束，再继续。涉及生产环境、密钥、付款、删除数据或系统权限的步骤，仍应保留人工批准。
## 什么时候不该用 Goal
一次能在几分钟内完成的小修改，不需要 Goal。需求还没有定稿、成功标准无法检查、或任务需要不断做产品判断时，也应该先讨论和规划。
使用 Goal 的判断标准很简单：目标稳定，过程可以拆开，结果可以验证。满足这三点，长任务才值得交给它持续推进。
## 参考资料
- [Long-running work](https://developers.openai.com/codex/long-running-work)
- [Slash commands in Codex CLI](https://developers.openai.com/codex/cli/slash-commands)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
### Codex 使用 Subagents 并行处理任务
URL: https://codexguide.io/guides/codex-subagents-parallel-work
如果一个任务可以拆成几块互不修改同一文件的工作，可以让 Codex 把其中一部分交给 Subagents。它适合代码库探索、测试检查、日志分析和安全审查，也适合需要多个独立结论的调研。
# Codex 使用 Subagents 并行处理任务
> 难度：进阶
>
> 类型：多 Agent 协作
## 这篇文章适合谁
如果一个任务可以拆成几块互不修改同一文件的工作，可以让 Codex 把其中一部分交给 Subagents。它适合代码库探索、测试检查、日志分析和安全审查，也适合需要多个独立结论的调研。
Subagent 是独立的工作线程。主 Agent 负责拆分、分派、等待和汇总，子 Agent 返回结果后，主 Agent 再形成最终答案。
## 先拆出真正独立的工作
好的拆分有清楚的输入和输出。例如检查一个 Pull Request 时，可以分别让子 Agent 阅读项目结构、运行测试、分析日志和检查安全风险。每个线程都有自己的上下文，最后只把摘要交回主 Agent。
不适合并行的任务包括多个线程同时改同一组文件、前一步结果决定后一步输入、或需要共享一个正在变化的运行状态。那种任务应当按顺序执行。
可以这样描述一次分工：
```text
请把这次审查拆成四个独立任务：项目结构、测试、日志、安全。
每个子任务只读，不修改文件。
每个子任务返回发现、证据、风险等级和建议，最后由主任务汇总。
```
## 让子 Agent 返回固定格式
主 Agent 要汇总多份结果，子 Agent 的输出格式越接近，合并越省事。可以要求每个线程返回：
- 检查范围
- 发现的问题和文件位置
- 使用过的命令及结果
- 尚未确认的地方
- 一句话建议
主 Agent 不应把摘要当成未经核验的事实。需要时继续打开子 Agent 的完整结果，或自己复查关键文件和命令输出。
## 内置角色与自定义 Agent
当前 Codex 提供可直接使用的内置角色，常见分工包括通用任务、执行任务和偏阅读分析的任务。具体可用角色取决于当前客户端和版本，调用时以界面或官方文档为准。
需要固定团队分工时，可以在 `~/.codex/agents/` 创建个人 Agent，或在项目的 `.codex/agents/` 创建项目级 Agent。文件使用 TOML，里面可以写名称、说明和开发者指令，也可以覆盖模型、沙箱或 MCP 设置。
全局并发设置位于 `config.toml` 的 `[agents]` 配置中。`agents.max_concurrent_threads_per_session` 用来限制同一会话中同时打开的子 Agent 数量。不要把并发数当成性能保证，线程越多，汇总和复核的成本也会增加。
## 权限和冲突控制
子 Agent 继承父任务能看到的部分设置，但每个线程仍有自己的操作过程。涉及写入时，要给每个线程独立 worktree，或明确规定只有主 Agent 可以修改文件。
最稳妥的第一步是让所有子 Agent 只读探索，主 Agent 根据结果选择一个实现方案，再由单个执行线程修改。这样能减少并行写入造成的冲突。
## 参考资料
- [Subagents](https://developers.openai.com/codex/concepts/subagents)
- [Customization](https://developers.openai.com/codex/concepts/customization)
- [Configuration Reference](https://developers.openai.com/codex/config-reference)
### Codex 使用 Computer Use 操作桌面应用
URL: https://codexguide.io/guides/codex-computer-use-desktop-apps
当任务只能通过桌面应用完成，或者命令行和结构化插件拿不到所需信息时，可以考虑 Computer Use。它能看屏幕、点击窗口、输入文字并在多个应用之间完成一段流程。
# Codex 使用 Computer Use 操作桌面应用
> 难度：进阶
>
> 类型：官方工具与集成
## 这篇文章适合谁
当任务只能通过桌面应用完成，或者命令行和结构化插件拿不到所需信息时，可以考虑 Computer Use。它能看屏幕、点击窗口、输入文字并在多个应用之间完成一段流程。
Computer Use 当前支持 macOS 和 Windows。Windows 运行时会接管活动桌面的前台输入，不能一边让它操作同一台电脑一边继续使用鼠标键盘。
## 安装和授权
在 ChatGPT 桌面 App 中切换到 Work 或 Codex，打开 Plugins，安装并启用 Computer Use。再到设置中查看应用访问权限。
macOS 需要按系统提示授予 Screen Recording 和 Accessibility 权限。Windows 要保持目标应用在活动桌面并处于可见状态。应用授权和文件、终端权限是两套设置，授予其中一项不会自动扩大另一项权限。
## 适合交给它的任务
Computer Use 适合检查桌面应用、操作浏览器、复现只在 GUI 中出现的问题、修改必须点击设置的选项，以及跨多个应用完成一段流程。开始时给它一个应用和一个清楚的目标，必要时逐步批准高风险动作。
不要把密码、密钥和客户数据放进不必要的任务。关闭不相关的敏感应用，也不要同时运行两个任务操作同一个应用。
## Windows 与 macOS 的区别
macOS 可以在你处理其他事情时运行部分后台任务，具体取决于锁定和权限设置。Windows 的 Computer Use 只能在前台运行，任务期间会移动指针和输入文字。要让 Windows 任务持续运行，应保持会话解锁，并把这台机器专门留给任务。
这项能力不会自动批准系统安全弹窗，也不能替你输入管理员凭据。遇到系统权限、登录和付款页面时，应该停下来由人确认。
## 如何验收结果
让 Codex 在动作完成后说明改了什么，保留必要截图或应用内结果。涉及代码的任务还要回到仓库运行测试、检查 diff。Computer Use 看到界面，不等于它已经验证了后台状态。
## 参考资料
- [Computer Use](https://developers.openai.com/codex/computer-use)
- [Computer Use 设置](https://developers.openai.com/codex/app/computer-use)
- [Use your computer with ChatGPT](https://developers.openai.com/codex/use-cases/use-your-computer-with-codex)
### Codex 连接 Sentry 排查线上错误
URL: https://codexguide.io/guides/codex-sentry-error-triage
如果线上错误已经进入 Sentry，而你还要在日志、Issue、代码和测试之间来回切换，可以把 Sentry 接入 Codex，让它读取错误上下文，再回到代码仓库分析原因。
# Codex 连接 Sentry 排查线上错误
> 难度：进阶
>
> 类型：官方工具与集成
## 这篇文章适合谁
如果线上错误已经进入 Sentry，而你还要在日志、Issue、代码和测试之间来回切换，可以把 Sentry 接入 Codex，让它读取错误上下文，再回到代码仓库分析原因。
Sentry 是外部数据源。接入后 Codex 能看到哪些项目、Issue 和事件，取决于你授予的账号范围和工具权限。
## 选择连接方式
OpenAI 官方文档把 Sentry 列为 Codex 可用的插件或 MCP 服务。桌面 App 中可以从 Plugins 安装推荐的 Sentry 工具；CLI 也可以配置远程 MCP。使用哪条路径，要看当前客户端和组织提供的连接方式。
如果通过 CLI 添加远程 MCP，可以先按官方文档配置，再完成 OAuth 登录。不要直接把 Token 写进命令、文章或仓库。连接成功后，先让 Codex列出它能访问的组织和项目，确认范围正确。
## 从一个 Issue 开始
不要一上来让 Codex 扫整个组织。先给一个 Sentry Issue 链接或 Issue 标识，让它完成四步：读取 Issue 详情，定位相关代码，解释堆栈和发生条件，列出可验证的修复建议。
可以这样开始：
```text
请读取这个 Sentry Issue，先不要修改文件。
结合当前仓库定位异常来源，列出堆栈证据、可能原因、需要补的测试，以及还无法确认的信息。
```
有了原因和证据后，再让 Codex 修改代码。修复完成要运行对应测试，检查 diff，并确认 Sentry 中的错误条件确实被覆盖。
## 控制读取范围
Sentry 里的事件、请求参数和用户上下文可能包含敏感数据。把组织和项目范围收窄，只读取当前问题需要的事件。对外部工具设置最小必要权限，排查结束后复查连接和审批设置。
## 默认模式和 Agent 模式
工具的调用方式和可见名称会随插件版本变化。不要把某个截图中的 Agent Mode 名称当成固定接口。更可靠的做法是让 Codex先说明当前可用工具，再根据工具返回结果继续。
## 参考资料
- [Model Context Protocol](https://developers.openai.com/codex/mcp)
- [Automate bug triage](https://developers.openai.com/codex/use-cases/automation-bug-triage)
- [Codex 官方文档](https://developers.openai.com/codex/)
### Codex Record & Replay：生成可复用 Skill
URL: https://codexguide.io/guides/codex-record-replay-skill
如果你有一套重复做、步骤稳定、但很难完整写成说明的桌面流程，可以用 Record & Replay 让 Codex 观察一次操作，再生成一个可复用的 Skill。
# Codex 用 Record & Replay 生成可复用 Skill
> 难度：进阶
>
> 类型：Skill 创建与复用
## 这篇文章适合谁
如果你有一套重复做、步骤稳定、但很难完整写成说明的桌面流程，可以用 Record & Replay 让 Codex 观察一次操作，再生成一个可复用的 Skill。
它适合周报、创建规范化 Issue、导出固定报表和发布测试环境等工作。录制前要先准备好脱敏数据，别在录制过程中输入密码、Token 或客户信息。
## 使用前的条件
Record & Replay 当前只在 macOS 提供，初期不对欧洲经济区、英国和瑞士开放。Computer Use 也必须可用并已启用；组织用 `requirements.toml` 关闭 `computer_use` 时，这两个入口都会消失。
它面向个人快速复用。需要团队分发、捆绑多个 Skill、接入 MCP 或管理安装元数据时，应当把流程整理成独立 Plugin。
## 录制一次工作流
在 Codex App 中打开 Plugins，找到 Record & Replay，按提示开始录制。Codex 会先给出一段建议提示词，你可以补充这次任务的目标、每次会变化的输入和成功标准。
开始录制后，把流程完整做一遍。步骤要短而完整，完成后立刻从菜单栏或悬浮窗停止录制，也可以告诉 Codex 已经做完。录制会持续到你停止，顺手做的无关动作也可能进入它的观察范围。
## 检查 Codex 生成的 Skill
停止后，Codex 会根据记录起草 Skill。一个能复用的 Skill 至少要写清四件事：什么时候使用，需要哪些输入，按什么步骤操作，怎样验证结果。
录制本身看不出你的隐含偏好，例如字段默认值、命名规则和某个判断点。打开草稿后，把这些内容补进去，再检查它是否把一次性的内容误写成固定步骤。
## 在新任务中复用
开一个新会话，让 Codex 使用刚生成的 Skill，并把本次变化的值说清楚，例如上传的文件、Issue 标题或报表日期。Codex 会把 Skill 当作上下文，结合当前可用的 Computer Use、浏览器操作和插件完成任务。
## 什么时候改成 Plugin
Record & Replay 适合个人快速得到一个可用草稿。需要多人安装、版本管理、多个 Skill 协同或打包 MCP 服务时，应该按 Plugin 的结构重新整理。两者可以衔接，前者用于探索流程，后者用于长期维护。
## 参考资料
- [Record & Replay](https://developers.openai.com/codex/record-and-replay)
- [Agent Skills](https://developers.openai.com/codex/skills)
- [Build plugins](https://developers.openai.com/codex/build-plugins)
### Codex 模型与推理强度怎么选
URL: https://codexguide.io/guides/codex-model-reasoning-effort
打开 Codex 的模型菜单，先分清模型、推理强度和速度三个设置。模型决定能力与基础消耗区间，推理强度决定当前任务投入的计算量，速度选项则用更多额度换更快返回。
# Codex 模型怎么选：推理强度 Low、Medium、High 有什么区别
> 测试环境：Windows 11 24H2；Codex Desktop 26.803.10989.0；Codex CLI 0.146.1；2026-08-14 核验。
打开 Codex 的模型菜单，先分清模型、推理强度和速度三个设置。模型决定能力与基础消耗区间，推理强度决定当前任务投入的计算量，速度选项则用更多额度换更快返回。
## 模型与推理强度怎么搭配
- 日常改代码、补测试和整理方案：Terra + Medium。
- 跨模块重构、复杂调试和架构规划：Sol + Medium，不够再升 High。
- 摘要、分类、格式转换和批量改名：Luna + Light；CLI 中最低档显示为 Low。
- Max 和 Ultra 留给少数真正困难的任务，并先确认用量和等待时间。
桌面端的 Light 在 CLI 中叫 Low。CLI 可以通过 `/model` 选择模型和推理强度；不要因为任务返回慢就盲目升高推理档位，先检查任务是否可以拆分、上下文是否过长，以及是否真的需要更强模型。
## 三个模型的使用边界
| 模型 | 更适合 | 不建议直接交给它 |
|---|---|---|
| Sol | 复杂规划、跨模块修改、多阶段调试和最终复核 | 大量机械改写和简单摘要 |
| Terra | 日常开发、范围明确的实现、常规审查和测试补全 | 没有验收标准的高风险架构决策 |
| Luna | 摘要、分类、批量转换和脚手架 | 并发问题和需要持续判断的仓库级修改 |
## 用总成本而不是单价做决定
一次任务的成本包括模型用量、等待时间、失败重跑和人工返工。范围清楚时，先用 Terra + Medium；发现任务需要更多推理，再升到 Sol 或 High。每次调整后都用同一类小任务检查结果，不要用一次偶然成功证明某档位永远更好。
模型和界面会更新，发布后请以当前 Codex Models 页面和 CLI 帮助为准。
参考：[OpenAI Codex Models](https://developers.openai.com/codex/models)、[Codex CLI reference](https://developers.openai.com/codex/cli/reference)。
### Codex CLI 管理多条任务线：命名、切换与 fork
URL: https://codexguide.io/guides/codex-cli-manage-multiple-sessions
当你同时处理重构、排错和测试时，不必为每条任务线开一个终端窗口。Codex CLI 可以保存会话、给会话命名、在会话之间切换，并从已有会话 fork 出一条独立分支。
# Codex CLI 管理多条任务线：命名、切换与 fork
当你同时处理重构、排错和测试时，不必为每条任务线开一个终端窗口。Codex CLI 可以保存会话、给会话命名、在会话之间切换，并从已有会话 fork 出一条独立分支。
## 先给会话命名
在当前会话中输入 `/rename`，给它一个能表达任务的名字，例如 `订单模块重构`。名称只帮助识别，不会改变任务目标，也不会扩大权限。
## 保存、切换和归档
`codex resume` 会打开已保存的交互会话列表，也可以按会话 ID 或名称恢复。`codex resume --last` 可以继续最近一次会话。归档只是从常用列表中收起，不会删除转录内容。
## 从当前节点 fork
`/fork` 会从当前聊天复制出一条新会话，原会话保持不变。终端里也可以使用 `codex fork`，或用 `codex fork --last` 从最近会话分叉。
fork 复制的是上下文，不是 Git 分支，也不会自动合并两条会话后续产生的文件修改。涉及写入时，给每条分支独立 worktree，或只允许其中一条执行修改。
## 一套实用的多线安排
主线负责实现和最终验证，辅助会话只读分析日志、测试和代码结构，实验会话从主线 fork 用来比较替代方案。每条会话写清输入、输出和是否允许修改文件。
会话名称、命令和界面可能随 CLI 版本变化，遇到差异以当前 `codex --help` 和官方文档为准。
参考：[Codex CLI command reference](https://developers.openai.com/codex/cli/reference)、[Slash commands](https://developers.openai.com/codex/cli/slash-commands)。
### Codex CLI 长任务如何恢复：保存、继续与检查会话
URL: https://codexguide.io/guides/codex-cli-resume-long-task
长任务中断后，最重要的不是让 Codex“接着猜”，而是恢复原会话并重新确认目标、修改范围和验证状态。会话历史不能替代 Git、测试和人工检查。
# Codex CLI 长任务如何恢复：保存、继续与检查会话
长任务中断后，最重要的不是让 Codex“接着猜”，而是恢复原会话并重新确认目标、修改范围和验证状态。会话历史不能替代 Git、测试和人工检查。
## 保存现场
结束终端前记录当前目标、已经修改的文件、最后一次实际运行的检查。任务仍在运行时，先让 Codex 汇报进度，停在可检查的节点再关闭终端。
## 恢复已有会话
在项目目录运行：
```bash
codex resume
codex resume --last
```
恢复后先只读检查当前会话目标、`git status` 和最近的 diff，不要马上继续大范围修改。
## 目标变化时重新确认
需求变化时明确哪些约束被替换，哪些仍然有效。需要完全不同方向的尝试时用 `/fork`，需要继续同一条主线时用 `codex resume`。
## 恢复后的验收顺序
1. 查看 `git status`，确认工作区正确。
2. 查看 `git diff`，排除无关修改。
3. 运行失败过的最小测试，再扩大到完整检查。
4. 记录命令、结果和仍未覆盖的边界。
会话历史只能说明讨论过什么，不能证明代码现在正确。原目标被替换、工作区被其他人改动或历史混入敏感内容时，开新会话通常更稳妥。
参考：[Codex CLI command reference](https://developers.openai.com/codex/cli/reference)、[Long-running work](https://developers.openai.com/codex/long-running-work)。
### Codex 创建自定义桌宠，从参考图到动画精灵图
URL: https://codexguide.io/guides/codex-create-custom-pet
Codex 桌面应用支持 Pets。你可以先启用内置宠物，也可以通过设置页里的自定义入口安装 hatch-pet Skill，再用一张参考图制作自己的动画角色。
# Codex 创建自定义桌宠，从参考图到动画精灵图
> 难度 | 进阶
>
> 类型 | 官方工具与集成
Codex 桌面应用支持 Pets。你可以先启用内置宠物，也可以通过设置页里的自定义入口安装 `hatch-pet` Skill，再用一张参考图制作自己的动画角色。
这套流程会生成多组状态动画和一张精灵图。参考图只负责确定角色外观，不能直接当成桌宠文件。
## 开始前的准备
先把 Codex 桌面应用更新到当前版本，然后打开设置页，确认外观选项中能找到 Pets。不同版本的菜单文字可能略有变化，以当前客户端为准。
打开 Codex 的设置入口。
进入外观设置后启用 Pets，并先选择一只内置宠物。内置宠物能够出现，说明当前客户端已经具备动画播放能力。
参考图最好只有一个主体，轮廓清楚，完整身体没有被裁掉。复杂背景、密集文字和水印会增加角色走样的概率。真人肖像、公司标志和受版权保护的角色还要先确认上传与使用权限。
## 安装并调用 hatch-pet
官方文档当前给出的入口位于 `Settings > Pets > Create your own pet`。第一次使用时，Codex 会安装 `hatch-pet` Skill。安装后如果当前任务没有识别到新 Skill，新建一个任务再继续。
把参考图拖入任务，并说明宠物名称、希望保留的外观特征和视觉风格。下面这段可以直接改。
```text
请使用 hatch-pet Skill，以我上传的图片为角色参考，制作一只可在 Codex 桌面应用中使用的自定义宠物。
宠物名称为小橘。
保留参考图中的脸型、配色和红色围巾，使用清晰的像素风。
所有状态保持同一个角色，最终背景必须透明。
完成后检查精灵图尺寸、动作连贯性和边缘残留，并告诉我安装路径和启用方法。
```
## 检查动作状态
`hatch-pet` 会围绕 Codex 的工作状态生成动作。原稿记录的状态包括待机、左右移动、招手、跳跃、失败、等待、运行和审查。具体名称与帧数可能随 Skill 更新，制作时应读取当前安装版本的规范，不能把旧表格当成固定接口。
重点看四件事。
1. 不同动作中的脸、比例、配色和配件是否一致。
2. 左右移动方向是否正确，身体是否被格子边缘裁掉。
3. 等待、运行和审查能否表达 Codex 的实际状态。
4. 透明背景是否残留白边、色边、阴影或零散像素。
## 检查精灵图与安装结果
原稿使用的精灵图为八列九行，每格 `192 × 208` 像素，整张图为 `1536 × 1872` 像素。这个规格需要以当前 `hatch-pet` Skill 的输出要求复核。不要在图像软件里随意拉伸最终文件，也不要把未使用的透明格填上背景色。
生成完成后，检查输出目录中是否有宠物配置和精灵图文件。让 Codex 报告实际安装路径，再回到 Pets 设置页选择新角色。
最后分别触发普通任务、等待审批和失败状态，观察动画是否切换。文件存在只能证明生成完成，状态切换正常才说明这套桌宠可以使用。
## 常见问题
设置页没有 Pets 时，先更新客户端并查看官方文档中的平台与版本说明。新 Skill 没有出现时，新建任务或重启客户端。角色走样时只重做失败的动作，已经通过检查的行不必全部生成一遍。背景残留时要让 Codex 检查透明通道和边缘像素，不能只看缩略图。
## 参考资料
- [Codex Pets](https://developers.openai.com/codex/pets)
- [Codex Skills](https://developers.openai.com/codex/skills)
### Codex Automations 定时执行任务，创建、检查与运行条件
URL: https://codexguide.io/guides/codex-automations-scheduled-tasks
Automations 可以让 Codex 桌面应用按计划重复运行任务。它适合检查最近提交、汇总 Git 活动、整理 CI 失败和生成周期性报告。每次运行仍然需要明确的数据来源和完成标准。
# Codex Automations 定时执行任务，创建、检查与运行条件
> 难度 | 进阶
>
> 类型 | 官方工具与集成
Automations 可以让 Codex 桌面应用按计划重复运行任务。它适合检查最近提交、汇总 Git 活动、整理 CI 失败和生成周期性报告。每次运行仍然需要明确的数据来源和完成标准。
本文只处理桌面应用中的定时任务。原稿中的 Skills 管理、线程界面和其他设置已经有独立教程，因此不在这里重复。
## 创建一条 Automation
打开 Codex 桌面应用中的 Automations 页面。可以从模板开始，也可以新建空白任务。
创建时至少检查名称、项目、提示词和执行计划。
| 字段 | 应写内容 | 检查重点 |
|---|---|---|
| Name | 能区分用途的任务名 | 不要只写 Daily Task |
| Projects | 允许读取的项目目录 | 避免把无关或敏感项目一起选中 |
| Prompt | 数据范围、动作和完成标准 | 说明没有数据时怎样结束 |
| Schedule | 日期、星期和时间 | 核对本机时区与工作日 |
检查最近提交可以这样写。
```text
检查当前项目过去 24 小时内的新提交。
只报告有代码证据支持的潜在问题，并给出文件路径和相关差异。
不要自动修改文件。
如果没有新提交，明确记录没有可检查内容并结束任务。
```
最后一句很重要。没有提交时，Automation 应如实结束，不能为了生成报告而假设存在问题。
## 运行条件
桌面端 Automation 依赖本机环境。电脑、Codex 应用和目标项目都要在任务执行时可用。系统休眠、应用退出、项目被移动或账号失效都会影响运行。云端触发能力若有变化，应以当前官方文档为准。
定时任务也不会自动获得更高权限。它仍然受项目范围、审批策略、网络访问和外部工具授权约束。涉及写文件、发消息或调用外部系统时，先用只读任务验证流程，再逐步增加权限。
## 检查运行结果
每次执行后查看任务状态、输入范围和实际输出。原稿中的示例检查了过去 24 小时的 Git 历史，因为没有提交而没有报告问题，并被归档。这种结果是正常完成，不是失败。
上线一条长期运行的 Automation 前，先手动执行一次。确认它读到了正确项目，没有越过时间范围，输出能回链到证据，并且空数据时会安静结束。之后再观察至少一次定时触发，确认本机时区和运行条件正确。
## 适合与不适合的任务
规则稳定、数据来源明确、结果可以复核的工作适合定时执行。需要临场判断、会产生外部副作用或错误成本很高的任务，应保留人工确认。自动提交代码、修改生产配置和向外部联系人发送消息都不宜直接作为第一版 Automation。
## 参考资料
- [Codex Automations](https://developers.openai.com/codex/app/automations)
- [Codex App](https://developers.openai.com/codex/app)
### Codex 处理文档、表格、幻灯片和 PDF 的完整工作流
URL: https://codexguide.io/guides/codex-document-delivery-workflow
Codex 的文档类工具可以把同一批材料整理成文档、电子表格、幻灯片和 PDF。稳定的做法是先确定事实与数据，再依次生成各类交付物，最后检查内容是否一致。
# Codex 处理文档、表格、幻灯片和 PDF 的完整工作流
> 难度 | 进阶
>
> 类型 | 插件工作流
Codex 的文档类工具可以把同一批材料整理成文档、电子表格、幻灯片和 PDF。稳定的做法是先确定事实与数据，再依次生成各类交付物，最后检查内容是否一致。
## 准备材料和验收标准
先把原始材料放进一个项目目录。代码、会议记录、CSV、品牌模板和参考文件应分开保存。涉及客户数据、合同和财务信息时，先确认当前工具的上传范围和组织策略。
给 Codex 的第一条指令应说明交付对象、事实来源和文件要求。
```text
读取 materials 目录中的项目说明、测试结果和 CSV 数据。
先列出可确认的事实、缺失信息和相互冲突的数据，不要生成交付文件。
我确认后，再制作一份技术报告、一张指标表、一套汇报幻灯片和最终 PDF。
所有数字必须能回链到原始文件。
```
## 用 Documents 整理正式文档
Documents 适合把零散材料整理成有标题层级、段落和列表的正式文档。技术方案、接口说明和事故复盘都可以从已有材料起步。
先让 Codex 生成结构，再补正文。审阅时重点看事实是否有来源，章节是否重复，命令和代码有没有被改错。文档的排版完成不等于内容已经通过验收。
## 用 Spreadsheets 整理数据
Spreadsheets 可以生成带公式和格式的工作簿。输入数据要保留原始表，计算结果放在新表中，并让 Codex 说明每个关键公式来自哪里。
检查时抽取几行手算，确认求和范围、日期格式、空值和百分比口径。图表使用的区域也要单独核对，避免新增数据后图表没有更新。
## 用 Presentations 生成汇报稿
Presentations 适合把已经确认的文档和表格改成可演示的结构。让 Codex 先列出每页要回答的问题，再生成幻灯片，能减少一页塞入太多信息的情况。
幻灯片中的数字应直接来自已核验的表格。演讲者备注可以补充上下文，页面正文只保留现场需要看到的信息。生成后逐页检查字体、裁切、对比度和图表标签。
## 用 PDF 完成固定版式交付
PDF 工具可以读取、创建和检查 PDF。导出前先确认源文档与幻灯片已经定稿，再生成固定版式文件。
PDF 验收要覆盖页数、目录、字体嵌入、链接、表格分页和图片清晰度。重要文档还应提取一次文本，与源文件对比标题、数字和关键条款。
## 串成一条交付流程
推荐顺序是原始数据、电子表格、正式文档、幻灯片、PDF。每一步只使用上一步已经确认的结果，发现数字变化时返回数据源修正，再重新生成下游文件。
可以让 Codex 在项目中保留一份交付清单。
```text
交付前检查所有产物。
核对文档、表格、幻灯片和 PDF 中的项目名称、日期、版本与核心数字。
列出每个文件的路径、页数或工作表数量，以及仍需要人工确认的项目。
不要用生成成功代替内容校验。
```
文档类能力的入口可能来自内置工具、Skill 或 Plugin，具体名称会随客户端和插件版本变化。开始任务前先让 Codex 列出当前可用工具，并在新任务中确认工具已加载。
## 参考资料
- [Codex Skills](https://developers.openai.com/codex/skills)
- [Codex Plugins](https://developers.openai.com/codex/plugins)
- [Generate slide decks](https://developers.openai.com/codex/use-cases/generate-slide-decks)
### 在 Zed 中通过 ACP 使用 Codex CLI
URL: https://codexguide.io/guides/codex-zed-acp-integration
Zed 可以通过 Agent Client Protocol 运行 Codex CLI。这样可以保留 Codex 的认证、模型和工具配置，同时使用编辑器里的文件树、差异预览和审批界面。
# 在 Zed 中通过 ACP 使用 Codex CLI
> 难度 | 进阶
>
> 类型 | 社区生态与项目评测
Zed 可以通过 Agent Client Protocol 运行 Codex CLI。这样可以保留 Codex 的认证、模型和工具配置，同时使用编辑器里的文件树、差异预览和审批界面。
我在写作前核对了 Zed 官方文档和 `codex-acp` 适配器仓库。ACP 生态仍在变化，安装前应再次查看文末来源。
## ACP 负责什么
ACP 定义编辑器与编程 Agent 之间的通信方式。编辑器负责展示会话、流式输出、工具调用和审批请求，Agent 继续负责读取项目、执行命令和修改文件。
协议基于 JSON-RPC。Agent 可以作为本地子进程通过标准输入输出通信，也可以由兼容客户端连接远程服务。实际支持范围取决于客户端与适配器版本。
## ACP 和 MCP 的分工
MCP 让 Codex 连接数据库、文档服务和其他外部工具。ACP 让 Zed 这类编辑器连接 Codex。一次任务中可以同时使用两者。
Zed 通过 ACP 管理 Codex 会话。Codex 再通过 MCP 调用已经配置的外部服务。ACP 不会绕过 Codex 的沙箱、审批策略或账号额度。
## 在 Zed 中启动 Codex
先安装并登录 Codex CLI，再安装当前版本的 Zed。打开 Zed 的 Agent 面板，在新建线程菜单中选择 Codex。Zed 官方页面会显示当前支持的安装或登录步骤，应以页面上的实际入口为准。
创建线程后先做一个最小测试。
```text
读取当前项目的 README，不要修改文件。
告诉我项目使用的主要语言、启动命令和测试命令，并给出对应文件路径。
```
确认读取范围正确后，再让 Codex 修改一个临时文件。检查 Zed 是否显示差异，拒绝修改时文件是否保持不变，批准后修改是否真实写入磁盘。
## 其他 ACP 客户端
Zed 之外的 ACP 客户端可以使用 `agentclientprotocol/codex-acp` 适配器。仓库当前给出的启动方式如下。
```bash
npx -y @agentclientprotocol/codex-acp
```
适配器通过 Codex App Server 对接 Codex。模型、认证、工具、审批和沙箱仍由 Codex 负责。客户端配置方式不同，不能把 Zed 的菜单步骤直接套到其他编辑器。
使用 API Key 时放进安全的环境变量或密钥管理器，不要写进编辑器设置、项目仓库或截图。启动后先用只读任务确认项目目录，再逐步开放写入和命令执行。
## 适用范围与限制
ACP 适合希望在编辑器中使用 Codex，又不想把工作流绑定到某个专用面板的人。它也方便客户端统一处理多种 Agent 的会话和审批。
目前仍要留意三类差异。客户端未必实现全部协议能力，适配器版本可能要求特定 Codex 版本，编辑器界面显示成功也不能替代 Git 和测试验收。出现问题时先分别检查 Zed、适配器和 Codex CLI 的版本与日志。
## 参考资料
- [Zed 中使用 Codex CLI](https://zed.dev/acp/agent/codex-cli)
- [Zed External Agents](https://zed.dev/docs/ai/external-agents)
- [codex-acp 适配器](https://github.com/agentclientprotocol/codex-acp)
- [Agent Client Protocol](https://agentclientprotocol.com/)
### Codex 使用 Archify 生成可验证的代码架构图
URL: https://codexguide.io/guides/codex-archify-architecture-diagrams
Archify 是第三方 Agent Skill。Codex 可以先读取代码仓库，整理系统边界和主调用路径，再让 Archify 把这些信息渲染成技术图。
# Codex 使用 Archify 生成可验证的代码架构图
> 难度 | 进阶
>
> 类型 | 社区生态与项目评测
Archify 是第三方 Agent Skill。Codex 可以先读取代码仓库，整理系统边界和主调用路径，再让 Archify 把这些信息渲染成技术图。
这类工具最容易出现的问题是图很好看，内容却和代码对不上。本文把代码证据、图表生成和验证分成三个阶段。
## Archify 能生成什么
Archify 当前支持 architecture、workflow、sequence、dataflow 和 lifecycle 等图表。不同图解决的问题不同。
| 类型 | 适合表达 |
|---|---|
| architecture | 服务、数据库、缓存和外部系统的边界 |
| workflow | 审批、CI、事故处理和工具调用步骤 |
| sequence | 请求、鉴权、缓存和异步消息的先后关系 |
| dataflow | 数据来源、转换、存储和下游消费 |
| lifecycle | 任务、订单或部署状态的变化 |
## 安装到 Codex
项目 README 当前提供的 Skill 安装方式如下。
```bash
npx skills use tt-a1i/archify@archify --agent codex
```
第三方 Skill 可以读取项目并运行自己的脚本。安装前先查看仓库内容、依赖和最近更新，确认它没有超出当前任务需要的权限。安装完成后新建 Codex 任务，检查 Skill 是否出现在可用列表中。
## 先生成 architecture brief
不要直接要求 Codex 画整座系统。先让它输出一份能回链到代码的说明。
```text
先扫描当前项目，不要生成图。
列出应用入口、核心模块、数据存储、外部服务和一条主要请求路径。
每个判断给出文件路径和关键符号。
无法从代码确认的部署信息单独列出，不要猜测。
```
人工检查这份 brief。删除不需要出现在图里的实现细节，补充仓库外才能确认的信息，并明确图要回答的问题。
## 让 Archify 生成图
确认 brief 后再调用 Skill。
```text
使用 Archify 根据刚才确认的 architecture brief 生成一张 architecture 图。
主路径从用户请求开始，到 API、业务模块和数据存储结束。
外部服务放在系统边界之外。
中文标签保持简短，节点内不放长段说明。
保存可编辑源文件和渲染结果。
```
复杂项目可以拆成多张图。总览图只画边界和主路径，时序图解释一个请求，数据流图解释一批数据。把所有依赖塞进一张图通常会降低可读性。
## 验证图表
让 Codex 对图中的每个节点和连接生成证据表。节点要对应代码、配置或已确认的外部事实，箭头要能说明调用、事件或数据关系。随后运行 Archify 提供的校验命令，并打开导出结果检查文字重叠、箭头方向和裁切。
建议把可编辑源文件留在仓库，把 HTML、SVG 或 PNG 当成构建产物。代码结构变化后重新生成，并通过 Git diff 查看图表说明是否同步更新。
## 适用范围与限制
Archify 适合 README、技术方案和架构评审中的展示图。小型流程放在 Markdown 中时，Mermaid 往往更轻。需要精确品牌排版或大量手工微调时，专业设计工具更合适。
它是第三方项目，不能写成 Codex 官方功能。生成结果也不能证明系统真实存在某项能力，最终依据仍然是代码、配置和运行环境。
## 参考资料
- [Archify 项目仓库](https://github.com/tt-a1i/archify)
- [Codex Skills](https://developers.openai.com/codex/skills)
### Codex 使用 Text-to-Lottie 制作界面动效
URL: https://codexguide.io/guides/codex-text-to-lottie-animation
Text-to-Lottie 是第三方 Skill。它让 Codex 根据文字要求创建或修改 Lottie 动画，并用预览项目检查运动、循环和透明背景。
# Codex 使用 Text-to-Lottie 制作界面动效
> 难度 | 进阶
>
> 类型 | 社区生态与项目评测
Text-to-Lottie 是第三方 Skill。它让 Codex 根据文字要求创建或修改 Lottie 动画，并用预览项目检查运动、循环和透明背景。
## 先了解 Lottie 文件
Lottie 用 JSON 描述矢量图形和关键帧。它适合图标反馈、加载状态、按钮和空状态等轻量界面动效。照片级画面、复杂粒子和长时间视频不适合直接用 Lottie 承担。
Text-to-Lottie 也不是图像模型。它提供给 Agent 一套生成、预览和检查动画文件的工作流，最终质量仍取决于素材、约束和验收。
## 安装 Skill
项目仓库当前提供的安装命令如下。
```bash
npx skills add diffusionstudio/lottie
```
安装第三方 Skill 前先检查仓库、依赖和权限。完成后新建 Codex 任务，确认它能读取 Skill。项目需要 Node.js 或预览依赖时，按仓库 README 安装，不能假定所有环境已经具备。
## 第一次生成
先选一个边界清楚的状态反馈。成功勾选动画可以这样描述。
```text
使用 Text-to-Lottie 创建一个成功反馈动画。
画布为 256 × 256，背景透明。
蓝色圆环在 400 毫秒内绘制完成，随后绿色勾线在 300 毫秒内出现。
动画只播放一次，结束后停在完成状态。
不要添加文字、阴影和背景卡片。
生成 JSON 后启动预览，并检查首帧、末帧和画布边界。
```
动效提示词至少要交代素材、画布、运动、时长和循环。只写“做得高级一点”，Codex 无法知道应该改速度、缓动还是图形。
## 用素材约束结果
已有 SVG 或品牌图标时，把源文件交给 Codex，并要求保留路径与颜色。没有素材时先让它生成静态构图，确认轮廓后再加运动。这样比同时修改造型和动画更容易定位问题。
## 检查常见动效
加载动画需要无缝循环，成功反馈通常播放一次，通知铃铛应在短暂摆动后回到稳定位置。每种用途的停止条件不同，不能只确认文件能打开。
验收时检查首尾帧是否跳动，主体有没有超出画布，透明背景是否正确，速度在实际界面中是否合适。还要在目标播放器中测试。浏览器预览正常，不能证明 iOS、Android 或 Flutter 的播放器支持文件中的全部特性。
## 修改已有动画
修复已有 Lottie 时，把问题描述成可观察的现象。
```text
读取 success.json，保留现有图形和颜色。
修复循环接缝处的跳动，让最后一帧自然回到第一帧。
不要改变画布尺寸和图层名称。
修改后生成前后对比预览，并说明改动的关键帧。
```
把 JSON、素材和预览命令放在项目中，导出的演示 GIF 或视频单独保存。这样可以在 Git 中审查可编辑源文件，也能重新生成展示产物。
## 参考资料
- [Text-to-Lottie 项目仓库](https://github.com/diffusionstudio/lottie)
- [Codex Skills](https://developers.openai.com/codex/skills)
### Codex 连接 ChatCut 完成视频粗剪、字幕与导出
URL: https://codexguide.io/guides/codex-chatcut-video-editing
ChatCut 是第三方视频编辑服务。通过它提供的插件和 MCP 工具，Codex 可以分析素材、修改时间线、生成字幕并导出视频。账号、素材和编辑操作仍在 ChatCut 的权限范围内。
# Codex 连接 ChatCut 完成视频粗剪、字幕与导出
> 难度 | 进阶
>
> 类型 | 社区生态与项目评测
ChatCut 是第三方视频编辑服务。通过它提供的插件和 MCP 工具，Codex 可以分析素材、修改时间线、生成字幕并导出视频。账号、素材和编辑操作仍在 ChatCut 的权限范围内。
## 安装与登录
开始前需要 ChatCut 账号、支持插件的 Codex 客户端和可用的 MCP 登录。项目仓库会给出当前安装方式。安装第三方插件前先查看仓库内容、权限和数据处理说明。
可以先让 Codex 按官方仓库处理安装。
```text
阅读 ChatCut 官方 agent-plugin 仓库的安装说明。
先告诉我将添加哪些 Plugin 和 MCP 配置，需要哪些账号权限，不要立即安装。
我确认后再完成安装与登录，并报告可用工具，不要读取任何项目素材。
```
安装和 MCP 登录完成后新建一个 Codex 任务。旧任务通常不会动态加载刚加入的工具。新任务中先让 Codex 列出 ChatCut 工具，再创建空白测试项目。
## 先整理素材
正式剪辑前把原始视频、录屏、图片、音频、品牌素材和来源记录分开放置。文件名要能说明内容，避免全部使用相机生成的编号。
客户未公开素材、内部会议和未授权人物画面不应直接上传。库存素材、音乐和生成内容要保留来源与商用授权记录。
## 第一次只做粗剪
首次任务不要把字幕、音乐、动画和导出一起交给 Codex。先完成转写与内容粗剪。
```text
使用 ChatCut 新建测试项目并导入指定视频。
这是一段中文口播。
删除明确口误、失败重录和无意义重复，压缩超过 1.2 秒的无意义停顿。
保留完整句意、自然呼吸和原本语气。
不要添加字幕、音乐、动画或补充画面，也不要导出。
完成后给出删减清单，并停在时间线供我检查。
```
完整播放粗剪，检查语气有没有被截断，句意是否变化，停顿是否过密。确认内容后再进入下一阶段。
## 按阶段完成成片
稳定顺序是素材分析、纸面剪辑、内容粗剪、人工审片、画面包装、字幕与声音、完整质检、导出。后续元素依赖时间点，过早添加会增加返工。
粗剪锁定后再加录屏和 B-roll。每段画面要对应正在讲的内容，没有真实素材时先报告缺口。不要用无关库存画面，也不要让生成画面冒充真实产品界面。
字幕要基于最终时间线生成。核对人名、品牌名、数字和专有名词，并检查字幕安全区。音乐要低于人声，转场处不能突然中断。
## 导出前检查
工具返回成功，只能证明命令执行，不能证明视频合格。导出前让 Codex 检查时间线，再由人完整看一遍。
检查黑帧、空白、素材重叠、音频切口、字幕同步、画面遮挡和音乐音量。竖屏版本还要确认主体没有被裁掉。涉及人物、数字和产品能力的内容应回到来源逐项核对。
确认后再指定分辨率、帧率、编码和文件名。多个平台版本应分别检查构图和字幕安全区，不能只机械裁边。
## 适用范围与限制
口播清理、字幕、访谈切片和简单产品演示适合先交给 Codex 与 ChatCut 做初版。复杂叙事、精细关键帧、调色和声音设计仍需要人在专业编辑工具中判断。
云端处理可能涉及上传、转码和转写，成本也可能按不同生成能力分别计算。正式项目开始前先确认隐私条款、额度与导出限制。
## 参考资料
- [ChatCut 插件仓库](https://github.com/ChatCut-Inc/agent-plugin)
- [ChatCut 官网](https://chatcut.io/)
- [Codex Plugins](https://developers.openai.com/codex/plugins)
- [Codex MCP](https://developers.openai.com/codex/mcp)
### Codex 移动端远程协作
URL: https://codexguide.io/guides/codex-mobile-remote-collaboration
早高峰的地铁上，你掏出手机，点开 ChatGPT。
# Codex 移动端远程协作：用手机查看、分派和跟进电脑上的任务
早高峰的地铁上，你掏出手机，点开 ChatGPT。
家里书房的 Mac 正在跑一个重构任务，Codex 刚把测试跑完，diff
摆在屏幕上等你审，你扫两眼，批准，顺手又派了个新活：“把昨天那个接口的报错日志也查一下。”
全程手机不烫，流量没走几兆，模型调用、代码、终端都在家里那台电脑上，手机只是个遥控器。
这就是 Codex Remote！刚出预览版的时候只支持 Mac 主机，不少人卡在配对这一步；现在正式
GA，Plus、Pro、Business、Enterprise、Education 这些付费用户都能用了，Windows 主机也补上了。
一句话概括：手机变遥控器，电脑变成你的随身机房。
## 它不是把 Codex 搬到手机上
最容易误会的一点先说：这不是"手机版 Codex"。
模型调用、代码、shell 命令、文件、凭据，还有你装好的插件和 MCP server，全部留在电脑上。
手机拿到的只是实时推过来的结果，diff、测试输出、终端日志、截图，以及最重要的审批请求。
为什么这么设计？因为 Agent 干活最依赖的是环境。你登录过的网站、配好的数据库环境，放到云端沙箱要重新配一遍，在自己电脑上是现成的。
所以它的思路是反着来的：不把环境搬上云，把操作入口装进口袋。
## 用之前，先确认你能不能用
几个硬门槛提前说，免得你扫半天码找不到入口。
首先得是付费 ChatGPT 计划，其次两端 App 都要更到最新版，手机 ChatGPT 加电脑 Codex App，缺一不可。手机上找不到 Codex
入口，八成是版本没更。
配对只能从电脑上的 Codex App 发起，CLI 和 IDE 插件里没有这个入口，别在终端里翻了。
电脑要醒着、联网，而且登录的必须是同一个 ChatGPT 账号和工作区。公司账号还多一道：管理员可能要先在后台开启 Remote Control 权限。
## 两分钟配对
1. 电脑上打开 Codex App，侧边栏选 Set up Codex mobile。
2. 手机扫屏幕上的二维码，自动跳转到 ChatGPT。
3. 确认账号和工作区一致，过一遍 MFA 或 passkey。
4. 完事，主机出现在手机端 Codex 里。
配好之后去 Settings 里的 Connections
看一眼，那里能管理已配对设备。有个选项建议顺手打开：保持机器唤醒。不然你人在地铁上，电脑在家睡着了，白配。
## 手机上能干什么
比想象的全。开新线程派活、接着旧线程继续聊、中途追加指令、回答它的提问，都行。跑出来的
diff、测试结果、终端输出，包括截图，实时推到手机上。任务做完了，或者它卡住需要你了，手机弹通知。家里不止一台电脑的，还能来回切。
最值钱的是审批，Agent 要执行敏感操作，比如装依赖、跑数据库迁移，会停下来等你点头，以前这意味着你得守在电脑前，现在是手机上弹一条通知，你点一下。
别小看这一下，让 Agent 跑长任务，最大的顾虑从来不是它干不完，是它干到一半要权限，然后干等你一个小时，这个功能的价值有一半在这。
## 安全这块怎么处理的
把自己电脑的操作权开到外网，听起来就危险。GA 版本专门重做了这一层。
那个二维码也不是普通链接，里面编码的是一个限时会话令牌。必须你本人拿着手机对着电脑屏幕扫，配对绑在你的 ChatGPT
账号和多因素认证上。想远程劫持你的机器？得先走进你家书房。
官方也把丑话说在前面，只配对你自己拥有且信任的设备。
## 写在最后
Codex 这个远程控制，本质上是把人必须坐在电脑前这个前提给拆了。
以前 AI 帮你写代码，你还是得守着，现在你能把电脑当成一个一直在家干活的同事，用手机远程给它派活、盯着、拍板。
真正跑代码的还是那台真实的机器，你只是不用再被物理位置绑住。
它没多神奇，配对也就扫个码的事，但那种人在外面，活在家里跑的感觉，用过一次确实回不去。
好不好用，你自己试一把就知道了。
> 延伸阅读：
>
> 官方文档：https://developers.openai.com/codex/remote-connections
### Codex 桌面端任务工作流
URL: https://codexguide.io/guides/codex-desktop-task-workflow
Sam Altman 昨天在 X 上宣布 Codex 桌面版正式上线 Mac 平台。也是立马试用了一下，可视化界面操作起来确实方便，多个线程可以独立工作互不影响，Skill 管理也比较直观，还新增了定时任务功能。
# Codex 桌面端任务工作流：项目切换、并行任务与本地协作
Sam Altman 昨天在 X 上宣布 Codex 桌面版正式上线 Mac
平台。也是立马试用了一下，可视化界面操作起来确实方便，多个线程可以独立工作互不影响，Skill 管理也比较直观，还新增了定时任务功能。
下载地址： ** openai.com/codex ** 官方说后续会支持 Windows，目前只有 Mac 版本。
限时福利：Free 和 Go 用户也能用，付费用户 rate limit 翻倍。
官方博客提到"For a limited time we're including Codex with ChatGPT Free and
Go"，不确定这个限时会持续多久，想试的可以抓紧。
官网文档：https://openai.com/zh-Hans-CN/index/introducing-the-codex-app/
通常一手信息是最有价值的。
## 智能体的指挥中心
Codex Desktop 的核心优势在于并行工作流管理。你可以同时运行多个独立的 Agent 线程，一个查
bug，一个讨论需求，一个策划活动，切换起来很流畅。
在 CLI 版本里需要开多个终端窗口才能实现。可视化界面让任务状态一目了然，对非技术人员或者不熟悉命令行的人来说更友好。
相比 Claude Code，Codex Desktop 更侧重于项目级的任务编排和可视化管理，而 Claude Code 在 IDE
集成和代码编辑体验上更深入。两者都支持 Skills 和 MCP，但使用场景有所不同。
## Skills 管理界面
桌面版提供了可视化的 Skills 管理界面，所有已安装的 Skill 都在这里。我平时用 Claude Code
比较多，所以这边只有两个元技能。下面有很多官方推荐的 Skill，可以一键安装。
比如 Figma Skill，让 Codex 能直接读取 Figma 设计稿，自动生成 React + Tailwind 代码，还会校验是否 1:1 还原。
简单说下这两个核心 Skill：
* ** Skill Creator ** ：用来创建自定义技能。官方提供了十几个现成技能，你也可以用 Skill Creator 自己做一个。
* ** Skill Installer ** ：从官方仓库安装技能。点右下角的 Try 按钮，它会开一个新对话，然后你可以问它"有什么可以安装的技能？"（其实都是从 OpenAI 官方技能库拉取的，和页面推荐的那些一样）
## 定时任务
这是 Desktop 的新功能，CLI 和 IDE 插件都没有。Automations 让 Codex 定时自动执行任务，比如每天早上自动分类 GitHub
issues，每天下班前生成日报，定期检查 CI 是否挂了，定时扫描代码里的 bug。
官方提供了几个模板：
模板 | 用途
---|---
📅 扫描最近提交 | 检查 24h 内的 commit，找潜在 bug 并建议修复
📄 生成周报 | 从已合并的 PR 生成 release notes
🌤 Git 日报 | 总结昨天的 git 活动，用于站会汇报
📈 CI 失败汇总 | 总结 CI 失败和不稳定测试，建议修复
🏆 做个小游戏 | 创建一个简单的经典小游戏（有点好玩）
🥜 技能建议 | 根据最近 PR 和 review 推荐该学什么
📝 周更汇总 | 汇总本周 PR、发布、事故、review
📈 性能回归检测 | 对比 benchmark，标记性能下降
🔧 依赖漂移检测 | 检测依赖和 SDK 版本漂移，建议对齐
比如 扫描最近提交 这个定时任务可以自定义这些：
字段 | 作用
---|---
Name | 任务名称（Daily bug scan）
Projects | 选择要扫描的项目文件夹
Prompt | 任务指令（可以自定义）
Schedule | 执行时间：每天 09:00，可选周一到周日
执行完会进入"待审队列"，你来最终确认。
需要注意的是，定时任务需要电脑开着 + App（客户端） 开着才会执行，目前是 Beta 功能，可能有
bug。官方博客提到未来会支持"云端触发"，就不用一直开着电脑了。
我这个检查了过去 24 小时的 git 历史，没有提交记录，所以没有可扫描的内容。遵守了 Grounding
rules，没有造bug，没活干就老实说没活干，自动归档到 Archived。
## 界面逻辑
Codex Desktop 的组织结构是：
项目（Project） └── 线程（Threads） └── 对话记录
一个项目可以有多个线程，每个线程是一个独立任务，Automations 可以针对特定项目运行。
比如三个任务同时进行：一个查 bug、一个讨论需求、一个策划活动，切换起来比较流畅。
## 实用的设置项
** 防休眠模式 ** ：开启后，Codex 跑任务时电脑不会自动休眠。跑个长任务出去倒杯水，回来不用担心电脑睡着了任务断掉。
** 追问排队 ** ：当 AI 还在执行任务时，你发的新消息会自动排队等候，不会打断它。想到什么随时补充，不用等它跑完再说。
** Personality 切换 ** ：输入 ` /personality ` 可以切换两种风格：
* Friendly：解释详细，像个耐心的同事
* Pragmatic：废话少说，直接给答案
写代码赶进度选 Pragmatic，学习探索选 Friendly。很多人吐槽 AI 话太多，现在可以自己选了。
** MCP 生态 ** ：可以一键连接 Linear、Notion、Figma 等常用工具，让 AI 直接操作你的项目管理、设计稿、文档。
** Custom instructions ** ：可以写一段"人设"，比如"我习惯用 TypeScript + React"，Codex 会记住。
** 安全沙箱 ** ：Codex 默认在沙箱里执行，访问网络或修改工作区外的文件需要手动批准。Settings 里可以调整 Sandbox mode 和
Approval policy，根据自己的使用场景选择合适的安全级别。
## 技术亮点
** Worktrees 隔离 ** ：多个 Agent 改同一个项目也不会冲突。Codex 使用 Git worktrees 技术，为每个 Agent
创建独立的工作目录，避免了并行任务之间的文件冲突。这在多线程开发场景下很实用。
** 跨端同步 ** ：Desktop 会读取你 CLI 和 IDE 插件的历史记录和配置，无缝衔接。不需要重新配置，直接继承之前的工作环境。
如果你想让多个 Agent 并行干活，或者需要设置定时任务自动巡检代码，桌面版的体验确实更好。
### Codex 接入 ACP：连接兼容开发工具
URL: https://codexguide.io/guides/codex-acp-integration
现在 AI 编程工具越来越多，但有一个问题一直没解决：它们之间不互通。
# Codex 接入 ACP：在兼容开发工具中复用编码代理能力
现在 AI 编程工具越来越多，但有一个问题一直没解决：它们之间不互通。
Claude Code 有自己的客户端，Codex 也有自己的 app，Cursor 的 Agent 只能在 Cursor
里用，每个工具都是封闭的，想把某个 Agent 放到另一个编辑器里用，或者让不同 Agent 协作处理同一个项目，做不到。
这个问题其实不新鲜，十几年前，编程语言工具也是同样的局面，每个编辑器都得自己做语法高亮、自动补全、错误检查，后来出了一个叫 LSP
的协议，把这层通信统一了，VS Code 能成功很大程度上就是因为这个。
这个问题听起来熟悉吗？
现在 AI 编程领域也有了类似的协议——Agent Client Protocol（ACP），让任何编辑器能接入任何 AI 编程 Agent。
目标很简单：让任何编辑器能用任何 AI 编程 Agent。
## ACP 是什么
Agent Client Protocol 是一个标准化的通信协议，定义了代码编辑器和 AI 编程 Agent 之间如何对话。
简单说：它让任何支持 ACP 的编辑器都能用任何支持 ACP 的 Agent，不再是「Claude Code 只能在终端用」或「Cursor 只能用自己的
Agent」，可以在 Zed 里用 Claude Code，在 VS Code 里用 Gemini CLI，随便组合。
技术上它基于 JSON-RPC，支持两种运行方式：
** • 本地模式 ** ：Agent 作为编辑器的子进程运行，通过 stdio 通信
** • 远程模式 ** ：Agent 跑在云端，通过 HTTP/WebSocket 连接
和 MCP（Model Context Protocol）的关系是互补的：MCP 解决「Agent 怎么获取外部工具和数据」，ACP 解决「编辑器怎么和
Agent 对话」。
一个管 Agent 的输入，一个管 Agent 的输出。
## Harness：Agent 的“容器”
这是 ACP 生态里一个很重要的概念。
如果说 ACP 是协议本身，那 Harness 就是“管理 Agent 生命周期的容器”。
类比一下：
• ** Docker 是应用的容器 ** — 管理应用的启动、停止、网络、存储
• ** Harness 是 Agent 的容器 ** — 管理 Agent 的启动、会话、权限、通信
具体来说，Harness 负责：
• 启动和停止 Agent 进程
• 管理多个并发会话（你可以同时跑多个任务）
• 处理权限控制（Agent 要执行命令、读写文件时的审批流）
• 管理会话的保存/恢复/关闭
比如在 OpenClaw 里，你可以这样启动一个 ACP harness：
# OpenClaw 作为 ACP harness 运行
openclaw acp
# 指向远程 Gateway
openclaw acp --url wss://my-server:18789 --token-file ~/.openclaw/gateway.token
# 绑定到特定 agent 会话
openclaw acp --session agent:main:main
编辑器只需要知道怎么跟 harness 说话，不需要知道后面是 Claude、Gemini 还是 DeepSeek，这层抽象让开发者可以自由组合编辑器和
Agent，而不用关心底层实现。
## 生态现状：30+ Agent 已接入
这不是纸上谈兵。截止现在，已经有 30 多个 Agent 实现了 ACP：
• Anthropic: Claude Code（通过 Zed 的 SDK adapter） • OpenAI: Codex CLI（通过 Zed 的
adapter） • Google: Gemini CLI • Cursor • GitHub Copilot（public preview） •
JetBrains: Junie • OpenClaw • Cline、Goose、OpenHands、OpenCode...
客户端（编辑器）方面，Zed 是最积极的推动者——它原生支持 ACP，可以接入任何 ACP Agent，VS Code 和 JetBrains 也在跟进。
这意味着什么？以前你选 Claude Code 就意味着只能在终端用，现在你可以在 Zed 里直接用它，享受编辑器的所有 UI 优势（diff
预览、文件树、内联显示），或者可以用 acpx 让两个 Agent 协作。
## 实操：在 Zed 里用 Claude Code
拿一个具体例子来说，假设想在 Zed 编辑器里用 Claude Code，以前完全不可能，现在只需要配置一下：
// ~/.config/zed/settings.json
{
"agent_servers": {
"Claude Code": {
"type": "custom",
"command": "claude-agent-acp",
"args": [],
"env": {}
}
}
}
或者想用 OpenClaw 的 agent：
// Zed settings
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": ["acp", "--session", "agent:main:main"],
"env": {}
}
}
}
打开 Zed 的 Agent 面板，选择配置的 Agent，就能开始用了，体验和在终端里直接用 Claude Code 一样，但有了编辑器的 UI 加持。
## 进阶：让不同 Agent 协作
更有意思的是 agent 之间的协作，通过 acpx（ACP 的命令行客户端），可以让一个 Agent 调用另一个：
# 让 Codex 通过 ACP 访问 OpenClaw agent 的上下文
acpx openclaw exec "总结一下当前项目的最新进展"
# 建立持久会话，多次交互
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge "help me review this PR"
这意味着可以创建一个 multi-agent 工作流：一个 Agent 擅长代码生成，另一个擅长代码审查，第三个负责测试，它们通过 ACP
标准接口通信，不需要任何自定义集成工作。
再比如 OpenClaw 里的 sessions_spawn 工具，可以直接以 ACP 模式启动一个子 agent，指定用哪个 harness，子
agent 完成任务后自动报告结果，这就是harness 管理 agent 生命周期的具体体现。
## ACP vs MCP：别混淆
很多人容易把 ACP 和 MCP 混淆。
• MCP (Model Context Protocol) — 解决的是Agent 怎么获取外部能力，比如接数据库、调 API、读文档，Agent 是
MCP 的客户端。
• ACP (Agent Client Protocol) — 解决的是编辑器怎么和 Agent 对话，管理会话、权限、流式输出、工具调用审批，编辑器是
ACP 的客户端。
两者是配合关系：编辑器通过 ACP 跟 Agent 说话，Agent 通过 MCP 获取外部工具和数据，编辑器还可以把自己配置的 MCP server 传给
Agent，让 Agent 直接用。
** ACP 管「人怎么和 Agent 交互」，MCP 管「Agent 怎么和世界交互」。 **
## 写在最后
简单来说，ACP 做的事情就是把编辑器和 AI Agent 之间的对话方式统一了，以前每家都各做各的，现在有了一个共同的接口规范，Harness
则是这个体系里管 Agent 启停、会话和权限的那一层。
目前支持 ACP 的 Agent 已经超过 30 个，包括 Claude Code、Codex、Gemini CLI、Cursor、Copilot
这些主流工具，编辑器端 Zed 已经原生支持，VS Code 和 JetBrains 也在跟进，不过很多集成还在早期阶段，实际体验可能和成熟产品有差距。
> 官网：https://agentclientprotocol.com/
>
> 规范文档：https://agentclientprotocol.com/protocol/overview.md
>
> 支持 Agent 列表：https://agentclientprotocol.com/get-started/agents.md
## 七、总结
ACP 让 Codex 可以在支持该协议的开发工具中被调用，但实际能力取决于客户端和代理端的实现。配置完成后，先用一个只读任务验证连接，再逐步开放编辑、命令执行和网络权限。
参考资料：
- [Agent Client Protocol](https://agentclientprotocol.com/)
- [ACP 协议概览](https://agentclientprotocol.com/protocol/overview.md)
### Codex CLI 安装、登录与多入口排查
URL: https://codexguide.io/guides/codex-cli-multi-entry-setup
现在三大主流的编程工具分别是 Codex、Claude Code 以及 Gemini。Claude Code 的综合能力很强，也是我的主力编程工具，但它封号太严重了，对国内极其不友好，使用门槛比较高，要找到靠谱的渠道。
# Codex CLI 使用与多入口配置：终端、编辑器和网络排查
现在三大主流的编程工具分别是 Codex、Claude Code 以及 Gemini。Claude Code
的综合能力很强，也是我的主力编程工具，但它封号太严重了，对国内极其不友好，使用门槛比较高，要找到靠谱的渠道。
Gemini 目前在前端设计方面优势比较明显。Codex
普遍认为在代码审查方面做得比较出色，因为它分析很严谨，这导致的另一个问题就是速度会比较慢。但它使用起来门槛要低，因为现在 ChatGPT
只要你充了会员就可以直接用 Codex，而且现在用下来发现它的速度有所提升。
## ** Codex 是什么？ **
OpenAI 官方出品的 AI 编程工具，可以理解为终端版 ChatGPT，专门用来写代码。
** 四种使用方式： **
1. ** Codex ** ** CLI ** 在终端里直接对话写代码
2. ** Cursor 插件 ** 在 Cursor 编辑器里用 Codex 模型
3. ** VS Code 插件 ** 在 VS Code 里侧边栏对话
4. ** Opencode ** 在 Opencode 客户端里用 Codex 模型
** 为什么推荐用？ **
* Plus 会员（$20/月）直接用，不用额外买 API
* 比 Claude 稳定，不用担心封号
* Codex 的使用体验越来越好，速度提升了
** 前提条件： **
* 需要 ChatGPT Plus/Pro/Team 会员（免费账号不行）
* 需要科学上网环境
## 一、前置准备
### 1.1 注册 ChatGPT 账号
如果你已经有账号，跳过这一步。官网注册地址：https://chat.openai.com/
国内邮箱可用（QQ、163、Outlook 都行），不需要国外手机号，需要科学上网环境。
### 1.2 订阅 Plus 会员（必须）
** 因为Codex 只对付费用户开放，免费账号用不了。 ** Plus（ 月 ） 、 （ 200/月）、Team，任意一种都行。
不过ChatGPT 要绑海外卡支付，国内的visa不行，对国内用户不友好，网上可能也有一些方法，如果想省事的话找代充平台。
全网最稳！ChatGPT Plus 微信直充，2分钟到账（亲测丝滑）
升级成功后，在 ChatGPT 设置页能看到 Plus 标识。
## 二、Codex CLI（命令行）
### 2.1 安装 Node.js 环境（前提条件）
Codex CLI 基于 Node.js 运行，需要 ** Node.js 22 或以上版本 ** 。
** 先检查是否已安装： ** 打开终端（Mac）或 PowerShell（Windows），运行：
node -v
如果显示版本号 ≥ 22，跳过安装直接看 2.2。如果版本低于 22 或提示命令不存在，按下面步骤安装：
** 安装 Node.js： **
1. 打开浏览器访问 https://nodejs.org/
2. 官网提供两种安装方式，任选其一：
** 方式一：下载安装程序（推荐新手） **
页面下方有下载按钮，点击下载安装包：
** 方式二：命令行安装（适合有终端经验的用户） **
官网会显示一段安装命令（基于 nvm，一个 Node.js 版本管理工具）
直接复制到终端执行：
# Mac/Linux 用户执行这段命令
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc # 或 source ~/.zshrc
nvm install 24
Windows 用户建议直接用方式一下载安装程序，更简单。
* ** Windows ** ：下载 ` .msi ` 文件，双击运行，一路点「下一步」即可
* ** Mac ** ：下载 ` .pkg ` 文件，双击运行，按提示完成安装
3. 安装完成后重新打开终端，运行 ` node -v ` 确认版本 ≥ 22
### 2.2 安装 Codex CLI
#### Mac 用户
** 方式一：npm 安装（推荐） **
# 安装 Codex 最新版
npm install -g @openai/codex@latest
这个命令会从 npm 官方仓库下载并安装最新版本的 Codex 工具。
如果遇到权限问题，可以用 sudo：
sudo npm install -g @openai/codex@latest
国内网络慢可以用镜像加速：
npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com
** 方式二：Homebrew 安装 **
brew install codex
#### Windows 用户
** 第一步：打开 PowerShell（管理员模式） **
右键点击开始菜单 → 选择 Windows PowerShell 或 终端
** 第二步：执行安装命令 **
npm install -g @openai/codex@latest
同样国内网络慢可以用镜像加速：
npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com
> “
>
> Windows ：如果遇到权限问题，用管理员模式运行 PowerShell
#### 验证安装成功
安装完成后，运行：
codex --version
看到版本号就说明安装成功了。
### 2.3 登录授权
Codex CLI 支持两种授权方式：
#### 方式一：ChatGPT 官方账号登录（推荐）
终端输入 ` codex ` ：
codex
如果你没有配置任何第三方的 API key 的话，输入这个命令会弹出下面的弹框，这是官网的返回。
选择使用官网登录，就会跳转到官网，如果没有自动打开官网的话，也可以复制它提供的链接手动打开。
然后登录自己的 ChatGPT 账号，有会员的那一个。
看到这个界面就是登录成功了。
进入到下面这个页面，它会提示你现在 Codex 在哪个目录下面工作。
选项 1 表示允许AI 直接修改这个目录下的文件，或者直接运行终端命令，期间不会跳出任何确认提示。
选项2 表示 Codex 在修改任何一行代码或执行任何一条指令前，都会让你手动确认。
一般让它自动执行的情况比较多，每次都确认太麻烦了。选择之后就可以开始使用了。
授权成功后，token 自动保存到 ` ~/.codex/ ` 目录，下次启动不用重复登录。
#### 方式二：使用第三方 API（适合有 API key 的用户）
如果你有支持 Codex 模型的第三方 API 服务，可以通过配置文件使用，不需要 ChatGPT Plus 账号，比如 aigocode.com
这个中转服务站。
** 第一步：创建配置目录 **
mkdir -p ~/.codex
** 第二步：创建 config.toml 配置文件 **
nano ~/.codex/config.toml
填入以下内容（根据你的服务商修改）：
model_provider = "custom"
model = "gpt-5-codex" # 改成你的服务商支持的模型
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.custom]
name = "custom"
base_url = "https://api.xxx.com/v1" # 改成你的服务商 API 地址
wire_api = "responses"
requires_openai_auth = true
** 第三步：创建 auth.json 存放 API Key **
nano ~/.codex/auth.json
填入：
{
"OPENAI_API_KEY": "sk-你的API密钥"
}
** 第四步：验证配置 **
codex
如果配置正确，就能正常使用了。
> “
>
> ** 注意： ** 第三方 API 需要支持 Codex 相关模型（比如 ` gpt-5-codex `
> ）才能正常使用。配置前先确认服务商是否提供对应模型。
### ** 2.4 ** ** CLI ** ** 常用命令 **
#### 基础命令（新手使用必会）
** 启动和退出 **
命令 | 说明 | 使用场景
---|---|---
` codex ` | 启动交互模式，进入对话界面 | 需要多轮对话完成复杂任务
` codex "你的问题" ` | 启动时提问 | 快速问一个简单问题（感觉没必要）
` /quit ` 或 ` Ctrl+C ` | 退出 Codex | 结束当前会话
** 常用交互命令 **
命令 | 说明 | 使用场景
---|---|---
` /model ` | 切换模型和 reasoning effort | 简单任务切低配省额度，复杂任务切高配
` /approvals ` | 设置哪些操作需要确认、哪些自动执行 | 信任度高的项目开 full access，重要项目开 default
` /status ` | 查看当前模型、权限模式、token 使用情况 | 检查还剩多少额度
` /clear ` | 清空当前对话历史，重新开始 | 换个话题，不想让之前的对话影响回答
` /compact ` | 压缩上下文，对话太长时用这个释放空间 | 聊了很久 token 快用完时（也会自动压缩）
` /new ` | 开始新对话（不退出当前会话） | 当前任务完成，开始下一个任务
` /review ` | 审查当前代码改动，找出问题 | 写完代码让 AI 帮忙 review
下面是部分命令的截图。
/model
/approvals
/compact
/status
/new
/review
** 会话管理 **
命令 | 说明 | 使用场景
---|---|---
` /resume ` | 恢复之前保存的对话 | 第二天继续昨天的重构任务
` /fork ` | 从当前对话分叉出一个新对话 | 想尝试不同方案但保留当前进度
** 进阶功能 **
命令 | 说明 | 使用场景
---|---|---
` /skills ` | 使用技能来优化 Codex 执行特定任务 | 让 AI 用特定技能处理任务（下面有单独介绍，非常推荐！！）
` /experimental ` | 开启/关闭实验性功能 | 尝鲜新功能
#### 进阶命令（高手进阶）
** 启动参数 **
命令 | 说明 | 使用场景
---|---|---
` codex --full-auto ` | 全自动模式，AI 直接执行不需确认 | 批量处理文件、自动化脚本
` codex -a on-request ` | 让模型每次执行命令前都需要你确认 | 重要项目，想逐步确认每个操作
` codex --model gpt-5-codex ` | 指定使用的模型 | 临时切换模型不想改配置
` codex --help ` | 查看所有可用参数 | 忘记某个参数怎么写
** 危险但方便的操作（谨慎使用） **
命令 | 说明 | 使用场景
---|---|---
` codex --dangerously-bypass-approvals-and-sandbox ` | 跳过所有确认并禁用沙盒，AI 完全自主执行 | 每次都要手动确认好麻烦
> “
>
> 建议在测试环境或你完全信任 AI 输出时使用，颇具规模的生产环境慎用！
这些命令不需要全都记住，用的最多的可能就是启动命令、review 审查、compact 压缩、skills 查看技能这些了。codex在 ** 代码审查
** 这块是公认的比较强的。
#### 实用技巧
** 1\. 截图报错，让 AI 帮你修 **
Codex 是多模态模型，能看懂截图里的文字、界面元素等信息，能根据截图中显示的报错内容来分析问题、推断原因，并给出修复建议。
** 2\. 指定工作目录 **
cd /path/to/your/project
codex
Codex 会自动读取当前目录的代码上下文。
** 3\. 恢复之前的对话 **
Codex 会自动保存对话历史，下次启动时用 ` /resume ` 可以恢复之前的对话继续工作。
** 4\. 上下文太长时压缩 **
对话久了 token 会用完，用 ` /compact ` 压缩上下文继续工作。
* * *
## 三、VS Code 插件
不习惯用命令行的话，推荐 VS Code 插件，更直观。
### 3.1 安装插件
1. 打开 VS Code
2. 左侧扩展商店
3. 搜索 ` Codex `
4. 找到 OpenAI 官方的 ** Codex ** 插件，点击安装
### 3.2 登录使用
安装后，左侧边栏会出现 Codex 图标：
1. 点击 Codex 图标，弹出登录提示
2. 点击登录，浏览器会自动打开授权页面（和 CLI 一样）
3. 用 ChatGPT Plus 账号授权
4. 授权成功后，回到 VS Code 就能在侧边栏对话了
### 3.3 使用技巧
** 选中代码快速提问 **
选中一段代码 → 右键 → 选择 ` Ask Codex ` → AI 会针对选中的代码回答
## 四、Cursor 集成
Cursor 是目前最火的 AI 编程编辑器之一，本身自带 Claude 模型，但你也可以切换成 Codex 模型。
### 方式一：安装 Codex 插件
和 VS Code 一样，在 Cursor 的扩展商店搜索 Codex 插件安装。
* 如果已经配置了 API Key，安装后直接可用
* 如果没有配置，需要授权登录 ChatGPT 账号
### 方式二：对话框切换模型
在 Cursor 的 AI 对话框中直接切换到 Codex 模型。
> “
>
> ** 注意： ** 这种方式走的是 OpenAI API 计费，不是 ChatGPT Plus 会员额度。你需要在
> platform.openai.com 有 API 余额，并在 Cursor Settings → Models → OpenAI API Key
> 里填入你的 Key。
这个操作步骤有需要的话可以试一下，我平常用cursor不多，如果发现有新的使用方法，欢迎留言指正。
操作步骤：
1. 打开 Cursor 设置
2. 点击 Models，向下滚动找到 "OpenAI API Key"
3. 填入你的 API Key
4. 在对话框选择 Codex 系相关的模型
### 地区限制问题
如果遇到报错： ` This model provider doesn't serve your region ` ，说明 Cursor
检测模型服务商不对你这个IP所属地区开放。
** 解决方案： ** 开全局代理（增强模式/系统代理）。如果开了还是报错，可能是 Cursor 没有走系统代理，可以尝试在 Cursor
Settings 里搜索 proxy 配置代理地址。
** 如果代理问题不好解决，建议用Codex 插件或者直接用 Codex CLI / Opencode，这些方式更稳定。 **
* * *
## 五、Opencode 集成
Codex 支持 OpenCode，允许用户直接在 Opencode 中使用 Codex 订阅和使用限制，也就是可以直接登录自己的 pro 或者 plus
账号使用。
我这里就分享一下客户端连接的过程，用命令行也是一样的。
首先下载一下 Opencode 客户端，地址：https://opencode.ai/download
安装完之后就进入到这个页面，还是什么都没有的状态。
看了一下，macOS 版目前没有“添加模型”的按钮（我这边是 macOS 15.7.3，OpenCode Desktop
1.1.34）我就以这个版本测试了，具体的要看你们的系统和安装的版本，Windows 有些版本左下角会出现 “+”添加模型。
左上角的加号可以添加项目。
在对话框输入 /model 命令可以选择模型，右上角有个 连接供应商 按钮。
选择 连接OpenAI，如果你开了会员的话，这里登录你的 ChatGPT 账号。
需要授权或直接跳转到 ChatGPT 登录页面，和上面的流程是一样的。
授权成功就可以使用了 ChatGPT 的模型了，然后在这个地方可以管理模型。
## 六、常见问题 & 踩坑指南
问题 | 原因 | 解决方案
---|---|---
安装时报错 ` npm ERR ` | Node 版本太低 | 升级到 Node 22+
登录后一直 thinking | 网络问题 | 开全局代理，或设置环境变量（见下方）
Cursor 里找不到 Codex 模型 | 版本问题 | 更新 Cursor 到最新版
` /model ` 命令无响应 | 网络延迟 | 等待几秒，或检查代理设置
** 网络问题解决方案： **
如果遇到一直 thinking 或连接超时，在终端设置代理：
# 临时设置（当前终端有效）
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
# 然后启动 Codex
codex
把 ` 7890 ` 换成你的代理端口。
原稿还包含一张外部工作流示例图，保留在这里作为上下文参考：
## 七、总结
Codex CLI 的入口和参数会随版本变化。完成安装后，先确认登录状态，再用一个可回退的小任务验证命令、权限和网络设置。
参考资料：
- [Codex CLI 官方文档](https://developers.openai.com/codex/cli)
- [Codex Manual](https://developers.openai.com/codex/codex-manual.md)
### Codex 使用 Remotion 和 HyperFrames 制作视频
URL: https://codexguide.io/guides/codex-remotion-hyperframes-video
Remotion 和 HyperFrames 都能把视频写成代码，Codex 可以读取脚本与素材，生成项目文件，启动预览并根据检查结果修改。它们是第三方工具，工作方式和适用场景不同。视频仍要经过人工审片，工具也不会自动解决素材版权、节奏和事实准确性。
# Codex 使用 Remotion 和 HyperFrames 制作视频
Remotion 和 HyperFrames 都能把视频写成代码，Codex 可以读取脚本与素材，生成项目文件，启动预览并根据检查结果修改。它们是第三方工具，工作方式和适用场景不同。视频仍要经过人工审片，工具也不会自动解决素材版权、节奏和事实准确性。
> 原稿中的成片示例，社交平台播放器界面保留用于说明竖屏视频结果。
## 两套工具怎样选
Remotion 使用 React 组件和时间轴 API 生成视频。它适合长期维护的模板、数据驱动视频，以及需要复用组件的项目。
HyperFrames 使用 HTML、CSS、媒体文件和时间属性描述画面。它面向 Agent 工作流，适合快速制作样片、网页转视频和短篇动效。当前 npm 包要求 Node.js 22 或更高版本，许可证为 Apache-2.0。
> 概念示意，两套工具分别采用 React 和 HTML 路线。
> 概念示意，代码、媒体素材、时间线和预览共同组成视频项目。
| 需求 | 更合适的起点 |
|---|---|
| 快速制作一版 HTML 动效样片 | HyperFrames |
| 把网页、产品页或 PR 做成短视频 | HyperFrames |
| 长期维护固定栏目模板 | Remotion |
| 用数据批量生成同结构视频 | Remotion |
| 团队已有 React 工程经验 | Remotion |
这张表只用于选择起点。同一项目可以先用 HyperFrames 试视觉，再把稳定结构迁移到 Remotion。
> 概念示意，工具选择取决于样片速度、技术栈和复用需求。
## 先给 Codex 一份视频 Brief
Codex 需要可执行的输入。至少准备视频用途、比例、时长、脚本、素材目录、视觉规则和验收标准。可以把这些内容写进 `docs/video-brief.md`。
```markdown
# 视频 Brief
[基本信息]
- 平台和比例
- 分辨率、帧率和时长
- 目标观众与视频目的
[素材]
- 文件路径与用途
- 必须使用和禁止使用的素材
- 字体、图片、视频和音乐的授权状态
[分镜]
- 每一段的起止时间
- 画面、字幕、旁白和动效
[验收]
- 字幕不越界、不遮挡主视觉
- 图片和视频不拉伸
- 时长与导出规格正确
- 关键画面能够解释脚本内容
```
> 概念示意，准备、实现、预览和渲染需要分开验收。
素材文件要使用能说明内容的名字，并按场景或用途分组。`final-final-v3.mp4` 这类名称会增加 Codex 误用素材的概率。
> 概念示意，视频目标、脚本、素材、视觉规则和技术规格应同时提供。
## 用 HyperFrames 生成 HTML 视频
先检查 Node.js 和 FFmpeg。
```powershell
node -v
ffmpeg -version
```
HyperFrames 官方仓库提供 Agent Skills。安装前先检查仓库和权限，随后按当前文档执行。
```powershell
npx skills add heygen-com/hyperframes --all
npx hyperframes init my-video
cd my-video
npx hyperframes preview
```
HyperFrames 通过 `data-start`、`data-duration` 和 `data-track-index` 描述片段在时间线中的位置。项目还需要为画面根节点设置 `data-composition-id`、宽度和高度。动画必须可以按时间定位，不能依赖不可重复的随机数或真实时间。
让 Codex 开始实现时，可以使用下面的任务说明。
```text
读取 docs/video-brief.md 和 assets 目录。
先输出带时间码的分镜计划，确认后再写 HTML、CSS 和动画。
只使用现有素材，缺少文件时列出缺口。
预览后检查字幕安全区、文字溢出、素材比例和时长。
通过 lint、validate 与 inspect 后再渲染 MP4。
```
当前 HyperFrames CLI 提供的质量检查以本地 `--help` 为准。已安装版本支持时，可以依次运行下列命令。
```powershell
npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
npx hyperframes render
```
## 用 Remotion 维护 React 视频模板
Remotion 更适合把标题页、内容页、字幕和结尾页拆成组件。脚本与素材路径通过 props 或数据文件传入，同一套组件可以生成多条结构一致的视频。
新项目可以从官方脚手架开始。
```powershell
npx create-video@latest
npx remotion studio
```
先在 Studio 中确认 Composition、帧率、尺寸和时长。让 Codex 修改组件时，每次只处理一类问题，例如字幕位置、场景节奏或素材裁切。全部画面确认后再运行渲染命令。
```powershell
npx remotion render
```
实际项目可能需要入口文件、Composition ID 和输出路径。运行 `npx remotion render --help`，让 Codex 根据当前项目配置补齐参数。
## 权限和工作目录要收紧
Codex 需要读取素材、安装依赖、启动本地服务和写入输出目录。授权范围只覆盖当前视频项目，不要把无关目录、账号凭据和私人素材一并开放。
> 实操界面，开始任务前确认 Codex 的项目访问范围。
## 预览时检查关键帧
代码能运行只说明工程通过了最低门槛。审片时需要查看开头、转场前后、字幕最密集处和结尾。长视频还应抽取更多时间点，避免只看第一屏。
活动回顾类视频可以先画出时间线，明确开场、主体和收尾各占多少时间。
> 概念示意，时间线先确定信息节奏，再进入工程实现。
一轮提示只改一个问题，并要求 Codex 重新预览对应时间点。最终检查至少包含以下内容。
- 所有本地素材都存在，没有虚构路径。
- 字幕在手机安全区内，字体可以正常加载。
- 图片和视频保持原比例，转场没有空白帧。
- 音乐、字体、图片和视频素材具备所需授权。
- 输出分辨率、帧率、时长和文件名符合 Brief。
> 概念示意，先完成判断和时间线，再生成工程并自动质检。
## 使用限制
Remotion 的许可条件会随组织规模和用途变化，商业使用前应查看当前许可证页面。HyperFrames 当前使用 Apache-2.0，仍要单独检查项目引用的字体、音乐和媒体素材。
视频项目应该和 MP4 一起保留。后续更换标题、脚本或素材时，Codex 可以在原项目上修改并重新渲染，省去重新搭建时间线。
## 参考资料
- [Remotion 关于编码 Agent 的说明](https://www.remotion.dev/docs/ai/coding-agents)
- [Remotion 文档](https://www.remotion.dev/docs/)
- [Remotion License](https://www.remotion.dev/docs/license)
- [HyperFrames GitHub 仓库](https://github.com/heygen-com/hyperframes)
- [HyperFrames Quickstart](https://hyperframes.heygen.com/quickstart)
- [HyperFrames License](https://github.com/heygen-com/hyperframes/blob/main/LICENSE)
### Codex 内容生产工作流
URL: https://codexguide.io/guides/codex-content-production-workflow
Codex 可以把内容生产拆成一组可检查的任务。调研留下来源，写作读取事实表，配图说明用途，发布后的数据再回到下一轮选题。这样做适合需要持续更新教程、博客或社交内容的人，也适合多人协作的内容团队。
# Codex 内容生产工作流
Codex 可以把内容生产拆成一组可检查的任务。调研留下来源，写作读取事实表，配图说明用途，发布后的数据再回到下一轮选题。这样做适合需要持续更新教程、博客或社交内容的人，也适合多人协作的内容团队。
这套方法不要求一次装齐所有插件。先选出当前最耗时间的两三个环节，用一个真实选题跑通，再决定要不要增加工具。
> 概念示意，展示 Codex 可以连接的内容处理环节。
## 先建立内容工作目录
让 Codex 直接在聊天里交付整篇文章，后续很难核对来源，也不方便继续修改。可以先准备一个小型工作目录。
```text
content-project/
brief.md
research.md
sources.md
draft.md
assets/
review.md
```
`brief.md` 写读者、主题和交付格式。`research.md` 保存调研笔记，`sources.md` 单独记录链接、日期和引用位置。正文只写入 `draft.md`，检查结果放进 `review.md`。这几个文件足以让 Codex 知道每一步该读什么、该交付什么。
> 概念示意，同一工作台可以按任务接入少量必要能力。
## 调研阶段先收集证据
网页、PDF 和知识库适合处理不同材料。
- 浏览器用于打开官方文档和一手来源，记录页面地址与访问日期。
- PDF 工具用于提取报告中的数据、页码、统计范围和脚注。
- Notion 等知识库插件适合查询团队已经整理的选题、采访和历史结论。
可以先让 Codex 生成事实表，不要立刻写稿。
```text
调研这个选题，优先使用官方网站和一手资料。
把结果写入 research.md，并在 sources.md 记录链接、发布日期和访问日期。
每条结论标明它能证明什么，遇到冲突信息时保留双方口径。
先交付事实表，不要写正文。
```
PDF 中的数字还要附页码和口径。网页标题、产品价格、开放范围和软件版本会变化，定稿前需要重新访问来源。
> 概念示意，原始网页和报告先转成可追溯的事实，再进入写作。
## 写作阶段给清楚边界
`draft.md` 应当只使用已经整理的材料。提示词里写清正文要保留的事实、不能改动的数字、引用格式和未知部分。材料不够时，让 Codex 缩短文章或列出缺口，不要用泛泛解释补长度。
需要 Word 交付时，可以使用 Documents 类工具处理批注、修订和格式。只发布 Markdown 时，直接在项目内编辑更简单。无论使用哪种入口，都要保留一份能继续修改的源文件。
一轮修改只处理一个问题。先看事实与结构，再检查标题、段落和语气，最后检查链接、图片和格式。把所有要求塞进一次提示，容易出现局部修好、其他部分又被改坏的情况。
## 配图和内容复用分开处理
生成式图片适合概念示意和封面草案，不能充当产品界面、新闻现场或真实操作证据。涉及产品功能时，优先使用官方图片或经过脱敏的实操图。
一篇核心文章完成后，可以继续生成演示文稿、轮播图或视频脚本。每种格式都应重新安排信息密度，不能把长文原样塞进画面。
> 概念示意，发布后的数据用于修正下一轮选题和表达。
> 概念示意，核心文章可以派生其他格式，但每种格式需要单独编辑。
## 用数据做复盘
平台导出的表格可以交给 Spreadsheets 类工具检查。先处理缺失值、重复记录和异常值，再比较标题、主题、发布时间与内容形式。
不同平台的指标口径不能直接混用。阅读量、播放量、完播率和收藏率分别说明不同问题，相关性也不能写成因果。复盘结果可以更新 `brief.md`，也可以写入选题库，供下一轮调研使用。
```text
读取最近 90 天的内容数据。
先列出缺失值、重复记录和异常值，再按主题与内容形式比较。
标出高点击低留存、低点击高转化的内容，不把相关性写成因果。
把可复用结论写入 review.md。
```
## 安装插件前检查权限
Skill 是一套供 Codex 遵循的任务方法。插件还可能包含 Skills、外部应用连接和工具。安装前要查看来源、脚本、连接器与权限，并确认它会把哪些数据发送给外部服务。
未发布客户材料、账号凭据和个人隐私不应直接上传。外部账号按需连接，完成任务后也要检查是否仍需保留授权。
> 概念示意，先核对来源和权限，再用一个小任务验证。
## 跑通一次最小流程
第一次可以只使用网页调研、Markdown 编辑和表格复盘。
1. 在 `brief.md` 写清读者和交付要求。
2. 让 Codex 调研并生成 `research.md` 与 `sources.md`。
3. 核对关键来源后生成 `draft.md`。
4. 分轮检查事实、结构、语气、图片和链接。
5. 发布后导出数据，把复盘写入 `review.md`。
这条流程稳定以后，再接入知识库、文档、设计或视频工具。每增加一个连接，都要说明它解决了哪个问题，以及结果怎样验收。
## 参考资料
- [Codex Skills](https://developers.openai.com/codex/skills)
- [Codex Plugins](https://developers.openai.com/codex/plugins)
- [OpenAI Plugins 仓库](https://github.com/openai/plugins)
### 给 Codex 写一个专属 Skill：从重复提示词到可复用工作流
URL: https://codexguide.io/guides/codex-zhuan-shu-skill
用 Codex 久了，发现自己攒了一堆万能咒语。
# 给 Codex 写一个专属 Skill：从重复提示词到可复用工作流
用 Codex 久了，发现自己攒了一堆万能咒语。
比如每次让它建新 Python 项目，都得复制粘贴同一大段话，用 uv 管理依赖、目录按 src 布局、必须配 ruff 和 pytest、README
要带徽章……
几十行，存在备忘录里，每次开新项目翻出来贴一遍，改需求了还得回去改那段话。
时间一长，这些咒语散落在各种地方，自己都记不清最新版在哪。
后来才知道，这件事 Codex 官方早有正规解法，叫 ** Skill ** 。
把这套流程写成一个文件，Codex 就永久记住了，之后不用再贴那一长串，一句帮我建个新项目它就照着自己定的规范来。
更妙的是它的加载方式，Codex 平时不会把所有 Skill 的完整内容都塞进上下文，它只记住每个 Skill 的名字和一句描述， ** 只有真要用到某个
Skill 时，才去读它的完整内容 ** ，所以你哪怕写了几十个 Skill，也不占用平时的对话空间。
这篇就手把手带你写一个自己的 Skill，从最简单的纯文字版，到进阶带脚本的版本。跟着敲，十分钟你就有了第一个专属技能。
## Skill 到底是什么
一句话： ** Skill 就是一个文件夹，里面放一份告诉 Codex遇到某类活该怎么干的说明书。 **
这个文件夹里，唯一必须有的东西是一个叫 ` SKILL.md ` 的文件。
它开头有一小段元数据（名字和描述），下面是给 Codex 看的具体步骤。
就这么简单，一个纯文字的 ` SKILL.md ` 就是一个能用的 Skill 了。
如果需求复杂点，文件夹里还可以放这些可选的东西：
• ` scripts/ ` ：可执行脚本，需要确定性结果时用（比如一段必须精确执行的构建逻辑）
• ` references/ ` ：参考文档，给 Codex 补充背景知识
• ` assets/ ` ：模板、资源文件，比如项目脚手架的模板
但记住，这些都是可选的。
官方也建议： ** 能用文字说清楚的，就别写脚本 ** ，只有当你需要精确、可重复的行为，或者要调外部工具时，才上脚本。
## 先搞清楚它放在哪、怎么被触发
在动手前，得先明白两件事，不然写完了不知道 Codex 能不能找到、会不会用。
** 第一，放哪。 ** Codex 会从几个位置扫描 Skill，最常用的是这两个：
• ** 项目级 ** ：放在项目里的 ` .agents/skills/ ` 目录下。适合团队协作，把 Skill 提交进 Git，所有人
clone 下来就都有了。
• ** 用户级 ** ：放在你个人目录的 ` ~/.agents/skills/ ` 下。适合自己的通用技能，不管在哪个项目都能用。
这篇的例子放用户级，因为建新项目这种事跟具体某个仓库无关。
** 第二，怎么触发。 ** 有两种方式：
• ** 显式调用 ** ：在对话里用 ` $技能名 ` 直接点名，或者输入 ` /skills ` 从列表里选，想精确控制用哪个时用这个。
• ** 隐式调用 ** ：正常描述任务，Codex 发现内容跟某个 Skill 的描述对上了，自动就用了。
这里藏着一个关键点， ** 隐式触发全靠写的那句 ` description ` 。 ** 描述写得准，Codex 才知道什么时候该拿出这个技能。
所以描述里要把什么时候用、什么时候不用讲清楚，并且把关键触发词放前面。
## 写第一个 Skill
做一个真实例子：一个按我的规范新建 Python 项目的 Skill。
** 第一步，建目录。 **
mkdir -p ~/.agents/skills/new-python-project
** 第二步，在里面建一个 ` SKILL.md ` ，内容如下： **
---
name: new-python-project
description: 当用户要新建、初始化一个 Python 项目或搭项目脚手架时使用。按团队规范生成目录结构、依赖管理和基础配置。不用于给已有项目加功能。
---
按以下规范初始化一个新的 Python 项目：
1. 用 `uv` 初始化项目，不要用 pip + venv。
2. 采用 src 布局：源码放在 `src/包名/` 下。
3. 必备开发依赖：`ruff`（lint + format）、`pytest`（测试）。
4. 生成 `pyproject.toml`，配置好 ruff 和 pytest 的基础规则。
5. 建一个 `tests/` 目录，放一个能通过的占位测试。
6. 生成 `README.md`，包含项目名、安装步骤、运行测试的命令。
7. 建好后运行一次 `uv run pytest` 确认能跑通，把结果告诉我。
注意看那段元数据里的 ` description `
，特意写清了什么时候用（新建/初始化项目）和什么时候不用（不用于给已有项目加功能），这就是让隐式触发准确的关键。
** 第三步，就没了。 ** Codex 会自动检测到新 Skill，如果它没出现，重启一下 Codex 就行。
## 试一下效果
现在打开 Codex，随便找个空目录，直接说一句大白话：
> 帮我在这里新建一个叫 datakit 的 Python 项目
因为这句话正好撞上了 Skill 描述里的新建 Python 项目，Codex 会自动加载 ` new-python-project ` 这个
Skill，然后严格按写的七步来：用 uv 初始化、建 src 布局、配好 ruff 和 pytest、写 README、最后跑一遍测试给你看。
也可以不靠它自己猜，直接显式点名：
> $new-python-project 项目名叫 datakit
效果一样，只是更精确，整个过程一个字的规范都没重复写，全在那份 ` SKILL.md ` 里了。
以后规范变了，改那一个文件就行，不用再翻备忘录。
## 什么时候该加脚本
上面的纯文字 Skill 已经能覆盖大多数场景了，但有些活，需要它每次都分毫不差地执行，这时候就轮到 ` scripts/ ` 上场。
举个例子。假设建项目这步里，有一段生成配置文件的逻辑，希望它完全固定、不受模型自由发挥影响，可以把这段逻辑写成脚本：
mkdir -p ~/.agents/skills/new-python-project/scripts
在 ` scripts/ ` 里放一个 ` init_config.py ` （或 shell 脚本），把那段确定性的逻辑固化进去。然后在 `
SKILL.md ` 里，把对应那步改成「运行 ` scripts/init_config.py ` 生成配置」。
判断标准很简单：
• ** 步骤描述清楚、允许模型灵活处理 ** → 用文字就够了。
• ** 必须精确、可重复，或要调外部工具 ** → 写成脚本。
别一上来就写脚本。文字版好维护、好读、改起来快，脚本是给非它不可的场景准备的。
## 几个让 Skill 更好用的习惯
** 一个 Skill 只干一件事。 ** 别把建项目 + 发布 + 写文档塞进一个 Skill，拆成三个，职责单一，Codex 才好精准匹配。
** 描述里带上触发词。 ** 因为 Codex 装了很多 Skill
时，会自动把描述缩短显示，所以要把最关键的使用场景和触发词放在描述开头，缩短了也不影响匹配。
** 用祈使句写步骤，输入输出写明确。 ** 生成 pyproject.toml，包含 ruff 配置比处理一下配置强得多，你写得越具体，它执行得越稳。
** 写完拿几种说法测一下。 ** 用不同的大白话去触发，确认该出现的时候出现、不该出现的时候不乱触发，再微调描述。
## 写在最后
Skill 这东西，本质是把你脑子里那套这活儿该怎么干的经验，从一次性的口头指令，变成了一份可以反复调用、持续迭代的资产。
以前我们用 AI，靠的是当场把要求讲清楚，讲一次用一次。有了
Skill，你讲清楚一次，它就永久记住，而且团队里每个人都能共享同一套标准。这中间的差别，用久了会越来越明显——会写 Skill
的人，等于给自己配了一队随叫随到、还从不忘事的专属助手。
今天这个「新建 Python 项目」只是最基础的例子。你完全可以照着这个套路，把自己天天重复的活——生成周报、按规范提
PR、跑固定的检查流程——一个个都教给 Codex。写第一个的时候花十分钟，之后每次都省十分钟。
延伸阅读：
• Codex Skills 官方文档：https://developers.openai.com/codex/skills
• 开放 Agent Skills 标准：https://agentskills.io
* * *
### GitHub Issue 到 Pull Request：让 Codex 跑完整协作流程
URL: https://codexguide.io/guides/codex-github-issue-pr-workflow
之前，我拿一个积压了很久的小 Issue 做了个实验，不打开编辑器，全程只在 GitHub 的 Issue 和 PR 评论区里 @codex 给它派活，看它能把这条 Issue 推进到什么程度。
# GitHub Issue 到 Pull Request：让 Codex 跑完整协作流程
之前，我拿一个积压了很久的小 Issue 做了个实验，不打开编辑器，全程只在 GitHub 的 Issue 和 PR 评论区里 @codex
给它派活，看它能把这条 Issue 推进到什么程度。
结果比我预期的走得远，它自己开了分支、写了代码、发起 PR、跑完 CI，最后连 review 意见都自己提了。
但也不是全程撒手不管，有几个环节该我拍板的地方,它老老实实停下来等我。
这篇就把这条链路拆开讲清楚，Codex 接上 GitHub 之后，从一条 Issue 到一个可合并的 PR，中间每一步到底谁在干活、哪一步是它的能力边界。
## 它是个能进仓库干活的队友，不是许愿池
很多人对「AI 写代码」的想象还停留在「我说一句它吐一段」。
Codex 跟 GitHub 打通之后不是这个模式，它更像一个能进你仓库、能开分支、能发 PR、能过 CI 的远程同事。
关键在于它跑在 ** 云端隔离环境 ** 里，你把任务甩给它，它在一个独立环境里干，该忙啥忙啥，甚至可以同时甩好几个任务并行跑，互不占用你本地机器。
干完了它提供一份改动摘要和 diff，有空了再回来看。
这个后台异步的特性，是它能串起整条 Issue-to-PR 工作流的前提。
## 开始之前：怎么让 GitHub 里能 @到 Codex
这套流程有个前提得先说清楚，@codex 不是 GitHub 自带的功能，得先把仓库和 Codex 连起来，光在评论里打 @codex 是不会有任何反应的。
前提：得有 ChatGPT 官方的 Codex 访问权限，能登录 chatgpt.com 进到 Codex 就行。
配置就三步：
* 第一步，给仓库接上 Codex cloud。在 chatgpt.com 的 Codex 里连接你的 GitHub 账号或组织，授权它访问你要用的那个仓库。这一步是把仓库和云环境绑上，@codex 才有干活的对象。
* 第二步，打开这个仓库的 Code review 开关。去 Codex 设置的代码审查页，把你那个仓库的 Code review 打开。不开这个，你在 PR 里 @codex review 它是不理你的。
* 第三步，在 PR 评论里 @codex。发一句 @codex review，等它冒个 👀 的表情回应，它就会像同事一样贴一份审查意见（只标 P0/P1 严重问题）。
几个进阶开关顺手一提：想每个新 PR 都自动审，在设置里打开 Automatic reviews；想让它按你的规矩审，在仓库根目录放一个 AGENTS.md
写审查准则；@codex 后面跟的不是 review 而是别的指令，它就当成一个新的云任务来跑。
如果 @了没反应，排查三点：这个仓库的 Code review 开关开了没、仓库接上 Codex cloud 没、触发词是不是准确写的 @codex
review。
## 第一步：从一条 Issue 起手
工作流的起点可以直接在已经在用的地方，GitHub 的 PR、Linear 的 issue、Slack 的频道，都能直接把活交给
Codex，不用切到别的界面。
具体到 GitHub，在一条 Issue 或 PR 里点名它，它就把这条 Issue 当作任务上下文，去云端环境开工。
它读得懂 Issue 描述里的诉求，也读得到仓库代码，所以不用把背景再复述一遍，这正是在仓库里干活和在对话框里问它的本质区别。
## 第二步：它在云环境里把代码写了
接到任务后，Codex 在配好的云环境里干活，这里有个容易被忽略的准备工作： ** 环境要可复现 ** 。
得先告诉它这个仓库需要哪些依赖、什么工具、哪些环境变量、怎么初始化，配好之后，它每次起的环境都跟本地那套一致，跑出来的东西才靠谱，不会出现它那边能跑我这边报错。
这一步基本是它自己完成的，可以在等结果，同时甩出去的其他任务也在各自的环境里跑，互不打架。
## 第三步：审查前你先把关
代码写完，Codex 不会替你直接合，它给你一份摘要和 diff，你来审。
这一步是我觉得设计得最克制、也最该保留的地方，可以看完就让它开 PR，也可以觉得思路不对、直接甩一句「follow-up」让它返工。
** 要不要进入下一环，决定权在你手里 ** ，它不会自作主张把没过目的东西推上去。
看着没问题了，就让它开 PR。到这儿，一条 Issue 已经变成一个躺在仓库里、等着被审的 Pull Request 了。
## 第四步：让它给自己的 PR 挑刺
PR 开出来之后，还有一步很多人不知道，Codex 能给 PR 做代码审查。
在 PR 评论里 @ 它并要求 review，它会像一个同事那样，看完整个 PR 的 diff，然后贴一份标准的 GitHub code review。
有意思的是它 ** 只标 P0 和 P1 的严重问题 ** ，不会拿一堆无关痛痒的风格碎碎念淹没评论区，这个取舍很务实，审查意见的信噪比一下就上去了。
如果嫌每次都要手动喊它麻烦，可以在设置里打开自动审查，之后每开一个新 PR 它都会自动过一遍，不用你招呼。
## 第五步：审查规矩写进 AGENTS.md，它照着挑
这里是让审查真正好用的关键：Codex 审查时会去翻仓库里的 ` AGENTS.md ` ，按你写的 review 规矩来挑。
在仓库根目录的 ` AGENTS.md ` 里写一段审查准则，比如：
## Review guidelines
- 不要在日志里打印 PII
- 确认每个路由都被鉴权中间件包住
它就会照着这些规矩审，而且规矩是 ** 就近生效 ** 的，哪个目录下的 AGENTS.md 离改动文件最近，就用哪份的规矩。
可以在某个需要额外盯紧的包目录里放一份更严格的 AGENTS.md，那个目录的改动就会被重点照顾。
想临时改一次审查重点也行，不用改文件，评论里直接说这次帮我盯安全回归就行。
## 第六步：让它顺手把问题修了
审查挑出问题之后，不用自己撸起袖子改。
在同一个 PR 里再 @ 它一句把那个 P1 问题修了，它会以这个 PR 作为上下文起一个新的云任务，在有权限的前提下，直接把修复推回这个分支。
CI 挂了也一样，甩一句「把 CI 的失败修了」，它就去查去修。
这时候整条链路就闭环了：发现问题 → 起任务 → 推修复，全在这个 PR 里转，不用你在本地来回切。
如果想把这套接进 CI 做成自动化，它还提供了 GitHub Action，可以塞进流水线里跑。
## 那到底「能做到哪一步」
** 它能自己干的 ** ：读 Issue 上下文、在隔离环境写代码、开 PR、过 CI、审自己的 PR（按你的规矩挑
P0/P1）、按指令推修复回分支，这一串确实能大幅省掉机械劳动。
** 还得把关的 ** ：合并前的审查确认（要不要开 PR、要不要 merge，它停下来等你）、审查规矩得你来定（AGENTS.md
是你写的）、环境得你配（可复现是前提）、真正拍板合入的那一下，是你的责任。
所以能做到哪一步的答案是， ** 它能把一条 Issue 推到「一个审查过、修过、CI 绿了的 PR」这一步，但最后按下 merge 的那个人，还是你。
这条线划得其实很健康，机械的活它包了，判断的活留给人。
## 写在最后
如果你手里有个仓库，别急着把整套流程一次上齐，先从最轻的一步试：给一个仓库开上 Codex 的代码审查，在下一个 PR 里 @ 它 review
一次，看看它挑出来的 P0/P1 靠不靠谱，觉得顺手了，再往前接 Issue 发起、往后接自动修复。
工作流这东西，是一步步长出来的，不是一次配到位的，但方向已经很清楚了，以后在 GitHub
上干的很多机械活，可以交给一个能进仓库的队友，你只要负责那些真正需要判断的环节。
延伸阅读：
* Codex cloud 官方文档：https://developers.openai.com/codex/cloud
* Codex 代码审查（GitHub）：https://developers.openai.com/codex/third-party/github
* Codex 开发者集成总览：https://developers.openai.com/codex/developers
* * *
### Codex 任务总跑偏？先检查这 5 个设置
URL: https://codexguide.io/guides/codex-settings-checklist
忙了一圈，使用体验还是别扭。
# Codex 任务总跑偏？先检查这 5 个设置
忙了一圈，使用体验还是别扭。
让它改一个小问题，它顺手碰了旁边几个文件。任务正在执行，临时补一句要求，不知道它会立刻改方向，还是等前面的工作结束。回复有时太长，有时又省掉了想看的解释。权限收得太紧，读文件、改代码、跑命令一路都在等确认。
这些问题未必需要一条更长的提示词。很多时候，Codex 还没按你的习惯设置好。
我把当前设置重新过了一遍，也对照了 OpenAI 的官方说明。开始干活以前，最值得先处理的是下面 5
项。顺序不必照着设置菜单走，我更建议从“你准备让它做什么”开始。
## 01 先选对入口， ChatGPT 和 Codex 是两个模式
左上角可以在 ChatGPT 与 Codex 之间切换。当前界面给出的说明很直白。
ChatGPT 用于“创建、学习和探索”，Codex 用于“构建、调试并发布”。
ChatGPT 与 Codex 入口
这两个入口有能力重叠，不能简单理解成 ChatGPT 只写文章，Codex 只写代码。
ChatGPT 更适合从对话出发。查资料、理解概念、比较方案、整理想法、写文档和规划产品，都可以在这里完成。即使是软件工作，也可以先用 ChatGPT
分析需求、讨论设计和写规格说明。
Codex 更像一个进入工作现场的编码智能体。它可以打开本地文件夹或代码仓库，阅读和修改文件，运行命令与测试，持续处理一个较长的工程任务。OpenAI 对
Codex 的定位也包括修复问题、开发功能、代码审查、迁移和准备可供人工审核的改动。
只需要讨论、研究、创作和规划，先用 ChatGPT。需要进入真实工作区，对文件和命令产生操作，切到 Codex。
## 02 把长期习惯写进自定义指令，再决定要不要开本地记忆
进入“个性化”，上半部分是自定义指令，下半部分是记忆。
自定义指令与本地记忆
自定义指令适合保存长期不变的协作要求。你希望它先分析还是直接做，要简短结论还是详细解释，能不能顺手调整相邻文件，都可以提前说清楚。
新手先写四条就够了。
先思考，再动手。
减少无关解释，优先回答当前问题。
只做必要修改，不随意扩大范围。
围绕目标给出结果和验证情况。
“启用本地记忆”，会根据这台电脑上的聊天创建记忆，用来个性化这台电脑上的后续聊天。
自定义指令和记忆解决的问题不同。前者是你主动写下的规则，后者会从聊天中保留可复用的信息。它们都不适合存放密钥、Cookie、客户资料和其他敏感内容。
如果你不希望某次聊天读取或更新记忆，可以关闭记忆，或者在支持的入口里使用临时聊天。官方也提供了查看、修改和删除记忆的控制。
## 03 回复总是太啰嗦，就把“个性”改成务实
“个性”决定 ChatGPT 默认用什么语气回复。当前界面提供两种选择。
“亲和”对应温暖、协作、贴心。它更愿意照顾阅读感受，解释通常也会多一些。刚开始接触 Codex，希望它多补背景、多讲原因，可以先用这一档。
“务实”对应简洁、专注、直接。它会更快进入问题，减少客套和铺垫。已经熟悉操作，平时更关心步骤、结果和风险提示，用这一档会省心很多。
回复个性中的亲和与务实
如果你经常觉得回复绕、重点难找，可以跟着这样设置。
个性只影响默认表达方式，不会改变模型能力和安全规则。具体任务的要求仍然优先。比如让它写一封温和的邮件，即使默认选择务实，它也会根据当前要求调整语气。
如果还想控制得更细，可以在自定义指令里补两句。
减少客套和重复总结。
先给结果，必要时再补原因和注意事项。
## 04 权限决定 Codex 能不能把一条任务连续做完
当前有三种选择。
“默认权限”允许 ChatGPT 读取和编辑工作空间里的文件，需要额外访问时再请求批准。
“自动审核”会自动审查额外访问权限请求，但界面明确提醒，自动审核可能出错。
“完整访问权限”允许它编辑电脑上的任何文件，并运行可以访问网络的命令，不再逐次等待批准。页面同时给出了数据丢失、泄露和意外行为风险提示。
默认权限、自动审核与完整访问权限
权限收得太紧，一条本来连续的执行过程会不断停下来。读文件、分析、修改、运行测试，每一步都在等人点确认，Codex 很快就变成了半自动工具。
完整访问确实省事，代价是监督更少。官方对 Full Access 的描述也是减少阻力，同时牺牲一部分人工监督。
熟悉、已经备份、风险可控的本地项目，可以按需要放宽权限。涉及数据库、生产环境、公开发布、账号配置和重要文件删除时，仍要在任务里写清边界。项目陌生、文件重要或没有备份时，默认权限会更稳。
## 05 跟进处理方式选“调整方向”，临时纠偏才不会排到最后
跟进处理方式中的调整方向
“跟进处理方式”决定 Codex 正在运行时，新消息怎样进入当前任务。当前有“加入队列”和“调整方向”两个选项。
加入队列会把新消息排到当前工作之后。适合要求已经明确、只想让后续任务按顺序执行的情况。
调整方向会让新消息参与当前执行。发现理解偏了，需要补一条限制，或者想让它立即缩小修改范围时，新要求可以直接改变正在进行的工作。
OpenAI 将这种用法称为 steering。它允许用户在 Codex 工作时补充上下文、修正方向、批准下一步，或者安排工具调用之后的动作。
对于新手，我更建议选择“调整方向”。需求往往很难一次写全，发现偏差后及时拉回来，比等它沿着错误方向做完更省时间。
## 基础设置调顺以后，再谈 Skill
前面 5 项决定 Codex 怎样跟你合作。Skill 解决的是另一件事，把一套重复出现的工作流程保存下来，让 ChatGPT 或 Codex
以后能够继续照着做。
一个 Skill 通常会写清任务什么时候触发、需要哪些输入、中间按什么步骤执行、最后交付什么，还可以带模板、示例和检查脚本。
新手不用先逛一堆网站，也不用研究哪一个 Skill 最热门。先把自己的痛点告诉 AI。
### Codex 插件安全检查：用 HOL Guard 评估第三方工具风险
URL: https://codexguide.io/guides/codex-plugin-security-hol-guard
现在装一个 AI 编程插件有多容易？一行命令的事。
# Codex 插件安全检查：用 HOL Guard 评估第三方工具风险
现在装一个 AI 编程插件有多容易？一行命令的事。
Codex 有了插件市场，Claude Code 有 skills，Cursor、Gemini 各有各的生态。
看到一个不错的插件， ` install ` 一下，它就接进了你的 agent，能读你的文件、能跑命令、能连网络，爽是真爽。
但有个问题估计你也想过：这工具安装装进来，我其实不知道它会干什么。
它是个第三方写的、几百行起步的代码包，里面塞了 skill、MCP
server、各种钩子。你装它的时候，等于把"读文件、执行命令、访问网络"这几样权限一起交了出去。
万一这插件里藏了点东西，比如趁你不注意把 ` .env ` 里的密钥发到某个服务器，大概率是发现不了的。
这不是吓唬人，AI agent 越权偷密钥、被 prompt 注入带跑偏，这些事已经实实在在发生过，问题是，普通开发者根本没有趁手的工具去防。
HOL Guard 想干的，就是给你的 AI 编程环境装一套杀毒系统。
## 装之前扫一遍，跑起来盯着拦
HOL Guard 不是单一功能，它把"安全"拆成了两个时间点来管。
** 第一个是装之前——plugin-scanner。 ** 拿到一个插件、skill 或者 MCP
server，先别急着用，拿它扫一遍打个分，它会把这个包从里到外检查一遍：清单写得规不规范、有没有硬编码的密钥、MCP 配置里有没有危险命令、GitHub
Actions 有没有被人做手脚、代码里有没有 ` eval ` 这种高危写法。
** 第二个是跑起来之后——hol-guard。 ** 这才是"杀毒"的核心。它常驻在 agent
前面，每一个工具动作真正执行之前，也就是在你的文件被改、网络被连之前——它先拦下来，毫秒级判断这一步该不该放行。
一句话概括： ** 扫描器管"这插件能不能信",Guard 管"这一步操作能不能放"。 ** 一个在装之前，一个在运行时，两头都堵上。
## 装之前怎么扫：给插件打一个体检分
先说扫描这块，因为最直接。
装个 scanner 很简单：
pipx install plugin-scanner
然后对着插件目录扫：
# 扫单个插件
plugin-scanner scan ./my-plugin
# 自动识别仓库里所有支持的生态(默认)
plugin-scanner scan ./plugins-repo --ecosystem auto
# 只扫 Claude 的包
plugin-scanner scan ./plugins-repo --ecosystem claude
它支持的不只是 Codex,Claude Code、Gemini CLI、OpenCode 的插件格式它都认，会自动从仓库里找出这些包逐个扫。
扫完会给一个分数，满分 130，分七个维度打：
清单规范 31 分
安全相关 36 分
运维安全 20 分
最佳实践 15 分
市场合规 15 分
Skill 安全 15 分
代码质量 10 分
这里有个设计挺聪明：它只评估这个插件 ** 实际暴露 **
的那些面。你没用到的可选功能，不会因为“没做”而扣分，也不会因为“做了”白送分，最后按适用项归一化。
这样小插件不吃亏，大插件也别想靠堆功能刷分。
光打分还不够，它还有一整套配套命令： ` lint ` 给你写插件时的规范建议， ` verify ` 检查能不能正常安装运行， ` submit
` 给提交市场做门禁， ` doctor ` 出问题时做诊断。
如果你是插件作者，想发布前先过一道质量关，直接把它塞进 CI:
-name:AIpluginqualitygate
uses:hashgraph-online/ai-plugin-scanner-action@v1
with:
plugin_dir:"."
fail_on_severity:high
min_score:80
这就是那个市场的硬门槛：分数得 ≥80，不能有 high 或 critical 级别的问题，否则 PR
直接卡住。说白了，能进市场的插件，都是被这套规则筛过一遍的。
## 跑起来怎么防？
扫描是一次性的，真正天天保护你的是 Guard。
装和初始化：
pipx install hol-guard
hol-guard init
` init ` 是引导式的首次设置，它有个我挺欣赏的细节： ** 每一步会动你东西之前，都先停下来问你。 **
先给你看一遍计划，然后开本地面板要你点头，再装 agent
防护要你点头，每个动作都卡一个确认点，你不批它就不动。不像有些工具上来一把梭，装完你都不知道它改了啥。
Guard 的核心是拦截。它守在你的 agent 前面，每个工具动作执行前先过它一道，毫秒级决定放行还是拦下。具体拦多严，你自己选档位：
hol-guard settings set security-level
四个档位是这么分的：
** Gentle(佛系) ** ——只拦最明确的密钥泄露和数据外传。适合有经验、嫌麻烦的人。
** Balanced(均衡，默认) ** ——拦密钥、shell 外传、prompt 注入、供应链钩子。大多数人用这个就够。
** Strict(严格) ** ——在上面基础上，连低置信度的可疑信号、不可信的 prompt 也一起拦。适合对安全比较上心的团队。
** Paranoid(偏执) ** ——再加上任何它不认识的 MCP server 动作，一律拦。高安全环境用。
官方的建议很实在：拿不准就从 Balanced 开始，用一周，回头看看它都拦了些啥，再决定要不要升到 Strict。
## 被拦了怎么办，误杀也能一键放行
实时拦截最怕的就是误杀——正常操作被挡住，活儿干不下去。Guard 这块处理得还行。
每次它拦一个动作，都会留一张"回执"，想知道它为什么拦你，几个命令查清楚：
hol-guard receipts # 看最近的拦截记录
hol-guard doctor # 跑一遍探针,看哪些检测器在生效
hol-guard approvals # 看待处理的审批
如果确认是误杀，从回执里直接批准放行就行；也可以打开本地面板 ` http://localhost:6174 `
，在审批中心里点放行，所有决定都存在本地，回头能复查。
对安全要求高的，它还能给审批本身再加一道锁：开启密码门，甚至上 TOTP 双因子(就是 Google Authenticator
那种动态码)，要批准一个全局放行、清空策略、改设置这种敏感操作，得先过密码加动态码，这一层对团队环境挺有用——防的是"有人手滑或者被诱导，一路点放行"。
还有个细节值得夸：它的威胁情报库更新是 ** 只拉不传 ** 的。你跑同步的时候，它只从服务器下载签名过的情报列表， **
不会把你的本地路径、配置、回执、工作区信息发出去 ** 。安全工具自己得先干净，这点它做到了。
## 适合谁，怎么开始
说实话，现在这个阶段，凡是认真用 AI 编程的人都该考虑装一套这种东西。
如果经常从市场装插件、装 skill、配 MCP server，那 Guard
对你几乎是刚需，装的每个第三方包都是一个潜在入口，有个东西在运行时帮你盯着，心里踏实得多。
如果自己写插件、还想发到市场，那 scanner 绕不开，市场门槛就是它定的，提前在本地和 CI 跑一遍，省得提交了被打回。
最快的上手路径就三步：
pipx install hol-guard
hol-guard init
hol-guard settings set security-level balanced
跑起来，用一周，看看 ` hol-guard receipts ` 里它都替你拦了些什么。
## 写在最后
HOL Guard 干的事其实特别朴素，它承认了一件我们都在装糊涂的事，你装进 agent
的那些第三方插件，根本不知道它们会干什么，以前这事儿只能靠运气和自觉，现在有了个能兜底的东西，装之前用 scanner 打个体检分，跑起来用 Guard
在每个动作前站一道岗，两头都堵上，中间那段你看不见的黑箱就被照亮了。
AI 写代码这波，大家都在拼谁生成得更快更准，很少有人管生成出来这堆东西安不安全。HOL Guard
补的正是这块空白。它不让你变慢，只是在你踩坑之前拉你一把。这个阶段，只要你认真用 AI 编程，给它配套这样的防线，真不算多余。
> 延伸阅读：https://github.com/hashgraph-online/hol-guard
* * *
### Codex 自动化与定时任务：从手动流程到 CI 执行
URL: https://codexguide.io/guides/codex-automation-ci-scheduled-tasks
用 Codex 的人，绝大多数都是这么用的：打开终端，输 codex ，进到那个交互界面，然后跟它一来一回地聊，你说要求，它改代码，看一眼再说下一句。
# Codex 自动化与定时任务：从手动流程到 CI 执行
用 Codex 的人，绝大多数都是这么用的：打开终端，输 ` codex `
，进到那个交互界面，然后跟它一来一回地聊，你说要求，它改代码，看一眼再说下一句。
这没错，也是它最顺手的形态，但用久了你会发现一个问题，它离不开你。
每一步都得有个人坐在屏幕前面，看着它、催着它、点着确认，活儿再简单，也得占着你一只手。
那些真正烦人的重复活儿，每天早上把昨晚的日志扫一遍挑出报错、每次发版前给 changelog
补一段、每周把某个目录的注释统一格式，你其实根本不想亲自坐那儿陪它聊。
你想的是，能不能让它自己跑，跑完把结果放那儿，我睡醒了直接看。
能！这就是 ` codex exec ` 干的事。
它是 Codex 的非交互模式，一条命令给个任务，它闷头跑完就退出，全程不需要盯着，这意味着可以把它写进 shell 脚本、塞进 CI 流水线、挂进
crontab 定时任务里，让 AI 变成一个能被自动化调度的东西。
## 交互模式和 exec 模式，差在哪
先把这两种形态的区别说清楚，不然不知道什么时候该用哪个。
平时敲 ` codex ` 进去的那个，是交互模式，一个持续开着的会话，你来我往，它随时等你输入。适合你还没想清楚要干嘛、需要边做边调整的活儿。
` codex exec ` 是非交互模式，把任务一次性喂给它，它自己规划、自己执行、跑完直接退出，中间不问你、也不等你。
它的设计目标就是无人值守，所以天然适合被脚本调用。
最基础的用法就一行：
codex exec"把 src 目录下所有函数补上类型注解"
回车，它就开始干了，任务描述也可以从管道喂进去，这在脚本里特别有用：
cat task.txt | codex exec
或者把前一个命令的输出直接接给它：
git diff | codex exec"根据这些改动，帮我写一段 changelog"
看出来了吧，它就是个普通的命令行程序，能读 stdin、能被 pipe、能拼进任何 shell 逻辑里。
这是它能自动化的根本原因。
## 想让它在脚本里听话，这几个参数得会
裸跑一句 ` codex exec ` 只是开始，真要把它嵌进自动化流程，你得让它行为可控、输出可读。
下面这几个参数是关键。
** 指定模型和思考强度。 ** 自动化任务往往不需要顶配模型，用 ` -m ` 挑一个够用的就行，思考强度用配置覆盖参数 ` -c `
来调，比如让它别想太久、快点出结果：
codex exec -m gpt-5.1-codex \
-c model_reasoning_effort="low" \
"把这个文件里的 print 全换成 logging"
这里的 ` -c ` 是个万能开关，能覆盖任何 ` ~/.codex/config.toml ` 里的配置项，用点号写嵌套路径，值按 TOML
解析。省钱、控速度，都靠它。
** 把最终结果单独存出来。 ** 这是脚本化里最实用的一个， ` -o ` 让 Codex
把它最后那段总结写进指定文件，后面的脚本直接读这个文件就行，不用去满屏的过程日志里 grep：
codex exec -o result.txt "检查依赖有没有已知的安全漏洞"
cat result.txt # 后续脚本读这里
** 权限和沙箱。 ** 无人值守时没人帮它点确认，所以你得提前把权限说清楚。 ` -s ` 指定沙箱策略（只读、还是允许写工作区）， `
--skip-git-repo-check ` 让它能在非 Git 目录里跑。
至于那个 ` --dangerously-bypass-approvals-and-sandbox ` （别名 ` --yolo `
），会跳过所有确认和沙箱。
这个只在本身已经被隔离的环境里用，比如一个一次性的 CI 容器，在自己主力机上图省事开它，等于把 AI 的手直接伸进你整个系统，出事没人拦得住。
一句话： ** 能限权就别放开，自动化环境里尤其是。 **
## 真正的杀手锏：–json 让输出能被程序消费
前面的参数还只是让它安静地跑， ` --json ` 才是把它接进流水线的关键。
加上这个参数，Codex 不再输出给人看的花哨界面，而是把整个执行过程按 JSONL 吐到标准输出。
它干了哪一步、调用了什么工具、最后说了什么，全都是结构化的。
结构化意味着什么？意味着你的脚本能 ** 读懂 ** 它的输出，然后据此做决策，配合 ` jq ` 这类工具，可以把它的结果接进任何后续逻辑：
codex exec --json "跑一遍测试，告诉我有没有失败" \
| jq -r 'select(.type=="item.completed") | .item.text' \
> report.txt
这一步是 AI 陪你干活和 AI 替你自动干活的真正分水岭。
人看得懂自然语言，程序看不懂；但程序看得懂 JSON。一旦 Codex 的输出能被程序消费，它就从一个聊天工具，变成了流水线里的一个可编程节点。
上游给它喂数据，它处理完，下游接着往下走，全程不需要人插手。
如果还想约束它最后返回的格式， ` --output-schema ` 能传一个 JSON Schema
文件，规定它最终答复必须长成什么样子，这样连解析都省了，拿到的直接是想要的结构。
## 几个能直接抄的自动化场景
参数讲完了，落到实处，下面几个是拿 ` codex exec ` 能立刻跑起来、也确实省事的活儿。
** 塞进 CI，让它当自动审查员。 ** 在 CI 流水线里加一步，每次提 PR 就让 Codex 扫一遍改动，把问题写进报告：
git diff origin/main...HEAD \
| codex exec -s read-only -o review.md \
"审查这些改动，列出潜在 bug 和风格问题"
用只读沙箱，它碰不了代码，只输出意见，审查结果落在 ` review.md ` ，在 CI 里把它贴成 PR 评论就行。
** 挂进 crontab，让它每天定时干活。 ** 比如每天早上八点，让它把昨天的错误日志汇总一遍：
0 8 * * * cd /path/to/project && \
codex exec -s read-only -o /tmp/daily.txt \
"扫一遍 logs/ 目录里昨天的日志，把报错归类总结" \
&& cat /tmp/daily.txt | mail -s "昨日日志汇总" me@example.com
人还睡着，报告已经在邮箱里了，这就是标题说的那个睡觉时自动干活，不是修辞，是真能这么排。
** 批量处理一堆文件。 ** 用最普通的 shell 循环，把它套在外面：
for f in src/*.py; do
codex exec -s workspace-write \
"给 $f 补上文档字符串，风格参考 Google style"
done
一个文件一次调用，跑完一个换下一个，几十个文件的机械活儿，扔给它挂着跑就是了。
看出这几个场景的共性了吗？
它们都不需要你在场，你要做的只是把任务描述清楚、把权限框好、把输出接对地方，剩下的交给调度器。
Codex 从一个你得盯着的对话框，变成了一个能被 cron、被 CI、被 shell 脚本随意调用的命令。
## 写在最后
Codex 最被低估的地方，可能就是大家默认它只能陪你在终端里聊，codex exec 把它从对话框里放了出来，它可以是脚本里的一个命令、CI
里的一步、crontab 里的一行。你要做的，只是把任务说清楚、把权限框好、把输出接对地方，剩下的交给调度器。
上手不用一步到位，想省事的，先把 git diff | codex exec 写进小脚本帮你生成 commit message，跑顺了再往 CI 和定时任务加；无人值守的活儿从只读、低风险的做起，验证靠谱了再放开权限。说到底，交互模式解决怎么和 AI 一起干活，exec 模式解决怎么让 AI 替你自动干活。
* * *
### Codex 协助出海 SEO：第一次购买客座文章的核验流程
URL: https://codexguide.io/guides/codex-chu-hai-seo-shi-zhan
继续给网站做 SEO 外链实验。
# Codex 协助出海 SEO：第一次购买客座文章的核验流程
继续给网站做 SEO 外链实验。
之前我对客座文章这种外链方式只停留在概念上，知道它大概是找一个相关网站，发布一篇带链接的文章，用来给目标页面增加相关性和权重。
现在属于新手实际操作一遍，这个过程中 codex 起到了很大的作用！
平台怎么用，筛选条件怎么设，哪些网站看起来指标好但不值得买，文章该怎么写，提交前有哪些必填内容...
Codex 很适合做这种平台的实操，替我把大量细节先梳理清楚，替我操作。
## 先用小预算熟悉平台
这次选的平台是 Adsy，一个可以买客座文章和内容发布的平台。这次只是想先用一笔小钱熟悉流程。
第一次进入这类平台，最容易被一堆指标绕晕。价格、DR、DA、Ahrefs Organic Traffic、Semrush Total
Traffic、国家、语言、分类、Dofollow。
Codex 先给了我筛选条件。针对自己的网站情况，我们先把语言限定为英文，把分类限定在 Software development 和
Technology，再给价格设一个上限。
目标很明确，先把范围缩小到和自己的网站更相关、预算还能接受的网站，不追求找到全平台最强的网站。
** 这一步里，人要做的是定边界。 **
比如我知道这次是给 AI 工具站做外链，不想买太泛娱乐、金融、生活方式的站。Codex 做的是把这些边界翻译成平台上的筛选条件，再帮我解释每个指标代表什么。
## 看指标，也看这个站像不像真的相关
筛出来以后还有几百个网站，这时候平台的推荐排序就不够用了。
Codex 帮我做了一轮人工筛选。它会看每个站的价格、流量、DR、DA、Dofollow，也会继续去 Google 搜这个站有没有 AI
tools、developer tools、software development 相关内容。
这个过程里，我学到一个很实用的判断方法。
** 一个站不能只看指标，还要看它平时发什么内容。如果一个站满屏都是 crypto、loan、casino、trading 这类高商业化内容，即使 DR
看起来很高，也要谨慎。 **
它可能更像一个卖链接的内容农场。
这一步里，人要判断业务价值。Codex 可以帮我把 900 多个候选缩成几个优先级，但最后为什么选一个站，还是要回到项目目标上。我们的网站是 AI
工具目录和工具决策站，不应该为了一个便宜链接去买完全不相关的网站。
## 文章不是随便写一篇就行
确定网站以后，下一步是准备 guest post。
这次我们的承接页是一篇关于免费 AI coding assistant 的文章，所以客座文章也围绕开发者如何选择免费 AI 编码助手来写。
Codex 帮我写了一篇英文文章，主题是从真实工作流出发，判断 AI coding assistant 是否适合自己。
我不想让这篇文章看起来像硬塞链接，所以锚文本没有写成很生硬的品牌词，而是用了 free AI coding assistants
comparison。它和承接页主题一致，也能自然出现在文章里。
文章写完后，Codex 又帮我检查了几个细节。
目标 URL 要和正文里的链接一致，锚文本要和平台字段一致，正文要满足平台要求的最低字数，Special requirements 要写清楚，希望发布在
technology、software development、AI tools 或 developer tools 相关栏目里。
** 这里我觉得 AI 的价值很明显。它不只是写文章，还会帮我做提交前检查。 **
很多新手第一次买客座文章时，大方向可能已经想清楚了，最后反而容易栽在这些小字段上。
URL 填首页还是承接页，锚文本有没有和正文一致，图片位置是不是放错了，浏览器翻译插件有没有把中文残留混进正文。
Adsy 客座文章下单前的内容与要求确认
我最后让 Codex 把提交页逐项复核了一遍。
Codex 对 Adsy 客座文章下单信息做提交前复核
这次文章还加了一张配图。图是为了让文章看起来更完整，也减少发布方随便配一张不相关图的概率。
配图这件事其实也有一套小流程。
先判断是否需要配图，再生成一张和文章主题一致的图，然后上传到图床，最后把图片地址插到文章里。
我们现在自己做 AI 出海产品，也在用 HiAPI 这类聚合 API 来处理图像生成和模型调用，所以这类流程后面完全可以串进内部内容生产里。
提交前我又让 Codex 检查了一次正文。最后它通过浏览器操作把源码里的正文清理了一遍，完全没问题了，才建议我去点 Buy。
## 人负责判断，AI 负责执行和检查
人和 AI 应该怎么分工。
人负责判断目标。为什么要买这条外链，预算是多少，能接受什么风险，什么类型的网站和我们的产品相关，自己心里要有一个判断。
AI
适合做陪跑。它可以帮我读平台、解释字段、设计筛选条件、初筛候选网站、检查内容相关性、写文章、生成配图、上传图床、复核提交字段，还能控制浏览器帮我把一些重复操作走完。
在这个过程中，AI 更像一个执行力很强的同事，会把平台里那些零碎、细节、容易漏的步骤整理出来，然后一项项过。
有 AI 辅助能降低上手成本，也能减少因为不熟平台而犯的低级错误。
最后，客座文章有没有效果，不能看提交完了就结束，而是要等文章发布后继续跟踪。后面还要记录发布 URL、是否 Dofollow、是否收录、目标页在 GSC
里的 impressions、clicks、average position 有没有变化。
提交成功后，钱会先进入 Reserved，不是立刻最终完成。
任务会出现在 Adsy 的 Tasks 里，这个页面后面就是验收入口，等文章发布后，还要从这里回来看发布 URL 和任务状态。
Adsy 购买成功后在 Tasks 页面查看任务状态
SEO 里很多动作都不是做完就结束。买一篇文章只是开始，后面还要继续看数据反馈。**
### Codex 沙箱与主机权限：一次权限边界风险复盘
URL: https://codexguide.io/guides/codex-sha-xiang-yu-zhu-ji-quan-feng-xian
用 Codex、Cursor、Gemini CLI 这些 AI 编程工具的人，心里多少都揣着一个默认的安心，反正它有沙箱。
# Codex 沙箱与主机权限：一次权限边界风险复盘
用 Codex、Cursor、Gemini CLI 这些 AI 编程工具的人，心里多少都揣着一个默认的安心，反正它有沙箱。
哪怕模型抽风、哪怕它读到一段不干净的内容，顶多在项目目录里瞎折腾一下，跑不出这个圈，动不了电脑别的地方。
这两天，这个安心塌了，四个主流 AI 编程工具在同一周被集中曝出沙箱逃逸漏洞，而且它们有个吓人的共同点：攻击者几乎都没正面去砸沙箱。
AI 全程老老实实待在沙箱里，每条规则都守，它只是往工作区写了个文件，这个文件后来被沙箱外一个受信任的组件捡起来执行了，机器就这么沦陷了。
这几个里 Codex CLI 中招的那个我觉得最典型，攻击链短到离谱，让 Codex 接个新库，它读了那个库的说明文档，文档里藏了一句话，Codex
照做，你的电脑门就开了。
全程不弹一次批准框。
## 沙箱不等于安全边界
在拆漏洞之前，得先纠正一个大多数人脑子里的错误图像。
我们以为沙箱的边界是这样的： ** AI 能碰的东西 = 沙箱里面的东西 ** ，沙箱像个透明盒子，AI 在里面怎么闹都行，出不来。
但真实的边界要复杂得多，它至少有三层：
** 第一层，直接执行。 ** AI 进程自己能跑什么命令。这层大家都盯得紧。
** 第二层，工作区写入。 ** AI 能创建、修改哪些文件。这层通常也在沙箱管辖内。
** 第三层，宿主信任。 ** 沙箱外面那些被默认信任的组件，事后会拿 AI 写的文件去干什么。这一层，才是真正出事的地方。
问题就在第三层，电脑上跑着一大堆宿主侧的自动化组件，Git 集成会扫仓库、Python 插件会找解释器、VS Code 会加载任务配置、各种 hook
会在特定时机触发命令。
这些组件都在沙箱外面，权限比 AI 大得多。
沙箱里的 AI 哪怕一条规则都不破，它只要能写一个文件，而这个文件恰好会被沙箱外某个组件读取并执行，边界就穿了。
说到底，在开发者的电脑上，项目文件往往本身就是一种可执行的基础设施。
## Codex 一句 git show 就够了
具体到 Codex，问题出在它的安全命令白名单上。
Codex CLI 默认带一个白名单，上面的命令被认为无论带什么参数都不会造成伤害，所以这些命令跳过沙箱、跳过用户批准，直接以权限执行。
` git show ` 就在这个名单上——因为按理说它只是用来显示 commit 信息的，看着人畜无害。
但 ` git show ` 其实能往任意文件写任意内容。
关键在两个参数： ` --output ` 让它把输出重定向到一个文件，而不是打印到屏幕； ` --format ` 让攻击者控制写进去的具体内容。
两个一拼，就是一个往任意路径写任意内容的原语。
攻击者构造的命令长这样（核心结构）：
git show --no-patch \
--format='[diff]%nexternal = bash -c "任意命令"' \
--output=./.git/config HEAD
拆开看： ` git show ` 负责骗过白名单； ` --format='[diff]%n...' ` 拼出一段合法的 git 配置语法（ `
%n ` 是换行）； ` external = bash -c '...' ` 是要塞进去的恶意「外部 diff 工具」； `
--output=./.git/config ` 直接把这段内容写进仓库的配置文件。
这条命令跑完， ` .git/config ` 里就多了一段，让 git 在做 diff 的时候，去调用攻击者指定的那条 bash 命令当「外部
diff 工具」。
然后就等着， ** 下次你（或者任何人）在这个仓库里跑 ` git diff ` ，它也在白名单上，git
就会乖乖调用那个外部工具，攻击者的命令以你的完整权限执行， ** 沙箱全程没弹一次批准框。
## 攻击是怎么送到你面前的
可能会问：攻击者怎么让我的 Codex 去跑那条命令？
答案朴素得让人后背发凉： ** 藏在文档里。 **
场景是这样：在接一个新的第三方库，让 Codex 帮忙，Codex 会去读这个库的 README、文档、示例，而攻击者早就在文档某个不起眼的角落。
比如安装说明和 API 示例之间，塞了一句 prompt injection，诱导模型去执行那条 ` git show ` 命令。
模型读到了，决定照做，命令就跑了，因为它在白名单上，没有任何一层会拦。
这里有个对比特别说明问题。同一个 Codex，当它想跑 curl 的时候，会规规矩矩弹出批准框请你确认，因为 curl 不在白名单上，沙箱正常工作。
可当它跑那条 ` git show --output ` 的时候， ** 什么都没有发生 ** ，没有提示、没有拦截，配置文件被悄悄改写。
两条命令都有安全影响，但只有一条被管住了。
## 为什么模型会拒绝这件事根本不算数
这个漏洞在验证的时候还闹过一个插曲：第一次复现失败了，因为那一次模型拒绝执行恶意指令。但这恰恰不重要。
** 模型的拒绝是概率性的，不是确定性的。 ** 同一个 prompt
你跑十次，结果可能不一样，它可能拒绝九次，第十次就照做了。做安全分析，不能赌模型这次会不会拒绝，得假设它一旦照做会发生什么。
而在 Codex 这个案例里，模型一旦照做，没有任何后备防线接得住。整套架构默认模型会拒绝，可当它不拒绝的时候，下面是空的。
这是整件事最该记住的一点： ** 如果在用大模型处理不受信任的内容，必须为模型听信了恶意指令这种情况做设计。 **
让模型永远不犯错，是个几乎无解的问题；但让它犯错时不至于把整台电脑赔进去，是可以做到的。
一句话：命令本身无所谓安全或危险，调用方式才是。git show HEAD 无害，git show --output=.git/config HEAD
能拿下你的机器。
一个只看命令名的白名单，根本分不清这两者。
## 现在该怎么办
先给结论，别慌：这个洞官方已经修了。 它属于高危级别（漏洞编号 CVE GHSA-w5fx-fh39-j5rw），是 Codex CLI 自去年 9
月以来第二个沙箱逃逸类漏洞。安全团队 1 月 7 日把细节报给 OpenAI，OpenAI 确认后修复，并给了高危级别的赏金。
给你几条能立刻落地的动作：
** 第一，升级 Codex CLI 到 v0.95.0 或更高版本。 ** 这是最直接的，补丁就在这个版本里。用之前先 ` codex
--version ` 看一眼自己在哪个版本。
** 第二，管住你喂给 AI 的不受信任内容。 ** 让 Codex 去读一个陌生仓库的 README、文档、issue 之前，心里得有根弦，这些都是
prompt injection 的天然入口。尤其是让它自主跑、少人盯着的时候，更要留神。
第三，如果自己在做类似的 AI 编程工具，这个案例是本活教材：靠命令名做白名单是靠不住的。git、curl、tar、rsync
这类工具，都有能把自己从只读变成可写的参数。
几个可行的堵法：显式拦截 --output、–format 这些危险 flag；或者干脆把 git 移出白名单、所有 git 操作都要批准；再或者在跑
diff 时用 git -c diff.external= diff 强制禁掉外部 diff 工具，直接斩断这条触发链。
## 写在最后
这个漏洞本身已经修了，真正值得带走的是它背后那层认知的转变。
过去把 AI 编程工具的沙箱，当成一堵把 AI 关在里面、把用户护在外面的墙，但这一连串漏洞反复说明：这堵墙比我们想的要脏、要漏，因为一旦 AI
能写下将来会被别的系统读取、执行的文件，它其实从一开始就没被真正关住。
这不是要吓得不敢用 AI 写代码——这些工具带来的效率是真实的，自己天天在用，它提醒的是另一件事：AI
编程工具已经悄悄变成了电脑上一个能读外部内容、能写文件、能触发自动化的「新型端点」，对它，我们得用对待端点的谨慎去对待，而不是把「有沙箱」三个字当成免死金牌。
保持工具更新，对喂进去的内容多一份警觉，这在 AI 越来越能自己动手的时代，只会越来越重要。
> 延伸阅读：
>
> Codex GitPwned 漏洞深度拆解：https://www.pillar.security/blog/gitpwned-allowlist-
> to-rce
>
> Codex CLI 官方文档：https://developers.openai.com/codex/cli
### Codex 接入飞书：从群聊指令到本地任务执行
URL: https://codexguide.io/guides/codex-feishu-ji-cheng-shi-zhan
用 Codex 有个一直没解决的别扭，它跑在我电脑的终端里，可我人不总在电脑前。
# Codex 接入飞书：从群聊指令到本地任务执行
用 Codex 有个一直没解决的别扭，它跑在我电脑的终端里，可我人不总在电脑前。
开会、通勤、躺沙发上刷手机的时候，突然想起有个小改动想让它去跑，只能等回到工位打开终端。
ChatGPT App 倒是能给 Codex 发消息，但那套流程对我来说总隔了一层，切来切去不顺手。
平时开会沟通全在飞书里，就想过一个特别自然的念头：能不能干脆在飞书群里直接指挥它？
还真找到了办法，有个开源项目把飞书和本机 Codex 打通了，在群里 @ 一下机器人，它就在我电脑上指定的项目目录里跑起来，边跑边把过程和结果甩回群里。
相当于给 Codex 开了个飞书账号，让它变成群里那个随叫随到的同事。
这篇就把它怎么装、怎么用讲清楚。
## 它到底是个什么东西
先说清楚原理，不然容易和别的方案搞混。
这个项目叫 ** feishu-codex-bridge ** ，本质是一座桥，一头连着飞书群消息，一头连着本机的 Codex。
它自己不写代码、不跑模型，真正干活的还是你电脑上那个 Codex，桥只负责把飞书的消息转发过去，再把 Codex 的输出转成飞书卡片发回来。
它设计里有个很妙的对应关系，记住这个就理解了大半：
** 一个群 = 一个项目 = 一个固定的本地目录。 **
** 一个话题（thread）= 一个会话（session）。 **
意思是，给某个群绑定一个代码目录，之后在这个群里 @ 机器人说的话，都是让 Codex 在那个目录里干活，而群里每开一个话题，就相当于开一条独立的
Codex 会话，上下文互不干扰，还能自动接着上次的聊。
举个例子，在飞书群里发一句「帮我加个登录接口」，机器人立刻在这个群绑定的代码目录里跑起
Codex，然后能在一张卡片上实时看到它的推理、执行的命令、改了哪些文件、最后的结果，全程刷新，想中途叫停，卡片上点一下 ⏹ 就行。
## 装起来到底麻不麻烦
不麻烦，核心就两步。不过得先满足个前提：电脑上得先有 Node.js（18 以上）和装好的 Codex CLI，这两个大概率你早就有了。
** 第一步，全局装这个桥。 **
npm i -g @modelzen/feishu-codex-bridge
** 第二步，打开本机的网页控制台。 **
feishu-codex-bridge web
这条命令一跑，会在你本机起一个网页控制台，默认端口 51847，只绑定在 127.0.0.1 本地、每次启动随机生成一个 token
鉴权，外面访问不了，比较安全。
命令就能 Ctrl+C 关掉了，不影响后台继续跑。
这里有个偷懒的玩法，可以把安装这件事本身交给 Codex，把「帮我在这台电脑上装好 feishu-codex-bridge 并跑起来，检查 Node 和
codex 版本、全局安装、启动控制台、把链接发给我」这段话直接丢给 Codex，让它替你一步步装。用 AI 装接入 AI 的工具，还挺有意思的。
## 两种群，看你怎么用
机器人建好后，它会带你新建项目：选一个本地目录绑上，选后端（Codex 或者 Claude Code
都行），然后它自动建好群、把命令说明置顶、再把你拉进去。
建群的时候有两种模式，按场景挑：
** 多话题群。 ** 每次 @ 机器人开一个新话题，每个话题是一条独立会话，上下文隔离、能并行跑。适合多人协作，或者你一个人同时开几摊活，互不打架。
** 单会话群。 ** 整个群就是一条连续会话，全程不用 @，像私聊一样直接说话。适合个人单线深入某个任务，聊起来最顺。
我自己的习惯是，正经项目开多话题群，方便并行；临时捣鼓点小东西就开单会话群，图个省事不用老 @。
真正干活的时候也就几个动作：@ 机器人（或话题里免 @）描述需求，看流式卡片出结果，想停就点 ⏹。要让它自己多轮跑到完成，用 ` /goal `
设个目标，它就自主推进，跑完停或者你手动结束。发图片能读图，发文件（日志、PDF、代码）它会下载到本地打开分析。
## 最戳我的一个功能：咖啡一下
前面都是飞书指挥电脑，这个功能反过来，是电脑主动找你，官方管它叫 ** 咖啡一下 ** 。
场景是这样：在电脑前用 Codex 干活，跑到一半要离开一会儿，去接杯咖啡或者开个会。平时这时候 Codex
卡在一个需要审批的操作上，就干等着，等你回来才能继续。
开了咖啡一下之后，Codex
一旦遇到需要审批、要问你问题、或者任务跑完了，会主动把这些推到你的飞书私聊，在手机上点个确认、回答一句，它就接着往下干，整个过程电脑保持不睡，屏幕关了
CPU 照样跑，等你回到座位，终端自动交还给你。
这个设计真的解决了实际问题。以前跑长任务得守在电脑前当人肉审批器，现在能起身走开，让手机替我盯着。
## 安全这块得说清楚
把一个能在电脑上跑命令的机器人放进飞书群，安全是绕不开的话题，这个项目在这块想得比较周到，给了三档权限沙箱，每个项目单独设。
** 只读档。 ** 机器人只能读项目目录，不能写。适合放外部群、给不完全信任的人用的问答机器人。
** 读写档。 ** 能读写，但锁死在项目目录里，碰不到你电脑其他地方。适合自己的编码项目，这是最常用的一档。
** 完全访问档。 **
整台电脑都能碰。只在你完全信任、自己独占的机器上开，而且要清楚：任何能给机器人发消息的人，都能以你的身份在这台电脑上执行任意命令。
有个细节得提醒：只读和读写这两档的限制，是靠操作系统级的沙箱强制的，目前只有 macOS 和原生 Windows 能真正强制住。
如果在 Linux 或者 WSL 上选这两档，它会直接拒绝启动，绝不偷偷降级成完全访问——这个处理挺负责任的，要在 Linux
上用，得把后端跑在容器或者隔离环境里。
说白了一句话：这不是一个多租户的托管服务，是给自己和信任的小团队自用的桥，别拉不认识的人进群，别在放着敏感数据的机器上开完全访问。
## 几个日常命令
装好之后，日常基本只跟两个命令打交道：
feishu-codex-bridge start # 起后台服务，装成系统服务、开机自启、崩了自动拉起
feishu-codex-bridge web # 打开网页控制台，看日志、加机器人、启停服务
其余的动作，网页控制台和飞书私聊里基本都有按钮点，不用记一堆命令，想自检环境有没有配好，一个 ` feishu-codex-bridge doctor
` 会帮查后端、登录状态、当前机器人。
有一个坑得单独拎出来： ** 后台服务必须全局安装，别图省事用 npx。 ** 因为后台服务里硬编码了 CLI 路径，npx
那种临时缓存会被系统清掉，服务就找不着了，前台单次跑用 npx 没问题，常驻服务一定要 ` npm i -g ` 。
## 写在最后
这个最打动我的，不是什么炫技的功能，而是它把 Codex 从一个只能待在终端里的工具变成了一个能在协作场景里随时找到的角色。
以前用 Codex，得先坐到电脑前、打开终端、进到项目目录，才能开始干活，现在这套流程被压缩成飞书群里 @
一句话。人在哪不重要了，反正活是在电脑上真真切切跑完的，结果再回到眼前。
如果团队本来就重度用飞书，又天天用 Codex，这个组合值得花十分钟装一下试试。哪怕只是为了咖啡一下那个功能，能让你跑长任务时终于敢起身离开电脑，就够本了。
延伸阅读：
* feishu-codex-bridge 项目仓库：https://github.com/modelzen/feishu-codex-bridge
* Codex CLI 官方文档：https://developers.openai.com/codex/cli
### Codex 与其他编程模型比较：模型选择与实际工作流
URL: https://codexguide.io/guides/codex-yu-qita-biancheng-moxing-bijiao
两大模型同一天发布新版本，这是要直接PK的意思啊，AI圈又热闹起来了。
# Codex 与其他编程模型怎么比较：从任务类型和验证条件出发
两大模型同一天发布新版本，这是要直接PK的意思啊，AI圈又热闹起来了。
Anthropic 放出 Opus 4.6，之后 OpenAI 放出 GPT-5.3-Codex。
今天还看到了这张图，有点难绷。
这俩是我现在用得最多的主力模型，一个负责日常创作和主力编程，一个负责搜索研究和精准改 bug，现在同时升级了。
先各自一句话总结：
Claude Opus 4.6：更强规划、更长自主任务、百万 token 上下文（beta）
GPT-5.3-Codex：融合 5.2-Codex 编码能力和 5.2 推理能力，速度快 25%，token 消耗减半
## Opus 4.6：编程更严谨，上下文翻了 5 倍
官方文档：https://www.anthropic.com/news/claude-opus-4-6
### 模型能力升级
Opus 4.6 在编码上的改进方向：规划更周密，先想清楚再动手；能更长时间地执行 agent 任务；代码审查和调试能力更强，能更有效地发现自身错误。
之前 Claude 经常被吐槽太自信，一路错到底也不回头检查，这次有了改善。Cognition（Devin 团队）的反馈是 bug
捕获率明显提升，Cursor 团队也说它在代码审查上表现很好。
** Opus 系列首次支持 100 万 token 上下文窗口（beta）！！ **
之前 Opus 只有 200K，这次直接翻了 5 倍。对做 Coding
的人来说，上下文容量有多重要不用多说。唯一要注意的就是考虑一下消耗，可能计费会比较夸张。
Opus 4.6 在这方面的表现相当不错：MRCR v2 的 8-needle 1M 测试中，Opus 4.6 得分 76%，而 Sonnet 4.5 只有
18.5%。这是一个质变级的提升，意味着百万行代码库、长文档分析、多轮对话都能 hold 住，不是摆设。
输出上限也从之前的 64K 翻倍到了 128K token，一次性输出更多内容，减少分轮请求的麻烦。
### 跑分表现
再来看看跑分吧，每次新的模型出来都少不了这个环节。
Opus 4.6 在多个评测上拿到了最高分。Terminal-Bench 2.0（终端编程能力）65.4%，GDPval-
AA（真实工作任务，涵盖金融、法律等领域）Elo 1606 分，比 GPT-5.2 高 144 分，比前代 Opus 4.5 高 190 分。
BrowseComp（网络搜索能力）84.0%，远超第二名 GPT-5.2 Pro 的 77.9%。Humanity's Last
Exam（复杂多学科推理）和 ARC AGI 2（流体智力测试，68.8%）也都是最高分。
在 OSWorld（操作电脑能力）上拿了 72.7%，比 Opus 4.5 的 66.3% 提升不少，说明 Claude 越来越会操控电脑了，越来越智能
agent化了。
### 新功能和产品更新
** Context Compaction（上下文压缩）。 ** 之前 Claude Code 里的 /compact
命令已经能手动触发上下文压缩，或者在检测到接近限制时自动总结对话。
这次的改进是在 API 层面，模型自己能判断什么时候该压缩、压缩哪些内容，配合百万 token 上下文，长任务能跑更久而不会因为上下文溢出中断。
** Adaptive Thinking（自适应思考）。 ** 以前 extended thinking
只能开或关，没有中间状态。简单问题开了深度思考就是浪费。现在 Claude 能自己判断问题的复杂度，简单问题快速回答，复杂问题多想一会儿。
配合新增的 Effort 控制（low / medium / high / max 四档，默认 high），开发者可以在速度、成本、质量之间灵活调整。
** Agent Teams（多 Agent 团队协作）。 ** 这是 Claude Code 的一个重要更新，目前是 research
preview。以前用 Claude Code 是一个 agent 在干活，现在可以启动多个 agent
并行工作，一个审代码、一个写测试、一个改文档，最后汇总结果。
和之前的 subagent 不同，subagent 只能向主 agent 报告结果，Agent Teams
的成员之间可以直接沟通、互相质疑、共享发现，不需要通过负责人中转。你可以用 Shift+Up/Down 或 tmux 直接接管任何一个 subagent。
** Claude in Excel 增强 + Claude in PowerPoint 首发。 ** Excel
插件现在支持数据透视表、图表修改、条件格式、排序筛选、数据验证，不只是写公式了。
PowerPoint 插件进入 research preview，能读懂你的模板、字体、配色，生成的 PPT 不用大改。这两个插件对 Max、Team 和
Enterprise 用户开放。
价格保持不变， 25 per million tokens（输入/输出）。超过 200K token 的上下文有额外定价， 37.50 per
million tokens。
## GPT-5.3-Codex：更快更省，模型开始造模型
OpenAI 官方：https://openai.com/index/introducing-gpt-5-3-codex
### 模型能力升级
GPT-5.3-Codex 融合了 GPT-5.2-Codex 的前沿编码性能和 GPT-5.2 的推理及专业知识能力，同时速度提升 25%。
Sam Altman 在推文里补充了一个更直观的数据：完成相同任务所需的 token 不到 5.2-Codex 的一半。
速度更快、消耗更少，这对跑长任务的开发者来说是实打实的省钱。
这次最值得关注的一点是，OpenAI 在博客里说 GPT-5.3-Codex 是他们第一个" ** 在创造自己的过程中发挥重要作用的模型 ** "。
Codex 团队用早期版本来 debug 自己的训练过程、管理部署、诊断测试结果。
工程团队用它定位 context 渲染 bug 和缓存命中率问题；
数据团队用它建数据管道、分析结果，三分钟内就能对上千个数据点生成摘要。
** 模型造模型。 ** 挺有意思的。
** Mid-task steerability（任务中途可调整）。 ** 这是 5.3 主打的差异化功能。
以前 Codex agent 跑起来只能等结果，现在可以中途提问、调整方向、讨论方案，不会丢失上下文。
Codex 还会频繁汇报进展，让你随时了解关键决策和进度，官方说体验像和同事协作一样。在 Settings > General > Follow-up
behavior 里开启。
前端生成能力也有明显提升。官方对比了 GPT-5.3-Codex 和 GPT-5.2-Codex 生成的落地页，5.3
会自动把年付方案显示为折算后的月价让折扣更直观，还会做自动轮播的多条用户评价，整体更接近生产级别的页面。
OpenAI 还测试了让 5.3-Codex 用 "develop web game" Skill 配合通用跟进提示（修复
bug、改进游戏），在几天时间里自主迭代了数百万 token，做出了一个有 8 张地图和道具系统的赛车游戏，以及一个有氧气和压力管理系统的潜水游戏。
### 跑分表现
Terminal-Bench 2.0 从 64%（5.2-Codex）跳到 77.3%，提升明显。
OSWorld-Verified 从 38.2% 跳到 64.7%，接近翻倍，computer use 能力大幅增强。
SWE-Bench Pro 是 56.8%，比 5.2 的 56.4% 提升不大，但这个 benchmark 覆盖
Python、Go、JavaScript、TypeScript 四种语言，比 SWE-bench Verified 更难也更抗数据污染。
网络安全 CTF 挑战从 67.4% 提升到 77.6%，SWE-Lancer IC Diamond 从 76% 提升到 81.4%。
### 新功能和产品更新
** 网络安全能力首次被标记为 High Capability。 **
这是 OpenAI Preparedness Framework 下第一个在网络安全领域被标记为高能力的模型，也是第一个专门训练来发现软件漏洞的模型。
OpenAI 同时投了 $10M API credits 用于网络防御研究，推出了 Trusted Access for Cyber
试点项目，还在扩展安全研究 agent Aardvark 的私测范围。
目前 GPT-5.3-Codex 通过 ChatGPT 付费订阅使用，API 还没开放。桌面 App 暂时只支持 Mac Apple
Silicon（M1+）。
## 两家怎么比
产品形态上，
OpenAI 把 Codex 做成了桌面 App、CLI、IDE 插件、Web 端全线打通的产品。不过这点 Claude 也一样，claude.ai Web
端、桌面 App、Claude Code CLI、各 IDE 插件都有，两家在产品覆盖面上基本持平。
然后就是说实话跑分这个东西参考一下就好。
一方面两家的评测基准有很多细节差异，OSWorld、SWE-bench、GDPval 用的都是不同版本或不同评测方法，表面上的数字高低说明不了太多问题。
另一方面，很多模型跑分很高但用起来就是不顺手，反过来有些模型跑分一般但在某些场景下特别好用。
关于产品路线的差异。
两家都在往 agent 方向走，但产品化思路不太一样。
Claude 这边是嵌入式路线，直接做了 Excel 和 PowerPoint 插件，嵌入你现有的工作流。Agent Teams 让多个 agent
并行协作，Cowork 让 Claude 在后台自主多任务。
产品矩阵更全，百万 token 上下文也是 GPT-5.3 的 128K 的 8 倍，对大项目的体验提升是质变级的。
OpenAI 这边是平台化路线，把 Codex 做成了一站式产品（App + CLI + IDE + Web），Skills 系统让 Codex
能对齐团队规范，Automations 能在后台自动处理 issue 分类、告警监控这些日常杂活。Mid-task steerability
让长任务的交互体验更好。
如果你想开箱即用地增强办公效率，Claude 的插件更方便。如果你习惯在一个产品里一站式搞定开发工作，Codex 的体验更完整。
我自己的工作流大概率不会大变：Claude Code 打草稿做主力开发，Codex
接手后续精准调试和长任务。两边同时升级，都去试试吧，找到自己的最佳使用方式。
现在算力已经变成了生产力，Opus 4.6 百万上下文一开，跑个大项目 token 消耗很可观。如果你是重度用户，比如用 OpenClaw 跑自动化、用
Claude Code 做大项目开发，API 费用会是一笔不小的开支。
### Codex 常用功能清单：把容易漏掉的能力补齐
URL: https://codexguide.io/guides/codex-changyong-gongneng-qingdan
很多人第一次用 Codex，会把所有事情都扔进同一个任务。
# Codex 常用功能清单：把容易漏掉的能力补齐
很多人第一次用 Codex，会把所有事情都扔进同一个任务。
先讨论方案，接着改文件，测试报错以后继续往里贴，最后还让它留在原任务里审查自己的修改。刚开始没什么感觉，任务一长，讨论过但放弃的方案、终端日志和最后确认的要求就混到了一起。
软件一直在工作，使用体验却越来越乱。
我现在看一套 Codex 配置是否顺手，主要看三个地方。复杂任务有没有足够的推理能力，讨论和执行有没有分开，任务结束后能不能把进度交给下一次对话。
下面这 8 项，我建议按这个顺序设置。它们有的是开关，有的是入口，还有两项只是很简单的文件习惯。全部用起来以后，Codex 才更像一个能长期合作的工作台。
## 01 先把 Luna 的最高推理强度放出来
Codex 能选 Luna，不等于已经用上了 Luna 的最高能力。推理强度需要在模型功能里手动开启。
进入设置，找到模型功能，在可用推理强度里勾选“最高”。开启后，模型选择器里才会出现对应档位。
普通任务用中档或高档就够了。跨文件重构、复杂排查、架构调整和回归风险较高的修改，我才会切到 Luna
Max。它会把更多精力放在代码结构、修改范围和验证方法上。
Sol 和 Luna 也可以分工。Sol 负责规划、架构判断和关键选择，方案明确以后，再把边界清楚的执行工作交给 Luna Max。
可以直接这样发给你的AI。
先用 Sol 分析范围、风险和执行顺序。方案确定以后，把边界清楚的具体任务交给 Luna Max。
## 02 让 Quick Chat 接住临时冒出来的问题
长任务总有等待的空档。日志还在滚动，新的疑点已经冒出来了。可能是一个接口，也可能是刚想起的遗漏条件。
这些问题直接塞进主任务，很容易把正在执行的要求打断。我会把它们先放进 Quick Chat。
入口就在左上角“新对话”旁边的加号里。
从新对话旁边打开快速聊天
Quick Chat 里讨论清楚以后，点击右上角“添加到聊天”，结论就能回到当前任务。
把快速聊天里的结论添加回当前任务
这个顺序很好用。主任务继续执行，临时问题单独讨论，最后只把确认后的要求送回去。
## 03 把方案讨论移到 Side Chat
Quick Chat 适合临时问题，Side Chat 更适合围绕当前任务继续深挖。
比如一项重构已经开始执行，你想重新比较两个架构方向，又不希望整段讨论进入主任务。这时可以从当前内容旁边开一个 Side Chat，先把分歧聊清楚。
最直接的入口是在输入框发送 ` /side ` 。
在输入框使用 side 命令
看到某段内容需要单独展开时，也可以选中文字，点击“在侧边聊天中提问”。
选中文字后在侧边聊天中提问
任务顶部的更多菜单里还有“打开侧边聊天”。
从任务菜单打开侧边聊天
我会让 Side Chat 负责方案比较、风险讨论和执行指令整理。方向确定后，只把最终版本发回主任务。这样主任务看到的是决定，Side Chat
留下的是思考过程。
## 04 修改完成以后，单独开一次 Review
同一个任务刚写完代码，通常会沿着自己的实现思路继续检查。前面忽略掉的边界，到了最后仍有可能被忽略。
所以我会把 Review 单独拿出来。修改完成后，打开 Review 或 Changes，让它只看当前变更、风险和缺失测试，先别急着修。
检查当前未提交修改。只报告可以被代码或测试证明的问题，标明文件和位置。先不要修改任何内容。
先审查，再决定修什么。这样能保留问题出现时的原始证据，也不会让新一轮修改把旧问题盖住。
## 05 配一个只接具体任务的 Subagent
任务开始变大以后，我会再加一个 ` luna_worker ` 。
它不参与大方向讨论，只接范围明确的执行工作。搜索过程、测试输出和中间尝试留在它自己的上下文里，主任务只接收结果、证据和改动文件。
个人 Agent 放在 ` ~/.codex/agents/ ` ，项目专用 Agent 放在项目里的 ` .codex/agents/ ` 。创建
` luna-worker.toml ` 后，可以写成下面这样。
name = "luna_worker"
description = "处理父级委托的具体且边界清楚的任务"
model = "gpt-5.6-luna"
model_reasoning_effort = "max"
developer_instructions = """
只处理父级委托的具体任务。
开始前明确范围、限制和完成标准。
不得扩大任务范围，也不要改动相邻文件。
默认先做只读调查。
只有委托明确授权修改时才能编辑文件。
保留用户已有的无关改动和配置。
根据风险大小验证结果。
完成后返回结果、验证证据、改动文件和剩余限制。
未经明确授权，不得提交、推送、发布、发送消息或执行破坏性操作。
"""
不想手动建文件，也可以把这段配置要求直接交给 Codex，让它按指定路径创建。
Subagent 最适合边界清楚的工作，比如只查一个报错、只修改指定文件、只补一组测试。方向还没定，或者任务范围仍在变化时，先留在主任务里讨论。
## 06 用 @ 把旧任务里的结论找回来
多个项目一起推进时，重复解释背景很浪费精力。Codex 的 ` @ ` 引用可以直接搜索其他任务，把相关对话带进当前任务。
输入 ` @ ` 和关键词，找到之前讨论过的任务，再选择需要引用的内容。另一种方法是复制任务 ID，把它发给新的任务读取。
我通常会多加一句限制。
只读取这个任务里已经确认的方案和限制。当前状态仍以现场文件、Git 和运行结果为准。
旧对话适合提供来龙去脉，当前文件和运行结果负责说明现在做到哪里。两者分开以后，引用旧任务会稳很多。
## 07 长任务结束前写一份 HANDOFF
` @ ` 引用适合找旧讨论， ` HANDOFF.md ` 更适合把一个进行中的任务交给下一次会话。
长任务准备结束时，我会让 Codex 把当前状态写进项目里的 ` HANDOFF.md ` 。
这个任务准备结束了，请把交接内容写入 HANDOFF.md。
写清当前目标、已经完成的内容、仍未解决的问题、下一步动作和已经踩过的坑。
分开记录本地完成、已经合并、已经部署和线上验证。
这份文件要让一个没有聊天上下文的新任务直接接手。
下一次打开任务，先让它读文件，再检查 Git 和现场状态。
先读 HANDOFF.md，再检查当前文件和 Git 状态，确认从哪里继续。
这份文件不用写成长报告。能够回答做到哪里、下一步做什么、哪些路别再走，已经够用。
## 08 把被纠正过的问题留下来
任务停在哪里，看 ` HANDOFF.md ` 。它为什么会走偏，看这一轮留下的纠正记录。
一次协作里，我可能纠正过范围、状态判断和验证方式。任务结束前，让 Codex 把这些纠正重新过一遍，只保留下次还可能发生的问题。
回顾这次协作中我纠正过的地方。
列出本次纠正、错误原因和下次开局指令。
只保留可能再次发生的问题，不要总结普通执行过程。
输出保留三列就够了。
本次纠正 | 错误原因 | 下次开局指令
---|---|---
把本地完成写成已经上线 | 状态判断过快 | 分开记录本地、合并、部署和线上验证
审查时顺手修改文件 | 忽略任务边界 | 本轮只审查，不进行修复
修改扩大到相邻模块 | 范围没有锁定 | 只触及明确列出的文件和功能
错题本要尽量保持短。同类错误合并到旧条目，已经进入固定审查要求的规则就从这里移走。留下来的每一条，都应该能在下次开局时直接使用。
## 最后
同一个模型，工作方式不同，结果会差很远。所有事情挤在一个任务里，Codex 会越做越乱。把推理、讨论、执行、审查和交接分开以后，它才会稳定下来。
如果只准备先改两处，我建议从 Luna Max 和 Side Chat 开始。一个负责把复杂任务想清楚，一个负责让主任务保持干净，变化最容易感受到。
### Codex 插件入口：安装、调用与权限边界
URL: https://codexguide.io/guides/codex-chajian-rukou-yu-gongzuoliu
这两天 OpenAI 发了三个教育插件，K–12 老师、大学老师、大学生各一个。
# Codex 插件入口：安装、调用与权限边界
这两天 OpenAI 发了三个教育插件，K–12 老师、大学老师、大学生各一个。
标题挂着教育两个字，跟天天写代码的人看着没半点关系，一开始我也想直接划过去。
但翻完公告改主意了，有两件事跟我们有关。
一是这三个插件不只在 ChatGPT Work 里，Codex 里也有了插件入口，那可是我们天天开着的东西。
二是公告中段藏了个数字，比插件本身扎人得多，OpenAI 说，就算是已经用得挺溜的年轻人，摸到的能力也比重度用户少 90% 到 99%。
OpenAI 把怎么用好 AI 这件事，从各自写 prompt，变成了装一个现成的包。
## 三个插件，各管一段活
先把三个插件是干嘛的说清楚，这部分官方讲得很具体。
K–12 教师插件，给中小学老师备课用。接进老师手头已有的材料和工具，生成分层的教学资源、做互动可视化、把学情整理成能落地的洞察。
它还接了个叫 Learning Commons 的公益组织的数据，让老师能按当地的学业标准来生成材料。但有一条写得很明白：教学决策、打分、以及 agent
具体干了什么，控制权始终在老师手里。
大学教师插件，管课程设计和教学规划。改教学大纲、搭互动网站或多媒体测评、给不同基础的学生改材料、把内容打包进
LMS。连上日历、文档这些批准过的工具后，老师在教学、科研、日常事务之间切换时，不用每次都重新交代一遍背景。
大学生插件，帮本科生把正在学的东西变成更个性化的学习过程。带引导的辅导、针对难点反复练、从自己选的资料里生成学习指南、测验、闪卡和可视化讲解，OpenAI
说这个是照着学习科学设计的，目标是让人真正学懂，而不是抄近道。
交付渠道是 ChatGPT Edu 和 ChatGPT for Teachers 的机构部署，个人账号暂时开不了。
## 把插件拆开，其实就是个打包好的 skill 包
官方给插件下的定义很实在：一个插件，等于 apps + 角色专属的 skills + instructions + 常用
workflows，全都围着用户自己选的材料转。
目的是让人不用自己憋复杂的 prompt，装上就能直接开工。
这几个词你要是眼熟，那就对了。
skills、instructions、workflows，这套东西开发者社区已经玩了很久。
我们聊过 AGENTS.md，聊过给 Codex 写专属 Skill，聊过怎么把一整套开发流程打包成可复用的 skill。
区别只是，以前这是开发者自己的手艺活，你得会写 SKILL.md，得知道放哪个目录，还得自己维护。
OpenAI 这次把它做成了正式的产品形态，而且第一批发给了完全不写代码的老师和学生。
对写代码的人来说，真正值得抄的不是这三个插件，是它的打包思路，按角色打包，不是按功能打包。
手里那堆 skill，大概率是按功能分的，一个查日志，一个改 SQL，一个写测试。
OpenAI 的分法是你是谁，同一个角色要干的所有活，连同他的材料、权限、常用流程，打成一个包，这个分法在团队里特别好使。
新人进来装一个后端包，项目规范、常用命令、能碰哪些库全在里面，不用他先修一门怎么写 prompt 的课。
## 那个 90% 到 99%，才是这篇公告的硬货
三个插件的功能说完了，但公告中段那个数字，比插件本身更值得琢磨。
OpenAI 说，18 到 24 岁的人里，每周有超过 2 亿在用 ChatGPT。但就算是这里面用得挺溜的，摸到的能力也比重度用户少 90% 到 99%。
它给这现象起了个名，叫 capability overhang，能力过剩。说白了就是车买了，油门只踩到 1%。
为什么要在一篇讲教育插件的公告里提这个？因为这三个插件，本质就是 OpenAI 给出的解法。
学生和老师不会写 prompt，摸不到模型的真本事，那就别让他们从零学。把「一个角色该怎么用好 AI」这件事，提前打包成一个插件塞给他们。装上就是 90
分的用法，不用自己从 1% 慢慢爬。
Codex 你天天开着，真正用到的是它哪几成？大概率就是「帮我改这个函数」「跑一下测试」「解释这段代码」。至于让它自己拆任务、并行跑子
agent、串起一整条工作循环，你认真用过几回？
看到这数字，第一反应不该是同情学生，是照镜子。
这三个插件真正给我们的启发，不是它们能干嘛，是它们证明了一件事：把「用好 AI」这件事产品化、打包化，是可行的，而且有人已经在做了。
## 这功能到底怎么用到自己身上
三个插件本身，暂时轮不到我们，得有 ChatGPT Edu 或 ChatGPT for Teachers 的机构部署才开得了，但它的做法可以直接抄。
** 天天用 Codex 的： ** 先去 Codex
里看一眼那个新的插件入口。这回进来的是教育包，但入口这个形态一旦定下来，后面会往里塞什么不难猜，趁现在，把自己那几个高频 prompt 攒一攒，你最常让
Codex 干的三五件事，就是你未来那个插件的雏形。
** 给团队搭 AI 工作流的： ** 这次最该抄的是它的打包思路，按角色打，不是按功能打。你手里那堆 skill 大概率是按功能分的，一个查日志、一个改
SQL、一个写测试。OpenAI 的分法是按「你是谁」，一个后端工程师要用的所有东西，apps、他专属的 skills、instructions、常用
workflows，连同他能碰的材料和权限，打成一个包。新人进来装一个后端包就能开工，不用先修一门怎么写 prompt
的课。权限交给管理员统一管，别撒给个人，这比你现在按功能散着放好维护太多。
** 做教育或 B 端 AI 产品的： ** 盯着「机构控权限」这一条看。OpenAI 把开关放在学校手里，不放在师生手里，教学决策、打分、agent
干的事，责任也全划给机构。这套边界看着冷，但合规场景下的 AI 产品，目前大概只有这一种形状走得通。
## 写在最后
虽然挂着教育两个字，但它真正的信号是，OpenAI 把怎么用好 AI 这件事，从各自写 prompt 的手艺活，变成了一个能装、能发、能统一管的产品形态。
第一批发给了完全不写代码的老师和学生，恰恰说明这套打包思路已经成熟到能给小白用了，轮到开发者手里，只会更顺。
至于那三个插件本身，等机构版铺开再说，但那个 capability overhang，值得现在就记一下，不是记 OpenAI
的数据，是记它逼出来的那个问题：你手里这台已经很强的工具，到底用到了几成。
想清楚这个，你比大多数人都早一步。
> 延伸阅读：
>
> OpenAI 官方公告：https://openai.com/index/learn-teach-chatgpt-work-codex/
>
> ChatGPT Edu 介绍：https://openai.com/business/solutions/education/
>
> ChatGPT for Teachers：https://chatgpt.com/plans/k12-teachers/