本篇介绍如何将安卓手机与 Codex 配对连接。

在半桶水课程里，它对应的是“手机协同 / 任务跟进 / 权限边界”的工作流：手机负责查看、回复和审批，真正执行仍然发生在电脑端或已授权环境里。

这节解决什么

很多长任务不是不能跑，而是中途需要你确认、补充或审批。安卓连接能让你离开电脑后继续跟进 Codex 任务，但它不是让手机替你做最终审查。

这节练的是：把手机端连接到电脑端 Codex，并知道哪些权限可以开、哪些权限要谨慎。

工作流卡

| 项目 | 内容 |
|

你不仅可以从现有宠物中选择，还可以用一张照片生成专属动画宠物，让编程时有一只独一无二的电子宠物。

本篇介绍如何用 Codex 的 Hatch Pet 功能，快速制作自定义宠物。

在半桶水课程里，它对应的是“视觉与页面 / 个性化工作台”的轻量案例：用一张合适的素材图生成可安装、可分享、可回滚的桌面形象。

这节解决什么

Hatch Pet 看起来像娱乐功能，但它也适合练习一个完整的小型 AI 生产流程：准备素材、描述风格、等待生成、检查输出、安装文件、分享给别人。

这节练的是：用低风险视觉任务熟悉 Codex 的 Skill 调用、文件输出和结果验收。

工作流卡

| 项目 | 内容 |
|

这节先解决什么

这节不是鼓励你一上来就接第三方 API。它要帮你做一个判断：我现在的问题，是 Codex 不会用，还是官方入口真的不满足我的工作流？

如果你还没完成第一个低风险任务，先不要碰这里。第三方 API 会增加变量：模型能力、网关稳定性、密钥安全、账单、日志留存和配置冲突都会影响结果。

适合谁

这一节适合已经具备这些前提的人：

• 已经跑通过 第一个任务。
• 知道 config.toml 是本机配置文件，不会随便覆盖。
• 能区分 API Key、Base URL、模型名、provider 和环境变量。
• 愿意自己承担第三方服务的账号、费用和数据安全风险。

如果你只是想“让 Codex 变聪明一点”，优先回到 任务设计，把目标、材料、边界和验收说清楚。很多时候问题不在模型，而在任务没有讲明白。

先做什么

配置前先做 5 件事：

1. 备份 ~/.codex/config.toml 和 ~/.codex/auth.json。
2. 记录当前官方入口是否能正常完成只读任务。
3. 准备一个不会泄露隐私的测试目录。
4. 明确只接一个 provider，不同时改多个工具。
5. 写好回滚方式：失败时能切回官方配置。

三种方案怎么选

| 方案 | 适合谁 | 优点 | 需要注意 |
|

这篇案例面向医护人员、研究生、规培医生和医学科研初学者，演示如何让 Codex 帮你把一个医学研究问题整理成可复核的文献工作台。它不替你诊断患者，也不替你下治疗决策；它只帮助你做研究辅助、资料整理和写作准备。

适合什么场景

• 准备综述、开题报告或课题背景。
• 想把几篇论文整理成证据表。
• 想检查文献总结里有没有过度推断。
• 想把医学问题转成 PICO 或 PICOS 框架。
• 想给团队留下可追踪的文献阅读记录。

不适合的场景：

• 让 Codex 直接给某个患者诊断或治疗方案。
• 让 Codex 编造 PMID、DOI、指南或随机对照试验。
• 让 Codex 处理未脱敏的真实病历。
• 把模型输出当成最终医学结论。

工作流卡

| 项目 | 内容 |
|

最后核对

官方资料最后核对日期：2026-05-27。本文参考 OpenAI 官方文章 Work with Codex from anywhere。具体入口、可用地区、系统支持和界面名称会随客户端更新变化，请以当前 ChatGPT 手机 App 和 Codex 桌面 App 为准。

这节解决的是“离开电脑后，任务是不是只能停着等你回来”。

手机端 Codex 的价值不是让你在手机上完成所有复杂工作，而是让你在碎片时间里继续跟进：看进度、补充方向、审批低风险请求，回到电脑后再做完整复核。

这里说的“手机端 Codex”，更准确地说，是 ChatGPT 手机 App 里的 Codex 入口。它不是单独的手机 Codex App，也不是把手机变成远程桌面鼠标键盘。

你可以把它理解成：桌面 App、远程开发机或其他已授权环境里正在运行 Codex，手机端负责连接这些环境，让你在离开电脑时继续查看、回复、审批和调整任务。

适合谁

这一节适合已经能在电脑上启动 Codex 任务的人，尤其是：

• 经常通勤、开会、外出，但希望长任务不中断的人。
• 需要在手机上快速回复 Codex 澄清问题的人。
• 团队负责人、课程老师或运营同学，想随时看任务进展。
• 已经理解权限边界，知道哪些操作不能在手机上草率批准的人。

如果你还没跑通过电脑端第一个任务，建议先读 用 Codex 完成第一个任务。

先做什么

先把 ChatGPT App 更新到最新版本，然后在手机端选择连接你电脑里的 Codex。第一次连接建议只用一个低风险任务练习，例如整理一份文档、生成一个待办清单，或让 Codex 总结某个测试文件夹。

连接桌面 Codex App：

在 ChatGPT 中打开 Codex，就可以直接使用了。

它能做什么

手机端连接到正在运行 Codex 的机器后，可以继续处理这些事情：

• 查看正在进行的线程和任务状态。
• 阅读 Codex 的阶段性输出、终端输出、截图、diff 和测试结果。
• 回复 Codex 的澄清问题。
• 审批命令、网络访问或其他需要人工确认的操作。
• 改变任务方向、切换模型或补充新的上下文。
• 新建任务，让 Codex 从已连接的开发环境里开始工作。

真正执行任务的地方仍然是桌面 App 或远程环境。你的文件、依赖、凭据、权限和本地配置不会因为手机端接入而搬到手机上。

使用前提

使用前先确认这些条件：

• 手机上安装并更新 ChatGPT App。
• 电脑上安装并更新 Codex 桌面 App。
• 手机和电脑登录同一个 ChatGPT / OpenAI 账号，且处在支持 Codex 的地区和套餐范围内。
• 桌面 App 已经连接到对应项目，或 Codex 正在某台已授权机器、devbox、远程环境中运行。
• 如果任务会写文件、跑命令、访问网络，仍然需要理解并确认对应权限。

推荐使用场景

手机端最适合处理“离开电脑但不想让任务停住”的时刻：

• 通勤路上查看长任务进展。
• Codex 需要你选择方案时，快速给出方向。
• 任务卡在权限审批时，从手机上批准或拒绝。
• 会议前让 Codex 汇总最新代码、issue、文档或客户背景。
• 突然想到一个改动点，先发给 Codex 开始探索，回到电脑后再细看 diff。

不适合怎么用

手机端不适合替代完整的本地审查流程。下面这些事情最好回到电脑上做：

• 大范围代码合并前的最终 review。
• 涉及生产环境、密钥、账单、发布部署的高风险操作。
• 需要长时间阅读大量 diff 的任务。
• 需要你手动操作 IDE、调试器或本地 GUI 的任务。

如果你在手机上审批命令，建议只批准自己能看懂的操作。遇到删除、覆盖、部署、传输敏感数据等动作，先停下来，回到电脑上确认。

一个典型流程

1. 在电脑上打开 Codex 桌面 App，并进入对应项目。
2. 让 Codex 开始一个需要较长时间但风险可控的任务，例如整理文档或只读分析项目结构。
3. 离开电脑后，在 ChatGPT 手机 App 中进入 Codex。
4. 打开同一个正在运行的任务线程。
5. 查看 Codex 的输出、截图、终端日志、测试结果或 diff。
6. 如果 Codex 需要确认，直接在手机上回复、审批或调整方向。
7. 回到电脑后，再做完整 diff review、运行验证命令和提交。

和 Codex Cloud 的区别

| 对比项 | 手机端连接桌面 App | Codex Cloud |
|

对第一次使用 Codex 的人来说，真正要完成的是：让电脑上出现一个可以安全尝试的 AI 工作台，并确认你知道它会在哪里读文件、在哪里执行任务。

本教程里的 Codex 桌面 App 指电脑端客户端，不是手机 App。它由 OpenAI 官方发布，支持 macOS 和 Windows，安装后可以在本地管理项目、发起任务、使用 Skills 和 Automations。

适合谁

这一节适合三类人：

• 想从桌面 App 开始学习 Codex 的非技术工作者。
• 准备参加半桶水课程，需要先把本机环境准备好的学员。
• 不想一开始碰终端，但希望 Codex 能读本地资料、整理文件或执行小任务的新手。

如果你已经装好 App，可以直接跳到 安装后验证。如果你是开发者，也可以稍后再读 CLI 安装与登录。

安装前先准备

先准备一个低风险练习环境，后面第一次任务会轻松很多：

| 准备项 | 怎么做 | 为什么 |
|

最后核对

官方资料最后核对日期：2026-06-11。Codex 已包含在 Free、Go、Plus、Pro、Business、Edu 和 Enterprise 等符合条件的 ChatGPT 套餐中，但不同套餐的使用限制不同。定价、额度、可购买 credits 和套餐命名以 ChatGPT 定价页、Codex Pricing 与 Using Codex with your ChatGPT plan 为准。

这节解决什么

这节不是劝你马上付费，而是帮你做三件事：

