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

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

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

三种方案怎么选

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

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

适合什么场景

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

不适合的场景：

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

推荐目录结构

先在本地建一个小型资料夹，例如：

literature-review-demo/
├─ question.md
├─ papers/
│  ├─ paper-01.md
│  ├─ paper-02.md
│  └─ paper-03.md
├─ evidence-table.md
├─ gaps-and-risks.md
└─ summary-draft.md

每篇论文可以先放结构化笔记，不需要一开始就很完美：

# Paper 01

Title:
Year:
Study type:
Population:
Intervention or exposure:
Comparator:
Outcome:
Key result:
Limitations:
PMID or DOI:

第一步：把问题拆成 PICO

先在 question.md 写下研究问题：

# Research question

在成人 2 型糖尿病患者中，连续葡萄糖监测是否能改善血糖控制和低血糖风险？

然后让 Codex 帮你拆解：

请只读取 question.md。

任务：
1. 把这个医学研究问题拆成 PICO。
2. 标出哪些信息还不明确。
3. 不要给临床建议。
4. 输出到 question.md 的 “PICO draft” 小节。

比较好的输出应该像这样：

| 元素 | 内容 | 需要补充 |
|

第一阶段：骨架完整

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

第二阶段：指南成型

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

第三阶段：案例驱动

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

第四阶段：社区传播

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

贡献入口

你可以从这些任务开始：

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

三种使用姿势

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

配置文件放在哪里

通常位于：

~/.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 是 OpenAI 面向软件工程与知识工作场景的代理式工作流。它可以在多个入口中出现：

• CLI：贴近终端和本地仓库，适合快速修改、运行命令、排障和验证。
• 桌面 App：适合本地多任务、Skills、Automations、子代理和插件化工作流。
• Web / Cloud / ChatGPT：适合连接仓库、分派长任务、并行处理、生成 PR 或回答代码问题。
• IDE：适合贴近编辑器上下文的解释、修改、审查和局部任务。
• 集成生态：GitHub、Slack、Linear、MCP 等入口让 Codex 接入团队协作链路。

四阶段路线

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

最后核对

官方资料最后核对日期：2026-05-27。下载地址与安装方式以 OpenAI Codex 产品页 和 chatgpt.com/codex/cloud 为准，不同地区和账号套餐下可用功能可能有所差异。

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

下载

打开 chatgpt.com/codex/cloud，页面中央会显示对应系统的下载按钮。

macOS：

点击「Download for macOS」下载 .dmg 安装包。

Windows：

Windows 用户点击对应的下载按钮，下载完成后运行安装程序，按提示完成安装。

macOS 安装步骤

1. 打开下载好的 .dmg 文件
2. 将 Codex 图标拖入「Applications（应用程序）」文件夹
3. 首次启动时，macOS 可能提示「无法验证开发者」，进入「系统设置 → 隐私与安全性」，点击「仍要打开」

登录

安装完成后打开 App，使用 ChatGPT / OpenAI 账号登录。

安装后验证

登录成功后，左侧栏应显示「Projects」和「Chats」两个入口，顶部显示当前账号信息。如果界面正常加载，说明安装成功。

下一步：订阅 ChatGPT Plus / Pro

最后核对

官方资料最后核对日期：2026-05-27。定价与套餐以 ChatGPT 定价页 和 Using Codex with your ChatGPT plan 为准。

为什么需要订阅

免费版 ChatGPT 可以体验基础对话，但 Codex 功能（包括桌面 App、Cloud 任务、多 agent 并行）需要付费套餐才能稳定使用。

| 套餐 | 月费（美元） | Codex 可用情况 |
|

最后核对

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

认识对话和项目

打开 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. 先观察使用情况：如果任务经常中断、额度告急或模型响应变慢，再回到「使用情况」和套餐页面确认限制。

设置逐项说明

什么时候需要改设置

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

最后核对

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

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

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

你需要更新你的 ChatGPT APP 到最新版本，然后选择连接你电脑里面的 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 |
|

最后核对

官方资料最后核对日期：2026-05-27。本章以开发一个简单网页为例，演示从创建工作目录到任务迭代的完整操作流程。

本章以"用 Codex 桌面 App 开发一个关于 AI 发展历史的简单网页"为例，走完一次完整的任务闭环，帮助你快速上手 Codex 桌面 App 的基本用法。

第一步：创建本地工作文件夹

在本地新建一个空文件夹，作为 Codex 的工作目录。Codex 生成的所有文件都会保存在这里。

