codex30分钟掌握Codex的97%功能(完整教程)

30分钟掌握Codex的97%功能(完整教程)

微信：taiyang54541

Codex 是 OpenAI 推出的 AI 编程助手——不是2021年那个已经停用的代码补全 API，而是全新的版本。它在2025年4月以命令行工具（CLI）的形式首次发布，随后发展出桌面应用、VS Code/Cursor/Windsurf 的 IDE 插件，以及云端版本。

Sam Altman 在2026年4月透露，Codex 已经拥有约400万周活跃用户。它现在是 Claude Code 最直接的竞争对手。

如果你用过 Claude Code，可以用一句话理解 Codex：本地的一个文件夹 + 一个 markdown 配置文件 + 一个能读取所有文件的 AI 智能体 + Skills（技能）、MCP 服务器、自动化任务和内置浏览器。

不同的工具外壳，不同的模型，但核心理念相同。

14个步骤。3个层次。一个文件夹搞定所有工作流。

第一部分 · 基础设置

01. 在电脑上创建项目文件夹

Codex 没有自己的数据库、文件系统或“工作区”。一个 Codex 项目，就是你电脑上的一个普通文件夹。当你新建项目时，Codex 会让你选择一个文件夹。

选好文件夹后，里面的所有文件都可以被 Codex 自由操作：读取、写入、编辑、整理、移动。

这个简单的设计带来了巨大的灵活性：

  • 项目完全可移植。 同一个文件夹可以在 Codex CLI、Codex 桌面应用、VS Code/Cursor/Windsurf 的 IDE 插件中打开——甚至可以用 Claude Code 或 Cursor 打开。工具换了，项目内容不变。

  • 可以像管理代码一样做版本控制。 Git、GitHub、Vercel——都是标准工具，不需要特殊集成。

  • 备份、分享、迁移都很简单，就像操作普通文件夹一样。

\

Codex 默认以智能体模式运行——它可以自动读取、编辑和运行工作目录内的命令。文件夹外的内容以及网络访问仍需要你的批准。文件夹就是信任边界。

02. 编写AGENTS.md** 配置文件** ：Codex 启动时首先读取的文档

这是 Codex 中最被低估的文件。AGENTS.md 放在项目根目录，每次你在该文件夹中打开新对话时，Codex 都会读取它。

它会告诉 AI 智能体：你是谁、项目是什么、目标是什么、有哪些限制条件。

小技巧：不要从头写。 用简单的话告诉 Codex 你的项目目标，让它帮你起草一个 AGENTS.md。你会得到一个结构完整的文件，然后再根据需要修改。这样更快、更完整、不容易遗漏。

plaintext

# 项目：YouTube评论智能分析

## 背景
我运营一个关于AI工具的YouTube频道。我想了解
观众在问什么、他们想看什么、他们在比较什么工具——
而不用手动阅读每条评论。

## 目标
构建一个工作流，提取最近的评论、对其分类、
发现模式，并在实时仪表板上可视化结果。

## 约束条件
- 使用YouTube Data API v3和API密钥（不用OAuth）。
- 将凭证保存在.env.local中，永远不要提交到代码仓库。
- 输出目标：用于分析的Excel工作簿 + Web仪表板。
- 将仪表板部署到Vercel。
- 通过自动化每周刷新数据。

## 工作习惯
- 将失败的方法保存到项目记忆中，避免重复犯错。
- 在编写代码之前始终确认计划。

一个好的 AGENTS.md 应该包含：

  • 背景——一段话。 你是谁、为什么做这个项目。这样就不用每次对话都重新解释。

  • 目标——一段话。 描述最终状态，而不是具体步骤。步骤属于计划模式（步骤3）。

  • 约束条件——列表形式。 硬性规则。比如 API 选择、要避免的语言、安全边界、输出格式。越简短具体越好。

  • 工作习惯——列表形式。 比如“将经验教训保存到记忆中”、“始终先确认计划”、“永远不要运行 X”。这些会累积成可靠的工作模式。

