Codex 提示词 | 线程与上下文
你通过发送提示词，也就是用户消息，与 Codex 交互，告诉它你希望完成什么。
提示词
示例提示词：
解释 transform 模块是如何工作的，以及其他模块如何使用它。新增一个命令行选项
--json，让它输出 JSON。
当你提交提示词后，Codex 会在一个循环中工作：先调用模型，然后执行模型输出所指示的动作，例如读文件、改文件、调用工具等。这个过程会在任务完成或你主动取消时结束。
让提示词更有效
和 ChatGPT 一样，Codex 的效果很大程度上取决于你给出的指令。以下是经过验证的实践建议：
1. 提供可验证的完成标准
当 Codex 能验证自己的工作时，它通常会产出更高质量的结果。尽量提供：
- 问题复现步骤（"在 X 页面点击 Y 按钮，预期 Z 但实际 W"）
- 功能验证方法（"完成后运行
pnpm test -- --filter=auth"） - lint、pre-commit checks 之类的检查要求（"确保
pnpm lint无新增 warning"）
| 提示词质量 | 示例 | Codex 反应 |
|---|---|---|
| ❌ 模糊 | "优化这个页面" | 追问"优化什么？性能？UI？" |
| 🔶 有方向 | "首页加载太慢，看看能不能优化" | 会分析性能，但不确定范围 |
| ✅ 可验证 | "首页 LCP 3.2s，目标降到 2.5s 以下。用 web-vitals 测量，不改 Hero 区域的图片" | 直接分析瓶颈，输出优化方案 |
2. 拆分复杂任务
当你把复杂任务拆成更小、更聚焦的步骤时，Codex 的表现通常更好。较小的任务更容易让 Codex 测试，也更容易让你审查。
| 策略 | 适用场景 | 示例 |
|---|---|---|
| 直接描述 | 任务简单明确 | "修复 login.tsx 中的类型错误" |
| 拆成步骤 | 任务涉及多个文件 | "先分析 auth 模块结构，再重构 middleware，最后补测试" |
| 让 Codex 先规划 | 你不确定该怎么拆 | "我想重构 checkout 流程，请先给出拆分方案" |
如果你不确定该怎么拆，可以直接让 Codex 先提出一个计划——用 /plan 命令或者在提示词中说"先给出计划，确认后再实现"。
3. 给出上下文，而不只是指令
Codex 不知道你脑子里在想什么。把背景信息、约束条件、期望行为写进提示词，比让 Codex 猜要好得多。
❌ "重构这个函数"
✅ "把 src/utils/date.ts 中的 formatDate 函数从 moment.js 迁移到 dayjs。
保持公共 API 不变，现有 12 个测试必须继续通过。
不要改其他文件。"
关于如何向 Codex 写提示词的更多思路，参见 工作流。
提示词写得好不好，核心指标不是"够不够详细"，而是信息密度够不够高。一句话包含目标 + 范围 + 约束 > 三段话只说了目标。结构化模板见 高质量任务描述模板。
线程
线程，就是一次会话：包括你的提示词，以及之后的模型输出与工具调用。一个线程可以包含多条提示词。例如，第一条提示词让 Codex 实现某个功能，后续提示词再让它补测试。
当 Codex 正在积极处理某个线程时，这个线程就处于"运行中"。你可以同时运行多个线程，但应避免让两个线程修改同一批文件。你也可以稍后继续向同一个线程追加提示词，从而恢复它。
三种线程模式
线程既可以在本地运行，也可以在云端运行，还可以是不绑定项目的聊天：
| 模式 | 运行位置 | 能读写文件 | 能运行命令 | 适用场景 |
|---|---|---|---|---|
| 本地线程 | 你的机器 | ✅ | ✅ | 日常开发、需要直接看到改动 |
| 云端线程 | 隔离的云端环境 | ✅（克隆仓库） | ✅ | 耗时任务、并行任务、跨设备 |
| 聊天 | Codex 管理的目录 | ❌（不绑定项目） | ❌ | 研究、规划、连接工具 |
本地线程
运行在你的机器上。Codex 可以读取和编辑你的文件，也可以运行命令，因此你可以直接看到有哪些改动，并继续使用你现有的工具。为了降低工作区之外发生意外改动的风险，本地线程会运行在沙箱中。
选择本地线程的信号：
- 你需要实时看到文件变化
- 任务需要频繁和你的本地环境交互（数据库、本地服务）
- 你想边做边审查 Codex 的改动
云端线程
运行在隔离的环境中。Codex 会克隆你的仓库，并检出它正在工作的分支。当你想并行运行任务，或从另一台设备委派任务时，云端线程特别有用。
选择云端线程的信号：
- 任务耗时较长（>10 分钟），你不想被阻塞
- 你想同时跑多个独立任务
- 你在手机/平板上，想从另一台设备委派任务
若要使用云端线程，请先把代码推送到 GitHub。你也可以从本地机器把任务委派到云端，此时会连同你当前的工作状态一起带过去。
聊天
在 Codex App 中，你也可以不选择项目，直接开始一次聊天。聊天不会绑定到已保存的仓库或项目文件夹，适合研究、规划、连接工具的工作流，或其他不希望 Codex 从代码库开始的任务。
聊天会使用 Codex 管理的 threads 目录作为工作位置；默认位置是 ~/.codex/threads。若要修改这类状态的基础目录，请设置 CODEX_HOME；参见配置与状态位置。
线程选择决策表
| 你的情况 | 推荐模式 | 理由 |
|---|---|---|
| 日常开发，边做边看 | 本地线程 | 直接看到改动，实时反馈 |
| 修一个有明确复现步骤的 Bug | 本地线程 | 需要运行本地测试验证 |
| 多文件重构，方向已明确 | 云端线程 | 不阻塞你的工作 |
| 同时改 3 个不相关的模块 | 3 个云端线程 | 并行效率最高 |
| 调研技术方案，不涉及代码 | 聊天 | 不需要访问代码库 |
| 规划一个复杂任务的步骤 | 聊天或本地 /plan | 先想清楚再动手 |
上下文
提交提示词时，尽量一并附上 Codex 可用的上下文，例如相关文件和图片的引用。Codex IDE 扩展会自动把当前打开的文件列表和选中的代码范围带入上下文。
上下文的来源
| 来源 | 如何提供 | 适用场景 |
|---|---|---|
| 文件引用 | @src/features/auth/middleware.ts | 让 Codex 看特定文件的代码 |
| 图片 | 直接粘贴截图到输入框 | UI 实现、设计稿还原、Bug 截图 |
| 选中代码 | IDE 中选中文本后发起提示 | 针对特定代码段提问或修改 |
| 当前打开的文件 | IDE 自动带入 | 编辑器和 Codex 联动 |
| 对话历史 | 自动累积 | 多轮对话中 Codex 记住之前的约定 |
| 工具输出 | Codex 执行命令的结果 | 调试、测试、构建信息 |
当智能体工作时，它也会不断从文件内容、工具输出，以及自己已经做过什么、还要做什么的持续记录中收集上下文。
上下文窗口管理
线程中的所有信息都必须落在模型的上下文窗口内，而这个窗口大小会随着模型不同而变化。Codex 会监控并显示剩余空间。
| 现象 | 原因 | 应对 |
|---|---|---|
| Codex 开始"遗忘"早期约定 | 上下文窗口快满了 | 开新线程，把关键约定重新说明 |
| Codex 响应变慢 | 上下文太长 | 精简上下文，移除不相关的文件引用 |
| Codex 自动压缩了早期对话 | 长任务的正常行为 | 如果压缩丢失了关键信息，在新线程中重新提供 |
对于较长任务，Codex 可能会自动通过总结相关信息、丢弃次要细节的方式来压缩上下文。通过反复压缩，Codex 可以在多步骤过程中持续处理复杂任务。
上下文不是越多越好。 一次性 @mention 20 个文件会让 Codex 不知道该重点看哪个。只引用和当前任务直接相关的信息。上下文管理的系统方法见 从提示词到上下文工程。
Goal mode
Goal mode 会给 Codex 一个可持续追踪的目标，适合步骤较多的长任务，或需要 Codex 在执行过程中反复对照"完成标准"的任务。
设置目标后，目标文本同时充当起始提示词和完成标准。Codex 会用它判断下一步该做什么，以及任务是否已经完成。你可以在 Codex App、IDE 扩展或 CLI 中用 /goal 启动 Goal mode。
启动 Goal mode
如果斜杠命令列表里没有 /goal，请在 config.toml 中启用 features.goals：
[features]
goals = true你也可以从 CLI 运行 codex features enable goals，或直接让 Codex 帮你运行。
在 Codex App 中，目标进度会显示在输入框上方，并提供暂停、恢复、编辑或清除目标的控件。
写好目标的关键
目标应写到 Codex 能判断是否成功为止。 好的目标通常包含具体产出、可衡量指标或测试标准。
| 目标质量 | 示例 | 问题 |
|---|---|---|
| ❌ 模糊 | "优化代码" | Codex 无法判断什么时候算"优化完了" |
| 🔶 有方向 | "重构 auth 模块" | 不知道重构到什么程度 |
| ✅ 可验证 | "将 auth 模块从 JavaScript 迁移到 TypeScript，strict 模式编译通过，无显式 any" | Codex 可以自检 |
| ✅ 可衡量 | "首页 TTI 降到 1 秒以下" | Codex 可以用工具测量 |
更多好目标的例子：
Migrate this codebase from JavaScript to TypeScript. The app should compile in strict mode without explicit
anytype definitions.
Reduce the time to interactive of the home page to below 1 second.
将用户设置页的通知偏好从全局开关改为按类型独立配置（email / push / inApp），
pnpm test -- --filter=settings全部通过，375px / 768px / 1440px 三个断点无布局问题。
目标写不出来怎么办？
如果目标一开始很难定义，可以先用 /plan，让 Codex 在实现前帮你整理目标。你也可以要求 Codex 先向你追问，再起草一条带有明确成功标准的目标。
# 示例：让 Codex 帮你起草目标
我想优化首页性能，但不确定从哪开始。
请先分析当前性能瓶颈，然后帮我起草一个带有明确指标的目标。
Goal mode 中的持续引导
目标启动后，你仍然可以继续引导 Codex。后续消息可以补充约束，例如要求使用某个库，或避免某种方案。
| 操作 | 适用场景 |
|---|---|
| 追加提示词 | 补充约束或调整方向 |
| side chat | 问问题或要求解释，不打断主任务 |
| 暂停目标 | 你要断开连接（通勤、吃饭等） |
| 恢复 / 编辑目标 | 准备好继续时 |
对于长时间运行的工作，如果你即将断开连接，请先暂停目标。直接离开可能导致 Codex 在没有你审查的情况下做出不可逆的改动。
常见错误与反模式
| 反模式 | 问题 | 改进 |
|---|---|---|
| 一句话指令 | "重构这个模块"——Codex 不知道范围和约束 | 加上范围、约束、验证标准 |
| 上下文轰炸 | @mention 20 个文件——Codex 注意力分散 | 只引用直接相关的文件 |
| 无限续线程 | 30+ 轮对话——上下文膨胀，Codex "遗忘"早期约定 | 关注上下文余量，必要时开新线程 |
| 没有验收标准 | "做完了"≠"做对了" | 每条任务至少一条可验证的完成标准 |
| Goal mode 不设标准 | "优化性能"——Codex 无法判断何时完成 | 写可衡量的指标 |
验证清单
- 你的提示词包含目标、范围、验证标准（至少三要素）
- 你知道当前任务应该用本地线程、云端线程还是聊天
- 你只 @mention 了和当前任务直接相关的文件
- 长任务会关注上下文窗口的剩余空间
- Goal mode 的目标包含可判断是否成功的标准
FAQ
Q：提示词用中文还是英文？
都可以。Codex 对中英文的理解能力相当。建议：提示词用你团队的工作语言——如果代码注释和文档是中文，提示词也用中文，保持一致性。
Q：一个提示词能做多少事？
建议一个提示词只做一件事。如果你发现自己在提示词中用了"然后"、"接着"、"同时还要"，说明任务该拆了。拆分后的多轮对话比一条超长提示词效果更好。
Q：Codex 没按我说的做怎么办？
先检查三件事：① 提示词中的指令是否足够明确（不是"优化"而是"把 LCP 降到 2.5s 以下"）；② 是否有约束条件遗漏（"不要改 X 文件"是否写了）；③ 上下文是否充分（相关代码是否 @mention 了）。如果都没问题，尝试在提示词开头加一句"请严格按照以下要求"。
平台能力、套餐限制以 OpenAI Codex 官方文档为准；本文写于 2026-06-24。
选读建议：掌握了提示词基础概念后，下一步是学会用结构化模板写任务描述——→ 高质量任务描述模板。如果你想先看看真实场景中提示词怎么用——→ 提示词实战案例库。