许多人打开 Codex，只把它当成“能写代码的聊天框”。

这样用当然也能解决问题，但只用到了很小一部分能力。

更完整的用法是：把一个本地文件夹配置成可持续工作的 AI 项目，让 Codex 能读写文件、理解项目规则、调用 MCP、沉淀 Skills、执行自动化任务，并在浏览器里帮你做测试。

这篇文章用一个“分析 YouTube 评论并生成仪表板”的例子，带你从空文件夹开始，搭出一套能反复运行的 AI 工作流。

你会看到：

• 项目文件夹怎么建
• AGENTS.md 怎么写
• API Key 怎么放才安全
• MCP 和普通 API 怎么接
• Skills 怎么沉淀成复用流程
• GitHub、Vercel、自动化任务怎么串起来
• 常见踩坑怎么排查

1. 先理解 Codex 的工作方式

Codex 不是一个“云端项目管理器”。

它真正操作的是你电脑上的一个普通文件夹。

当你创建 Codex 项目时，本质上是在告知它：

这个文件夹是当前工作区，你可以在这里读文件、改文件、运行命令、生成脚本和整理结果。

这意味着 Codex 项目天然具备三个特点：

• 可迁移：同一个文件夹可以用 Codex CLI、桌面端、IDE 插件打开
• 可版本控制：可以直接接入 Git、GitHub、GitLab 等工具
• 可审计：所有修改都落在文件里，方便回滚和对比

这里有一个关键边界：Codex 默认信任的是当前工作目录。

如果它需要访问目录外文件、联网、执行高风险命令，一般会要求你确认。

所以，<span style='color: rgb(202,88,99); font-weight: bold;'>不要把整个桌面或用户根目录当成 Codex 项目目录。</span>

提议每个任务单独建文件夹，例如：

mkdir youtube-comment-insights
cd youtube-comment-insights

一个比较稳妥的初始目录结构可以是：

youtube-comment-insights/
├── AGENTS.md
├── .env.local
├── .gitignore
├── data/
├── scripts/
├── reports/
├── dashboard/
└── skills/

各目录的作用可以这样分：

• data/：保存原始数据或中间文件
• scripts/：放 API 拉取、清洗、导出脚本
• reports/：放 Excel、CSV、Markdown 报告
• dashboard/：放前端仪表板项目
• skills/：放项目级 Skills
• .env.local：放 API Key 等敏感配置

这一步做好，后面让 Codex 改文件、生成脚本、部署项目时，才不会混乱。

2. 写好 AGENTS.md，让 Codex 记住项目规则

AGENTS.md 是 Codex 项目里最值得认真写的文件。

它相当于项目说明书，也是每次新会话启动时，Codex 优先读取的上下文。

如果没有它，你每次都要重新解释：

• 这个项目是做什么的
• 要用哪些 API
• 哪些文件不能动
• 输出结果要放在哪里
• 代码风格和安全边界是什么

不要一开始就追求完美。

你可以先让 Codex 根据项目目标起草一版，再人工删改。

例如你可以这样写：

# 项目：YouTube 评论智能分析

## 背景

我运营一个关于 AI 工具的 YouTube 频道，希望了解观众最近在讨论什么、提问什么，以及他们在比较哪些工具。

## 目标

构建一个工作流，定期提取最近评论，完成分类、摘要、优先级排序，并生成 Excel 报告和 Web 仪表板。

## 约束条件

- 使用 YouTube Data API v3
- 使用 API Key，不使用 OAuth
- 凭证保存在 .env.local
- 不要把 .env.local 提交到代码仓库
- 输出 Excel 工作簿和 Web 仪表板
- 仪表板部署到 Vercel

## 工作习惯

- 写代码前先给出计划
- 遇到失败方案时记录缘由
- 修改多个文件前先说明影响范围
- 不要删除 data/ 下的原始数据

一个好用的 AGENTS.md，不需要长篇大论。

关键是把规则写清楚。

提议包含四类信息：