1. 判断自己是否真的需要升级套餐。
2. 知道订阅前要核对哪些官方信息。
3. 订阅后能检查 Codex 是否真正可用，而不是只看到扣费成功。

适合谁

• 已经想用 Codex 跑真实任务，但不确定 Free、Go、Plus、Pro 差别的人。
• 准备给自己或团队配置 Codex 学习环境的人。
• 需要通过 App Store、Google Play 或信用卡完成订阅的人。

先看官方套餐，而不是先找付款技巧

Codex 可用性和额度会随套餐、地区、模型、任务复杂度和 OpenAI 策略变化。订阅前先打开官方页面核对：

| 你要核对什么 | 去哪里看 | 判断方式 |
|

最后核对

官方资料最后核对日期：2026-05-27。本章参考 Codex App docs、Settings、Agent approvals and security 等官方资料。界面说明以当前 Codex 桌面 App 实际版本为准，不同系统、地区、客户端版本和账号套餐下显示可能略有差异。

这一节解决一个很常见的问题：打开 Codex 后，界面上到处都是入口、设置、权限和任务状态，新手很容易不知道先看哪里。

半桶水式学习不要求你一次记住所有按钮。你只需要先分清三件事：

• 在哪里说需求：对话框和上下文入口。
• 在哪里放材料：项目工作区和本地文件夹。
• 在哪里控风险：权限、设置、任务状态和结果复核。

适合谁

这一节适合已经装好桌面 App，但还不敢正式下任务的人。读完后，你应该能看懂 Codex 的基本工作台，而不是把它当成一个更复杂的聊天窗口。

先做什么

先准备一个低风险练习项目，然后边看边点：

1. 打开 Codex 桌面 App。
2. 新建或进入一个测试项目。
3. 找到对话框、项目目录、权限设置和任务状态。
4. 不急着让 Codex 修改文件，先确认你知道每个入口大概负责什么。

认识对话和项目

打开 Codex 桌面 App，左侧栏包含两个主要入口：Chat（对话） 和 Project（项目）。

Chat 对话

与 ChatGPT 网页端对话体验基本一致，适合处理日常的、一次性的问答和简单任务。每个对话相互独立，不共享工作目录。

Project 项目

适合需要操作本地文件的任务，例如生成代码、编写文档、制作 PPT、完成报告。在项目里创建的所有对话都共享同一个本地工作目录，方便统一管理多个子任务。

在项目里下达指令后，Codex 的修改会直接应用到你本地文件夹中的文件。

对话框功能说明

Codex 桌面 App 的对话框与 ChatGPT 网页端类似，但额外提供了以下功能：

1. 添加上下文：可以附加文件、截图或其他参考内容
2. 切换模型：在不同模型之间切换
3. 控制权限：设定 Codex 在当前任务中的操作权限
4. 选择工作目录：指定 Codex 在哪个本地文件夹下执行任务

设置面板

点击左下角头像或设置图标可以打开设置面板。

上图左侧就是 Codex 桌面 App 的设置菜单。不要把它当成一次性必须填完的表单：新手只需要确认「常规」和「权限」能支撑第一个任务，其他设置等真实场景出现后再逐步打开。

新手先按这四步检查

1. 先选工作模式：做代码、网站、脚本、仓库任务时选「适用于编程」；写文案、整理资料、做非代码任务时可以选「适用于日常工作」。
2. 先别急着开最大权限：刚开始建议让 Codex 只在当前工作区内读写文件，遇到联网、系统文件、危险命令时再单独审批。
3. 先配置工作目录：第一个任务尽量使用一个空文件夹或测试项目，不要直接把重要项目交给新手阶段的 Codex。
4. 先观察使用情况：如果任务经常中断、额度告急或模型响应变慢，再回到「使用情况」和套餐页面确认限制。

设置逐项说明

什么时候需要改设置

| 你遇到的情况 | 优先检查 |
|

这节课解决什么问题

很多新手第一次打开 Codex 会卡在两个地方：

• 不知道该选哪个文件夹，怕它乱改东西。
• 不知道该怎么描述任务，只能说“帮我做一下”。

这一节只训练一件事：让 Codex 在一个安全文件夹里完成一件可检查的小事。

先选一个低风险任务

推荐从这些任务里选一个：

| 任务 | 为什么适合第一次 |
|

这节课解决什么问题

新手常见困惑是：

• 我连续发了几条消息，为什么后面的没有马上执行？
• Codex 正在做任务，我突然想到一个重要要求，怎么办？
• 一个项目里能不能同时开多个任务？
• 怎么避免上下文越来越乱？

这一节训练的是任务节奏管理。

顺序执行：先来的任务先处理

在同一个对话里，Codex 会按顺序处理任务。前一个任务没结束时，后面的消息通常会排队。

如果你让 Codex 设计一个网页，又马上补一句“顺便讲一下技术选型”，再补一句“要手绘风格”，后两条可能会等前面的任务执行完。

这个机制本身不是坏事。它能避免 Codex 同时处理互相冲突的要求。

引导：给正在执行的任务补关键方向

如果你突然意识到“这个要求必须现在告诉它”，比如网页风格必须是手绘，而不是等它做完再改，可以使用界面里的“引导”能力。

引导的作用可以理解为：把关键补充插入当前任务，让它尽早影响正在进行的工作。

适合引导的内容：

• 风格方向：比如更克制、更适合小白、更像课程页。
• 禁止事项：比如不要安装依赖、不要改配置、不要访问网络。
• 验收标准：比如必须生成截图、必须告诉我改了哪些文件。

不适合引导的内容：

• 完全换一个新任务。
• 让它同时处理另一个项目。
• 大量追加无关背景。

并行：同一个项目里开多个对话

如果两个任务互不影响，可以在同一个项目里新建对话并行执行。

适合并行的例子：

| 对话 | 任务 |
|

这节课解决什么问题

权限不是给开发者看的复杂设置，而是每个学习者都要理解的安全边界。

你只需要先记住一句话：越是涉及文件修改、命令执行、网络访问、账号凭据和费用的任务，越要慢一点。

学完这一节，你要能回答：

• Codex 现在能不能自动改文件？
• 它准备执行命令时，我有没有机会确认？
• 当前任务有没有敏感资料、账号、费用或删除风险？
• 如果结果不对，我能不能回退？

三种常见模式

1. Suggest
   这是最保守的模式。Codex 可以读取文件并提出修改建议，但真正改文件或执行命令前，通常仍需要你确认。它适合初次了解陌生仓库、做代码审查、或者你希望全程掌控关键操作的时候使用。

2. Auto Edit
   这个模式通常允许 Codex 自动写文件，但在执行 shell 命令时仍会保留人工确认。它适合你已经比较了解项目结构，想让 Codex 快速完成重构、批量改文档或局部实现，但又不想完全放开命令执行权限的场景。

3. Full Auto
   这是自主性最高的模式。Codex 会在受限环境中自动读取、写入并执行命令，适合较长的连续任务，比如修复构建、跑一轮验证或完成一个边界明确的小功能。因为风险更高，最好只在版本可回退、任务范围清晰、并且你理解当前沙盒边界时使用。

怎么选更稳妥

• 第一次进入新项目，优先从 Suggest 开始。
• 需要批量修改文档、样式或测试时，可以考虑 Auto Edit。
• 只有在任务边界明确、仓库可回滚、并且你接受它连续执行命令时，再考虑 Full Auto。

半桶水式选择法

| 你的任务 | 推荐模式 | 原因 |
|

如果你在 App 中看到了和技能、插件相关的入口，可以结合下面的概念来理解它们：

这节课解决什么问题

当你重复做同一类任务时，如果每次都从零描述，就会越来越累。Skill 和 Plugin 的价值在于：把一次跑通的经验，变成下次可以复用的流程。

半桶水课程里可以这样理解：

• 第一次做，是练习。
• 第二次做，是流程。
• 第三次还要做，就应该考虑沉淀成 Skill、模板或团队规则。

Skill 是什么

Skill 可以理解为一份让 Codex 稳定执行重复任务的操作手册。当某个工作流已经很固定，例如“审查 PR”“整理文档”“补案例索引”，就可以把它沉淀成一个 Skill，减少每次重复描述的成本。

一个 Skill 通常会包含：

1. 一个 SKILL.md 文件
   这里会写清触发场景、执行步骤、输出格式和注意事项。
2. 必要时配套脚本、模板或参考文件
   用来帮助 Codex 更稳定地完成任务。

常见使用方式是：

• 先准备或安装可用的 Skill。
• 在发起任务时明确说明你希望使用哪个 Skill。
• 让 Codex 按这个 Skill 的流程执行，再根据结果继续追问或迭代。

有些工作区会提供更直接的安装或启用方式；也有一些场景里，需要先把 Skill 放到约定目录，或者通过现有插件能力来分发。稳妥起见，不建议把“给一个 GitHub 链接就一定能自动安装”写成固定结论，更好的表述是：可以把 Skill 来源交给 Codex 协助识别和安装，但具体流程会受客户端能力和工作区设置影响。

哪些工作流适合沉淀成 Skill

| 工作流 | 为什么适合 |
|

当一个工作流已经足够稳定、而且会重复发生时，就可以考虑把它交给 Automation，在后台按计划触发，而不是每次都手动发起。

这节课解决什么问题

自动化不是让 Codex 替你“随便动手”。它适合那些已经跑通过、边界清楚、结果可检查的重复任务。

