Codex 是 OpenAI 出的 AI 编程助手——不是 2021 年那个已停用的旧代码补全 API，而是 2025 年 4 月以 CLI 首发、随后扩展到桌面、IDE 插件和云端的新版本。Altman 在 2026 年 4 月透露 Codex 已有约 400 万周活，是 Claude Code 最直接的对手。
如果你用过 Claude Code，可以这样理解 Codex：本地一个文件夹 + 一个 markdown 配置文件 + 一个能读所有文件的 AI 智能体 + Skills + MCP + 自动化 + 内置浏览器。外壳不同，模型不同，核心理念一致。
大多数人打开 Codex 看到聊天窗口，就把它当 ChatGPT 套了个 UI。结果 90% 的功能没用上——不会建 Skills、不会部署、不会让自动化在后台跑。
下面 14 步，30 分钟，从空白文件夹搭出完整可用的工作流。
1. 建项目文件夹
Codex 没有自己的数据库或文件系统。一个 Codex 项目 = 你电脑上的一个普通文件夹。里面的所有文件 Codex 都能读、写、改、整理。
这意味着：
- 项目可移植。同一个文件夹在 Codex CLI、桌面、IDE 插件、Claude Code、Cursor 都能开。
- 像代码一样管理。Git、GitHub、Vercel 都是标准工具。
- 备份/分享/迁移和操作普通文件夹一样。
Codex 默认 agent mode，自动读、写、跑工作目录里的命令。文件夹外和网络访问需要批准。文件夹就是信任边界。
2. 写 AGENTS.md——Codex 启动先读的文件
被严重低估。AGENTS.md 放项目根目录，每次在该文件夹里开新对话 Codex 都先读它。告诉 AI：你是谁、项目是什么、目标是什么、限制是什么。
不要从零写。用大白话告诉 Codex 项目目标，让它帮你起草 AGENTS.md。得到一个结构完整的文件，再按需改。
好的 AGENTS.md 包括：
- 背景——一段话。你是谁、为什么做。
- 目标——一段话。描述最终状态，不描述步骤（步骤归计划模式）。
- 约束——列表。硬规则：API 选择、避开的语言、安全边界、输出格式。
- 工作习惯——列表。比如"把教训存到记忆里"、"先确认计划"、"永远别跑 X"。
OpenAI 官方实践："把 Codex 当作可以配置和持续改进的队友，不是一次性助手。"
3. 每次构建先开计划模式
计划模式 = Codex 不立刻执行。它先头脑风暴、问澄清问题、列方案对比、给编号计划等你批。
跳过计划模式是项目出错的 #1 原因。
有效用法：
- 说目标，不说步骤。"从 YouTube 频道提取最近评论生成 Excel 报告"——不是"用 Python 调 YouTube API 然后写 xlsx"。
- 让它问。计划模式通常返 3-5 个澄清问题。认真答，每个问题都省未来的 bug。
- 批之前读计划。少了边界处理、工具选错、过度复杂——现在改。计划阶段改比写完再改省事 10 倍。
计划模式 + AGENTS.md 组合效果尤其好：配置文件里的约束会直接影响 Codex 提的方案。
4. 用 .env.local 管 API key
所有 API key、secret、凭证放项目根目录的 .env.local。文件名前的点告诉 Codex（和 git）不要公开提交。
两条铁律：
- 永远别把 key 贴进 secrets.txt 或聊天消息。最终都会进版本控制。
- 加 key 后立即测。让 Codex 跑最小 API 调用确认有效。
已经提交了？立即去服务商轮换 key。 不要只删再推——旧 commit 里还有，扫描机器人几分钟内捡走。
5. 接 MCP 服务器和插件
Codex 用模型上下文协议（MCP）——Claude Code 也在用的开放标准。大部分现有 MCP 都能在 Codex 里用：GitHub、Slack、Notion、Linear、Drive、Figma + 数十个社区服务器。
回报最快的三种：
- GitHub MCP — 读 repo、建分支、发 PR、评论 issue。
- Vercel MCP — 部署、查状态、回滚。配 GitHub 跑通"build → commit → deploy"全环。
- Notion / Drive MCP — 把内部文档抽出来当上下文，把决策写回中央知识库。Codex 不再是黑盒，成为团队记忆的一部分。
6. 没插件时让 Codex 帮你接 API
不是每个服务都有 MCP。YouTube Data API 没有，公司内部 API 没有，小众 SaaS 也没有。直接问 Codex：在计划模式下告诉它集成目标，它会返不同选项，推荐一个，列分步计划。
长期有效：
- 先试第一种。Codex 按权衡选。
- 失败就记教训。"PowerShell 撞 TLS 错误，Python 没事。写到项目记忆。" 下次对话继承。
- 稳定了锁成 Skill，下次不重复设置。
这是 AI 辅助工作里最重要的习惯：试、败、记、不再犯。 Codex 默认只有短期记忆——本次对话学的东西明天就忘，除非你写下来。
7. 用具体提示词做真实交付
决定第一次出活质量的关键是提示词具体度。
"分析 YouTube 评论" → 出来一个"正面/负面/中性"分类的 Excel，没用。 "分析 YouTube 评论按以下维度：工具对比、内容建议、技术问题、一般反馈——再按回复优先级为创作者排序" → 会真用的工作簿。
提升质量：
- 说输出用途——"给我这个创作者用的"/"给董事会汇报"/"给我工程团队"。受众决定结构。
- 列出你关心的分类。别让分类依赖默认判断。
第一版还行但不够好？别推倒重来。 加细节重跑。迭代三轮清晰的 prompt 比从零五次强。
8. 构建 UI 前先用 gpt-image-2 出概念图
Codex 内置 gpt-image-2。显式调用或在 prompt 里描述需求，Codex 自动识别。
关键用法：写 UI 代码前先生成概念图。 让 Codex 用一两张图模拟仪表板长相，存到项目里。再构建仪表板时引用这些图。最终视觉效果比凭空设计好得多。
9. 把工作流变成 Skills
Skill = Codex 按需加载的可重用配方。构建了有效工作流（提评论、生成报告、部署仪表板）就转成 Skill，下次一条命令跑。
Codex 里的 Skill = 文件夹里的 markdown，根目录 SKILL.md，含前置元数据（名称+描述）和指令正文。可选放脚本和参考文件。
两个存储级别：
- 全局 Skills —
~/.agents/skills/。电脑上每个 Codex 项目都可用。 - 项目级 Skills — 项目文件夹内。只在该项目可用。客户/项目专属配方。
决定 Skill 能不能自动触发的三个因素：
- 描述就是一切。Codex 只按描述文本匹配任务以便隐式调用。关键用例和触发词放前面；模糊的描述永远不会触发。
- 两种调用方式。显式（CLI/IDE 里
/skills或$提及），或隐式（prompt 匹配描述时自动选）。 - 开放标准。Skills 2025 年 12 月在 Codex 推出，现在是跨平台 Agent Skills 标准的一部分——同样格式在 Codex、Claude Code、Gemini CLI、Cursor 都能用。
10. 部署上线：GitHub → Vercel → 生产
Excel 是后端，仪表板是前端，localhost 是开发地址，这些都不能直接交付。
Codex 协调全流程：接 GitHub 建私有 repo 并推代码；接 Vercel 导入 repo 部署。GitHub 和 Vercel 首次连接后持续通信——推 main 分支 → Vercel 自动部署。
你在 Codex 工作，Codex 推 GitHub，Vercel 自动部署。三个工具，一个工作流。
11. 配自动化任务——并明确指定模型
Codex 应用有自动化选项卡，按 cron 表达式跑定时任务。配 Skills 就能让仪表板"你睡觉时自动更新"。
真实场景：周日晚上跑自动化 → 提新评论 → 跑 insight Skill → 更新 Excel → 推新数据 → Vercel 自动部署。端到端刷新，零人工。
坑：自动化面板的模型选择器不继承你活跃对话的设置。 新建任务用面板默认值——可能比你想要的生产模型更慢更便宜。每个自动化任务明确设模型，否则你会奇怪 7 分钟的活为啥突然 40 分钟。
12. 选对线程模式——Local / Worktree / Cloud
- Local — 直接在当前项目目录工作。最快最简单，但每次改动影响实际工作文件。小型、可控的编辑，信任 AI 时用。
- Worktree — 在 Git worktree 隔离改动（同 repo 绑定的独立工作目录）。AI 在单独分支干，不影响主分支。任何重要构建的默认选择。 跑错了删 worktree，零风险。
- Cloud — 在配置的云环境远程跑。笔记本关机也能跑。配自动化任务做真正异步工作流。
经验法则：Worktree 重要工作，Local 小修小补，Cloud 长跑自动化。
13. 用内置浏览器做 QA
构建完仪表板让 Codex 在内置浏览器里打开它，点击浏览，找问题，报告。它会找到你盯代码看不到的事：失效的外部链接、看起来空的空状态、死板的搜索行为、可访问性缺陷、UI 不一致。
把一次性操作变习惯：把 QA 写进项目记忆或 Skill。每次发新功能，AI 智能体跑浏览器测试再交回。你不再是 QA 测试员——AI 测，你审报告。
浏览器也是通用工具：登没 API 的传统管理面板、从没编程接口的仪表板提报告、自动多步 UI 流程。
14. 多数人忽略的 UX 功能
- 侧边对话 — 从主对话开侧线程，同项目上下文、不同对话。
- 斜杠命令 —
/skills显式调用 Skill，/clear、/help。 - @ 提及 — prompt 里标特定文件，比粘路径干净。
- **` 内联提技能，能和 @ 组合。
- 模型切换器 + 推理强度 — 聊天框下方的切换器按对话切模型和推理强度。更高强度 = 复杂任务表现好，但吃更多 token、更快撞 rate limit。
- 与 IDE 扩展的自动上下文同步 — 应用和编辑器自动同步。开"自动上下文"让 Codex 跟踪你看哪些文件。
- 完全访问模式 — 设置里切换跳过批准。更快，更危险。 默认开，信任项目边界后再切。
只发挥 3% 潜力的习惯
- 没有 AGENTS.md → 每次对话重解释项目，每次答案不同
- 跳过计划模式 → 修一句话的误解改了 40 个文件
- 把 key 放聊天或 secrets.txt → 推送就公开
- 从不记教训 → 一遍遍犯同样的错
- 模糊的 prompt → 通用交付
- 一次性构建 → 每周从零重建同样工作流
- 所有事用 Local 模式 → 一次糟糕的 AI run 清空工作文件
- 让自动化用默认模型 → 7 分钟的活跑 40 分钟
- 没有 QA → 发布仪表板有失效链接和空状态
- 工具站队 → 按身份不按任务选工具
总结
Codex 看起来像聊天窗口，不是。它是一个带 AI 智能体的文件夹——外加 Skills、MCP、自动化任务、浏览器，全部通过文件夹里的 markdown 文件配置。
这个文件夹可移植。在 Codex、Claude Code、Cursor 或任何支持 Agent Skills 标准的工具里打开它。外壳变，工作内容不变。
400 万周活里真用起来的，是那些把文件夹配对的人。挑一个没做过的步骤——可能是 AGENTS.md，或者你的第一个真 Skill——明天就加上。Codex 的输出取决于 Codex 的配置。
🦞 400 万周活里绝大多数人不知道 Skills 跨平台通用——同一个 SKILL.md 能在 Codex、Claude Code、Gemini CLI、Cursor 里跑。会一个等于会四个，这件事本身才是 Codex 体系最被低估的护城河。