CodeX 桌面端
应用完全指南

版权与说明

版权声明

本文由站长基于个人实践、公开资料和当时可用的 Codex 桌面端功能整理而成。网页公开版用于学习、交流和个人参考，不代表 OpenAI 或其他第三方机构的官方立场。

使用与引用

如果引用本文内容，请注明来源为「AI学习站 / learn.ai-news2026.autos」及原文链接。未经许可，请勿将本文整体搬运、二次售卖或包装为商业课程。

商标说明

Codex、OpenAI、ChatGPT、GitHub、Google Drive、Google Docs、Google Sheets、macOS、Windows 等名称归各自权利方所有。本文中出现这些名称，仅用于说明和教学目的，不代表作者与相关公司之间存在授权、代言或合作关系。

内容准确性

本文主要依据 2026-06-10 前后的版本体验和公开资料整理。Codex 桌面端、模型、账号权限、客户端界面和相关产品政策都可能持续变化，实际操作请以官方说明和应用内显示为准。

联系方式

如有勘误、建议或合作需求，可通过邮箱联系：121280003@qq.com。

前言

过去很长一段时间里，很多人使用 AI 编程工具的方式都很相似：打开聊天窗口，输入一句需求，等待一段代码，然后复制、粘贴、修改。这个流程当然也能产生价值，但它很难真正成为团队工作流的一部分。

Codex 桌面端不同的地方，不只是“它更会写代码”，而是它把真正的软件开发环境拆开摆在你面前：项目目录、线程、终端、diff、审查区、工作树、权限、自动化，以及一整套围绕真实仓库展开的协作节奏。

这意味着，当你使用 Codex 桌面端时，你不再只是“向 AI 提问”，而是在经营一条完整的任务链路：

• 你决定目标
• 你提供上下文
• 你设定边界
• Codex 负责理解、执行和返回结果
• 你通过审查、测试和提交动作决定哪些结果值得留下

本书的重点不是把所有按钮讲一遍，而是把桌面端真正讲成一套能落地的协作方法。

本书解决的核心问题

本书主要回答四类问题：

1. Codex 桌面端到底适合做什么，不适合做什么
2. 第一次安装后，怎样最快建立正确用法
3. 怎样把“规划、编写、审查、运行、发布”串成闭环
4. 怎样减少常见误用和返工

版本说明

本书的写法

你会发现这本书不是按照“菜单 A 做什么、菜单 B 做什么”的顺序来写，而是按下面这条主线组织：

• 先理解工作台是什么
• 再理解线程、项目、模式这些概念
• 然后进入完整工作流
• 最后用模板、清单、排错把它稳定下来

阅读说明

这本书不是单纯介绍按钮的文章，而是一本围绕真实项目协作来写的桌面端使用书。

建议阅读顺序

1. 先看安装与注册登录
2. 再看3 分钟快速上手
3. 然后看界面结构 和核心概念
4. 接着看完整工作流
5. 最后把提示词模板与清单、常见问题与翻车点 当作日后速查

这本书适合谁

• 经常处理真实仓库，而不是只写零散代码片段的人
• 需要同时看对话、代码改动和终端结果的人
• 想把规划、实现、审查、发布都放在一个界面里的人

这本书不强求你一次读完

如果你更偏实践，完全可以：

1. 先读安装与注册登录
2. 再读3 分钟快速上手
3. 做一次小任务
4. 再回来读核心概念
5. 最后用提示词模板与清单 做日常速查

建议配套动作

阅读过程中，建议你同步准备这几样东西：

• 一个可以放心练手的小项目
• 一个已经初始化 Git 的目录
• 一份你愿意重复使用的提示词模板
• 一份自己的“发布前检查清单”

命令与代码阅读约定

为了保证全书里的命令和代码都尽量可执行，本书统一采用下面三条约定：

1. 先分清“在哪里输入”

• 以 /plan、$skill-installer、@plugin-creator 这类形式出现的内容，默认是在 Codex 线程输入框里输入
• 以 codex ...、git ...、npm ...、python ... 这类形式出现的内容，默认是在系统终端或 Codex 内置终端执行

2. 先分清“通用命令”和“项目命令”

• codex --help、codex plugin marketplace list、git status 这类命令属于通用命令
• npm test、pnpm build、pytest 这类命令是否能运行，取决于你当前项目是否真的定义了这些脚本或测试入口

所以本书凡是涉及项目启动、测试、构建，都会优先建议你先让 Codex 识别当前仓库的真实命令，再执行。

3. 平台差异默认按 macOS / Linux 写法展示

本书中的 shell 示例优先采用 macOS / Linux 常见写法，因为 Codex 桌面端在这类环境中的命令表达更统一。

如果你在 Windows 上使用：

• 优先在 Codex 内置终端中执行并观察实际环境
• 必要时把路径、复制命令和环境变量写法改成 PowerShell 版本

学习路径与使用建议

三种阅读方式

flowchart TD
    A["快速体验"] --> B["安装与注册登录"]
    B --> C["3 分钟快速上手"]
    C --> D["界面与概念"]
    D --> E["完整工作流"]
    E --> F["提示词模板与清单"]

    I["系统入门"] --> G["前言"]
    G --> H["按目录顺序完整阅读"]

    J["问题查找"] --> K["核心概念"]
    K --> L["完整工作流"]
    L --> M["常见问题与翻车点"]

这三种方式没有高下之分，关键是你当前最需要解决的问题是什么：

• 如果你最缺的是“先用起来”，就走快速体验
• 如果你最缺的是“完整心智模型”，就走系统入门
• 如果你最缺的是“遇到问题时知道回哪一章查”，就走问题查找

方式一：先跑通，再回头理解

适合下面这类读者：

• 刚安装好应用
• 希望先成功完成一次真实任务
• 不想一开始就读太多概念

建议顺序：

1. 安装与注册登录
2. 3 分钟快速上手
3. 界面结构
4. 完整工作流

方式二：系统入门

适合下面这类读者：

• 第一次接触 Codex 桌面端
• 希望建立比较完整的心智模型
• 后续要在真实项目中长期使用

建议从前言开始，按目录顺序完整阅读。

方式三：按问题查找

适合下面这类读者：

• 已经开始使用，但总觉得结果不稳定
• 常遇到“为什么它改乱了”“为什么审查区没东西”“为什么该先 /plan”这类问题

建议重点阅读：

• 核心概念
• 完整工作流
• 常见问题与翻车点

学习节奏建议

最稳的学习方式不是一次读完所有内容，而是“读一章，做一件小事，再回来对照”。

推荐节奏：

1. 读快速上手
2. 在一个小项目里完成一次真实改动
3. 回来看核心概念与工作流
4. 再把提示词模板和检查清单用起来

如果你已经开始做真实任务，推荐再加一步：

5. 用插件、技能与自动化 判断这类任务值不值得沉淀成技能或自动化

使用建议

先在低风险项目里练习

不要一上来把 Codex 扔进你最复杂、最关键、最不熟悉的仓库。更推荐先选：

• demo 项目
• 个人练手项目
• 风险较低的小型内部工具

不要把它当作神灯

更好的心态是把它当成“执行力很强、但仍需要你指导和审核的同事”。

让每次任务都有边界

如果一个线程里同时混入“修 Bug、加功能、顺手重构、补测试、写文档”，它的结果大概率会越来越乱。

安装与注册登录

支持平台

截至本书整理时，Codex 桌面端主要面向：

• macOS
• Windows

如果你主要使用 Linux，更适合先从 CLI 或 IDE 插件开始；如果官方已经开放 Linux 桌面端，请以官方下载安装页为准。

系统要求

在安装之前，请确认你的设备满足以下最低要求：

两种登录方式

ChatGPT 登录

适合：

• 想优先获得更完整桌面端体验的用户
• 希望少碰底层配置的新手
• 需要依赖工作区能力的使用场景

API Key 登录

适合：

• 更偏本地和程序化工作流的用户
• 明确知道自己只需要 API 范围能力的用户

对第一次上手的人来说，推荐优先使用 ChatGPT 登录。

安装前检查

建议至少确认：

• 当前系统版本正常
• 官方登录流程可以正常打开
• 本机已有一个可以练手的项目目录
• 如果准备体验审查区（Review），最好这个目录已经初始化 Git

安装步骤

macOS

1. 访问 Codex 桌面端官方下载页面
2. 下载 macOS 安装包（.dmg 文件）
3. 双击打开 .dmg 文件，将 Codex 拖入 Applications 文件夹
4. 首次打开时，系统可能要求你确认"来自未识别开发者"——前往系统偏好设置 → 安全性与隐私 → 点击"仍要打开"

Windows

1. 访问 Codex 桌面端官方下载页面
2. 优先通过 Microsoft Store 安装 Codex
3. 如果你更习惯命令行，可在 PowerShell 中使用官方文档给出的 winget install Codex -s msstore
4. 安装完成后打开 Codex，按提示登录

安装成功标志

打开 Codex 桌面端后，你应该能看到：

• 登录界面（ChatGPT 登录或 API Key 登录两个选项）
• 左侧边栏（此时可能为空，尚未创建项目）
• 如果以上都能正常显示，说明安装成功

第一次登录后的建议

• 不要把 ~/.codex/auth.json 这类本地凭证文件提交到仓库；如果你的系统使用系统钥匙串而不是文件缓存，也同样要把这些凭证视为敏感信息
• 不要把 API Key 写进公开文档或聊天窗口
• 如果是公司设备，优先遵循组织的认证和权限要求

新手常见误区

误区一：先不管项目环境，装上就用

真正会影响体验的，往往不是安装动作本身，而是你打开的项目是否能在本机正常运行。

误区二：一上来就给最大权限

更稳的方式是：先用默认权限跑通一个小闭环，再逐步放宽。

3 分钟快速上手

如果你现在的目标不是“把所有概念都看懂”，而是“先成功用起来一次”，那就按下面这条最短路径走。

1. 安装 Codex 桌面端并登录，优先使用 ChatGPT 账号登录。
2. 选择一个真实项目目录，最好已经能在本机运行，并且已经初始化 Git。
3. 新建线程，不要一上来做大任务，先给它一个范围清晰的小任务。
4. 先让它读代码，不要立即改代码。
5. 如果任务稍微复杂一点，先输入 /plan。
6. 开始执行后，先看审查区（Review）面板，再看回复文字。
7. 用内置终端跑“当前项目真实存在”的测试或构建命令，确认通过后再提交。

第一条提示词

下面这段内容要输入到 Codex 线程输入框里，不是在系统终端里执行：

请先阅读这个项目，不要修改代码。
告诉我：
1. 这个项目是做什么的
2. 本地启动命令是什么
3. 测试命令是什么
4. 最值得先看的 5 个文件是什么
5. 如果我要先做一个小改动，你建议从哪里开始

这里的关键不是让它直接假设 npm test 或 pytest 一定存在，而是先让它从当前仓库文件中识别真实命令。

第一次最适合让它做的，不是复杂功能，而是下面三类任务：