OpenAI 官方的最佳实践指南明确指出：“当你把 Codex 当作一个可以配置和持续改进的队友，而不是一次性助手时，Codex 效果最好。从正确的任务背景开始，使用 AGENTS.md 进行持久指导，配置 Codex 以匹配你的工作流。”

03. 每次构建都先用计划模式

计划模式意味着 Codex 不会立即执行。它会先头脑风暴、提出澄清问题、展示不同方案的权衡，然后生成一个编号计划供你在写代码之前审批。跳过计划模式是项目出错的最大原因。

有效的使用方法：

  • 描述目标，而不是步骤。 比如“从我的 YouTube 频道提取最近的评论并生成 Excel 报告”——而不是“用 Python 调用 YouTube API 然后写入 xlsx”。

  • 让它提问。 计划模式下的 Codex 通常会返回3-5个澄清问题。认真回答它们。每个问题都能帮你避免未来的 bug。

  • 执行前先批准计划。 仔细阅读步骤。如果发现问题——比如缺少边界情况处理、工具选择不当、不必要的复杂性——及时提出。在计划阶段修改比写完代码再改要省事得多。

计划模式与 AGENTS.md 配合效果特别好：配置文件中的约束条件会影响 Codex 提出的方案。两者结合可以大幅减少错误尝试。

04. 用 .env.local 管理 API 密钥

所有 API 密钥、秘密、凭证都要放在项目根目录的 .env.local 文件中。文件名前面的点不是装饰——这是告诉 Codex（和 git）要把这个文件排除在公开提交之外。

防止泄密的两条铁律：

  • 永远不要把密钥粘贴到随意命名的 secrets.txt 中，更不要直接粘贴到聊天消息里。这两种做法最终都会进入版本控制。一旦你推送代码，密钥就公开了。

  • 添加密钥后立即测试。 让 Codex 做一个最小的 API 调用来确认密钥有效。在它影响整个构建之前发现认证错误。

如果密钥真的不小心提交了，立即去服务提供商（Google Cloud、OpenAI 等）那里轮换密钥。不要只是从文件中删除然后推送删除操作——旧的提交记录里仍然有密钥，机器人会在几分钟内扫描 GitHub 提交记录来寻找泄露的秘密。唯一安全的做法是轮换凭证。

第二部分 · 连接与构建

05. 连接 MCP 服务器和插件

Codex 使用模型上下文协议（MCP）——这是一个开放标准，Claude Code 也在用。这意味着大多数现有的 MCP 服务器都可以在 Codex 中使用：GitHub、Slack、Notion、Linear、Drive、Figma，以及数十个社区开发的服务器。

这带来了什么变化：不再是向 Codex 描述你的数据，而是让它直接读取你的数据。不再是描述你想做什么操作，而是让它直接执行。对话从_“这是我代码仓库里的内容”<u>变成了</u>“用这个修复创建一个 PR 并通知负责人”_。

回报最快的三种用法：

  • GitHub MCP — 读取代码仓库、创建分支、发起 PR、评论问题。对任何开发者来说都是最直接的收益。

  • Vercel MCP — 部署、检查状态、回滚。与 GitHub 配合可以实现完整的“构建→提交→部署”循环。

  • Notion 或 Drive MCP — 提取内部文档作为上下文，将决策记录写回中央知识库。Codex 不再是黑盒，而是成为团队记忆的一部分。

06. 没有插件时，让 Codex 帮你设置 API

不是每个服务都有 MCP 服务器。YouTube Data API 没有。公司内部 API 没有。小众 SaaS 工具通常也没有。

遇到这种情况，你不需要去找第三方封装库。直接问 Codex。 在计划模式下，告诉它集成目标——比如“从我的 YouTube 频道提取最近的评论”。

它会返回不同选项（API 密钥 vs OAuth），推荐一个，然后生成分步计划来设置凭证、启用相关 API 并测试连接。