1. 背景：你是谁，为什么做这个项目
2. 目标：最终要得到什么结果
3. 约束：API、技术栈、安全边界、输出格式
4. 工作习惯：计划模式、失败记录、提交规范、测试要求

这里最容易踩坑的是把“步骤”写进 AGENTS.md。

AGENTS.md 适合写长期规则，不适合写一次性执行计划。

例如：

• 适合写：所有密钥都放在 .env.local
• 不适合写：今天先写 Python，再做 React 页面

后者应该交给计划模式处理。

3. 每次构建前，先让 Codex 出计划

Codex 能直接改文件，也能直接运行命令。

但这不代表你应该一上来就让它执行。

更稳的做法是先进入计划模式，让它先解释准备怎么做。

一个有效提示词可以这样写：

请先不要写代码。

我想从 YouTube 频道提取最近 200 条评论，按工具对比、内容提议、技术问题、一般反馈分类，并生成 Excel 报告。

请先给出实现计划、需要的配置项、可能的风险和你要创建的文件。

计划模式有三个价值：

• 提前发现方案是否过度复杂
• 提前确认是否遗漏异常处理
• 提前判断文件改动范围是否安全

如果你直接说“帮我做一个 YouTube 评论分析工具”，Codex 可能会马上生成许多文件。

但你可能还没确认：

• 用 Python 还是 Node.js
• Excel 用什么库生成
• 数据缓存放在哪里
• 是否需要分页拉取
• API 额度不够时怎么处理
• 空评论、重复评论、删除评论怎么处理

所以，实际工作中提议采用这个节奏：

1. 描述目标，不指定过细步骤
2. 让 Codex 提问
3. 回答关键问题
4. 审核计划
5. 再允许它写代码

如果计划里出现了你不想要的技术栈，马上打断。

计划阶段改方向，成本最低。

4. 安装、登录与模型服务配置

Codex 一般可以通过 CLI、桌面应用或 IDE 插件使用。

不同版本的入口略有差异，但你需要重点确认三件事：

• 当前项目目录是否正确
• 是否完成登录或模型服务配置
• 是否能读取并修改项目文件

常见登录方式包括账号登录，以及工具支持的 API 配置方式。

如果你不走账号登录，而是使用 OpenAI Compatible API 配置，一般要填写三个核心字段：

• API Key
• Base URL
• Model

本文后续演示会把 iThinkAPI 作为一个 OpenAI Compatible API 配置环境，用来说明 Codex 这类工具在 API 登录或模型服务配置时该看哪些字段。实际接入时，重点核对 API Key、Base URL 和模型名称；可用模型、接口格式、计费和能力边界，都应以对应服务文档为准。

Base URL：https://token.ithinkai.cn/v1
API Key：YOUR_API_KEY
Model：以服务文档为准，最新模型 claude-fable-5, gpt-5.5, claude-opus-4-8,gpt-image-2 模型都有几乎在 0.05¥/图，支持 2k,4k

配置时不要只看“能不能连上”。

更提议做一个最小测试：

请读取当前项目结构，确认 AGENTS.md 是否存在。
不要修改文件，只输出你看到的目录和你的理解。

如果 Codex 能正确读取项目结构，说明工作区绑定正常。

如果它无法读取文件，优先检查：

• 当前打开的是否是正确文件夹
• IDE 插件是否选择了当前项目
• CLI 是否在项目根目录运行
• 权限提示是否被拒绝
• API 配置里的模型名称是否填写正确

这里不要急着让它写业务代码。

先确认工具链本身可用，再进入项目开发。

5. 用 .env.local 管理 API Key

只要项目里涉及外部服务，就会遇到 API Key。

例如 YouTube Data API、模型服务、数据库、对象存储、部署平台等。

正确做法是把敏感配置放进 .env.local。

示例：

YOUTUBE_API_KEY=your_youtube_api_key

同时在 .gitignore 里加入：

.env.local
.env

不要把密钥放在这些地方：

• 聊天消息里
• secrets.txt
• README 示例里
• 前端代码里
• 截图里
• Git 提交记录里