• 改一个静态文案、标题或按钮文字
• 修一个已经能稳定复现的小 Bug
• 给现有功能补一条测试或补一段说明文档

为什么这三类任务最适合入门

它们共同具备四个特点：

• 改动范围小
• 容易验证
• 很少需要复杂架构判断
• 能完整体验一次“改动 -> 审查 -> 验证 -> 提交”的闭环

第一次操作时的注意事项

先让它读，不要急着让它写

如果一上来就直接要求大改动，你很难判断它到底是否真的理解了项目。

优先看审查区，不要只看回复

很多新手的误区是：只要 Codex 说“已经完成”，就默认任务结束。更稳的做法是先看真实 diff。

不要一次做太大

第一次的目标不是“让它做出最复杂的功能”，而是“让你建立一次稳定的协作体验”。

课后建议

做完这一章之后，建议你立刻进入界面结构，把工作区的几块关键区域认清楚。

界面结构

很多人第一次打开 Codex，会把它当成“会写代码的聊天软件”。其实它更像一个项目工作台。

你最需要先认识的四块

• 侧边栏：切项目、切线程、进辅助功能
• 当前线程区：承载任务对话、计划、总结和上下文
• 审查区 / Diff：看真实代码改动、加批注、收敛范围
• 内置终端：跑测试、看报错、继续修复

为什么界面理解会直接影响结果

如果你只盯着线程区，你会自然把 Codex 用成聊天工具；但当你同时使用：

• 线程区去描述任务
• 审查区去审查改动
• 内置终端去验证结果

你才真正开始使用桌面端的完整能力。

侧边栏的使用建议

项目层

一个项目最好对应一个相对独立的工作目录，这样上下文更干净。

线程层

一个线程最好只做一件事。线程目标越单一，结果通常越稳定。

当前线程区的使用建议

• 复杂任务先 /plan
• 后续追问尽量围绕同一目标继续推进
• 要求它说明“改了哪些文件、如何验证、风险是什么”

审查区与内置终端的分工

• 审查区负责“看是否该留下”
• 内置终端负责“看是否真的能跑”

这两个区域一起构成了桌面端最重要的验证闭环。

核心概念

建议读法：

• 第一次读，先抓“项目、线程、模式、审查区”四个词分别控制什么
• 当你感觉任务总是跑偏时，再回来看“边界、任务线、执行位置”这三个层面

项目（Project）

项目（Project）是 Codex 当前工作的目录边界。你打开哪个目录，它就主要在那个目录内看文件、改文件、跑命令。

为什么项目边界很重要

很多看起来像“模型不稳定”的问题，实际是项目边界不合适：

• 打开了错误目录
• 项目过大，导致上下文分散
• 多个互不相关应用放在同一个范围里

更稳的做法是：一个项目尽量只覆盖一块相对聚焦的代码范围。

线程（Thread）

线程（Thread）是一条持续推进的任务上下文。一个线程最好只对应一个明确目标。

推荐线程命名思路

虽然你不一定要手动命名，但心里最好始终把它当成某一类明确任务：

• 修复登录跳转问题
• 给用户列表增加邮箱筛选
• 处理某一轮 review comments

如果线程目标说不清，任务边界通常也很难稳定。

模式（Mode）

• Local：直接在当前项目目录工作
• Worktree：基于 Git worktree 创建隔离副本
• Cloud：在远程环境中执行

什么时候选本地模式（Local）

适合：

• 小改动
• 快速验证
• 当前目录本来就应该被直接修改

什么时候选工作树模式（Worktree）

适合：

• 并行多个任务
• 试验性改动
• 不想污染当前目录

什么时候再去理解云端模式（Cloud）

如果你还是第一次上手，本书更建议先把 Local 和 Worktree 用顺，再去理解 Cloud。

审查区（Review）

审查区（Review）是把“写代码”和“审代码”连起来的关键。

为什么审查区不能省

因为 Codex 说“已经改好”和“这次改动真的值得提交”是两件事。真正要看的，是：

• 它改了哪些文件
• 有没有改到无关位置
• 有没有把临时修法写成长期问题
• 有没有遗漏测试或验证步骤

完整工作流

建议读法：

• 第一次读，先看"推荐节奏"和"运行、审查、发布"三节
• 真正开始做正式任务时，再把整章按顺序对照一遍

推荐节奏

1. 明确目标
2. 给上下文
3. 限制范围
4. 先做计划
5. 再执行改动
6. 查看审查区（Review）
7. 运行测试或构建
8. 处理批注
9. 再提交和发布

这一顺序的意义不在于形式，而在于让任务始终处在"可解释、可检查、可回退"的状态。

规划

复杂任务、模糊需求和跨模块改动，都建议先 /plan。

推荐规划提示

可以要求它先回答下面几类问题：

• 相关代码在哪里
• 当前实现方式是什么
• 最小改动方案是什么
• 风险点和依赖是什么
• 该怎么验证

如果这一步说不清，后面的执行通常也很难稳定。

建立

新项目适合让 Codex 初始化结构；旧项目更适合先做接手分析。

新项目建立建议

• 先让它给目录结构方案
• 再决定技术栈和基础配置
• 最后再开始批量生成文件

老项目接手建议

优先要求它讲：

• 项目用途
• 关键模块
• 启动命令
• 测试命令
• 最值得先看的文件

编写

不要把很大的模糊需求一次性交给 Codex。尽量拆成理解回合、实现回合、修正回合。

一个更稳的拆分方法

1. 先定位问题或范围
2. 只做一个子功能
3. 看 diff
4. 跑验证
5. 再处理下一小块

这比"大任务一口气做完"更像真正可靠的工程流程。

运行

运行阶段的关键不是"让它会敲命令"，而是让命令结果回到当前线程上下文里。

更稳的做法不是先猜命令，而是先让 Codex 识别当前项目真正可用的命令来源，例如：

• package.json
• pyproject.toml
• Makefile
• go.mod
• Cargo.toml

确认后，再在内置终端里运行这个项目实际存在的测试或构建命令。

常见示例包括：

• npm test
• pnpm test
• pytest
• go test ./...
• cargo test

这些只是"常见项目命令示例"，不是对所有仓库都可直接复制运行的通用命令。

测试或构建失败时的修复提示

如果终端报错，在线程中输入以下提示词，让 Codex 结合错误继续修复：

请结合刚才终端里的错误继续修复。
优先最小改动，完成后说明你是怎么验证的。

不知道该跑什么命令时

如果你不确定当前项目的启动、测试和构建命令，先不要让它改代码，在线程中输入：

请先不要改代码。
先根据当前仓库中的 package.json、Makefile、pyproject.toml 或其他配置文件，
告诉我这个项目真实可用的启动、测试和构建命令分别是什么。
确认后我再让你执行。

审查

正如《前言》中所说，先看审查区不要只看回复。真正稳定的方式不是"让它改完就提交"，而是：改动 -> 审查 -> 批注 -> 修正 -> 验证 -> 再决定提交。

审查时重点看什么

• 是否只改了必要文件
• 是否误伤了无关模块
• 命名、结构和风格是否合理
• 有没有缺少测试、日志或错误处理

如果你不满意某一段改动，最好的方式通常不是重新写很长解释，而是直接在审查区里加 inline comment。

发布

发布阶段通常包括：

• stage
• commit
• push
• 创建 PR

你可以要求 Codex 基于当前改动生成：

• commit message
• PR 描述
• 验证说明
• 变更摘要

这样它不仅帮你写代码，也开始参与交付表达。

设置与进阶

建议读法：

• 新手先看"新手推荐设置"和"推荐掌握顺序"
• 只有当你真的开始需要并行任务、页面检查或外部连接时，再深入看后面的进阶能力

新手推荐设置

正如《前言》中所说，先理解后执行。核心建议：

• 权限先保守，再逐步放宽
• 每个线程只做一件事
• 每轮都给完成标准
• 每次重要改动后都看审查区（Review）

为什么"默认保守"通常更好

对新手来说，最重要的是先跑顺流程，而不是一上来就把权限、网络和执行范围全部放开。过早放权的常见后果是：

• 改动范围失控
• 误改无关文件
• 难以回头检查每一步发生了什么

所以更推荐的方式是：

1. 先用默认权限完成一个小任务
2. 只有在明确受限时再放宽
3. 优先按项目或按任务放宽，而不是全局放宽

常见设置项怎么理解

行为配置（Agent configuration）

这是和模型、推理强度、权限边界最相关的一组设置。你可以把它理解成"行为基线"。

Git 相关设置（Git）

这部分更偏交付规范，比如：

• 分支命名
• commit 习惯
• PR 描述风格

集成与 MCP（Integrations & MCP）

这是扩展外部数据和动作的入口。它的价值不在"更多工具"，而在"让上下文更完整"。

进阶能力

工作树（Worktree）

最值得学会的桌面端能力之一，适合并行任务和隔离改动。

如果你开始长期使用 Codex，Worktree 往往是最先值得深入掌握的高级能力。

应用内浏览器（In-app browser）

适合预览本地开发服务器、文件预览和不需要登录的公开页面，不适合依赖登录态、浏览器插件、已有 Cookie 或历史标签页的网站。遇到登录态页面，优先考虑 Chrome 插件或你自己的常规浏览器。

电脑操作（Computer Use）

适合 GUI 场景，比如桌面应用、模拟器或只能点界面的后台工具。

技能、插件、MCP 与自动化

• Skills：任务套路
• Plugins：能力集合
• MCP：外部数据和动作连接
• Automations：定时或持续触发的任务

AGENTS.md

AGENTS.md 是放在项目根目录或 .codex/ 目录下的团队级指令文件。它的作用是让 Codex 在每次开始工作时，自动读取你预设的规则和约定。

它适合放什么：

• 团队编码规范（命名风格、提交格式、分支策略）
• 项目特定的约束（不要修改的文件、不要引入的依赖）
• 常用命令说明（启动命令、测试命令、构建命令）
• 审查标准（重点检查什么、什么算完成）

一个最小示例：

# 项目规范

## 编码约定
- 使用 TypeScript 严格模式
- 组件命名使用 PascalCase
- 提交信息遵循 Conventional Commits

## 约束
- 不要修改 `src/legacy/` 目录下的文件
- 不要引入新的运行时依赖，除非经过团队确认

## 常用命令
- 启动：`pnpm dev`
- 测试：`pnpm test`
- 构建：`pnpm build`

## 审查标准
- 每次改动必须附带测试
- 不要遗留 console.log
- PR 描述需要说明改动原因和验证方式

什么时候创建：

• 当你的提示词中有反复出现相同的规则和约束时
• 当团队多人使用 Codex 协作时
• 当你希望 Codex 每次都自动遵循项目约定时

详细用法请参考插件、技能与自动化 中的"从一次性提示词到团队资产的升级路线"一节。

推荐掌握顺序

不要一开始就把所有高级功能都接进来。更稳的顺序通常是：

1. 先把线程、审查区和内置终端用顺
2. 再掌握工作树（Worktree）
3. 再看插件、技能与自动化
4. 再沉淀 AGENTS.md
5. 最后按需要接技能、MCP 和自动化