长期有效的做法：

  • 先尝试第一种方法。 Codex 会根据权衡选择一个方案。让它试。

  • 失败时记录教训。 比如“PowerShell 遇到 TLS 错误，Python 可以。把这个保存到项目记忆里，以后不要再试错误的路径。”下次对话会继承这些知识。

  • 锁定可用方案。 一旦某个集成稳定了，把它转换成 Skill（步骤9）。以后就不用重复设置了。

这是 AI 辅助工作中最重要的习惯。尝试、失败、记录失败、不再重复同样的错误。 Codex 的 AI 智能体默认只有短期记忆——它在本次对话中学到的东西明天就会忘记，除非你把它写下来。

每当遇到值得记录的经验教训时，告诉 Codex 更新 AGENTS.md 或项目记忆。 系统会越用越聪明。

07. 用具体的提示词构建真实的交付物

任何工具的价值都在于交付物。对大多数用户来说，第一个交付物通常是具体的东西——Excel 报告、自动化脚本、仪表板、生成的文档。能证明工具价值的东西。

决定第一次构建质量的关键因素：提示词的具体程度。 “分析我的 YouTube 评论”会生成一个只有“积极”、“消极”、“中性”分类的 Excel 表格，没什么用。“分析我的 YouTube 评论并按以下维度分类：工具对比、内容建议、技术问题、一般反馈——然后按回复优先级为我这个创作者排序”会生成一个你真正会用的工作簿。

快速提升输出质量的两个技巧：

  • 说明输出的用途 — “给我这个创作者用的”、“用于董事会汇报”、“给我的工程团队看的”。受众决定结构。

  • 列出你关心的分类或维度。 不要让分类依赖默认判断。告诉 Codex 你的分类体系。

如果第一版还可以但不够好，不要推倒重来。<u>增加更多细节然后重新运行。</u> 用更清晰的提示词迭代三轮，比从头开始五次要好。

08. 构建 UI 之前先用 gpt-image-2 生成概念图

Codex 内置了图像生成功能，使用的是 gpt-image-2——OpenAI 的图像模型。在提示词中用

$imagegen

显式调用，或者直接描述你需要什么，Codex 会自动识别。

生成的图像会成为项目资源，后续构建可以引用。

解锁这个功能的方法：在写 UI 代码之前先生成概念图。 让 Codex 先用一两张图模拟仪表板的外观。保存到项目里。

然后让它构建仪表板，并引用这些概念图。最终的视觉效果会比让模型凭空根据文字描述设计要好得多。

09. 将工作流转换成 Skills（技能）

Skill 是 Codex 按需加载的可重用配方。一旦你构建了一个有效的工作流——比如提取评论、生成报告、部署仪表板——就可以把它转换成 Skill，下次运行只需一条命令。

Codex 中的 Skills 是文件夹里的 markdown 文件。目录里有一个 SKILL.md 文件，包含前置元数据（名称+描述）和指令正文。可以选择性地在旁边放脚本和参考文件。

plaintext

---
name: youtube-comment-insights
description: 通过 Data API 提取最近的 YouTube 评论，
  按内容类别和工具提及分类，
  按回复优先级排序，并输出带有
  摘要选项卡和图表的 Excel 工作簿。每当我要求
  "评论洞察"或"每周 youtube 报告"时触发。
---

# YouTube 评论洞察

## 设置
- 从 .env.local 读取 YOUTUBE_API_KEY。
- 获取最近10个视频的约200条最新评论。

## 分类
- 类别：工具对比、内容建议、技术问题、
  一般反馈、无关内容。
- 工具提及跟踪：Codex、Claude Code、Cursor、API、GPT 等。
- 优先级信号：问题 > 高互动评论 > 其他。

## 输出
- 工作簿选项卡：摘要、分类、工具提及、
  优先回复、内容创意、原始数据。
- 摘要选项卡上的图表：类别分布、工具排名。

两个值得了解的存储级别：

  • 全局 Skills — 存储在 ~/.agents/skills/。在你电脑上的每个 Codex 项目中都可用。

  • 项目级 Skills — 存储在项目文件夹内。只在该项目中可用。适合客户专属或项目专属的配方。