让 Codex 写代码时，也要明确告知它：

从 .env.local 读取 YOUTUBE_API_KEY。
不要把密钥写入代码、日志、README 或示例输出。

添加密钥后，先做最小验证。

例如：

请写一个最小脚本，只验证 YouTube Data API Key 是否可用。
不要拉取大量数据，只请求一个轻量接口，并给出错误处理。

如果验证失败，按顺序排查：

1. .env.local 文件名是否正确
2. 变量名是否和代码一致
3. API Key 是否启用对应服务
4. 项目是否有 API 配额
5. 当前网络环境是否能访问目标服务
6. 错误日志是否暴露了敏感信息

如果密钥被提交到公开仓库，不要只删除文件。

正确做法是去服务平台轮换密钥。

由于旧提交记录依旧可能被扫描到。

6. 连接 MCP：让 Codex 直接使用外部工具

MCP，全称是 Model Context Protocol。

它可以理解为一种让 AI 工具连接外部系统的开放协议。

有了 MCP，Codex 不只是“听你描述 GitHub 上有什么”，而是可以在授权范围内读取仓库、创建分支、发起 PR、查看 Issue。

常见 MCP 场景包括：

• GitHub：读取仓库、创建分支、提交 PR
• Vercel：部署项目、查看构建状态、回滚版本
• Notion：读取文档、写入项目记录
• Drive：读取文件、整理资料
• Figma：读取设计稿相关上下文

这一步的核心不是“能接多少工具”。

而是把人工搬运上下文的动作减少掉。

例如以前你可能这样做：

这是我 GitHub 仓库的文件结构，这是报错截图，这是我想改的地方……

接入 MCP 后，可以变成：

请查看当前仓库最近一次失败的构建日志，定位缘由，创建一个修复分支，并给出 PR 摘要。

不过，MCP 不是越多越好。

提议只接真正需要的服务。

每接一个外部系统，都要思考：

• 权限范围是否过大
• 是否允许写操作
• 是否需要人工审批
• 是否会影响生产数据
• 是否有日志可追踪

如果你只是做本地脚本，不需要一开始就配置一堆 MCP。

先把最小工作流跑通，再逐步接外部系统。

7. 没有 MCP 时，让 Codex 帮你接普通 API

不是每个服务都有 MCP。

YouTube Data API、公司内部接口、小众 SaaS 工具，许多时候都需要自己接 API。

这正是 Codex 很适合发挥作用的地方。

你可以在计划模式里这样提问：

我需要用 YouTube Data API v3 拉取频道最近视频下的评论。
请比较 API Key 和 OAuth 两种方式，说明本项目适合哪一种，并给出最小验证步骤。

对于只读取公开或你有权限的数据，API Key 往往更简单。

但如果需要访问用户私有数据、代表用户操作，就可能涉及 OAuth。

不要让 Codex 盲目选方案。

你要明确告知它：

• 数据来源是什么
• 是否需要用户授权
• 是否只读
• 调用频率大致多少
• 失败后是否允许重试
• 数据要保存到哪里

拉取评论时，还要注意几个细节：

• 分页参数不要漏
• API 配额要控制
• 评论可能为空
• 评论可能被删除
• 同一评论不要重复写入
• 原始数据和清洗结果要分开保存

一个比较稳的流程是：

1. 写最小连通性脚本
2. 拉取 5 条样例评论
3. 保存原始 JSON
4. 再写清洗逻辑
5. 再导出 Excel
6. 最后接入仪表板

不要一上来就让 Codex 写完整系统。

先小步验证，每一步都有文件输出，排错会容易许多。

8. 用具体提示词生成真正可用的交付物

Codex 输出质量，很大程度取决于你的任务描述质量。

“分析我的 YouTube 评论”太宽泛。

它可能只给你积极、消极、中性三类，结果看起来完整，但对创作者没什么协助。

更好的提示词是：

请分析 data/comments.json 中的 YouTube 评论。

按以下维度分类：
- 工具对比
- 内容提议
- 技术问题
- 一般反馈
- 无关内容