键盘快捷键速查表

通用操作

线程操作

审查区（Review）

终端

模式切换

费用与配额说明

两种登录方式的费用差异

ChatGPT 登录

• 使用 ChatGPT 计划中包含的 Codex 权益和额度
• 具体可用额度、并发能力和高级功能取决于你的计划
• 官方计划名称和包含范围会变化，阅读时请以当前 ChatGPT 计划与官方说明为准
• 适合：希望用同一个 ChatGPT 账号打通桌面端、CLI、IDE 或云端入口的用户

API Key 登录

• 按 API 调用量计费，使用你的 OpenAI API 余额
• 每次请求（包括读取文件、执行命令、生成回复）都会产生 token 费用
• 费用透明度高，可在 OpenAI Usage 页面 实时查看
• 适合：需要精确控制成本、有程序化工作流的用户

可能影响费用的使用场景

控制费用的建议

1. 先明确范围再执行：模糊的大任务通常比精确的小任务消耗更多 token
2. 优先使用 /plan：先规划再执行，避免反复试错带来的额外费用
3. 合理设置自动化频率：不要设置过于频繁的巡检间隔
4. 定期检查用量：API Key 用户建议每周检查一次用量页面
5. 利用 Worktree 隔离：避免在一个线程里反复做大量无关操作

配额限制

Codex 桌面端可能受以下限制（具体以官方说明为准）：

• 每分钟 / 每天的请求次数上限
• 单次对话的上下文长度上限
• 并发线程数量
• 自动化任务的运行频率

如果遇到限制提示，通常可以通过等待、减少并发或升级计划来解决。

数据安全与隐私说明

Codex 能访问什么

根据你授予的权限级别，Codex 桌面端可能能够：

数据发送与存储

发送到 OpenAI 服务的内容

以下内容会在使用过程中发送到 OpenAI 的服务器：

• 你输入的提示词
• Codex 读取的项目文件内容
• 终端输出的内容
• 通过 Browser 或 Computer Use 截取的界面信息
• 自动化运行时产生的上下文

本地存储的内容

• ~/.codex/ 目录：存储配置和认证信息
• 项目目录中的 .codex/ 目录：存储工作树和本地配置
• AGENTS.md：团队级指令文件（如果你创建了的话）

安全最佳实践

1. 保护凭证信息

• 不要把 API Key 提交到代码仓库
• 不要在公开文档中暴露 API Key
• 如果使用公司设备，遵循组织的认证和权限规范
• 定期轮换 API Key

2. 谨慎授权

正如《设置与进阶》中强调的，权限先保守再放宽：

• 默认权限：只允许读取和少量修改
• 按任务放宽：只在明确需要时临时扩展
• 避免全局放开：优先按项目或按线程授权

3. 用 Worktree 隔离风险

• 自动化任务推荐在 Worktree 中运行，避免直接修改主分支
• 试验性改动使用 Worktree 隔离，确认后再合并

4. 敏感项目的额外注意事项

如果你的项目涉及以下内容，请格外注意：

• 用户数据、个人信息（PII）
• 密钥、证书、token
• 金融、医疗等受监管领域数据
• 企业内部机密信息

建议：

• 在项目根目录创建 .codexignore 文件，排除敏感文件
• 在提示词中明确声明"不要读取或修改以下文件：..."
• 使用最小权限模式，限制 Codex 的文件访问范围

5. 自动化的安全边界

自动化因为后台运行，风险比普通线程更高：

• 先手动验证提示词，再设为自动化
• 前几次运行结果必须人工检查
• 设置合理的停止条件和汇报门槛
• 避免给自动化 Full Access 权限

合规建议

如果你在以下环境中使用 Codex，建议先咨询合规团队：

• 受 SOC 2、HIPAA、GDPR 等法规约束的组织
• 处理政府或国防相关项目
• 有严格数据出境要求的地区

插件、技能与自动化

建议读法：

• 第一次读，先抓"插件、技能、自动化分别解决什么问题"
• 第二次读，重点看"推荐安装清单"和"如何与提示词串起来"
• 真正准备沉淀团队流程时，再重点看"技能、插件、自动化"的升级路线

一、先把四个概念分清楚

1. 插件（Plugin）

插件是 Codex 里的"安装包"或"分发单元"。一个插件里可以包含：

• 技能
• Apps 连接
• MCP servers

你可以把插件理解成：别人已经打包好的能力集合。

2. 技能（Skill）

技能是"可复用工作流"的作者格式。它通常由：

• 一个 SKILL.md
• 可选脚本
• 可选参考资料

构成。技能更像"如何做一类事情"的流程说明。

3. MCP / Apps

这部分负责把 Codex 接到外部系统，比如：

• GitHub
• Google Drive
• Browser
• 文档、表格、设计工具

它解决的是"Codex 怎么读外部数据、怎么调用外部动作"的问题。

4. 自动化（Automation）

自动化负责"按时间或心跳反复运行一段工作流"。你可以把它理解成：

• 定时唤醒
• 自动巡检
• 持续跟进

的机制。

二、它们之间的关系

更好记的方式是：

• 技能定义工作流
• MCP / Apps 提供外部能力
• 插件把这些能力打包并分发
• 自动化把工作流按计划运行起来

所以很多时候不是四选一，而是组合使用。

例如：

• 用 GitHub 插件拿到 PR 信息
• 用技能定义"怎么处理 review comments"
• 用自动化每隔一段时间检查一次 PR 状态

这才是 Codex 扩展生态真正强的地方。

三、什么时候优先用插件，什么时候优先用技能

更适合先装插件的场景

• 你想直接获得一类成熟能力
• 这类能力需要接外部系统
• 你不想从零写流程

例如：

• GitHub
• Google Drive
• Browser
• Data Analytics

更适合先做技能的场景

• 你已经有一套固定工作方法
• 这套方法会反复使用
• 你希望它可复用，但暂时不需要对外分享

例如：

• 固定的代码审查流程
• 固定的发布准备流程
• 固定的文档整理套路

四、如何安装和使用插件

根据官方文档，Codex 桌面端可以通过 Plugins 目录浏览和安装插件。

一般流程是：

1. 打开 Plugins
2. 搜索或浏览插件
3. 进入详情页
4. 安装插件
5. 如果需要外部 app，按提示登录或连接
6. 新开线程，直接描述任务或用 @ 指定插件

插件装好之后，你有两种常见用法：

方式一：直接说你要的结果

例如：

• 总结今天未读的 GitHub PR 评论
• 从 Google Drive 里找最新的培训文档并帮我提纲

适合：你更关心结果，不想指定底层工具。

方式二：显式指定插件

通过 @插件名 或对应技能显式调用。

适合：你明确知道自己希望哪一个插件来完成任务。

一个很容易混淆但必须分清的点

本章会同时出现三类"像命令的东西"，它们输入位置不同：

• /plan 这类以斜杠开头的是线程里的 slash command
• $skill-name 这类以美元符号开头的是在线程输入框里显式调用技能
• codex ...、mkdir ... 这类才是系统终端里的 shell 命令

如果把这三类混在一起照抄，是最容易导致"为什么跑不通"的原因之一。

五、推荐优先掌握的插件与技能

这里说的是"推荐优先掌握"，不是客观意义上的"必装"。

1. GitHub 相关

推荐原因：

• 最贴近日常开发流程
• 能处理 PR、评论、CI 等真实协作问题

适合人群：

• 经常做代码审查
• 需要处理评审反馈
• 想把 Codex 真正纳入团队开发闭环

2. Google Drive / Documents / Spreadsheets

推荐原因：

• 很多真实工作不只有代码
• 文档、表格、培训材料、汇报稿都能纳入同一工作流

适合人群：

• 经常写说明文档
• 要处理表格和资料
• 需要做培训、教程或交付材料

3. Browser / Product Design / imagegen

推荐原因：

• 前端和内容型工作很常需要看页面、看布局、看视觉
• 这些能力能补足"只看代码"的盲区

4. openai-docs

推荐原因：

• 当你写的是 Codex、OpenAI API、模型能力相关材料时，这类技能非常关键
• 适合校对官方术语和事实

5. skill-creator / skill-installer / plugin-creator

推荐原因：

• 当你开始积累自己的工作方法时，真正提升效率的关键不是装更多东西，而是把自己的套路沉淀出来

六、更明确的推荐安装清单

这一节更像"按人群给安装建议"，方便你快速判断该先装什么。

1. 新手用户优先安装

openai-docs

建议优先级：高

适合原因：

• 能帮你校对 OpenAI / Codex 官方术语和产品事实
• 写教程、写说明、查最新文档时非常实用

适合人群：

• 第一次接触 Codex
• 正在写教程、笔记、培训材料

典型使用案例：

• 你在写一篇"Codex 与 ChatGPT 有什么区别"的教程，想确认术语和最新官方说法
• 你要比较模型、产品入口、官方能力边界，不想依赖二手博客

从安装到第一次使用：

1. 打开 Codex 桌面端的 Plugins
2. 搜索 openai-docs
3. 安装后新建一个对话
4. 直接输入：请基于官方文档说明 Codex 桌面端与 API 使用场景的区别，并给出引用来源
5. 检查回答里是否带有官方出处，再继续追问细节

第一次建议你做的小任务：

• 让它帮你核对一段教程中的术语是否准确
• 让它给出某个能力的官方链接和简明解释

Browser

建议优先级：高

适合原因：

• 前端、网页预览、本地页面检查非常常见
• 比单纯口头描述页面问题更直观

适合人群：

• 前端开发
• 需要预览 localhost 页面的人

典型使用案例：

• 你本地跑了一个站点，希望 Codex 直接打开页面并指出布局问题
• 你要检查一个按钮在移动端是否被遮挡，或某个表单是否能正常提交

从安装到第一次使用：

1. 打开 Plugins
2. 搜索并安装 Browser
3. 确保你的本地页面已经启动，比如 本地开发地址
4. 新建一个对话，输入：打开 3 个最值得先修的问题
5. 如果需要继续修改，再让它结合页面状态给出修复建议

第一次建议你做的小任务：

• 检查首页在桌面端和移动端的排版是否稳定
• 查看某个弹窗、下拉菜单、表单交互是否正常

GitHub

建议优先级：高

适合原因：

• 大多数真实开发最终都要落到 PR、评论、CI、分支协作
• 很容易把 Codex 从"写代码工具"升级为"协作工具"

适合人群：

• 有 GitHub 工作流的人
• 需要处理 PR 与审查流程的团队

典型使用案例：

• 你要汇总一个 PR 里的评审意见，并分辨哪些是必须修、哪些只是建议
• 你想让 Codex 帮你查看失败的 CI，并优先定位最可能的报错点

从安装到第一次使用：

1. 打开 Plugins
2. 搜索并安装 GitHub
3. 按提示完成 GitHub 账号连接
4. 新建一个对话，输入：帮我总结这个仓库最近一个 PR 的 review comments，并按必须处理 / 可选优化分类
5. 如果你已经在某个仓库目录中，也可以直接让它读取当前分支关联的 PR 上下文