第二步：选择对话还是项目

打开 Codex 桌面 App 后，你需要选择用"对话"还是"项目"来开始任务。

• 对话：适合一次性任务，操作简单，但多个对话之间不共享工作目录。
• 项目：支持在同一工作目录下创建多个对话，每个对话处理不同的子任务，管理更方便。

如果你不确定选哪个，优先选择项目——后续扩展任务时更灵活，工作目录也只需要配置一次。

第三步：添加工作目录

选择项目后，点击"使用现有文件夹"，选中刚才创建的文件夹。

选择完成后，对话框左下角会显示当前工作目录的路径，确认路径正确即可。

第四步：输入任务描述，开始执行

在对话框中输入你的需求，点击发送，Codex 就会开始执行任务。

任务完成后，Codex 会在对话中展示结果，同时将生成的文件写入工作目录。

如果生成的是网页文件，可以直接点击 Codex 弹出的"打开"按钮，在 App 内置浏览器中预览效果，无需手动打开文件夹。

第五步：逐步迭代

对结果不满意时，直接在当前对话框中继续描述修改需求，Codex 会在已有基础上进行调整。

随着对话轮次增加，上下文窗口会逐渐被填满。点击对话框右下角的小圆圈图标，可以查看当前上下文使用情况。

如果使用的是"对话"模式而非项目，新建对话时需要重新指定工作目录，两个对话之间也是相互隔离的，不方便统一管理。这也是推荐使用项目的主要原因之一。

我们使用codex开发obsidian新手教程网站作为示例：来说明任务的顺序执行管理和并行操作

1.顺序执行

选择本地项目/创建新的项目，该项目实际上就对应我们本地的一个文件夹，它存储在我们的本地。

然后点击创建新的对话。

我们向 CodeX 发送任务，让他帮我们设计一个网站，这个时候他就会开始执行。

在这个任务没有执行的过程中，如果我们去给他下达新的命令，就只能等待。显示的是下面这种情况：

这种相当于当前他正在执行一个任务，我们给他的另外两个命令就需要排队，必须等前面的任务执行完成之后才能执行。

但是如果我们想修改一下要求，比如想让他明确这个网站的背景风格为“手绘风格”，如果等他设计完成之后再去修改就会比较麻烦。我希望他在正在设计的时候就知道我的风格要求。

这时候，我们可以点击引导选项。这样操作后，他就会执行一个“插队”的操作：

1. 原本的任务顺序：
   (a) 执行网站设计
   (b) 介绍技术选型
   (c) 执行手绘风格要求（原定第三个任务）

2. 插队后的效果：
   我们想让“手绘风格”在设计过程中就发挥作用，通过点击引导提示，这个任务就会直接插队到当前正在执行的任务当中。

这实际上就是通过这样一个过程，演示如何对顺序执行的任务进行管理以及相关的插队操作。

2.如何并行

实际上就是一个项目（Project）里面，我们同时去执行多个任务。

这个时候，我们只需要在左侧边栏点击“新建对话”就可以了。这样的话，它的几个任务就会并行执行，互不干扰。

三种常见模式

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

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

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

怎么选更稳妥

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

使用时的提醒

• 不同客户端可能不会把权限模式写成完全一样的中文名，建议优先认官方英文模式名。
• 即使使用更自动化的模式，也要保留对高风险操作的复核，比如安装依赖、删除文件、访问网络、推送代码或处理敏感信息。
• 如果你不确定当前模式会不会执行某个动作，先让 Codex 说明它准备运行哪些命令、会改哪些文件，再决定是否继续。

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

Skill 是什么

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

一个 Skill 通常会包含：

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

常见使用方式是：

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

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

Plugin 是什么

Plugin 更像一种打包和分发机制，用来把可复用工作流、应用集成、MCP 服务配置等能力组合起来，方便在项目或团队中统一安装和使用。

简单理解：

• Skill 关注“这件事应该怎么做”。
• Plugin 关注“把哪些能力打包起来，方便安装和复用”。

所以 Skill 往往是具体流程本身，而 Plugin 更像承载这些流程和集成能力的安装单元。

怎么理解它们的关系

你可以把两者想成：

• Skill 是“工作说明书”
• Plugin 是“装着说明书、工具和连接配置的工具箱”

有些插件里会包含一个或多个 Skills，也可能附带应用集成或 MCP 配置。这样团队在迁移环境时，不用手动一个个配置。

使用时的提醒