半桶水式判断很简单：

1. 这个任务是否重复出现？
2. 输入范围是否固定？
3. 输出格式是否固定？
4. 失败时是否容易发现？
5. 是否不涉及高风险写入、费用或敏感资料？

五个问题里只要有两个答不上来，就先不要自动化，先把它做成任务模板。

适合自动化的任务包括：

• 定期检查文档死链
• 每周整理一次 issue 或 PR 摘要
• 每天汇总 failing CI
• 在固定时间提醒补复盘或更新文档

不适合第一批自动化的任务包括：

• 删除、迁移或批量覆盖文件。
• 处理客户隐私、账号凭据、账单或生产数据。
• 需要强人工判断的内容发布。
• 失败后没有明确报警或复核方式的任务。

可以怎么理解自动化

一个自动化任务通常至少会包含三部分：

1. 目标对象
   它对应哪个项目、仓库或线程。
2. 触发时机
   比如固定时间、固定间隔，或者稍后回到当前任务继续跟进。
3. 执行内容
   也就是让 Codex 到时具体去完成什么。

常见使用流程

在支持 Automations 的界面里，你通常会经历类似下面的流程：

1. 选择对应的项目、仓库或当前线程。
2. 设定执行时间或执行周期。
3. 写清楚自动化任务本身的目标、输出格式和边界。
4. 保存后观察第一次运行结果，再决定是否长期保留。

这里最容易被忽略的一点是：自动化 prompt 要尽量写成”自包含”的任务说明。不要默认它会记得你之前说过什么，最好把检查范围、输出格式和验证要求写完整。

❌ 不够自包含的写法：

请检查一下文档里的链接有没有问题。

✅ 推荐的写法：

请检查 docs/ 目录下所有 .md 文件中的外部链接是否有效。

检查范围：仅检查以 http:// 或 https:// 开头的链接，忽略锚点和相对路径。
输出格式：按”文件路径 | 行号 | 链接 | 状态”列出失效链接；全部正常时输出”全部链接正常”。
验证方式：对每个链接发起 HEAD 请求，超时 5 秒视为失效。
限制：不修改任何文件，不创建新文件。

两者的区别在于：第一种每次触发时 Codex 都要靠猜测来填补缺失的细节，结果容易不稳定；第二种把边界、格式、验证方式都写明白了，无论在哪次执行、哪个上下文里，行为都是一致可预期的。

使用时的提醒

• 不同工作区里的自动化能力可能并不完全一样，有些支持项目级任务，有些更偏向提醒和跟进。
• 第一次配置时，建议先从低风险、只读型任务开始。
• 如果自动化会写文件、访问外部系统或触发通知，最好先确认权限边界和人工复核方式。

从模板到自动化

建议按 3 步走：

| 阶段 | 做什么 | 进入下一步的标准 |
|

这节解决什么

很多人第一次用 Codex 时，会忍不住一直盯着窗口：它是不是还在工作？是不是卡住了？是不是需要我确认？

桌面宠物解决的是“状态可视化”问题：让你不用频繁切回 Codex，也能知道任务正在进行、需要确认，还是已经完成。

适合谁

• 经常让 Codex 跑资料整理、构建、测试或长任务的人。
• 想把 Codex 放在一边工作，但又担心错过确认提示的人。
• 需要给课程学员演示“AI 正在执行任务，而不是聊天结束”的老师或助教。

这个宠物最大的价值在于状态的可视化：

1. 任务进度一目了然： 不用一直切换回 Codex 的界面，就能看到当前任务的进度。
2. 实时状态反馈：
   • 它会在 Codex 忙碌的时候显示忙碌的画面。
   • 在需要你确认的时候会发出提醒。
   • 任务完成之后，它也会让你知道可以去检查结果了。

工作流卡

| 输入 | 过程 | 输出 | 验收 |
|

最后核对

官方资料最后核对日期：2026-05-27。本章以 VS Code 为例演示插件安装与基本用法，操作界面以实际版本为准。

本章介绍如何在 VS Code 代码编辑器中安装 Codex 插件，并通过插件完成开发任务。相比桌面 App，在 VS Code 中使用 Codex 可以更直接地看到文件目录结构和修改前后的对比，适合习惯在编辑器里工作的开发者。

这节解决什么

桌面 App 适合管理任务，CLI 适合跑命令，VS Code 插件更适合处理“我正在看这几个文件，想让 Codex 就地帮我解释、修改或审查”的局部协作。

这节的目标是让你学会：把 Codex 放到编辑器旁边，但仍然由你决定上下文、范围和最终是否接受改动。

适合谁

这一节适合：

• 已经在 VS Code 里写代码或维护文档的人。
• 想让 Codex 解释当前文件、补小段代码、改 README 或审查局部 diff 的人。
• 需要边看文件边问问题，不想频繁切换桌面 App 的人。

如果你的任务需要长时间后台执行、多任务并行或 Skills 协作，桌面 App 可能更合适。如果任务主要是跑测试、改仓库和看终端输出，CLI 会更直接。

先做什么

开始前先打开一个低风险项目，并确认你知道：

1. 当前打开的是哪个工作区。
2. 哪些文件可以交给 Codex 看，哪些文件不该上传或引用。
3. 项目有没有可运行的测试、构建或预览命令。
4. 修改前后如何通过 VS Code diff 查看变化。

安装 Codex 插件

打开 VS Code，点击左侧边栏的「扩展」图标，在搜索框中输入 Codex，选择第一个结果，点击「安装」即可。

打开插件对话窗口

安装完成后，在 VS Code 中打开任意一个项目文件，右上角会出现 ChatGPT 的图标。点击该图标，右侧边栏就会展开 Codex 的对话窗口。

开始使用

对话窗口打开后，直接输入需求，Codex 就会开始辅助完成开发任务，用法与 Codex 桌面 App 基本一致。

使用 @ 指定文件：

在对话框中输入 @ 后选择具体文件，Codex 会直接定位到该文件进行分析或修改，比让它全局搜索更快、更准确。建议在任务目标明确时优先使用 @ 指定相关文件。

适合练的第一个任务

不要第一次就让插件全局重构。推荐从这些小任务开始：

• 解释当前文件的作用，并指出最重要的 3 个函数或组件。
• 给 README 增加一段安装说明。
• 根据当前测试文件补一个缺失用例。
• 让 Codex review 当前选中的代码片段，只提建议不修改。
• 把一段难读的错误信息整理成排障步骤。

一个可复制的任务模板：

请只基于我指定的文件回答，不要全局搜索，也不要直接修改文件。

目标：
1. 解释这个文件解决什么问题。
2. 标出最值得我注意的逻辑。
3. 如果要改，先给出最小改动方案。
4. 等我确认后再修改。

App 与 VS Code 插件怎么选

| | Codex 桌面 App | VS Code 插件 |
|

这节解决什么

Cloud 模式解决的是“任务需要跑一段时间、依赖 GitHub 仓库、我不想占用本机环境”的问题。它不是桌面 App 的替代品，而是另一种执行位置。

你可以把它理解成：你在浏览器里分派任务，Codex 在云端环境里读仓库、执行步骤、整理结果，必要时生成 PR 或说明修改建议。

适合谁

这一节适合：

• 已经把代码或文档放在 GitHub 仓库里的人。
• 想让 Codex 分析远程仓库、整理 issue、生成 PR 草案的人。
• 本地电脑不方便长时间跑任务，但希望任务继续推进的人。
• 团队需要把 AI 协作接入 GitHub 工作流的人。

如果任务依赖本机私有文件、桌面软件、局域网服务或本地密钥，优先使用桌面 App 或 CLI。

适合场景

• 较长的任务，不想占用本地资源
• 多个任务并行推进
• 让 Codex 在独立环境里分析仓库、提出 PR
• 不在电脑旁、只有浏览器时临时使用

先做什么

连接仓库前先确认：

1. 仓库里没有不该暴露的密钥、客户资料或私有文件。
2. 你知道要授权全部仓库，还是只授权特定仓库。
3. 任务可以通过云端仓库完成，不依赖本机 GUI 或本地服务。
4. 你知道完成后要看 diff、日志、测试结果或 PR 内容。

如何使用

第 1 步：打开 Codex Cloud

访问：https://chatgpt.com/codex/cloud

连接成功后会跳转到任务页面：

第 2 步：授权并选择仓库

Cloud 模式直接在 GitHub 仓库中运行，需要先完成授权。你可以授权全部仓库，也可以只选择特定仓库：

第 3 步：下达指令，查看任务进度

下达指令后，Codex 会在云端执行任务，进度显示在页面下方的任务列表里：

点击任务可以查看每一步的执行过程和中间状态。任务完成后也可以查看最终回答和产出内容：

适用场景

• 让 Codex 帮你在网页里搜索资料。
• 让 Codex 打开某个站点并完成简单点击流程。
• 在不离开当前工作区的前提下，把浏览器操作接入任务链路。

在半桶水课程里，它对应的是“资料查找 / 网页协作 / 人工审批”的工作流：Codex 可以帮你打开网页和整理结果，但涉及登录、提交、付款、删除的动作必须由人判断。

这节解决什么

很多工作资料在网页里：搜索结果、后台页面、帮助文档、表单状态、活动页面。浏览器能力让 Codex 能看到页面并操作页面，但这类能力比普通文档任务风险更高。

这节练的是：让 Codex 完成低风险网页操作，并学会用来源链接和截图验证结果。

