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

大多数人打开 Codex，看到聊天窗口，就把它当成一个界面更华丽的 ChatGPT，结果， 90%的用户都错过了它真正强大的功能。

他们 不会构建技能（Skills）， 不会部署到线上 ， 不会让自动化任务在后台运行 。本文将用14个步骤，在30分钟内带你从_空白文件夹_搭建出_完整可用的 AI 工作流_。

Codex 是 OpenAI 推出的 AI 编程助手——不是2021年那个已经停用的代码补全 API，而是全新的版本。

它在2025年4月以命令行工具（CLI）的形式首次发布，随后发展出桌面应用、VSCode/Cursor/Windsurf 的 IDE 插件，以及云端版本。

Sam Altman 在2026年4月透露，Codex 已经拥有约400万周活跃用户。

它现在是 Claude Code 最直接的竞争对手。

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

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

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

 

第一部分 · 基础设置

在电脑上创建项目文件夹

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

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

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

项目完全可移植。 同一个文件夹可以在 Codex CLI、Codex 桌面应用、VS Code/Cursor/Windsurf 的 IDE 插件中打开——甚至可以用 Claude Code 或 Cursor 打开。工具换了，项目内容不变。
可以像管理代码一样做版本控制。 Git、GitHub、Vercel——都是标准工具，不需要特殊集成。
备份、分享、迁移都很简单 ，就像操作普通文件夹一样。

 

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

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

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

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

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

# 项目：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 以匹配你的工作流。”

每次构建都先用计划模式

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

 

有效的使用方法：

描述目标，而不是步骤。 比如“从我的 YouTube 频道提取最近的评论并生成 Excel 报告”——而不是“用 Python 调用 YouTube API 然后写入 xlsx”。
让它提问。 计划模式下的 Codex 通常会返回3-5个澄清问题。认真回答它们。每个问题都能帮你避免未来的 bug。

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

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

用 .env.local 管理 API 密钥

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

防止泄密的两条铁律：

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

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

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

第二部分 · 连接与构建

连接 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 不再是黑盒，而是成为团队记忆的一部分。

没有插件时，让 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 或项目记忆。 系统会越用越聪明。

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

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

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

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

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

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

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

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

Codex 内置了图像生成功能，使用的是 gpt-image-2 ——OpenAI 的图像模型。在提示词中用 $imagegen显式调用，或者直接描述你需要什么，Codex 会自动识别。

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

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

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

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

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

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

—

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，或提及），或隐式调用（当你的提示词与描述匹配时 Codex 自动选择技能）。

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

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

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

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

> 将此项目连接到 GitHub。创建一个名为”yt-comments-dashboard” 的私有仓库并推送代码。

▲ Codex 使用 gh CLI 进行身份验证…

创建了 github.com/you/yt-comments-dashboard（私有）

初始提交已推送

✓ 仓库就绪

> 将 Vercel 连接到同一个 GitHub 账户。导入此仓库。部署。

▲ Codex 连接 Vercel…

已创建 vercel 项目

构建在38秒内成功

 

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

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

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

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

 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ 提及。 在提示词中标记特定文件：“参考.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 的配置。