• 插件和技能的具体入口会随版本变化，不要把某个截图里的按钮位置当成永远不变。
• 如果插件涉及外部系统、浏览器、邮箱、知识库或项目管理工具，先确认它是只读还是可写。
• 涉及安装、写回外部系统或共享给团队时，最好保留人工复核。

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

适合自动化的任务包括：

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

可以怎么理解自动化

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

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

常见使用流程

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

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

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

❌ 不够自包含的写法：

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

✅ 推荐的写法：

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

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

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

使用时的提醒

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

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

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

安装前检查

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

| 项目 | 建议 |
|

选择第一个任务

适合新手：

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

暂时避开：

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

第一步：只读建图

先让 Codex 理解仓库：

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

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

第二步：给出小任务

推荐复制这个模板：

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

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

如果任务是文档：

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

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

第三步：观察过程

重点观察五件事：

| 观察点 | 说明 |
|

最后核对

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

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

安装 Codex 插件

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

打开插件对话窗口

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

开始使用

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

使用 @ 指定文件：

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

App 与 VS Code 插件怎么选

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

所以 Codex 提供了记忆系统来解决这样的问题

AGENTS.md 是给 Codex 这类编码代理看的项目说明文件。它可以描述项目结构、开发命令、测试要求、代码风格和协作边界。

为什么需要 AGENTS.md

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

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

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

## 项目概览

- 项目类型：
- 主要语言：
- 关键目录：

## 常用命令

- 安装依赖：`...`
- 本地开发：`...`
- 运行测试：`...`
- 类型检查：`...`
- 格式化：`...`

## 代码规范

- 遵循现有代码风格。
- 不做无关重构。
- 新增功能必须补充或更新测试。

## 安全边界

- 不读取或提交 `.env`、密钥和私有凭据。
- 不执行删除生产数据的命令。
- 修改数据库迁移前先说明影响。

## 交付要求

- 说明改动文件。
- 说明验证命令和结果。
- 说明未验证项和剩余风险。

写作建议

• 越具体越好。运行测试：pnpm test 比“记得测试”有用。
• 把生成目录、构建产物、锁文件策略写清楚。
• 如果是 monorepo，请说明每个包的边界。
• 如果有特殊 lint、格式化或代码生成流程，写在命令区。
• 对安全敏感项目，单独写“禁止事项”。

最小可用版本

# AGENTS.md

## 项目命令

- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 构建：`pnpm build`

## 改动规则

- 修改前先阅读相关文件。
- 保持现有代码风格。
- 不提交构建产物和环境变量文件。

## 验证要求

- 文档改动运行：`pnpm build`
- 代码改动运行相关测试。

## 安全边界

- 不读取 `.env` 或任何私有凭据。
- 不执行发布、部署、数据库迁移和删除数据命令。

你需要关心什么

先把风险拆成几个层面：

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

低风险任务

通常可以较快推进：

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

高风险任务

建议先确认计划：

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

给 Codex 的安全提示词

请在动手前先说明你计划运行的命令和可能影响的文件。不要读取 `.env`、密钥、token 或任何私有凭据。不要执行删除数据、发布、部署或迁移命令，除非我明确确认。

Codex 桌面 App 中的审批流程

在 Codex 桌面 App 里，当 Codex 要执行写入文件、运行命令、访问网络等敏感操作时，会暂停并弹出审批提示，列出它打算做的事。你可以：

• 放行：确认操作合理，继续执行
• 拒绝：取消该步骤，Codex 会尝试其他方案
• 修改提示词：告诉它换一种方式做

这个机制在前面的实战案例中多次出现——比如 Playwright MCP 操作浏览器时，每一步填写输入框、打开网页都需要手动放行。

养成习惯：不确定的操作先看清楚再放行，尤其是涉及删除文件、写入配置或访问外部服务的步骤。

团队建议

• 在 AGENTS.md 写清楚禁止事项。
• 把高风险命令放进人工审批流程。
• 给测试、lint、类型检查提供明确命令。
• 避免把生产凭据放在普通开发环境里。
• 对 Codex 产出的 PR 仍然执行正常代码审查。

Codex 找不到项目上下文

可能原因：

• 你不在项目根目录。
• 仓库缺少 README、测试命令或项目说明。
• monorepo 没有说明包边界。

处理方式：

• 先让 Codex 只读目录并总结项目结构。
• 添加或更新 AGENTS.md。
• 在任务说明里指定相关目录。

Codex 改动范围太大

处理方式：

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