工作流卡

| 项目 | 内容 |
|

所有案例截图均为作者本人实际操作所得，文字内容在参考基础上重新整理与二次创作。如有侵权，请联系删除。

对有编程经验的人来说，解决方法有很多——GitHub Pages、Vercel、Cloudflare Pages——但这些工具对普通用户并不友好：什么是分支？什么是部署？什么是域名解析？

本篇介绍一个对新手极其友好的工具：DKFile。

在半桶水课程里，它对应的是“视觉与页面 / 办公交付 / 沉淀复用”的工作流：把 AI 生成的网页从本地文件，变成别人能打开、能检查、能反馈的公网链接。

这节解决什么

很多人已经能让 Codex 生成 HTML，却卡在最后一步：怎么发布、怎么分享、怎么确认别人真的能打开。DKFile 的价值，是把部署流程压缩成上传文件和获得链接。

这节练的是：让 Codex 生成网页，并用 DKFile 发布，同时确认链接可访问、内容正确、API Key 不泄露。

工作流卡

| 项目 | 内容 |
|

Draw.io 就是一个非常好的工具。它可以用来绘制：

1. 流程图
2. 架构图
3. 思维导图
4. 系统设计图
5. 业务流程图
6. 技术路线图

很多程序员、产品经理、架构师都会用它来表达复杂系统之间的关系。前段时间，Draw.io 官方发布了自己的 MCP。

GitHub 地址：https://github.com/jgraph/drawio-mcp

本章节介绍如何使用 Codex 安装、使用 Draw.io 的 MCP 工具，去绘制信息图或架构图。

在半桶水课程里，它对应的是“内容表达 / 办公交付 / 工程协作”的工作流：把一段复杂材料，拆成节点、关系和层级，再生成可编辑的图。

这节解决什么

很多人不是不会画图，而是不知道先画什么、节点怎么分、关系怎么连。Draw.io MCP 可以让 Codex 把文字材料转成图形草稿，但图里的逻辑关系仍然需要人来判断。

这节练的是：让 Codex 先整理节点关系，再调用 Draw.io MCP 生成可编辑图形。

工作流卡

| 项目 | 内容 |
|

如果你的团队或个人经常使用飞书，那么接入飞书 CLI 之后，你就拥有了一种全新的使用方式——在 Codex 里一句话处理飞书里的所有信息和数据。

本篇介绍如何把 Codex 和飞书 CLI 结合，直接通过自然语言操作飞书中存储的数据和内容。

在半桶水课程里，它对应的是“办公交付 / 团队协作 / 资料整理”的工作流：把飞书里的文档、表格、云盘资料变成可复核的纪要、清单、报告或素材包。

这节解决什么

很多团队资料都散在飞书里：文档、表格、云盘、会议记录、任务信息。手动整理容易漏、慢，也很难重复。

这节练的是：让 Codex 通过飞书 CLI 读取和整理团队资料，但必须把权限、凭证和输出验收说清楚。

工作流卡

| 项目 | 内容 |
|

在半桶水课程里，它对应的是“视觉与页面 / 产品表达 / 研发协作”的工作流：把模糊的产品想法、页面结构或流程说明，变成可查看、可讨论、可继续设计的视觉草稿。

这节解决什么

很多非设计同学不是完全没有想法，而是说不清“页面应该长什么样”。Figma MCP 可以让 Codex 读设计稿、生成流程图或高保真草稿，但最终审美、业务逻辑和可用性仍然要由人判断。

这节练的是：让 Codex 把想法变成设计草稿，同时学会检查结构、信息层级和可交付性。

工作流卡

| 项目 | 内容 |
|

演示用的是一个购物车项目。

在半桶水课程里，它对应的是“工程协作 / 自动化 / 验证闭环”的工作流：让 Codex 处理重复排障步骤，但把最终合并权留给人。

这节解决什么

CI 失败后，最耗人的不是修一行代码，而是打开日志、定位失败、切分责任、跑验证、整理 PR。这个案例练的是：让 Codex 自动生成一个最小修复候选，但必须通过测试和人工 review 才能进入主分支。

工作流卡

| 项目 | 内容 |
|

1. Remotion：使用 React 写视频
2. HyperFrames：使用 HTML、CSS 或 JS 做视频

如果你想做一些轻量化的视频，比如网页转视频、文档转视频等，那么使用 HyperFrames 就是一个非常不错的选择。

在半桶水课程里，它对应的是“视觉与页面 / 内容表达 / 办公交付”的工作流：把一段内容、一本书或一个观点，转成短视频脚本、分镜画面和可预览的视频文件。

这节解决什么

很多人想做视频，但不知道从哪里开始：先写脚本，还是先做画面？要几页？每页多久？HyperFrames 的价值，是把视频拆成代码化页面和渲染流程，让 Codex 可以逐步生成、预览和修改。

这节练的是：让 Codex 先拆脚本和分镜，再用 HyperFrames 生成可预览的视频产物。

工作流卡

| 项目 | 内容 |
|

前段时间，AI 领域的著名研究者 Andrej Karpathy 提出了一个新想法。他认为 RAG 的主要问题在于：每一次提问，模型都要从零开始重新发现知识。如果你问了一个需要综合五篇文档的问题，RAG 会检索、拼接、生成；如果你明天再问同样的问题，它会重复整个过程，没有任何积累，也没有任何记忆。本来可以建立关联的知识，却在一次又一次的反复查询中被浪费掉了。

Karpathy 给出的解决方案是 LLM Wiki。他描述的系统分为三层：

1. 原始资料层 — 负责收集论文、文章、播客、网页等素材。大模型对这一层只读不改。
2. Wiki 层 — 大模型拥有这一层的完整所有权。它负责编写 Markdown 文件、目录、摘要、实体概念、比较分析和综述，创建页面、更新页面，并维护交叉引用。我们只需要负责阅读。
3. Schema 层 — 一个配置文件，例如对于 Codex 来说就是 AGENTS.md，对于 Cursor 来说就是 .cursorrules。告诉大模型这个 Wiki 的结构规范、命名约定和工作流程，并在使用过程中共同迭代这份文件。

本篇介绍如何参考 Karpathy 的理念，在 Obsidian 里借助 Codex 搭建一套 LLM Wiki 知识库。

在半桶水课程里，它对应的是“资料整理 / 沉淀复用 / 个人知识系统”的工作流：不是把资料一次性丢给 AI，而是让 Codex 持续把原始材料整理成可链接、可更新、可复用的 Wiki。

这节解决什么

普通资料整理常常停在“总结一下”。LLM Wiki 练的是更长期的能力：原始资料只读，Wiki 页面持续更新，规则文件约束 Codex 怎么命名、怎么引用、怎么维护结构。

这节练的是：让 Codex 建一个有规则的知识库，而不是生成一堆散乱摘要。

工作流卡

| 项目 | 内容 |
|

在半桶水课程里，它对应的是“资料整理 / 内容表达 / 团队知识库”的工作流：把散落在 Notion 里的页面、数据库和项目记录，变成可复核的摘要、清单或新页面。

这节解决什么

Notion 里的信息通常不是少，而是太散：项目页、会议页、数据库、灵感记录、团队文档混在一起。Notion MCP 的价值，是让 Codex 在授权范围内读取这些内容，帮你整理结构、提炼重点，并把整理后的结果写回工作空间。

这节练的是：让 Codex 读懂你的知识空间，但只在你允许的范围内读取和写入。

工作流卡

| 项目 | 内容 |
|

内容创作者以前有一件很头疼的事：给文章配图。但自从 Codex 命令行可以直接调用 ChatGPT 最新的生图模型 gpt-image-2 之后，我们就可以在 Obsidian 里让 Codex 根据文章内容自动生成配图。

在半桶水课程里，它对应的是“内容表达 / 资料整理 / 沉淀复用”的工作流：让 Codex 在本地知识库里读文章、生成素材、插入链接，并保留可复核的文件路径。

前提条件：

1. 了解 Obsidian 的基本操作
2. 熟悉 Codex 命令行的使用方式（参见本教程第二部分）

这节解决什么

很多内容创作者不是不会写，而是卡在后续整理：配图、图片链接、文章素材、引用位置和发布前检查。Obsidian 的优势是本地文件清晰，Codex 的优势是能读写这些 Markdown 文件并调用生成能力。

这节练的是：让 Codex 在本地知识库里辅助创作，但每张图、每个链接、每次写入都能回到文件里检查。

工作流卡

| 项目 | 内容 |
|

像 Codex 这类编程类的 Agent，不仅能够编写和修改代码，还能够打开网页，像人一样检查页面是否跑通。

本章节使用命令行的方式，来学习 MCP 的安装和使用。在半桶水课程里，它对应的是“网页检查 / 资料整理 / 自动化验证”的工作流。

这节解决什么

很多网页任务不能只靠文字判断，例如“按钮能不能点”“表单有没有提交成功”“页面是否真的出现结果”。Playwright MCP 的价值，是让 Codex 能打开页面、操作页面、截图和回报状态。

这节练的是：让 Codex 操作浏览器，但每一步都要有边界、有授权、有验收。

工作流卡

| 项目 | 内容 |
|

在半桶水课程里，它对应的是“内容表达 → 视觉与页面”的工作流：把一个模糊主题，变成可预览、可修改、可交付的演示稿。

适用场景