请额外识别评论中提到的工具名称，例如 Codex、Claude Code、Cursor、API、GPT。

输出 Excel 工作簿，包含：
- 摘要
- 分类明细
- 工具提及
- 优先回复
- 内容选题提议
- 原始数据

优先回复规则：
问题类评论 > 高互动评论 > 明确表达需求的评论 > 其他评论。

这里的关键是给出“你会怎么用这个结果”。

例如：

• 给创作者看：需要选题提议和回复优先级
• 给工程团队看：需要 bug、需求、复现路径
• 给老板看：需要趋势、风险、机会点
• 给运营看：需要关键词、用户分层、话题热度

如果第一版结果不够好，不要马上推倒重来。

可以让 Codex 基于已有输出迭代：

这版分类太粗。
请保留已有数据结构，新增“是否值得做成视频选题”字段，并给出判断理由。

这样比反复从零开始更稳定。

由于文件结构、数据字段、输出路径都已经被固定下来。

9. 做 UI 前，先生成概念图或草图

如果你的项目包含仪表板，不提议一开始就直接写前端页面。

更稳的做法是先明确视觉目标。

Codex 支持在工作流中调用图像生成能力，例如通过 gpt-image-2 生成仪表板概念图。

你可以这样描述：

请生成一个 YouTube 评论洞察仪表板概念图。

页面包含：
- 顶部 KPI 卡片：评论总数、问题数量、工具提及数、待回复数量
- 左侧分类分布图
- 右侧工具提及排行
- 下方优先回复列表
- 风格简洁，适合创作者每周查看

概念图的价值不是直接当最终 UI。

它的作用是减少“凭空设计”。

后续你可以继续让 Codex：

请参考刚生成的概念图，在 dashboard/ 中实现一个 React 仪表板。
数据先从 reports/summary.json 读取。

这样生成出来的页面一般更贴近目标。

做 UI 时还要提前约定：

• 使用什么框架
• 是否需要移动端适配
• 图表库用哪一个
• 空数据状态怎么展示
• 错误状态怎么展示
• 是否需要导出按钮
• 是否读取静态 JSON

如果只是个人仪表板，静态 JSON + Vercel 部署就够用。

不必一开始就上数据库和后端服务。

10. 把稳定流程沉淀成 Skill

当一个流程跑通两三次后，就应该沉淀成 Skill。

Skill 可以理解为一份可复用的任务说明。

后来你不需要重新写长提示词，只要触发 Skill，Codex 就知道该按既定方式执行。

一个项目级 Skill 可以放在：

skills/youtube-comment-insights/SKILL.md

示例：

---
name: youtube-comment-insights
description: 当用户要求“评论洞察”“每周 YouTube 报告”“评论分析”时，提取 YouTube 评论，分类、排序，并输出 Excel 和仪表板数据。
---

# YouTube 评论洞察

## 输入

- 从 .env.local 读取 YOUTUBE_API_KEY
- 默认分析最近 10 个视频
- 默认提取约 200 条最新评论

## 分类

- 工具对比
- 内容提议
- 技术问题
- 一般反馈
- 无关内容

## 输出

- reports/comments.xlsx
- reports/summary.json
- dashboard/public/summary.json

## 规则

- 不覆盖原始数据
- API 失败时输出错误缘由
- 输出前检查 Excel 和 JSON 是否生成成功

Skill 最重大的是 description。

由于 Codex 一般会根据描述判断是否调用它。

描述不要写得太抽象。

不要写：

用于分析数据的技能。

要写：

当用户要求“评论洞察”“每周 YouTube 报告”“评论分析”时，提取 YouTube 评论并生成 Excel 与仪表板数据。

Skills 一般有两类存放方式：

• 全局 Skills：适合你所有项目复用
• 项目级 Skills：适合某个客户、频道或业务项目

提议刚开始都放项目里。

等某个 Skill 被多个项目复用，再迁移到全局目录。

11. GitHub、Vercel 与线上部署

本地 Excel 和仪表板，只能算开发完成。