决定 Skill 能否在需要时自动触发的三个因素：

  • 描述就是一切。 Codex 仅根据描述文本来匹配你的任务，以便隐式调用。把关键用例和触发词放在前面；模糊的描述永远不会触发。

  • 两种调用方式。 显式调用（CLI/IDE 中的 /skills，或

    $skillname

    提及），或隐式调用（当你的提示词与描述匹配时 Codex 自动选择技能）。

  • 开放标准。 Skills 在2025年12月为 Codex 推出，现在已经是跨平台 Agent Skills 标准的一部分——相同格式可以在 Codex、Claude Code、Gemini CLI、Cursor 中使用。写一次，到处运行。

10. 将本地服务部署到线上 <u>GitHub → Vercel → 生产环境</u>

Excel 表格是后端。仪表板是前端。Localhost 是开发地址。这些都不能直接交付。

要从本地到线上，你需要连接两个服务：GitHub 用于代码仓库，Vercel 用于托管。Codex 会协调整个流程。

plaintext

> 将此项目连接到 GitHub。创建一个名为
  "yt-comments-dashboard" 的私有仓库并推送代码。
▲ Codex  使用 gh CLI 进行身份验证…
  - 创建了 github.com/you/yt-comments-dashboard（私有）
  - 初始提交已推送
✓ 仓库就绪

> 将 Vercel 连接到同一个 GitHub 账户。
  导入此仓库。部署。
▲ Codex  连接 Vercel…
  - 已创建 vercel 项目
  - 构建在38秒内成功
✓ 已上线：https://yt-comments-dashboard.vercel.app

关键细节：GitHub 和 Vercel 在初始连接后会持续通信。 每次推送到 main 分支都会触发 Vercel 自动部署。你不需要再登录 Vercel。你在 Codex 中工作，Codex 推送到 GitHub，Vercel 自动部署。三个工具，一个工作流。

11. 设置自动化任务——并明确指定模型

Codex 应用有一个自动化选项卡。可以按 cron 表达式运行定时任务。与 Skills 结合，这就是让仪表板“在你睡觉时自动更新”的方法。

一个真实的周日晚上自动化任务：提取新评论，运行洞察 Skill，更新 Excel 文件，推送新数据，让 Vercel 自动部署。端到端刷新，无需人工干预。到周一早上，仪表板已经是最新的了。

自动化面板里的模型选择器不会继承你活跃对话的设置。新建的自动化任务会使用面板的默认值，这可能比你实际想要的生产运行模型更慢更便宜。

为每个自动化任务明确设置模型，否则你会疑惑为什么原本7分钟的任务突然需要40分钟。如果你在本地打开了 Codex 需要覆盖的文件，也会出现同样的问题——先关闭它。

12. 选择正确的线程模式——Local、Worktree 或 Cloud

Codex 应用中的每个对话线程都运行在三种模式之一：

  • Local（本地） — 直接在你当前的项目目录中工作。最快、最简单，但每次更改都会影响实际的工作文件。适合小型、可控的编辑，当你信任 AI 智能体时使用。

  • Worktree（工作树） — 在 Git worktree（与同一仓库绑定的独立工作目录）中隔离更改。AI 智能体在单独的分支中工作，不会影响你的主分支。这是任何重要构建的默认选择。 如果运行出错，直接删除 worktree。零风险。

  • Cloud（云端） — 在配置的云环境中远程运行。你的笔记本电脑可以关机。将此与自动化任务（步骤11）配合，实现真正的异步工作流，不依赖你的机器在线。

经验法则：Worktree 用于重要工作，Local 用于小修小补，Cloud 用于长时间运行的自动化任务。三个信任级别，按任务选择。

13. 用内置浏览器做 QA 测试

构建完仪表板后，让 Codex 在内置浏览器中打开它，点击浏览，尝试找出问题，然后报告。它会做到。

它会发现你盯着代码看不出来的问题——失效的外部链接、看起来空荡荡的空状态、过于死板的搜索行为、可访问性缺陷、小的 UI 不一致。

把这从一次性操作变成习惯的方法：把 QA 测试写进你的项目记忆或 Skill 中。