• 你已经找到一个想用的社区 Skill。
• 你想让 Codex 帮你完成安装，而不是手动整理目录和文件。
• 你希望安装后立刻用一个真实任务验证它是否可用。

这节解决什么

很多人以为 PPT 生成就是“丢一句主题，等 AI 变出成品”。真正稳定的方式是先把主题变成任务卡：受众是谁、讲多久、要说服谁、输出什么格式、怎么验收。

这节练的是：让 Codex 安装并调用 PPT Skill，同时让你学会检查结构、视觉和导出结果。

工作流卡

| 项目 | 内容 |
|

你的代码跑在云服务器上，本地一行代码都没有——Codex 照样能帮你找到 Bug、修好它、跑通测试。这篇文章手把手带你走一遍完整流程。

在半桶水课程里，它对应的是“工程协作 / 配置排障 / 验证闭环”的工作流：让 Codex 进入远程环境排查问题，但每一步都要可复现、可回滚、可审查。

这节解决什么

远程服务器排障难在环境不在本机：代码、依赖、日志、容器和测试都在远端。Codex Remote Mode 的价值，是让 Codex 在真实运行环境里读文件、运行命令、修改代码并验证。

这节练的是：连接远程环境后，只修一个可复现的小 Bug，并用测试证明修复有效。

工作流卡

| 项目 | 内容 |
|

三种使用姿势

| 模式 | 适合任务 | 典型命令 |
|

配置文件放在哪里

通常位于：

~/.codex/config.toml

项目长期规则建议写到仓库内的 AGENTS.md，个人偏好放到本机 config.toml。这样团队成员能共享项目规则，又能保留自己的 CLI 使用习惯。

最小配置示例

下面是一个学习用示例，实际字段请以官方 config reference 和当前 CLI 版本为准：

model = "gpt-5.1-codex-max"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.build]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

这个示例表达三件事：

• 默认允许在当前工作区写文件。
• 高风险命令仍需要审批。
• 额外保留一个只读 profile，适合新仓库分析。

常见配置项按用途理解

| 用途 | 你要决定什么 | 建议 |
|

这页解决什么

很多人一开始会把“配置”理解成改一堆开关。半桶水式学习更关心另一件事：配置要服务于稳定交付。

这一页帮你把配置分成四层：项目规则、本地配置、扩展能力和安全边界。先把任务规则写清楚，再逐步调整工具能力。

适合谁

• 已经能完成一个 Codex 小任务，准备把流程稳定下来的人。
• 想把自己的常用任务沉淀成 AGENTS.md、Skill 或团队规范的人。
• 需要理解沙盒、审批、MCP、Skills 和安全边界的人。

工作流卡

| 输入 | 过程 | 输出 | 验收 |
|

三个概念

| 能力 | 解决的问题 | 适合沉淀什么 |
|

先分清风险等级

| 风险等级 | 例子 | 建议策略 |
|

桌面 App 适合什么

• 本地仓库中的长任务和多阶段任务。
• 同时推进多个不互相阻塞的任务。
• 使用 Worktrees 隔离不同实现分支。
• 把重复流程写成 Skills。
• 用 Automations 做提醒、定期检查或后续跟进。
• 配合浏览器、文档、表格、演示文稿等插件做跨工具工作。

核心能力地图

| 能力 | 用途 | 学习重点 |
|

适用场景

• 连接 GitHub 仓库后发起任务。
• 让 Codex 阅读仓库并总结架构。
• 将 issue 转成可执行任务。
• 生成 PR 摘要或变更说明。
• 面向非开发者解释技术改动。
• 把复杂任务拆成阶段计划。

第一次任务怎么写

先让 Codex 只读分析：

请阅读这个仓库并帮我理解 [主题]。请先总结相关目录和关键文件，再给出执行建议。暂时不要修改代码。

进一步推进时：

请基于刚才的分析，完成第一步最小改动，并创建可审查的结果。请说明改动原因、验证方式和剩余风险。

适合非开发者的用法

| 场景 | 任务说明 |
|

CLI 能做什么

• 只读理解仓库结构、入口、测试命令和风险点。
• 修改代码、文档、配置和测试。
• 运行 lint、typecheck、unit test、build 等验证命令。
• 在终端里查看 diff、调整审批策略、恢复会话。
• 通过 codex exec 执行标准化的一次性任务。
• 配合 AGENTS.md、config.toml、Skills、MCP 构建长期工作流。

推荐学习顺序

1. 安装 CLI 并完成登录。
2. 在陌生仓库中做一次只读总结。
3. 学会交互模式中的常用 Slash Commands。
4. 完成一次低风险修改，并运行验证。
5. 学会 codex exec，把可重复任务脚本化。
6. 增加 AGENTS.md 和本地 config.toml。

交互模式

进入项目根目录：

cd path/to/project
codex

第一轮建议不要直接让 Codex 改代码。先让它建立地图：

请只读分析当前仓库，不要修改文件。

请输出：
1. 项目用途
2. 主要目录和入口文件
3. 安装、启动、测试、构建命令
4. 当前仓库对 Codex 来说最需要注意的风险
5. 适合第一次交给 Codex 的 5 个低风险任务

非交互模式

codex exec 更适合批处理和自动化：

codex exec "请只读分析当前仓库，输出安装、测试和构建命令。不要修改文件。"

建议让输出格式稳定：

请读取当前仓库，不要修改文件。

输出格式：
## 项目概览
## 本地运行
## 测试命令
## CI 风险
## 适合 Codex 处理的任务

适合脚本化的任务：

| 任务 | 产出 |
|

Cloud 适合什么

• 连接 GitHub 仓库后分派任务。
• 在后台处理长时间修复、迁移或分析。
• 基于 issue 或需求生成分支和 PR。
• 团队成员共同查看任务进度。
• 为大型仓库做结构分析和风险扫描。

提交任务前的清单

| 检查项 | 为什么重要 |
|

IDE 适合什么

• 解释当前文件或选中代码。
• 为一个函数补测试。
• 局部重构。
• 生成注释、文档或类型说明。
• 审查当前 diff。
• 快速理解错误信息和调用链。

选区任务写法

选区越准确，结果越稳定。推荐模板：

请只基于当前选中的代码解释：
1. 它在模块中的职责
2. 输入输出和副作用
3. 可能的边界情况
4. 如果要补测试，建议覆盖哪些场景

如果允许修改：

请只修改当前文件和对应测试文件。

目标：为当前函数补充边界测试。
要求：
1. 先解释测试场景。
2. 修改后运行相关测试。
3. 不做无关重构。

IDE 中的高频任务

| 任务 | 推荐输入 | 结果检查 |
|

这页解决什么

很多新手卡住，不是因为不会点按钮，而是不知道“这个任务应该从哪里开始”。同一个 Codex，可以出现在 CLI、桌面 App、Cloud、IDE 和 ChatGPT 里；入口不同，适合的任务和风险边界也不同。

这一页帮你先做入口选择：先用低风险入口跑通任务，再逐步进入更复杂的配置和团队协作。

适合谁

• 还分不清 CLI、桌面 App、Cloud、IDE 和 ChatGPT 中 Codex 区别的人。
• 想给团队成员安排统一学习路径的人。
• 已经会用一个入口，但不知道什么时候该换另一个入口的人。

工作流卡

| 输入 | 过程 | 输出 | 验收 |
|

方法地图

| 主题 | 解决什么问题 | 适合阶段 |
|

半桶水式学习的重点不是“非开发者也能用高级工具”，而是：把你每天最耗时间、最重复、最容易卡住的工作，拆成 AI 能帮忙的步骤和你必须判断的步骤。

这节课解决什么问题

非技术工作者常见的卡点是：

• 资料太多，不知道先看什么。
• 想写内容，但第一版总是很慢。
• 会议记录、表格、客户跟进反复占用时间。
• 想做 PPT、网页或提案，但不知道怎么开头。
• 担心 AI 胡说，又不知道怎么验收。

这节课训练你用 Codex 完成 4 类工作流：资料整理、内容生产、办公交付、知识沉淀。

工作流一：资料整理

适合任务：

• 把客户资料整理成提案重点。
• 从一组网页、PDF 或 Markdown 中提取关键信息。
• 把散乱文件夹整理成目录说明。
• 给陌生项目生成阅读路线。

任务卡：

请阅读我提供的资料，帮我整理一份“可用于下一步工作的摘要”。

目标：
- 提炼关键信息，不要逐字复述。
- 标出不确定或缺少来源的地方。

边界：
- 不编造数据。
- 不替我做最终商业判断。

交付：
- 背景摘要
- 关键发现
- 可引用材料
- 下一步行动清单

验收标准：你能回到原始材料中找到关键结论的来源。

工作流二：内容生产

适合任务：

• 写公众号、小红书、短视频脚本或课程文案初稿。
• 把一个想法扩写成提纲。
• 把技术内容翻译成普通人能懂的表达。
• 为同一主题生成不同平台版本。

人类判断点：

• 选题是否真的有价值。
• 表达是否符合你的品牌气质。
• 事实和案例是否可靠。
• 是否需要删掉夸张或过度承诺。

任务卡：

请根据下面材料生成一版内容初稿。

读者：第一次接触 AI 工作流的非技术工作者。
语气：专业、通俗、有温度，不要夸张营销。
边界：不编造案例，不承诺无法验证的结果。
交付：标题、开头、正文结构、结尾行动建议。

工作流三：办公交付

适合任务：