如果你希望别人访问，就要部署到线上。

一个常见路径是：

本地项目 → GitHub 仓库 → Vercel 部署 → 线上访问

你可以让 Codex 先做计划：

请检查当前项目是否适合部署到 Vercel。
先不要执行，只说明需要哪些文件、环境变量和构建命令。

确认后，再让它执行：

请创建 GitHub 私有仓库，提交当前项目，并准备 Vercel 部署所需配置。

这里要注意三件事。

第一，.env.local 不能提交。

部署环境需要在 Vercel 后台单独配置环境变量。

第二，构建命令要写清楚。

例如前端项目可能是：

npm install
npm run build

第三，数据文件路径要统一。

如果仪表板读取的是：

dashboard/public/summary.json

那自动化脚本就必须把最新摘要写到这个位置。

部署失败时，优先看这几类问题：

• 构建命令不存在
• 依赖没有写进 package.json
• 环境变量缺失
• 文件路径大小写不一致
• 本地能读的文件没有提交
• Node.js 版本不匹配

不要只把报错截图丢给 Codex。

更好的方式是让它读取构建日志并定位：

请根据 Vercel 构建日志定位失败缘由。
不要猜测，先列出证据，再给修复方案。

12. 自动化任务要明确模型和运行边界

Codex 应用支持自动化任务时，可以按时间计划运行工作流。

这很适合周报类任务。

例如每周日晚上自动执行：

1. 拉取最新 YouTube 评论
2. 运行评论洞察 Skill
3. 更新 Excel 和 JSON
4. 提交到 GitHub
5. 触发 Vercel 重新部署

设置自动化时，最容易忽略的是模型选择。

自动化任务不必定继承你当前会话的模型设置。

所以要在任务配置中明确：

• 使用哪个模型
• 推理强度如何
• 是否允许写文件
• 是否允许联网
• 失败后是否重试
• 是否需要通知你确认

不要让自动化任务拥有过大权限。

尤其是涉及删除文件、覆盖数据、推送主分支时，提议加入检查步骤。

例如：

执行前先检查 data/raw/ 是否存在。
不要删除原始数据。
生成报告后先验证文件存在，再提交。
如果 API 调用失败，不要覆盖上一次成功结果。

自动化任务跑慢时，可以从这些方向排查：

• 是否选错模型
• 是否重复安装依赖
• 是否每次都全量拉取
• 是否没有缓存原始数据
• 是否在等待人工审批
• 是否外部 API 响应变慢

定时任务不是“写完就不用管”。

提议保留运行日志，至少记录：

• 开始时间
• 结束时间
• 拉取评论数量
• 输出文件路径
• 是否部署成功
• 失败缘由

13. 选择 Local、Worktree 还是 Cloud

Codex 的不同运行模式，适合不同风险等级的任务。

常见可以理解为三类：

• Local：直接改当前目录
• Worktree：在隔离工作树里改
• Cloud：在云端环境里运行

小修小补可以用 Local。

例如改 README、修一个样式、调整一个字段名。

重大开发提议用 Worktree。

例如新增数据清洗逻辑、重构仪表板、调整部署流程。

长期自动化任务可以思考 Cloud。

例如每周刷新数据、生成报告、提交部署。

经验规则很简单：

小改动用 Local
重大改动用 Worktree
长任务用 Cloud

Worktree 的好处是隔离。

如果 Codex 的一次尝试方向错了，不会直接污染主工作区。

你可以先审查变更，再决定是否合并。

这里特别提醒：

<span style='color: rgb(202,88,99); font-weight: bold;'>不要在没有版本控制的目录里，让 Codex 大范围重构。</span>

至少先初始化 Git：

git init
git add .
git commit -m "initial project"

这样即使修改不满意，也能回到干净状态。

14. 用内置浏览器做 QA，而不是只看代码

仪表板能构建成功，不代表它真的好用。

页面可能存在：

• 链接失效
• 图表空白
• 移动端错位
• 搜索没有结果提示
• 空数据状态难看
• 按钮没有反馈
• 可访问性问题