第一次建议你做的小任务：

• 总结最近一个 PR 的评论
• 查看一次失败的 CI，并让它解释报错含义

2. 开发者常装清单

GitHub

用途：

• 看 PR
• 处理 review comments
• 跟进 CI
• 做分支协作

典型使用案例：

• "把这个 PR 里还没解决的评论列出来，并给出逐条处理建议"
• "帮我看为什么这次 GitHub Actions 挂了"

从安装到第一次使用：

1. 安装并连接 GitHub
2. 在仓库目录新建对话
3. 输入：检查当前分支对应 PR 的 review 状态，并给我一个处理清单
4. 处理完后，再让它复核是否还有遗漏

Browser

用途：

• 看本地页面
• 检查前端交互
• 配合页面批注修问题

典型使用案例：

• "打开本地开发页，看看登录按钮点击后有没有报错"
• "对比改版前后两个页面，指出视觉层级和可用性差异"

从安装到第一次使用：

1. 安装 Browser
2. 启动本地项目
3. 输入：`打开
4. 如果发现问题，再让它配合代码改动一起修

Computer Use

用途：

• 处理 GUI 场景
• 桌面应用测试
• 模拟器或只能点界面的工具操作

注意：

• 这类能力更强，也更要注意边界

典型使用案例：

• 你需要在一个只能通过桌面界面操作的软件里重复执行固定步骤
• 你想让 Codex 帮你检查某个设置项到底藏在哪个菜单里

从安装到第一次使用：

1. 安装 Computer Use
2. 打开目标应用，先停在安全页面
3. 在对话里明确范围：只在当前应用窗口中检查导出菜单，不做提交、发送、删除动作
4. 让它先描述界面，再进行一步一步操作

第一次建议你做的小任务：

• 查找菜单入口
• 执行不涉及删除、付款、发送的只读或低风险操作

skill-creator

用途：

• 把你自己的固定流程做成技能
• 让常用工作法可复用

典型使用案例：

• 你经常做"提交前检查"，想让 Codex 每次都按同一套标准执行
• 你想把"写接口文档"的固定流程封装成团队技能

从安装到第一次使用：

1. 安装 skill-creator
2. 新建对话，输入：帮我创建一个"提交前检查"技能，包含测试、lint、变更摘要和风险提示
3. 让它生成技能骨架
4. 把生成的说明再根据你的团队习惯补充细节

第一次建议你做的小任务：

• 先做一个单一职责的小技能
• 不要一开始就做过于庞杂的"万能技能"

3. 文档 / 培训 / 内容型用户常装清单

Google Drive

用途：

• 处理 Docs、Sheets、Slides、Drive 文件
• 适合写教程、整理材料、做课件

典型使用案例：

• 从 Drive 里找到最近一次培训课件，提取成教程目录
• 汇总多个 Docs 的内容，生成统一风格的说明文档

从安装到第一次使用：

1. 安装 Google Drive
2. 完成账号连接
3. 输入：帮我在 Google Drive 中找最近更新的 Codex 培训文档，并整理出目录结构
4. 确认找到的文件后，再让它进一步摘要或改写

第一次建议你做的小任务：

• 找文件并摘要
• 对比两个文档版本的差异

Documents

用途：

• 生成和修改文档型交付物
• 适合正式说明书、培训材料、文档输出

典型使用案例：

• 把 Markdown 教程排版为更正式的文档交付件
• 对一份说明书进行结构重写、章节补强和格式统一

从安装到第一次使用：

1. 安装 Documents
2. 准备一份已有内容，哪怕是粗稿也可以
3. 输入：把这份教程整理成正式文档结构，增加封面、章节层级和统一术语
4. 生成后检查版式，再继续微调

第一次建议你做的小任务：

• 先整理一篇短文档
• 再处理整本手册，避免第一次就面对过大的版式复杂度

Spreadsheets

用途：

• 表格清洗
• 公式整理
• 图表和简单数据分析

典型使用案例：

• 清洗一份学员名单或测试结果表
• 把混乱的统计表转成适合画图和汇报的结构

从安装到第一次使用：

1. 安装 Spreadsheets
2. 准备一个表格文件或可访问的数据表
3. 输入：帮我检查这个表的空值、重复项和字段命名问题，并给出整理建议
4. 确认规则后，再让它实际生成整理后的版本

第一次建议你做的小任务：

• 先做字段清洗和格式统一
• 再进阶到公式、透视、图表和分析说明

openai-docs

用途：

• 校正文档内容
• 避免术语和产品事实写错

典型使用案例：

• 你写了一章"模型与能力边界"，想让它逐段核对
• 你要在培训材料中引用官方功能定义

从安装到第一次使用：

1. 安装 openai-docs
2. 把你写好的段落贴进对话
3. 输入：请按官方文档校对这段内容，指出术语不准确和事实过时的地方
4. 根据它的反馈再回改正文

4. 团队负责人或重度用户常装清单

plugin-creator

用途：

• 把稳定工作流打包成插件
• 方便团队安装和共享

典型使用案例：

• 你们团队有固定的发布检查流程，想打包成可安装插件
• 你想把多个技能、说明和工具入口整合成一个团队能力包

从安装到第一次使用：

1. 安装 plugin-creator
2. 输入：帮我创建一个团队内部插件，包含发布检查、PR 规范和文档模板
3. 让它先生成最小插件骨架
4. 再逐步补充技能、说明和分发方式

第一次建议你做的小任务：

• 先打包一项稳定流程
• 等团队验证有价值后，再继续扩展插件能力

skill-installer

用途：

• 统一团队技能安装
• 快速试用现成技能

典型使用案例：

• 你想批量试用几个现成技能，看看哪些适合团队
• 你希望新人按统一清单完成基础能力安装

从安装到第一次使用：

1. 安装 skill-installer
2. 输入：列出适合代码审查、文档整理、发布准备的可安装技能
3. 按优先级先安装 1 到 2 个
4. 立即用一个真实任务验证是否值得保留

第一次建议你做的小任务：

• 不要一次装太多
• 每装一个就安排一次真实使用验证

Data Analytics

用途：

• 数据分析
• KPI、报表、指标追踪

适合：

• 既做开发，又经常处理业务数据的人

典型使用案例：

• 你想让 Codex 帮你做一份周报式指标解读
• 你需要分析某个功能上线后，转化率、留存率或错误率的变化

从安装到第一次使用：

1. 安装 Data Analytics
2. 准备数据来源或报表文件
3. 输入：基于这份数据，帮我生成一个本周核心指标概览，并指出最异常的两个变化
4. 先从简单描述和可视化开始，再进阶到 dashboard 或报告

第一次建议你做的小任务：

• 先做单次分析
• 再扩展为周期性报表、监控或 dashboard

5. 如果你只想先装 3 个

如果我是面向大多数桌面端用户给一个最小推荐组合，我会建议先掌握：

1. GitHub
2. Browser
3. openai-docs

原因很简单：

• GitHub 连接真实开发协作
• Browser 连接页面和可视化结果
• openai-docs 连接准确信息来源

这三个加起来，已经能覆盖大量最常见的桌面端使用场景。

七、怎样安装技能

根据官方技能说明，最常见的方式有两类：

方式一：安装现成技能

用：

下面这段要输入到 Codex 线程输入框里：

$skill-installer <skill-name>

来安装内置或可安装的技能。

例如，官方文档中的可执行示例是：

下面同样是线程输入，不是 shell：

$skill-installer hatch-pet

这里要注意：

• 这不是系统终端命令
• 这是在 Codex 线程输入框中输入的技能调用
• 最稳妥的写法是把目标技能名一起写上

它更适合：

• 本地试用
• 个人能力扩展
• 先验证值不值得长期保留

方式二：在本地或仓库里直接写技能

技能可以放在：

• 用户级目录
• 仓库级 .agents/skills

这让你既可以做个人技能，也可以做团队共享技能。

八、怎样创建自己的技能

官方推荐优先使用：

下面这段要输入到 Codex 线程中：

$skill-creator

它会先帮你梳理：

• 技能做什么
• 什么时候触发
• 是只用说明，还是带脚本

如果手工创建，一个最小技能大概长这样：

下面这是 SKILL.md 的最小模板，不是终端命令：

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

在这里写技能给 Codex 的说明内容。

什么样的内容适合写成技能

最适合写成技能的，通常是这些"会重复出现"的流程：

• 提交前检查
• PR 评论处理
• 文档整理
• 数据校验
• 发布准备

写技能时的原则

正如《前言》中所说，一个线程只做一件事。写技能时同样建议：

• 一次只做一件事
• 描述触发条件要清楚
• 能用说明解决，就先不用脚本
• 只有在需要确定性或外部命令时，再加脚本

九、怎样创建自己的插件

当你不只是自己用，而是准备：

• 给团队分发
• 把多个技能打包
• 绑定 Apps / MCP
• 做更稳定的复用能力

就该考虑插件。

官方推荐先用：

下面这段要输入到 Codex 线程中：

@plugin-creator

来生成插件骨架。

这里同样要注意：

• @plugin-creator 是在线程里显式调用插件或技能的写法
• 不是在 macOS 终端、PowerShell 或 Bash 中执行的 shell 命令

一个最小插件至少有：

• .codex-plugin/plugin.json
• 一个或多个技能目录

例如最小结构：

下面这是目录结构示意，用来说明插件最小骨架：

my-first-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

什么时候"先技能后插件"更合理

如果你还在反复改流程，先写技能更轻。

如果流程已经稳定，并且：

• 你要给别人装
• 你要绑定外部连接
• 你要做自己的 marketplace

这时再升级成插件更合适。

十、怎样理解"必装"

严格说，并不存在对所有人都一样的"必装插件"。更准确的说法应该是：

• 对代码团队最值得先装什么
• 对文档团队最值得先装什么
• 对前端团队最值得先装什么
• 对培训和知识管理最值得先装什么

所以本书更推荐"按场景选装"，而不是盲目追求越多越好。

十一、自动化是什么，适合做什么

根据官方文档，自动化适合：

• 定期巡检
• 按计划运行后台任务
• 把发现结果送回 Inbox / Triage
• 或在没有结果时自动归档

自动化特别适合重复性任务，例如：

• 每天检查某个项目最近的改动
• 定期看 PR 状态
• 周期性生成报告
• 持续跟进某个长任务

十二、自动化的两种主要形态

1. 线程自动化（Thread automation）

线程自动化会保留当前线程上下文，适合：

• 长任务跟进
• 固定周期回来继续同一个问题
• 需要延续讨论背景的任务

2. 独立 / 项目自动化（Standalone / project automation）

独立自动化适合：

• 每次都是独立运行
• 跑多个项目
• 希望每次结果单独进入 Triage

十三、怎样创建自动化

官方说明里，一个很实用的做法是：

先在普通线程里把提示词跑通，再让 Codex 帮你创建自动化。

你可以直接在普通线程里说：

• 帮我创建一个每天上午检查这个项目测试状态的自动化
• 帮我在这个线程里每 15 分钟提醒一次，直到部署完成

Codex 会帮助你选择：

• 自动化类型
• 运行频率
• 是否绑定当前线程

十四、怎样把技能和自动化结合起来

这是自动化最值得用的方式之一。

例如：

• 用一个技能定义"PR 巡检和反馈处理"
• 再让自动化每隔一段时间运行这个技能

这比把一大段复杂提示词直接塞进自动化更稳定，也更好维护。

你可以在自动化提示里显式写：

下面这段要写在自动化提示词或线程输入框中：

$skill-name

让自动化按某个技能工作流来执行。

十五、自动化的安全边界

自动化因为是后台运行，所以风险比普通线程更高。官方文档特别强调：

• 读写权限会影响自动化能力
• Full access 风险最高
• 在 Git 项目里更推荐用 Worktree 跑自动化

更稳的建议是，正如《核心概念》中所建议的，先保守权限再放宽：

1. 先用默认或较保守权限
2. 先手动验证提示词
3. 再把它变成自动化
4. 前几次结果一定要人工检查

十六、给不同用户的推荐路线

个人开发者

推荐顺序：

1. 先掌握 GitHub / Browser / openai-docs 类能力
2. 再写自己的提交、评审、发布技能
3. 最后再加自动化

团队负责人或培训者

推荐顺序：

1. 先统一 AGENTS.md
2. 再统一几项关键技能
3. 再把稳定流程打包成插件
4. 最后用自动化做巡检和节奏维护

内容、文档、培训型用户

推荐顺序：

1. Google Drive / documents / spreadsheets
2. openai-docs
3. 自己的写作、整理、输出模板技能

十七、怎样把插件、技能、自动化和提示词真正串起来

很多人学到这里，已经知道：

• 插件是什么
• 技能是什么
• 自动化是什么

但真正让效率上台阶的关键，不是分别知道这些概念，而是知道：

• 当前阶段该先用哪类提示词
• 提示词跑稳后，下一步该沉淀成技能还是自动化
• 哪些提示词适合接 Browser、GitHub、Google Drive 这类插件

这一节就是把这些东西真正串起来。

flowchart TD
    A["普通线程提示词"] --> B["个人固定模板"]
    B --> C["团队提示词模板"]
    C --> D["技能 Skill"]
    D --> E["插件 Plugin"]
    D --> F["自动化 Automation"]
    E --> F
    G["GitHub / Browser / Google Drive 等插件"] --> A
    G --> D

1. 调研阶段：先用普通线程提示词，不急着做自动化

这时最常用的是：

• 项目接手型提示词
• 先调研，不改代码
• Bug 定位型

适合配合的插件：

• openai-docs
• GitHub
• Google Drive

为什么：

• 调研阶段最重要的是把上下文找全
• 这时你更需要外部资料和仓库上下文
• 还不适合过早做自动化

一个典型组合：

1. 用普通线程输入"先调研，不改代码"
2. 如果需要官方事实，用 openai-docs
3. 如果需要 PR 或仓库上下文，用 GitHub
4. 如果需要查文档资料，用 Google Drive

2. 规划阶段：提示词先稳，再考虑做团队模板

这时最常用的是：

• /plan
• 复杂任务先规划
• 团队模板整理型

适合配合的能力：

• skill-creator
• AGENTS.md

为什么：

• 如果你发现某种规划提示词反复有效，就不该每次重写
• 这时最适合把方法沉淀成团队模板或技能说明

一个典型组合：

1. 先在普通线程里用 /plan
2. 连续几次都有效后，把提示词骨架整理出来
3. 再考虑写进 AGENTS.md 或沉淀成技能

3. 实现阶段：插件负责上下文，提示词负责边界

这时最常用的是：

• 控制范围地执行
• 小功能实现型
• 终端报错修复型
• 视觉问题修复型

适合配合的插件：

• Browser
• GitHub
• Computer Use

为什么：

• 实现阶段最容易跑偏的不是"不会写"，而是"边界失控"
• 插件帮你接到真实页面、真实 PR、真实桌面环境
• 提示词负责限制改动范围和验证方式

一个典型组合：

1. 用 Browser 检查页面问题
2. 用"控制范围地执行"提示词实施修改
3. 用终端或审查区做验证
4. 如果是 PR 场景，再用 GitHub 看协作上下文

4. 审查阶段：先有 review 提示词，再谈自动 review

这时最常用的是：

• 代码审查型
• 提交前复核
• 数据安全型提示词

适合配合的插件：

• GitHub
• openai-docs

为什么：

• 自动 review 真正好用的前提，是你先知道自己想让它重点看什么
• 如果连人工 review 提示词都还不稳定，自动化 review 只会放大噪音

更稳的路线：

1. 先把代码审查提示词跑顺
2. 再把审查关注点整理成团队标准
3. 最后才考虑做更自动化的 review 工作流

5. 文档阶段：插件负责资料来源，提示词负责读者视角

这时最常用的是：

• 文档整理型
• 生成说明文档
• 教程改写
• 术语统一

适合配合的插件：

• Google Drive
• Documents
• Spreadsheets
• openai-docs

为什么：

• 写文档最怕的不是没内容，而是资料分散、术语不统一、对象不明确
• 插件帮你把资料接进来
• 提示词帮你明确给谁写、写到多深、哪些不能编造

6. 自动化阶段：先把人工提示词跑稳，再升级

这时最常用的是：

• 自动化 / 巡检型
• 把人工任务改成自动化提示
• 自动化前验证

适合配合的能力：

• skill-creator
• 已有插件能力
• Automations

最稳的升级路径通常是：

1. 先在普通线程里跑通一次人工提示词
2. 再把它整理成更稳定的模板
3. 如果重复频率高，再考虑做成技能
4. 如果需要按时间反复执行，再做成自动化

这条顺序非常重要。很多自动化失败，不是工具不行，而是提示词本身还不稳定。

十八、从一次性提示词到团队资产的升级路线

可以把一条好用的提示词，看成会不断升级的资产。

第一层：一次性线程提示词

特点：

• 为当前任务临时写
• 适合探索和试错

第二层：个人固定模板

特点：

• 你开始反复复用
• 会保留稳定骨架

第三层：团队提示词模板

特点：

• 团队里多人可复用
• 更强调统一表达和最低验证要求

第四层：技能

特点：

• 不只是模板，而是可复用工作流
• 可以带说明、脚本、参考资料

第五层：插件

特点：

• 可以把技能、MCP、Apps 一起打包
• 更适合团队分发和安装

第六层：自动化

特点：

• 适合重复性、高频、可标准化的任务
• 要求提示词比普通线程更耐久

这个升级路线的核心不是"越高级越好"，而是：

• 能用普通线程解决的，不必一开始就插件化
• 还没稳定的流程，不要急着自动化
• 真正稳定后，再做沉淀和分发

十九、几种最值得优先打通的组合

组合一：GitHub + 审查提示词

适合：

• PR review
• 评论处理
• CI 跟进

建议搭配：

• 代码审查型
• 提交前复核
• 团队审查标准模板

组合二：Browser + 前端实现提示词

适合：

• 页面检查
• UI 修复
• 交互回归验证

建议搭配：

• 视觉问题修复
• 页面理解与改版评估
• 控制范围地执行

组合三：Google Drive / Documents + 文档提示词

适合：

• 教程编写
• 培训材料
• 说明书整理

建议搭配：

• 生成说明文档
• 教程改写
• 术语统一

组合四：skill-creator + 高频稳定提示词

适合：

• 提交前检查
• PR 巡检
• 文档整理
• 发布准备

建议搭配：

• 已经连续多次验证有效的提示词骨架

组合五：技能 + 自动化

适合：

• 每日巡检
• 周报生成
• 长任务跟进

建议搭配：

• 自动化 / 巡检型
• 把人工任务改成自动化提示
• 自动化前验证

二十、本章小结

提示词模板与清单

建议读法：

• 第一次用 Codex，先看"按任务阶段快速找模板"
• 日常工作中，优先用"常用模板"和"按角色分类的提示词库"
• 当你想提升稳定性时，再重点看"调优前后对照示范"和"提示词升级的三步法"

本章速查图

一条高质量提示词的 5 个组成部分

• 目标
• 范围
• 约束
• 验证
• 交付

这一套五段式结构，不只是经验总结，也和官方推荐的思路高度一致。OpenAI 在 Codex 最佳实践中建议，好的任务提示至少要包含：

• 目标 Goal
• 上下文 Context
• 约束 Constraints
• 完成标准 Done when

本书把它进一步落成更适合中文日常使用的五段式：

• 目标
• 范围
• 约束
• 验证
• 交付

这样做的好处是，读者不只知道"要做什么"，还会自然补上"怎么判断它真的做完了"。

为什么提示词在日常使用里占核心地位

很多人以为，Codex 的效果主要取决于模型强不强。其实在真实项目里，提示词质量往往更直接决定下面几件事：

• 它会不会先读对上下文
• 它会不会误改无关文件
• 它能不能自己验证结果
• 你审查 diff 时会不会轻松很多

官方文档里反复强调两点：

• 能验证的任务，结果质量通常更高
• 复杂任务拆成小步，通常比一口气描述一大团需求更稳定

这也和很多社区高质量使用经验一致。比较常见的稳定套路不是"大而全的一次性提示"，而是：

1. 先理解
2. 再规划
3. 然后小批次执行
4. 每一轮都 review 和验证

本章下面的代码块怎么使用

本章下面出现的所有代码块，默认都是"输入到 Codex 线程中的提示词模板"，不是系统终端命令。

如果你看到 /plan，它表示：

• 这是 Codex 线程里的 slash command
• 适合在复杂任务开始前先切换到规划模式

如果你看到方括号占位符，例如 [在这里写需求]，记得替换成你的真实任务，不要原样照抄。

按任务阶段快速找模板

如果你不是按"角色"来找模板，而是按"当前任务走到哪一步了"来找，更适合直接看这一节。

1. 调研阶段

适合使用：

• 先调研，不改代码
• 项目接手型
• 接手陌生模块
• 页面理解与改版评估
• 接口改动前评估

这类提示词的共同目标是：

• 先理解项目或模块
• 先找入口、边界和依赖
• 暂时不急着修改

2. 规划阶段

适合使用：

• 复杂任务先规划
• 大需求拆分型
• 团队模板整理型
• 自动化前验证

这类提示词适合：

• 需求复杂
• 任务会分多轮做
• 你需要先把工作拆开

3. 实现阶段

适合使用：

• 控制范围地执行
• 小功能实现型
• 视觉问题修复
• 修复一个明确 Bug
• 终端报错修复型

这类提示词的核心是：

• 明确范围
• 减少误改
• 把验证方式写进去

4. 审查阶段

适合使用：

• 代码审查型
• 提交前复核
• 数据安全型提示词
• 制定统一审查标准

这类提示词更适合：

• 看 diff
• 看风险
• 看有没有遗漏

5. 文档与交付阶段

适合使用：

• 文档整理型
• 生成说明文档
• 教程改写
• 术语统一

这类提示词特别适合：

• 写 README
• 写交接文档
• 写培训材料
• 写发布说明

6. 自动化与沉淀阶段

适合使用：

• 自动化 / 巡检型
• 把人工任务改成自动化提示
• 技能化提炼
• 建立团队提示词模板

这类提示词的目标是：

• 把一次性任务变成复用资产
• 把个人套路变成团队能力
• 把稳定流程变成自动化或技能

常用模板

先调研，不改代码

先不要修改代码。
请先阅读与这个需求相关的文件，告诉我：
1. 当前实现方式
2. 关键入口文件
3. 最小改动方案
4. 风险点
5. 验证方式

适合场景：

• 你刚接手一个项目
• 你不确定需求该改哪一层
• 你希望先看分析，再决定是否动手

为什么好用：

• 它天然限制了第一轮不要直接修改代码
• 它逼着 Codex 先把"改哪里、怎么改、怎么验"说清楚

复杂任务先规划

这一段的第一行 /plan 是 Codex 线程里的 slash command，用来切换到规划模式：

/plan
我要做以下需求：
[在这里写需求]

请先：
1. 梳理相关代码
2. 给出分步执行方案
3. 标出需要我确认的地方
4. 说明建议的验证方式

适合场景：

• 涉及多个文件或多个模块
• 需求本身还有不确定点
• 你预计会做超过一轮修改

官方对应思路：

• 复杂、模糊、难描述的任务，优先先 plan
• 不确定怎么拆时，可以让 Codex 先反过来问你问题

控制范围地执行

按刚才确认的方案执行。
要求：
1. 改动范围尽量小
2. 不改无关代码
3. 保持现有风格
4. 完成后说明改了哪些文件
5. 告诉我如何验证

适合场景：

• 你已经确认方案
• 不想让它"顺手重构"
• 你更在意稳定交付而不是一次性改很多

日常最常用的 8 类提示词

下面这一部分是本章最值得反复使用的内容。它不是只给你"示例句子"，而是告诉你每一类提示词到底适合在什么时机用。

1. 项目接手型

请先阅读这个项目，但先不要修改代码。
告诉我：
1. 项目主要用途
2. 核心模块和入口
3. 本地启动、测试、构建命令分别是什么
4. 最值得先看的 5 个文件
5. 如果我要先做一个低风险改动，建议从哪里开始

适合：

• 第一次打开某个仓库
• 刚从别人手里接项目
• 想先建立整体地图

2. Bug 定位型

先不要直接修。
请先根据我描述的问题，定位最可能相关的文件、调用链和状态变化过程。

问题现象：
[在这里写复现现象]

请输出：
1. 最可能的根因候选
2. 你需要我补充的最少信息
3. 最小修复方案
4. 建议如何验证修复是否生效

适合：

• Bug 现象明确，但根因不明确
• 你不希望它一上来就"盲修"

3. 小功能实现型

按最小改动原则实现下面这个需求：

需求：
[在这里写功能]

要求：
1. 先复用现有模式，不要无关重构
2. 改动范围尽量小
3. 如果涉及 UI，保持现有风格
4. 完成后说明改了哪些文件
5. 告诉我如何验证

适合：

• 增加一个筛选条件
• 增加一个按钮或状态
• 补一个小接口或配置项

4. 测试补全型

请为这次改动补充最必要的测试。
要求：
1. 优先覆盖核心行为和边界情况
2. 保持现有测试风格
3. 如果当前项目已有测试工具或辅助函数，优先复用
4. 完成后告诉我新增了哪些测试，以及分别覆盖了什么

适合：

• 功能改完后补测试
• 修复 Bug 后补回归验证

5. 代码审查型

请把自己切换到代码审查模式。
先不要直接修改代码。

请重点检查：
1. 是否存在行为回归风险
2. 是否缺少测试或错误处理
3. 是否有命名、结构或边界不清的问题
4. 是否改动了不必要的文件

请按"高风险 / 中风险 / 低风险"输出。

适合：

• 你已经看到一轮 diff
• 准备提交前做一次独立复核
• 想让 Codex 扮演 reviewer，而不是 implementer

6. 终端报错修复型

请结合刚才终端里的报错继续修复。
要求：
1. 优先修复第一处真正导致失败的错误
2. 不要顺手做无关改动
3. 完成后说明根因是什么
4. 说明你用什么命令重新验证过

适合：

• 构建失败
• 测试失败
• lint / type-check 失败

7. 文档整理型

请基于当前代码和已有文档，整理一份给团队成员看的说明。
要求：
1. 先尊重现有实现，不要编造不存在的能力
2. 用结构化小标题组织内容
3. 明确写出使用前提、主要流程、限制和常见问题
4. 如果信息不足，先指出缺口，再给出可确认部分

适合：

• 写 README
• 写交接文档
• 写培训材料

8. 自动化 / 巡检型

请帮我把下面这类重复工作整理成可复用提示词：

任务：
[在这里写周期性任务]

要求：
1. 输出一版适合人工线程使用的提示词
2. 再输出一版适合自动化使用的更耐久提示词
3. 说明哪些条件下应该停止、汇报或请求人工确认

适合：

• 每日巡检
• 周报生成
• 定期检查 PR、日志或部署状态

三种特别重要的提示词写法

1. 先理解，后执行

这是社区里非常常见、也非常稳定的一种用法。

核心不是一上来就让它改，而是先让它：

• 理解项目结构
• 理解相关文件
• 理解现有实现方式

再进入真正执行。

它特别适合：

• 老项目
• 不熟悉的仓库
• 一改就容易连锁反应的模块

2. 小批次推进，而不是大一锅端

不少高质量的个人教程和社区经验都提到同一个规律：把需求拆成小批次，比一次性扔一个超大提示更稳定。

更稳的节奏通常是：

1. 一次只解决一个小问题
2. 每次改完先看 diff
3. 每次都做验证
4. 再进入下一小步

如果你发现 Codex 总是：

• 改动过大
• 误伤无关逻辑
• 做完后很难 review

通常不是模型不行，而是提示词没有帮它建立好边界。

3. 把"完成标准"写清楚

官方提示工程指导特别强调成功标准和停止条件。

对日常用户来说，最实用的落地方式就是在提示词里写清：

• 改到什么程度算完成
• 需要通过哪些验证
• 什么情况下先停下来等你确认

例如：

完成标准：
1. 问题不再复现
2. 相关测试通过
3. 没有新增无关文件改动
4. 如果需要改数据库结构，先停下来向我确认

坏提示词是怎么把任务带偏的

下面几种写法，在日常使用里非常常见，也最容易导致结果失控。

坏例子一：目标太大

帮我把这个项目整体优化一下。

问题：

• 没有范围
• 没有优先级
• 没有完成标准

更好的写法：

请先只关注首页加载性能。
先分析首屏慢的主要原因，再给出最小优化方案。
如果需要大范围重构，先不要实施，先告诉我影响面。

坏例子二：只有结果，没有约束

给我把这个功能做出来。

问题：

• 它不知道该遵循什么模式
• 它不知道能不能重构
• 它不知道要不要补测试

更好的写法：

请按现有项目模式实现这个功能。
要求改动范围尽量小，不改无关文件。
如果涉及新依赖，先说明理由再决定是否引入。
完成后告诉我如何验证。

坏例子三：没有验证要求

修一下这个 bug。

问题：

• 它可能只做表面修补
• 你事后很难判断是否真的修好

更好的写法：

请先定位这个 bug 的最可能根因，再做最小修复。
完成后说明：
1. 根因是什么
2. 改了哪些文件
3. 用什么方式验证过
4. 还有什么残留风险

一个建议长期保留的万能骨架

如果你平时只想记住一套结构，可以长期复用下面这一版：

任务目标：
[写清你要它做什么]

相关范围：
[写清文件、模块、页面、报错或背景]

约束条件：
1. [写清不能乱动什么]
2. [写清要遵循什么]

完成标准：
1. [写清什么算完成]
2. [写清如何验证]

交付要求：
1. 说明改了哪些文件
2. 说明如何验证
3. 如有风险或待确认项，单独列出

这套骨架的好处是：

• 足够简单
• 适合复制
• 同时兼容调研、实现、修复、审查四类任务

按角色分类的提示词库

这一节适合当"速查页"来用。不同角色面对 Codex 时，最常见的问题不一样，所以高频提示词也不一样。

一. 开发者常用

1. 接手陌生模块

请先阅读这个模块，但先不要修改代码。
我希望你重点告诉我：
1. 这个模块的职责
2. 核心入口和主要依赖
3. 最容易改坏的边界在哪里
4. 如果我要新增一个小功能，最合适的切入点是什么
5. 建议我先看哪几个文件

适合：

• 接手旧代码
• 刚进入新团队
• 临时被分配到不熟悉的模块

2. 修复一个明确 Bug

请先定位这个问题，不要直接修改。

问题描述：
[在这里写复现现象]

请输出：
1. 最可能相关的文件和调用链
2. 根因候选按概率排序
3. 最小修复方案
4. 建议验证步骤
5. 哪些地方最可能引入回归

适合：

• 已经能复现
• 但你不希望它"先改再说"

3. 做一个小需求

请按现有模式实现下面这个需求：

需求：
[在这里写需求]

要求：
1. 先复用现有组件、工具函数和模式
2. 不做无关重构
3. 改动范围尽量小
4. 完成后列出改动文件
5. 说明测试或手动验证方式

4. 补测试

请为这次改动补充最必要的测试。
要求：
1. 优先补核心路径和边界情况
2. 复用现有测试约定
3. 不为了测试而大改生产代码
4. 完成后说明每条测试覆盖了什么

5. 提交前复核

请基于当前 diff 做一次提交前复核。
先不要直接修改代码。

重点检查：
1. 有没有无关改动
2. 有没有行为回归风险
3. 有没有缺少测试、日志或错误处理
4. 命名和结构是否保持一致

请按"必须处理 / 建议优化 / 可以接受"三类输出。

二. 前端 / UI 开发者常用

1. 页面理解与改版评估

请先理解这个页面的结构和交互，不要直接改代码。
告诉我：
1. 页面由哪些主要区域组成
2. 数据流和状态流大致是什么
3. 哪些组件最适合复用
4. 如果要做视觉改版，最容易牵动哪些地方
5. 建议先从哪一个最小改动开始

2. 视觉问题修复

请帮我定位这个前端显示问题，并优先给出最小修复方案。

问题：
[在这里写页面现象]

要求：
1. 先解释最可能原因
2. 如果能只改样式，不要动业务逻辑
3. 完成后说明桌面端和移动端分别如何验证

3. 结合 Browser 做页面检查

请打开本地页面并检查以下问题：
[在这里写要检查的点]

输出要求：
1. 先列出发现的问题
2. 按优先级排序
3. 再给出建议修复顺序
4. 如果你认为应该直接修改代码，再等我确认

三. 后端 / 接口开发者常用

1. 接口改动前评估

请先分析这个接口相关的实现，不要直接修改。
告诉我：
1. 请求入口和调用链
2. 参数校验、权限校验、错误处理分别在哪里
3. 改这个接口最容易影响哪些调用方
4. 最小改动方案是什么
5. 应该如何验证没有破坏现有行为

2. 错误排查

请根据这段日志或报错，先做根因分析。

日志 / 报错：
[贴在这里]

请输出：
1. 最可能的根因
2. 需要继续确认的最少信息
3. 建议先检查的文件和配置
4. 如果修复，最小改动应该落在哪一层

3. 数据安全型提示词

请评估这个改动是否可能影响数据一致性、权限边界或异常处理。
先不要直接改代码。

请重点检查：
1. 是否会写错数据
2. 是否会绕过原有权限判断
3. 是否会吞掉原有错误
4. 是否需要补充测试或日志

四. 文档 / 培训 / 写作型用户常用

1. 生成说明文档

请根据当前代码和已有资料，整理一份给新同事看的说明文档。
要求：
1. 结构清楚，分章节
2. 不要编造实现细节
3. 写清使用前提、主要流程、限制和常见问题
4. 如果信息缺失，明确标记"待确认"

2. 教程改写

请把下面这段内容改写成更适合培训教材的风格。
要求：
1. 保留原意
2. 表达更清楚
3. 增加步骤感
4. 必要时补充读者容易忽略的前提条件

3. 术语统一

请帮我统一这份文档中的术语和表达风格。
要求：
1. 同一个概念只保留一种主称呼
2. 优先使用官方术语
3. 标出可能过时或模糊的说法
4. 不改变技术含义

五. 团队负责人 / Reviewer 常用

1. 制定统一审查标准

请帮我整理一份团队级代码审查清单。
背景：
[写清团队类型或项目类型]

要求：
1. 按高风险、常规风险、风格一致性分类
2. 尽量可执行、可检查
3. 避免空泛口号
4. 最后给出一版适合放进 AGENTS.md 的短版

2. 复盘一次失败任务

请帮我复盘这次 Codex 使用为什么效果不好。

我给你的材料有：
1. 原始提示词
2. 最终改动
3. 发现的问题

请分析：
1. 是目标不清、范围不清、约束不足，还是验证缺失
2. 哪一句提示最可能导致跑偏
3. 下次应该怎么改写

3. 建立团队提示词模板

请把下面这类高频任务整理成团队统一模板：
[在这里写任务类型]

要求：
1. 输出一个短版模板，适合日常直接复制
2. 输出一个长版模板，适合复杂任务
3. 说明什么时候应该先 `/plan`
4. 说明最低验证要求

六. 重度用户 / 自动化设计者常用

1. 把人工任务改成自动化提示

请把这个人工工作流改写成一版适合自动化运行的提示词。

原始任务：
[在这里写任务]

要求：
1. 写清每次运行应该做什么
2. 写清发现什么才值得汇报
3. 写清什么时候应该停止或请求人工确认
4. 尽量让提示词对未来多次运行都成立

2. 技能化提炼

我有一类重复出现的任务，想把它沉淀成技能。
请先帮我判断：
1. 它适不适合写成技能
2. 触发条件该怎么写
3. 说明型技能就够了，还是需要脚本
4. 如果做成技能，最小版本应该长什么样

3. 自动化前验证

请先不要创建自动化。
先帮我检查这段自动化提示词是否足够稳定。

请重点判断：
1. 是否写清了目标
2. 是否写清了停止条件
3. 是否容易误报或漏报
4. 是否需要加入人工确认环节

怎样按角色混合使用这些模板

真实工作里，你往往不会只属于一个角色。

例如：

• 前端负责人：通常要混合使用"前端模板 + Reviewer 模板"
• 技术写作者：通常会混合使用"文档模板 + openai-docs 校对模板"
• 带团队的工程师：通常要混合使用"开发模板 + 团队模板 + 自动化模板"

最稳的做法不是追求一个"万能提示词"，而是：

1. 先选一个主角色模板
2. 再补一段当前任务特有的约束
3. 最后补上验证和交付要求

提示词升级的三步法

如果你发现某个模板已经比较好用，可以按下面三步持续升级：

第一步：从一次性提示词变成固定骨架

把经常重复写的部分抽出来，保留：

• 任务目标
• 常见约束
• 最低验证要求

第二步：从个人模板变成团队模板

把只适合你个人的表述，改成团队都能理解和接受的说法。

例如把：

• "按我平时的写法来"

改成：

• "遵循当前仓库已有模式和命名风格"

第三步：从团队模板变成技能或自动化输入

当某一类任务已经足够稳定，就可以继续升级为：

• AGENTS.md 中的团队规则
• 某个技能的标准入口
• 某个自动化任务的耐久提示词

提示词调优前后对照示范

这一节的目标不是再给你更多模板，而是让你看到：同一个任务，提示词写法不同，结果稳定性会差很多。

下面所有示范都采用同一种思路：

1. 先看原始提示为什么容易跑偏
2. 再看优化后的写法
3. 最后总结这次优化到底补了什么

示例一：从"帮我改一下"到"最小改动实现"

原始提示：

帮我把这个页面改一下。

为什么容易跑偏：

• 没说改哪里
• 没说想达到什么效果
• 没说能不能改结构
• 没说怎么验证

优化后：

请按最小改动原则优化这个页面的首屏信息层级。
目标：
1. 让主标题更突出
2. 让主按钮更容易被看到

要求：
1. 先复用现有组件和样式体系
2. 不改无关业务逻辑
3. 如果需要明显改布局，先告诉我影响面
4. 完成后说明改了哪些文件
5. 告诉我桌面端和移动端如何验证

这次优化补了什么：

• 明确了目标
• 限定了改动范围
• 增加了停止条件
• 增加了验证要求

示例二：从"修一下 bug"到"先定位再修"

原始提示：

修一下这个 bug。

为什么容易跑偏：

• Codex 不知道你是要它先定位，还是直接尝试修改
• 它可能会做表面修补，而不是找根因

优化后：

请先不要直接修改代码。

问题现象：
[在这里写复现现象]

请先完成下面几件事：
1. 定位最可能相关的文件和调用链
2. 给出最可能的根因候选
3. 说明最小修复方案
4. 说明修复后该如何验证

确认分析后，再进入修改。

这次优化补了什么：

• 把任务拆成"定位"和"修复"两个阶段
• 避免一上来盲改
• 让你在改动前就能判断方案质量

示例三：从"大需求一把做完"到"小批次推进"

原始提示：

把用户中心重构一下，顺便把交互也优化了，再补全测试。

为什么容易跑偏：

• 同时混入了重构、交互优化、测试补全三个目标
• 任务太大，很难 review
• 很难判断做到哪一步算完成

优化后：

/plan
我要优化用户中心，但先不要直接开始大改。

请先：
1. 把这个任务拆成 3 到 5 个小步骤
2. 标出哪些属于结构改动，哪些属于 UI 改动，哪些属于测试补全
3. 说明建议先做哪一步，以及为什么
4. 给出每一步的验证方式

然后第一轮执行只给它一小步：

先只执行第一步。
要求：
1. 不提前做后面的重构
2. 改完后先给我看 diff 和验证方法
3. 我确认后再做下一步

这次优化补了什么：

• 先拆任务
• 再分批执行
• 把 review 环节前置

示例四：从"帮我写文档"到"按读者对象写文档"

原始提示：

帮我写一下这个模块的文档。

为什么容易跑偏：

• 不知道给谁看
• 不知道写到什么深度
• 不知道要不要补背景、限制和示例

优化后：

请基于当前代码和现有说明，为"第一次接手这个模块的开发者"整理一份文档。

要求：
1. 先解释模块用途
2. 再解释主要入口、调用流程和依赖关系
3. 写清运行前提、限制和常见坑
4. 不要编造代码里没有体现的能力
5. 如果信息不足，明确标记待确认项

这次优化补了什么：

• 明确了读者对象
• 明确了写作层次
• 加入了"禁止编造"和"待确认项"

示例五：从"帮我 review"到"按风险层级 review"

原始提示：

帮我 review 一下这次改动。

为什么容易跑偏：

• 不知道你更关心风格、Bug、测试还是架构
• 结果可能变成泛泛而谈

优化后：

请把自己切换到代码审查模式，基于当前 diff 做 review。
先不要直接修改代码。

请重点看：
1. 行为回归风险
2. 边界条件和错误处理
3. 是否缺少测试
4. 是否改动了不必要的文件

输出要求：
1. 按高风险、中风险、低风险分类
2. 每条都说明原因
3. 如果没有明显问题，也要说明剩余风险或验证缺口

这次优化补了什么：

• 指定了 review 视角
• 指定了输出结构
• 避免得到模糊评价

示例六：从"做个自动化"到"耐久提示词"

原始提示：

帮我做个自动化，每天看看项目有没有问题。

为什么容易跑偏：

• "有没有问题"太模糊
• 没写清发现什么才值得汇报
• 没写清什么时候应停止或请求人工确认

优化后：

请帮我设计一个每天运行一次的项目巡检自动化提示词。

巡检目标：
1. 检查最近一次构建是否失败
2. 检查最近是否有新的高优先级 PR 评论
3. 检查是否有未处理的关键报错线索

要求：
1. 只在发现值得人工关注的问题时汇报
2. 没有发现时允许静默结束
3. 如果需要改文件、发消息或执行高风险动作，先停下来请求人工确认
4. 请同时输出人工线程版和自动化耐久版两份提示词

这次优化补了什么：

• 明确了巡检目标
• 加上了汇报门槛
• 加上了停止条件
• 让提示词更适合长期重复运行

一眼判断提示词还缺什么的方法

如果你写完一条提示词，想快速判断它还缺不缺关键条件，可以用下面这 7 个问题自查：

1. 我有没有写清最终目标？
2. 我有没有写清当前范围？
3. 我有没有告诉它什么不能乱动？
4. 我有没有说明先分析还是直接执行？
5. 我有没有写清验证方式？
6. 我有没有写清交付要求？
7. 我有没有写清什么时候应该停下来等我确认？

如果这 7 个问题里有 3 个以上答不上来，这条提示词大概率还不够稳。

发布前检查

除了检查代码本身，提示词也值得做一次"发布前检查"：

• 目标是否单一
• 范围是否清楚
• 是否写明了不要改什么
• 是否写明了验证方式
• 是否写明了输出要求

• 是否区分了"先分析"还是"直接执行"

• 只改必要文件

• 没有无关重构
• 测试或 build 至少跑了一轮
• 审查区已看过
• commit message 和 PR 描述清晰

怎样让模板真正产生效果

模板不是为了让提示词看起来"更专业"，而是为了避免遗漏真正影响结果的条件。你越能稳定表达这五件事：

• 做什么
• 看哪里
• 不能改什么
• 怎样算完成
• 最后要交什么

Codex 的表现通常就越稳定。

本章内容主要借鉴了哪些思路

本章的结构主要综合了三类来源：

1. 官方 Codex 指南

• 强调 Goal / Context / Constraints / Done when
• 强调复杂任务先 plan
• 强调把任务拆小，并要求可验证

2. 官方 Prompt 指导

• 不要堆太多绝对化规则
• 只提供完成任务所需的最小充分信息
• 把成功标准和停止条件写清楚

3. 社区高质量实践

• 先理解后执行
• 小批次推进
• 每轮都 review 和验证
• 把文档、测试、回归检查纳入闭环

这也是为什么本章不是只给你"万能咒语"，而是更强调任务节奏和边界表达。

练习任务与教学建议

推荐的三层练习

如果你已经读过提示词模板与清单，这里推荐你不要随机练习，而是先按自己的角色选择模板：

• 开发者优先练"项目接手型、Bug 定位型、小功能实现型"
• 前端用户优先练"视觉问题修复、页面检查型"
• 文档用户优先练"说明文档型、教程改写型"
• 团队负责人优先练"代码审查型、团队模板整理型"

第一层：低风险练习

适合第一次体验。

推荐任务：

• 改按钮文案
• 补一条文档说明
• 修一个稳定复现的小显示问题

训练重点：

• 学会写目标、范围和验证方式
• 学会打开审查区（Review）看 diff
• 学会在终端里完成一次验证

第二层：标准开发练习

适合已经完成第一次闭环之后。

推荐任务：

• 给列表页增加一个筛选条件
• 补一条测试
• 修一个跨两三个文件的小问题

训练重点：

• 学会先 /plan
• 学会拆分回合
• 学会用 inline comment 收敛修改

第三层：协作与交付练习

适合准备在团队里推广使用。

推荐任务：

• 在 Worktree 中并行推进一个独立功能
• 基于改动生成 commit message 和 PR 描述
• 模拟处理一轮 review comments

训练重点：

• 学会做结果审核
• 学会管理线程边界
• 学会把 Codex 纳入正式交付流程

带新人时怎么教更有效

如果你要把这本书用于内部培训，最推荐的方式是：

1. 先讲线程、项目和审查区这三个最重要的概念
2. 现场演示一次"先 /plan 再实施"的完整回合
3. 让每个人在自己的小项目里完成一次低风险练习
4. 再统一复盘：哪里提问不清、哪里 diff 失控、哪里没验证

更好的讲法是，不只演示"正确提示词"，还要演示：

• 一个普通但容易跑偏的提示词
• 再现场把它改写成更稳的版本

这样新人会更容易真正理解"为什么提示词会影响结果"，而不是只记住几个模板句子。

一套可复用的教学目标

如果作为培训教材，可以把学习目标设成下面这五条：

• 能独立打开一个项目并创建线程
• 能给出一条结构清楚的提示词
• 能在复杂任务前主动使用 /plan
• 能在审查区中检查并反馈修改
• 能在终端中完成一次验证并说明结果

常见问题与翻车点

常见问题

• 无法登录：检查登录方式、浏览器授权和网络限制
• 看不到项目文件或不能修改：检查目录、权限和沙箱边界
• 审查区（Review）没有内容：检查是否是 Git 仓库、是否有改动
• 改动越来越乱：通常是线程承担了太多目标，或没有及时收敛范围

排查思路：先看哪一层出了问题

很多问题都可以按下面这条顺序排查：

1. 目录对不对
2. 项目环境能不能正常运行
3. 权限边界是不是限制了动作
4. 线程目标是不是过大
5. 是否缺少审查或验证步骤

如果你能分清问题究竟属于哪一层，处理速度会快很多。

最常见的 6 个翻车点

• 把它当聊天框
• 不做规划就开改
• 只看回复不看 diff
• 一个线程塞太多目标
• 一开始权限过大
• 没验证就准备发布

每个翻车点的应对方式

把它当聊天框

应对方式：强制自己每次都看审查区和内置终端，不只看线程回复。

不做规划就开改

应对方式：复杂任务先 /plan，先讲方案再开始执行。

只看回复不看 diff

应对方式：把审查区作为"任务是否完成"的必经步骤。

一个线程里塞太多目标

应对方式：正如《前言》中所说，一个线程只做一件事，拆线程，一个线程只做一类任务。

一开始权限过大

应对方式：正如《核心概念》中所建议的，先保守权限再放宽。

没验证就准备发布

应对方式：至少跑一轮最基本的测试、build 或手动验证。

命令与代码核验说明

一、本书对"可运行"的定义

在这本书里，"可运行"分成三层：

1. 产品内调用方式正确
2. CLI 命令在官方文档和本机环境中存在
3. 项目相关命令必须以当前仓库真实配置为准

这三层缺一不可。

二、已经核验过的线程输入类写法

下面这些内容不是 shell 命令，而是应该输入到 Codex 线程中的内容：

• /plan
• $skill-creator
• $skill-installer <skill-name>
• @plugin-creator

这些写法已经按 Codex 官方手册中的 Codex app commands、Skills、Build plugins 相关章节核对。

三、已经核验过的 CLI 命令

下面这些命令已在本机 Codex CLI 中确认存在：

codex --help
codex plugin marketplace --help
codex plugin marketplace list
codex plugin marketplace add <source>
codex plugin marketplace upgrade
codex plugin marketplace remove <marketplace-name>

说明：

• 这些命令属于系统终端命令
• 适合在 macOS Terminal、Linux shell 或 Codex 内置终端中执行
• 其中带占位符的写法，需要把 <source>、<marketplace-name> 换成实际值

四、必须按项目实际情况确认的命令

下面这些命令虽然常见，但并不保证在每个项目都存在：

• npm test
• pnpm test
• npm run build
• pytest
• go test ./...
• cargo test

它们是否能运行，取决于：

• 当前项目是否使用对应语言或工具链
• 项目是否真的定义了相关脚本
• 当前机器是否已安装对应依赖

所以本书统一建议：

1. 先让 Codex 读取 package.json、pyproject.toml、Makefile、go.mod、Cargo.toml 等文件
2. 先确认当前项目真实存在的启动、测试、构建命令
3. 再在终端执行

五、代码片段的使用原则

书中的代码片段主要分三类：

1. 结构示例

例如插件目录结构：

my-first-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

这类内容的目标是说明结构，不是直接复制后立刻运行。

2. 最小可用模板

例如技能最小骨架：

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

在这里写技能给 Codex 的说明内容。

这类模板可作为起点使用，但需要替换成你的真实名称和描述。

3. 可直接执行的 shell 片段

例如：

mkdir -p my-first-plugin/.codex-plugin
mkdir -p my-first-plugin/skills/hello

这类片段默认采用 macOS / Linux shell 写法。Windows 用户需要根据 PowerShell 语法做适配。

六、本书后续修订原则

从这一版开始，全书中所有命令和代码都按下面标准修订：

• 能核验的，尽量核验到官方文档或本机 CLI
• 不能对所有项目通用的，不再写成"默认可直接运行"
• 属于线程输入、插件调用、shell 命令的，明确标注输入位置

核验基准时间：

• 官方文档核验日期：2026-06-10
• 本机 CLI 核验日期：2026-06-10

术语表

项目（Project）

Codex 当前工作的目录边界。你打开哪个目录，它就主要围绕那个目录看文件、改文件、跑命令。

线程（Thread）

一条持续推进的任务对话上下文。一个线程最好只对应一个明确目标。

本地模式（Local）

直接在当前项目目录中工作。

工作树模式（Worktree）

基于 Git worktree 创建出的隔离工作副本，适合并行任务和试验性改动。

云端模式（Cloud）

在远程环境中执行任务，而不是直接运行在当前本机环境。

审查区（Review）

桌面端里的改动审查区域，用来看 diff、加批注、收敛范围和决定哪些结果值得保留。

内置终端（Terminal）

内置终端，用于运行测试、构建、脚本、Git 命令和验证流程。

技能（Skill）

可复用的任务套路或工作流。

插件（Plugin）

一组能力的集合，通常包含技能、工具或其他扩展能力。

MCP

连接外部数据与动作的协议层，让 Codex 能接入外部系统和上下文。

Apps / Connector

连接外部产品或数据源的应用入口，例如 GitHub、Google Drive、Documents、Spreadsheets 等。它更偏“接到哪里”，技能更偏“怎么做事”。

Sandbox

限制 Codex 能读取、修改和执行哪些内容的安全边界。新手建议先保持默认或较保守权限。

Approval policy

决定 Codex 在执行高风险操作前是否需要向你确认的策略。权限越大，越需要明确审批边界。

In-app Browser

Codex 桌面端内置的浏览器视图，适合本地开发页、文件预览和无需登录的公开页面。

Chrome Extension

让 Codex 与你的 Chrome 浏览器协作的能力，适合需要登录态、Cookie、扩展或现有浏览器环境的页面。

Computer Use

让 Codex 看见并操作图形界面的能力，适合桌面应用、模拟器、后台管理界面等无法只靠命令行完成的任务。

Artifact

Codex 生成或预览的结果对象，例如报告、图表、页面、文件预览等，用于让交付物更容易检查。

AGENTS.md

项目级或团队级指令文件，用来写入编码规范、常用命令、审查标准和项目约束。

.codexignore

用于排除敏感文件或无关文件的忽略配置，帮助收紧 Codex 的读取和修改范围。

自动化（Automation）

定时或持续触发的任务，用于重复性检查、报告或跟进。

CSS 主题说明

主题文件

• 文件位置：.obsidian/snippets/codex-book-theme.css
• 适用范围：本项目内所有 Markdown 笔记

如何启用

1. 打开 Obsidian 设置 → 外观 → CSS 代码片段
2. 点击文件夹图标，确认 codex-book-theme.css 所在的 snippets 文件夹已被识别
3. 在代码片段列表中，找到 codex-book-theme 并开启右侧开关
4. 切换回任意笔记页面，主题即刻生效

主题设计目标

• 优化长文档的行间距和段间距，减少阅读疲劳
• 调整标题层级的大小比例，使章节结构更清晰
• 优化表格、代码块和引用块的视觉样式
• 为 Mermaid 图表和嵌入图片提供适当的间距

自定义调整

如果你希望微调主题样式，可以直接编辑 codex-book-theme.css 文件。修改保存后，Obsidian 会自动热更新。

参考资料

官方文档

• Codex Quickstart
• Codex App Overview
• Codex App Features
• Codex App Settings
• Codex App on Windows
• Codex In-app Browser
• Codex App Commands
• Codex Automations
• Using Codex with your ChatGPT plan
• Codex Prompting Guide
• Codex Best Practices
• Codex Skills
• Codex Plugins
• Building Plugins
• Prompt Engineering Guide
• Prompt Guidance
• Codex Prompting Cookbook (GPT-5)
• Build AI-Native Engineering Team

外部教程

• 掘金：Codex 桌面工作流完整指南
• GitHub：AI-Coding-Guide-Zh / Codex App 桌面工作流完整指南
• Substack：Complete Beginner's Guide to OpenAI Codex
• Dev.to：Complete Beginner to Advanced Guide to ChatGPT Codex
• Reddit：My Workflow for Building an App with Codex