• 把会议记录变成纪要和任务表。
• 把聊天记录整理成客户跟进清单。
• 把零散需求整理成项目计划。
• 把表格字段解释成可读报告。

建议让 Codex 输出两层内容：

| 层级 | 内容 |
|

这节解决什么

很多失败任务不是因为 Codex 不会做，而是因为任务本身太散：

• “帮我优化一下”没有说明优化到什么程度。
• “整理资料”没有说明资料来源、输出格式和判断标准。
• “改一下代码”没有说明哪些地方不能碰、怎么验证是否改对。

这一节帮你建立一张任务卡：让 Codex 知道要做什么，也让你知道最后怎么判断结果能不能用。

适合谁

• 第一次发现 Codex 结果“看起来很努力，但不是我要的”的学习者。
• 经常处理资料整理、文案初稿、PPT、表格、网页和项目文件的人。
• 想把一次成功经验沉淀成团队模板、个人 Skill 或 AGENTS.md 规则的人。

工作流卡

| 项目 | 你要写清楚什么 | 不写清楚的风险 |
|

团队最容易出问题的地方不是“AI 不够聪明”，而是：每个人给 Codex 的边界不同、验收标准不同、风险意识不同。最后结果看起来热闹，但没人敢放心复用。

这节课解决什么问题

团队落地要解决 4 件事：

1. 让 Codex 知道项目规则。
2. 让每次任务都有验证证据。
3. 让高风险动作有人确认。
4. 让成功经验沉淀成模板，而不是停留在某个人的聊天记录里。

团队接入清单

| 项目 | 建议 | 验收标准 |
|

第一阶段：骨架完整

• 建立 VuePress + Theme Hope 文档站。
• 建立 README、贡献指南、行为准则和安全政策。
• 搭建入门、进阶、团队和案例目录。
• 添加官方资料索引。
• 补充第一批截图和命令输出。
• 给每篇教程增加“适用版本”和“最后核对日期”。

第二阶段：指南成型

• 完成 CLI 从安装到日常使用的完整教程。
• 完成 AGENTS.md 专题。
• 完成提示词模板库。
• 完成排障手册第一版。
• 补齐 Cloud、IDE、桌面 App 的使用差异。

第三阶段：案例驱动

• 收集 20 个真实工程案例。
• 每个案例包含任务说明、关键过程、验证方式和复盘。
• 建立案例标签：前端、后端、测试、重构、文档、CI、安全。
• 补充失败案例，说明 Codex 不适合直接处理的场景。

第四阶段：社区传播

• 设计更完整的首页和 Open Graph 图。
• 建立中英文关键词索引。
• 发布 GitHub Pages。
• 整理适合社媒传播的短链接和学习路线图。
• 邀请早期贡献者认领章节。

贡献入口

你可以从这些任务开始：

• 修正文档里的不准确表述。
• 新增一个你亲自跑过的 Codex 案例。
• 给排障手册补一个常见错误。
• 把官方文档的新变化同步到资料索引。

先选一个真实但低风险的工作任务，跑通一次，再把成功经验沉淀成下次还能用的工作流。

第 0 步：先带一个真实问题进来

不要用“我要学 Codex”作为起点。这个目标太大，也太空。

更好的起点是：

• 我有一堆资料，想整理成客户提案重点。
• 我想把会议记录变成纪要、任务表和下一步行动。
• 我想让 Codex 检查一个文件夹，告诉我项目结构和风险。
• 我想改一篇 README，让它更适合新用户阅读。
• 我想把一个想法变成 PPT 大纲、网页草稿或内容计划。

如果你能说清楚一个真实任务，Codex 才有机会帮你完成一个真实结果。

五阶段学习路径

| 阶段 | 学习目标 | 推荐页面 | 验收标准 |
|

这节课解决什么问题

如果你不是开发者，可以先跳过 CLI，从 课程入口 和 桌面 App 开始。

如果你准备让 Codex 进入本地项目、读取仓库、运行测试、修改代码或批量整理文件，CLI 会更贴近真实工程现场。它的学习目标不是“会敲命令”，而是：能在一个项目目录里，让 Codex 做有边界、可验证的任务。

安装前检查

官方仓库当前给出的 CLI 运行环境建议：

| 项目 | 建议 |
|

这节解决什么

这节不是教你把代码任务全部交给 AI，而是练一件很关键的事：让 Codex 在一个真实仓库里做最小改动，并用测试、diff 和总结证明它没有乱改。

适合谁

这一节适合已经完成 CLI 安装与登录，并且手上有一个可以练习的本地仓库的人。

如果你完全不熟悉终端，可以先用桌面 App 跑通 第一个任务，再回来做这节。CLI 的优势是离代码和验证命令更近，但它也更要求你看得懂命令和文件改动。

先做什么

开始前先确认：

1. git status 是干净的，或者你知道哪些改动是自己已有的。
2. 项目有一个能运行的测试、构建或文档验证命令。
3. 任务范围足够小，最好只影响 1-3 个文件。
4. 不涉及密钥、生产数据、发布部署和大范围删除。

选择第一个任务

适合新手：

• 修复一个文案错别字。
• 给一个纯函数补测试。
• 更新 README 里的过期命令。
• 解释一个小模块，并补充必要注释。
• 修复一个已经有失败测试覆盖的 bug。
• 为文档站补一段截图说明或补图清单。

暂时避开：

• 大规模架构重构。
• 跨多个服务的迁移。
• 没有测试的核心业务逻辑改动。
• 涉及生产凭据、账单、权限和删除数据的操作。
• 需要同时修改十几个文件的需求。

第一步：只读建图

先让 Codex 理解仓库：

请只读分析当前仓库，不要修改文件。

请输出：
1. 项目用途
2. 关键目录
3. 安装、测试、构建命令
4. 当前任务适合从哪里开始
5. 你建议我第一次交给你的低风险任务

第二步：给出小任务

推荐复制这个模板：

请修复当前仓库中最小范围的一个测试失败。

要求：
1. 先运行测试，确认失败信息。
2. 阅读相关代码和测试，不做无关重构。
3. 修改最少必要文件。
4. 修复后重新运行相关测试。
5. 最后总结：失败原因、改了哪些文件、验证命令和剩余风险。

如果任务是文档：

请更新 [文档文件] 中关于 [主题] 的说明。

要求：
1. 先读取相关官方资料和现有文档结构。
2. 保持中文教程风格，避免整段翻译官方原文。
3. 涉及操作步骤时标出建议配图的位置和截图内容。
4. 修改后运行文档站构建。
5. 最后列出来源链接和需要人工补图的位置。

第三步：观察过程

重点观察五件事：

| 观察点 | 说明 |
|

半桶水式理解：如果一个规则你不想每次都重复解释，就应该写进 AGENTS.md。

为什么需要 AGENTS.md

没有项目规则时，Codex 需要从仓库里推断很多事情：

• 用哪个包管理器。
• 如何运行测试。
• 哪些目录是生成物。
• 哪些文件不能改。
• 提交前要跑哪些检查。

AGENTS.md 能把这些规则显式写下来，减少反复解释。

这节课解决什么问题

很多新手以为 Codex “应该自己懂项目”。但真实项目里，很多关键规则不是靠猜能知道的：

• 构建命令到底是 pnpm build、npm run build 还是别的？
• 哪些目录是生成物，不能手改？
• 文档改动要不要跑构建？
• 哪些安全边界不能碰？
• 最终回复应该说明哪些验证结果？

AGENTS.md 的作用就是把这些隐性规则变成显性规则。

建议放在仓库哪里

针对于我们打开的项目，我们可以在项目根目录下创建一个 agents.md 的文件。

它是 Codex 的记忆文件，Codex 在开始工作之前会先读取 agents.md 的内容。我们可以测试一下：

1. 在 agents.md 文件里面写入一些内容。

1. 回到 Codex 对话窗口问它：“这是一个什么样的系统？”

从这里可以看出，Codex 会读取 agents.md 文件，把里面的内容自动带入到新的对话，作为它们的上下文。

当然，在当前目录根目录下创建 agents.md 只对当前文件夹生效，并不是全局生效的。

如果想要全局生效，有以下两种方式：

1. 在系统的全局 Codex 文件夹里面找到 agents.md。
2. 在 Codex 桌面 App 里面打开设置，找到“个性化”，在其中填写“自定义指令”。这里面设置的就是全局的 agents.md 文件。

设置全局文件后，对于所有的项目都会生效。所以它们的作用域和作用范围是不一样的，这一点大家需要了解一下。

团队共享规则和本地私有规则

多人协作时，AGENTS.md 适合保存团队共同认可的项目规则；个人路径、本机工具习惯、临时约束和私有工作流偏好，则更适合留在本地。这样团队规则保持稳定，个人习惯也不会被提交到仓库。

使用场景

下面这些内容适合放在本地私有规则里：

• 本机缓存、SDK、脚本或临时目录路径。
• 个人常用命令、别名、编辑器习惯。
• 只对自己有效的语言风格、回复格式、验证偏好。
• 不方便进入团队文档的临时限制，例如“今天先只做只读分析”。

文件分工

| 文件 | 作用 | 是否提交到 Git |
|

你需要关心什么

先把风险拆成几个层面：

• 文件系统：能读写哪些目录。
• 网络：是否允许访问外网。
• 命令：是否允许安装依赖、启动服务、跑迁移。
• 凭据：是否可能接触密钥、token、cookie。
• 数据：是否会修改数据库、对象存储或生产资源。