每次你发布新功能时，AI 智能体在返回给你之前先运行浏览器测试。你不再是 QA 测试员。AI 智能体做测试。你审查报告。

不过，浏览器不仅仅用于 QA。当 API 不存在时，它就是通用工具：

  • 登录没有 API 的工具 — 传统管理面板、供应商门户、内部仪表板。

  • 从不提供编程接口的仪表板中提取报告 — 分析视图、计费工具、状态页面。

  • 自动化你原本需要手动点击的多步 UI 流程。用自然语言描述步骤；Codex 执行它们。

14. 使用大多数人忽略的 UX 功能

Codex 应用有一些 UI 功能，能让它从“我用的工具”变成“我工作的环境”。它们单独看起来很小，加在一起效果显著。

  • 侧边对话。 从主对话中打开一个侧边线程。相同的项目上下文，不同的对话。快速提问而不污染主对话。用完就关。

  • 斜杠命令。 输入 / 浏览：/skills 显式调用 Skill，/clear，/help 等。斜杠菜单展示 Codex 的所有功能。

  • @ 提及。 在提示词中标记特定文件：“参考

    @example

    .tsx 添加一个新页面，列出来自

    @resources

    .ts 的项目。”比粘贴路径干净得多。

  • 模型切换器 + 推理强度。 聊天输入框下方的切换器可以按对话切换模型。推理强度控制 Codex 响应前思考多长时间。更高的强度 = 复杂任务表现更好，消耗更多 token，更快达到速率限制。根据任务匹配强度。

  • $imagegen

    ** + Skills 提及。** 输入 $ 以内联提及技能。与 @ 用于文件的语法相同。让你在一个提示词中组合多个技能。

  • 与 IDE 扩展的自动上下文同步。 如果在编辑器中安装了 Codex IDE 扩展，当两者都在同一项目中时，应用和编辑器会自动同步。你可以在编辑器内看到应用中运行的线程，反之亦然。切换“自动上下文”让 Codex 跟踪你正在查看的文件。

  • 完全访问模式。 设置 → 切换以跳过批准提示。更快，更危险。从默认开始。只有在你信任项目边界后才切换到完全访问。

让 Codex 只发挥3%潜力的习惯

  • 没有AGENTS.md. 每次对话都重新解释项目，每次得到不同的答案。

  • 跳过计划模式。 为了修复一句话的误解，改了四十个文件。

  • 把密钥放在聊天里或 secrets.txt 里。 一推送就公开了。

  • 从不记录教训。 一遍又一遍地犯同样的错误，因为什么都没写下来。

  • 模糊的提示词。 得到通用的交付物，然后惊讶于输出为什么这么通用。

  • 一次性构建。 每周从头重建相同的工作流，而不是把它转换成 Skill。

  • 所有事情都用 Local 模式。 一次糟糕的 AI 运行清空了你的工作文件，因为你没用 worktree。

  • 让自动化任务使用默认模型。 本该7分钟的任务跑了40分钟。

  • 没有 QA 测试。 发布的仪表板有失效链接和空荡荡的空状态。

  • 工具站队。 根据身份而不是眼前的任务选择 Codex vs Claude Code。两者各有优势，取决于具体情况。

总结

Codex 看起来像一个聊天窗口。但它不是聊天窗口。它是一个带有了解内容的 AI 智能体的文件夹——加上 Skills、MCP、自动化任务和浏览器层，所有这些都通过位于文件夹内的 markdown 文件进行配置。

这个文件夹是可移植的。 在 Codex、Claude Code、Cursor 或任何支持 Agent Skills 标准的工具中打开它。工具外壳变了，工作内容不变。

大多数用户会继续在聊天框里输入问题然后止步于此。他们会得到答案、复制代码、继续前进。用 Codex 真正发挥作用的400万周活跃用户，是那些配置好文件夹的人。

选一个你没做过的步骤——可能是 AGENTS.md，或者你的第一个真正的 Skill——明天就加上。

Codex 的输出取决于 Codex 的配置。

Was this page helpful?