测试跑不起来

处理方式：

• 让 Codex 先定位测试命令。
• 检查依赖是否安装。
• 区分环境问题和代码问题。
• 如果是环境问题，让 Codex 记录阻塞，而不是继续乱改。

生成内容不准确

处理方式：

• 要求 Codex 引用它依据的文件。
• 对官方事实要求附链接。
• 让它区分“已确认”和“推测”。
• 让它先读代码再写文档。

登录或权限问题

处理方式：

• 更新 Codex CLI 到最新版本。
• 重新运行登录流程。
• 检查当前账号计划和组织策略。
• 查看官方 Help Center 的 Codex 相关文章。

Windows 桌面 App / CLI 专项排障

如果问题发生在 Windows 桌面 App、Microsoft Store / winget 安装、Windows sandbox、Worktree、Browser / Computer Use 插件、WSL 混合路径或 PowerShell 环境，可以参考社区维护的 Windows 专项排障库：

• Community Codex Windows Troubleshooting
• Windows Codex Error Guide
• Dogfood Matrix

这个项目会把 Windows 报错按证据等级、复现等级和 workaround 状态整理，并提供只读诊断脚本。提交日志、截图或诊断输出前，请先脱敏用户名、路径、私有仓库名、token 和账号信息。

切换 provider 后旧会话不可见

可能原因：

• 修改过 config.toml 根级 model_provider。
• 旧会话文件还在，但会话 metadata、SQLite 状态或项目路径缓存仍指向旧 provider。
• CLI /resume 能看到旧会话，但 Codex Desktop 项目侧看不到，可能只是 Desktop 最近 50 条会话的首屏显示限制。

处理方式：

• 先确认 ~/.codex/sessions 或 ~/.codex/archived_sessions 里是否还存在旧会话文件。
• 如果只是 Desktop 项目侧不可见，先判断是否被最近 50 条显示限制挡住。
• 如果确认是切换 provider 后 metadata 不一致，再参考 config.toml 里的社区工具说明。
• 使用第三方工具前先备份 ~/.codex，不要把它当成官方认证或账号切换工具。

桌面 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 中的高频任务

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

入口对照表

| 入口 | 更适合 | 典型任务 | 学习优先级 |
|

方法地图

| 主题 | 解决什么问题 |
|

文档工作

适合任务：

• 把 README 改成新手友好的版本。
• 根据代码生成模块说明。
• 整理迁移指南。
• 生成发布说明。
• 把 issue、PR、commit 整理成周报。

任务模板：

请阅读当前仓库的 README、docs 和 package 配置，帮我整理一份新手上手指南。

要求：
1. 不修改代码。
2. 命令必须来自仓库真实配置。
3. 不确定的步骤标注为“待确认”。
4. 输出目录结构、安装步骤、开发命令、测试命令和常见问题。

学习工作

适合任务：

• 让 Codex 按学习顺序解释代码库。
• 生成“从入口到核心模块”的阅读路线。
• 把复杂模块讲成产品、设计或运营也能理解的语言。
• 把陌生技术栈拆成学习清单。

任务模板：

请把这个仓库当成学习材料。请按初学者阅读顺序讲解：
1. 先看哪些文件
2. 每个目录承担什么职责
3. 关键数据流或调用链
4. 学完后可以做的 3 个练习

产品与运营工作

适合任务：

• 把 PR 改动翻译成用户影响。
• 生成发布公告草稿。
• 检查文案和功能说明是否一致。
• 从 issue 中提取用户痛点。

任务模板：

请阅读当前 diff，把技术改动整理成产品发布说明。请包含：
1. 用户能感知到的变化
2. 管理后台或配置变化
3. 可能影响旧用户的地方
4. 需要客服或运营同步的话术

知识管理

Codex 很适合把零散经验沉淀成模板：

• 排障记录。
• FAQ。
• 任务模板。
• 团队规范。
• 案例复盘。

最终目标是把“每次临时问一次”变成“下一次直接复用”。

任务六要素

| 要素 | 写法 | 示例 |
|

团队接入清单

| 项目 | 建议 |
|

适用场景

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

使用前先理解一件事

这里说的“控制浏览器”，更准确地说，是让 Codex 借助浏览器或浏览器插件能力去完成网页交互。不同工作区里，入口可能叫 Chrome、Browser，也可能表现为浏览器插件或内置浏览能力。

因此，更稳妥的理解方式是：