让 Codex 用内置浏览器做 QA，是一个很实用的习惯。

你可以这样下指令：

请在内置浏览器中打开本地仪表板，完成一次 QA。

请检查：
- 首页是否正常加载
- 图表是否有数据
- 空状态是否合理
- 链接是否可点击
- 移动端宽度是否溢出
- 控制台是否有错误

只输出问题清单和修复提议，先不要改代码。

确认问题后，再让它逐条修。

不要一次性说“全部优化一下”。

更好的方式是：

请先修复控制台错误和空数据状态。
不要调整视觉风格。

浏览器能力还可以用于没有 API 的后台操作。

例如：

• 打开管理后台下载报表
• 检查某个状态页
• 验证一个多步骤表单
• 对比线上页面和本地页面

但这类操作要注意权限边界。

涉及真实业务数据、用户数据、付款、删除、发布等动作时，最好保留人工确认。

15. 这些 UX 功能也值得用起来

Codex 的一些小功能，单看不起眼，但组合起来能明显减少重复操作。

常用的有这些：

• 侧边对话：在不污染主线程的情况下快速提问
• 斜杠命令：例如 /skills、/help、/clear
• @ 文件提及：让 Codex 精准参考某个文件
• 模型切换器：按任务复杂度选择模型
• 推理强度：复杂任务提高，简单任务降低
• $imagegen：在 UI 设计前生成概念图
• IDE 自动上下文：让 Codex 跟随你正在看的文件
• 完全访问模式：减少审批，但风险更高

这里最提议养成的是 @ 文件提及。

不要说：

帮我改那个导出 Excel 的脚本。

改成：

请参考 @scripts/export_excel.py，新增“优先回复”工作表。

这样 Codex 更容易定位。

如果项目变大，也提议频繁使用 /clear 开新上下文。

长对话里积累了太多旧信息，反而可能影响判断。

16. 常见错误与排查方式

许多人觉得 Codex “不稳定”，实则是项目配置不稳定。

下面这些问题最常见。

没有 AGENTS.md

每次对话都重新解释项目，结果每次输出风格不同。

解决方法：

请根据当前项目，起草一份 AGENTS.md。
重点写清楚目标、约束、文件结构和工作习惯。

跳过计划模式

一句需求理解错，可能改动几十个文件。

解决方法：

先不要写代码，先列计划、文件影响范围和风险。

密钥放错地方

把 API Key 放聊天里、README 里、前端代码里，后续很难处理。

解决方法：

所有敏感配置只从 .env.local 读取。
请检查项目中是否存在疑似泄露的密钥文本。

提示词太泛

“帮我分析评论”会得到很普通的分类。

解决方法：明确分类维度、输出格式、受众和排序规则。

没有沉淀 Skill

每周都从头描述同一个流程。

解决方法：把稳定流程写成 SKILL.md。

所有任务都用 Local

一旦大范围修改失败，工作区会很乱。

解决方法：重大改动用 Worktree，并先提交当前状态。

自动化任务没有边界

失败时覆盖旧数据，或者推送了错误结果。

解决方法：加入前置检查、输出验证和失败保护。

没有 QA

页面能打开，但用户实际用不了。

解决方法：把浏览器 QA 写进发布流程或 Skill。

总结：Codex 的关键不是聊天，而是配置工作流

Codex 看起来像聊天窗口，但真正的用法是围绕文件夹搭工作流。

一个成熟的 Codex 项目，至少应该具备这些东西：

• 一个边界清晰的项目文件夹
• 一份可持续维护的 AGENTS.md
• 一个安全的 .env.local
• 一套可验证的 API 接入脚本
• 一个能复用的 Skill
• 一个可部署的仪表板
• 一个自动化刷新流程
• 一套浏览器 QA 检查

如果你还停留在“问一句、复制一段代码”的阶段，可以先从两个动作开始：

1. 给当前项目补一份 AGENTS.md
2. 把重复执行过三次的任务写成 Skill

Codex 的效果，很大程度取决于你给它的项目结构、规则和反馈。