这节课解决什么问题

很多人第一次看到审批弹窗会紧张：到底该点允许，还是拒绝？

你不需要记住所有底层机制。先学会一个判断法：

看不懂影响范围，就先不要放行。能说清楚影响范围，再决定是否继续。

审批不是拖慢效率，而是给你一个停顿点：确认 Codex 要做的事，是否仍然符合你的目标和边界。

低风险任务

通常可以较快推进：

• 修改文档。
• 补充测试。
• 修复本地可复现 bug。
• 更新非敏感配置。
• 运行项目已有的测试命令。

高风险任务

建议先确认计划：

• 删除文件或批量移动文件。
• 数据库迁移。
• 修改认证、权限、支付、账单逻辑。
• 访问生产服务。
• 上传、下载或处理敏感数据。
• 引入新依赖或大规模升级依赖。

审批弹窗怎么看

| 你看到的动作 | 先问自己 |
|

半桶水式学习里，失败不是“AI 不行”的证据，而是一次把边界、材料、任务卡和验证方式补清楚的机会。本页按常见症状整理处理路径。

排障先做三件事

1. 保留现场：不要急着清空对话或删除文件，先保存报错、截图、命令输出。
2. 分层判断：是项目上下文问题、权限问题、环境问题，还是任务描述问题？
3. 缩小范围：让 Codex 先只读分析，不要边猜边大改。

Codex 找不到项目上下文

可能原因：

• 你不在项目根目录。
• 仓库缺少 README、测试命令或项目说明。
• monorepo 没有说明包边界。
• 新对话没有继承你上一轮口头说明。

处理方式：

• 先让 Codex 只读目录并总结项目结构。
• 添加或更新 AGENTS.md。
• 在任务说明里指定相关目录。
• 把“项目是什么、怎么跑、哪些不能动”写成固定任务卡。

Codex 改动范围太大

处理方式：

• 明确“只修改这些文件”。
• 要求“先输出计划，不要动手”。
• 把任务拆成更小的步骤。
• 在 review 时拒绝无关重构。

可以这样说：

这次改动范围太大。请先停止继续修改，只总结你已经改了哪些文件、哪些改动和原目标直接相关、哪些可能需要撤回。不要继续编辑文件。

测试跑不起来

先区分两类问题：

| 类型 | 表现 | 处理方式 |
|

半桶水式案例学习法

每个案例都建议按 5 个问题学习：

| 问题 | 你要看什么 |
|

最后核对日期：2026-05-27。

OpenAI 官方

• Codex 产品页：Codex 的产品定位、使用界面和团队能力概览。
• Codex in ChatGPT Help Center：计划可用性、入口和常见问题。
• OpenAI Codex CLI Getting Started：CLI 入门、安装和基础能力。
• Codex 文档入口：Codex 桌面 App、CLI、Cloud、配置、安全、Skills、MCP 等官方文档入口。
• Codex cloud docs：云端任务、GitHub 连接和仓库工作流入口。
• Introducing Codex：Codex 发布背景和云端软件工程代理介绍。
• Introducing the Codex app：Codex 桌面 App 相关介绍。
• Work with Codex from anywhere：ChatGPT 手机 App 中的 Codex 入口、跨设备连接和可用性说明。
• Unrolling the Codex agent loop：Codex agent loop 背后的工作方式介绍。

官方文档重点页面

• Codex App docs（桌面端）：桌面 App 功能入口，包含本地项目、Review、Automations、Worktrees、Local Environments、In-app Browser、Computer Use 等主题。
• Codex CLI features：CLI 交互模式、非交互模式、功能概览。
• AGENTS.md：项目规则文件的官方说明。
• Codex security：沙盒、审批和安全边界。
• Codex config basic：基础配置。
• Codex config advanced：高级配置。
• Codex config reference：完整配置参考。
• Codex skills：Skills 官方说明。
• Codex Cloud docs：云端任务、环境、仓库连接和任务执行入口。

GitHub 官方仓库

• openai/codex：Codex CLI 开源仓库。
• AGENTS.md 相关文档：项目规则文件相关说明。
• CLI getting started：CLI 首次使用流程。
• Authentication：认证和登录相关说明。
• Exec：非交互模式相关说明。
• Slash Commands：CLI 会话命令说明。
• CLI 安装与构建：系统要求、源码构建和日志说明。
• CLI 配置：配置文档索引。
• Sandbox 文档：沙盒与审批官方入口。
• Exec Policy：命令执行策略相关说明。
• Skills：CLI 仓库中的 Skills 文档。

如何使用这些资料

• 入门安装优先看 Help Center 和 GitHub README。
• 了解产品边界优先看 OpenAI Codex 产品页。
• 做团队接入时优先看 Help Center、平台文档、App 文档和企业相关说明。
• 写教程时不要整段翻译原文，应转化成中文场景和可复现步骤。
• 涉及价格、计划、模型、可用地区、功能开关、账号权限时，必须打开原文重新确认。

这张矩阵不按工具入口分类，而是按真实工作能力分类。你可以先找到自己最常遇到的工作问题，再决定从哪一类任务开始练。

怎么用这张矩阵学习

先不要追求一次学完所有能力。更稳的方式是每次只选一个能力域，带着一个真实但低风险的任务练完闭环。

1. 选一个能力域：比如“资料整理”或“办公交付”。
2. 写一张任务卡：说明目标、材料、边界、验证和交付格式。
3. 让 Codex 执行：观察它读了什么、改了什么、有没有说明不确定点。
4. 做人工判断：确认事实、语气、风险、权限和最终用途。
5. 沉淀模板：把这次成功的任务改成下次能复用的提示词、流程或规则。

如果你不知道从哪里开始，优先选“资料整理”。它风险低、反馈快，也最容易让你理解“AI 起草，人来判断，结果要验收”的基本节奏。

六个能力域

| 能力域 | 适合练习的任务 | 进阶方向 |
|

它更像一次工作方式改造：带着你自己的真实问题进来，用 Codex 跑通一个小任务，再把它整理成可以重复使用的 AI 工作流。

适合谁

如果你每天都在处理这些事情，这门课就适合你：

• 资料很多，但不知道怎么快速整理成重点。
• 想写内容、方案、脚本、提案，但总卡在第一版。
• 会议纪要、表格、客户跟进和文件整理占掉太多时间。
• 想做 PPT、网页、图片、视频，但不知道怎么把 AI 串成流程。
• 听说 Codex 能改代码、跑命令、读项目，但不知道非技术工作者能怎么用。

课程主要面向非技术工作者，也兼容零基础开发者。区别只在入口不同：非技术工作者先从桌面 App 和真实工作任务开始，开发者可以更早进入 CLI、AGENTS.md 和项目验证。

你会学到什么

| 模块 | 你要学会的事 | 交付物 |
|

本规格用于指导 CodexGuide 的渐进式课程化改造。当前执行策略是：先保证课程骨架、入口、核心入门页、案例页和轻量交互可运行，再进入视觉一致性和内容质量审查。

• Phase 1：课程骨架、首页、课程入口和轻量交互已进入可构建状态。
• Phase 2：核心入门章节已按“小白友好 + 验收标准”方向改造，后续继续补齐非核心页。
• Phase 3：案例库已从工具清单改为工作流场景课，credits.md 保持来源致谢属性。
• Phase 4：已采用 VuePress 全局组件实现学习地图、任务拆解器、工作流护照和能力矩阵；AetherViz Master 暂作为后续动态教学图参考，不引入重型 3D。
• Phase 5：进入构建、链接、截图、移动端和内容 QA 的循环验证。

目标

把当前 CodexGuide 改造成半桶水主导的 Codex 小白学习课程站。它不只是解释 Codex 有哪些入口和配置，而是帮助学习者从真实工作问题出发，学会把 Codex 放进自己的资料整理、内容生产、办公交付、网页/PPT/视觉表达和开发协作流程里。

改造不能把原项目变成一个只有营销口号的页面。它必须继续保留 CodexGuide 的资料价值，同时用课程结构把学习顺序、判断点和验收标准讲清楚。

受众

• 主要受众：非技术工作者，包括老板、主理人、运营、内容创作者、设计师、销售顾问、行政办公和培训老师。
• 兼容受众：零基础开发者和想把 Codex 用进真实仓库的人。
• 学习者共同状态：听过 AI 很强，但不知道怎么把它稳定放进自己的日常工作。

内容原则

• 从场景进入，不从工具名进入。
• 每一页都回答：为什么学、什么时候用、怎么开始、哪里需要人判断、怎么验收。
• 避免低幼化、被动喂养式和过度承诺式表达，改成“真实工作者一步步长出能力”。
• 保留专业边界：涉及账号、权限、命令、费用、隐私和安全时，要明确提醒。
• 课程承诺固定为：帮助学习者用 Codex 把真实工作改造成可验证、可复用的 AI 工作流。

叙事风格

半桶水风格要保持三件事：

• 通俗：少讲术语堆叠，多讲真实工作里的动作和判断。
• 专业：账号、权限、隐私、费用、生产环境、医疗法律金融等边界必须明确。
• 人性化：承认学习者一开始会不确定，但不把学习者写成被动等待喂养的人。

避免使用低幼化、过度承诺和暗示 AI 可以替代人工判断的表达。推荐使用“先跑通一个低风险任务”“用验收标准判断结果”“把一次成功沉淀成模板”等表达。

信息架构

采用 5 层学习路径：