1. 在当前工作区确认是否已经启用了相关浏览器能力。
2. 如果是第一次使用，按界面引导完成浏览器侧安装或授权。
3. 安装完成后，再在任务里明确告诉 Codex 你想让它做什么。

一个常见流程

如果你的客户端提供了 Chrome 相关插件或浏览器能力，常见流程通常类似这样：

1. 在 Codex 桌面 App 中找到对应的浏览器能力并启用。
2. 按引导完成浏览器侧的插件安装或连接配置。
3. 回到任务中，明确描述目标网页、搜索词和预期输出。

第一次点击后会跳转到浏览器插件安装页，点击添加扩展即可

任务示例

你可以像下面这样给出一个明确任务：

请使用浏览器能力打开 Bilibili，搜索“RAG 知识库 教程”，找一个适合新手入门的视频，并把标题和链接返回给我。

一个类似任务完成后，Codex 可能会：

1. 打开目标站点。
2. 搜索你提供的关键词。
3. 进入相关结果页。
4. 把它认为最合适的结果链接返回给你。

你要重点检查什么

• 它打开的网站是不是你指定的那个站点。
• 搜索词有没有被错误改写。
• 点击结果后返回的是不是你真正需要的页面，而不是广告页或无关页。
• 如果涉及登录态、个人数据或付费后台，是否会超出你愿意授权的范围。

风险提醒

• 浏览器相关能力通常比纯文本任务权限更高，第一次使用时建议从只读、低风险页面开始。
• 不要直接让 Codex 操作带有支付、删除、发帖、提交表单等高风险页面，除非你准备全程复核。
• 如果教程依赖插件安装，未来界面名称或入口位置可能变化，因此文档里应优先描述“能力和流程”，而不是把某个按钮位置写死。

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

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

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

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

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

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

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

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

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

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

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

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

如果你想做一些轻量化的视频，比如网页转视频、文档转视频等，那么使用 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 知识库。

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

前提条件：

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

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

本章节使用命令行的方式，来学习 MCP 的安装和使用。

适用场景

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

准备一个 Skill 来源

首先要有这个 Skill 的来源地址。很多开发者会把自己做好的 Skill 放在 GitHub 仓库里，供其他人安装和复用。

这个案例里使用的是一个社区 PPT Skill：

guizang-ppt-skill

第一步：安装

你可以把 Skill 仓库地址交给 Codex，请它协助识别并完成安装流程。

例如：

请帮我安装这个 Skill：https://github.com/op7418/guizang-ppt-skill
安装完成后，告诉我它的用途、依赖要求，以及应该如何调用。

不同工作区里，安装方式可能不完全一样。有些会直接支持安装，有些则会先分析仓库结构，再提示你确认放置位置或依赖要求。

第二步：调用使用

安装完成后，可以直接让 Codex 调用这个 Skill 去完成一项真实任务。

如果这个 Skill 已经提前安装过，你通常也可以通过斜杠命令、技能选择器，或者在任务里明确点名的方式来调用它。

例如：

请使用刚刚安装的 PPT Skill，根据“AI 编程工具入门”这个主题生成一份适合分享的演示稿。先告诉我还缺哪些关键信息。

如果你没有给足上下文，Codex 往往会先回到这个 Skill 的操作手册里，看看它需要什么输入，然后再向你追问必要信息。

当你补齐背景、主题、受众或风格要求后，它会按该 Skill 的流程去读取 README、模板和相关文档，再生成结果。

如果这个 Skill 的默认产物是 HTML 演示稿，你通常可以直接在 Codex 内置浏览器里打开预览。

你要重点检查什么

• Codex 安装的是不是你指定的那个 Skill，而不是名称相似的别的仓库。
• 安装后有没有说明依赖要求、输出格式和调用方式。
• 生成结果是否符合这个 Skill 原仓库描述的能力边界。
• 如果结果不理想，是 Skill 本身限制，还是你提供的输入信息不够。

风险提醒

• 社区 Skill 不是官方能力，质量和维护状态差异会很大，使用前最好先看仓库 README。
• 不要默认“给出 GitHub 链接就一定能一步安装成功”，有些 Skill 还会依赖额外脚本、模板或本地环境。
• 第一次验证时，优先选一个小任务，确认 Skill 能正常运行后，再拿去做正式产物。

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

最后核对日期：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 文档和企业相关说明。
• 写教程时不要整段翻译原文，应转化成中文场景和可复现步骤。
• 涉及价格、计划、模型、可用地区、功能开关、账号权限时，必须打开原文重新确认。