1. 看见 AI 能做什么：理解 Codex 不是聊天框，而是能读文件、跑命令、整理流程的工作伙伴。
2. 跑通第一个低风险任务：用桌面 App 或 CLI 完成一次可复核的小任务。
3. 学会任务拆解与验证：把目标、材料、边界、验证和交付说清楚。
4. 建立个人工作流：把一次成功任务保存成模板、Skill、案例或团队规则。
5. 形成工作流护照：记录自己的工具组合、常用任务、素材库、风险边界和下一步升级计划。

页面改造

• 首页：半桶水课程入口，突出真实工作痛点、5 层学习路径、三类人群路线、交互练习和精选案例。
• 学习路线：从“入口分类”改为“小白如何由浅入深学习 Codex”。
• 课程入口 /course/：解释 3 天线下 + 4 周陪跑如何与站内教程对应。
• 导航：新增“课程入口”，保留 Codex 入门、工作流案例、配置排障。
• 侧栏：新增 /course/ 分组，首页 fallback 也加入课程入口。

教学页面模板

核心教学页应尽量靠近以下结构。不是每页都机械套满，但至少要让学习者知道为什么学、怎么做、怎么验收。

1. 这节解决什么：用真实工作问题开场。
2. 适合谁：告诉不同起点的人如何进入。
3. 工作流卡：说明输入、过程、输出、验收。
4. 操作步骤：保持具体、可执行、不过度堆概念。
5. 你要重点检查什么：标出人的判断点。
6. 验收标准：说明什么叫完成，而不是只讲步骤。
7. 复用方式：把一次任务沉淀成模板、案例、Skill 或团队规则。
8. 风险边界：涉及敏感信息、账号权限、生产环境和专业建议时显性提醒。

案例页模板

案例页不是展示“这个工具很厉害”，而是展示“这个工作流如何迁移到你的工作”。

• 场景：这件事在真实工作里解决什么问题。
• 输入：需要准备哪些文件、链接、账号、素材或背景。
• 过程：Codex 做哪些动作，人在哪些节点判断。
• 输出：最终得到什么交付物。
• 验收：如何检查结果正确、可用、可交付。
• 复用：如何换成自己的行业材料。
• 边界：哪些内容不能让 AI 直接决定。

交互组件

• LearningPathMap：展示 5 层学习路径，每层对应目标、行动和验收。
• TaskBriefBuilder：让学习者把模糊需求拆成目标、材料、边界、验证和交付。
• WorkflowPassport：预览最终工作流护照结构，让学习者知道课程终点是什么。
• CapabilityMatrix：帮助学习者从资料整理、内容表达、办公交付、视觉页面、工程协作和沉淀复用中选择练习入口。

如果 AetherViz Master 可用，后续用于动态学习地图和能力矩阵；如果不可用，继续使用 VuePress 全局 Vue 组件、SVG 和 CSS 实现。

视觉方向

视觉目标是“专业、克制、有人味”，而不是强营销或重装饰。

• 首页和课程页可以更有引导感，但正文页要优先可读。
• 卡片用于重复项目、交互组件和信息块，不把每个段落都做成卡片。
• 色彩以清晰层级和状态表达为主，避免单一色系铺满页面。
• 移动端优先保证文字不溢出、交互控件可点击、侧栏导航可理解。
• 动态交互只服务教学理解，不为了炫技增加学习负担。

分阶段实施

Phase 1：课程骨架改造

范围：

• 首页改为“半桶水 Codex AI 工作流实战课”。
• 新增 /course/ 和能力矩阵入口。
• 改造学习路线、导航、侧栏和 SEO。
• 注册轻量交互组件。

验收：

• 首页、课程入口、学习路线和案例入口可访问。
• 新手能在 1 分钟内判断自己应该从哪里开始。
• 构建通过，桌面和移动端首屏不出现明显遮挡。

Phase 2：教学模板统一

范围：

• 优先改造 App 入门、第一个任务、任务执行、权限、Skills、CLI、IDE、AGENTS.md、沙盒和排障。
• 补强任务设计页，让它成为课程里的核心方法页。

验收：

• 核心页包含学习目的、适合人群、判断点和验收标准。
• 敏感操作都有边界提醒。
• 不把 Codex 描述成无需人工判断的万能按钮。

Phase 3：案例课程化

范围：

• 把 PPT、浏览器、知识库、飞书、Figma、Notion、远程排障、CI、医学文献、视觉生成和安卓协同等案例改造成工作流场景课。
• credits.md 保持参考来源与致谢，不强行套教学模板。

验收：

• 案例页说明输入、过程、输出、验收和复用方式。
• 高风险案例有明确人工复核和权限边界。
• 案例总览能按工作场景引导，而不是只列工具名。

Phase 4：交互与视觉增强

范围：

• 用 VuePress 组件承载学习地图、任务拆解器、工作流护照和能力矩阵。
• 需要动态教学图时，优先参考 AetherViz Master 的教学可视化方法；当前阶段保持轻量实现。

验收：

• 组件不依赖外部服务。
• 键盘可访问，移动端不横向溢出。
• 交互能帮助学习者做选择或理解结构，而不是只增加视觉效果。

Phase 5：质量审查与迭代

范围：

• 构建检查、关键页面 HTTP 检查、关键词检查、桌面与移动截图检查。
• 内容 QA：用新手视角检查“能不能照做、知不知道为什么做、知不知道如何验收”。

验收：

• corepack pnpm build 通过。
• 首页、课程页、学习路线、任务设计、案例总览和代表性案例在桌面与移动端可读。
• 禁用语和不合适承诺没有命中。
• 审查结果记录剩余风险，不把未检查内容默认说成完成。

公共接口与内容合同

• /course/ 是一级课程入口。
• /course/capability-matrix.md 是学习者选择任务入口的辅助页。
• /guide/00-overview.md 是学习路线页。
• /practice/task-design.md 是任务拆解方法页。
• /recipes/ 是工作流案例库入口。
• 首页承诺固定为：帮助学习者用 Codex 把真实工作改造成可验证、可复用的 AI 工作流。

检查命令

每阶段至少运行：

corepack pnpm build

关键词检查：

rg -n "[禁用表达清单]" docs/guide docs/course docs/practice docs/recipes docs/index.md

代表性链接检查：

python3 -m http.server 8801 --directory docs/.vuepress/dist

然后检查：

• /
• /course/
• /course/capability-matrix.html
• /guide/00-overview.html
• /practice/task-design.html
• /recipes/

内容 QA 问题

每阶段至少完成：

• pnpm build 通过。
• 首页、课程页、学习路线页在桌面和移动端可读。
• 导航和侧栏链接可访问。
• 新增交互组件不依赖外部服务。
• 内容回答 5 个问题：新手从哪开始、为什么学、是否有真实场景、是否有验收标准、是否符合半桶水专业但通俗的人性化表达。

补充检查：

• 这页有没有说明学习者要准备什么输入？
• 这页有没有说明 Codex 的动作和人的判断分别是什么？
• 这页有没有说明失败时先检查哪里？
• 这页有没有说明如何迁移到自己的真实工作？
• 这页有没有避免把高风险判断交给 AI？

审计日期：2026-06-11

审计结论

当前状态：阶段目标已可运行并具备关闭前证据。

理由：

• Phase 1 到 Phase 4 的主要交付物已经落地：课程入口、学习路线、首页、核心入门页、案例页、轻量交互组件、导航和侧栏都已接入。
• Phase 5 已有构建、关键词、链接、截图和内容 QA 证据。
• 官方资料类页面已经新增定期复核机制，用于处理订阅、套餐、额度和入口可用性的变化风险。

Phase 1：课程骨架改造

| 要求 | 当前状态 | 证据 | 结论 |
|

关联审计：半桶水式 Codex 学习项目完成度审计。
维护机制：Codex 官方资料定期复核协议。

2026-06-11 阶段检查

范围

本轮检查覆盖：

• 首页 /
• 课程入口 /course/
• 能力矩阵 /course/capability-matrix.html
• 学习路线 /guide/00-overview.html
• 订阅指南 /guide/02-subscribe-plus.html
• 桌面宠物 /guide/11-desktop-pet.html
• 任务设计 /practice/task-design.html
• 案例总览 /recipes/
• 入口地图 /platform/
• 配置总览 /configuration/
• 代表性高风险案例：GitHub Actions 自动修复、临床文献综述

构建检查

命令：

corepack pnpm build

结果：通过。VuePress 成功渲染 65 个页面，并生成 SEO、feed、sitemap 和 redirect 文件。

关键词检查

命令：

rg -n "[禁用表达清单]" docs/guide docs/course docs/practice docs/recipes docs/index.md

结果：无命中。

补充检查：

rg -n "[占位表达清单]" docs/index.md docs/course docs/guide docs/practice docs/recipes docs/platform docs/configuration

结果：无命中。

关键链接检查

本地服务：

python3 -m http.server 8801 --directory docs/.vuepress/dist

关键页面返回：

| 页面 | 状态 |
|

什么时候复核

至少在以下场景复核一次：

• 每月课程更新前。
• 线下课或陪跑营开课前 7 天内。
• OpenAI 发布 Codex、ChatGPT、CLI、App、Cloud、Skills 或 pricing 相关更新后。
• 学员反馈“页面步骤和当前产品不一致”后。
• 准备对外发布大版本前。

必查官方来源

| 主题 | 优先来源 | 影响页面 |
|