课程内容
这页是课堂正文。左侧目录负责定位章节，右侧直接展开完整教程。你不用先学编程语法，先学会三件事：把需求说清楚、让 Codex 在指定文件夹里产出文件、自己能检查结果。
为什么要学AI编程
为什么要学编程？
01 编程是怎么和普通人扯上关系的
自从 2025 年开始，世界变化了：普通人可以编程了。Andrej Karpathy（特斯拉前 AI 负责人）在 2025 年初提出了一个词：Vibe Coding。你只需要描述意图，AI 来写代码。到 2026 年，这不再是一个概念，而是真实的、正在发生的生产方式。
Anthropic 在 2026 年 2 月发布的《2026 智能体编程趋势报告》里有一句话值得品味：
注意，不是“每个程序员变得更强了”，而是“非技术人员也能开发了。”
律师用 Claude Code 做了自助分类工具。法务团队把审核周期从三天压缩到一天。一个没有编程背景的 CTO，两周完成了原本需要 40 人团队做半年的项目。
如此巨变让一部分程序员朋友们感觉到很不舒服：
- 它意味传统程序员朋友们的技能变得不那么值钱了。
- 也意味着“会不会编程”这条线，正在从技术能力的分界线，变成思维方式的分界线。
对于非技术出身的朋友们来说，此时反而出现了一个新问题：
既然只要描述意图，AI 就能写代码，那我们还需要学吗？不是天生就会吗？
02 Vibe Coding，从褒义词到贬义词
在 2025 年初，Vibe Coding 是一种生活方式，很潮，妥妥的是褒义词。但是到了 2026 年，Vibe Coding 铁定是贬义词了。
Vibe Coding 的原意：完全跟着感觉走，让 AI 写代码，自己不怎么碰键盘，遇到报错就把报错扔给 AI，看它自己修。
随后，各路自媒体开始用“Vibe Coding”来包装产品、吸引流量、讲故事给投资人听。“不会编程？没关系，Vibe Coding 就行！”“两小时做出一个 App！”这类标题铺天盖地。
那些写“两小时做出一个 App”的自媒体，一辈子也没做出来过有用的 App。那也不影响人家获取流量，普通人最爱看的就是这样的自媒体文章，平台使劲给流量。
然后，反弹来了。
大概半年后，人们发现 Vibe Coding 越来越不对劲。
安全公司 Aikido Security 调查了 450 名开发者和安全工程师，得出的结论是：AI 生成的代码现在是每 5 起安全漏洞中 1 起的直接原因。
Hacker News 上有一个高赞帖子，标题直接叫 “Vibe code is legacy code”（Vibe 代码就是遗留代码），意思是，今天用 Vibe Coding 写出来的东西，明天就是别人头疼的技术债。
Fast Company 在 2025 年 9 月报道，资深软件工程师开始把 AI 生成的代码称为 “development hell”（开发地狱），分析师预测，由此积累的技术债务到 2027 年将高达 1.5 万亿美元。
最后，连这个词的发明者本人也放弃了它。
2026 年 2 月，在 “Vibe Coding” 诞生一周年的时候，Karpathy 本人在 X 上发帖，提出了一个新词来取代它：Agentic Engineering。
如果最近你用 AI 编程开发了一个产品，别人问你“喔唷，是 Vibe Coding 出来的吧？”
你大可以理解为：他在骂你做得烂。
03 投资者到底该学什么
先把概念分清。Andrej Karpathy 区分过两种用 AI 写代码的方式：
| 方式 | 本质 |
|---|---|
| Vibe Coding | 蒙头提示，祈祷有用，不管后果。 |
| Agentic Engineering | 清晰目标，系统拆解，人类判断，AI 执行。 |
投资人要学的是后者。而且投资人天生就该擅长后者，因为这套动作和你做投资是同一套：先有清晰的判断，再拆成可验证的步骤，自己拍板，让工具去跑。你每天都在干这件事，只是过去执行那一环交给了别人。
过去两年靠 AI 跑在前面的人是那些人？
真正吃到红利的常常不是写代码最熟的那批，而是判断力强、说得清自己要什么的人。会写代码的人在 AI 时代反而容易卡住，因为他们最容易掉进执行细节，花大量时间打磨工具本身，而不去想“该拿这工具查什么、赌什么”。投资也一样，盯着数据管道和模型参数较劲的人，往往跑不过那个先想明白“什么值得跟踪”的人。
真正的壁垒从来不是代码，也不是数据源、不是某个模型。是判断：
- 看什么
- 什么时候看
- 为什么看
AI 不替你做这件事，它只负责把你的判断变成跑得起来的东西。在 AI 越来越强的今天，真正稀缺的能力是这一句：把一个还很模糊的投资想法，拆成清晰的任务，然后指挥 AI 把它做出来。这就是 Agentic Engineering，也是这门课的核心。
回到很多人的第一反应：“我又不是做技术的，这事不该交给量化团队、数据团队吗？”换个问法你就明白了。
如果有一根杠杆，能把你的行业理解、你的研究洞察、或者一个还很粗的想法，直接变成一个跑起来的工具：
- 一个按你的投资框架的的标的筛选器
- 一个在条件触发时就提醒你的监控
- 一套替你读财报、扒数据、做回测的流程。
你要不要？
过去这根杠杆叫“团队”。一个量化、一个工程师、一套外包，门槛几十万起，还慢。更要命的是，你的洞察每经一手就漏一点，等东西做出来，那点边际可能已经被别人吃掉了。现在这根杠杆叫 AI 编程，门槛只剩一条：你能不能想清楚自己到底要什么。
过去，没技术的投资人只能把想法说出来，然后排队等人实现。现在，会用 AI 的投资人第一次可以当天就把它做出来。
这门课不是教你去当程序员、当 quant，是教你别再把自己的判断力外包出去，别让你最好的想法烂在某个待办列表里，在层层传递中一点点漏光。
你是不是技术出身，不重要。重要的是从现在起，你得学会把 AI 变成杠杆，把判断变成工具，把洞察变成别人拿不走的优势。
AI 到底是什么？别怕，它只是你的 24 小时员工
01 前言
你可能听过很多关于 AI 的说法：
- “AI 要取代人类了。”
- “AI 比人聪明。”
- “AI 太难了，我学不会。”
这些说法都不准确。把 AI 理解成一个员工会更容易，一个不用发工资、不下班、不请假、随叫随到的员工，我们把它叫作 24 小时员工。
02 这个 24 小时员工有什么特点？
它见识特别广，读过大量公开资料：维基百科、Stack Overflow、GitHub 上数十亿行代码，以及大量书籍、论文、新闻和论坛内容。单论接触过的信息量，绝大多数人都比不过它，很多你需要花几天才能查完的资料，它几秒钟就能整理出来。
它干活特别快。你给它一句话，它很快就能开始工作，写邮件、整理方案、生成表格、制作网页、解释概念，往往几秒钟就能给出结果。
但它有个很重要的特点：知道很多知识，却没有亲身经历。它读过所有关于游泳的书，却从来没下过水；它知道大量菜谱，却从来没做过饭；它学过无数管理理论，却从来没真正带过团队。所以它会犯一些看起来很离谱的错误：你问它一个事实，它可能一本正经地说错答案，这类问题通常被称为“幻觉”；你让它完成任务，它可能主动增加一些你根本没要求的内容；你的要求不够明确，它会按照自己的理解执行，最后结果和你的预期完全不同。是不是很像刚入职的新员工？知识很多，执行很快，但需要管理和检查。
03 它能干什么？
先记住三件最常见的事。
第一是回答问题。你可以直接问：
用大白话解释一下什么是数据库。
它会快速整理相关知识并给出解释，很多时候比传统搜索更直接。
第二是写内容。你可以说：
帮我写一封请假邮件，语气正式一点，理由是家里有事。
几秒钟后，它就能给出一版完整内容，通常只需要稍微修改就能使用。
第三是写代码。你可以说：
写一个网页，页面中间显示一个倒计时，从 60 秒倒数到 0。
它会直接生成可以运行的代码。
需要注意的是，回答问题、写文章、写代码并不是三种不同的 AI，本质上都是同一个 24 小时员工在完成不同类型的工作，就像一个员工既能做 PPT、写文档，也能处理数据一样。
04 它不能干什么？
下面三件事必须记住，后面的课程会不断提到。
第一，它不能保证正确。AI 的回答通常很自信，但自信不等于正确，尤其在数据、法律、财务、医疗、业务决策这些方面。你必须验证结果，重要内容要核对来源、检查逻辑、确认事实，不要因为它说得像真的，就默认它是对的。
第二，它不能自动理解长期背景。如果你开启一个新的对话，它通常不知道你上周做过什么项目，也不知道你之前聊过什么内容，除非你重新提供背景信息，否则它很难准确延续之前的工作。这个问题后面的课程会介绍怎么解决。
第三，它不能替你做决定。它可以给出多个方案、分析优缺点、提供参考意见，但最终选择必须由你完成。它负责提供建议，你负责承担结果。
05 管理 AI 最重要的一件事
最重要的一件事，是学会控制它的自主级别。简单重复的工作，可以直接交给它完成；重要工作，则需要你逐步审核。比如让它整理会议纪要，可以直接做；给客户发送正式报价，需要认真检查；涉及合同、资金、法律风险的内容，必须人工确认。就像管理团队一样，不是所有工作都需要同样的授权等级。
06 所以，你和 AI 是什么关系？
最容易理解的答案是：你是主管，AI 是你的 24 小时员工。你的职责是明确目标、提供背景信息、判断结果是否合格、做最终决策；它的职责是执行任务、生成方案、处理细节、提高效率。
这门课真正要教你的不是编程，而是如何管理一个 24 小时在线的员工。一个优秀的管理者不一定会亲自完成所有工作，但必须知道自己要什么结果、怎样判断质量、什么时候需要纠正方向。
07 最后一个必须记住的原则
过去在公司里，通常是你干活，领导负责结果。现在变成了 AI 干活，你负责结果。AI 写的代码出现问题，客户找的是你；AI 写的文案出现错误，领导找的是你；AI 提出的方案导致损失，承担责任的还是你。
AI 不承担责任，责任始终属于使用它的人。因此，检查结果不是额外工作，而是你的本职工作。这个 24 小时员工不要工资、不会离职、不会请假、全天在线，但它不会为任何结果负责。最终负责的人，永远是你。
01 桌面 App 安装
最后核对
官方资料最后核对日期：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 安装步骤
- 打开下载好的
.dmg文件 - 将 Codex 图标拖入「Applications（应用程序）」文件夹
- 首次启动时，macOS 可能提示「无法验证开发者」，进入「系统设置 → 隐私与安全性」，点击「仍要打开」
登录
安装完成后打开 App，使用 ChatGPT / OpenAI 账号登录。
注意套餐限制
Codex 桌面 App 的完整功能（多 agent 并行、Skills、Automations 等）需要 Plus 及以上套餐。免费账号登录后部分功能会受限或无法使用。如需升级，参考下一章：订阅 ChatGPT Plus。
提示
如果登录失败，可以考虑切换代理节点或者切换代理，可以选择非美国节点。
安装后验证
登录成功后，左侧栏应显示「Projects」和「Chats」两个入口，顶部显示当前账号信息。如果界面正常加载，说明安装成功。
02 账号与套餐准备
最后核对
官方资料最后核对日期：2026-05-27。定价与套餐以 ChatGPT 定价页 和 Using Codex with your ChatGPT plan 为准。
为什么需要订阅
免费版 ChatGPT 可以体验基础对话，但 Codex 功能（包括桌面 App、Cloud 任务、多 agent 并行）需要付费套餐才能稳定使用。
| 套餐 | 月费（美元） | Codex 可用情况 |
|---|---|---|
| Free | 免费 | 仅限试用，额度极少 |
| Go | $8 | 有限额度，可体验 Codex |
| Plus | $20 | 完整 Codex 访问，日常开发够用 |
| Pro | $200 | Plus 的 5 倍额度，高强度使用 |
| Team / Enterprise | 按人计费 | 完整访问，含团队管理 |
对大多数个人开发者来说，Plus（$20/月）是性价比最高的起点。
前提条件
- 能正常访问国际网络（需要代理工具，这里不展开）
- 一个注册好的 ChatGPT / OpenAI 账号
- 支持国际支付的方式（详见下方）
如果还没有账号，需要先准备一个国外手机号用于接收注册验证码，可以使用专门的接码平台完成注册。
可以试试：https://hero-sms.com
方法一：苹果礼品卡（最稳定，推荐优先尝试）
适合已有 iOS 设备或愿意准备一台的用户。整个流程在国内支付宝内完成充值，不需要境外银行卡。
准备物品：
- 一台苹果设备（iPhone / iPad，可以是二手，能正常使用 App Store 即可）
- 已注册好的海外区 Apple ID（注册时选美国或新加坡，不需要绑定国内手机号）
- 国内支付宝（正常使用即可）
操作步骤：
- 在苹果设备上退出国内 Apple ID，登录准备好的海外区 Apple ID
- 打开支付宝，将定位切换为「美国旧金山」，支付宝会自动切换为国际版界面
- 在支付宝功能区找到「苹果礼品卡」，购买 $20 额度
- 购买成功后复制兑换码，打开 App Store，点击头像 → 「兑换礼品卡或代码」，粘贴充值
- 打开 ChatGPT App，登录账号，进入设置订阅 Plus，选择 Apple ID 余额支付
给Apple id充值礼品卡：
提示
如果支付宝购买偶尔不稳定，可以通过代理访问苹果官网直接购买礼品卡，一次性多充值几个月额度，后续续订不需要重复操作。
方法二：土耳其区 App Store（第三方经验，价格优先）
如果你的核心诉求是降低长期订阅成本，可以参考低价区 App Store 的做法：单独准备一个土耳其区 Apple ID，通过该区礼品卡给 Apple ID 余额充值，再在 ChatGPT iOS App 里用 App Store 应用内购订阅。
来源与风险
本小节整理自第三方文章 App Store Price《没有海外信用卡也能稳定订阅 ChatGPT/Claude》，源文发布于 2026-03-06，作者/发布方为 App Store Price。下图也来自该文。如有问题，请联系作者删除
这不是 OpenAI 或 Apple 官方订阅说明。跨区账号、礼品卡余额、汇率、App Store 定价和风控策略都可能变化，存在充值失败、订阅失败、余额无法退款、账号触发安全验证或后续续费不稳定等风险。正式操作前建议先小额验证，不要把主 Apple ID 频繁切区。
图源：App Store Price 文章。本小节后续截图除特别说明外，均整理自同一篇文章。价格、排名和汇率只代表源文截图时的状态，实际付款前一定以 App Store 结算页显示为准。
适合谁：
- 已经有 iPhone / iPad，愿意单独维护一个海外区 Apple ID。
- 能接受第三方礼品卡渠道的不确定性。
- 更看重订阅价格，而不是最省心的官方直连支付体验。
详细流程
第一步：核对当前低价区
先打开 App Store Price 的 ChatGPT 价格页，选择 ChatGPT Plus 月付项，看当前各地区价格。源文截图显示土耳其区价格较低，但低价区会随 App Store 定价、汇率和税费变化，操作前必须重新核对。
第二步：确认网络节点与账号地区一致
源文建议先准备土耳其节点，并在 IP 检测页面确认当前出口地区。核心原则是：注册 Apple ID、填写地区信息、登录 App Store 时，地区信息要尽量保持一致，减少触发安全验证的概率。
第三步：注册土耳其区 Apple ID
打开 account.apple.com 注册新的 Apple ID。注册时选择土耳其地区，按页面提示填写邮箱、手机号和验证码。源文说明旧的 appleid.apple.com 入口也可用，但 Apple 当前页面名称可能会变化，以实际页面为准。
警告
建议为这条订阅路线单独准备 Apple ID，不要频繁切换自己的主力 Apple ID 地区。跨区账号可能涉及 Apple 当前服务条款、账单地址真实性和后续风控，请自行确认能接受这些风险。
第四步：补齐 Payment Address
注册完成后，在 Apple 账号或 iPhone / iPad 的 App Store 账户设置里补齐 Payment Address。即使不绑定土耳其本地银行卡，Apple 也可能在购买或兑换时要求补充账单地址。
第五步：购买土耳其区 App Store 礼品卡
源文提到土耳其区礼品卡可以通过淘宝、闲鱼等渠道购买，也可以在土耳其数字商品平台购买。它以 oyunfor.com 为示例：注册并登录后，在站内找到 App Store 礼品卡，选择所需面值并加入购物车。
注意
本课程不推荐具体商家，也不保证任何第三方礼品卡渠道的稳定性。礼品卡一旦兑换通常不可退款，建议先小额测试。
第六步：选择支付方式并付款
源文示例中，Oyunfor 支持信用卡和 Binance Pay。信用卡页面里会出现不同支付通道，部分通道可能要求土耳其本地支付方式，源文选择了可用的国际卡通道。截图中的示例为 1000 土耳其里拉礼品卡，并叠加约 2.5% 手续费，实际手续费以付款页为准。
随后进入支付页，填写银行卡信息并确认付款。源文里的银行卡信息已经做了遮挡；你自己操作时不要把银行卡、验证码、礼品卡兑换码截图发给任何人。
如果银行或支付通道要求 3D Secure / 短信验证码，按页面提示完成验证。
第七步：收取并兑换礼品卡
付款成功后，礼品卡通常会通过邮件发送。源文的邮件截图中露出了兑换码，所以这里不再放图。拿到兑换码后，打开 App Store，点击头像，进入「兑换礼品卡或代码」，把土耳其区礼品卡兑换到同一个土耳其区 Apple ID。
第八步：在 ChatGPT App 内购买订阅
在 iPhone / iPad 的 App Store 登录这个土耳其区 Apple ID，用它下载 ChatGPT App。如果之前 ChatGPT 是用其他地区 Apple ID 下载的，源文建议先删除再用当前 Apple ID 重新下载。打开 ChatGPT App 后登录你的 ChatGPT 账号，进入订阅页，选择 Plus / Pro，用 Apple ID 余额完成 App Store 应用内购。
后续如果开启自动续费，需要保证这个 Apple ID 余额足够；如果余额不足，续费可能失败。
注意事项：
- 不要只看网页截图里的价格，最终价格以 App Store 付款页为准。
- 礼品卡有区域限制，土耳其区礼品卡通常不能给其他区 Apple ID 充值。
- 礼品卡渠道质量差异很大，避免一次性充值太多。
- 如果后续要续费，需要保证 Apple ID 余额足够，或者提前补充礼品卡余额。
- 如果你更在意稳定和售后，优先用前面的美国 / 新加坡区礼品卡方案。
方法三：安卓 Google Play（备选）
逻辑与苹果礼品卡类似：在安卓设备上切换到对应 Google 账号区域，通过 Google Play 购买礼品卡充值后订阅。有部分用户反映这条路可行，但实测稳定性不如苹果礼品卡，可作为备选方案。
常见问题
Q：订阅后 Codex 额度够用吗？
Plus 按 token 计费（2026 年 4 月起），日常开发任务普通使用量通常可以撑一整个月。如果额度用完，可以单独购买额外额度，也可以等下月重置。
Q：Plus 和 Pro 区别大吗？
Pro 的 Codex 使用额度是 Plus 的 5 倍，适合重度用户或需要大量并行任务的场景。普通开发者先从 Plus 开始，不够用再升级。
Q：可以用现有手机而不买二手设备吗？
可以。如果你的设备能正常使用海外区 Apple ID，不需要专门买二手。建议不要在自己常用的国内账号设备上频繁切换 ID，长期使用建议准备一台专用设备。
订阅后验证
登录 ChatGPT App 或网页端，在账号设置里确认套餐显示为 Plus 或以上，然后进入 Codex 入口检查功能是否正常可用。
03 桌面 App 总览
最后核对
官方资料最后核对日期：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 网页端类似，但额外提供了以下功能：
- 添加上下文：可以附加文件、截图或其他参考内容
- 切换模型：在不同模型之间切换
- 控制权限：设定 Codex 在当前任务中的操作权限
- 选择工作目录：指定 Codex 在哪个本地文件夹下执行任务
设置面板
点击左下角头像或设置图标可以打开设置面板。
上图左侧就是 Codex 桌面 App 的设置菜单。不要把它当成一次性必须填完的表单：新手只需要确认「常规」和「权限」能支撑第一个任务，其他设置等真实场景出现后再逐步打开。
新手先按这四步检查
- 先选工作模式：做代码、网站、脚本、仓库任务时选「适用于编程」；写文案、整理资料、做非代码任务时可以选「适用于日常工作」。
- 先别急着开最大权限：刚开始建议让 Codex 只在当前工作区内读写文件，遇到联网、系统文件、危险命令时再单独审批。
- 先配置工作目录：第一个任务尽量使用一个空文件夹或测试项目，不要直接把重要项目交给新手阶段的 Codex。
- 先观察使用情况：如果任务经常中断、额度告急或模型响应变慢，再回到「使用情况」和套餐页面确认限制。
截图不是推荐配置
截图中的开关只是界面示例，不代表所有读者都应该照着开启。尤其是「完全访问权限」、浏览器控制、电脑操控、钩子和 MCP 服务器，第一次使用时都应该按任务逐步开启。
设置逐项说明
这里决定 Codex 默认以什么方式回答和执行任务。最重要的是「工作模式」和「权限」。如果你要跟着本教程做网页、脚本、代码修改，优先选「适用于编程」；它会保留更多技术细节、命令输出和变更说明。如果只是写提纲、整理资料或改文案，可以切到「适用于日常工作」，回复会更轻量。
「默认权限」通常表示 Codex 可以在当前工作区里读取和编辑文件；「自动审核」会让它对额外权限请求做部分自动判断；「完全访问权限」会显著放大能力和风险。小白阶段不建议长期打开完全访问权限，等你能看懂它要运行的命令后，再按任务临时使用。
新手推荐：编程模式 + 最小可用权限外观只影响显示体验，比如浅色 / 深色模式、字体观感、界面密度或窗口呈现方式。它不会改变 Codex 能不能读文件、改代码或联网。
如果你经常截图写教程，建议统一使用浅色模式和较大的窗口宽度；如果长时间阅读终端输出，可以使用深色模式减少视觉疲劳。教程截图和你的实际界面颜色不同，不影响功能位置。
新手推荐：按阅读习惯选择配置页对应官方文档里的 agent configuration，通常用于管理模型、推理强度、沙盒、审批策略、网络访问和本地配置文件。桌面 App 会把常用项做成可点选的界面，高级用户也可以进一步查看 config.toml 基础配置 与高级配置。
初学时不要一上来追求“全自动”。如果你不知道某个选项会带来什么后果，优先保持默认；等你遇到“总是需要审批同一个安全命令”“某个项目需要固定模型”“团队要统一规则”时，再回来调整。
新手推荐：默认即可个性化用于调整 Codex 的沟通风格和默认偏好，例如更详细、更简洁、更偏教学式，或在任务中遵守你的长期习惯。它适合放“你希望 Codex 怎么跟你协作”的规则，不适合放项目级命令。
项目级规则应该写进 AGENTS.md，例如测试命令、代码风格、禁止改动目录。个人偏好可以写“回答先给结论”“中文解释”“提交前列出验证命令”。这样个人习惯和项目规则不会混在一起。
新手推荐：只写 3 条以内MCP 服务器让 Codex 连接外部工具，例如浏览器、设计工具、知识库、数据库、飞书、Notion 或自定义系统。官方文档把 MCP 视为扩展 Codex 能力的重要方式，但每接入一个服务，也意味着 Codex 能看到或操作更多上下文。
小白不要一次性接很多 MCP。先从一个低风险工具开始，比如只读知识库或浏览器测试；需要 API Key 时尽量使用环境变量或系统凭据管理，不要把密钥直接写进教程、截图或对话里。
新手推荐：一个场景只开一个 MCP钩子是让 Codex 在特定时机自动触发脚本或命令的机制，例如任务开始前准备环境、任务结束后运行格式化、测试或检查。它很适合团队标准化，但也最容易因为命令写错而带来副作用。
第一次使用时可以先不配置钩子。等你明确知道“每次修改后都必须跑 pnpm lint”或“每次提交前都要生成报告”时，再把这些固定动作写进去。钩子里的命令要短、可重复、失败信息清晰，不要放删除、发布、上传密钥这类高风险动作。
新手推荐：先空着Git 设置用于管理 Codex 如何理解当前仓库、分支、diff、提交和远程协作。对于真实项目，Git 是你回滚和审查 Codex 修改的安全网。
新手最好养成两个习惯：让 Codex 开始前先看 git status，结束后列出改动文件和验证结果。不要让 Codex 在你没看 diff 的情况下直接 push 或改主分支；团队项目可以统一使用 codex/ 这类分支前缀。
环境设置通常用于准备项目运行所需的依赖、命令、环境变量和本地初始化步骤。官方 App 文档里的 Local environments 关注的是让 Codex 在可复现的环境里工作，而不是每次都重新猜项目怎么启动。
你可以把常用准备步骤写成脚本，例如安装依赖、复制示例配置、启动服务。不要把真实生产密钥写进脚本；需要密钥时使用本机环境变量、团队密钥管理或明确的人工审批流程。
新手推荐：先记录启动命令工作树对应 Git worktree。它允许 Codex 在同一个仓库旁边开出独立工作区，适合并行做多个任务，或让不同 agent 同时处理不同分支而互不覆盖。
如果你还不熟悉 Git 分支，先不要急着使用工作树。等你需要“同时让 Codex 修两个 bug”“一个任务跑测试，另一个任务改文档”时，再开启。使用后要定期清理不再需要的工作树，避免磁盘里留下很多过期副本。
新手推荐：会用分支后再用浏览器设置让 Codex 可以打开网页、点击、输入、截图和检查页面状态。它适合前端验收、登录态页面检查、表单流程测试和资料查阅。官方 App 文档也把 In-app browser 作为桌面 App 的重要能力之一。
浏览器能力会接触账号、网页内容和可能的表单提交。不要让 Codex 随便在第三方网站提交个人信息、付款、删除内容或改权限。做前端测试时，优先用本地 localhost 页面；做线上页面时，先明确允许它看什么、不能点什么。
电脑操控让 Codex 像用户一样读取屏幕、点击应用和输入内容。它适合没有 API 或 MCP 的桌面软件，例如设计工具、办公软件、系统弹窗或只能通过 UI 操作的流程。
这类能力风险高于普通文件编辑。首次使用时只给明确、低风险、可撤销的动作，例如“打开这个窗口并截图说明”。不要让它替你最终确认付款、改密码、删除云文件、发送消息或提交重要表单。
新手推荐：只做观察和截图归档对话用于收起不再活跃的线程，让侧边栏保持干净。归档不是删除，通常还可以找回历史上下文、结论和文件修改记录。
如果一个任务已经完成、验证通过、总结也写好了，就可以归档。还没合并、还在等审批、或者你可能继续追问的任务先不要归档，避免之后找上下文费劲。
新手推荐：完成后再归档使用情况用于查看额度、用量或套餐相关状态。Codex 的可用功能、额度和并发能力会随账号计划变化，具体以 ChatGPT / OpenAI 当前套餐说明为准。
如果 Codex 变慢、任务被限流、无法启动新任务，先看这里，再去核对 订阅 Plus / Pro 章节。团队账号还要确认管理员是否限制了某些能力。
新手推荐：遇到限制时先看这里什么时候需要改设置
| 你遇到的情况 | 优先检查 |
|---|---|
| Codex 回答太技术或太啰嗦 | 常规、个性化 |
| 每次都问同一个安全命令 | 常规权限、配置、项目 AGENTS.md |
| 需要连接 Figma、Notion、飞书或数据库 | MCP 服务器 |
| 想让任务结束后自动跑测试 | 钩子、环境 |
| 想同时跑多个仓库任务 | Git、工作树 |
| 需要打开网页检查 UI | 浏览器 |
| 需要操作桌面软件 | 电脑操控 |
| 找不到旧任务 | 已归档对话 |
| 无法继续启动任务或额度不足 | 使用情况、订阅套餐 |
官方资料怎么配合看
设置页里的名称会随着客户端迭代变化。遇到和教程截图不一致时，先看 OpenAI 官方的 Codex App docs，再回到本教程查中文场景解释。
04 手机端协同
最后核对
官方资料最后核对日期：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、远程环境中运行。
- 如果任务会写文件、跑命令、访问网络，仍然需要理解并确认对应权限。
平台支持
OpenAI 官方文章说明，Codex 手机端能力正在 iOS 和 Android 的 ChatGPT App 中预览推出。连接 macOS 上的 Codex App 可用；连接 Windows 上的 Codex App 支持仍以官方当前说明为准。
推荐使用场景
手机端最适合处理“离开电脑但不想让任务停住”的时刻：
- 通勤路上查看长任务进展。
- Codex 需要你选择方案时，快速给出方向。
- 任务卡在权限审批时，从手机上批准或拒绝。
- 会议前让 Codex 汇总最新代码、issue、文档或客户背景。
- 突然想到一个改动点，先发给 Codex 开始探索，回到电脑后再细看 diff。
不适合怎么用
手机端不适合替代完整的本地审查流程。下面这些事情最好回到电脑上做：
- 大范围代码合并前的最终 review。
- 涉及生产环境、密钥、账单、发布部署的高风险操作。
- 需要长时间阅读大量 diff 的任务。
- 需要你手动操作 IDE、调试器或本地 GUI 的任务。
如果你在手机上审批命令，建议只批准自己能看懂的操作。遇到删除、覆盖、部署、传输敏感数据等动作，先停下来，回到电脑上确认。
一个典型流程
- 在电脑上打开 Codex 桌面 App，并进入对应项目。
- 让 Codex 开始一个需要较长时间的任务，例如排查失败测试或整理文档。
- 离开电脑后，在 ChatGPT 手机 App 中进入 Codex。
- 打开同一个正在运行的任务线程。
- 查看 Codex 的输出、截图、终端日志、测试结果或 diff。
- 如果 Codex 需要确认，直接在手机上回复、审批或调整方向。
- 回到电脑后，再做完整 diff review、运行验证命令和提交。
和 Codex Cloud 的区别
| 对比项 | 手机端连接桌面 App | Codex Cloud |
|---|---|---|
| 执行位置 | 你的电脑、devbox 或远程环境 | OpenAI / ChatGPT 连接的云端任务环境 |
| 文件与凭据 | 留在原机器上 | 依赖云端连接的仓库与授权 |
| 适合任务 | 跟进本地长任务、审批、查看结果 | 不依赖本地电脑的仓库任务 |
| 是否能离开电脑 | 可以，但原执行环境要可连接 | 可以 |
一句话：手机端 Codex 更像“随身工作台”，Codex Cloud 更像“云端执行环境”。
下一步：连接第三方 API
05 第三方 API 与密钥风险
Codex 默认最稳妥的使用方式，是通过官方 ChatGPT / OpenAI 账号登录，并使用官方支持的模型与服务。连接第三方 API 属于进阶配置，适合已经理解 config.toml、API Key、Base URL、模型名和代理网关含义的用户。
第三方 API 风险
本文只整理接入思路，不推荐任何具体中转商或 API 服务。第三方 API 可能涉及账号安全、API Key 泄露、账单超额、服务稳定性、日志留存、数据跨境、模型能力降级和合规风险。请只使用你信任、能承担责任的服务，并避免把密钥写进截图、仓库和公开文档。
最后核对
官方资料最后核对日期：2026-05-29。本文参考 OpenAI Codex config reference。社区工具资料最后核对日期：2026-05-29，参考 Codex++、CCX 与 CC Switch。
三种方案怎么选
| 方案 | 适合谁 | 优点 | 需要注意 |
|---|---|---|---|
| 手动配置 | 想理解 Codex 底层配置的人 | 透明、可控、方便排障 | 要自己维护 config.toml，字段写错就不生效 |
| Codex++ | 主要使用桌面 App，希望图形化管理中转注入的人 | 有管理界面，能把配置写成 CodexPlusPlus provider | 是第三方 launcher / 注入工具，Codex 更新后可能需要跟进适配 |
| CCX + CC Switch | 有多个供应商、需要协议转换和统一切换的人 | CCX 负责网关与路由，CC Switch 负责供应商配置管理 | 组件更多，需要理解本地服务、端口、密钥和代理链路 |
如果你只是刚开始学习 Codex，建议先完成 第一个任务，再回来看本章。第三方 API 不是入门必需步骤。
方案一：手动配置
这种是没办法使用 Codex APP 的插件功能的，可以看看方案二可以使用插件功能。
手动配置的核心，是编辑本机的：
~/.codex/config.toml改之前先备份：
cp ~/.codex/config.toml ~/.codex/config.toml.backup
cp ~/.codex/auth.json ~/.codex/auth.json.backup
两类登录思路
| 思路 | 怎么理解 | 适合场景 |
|---|---|---|
| ChatGPT 登录 | Codex 仍使用 ChatGPT / OpenAI 登录态，provider 只改请求入口或中转地址 | 想保留官方账号能力，同时把请求转到兼容入口 |
| API Key 登录 | Codex 使用环境变量里的 API Key，按 provider 配置请求接口 | 用 OpenAI API Key 或自建兼容 Responses API 的服务 |
不要同时混着改太多东西。第一次配置时，先只新增一个 provider，确认能跑通后再整理多套 profile。
ChatGPT 登录态示例
也就是你的 Codex 先要登录到 ChatGPT 先。
第一步，手动修改文件配置文件：
在~/.codex/config.toml 文件下添加如下配置。
下面只展示示例，字段和值要按你实际服务填写：
model = "gpt-5-codex" #这里填你想要的模型
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.ciyuan]
name = "ciyuan" # 填你的模型提供商名字或者中转站名字，这里以词元为例
base_url = "https://ciyuan.today/v1" # 填你的模型提供商的请求 URL
wire_api = "responses" # 这里不要变
env_key = "OPENAI_API_KEY" # 这里将会通过环境变量的方式注入并启动Codex APP
requires_openai_auth = false这里的重点是：
model_provider要和[model_providers.xxx]里的xxx完全一致。base_url通常写到/v1，不要把/v1/responses整段写进去。wire_api = "responses"表示 Codex 以 Responses API 的请求形态访问。requires_openai_auth = true表示使用已有 OpenAI / ChatGPT 登录态。
第二步，打开终端输入环境变量
export OPENAI_API_KEY="这里填你的key"
第三步，终端中启动 Codex APP
这里如果是 mac，你要用终端启动，不然可能读不到模型。要特别注意，在启动前要先彻底关闭 Codex APP
终端输入以下命令启动：
open -a Codex第四步，打开 Codex APP
你就可以看到已经应用到新模型了：
API Key 登录示例
如果你的服务使用 API Key，推荐把密钥放在环境变量里，不要写死在 config.toml：
export OPENAI_API_KEY="sk-your-api-key"对应配置示例：
model = "gpt-5.1-codex-max"
model_provider = "my-api-provider"
[model_providers.my-api-provider]
name = "My API Provider"
base_url = "https://example.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
requires_openai_auth = false如果上游只支持 Chat Completions，而不支持 Responses API，通常不能只靠 config.toml 解决，需要使用 CCX 这类网关做协议转换。
修改鉴权文件
打开 ~/.codex/auth.json，然后添加 OPENAI_API_KEY 为你模型服务商的API KEY：
手动配置后怎么验证
- 完全退出并重新打开 Codex。
- 让 Codex 执行一个只读任务，例如总结当前目录结构。
- 如果失败，先检查
model_provider名称、base_url、wire_api、环境变量和 API Key 权限。 - 出现认证错误时，先切回备份配置，不要反复把真实 Key 粘贴到对话里。
请只读说明当前工作区路径、你准备使用的模型和验证方式。不要修改任何文件。方案二：Codex++
Codex++ 是面向 Codex App 的外部增强 launcher 和管理工具。根据项目 README，它不修改 Codex App 原始安装文件，而是通过外部 launcher 启动 Codex，并使用 Chromium DevTools Protocol 注入增强脚本。
它更适合这些情况：
- 你主要使用 Codex 桌面 App。
- 你希望通过图形界面维护 Base URL 和 Key。
- 你希望切换回官方 ChatGPT 登录态时，不完全靠手写配置。
- 你能接受第三方 launcher 带来的兼容性和维护风险。
流程步骤
- 打开 Codex++ Releases，下载与你系统匹配的安装包。
会有 「Codex++ 管理工具」和 「Codex++ app」两个安装包。
- 安装后打开
Codex++ 管理工具。
首次打开如果出现这个错误：
不要慌，先打开「系统设置」-「隐私与安全性」，点击「仍要打开」：
打开后就会进入到这个管理界面：
同样的方式，安装刚才安装包中的 Codex++ app。你就可以看到管理工具检测全绿了。
确认已经检测到 ChatGPT 登录状态。
- 添加中转配置，填写 Base URL 和 Key。
选择「供应商配置」-添加供应商配置。填写自己的供应商的配置，并填写模型相关信息，注意 接入方式要选「纯API」的方式：
模型列表可以选择从上游获取，如果你配置的是中转站，这里就可以用很多不同的模型了：
可以看到这个工具做的就是帮你更方便的写入配置。
保存后可以测试联通情况，没问题，直接选择使用：
- 从
Codex++入口启动 Codex，而不是从原版 Codex 入口启动。
重新启动后，你就能看到现在 Codex已经完全使用了我们自定义的模型供应商，并可以选择更多的模型。
其中插件也可以直接使用了：
根据 Codex++ README，它会写入类似这样的 provider：
model_provider = "CodexPlusPlus"
[model_providers.CodexPlusPlus]
name = "CodexPlusPlus"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://example.com/v1"
experimental_bearer_token = "sk-..."Codex++ 验证和回滚
- 验证时，先用只读任务确认 Codex 能正常响应。
- 如果 Codex++ 菜单或增强功能没有出现，确认你是从
Codex++入口启动，而不是原版 Codex。 - 如果要回到官方登录态，在管理工具里清除 API 模式或切回官方配置。
- Codex App 更新后，如果页面结构变化，注入脚本可能需要等待 Codex++ 适配。
方案三：CCX + CC Switch
这个方案把“网关”和“切换工具”拆开：
- CCX：AI API 代理与协议转换网关，支持 Claude Messages、OpenAI Chat Completions、Codex Responses、Gemini 等入口，也提供 Web 管理界面、渠道编排、故障转移和模型路由。
- CC Switch：桌面管理工具，用来管理 Claude Code、Codex、Gemini CLI 等工具的供应商配置、MCP、Skills 和会话，并支持一键切换。
适合你有多个国产模型 API、多个中转服务、多个 Key，或者需要把 Chat Completions 形态转换成 Codex 可用入口的情况。
第 1 步：部署 CCX
如果使用 Docker，可以参考 CCX README 中带访问密钥的方式：
docker run -d \
--name ccx \
-p 3000:3000 \
-e PROXY_ACCESS_KEY=your-proxy-access-key \
-e APP_UI_LANGUAGE=zh-CN \
-v $(pwd)/.config:/app/.config \
crpi-i19l8zl0ugidq97v.cn-hangzhou.personal.cr.aliyuncs.com/bene/ccx:latest启动后打开：
http://localhost:3000第 2 步：在 CCX 添加渠道
在 CCX Web 管理界面里添加你的上游渠道：
- 选择上游服务类型。
- 填写国产模型或中转服务的 API Key。
- 填写 Base URL。
- 配置模型映射、可用模型或路由规则。
- 先用 CCX 自带测试功能确认渠道可用。
这里要确认一件事：Codex 需要的是 Responses API 入口。如果上游只有 Chat Completions，CCX 需要负责协议转换。
第 3 步：安装 CC Switch
CC Switch 可以用桌面安装包，也可以按你的习惯使用命令行安装。你给出的命令是：
npm install -g cc-switch安装后初始化：
cc-switch init初始化时把 CCX 地址作为中转入口，例如：
http://localhost:3000第 4 步：切换配置并启动 Codex
切换到你刚配置好的供应商：
cc-switch use <配置名>然后重新启动 Codex，让新的 provider 配置生效。
如果 CC Switch 写入的是 ~/.codex/config.toml，建议切换后打开文件核对一次：
- 当前
model_provider是否是你刚选择的配置。 base_url是否指向 CCX。- API Key 是否没有被写进公开仓库。
- 原有 MCP、Skills、profile 等配置是否还在。
常见问题
| 现象 | 先检查什么 |
|---|---|
| 切换后没有生效 | 是否完全重启 Codex，model_provider 名称是否一致 |
| 报认证错误 | API Key 是否有效，环境变量是否被当前 shell 继承 |
| 报接口路径错误 | base_url 是否只写到 /v1，不要重复拼上 /responses |
| 国产模型无法响应 | 上游是否支持 Responses API；不支持时需要 CCX 这类网关转换 |
| 插件或 Skills 配置不见了 | 切换工具是否覆盖了通用配置，是否有备份或共享配置片段 |
| 旧会话不可见 | 参考 切换 provider 后历史会话不可见怎么办 |
下一步：用 Codex 完成第一个任务
06 第一个 Codex 任务
最后核对
官方资料最后核对日期：2026-05-27。本章以开发一个简单网页为例，演示从创建工作目录到任务迭代的完整操作流程。
本章以"用 Codex 桌面 App 开发一个关于 AI 发展历史的简单网页"为例，走完一次完整的任务闭环，帮助你快速上手 Codex 桌面 App 的基本用法。
第一步：创建本地工作文件夹
在本地新建一个空文件夹，作为 Codex 的工作目录。Codex 生成的所有文件都会保存在这里。
注意
文件夹路径中尽量不要包含中文，避免部分工具出现兼容性问题。
第二步：选择对话还是项目
打开 Codex 桌面 App 后，你需要选择用"对话"还是"项目"来开始任务。
- 对话：适合一次性任务，操作简单，但多个对话之间不共享工作目录。
- 项目：支持在同一工作目录下创建多个对话，每个对话处理不同的子任务，管理更方便。
如果你不确定选哪个，优先选择项目——后续扩展任务时更灵活，工作目录也只需要配置一次。
第三步：添加工作目录
选择项目后，点击"使用现有文件夹"，选中刚才创建的文件夹。
选择完成后，对话框左下角会显示当前工作目录的路径，确认路径正确即可。
第四步：输入任务描述，开始执行
在对话框中输入你的需求，点击发送，Codex 就会开始执行任务。
请帮我设计并实现一个高质量的单页网页，主题是「人工智能的发展历史」。
网页目标：
这是一个面向普通用户的科普型网页，用来介绍 AI 从早期理论到现代应用的发展过程。页面应有科技感、历史感和未来感，整体视觉效果要精致，不要像普通课程作业页面。
内容方法：
请你自行搜索、筛选并组织与「人工智能发展历史」相关的关键资料，包括重要时间节点、代表人物、核心技术、重大事件、产业变化和未来趋势。
内容组织不要堆砌资料，要形成清晰叙事：
- 先交代 AI 发展的起点和早期思想来源；
- 再说明不同阶段的技术路线如何变化；
- 接着展示关键突破如何推动 AI 进入新的发展阶段；
- 最后总结当前 AI 的主要方向和未来可能性。
页面结构：
请根据主题自行设计合理的页面结构。页面应至少包含：
- 首屏介绍；
- 历史发展脉络；
- 技术演进逻辑；
- 关键转折点；
- 未来展望。
具体模块名称、内容顺序和信息密度由你根据资料和设计效果自行决定。
设计方法：
整体使用现代科技风格，深色背景为主，可以使用渐变、光效、网格、粒子、玻璃拟态、时间线、卡片等元素。视觉元素要服务于内容表达，不能为了炫技而堆砌。
页面需要做到：
- 信息层次清晰；
- 视觉统一；
- 有明显主视觉；
- 有适当留白；
- 阅读体验顺畅；
- 在桌面端和移动端都有良好表现。
交互与动效：
请加入适度的交互和动画效果，例如加载动效、滚动显现、卡片悬停、背景缓慢动态效果等。动效要克制、流畅，不要影响阅读。
技术要求：
- 使用 HTML、CSS 和 JavaScript 实现；
- 所有代码放在一个 index.html 文件中；
- 可以使用 CDN 引入必要的前端库；
- 不要使用 React、Vue、Angular 等前端框架；
- 页面保存后可以直接在浏览器打开运行；
- 代码结构清晰，不要有无效代码、伪代码或占位内容。
输出要求：
直接输出完整可运行的 index.html 代码。
不要省略代码。
不要写解释说明。任务完成后，Codex 会在对话中展示结果，同时将生成的文件写入工作目录。
如果生成的是网页文件，可以直接点击 Codex 弹出的"打开"按钮，在 App 内置浏览器中预览效果，无需手动打开文件夹。
第五步：逐步迭代
对结果不满意时，直接在当前对话框中继续描述修改需求，Codex 会在已有基础上进行调整。
随着对话轮次增加，上下文窗口会逐渐被填满。点击对话框右下角的小圆圈图标，可以查看当前上下文使用情况。
什么是上下文窗口？
每次对话都有容量上限，每一轮问答都会占用一定空间。当上下文接近满载时，建议在项目中新建一个对话继续处理后续任务——新对话仍然共享同一工作目录，不需要重新配置。
如果使用的是"对话"模式而非项目，新建对话时需要重新指定工作目录，两个对话之间也是相互隔离的，不方便统一管理。这也是推荐使用项目的主要原因之一。
⼀份好的Prompt⻓什么样？
一、划定内容边界：5 个必含模块加 4 步叙事
它没有用"介绍一下 AI 历史"这种模糊说法，而是精确到了两层。
页面骨架：至少包含首屏介绍、历史发展脉络、技术演进逻辑、关键转折点、未来展望这 5 个模块。叙事逻辑：内容按 4 步推进，先讲起点和早期思想来源，再讲不同阶段技术路线怎么变，接着讲关键突破怎么把 AI 推进新阶段，最后落到当前方向和未来可能。
5 个模块是骨架，4 步叙事是骨架里的逻辑。骨架告诉 AI 页面长什么样，逻辑告诉 AI 这些模块之间怎么串。
就像你不会跟实习生说"写个报告"，你会说"写一份覆盖 3 个竞品的竞品分析，每个竞品写清优劣势"。有边界，活才不会跑偏。
提示
这份 Prompt 给的不是数量硬指标（比如"15 个节点"），而是结构硬指标：必含哪几块、内容按什么顺序推进。对一篇叙事型网页，结构边界比数量边界更管用。
二、锁定视觉风格：写的是具体效果，不是"好看一点"
它规定了风格：现代科技风，深色背景为主，要有科技感、历史感、未来感。可用的元素也列清楚了：渐变、光效、网格、粒子、玻璃拟态、时间线、卡片。
它没有说"好看一点"。"好看"是最没用的需求描述，每个人对"好看"的定义都不一样。它给的是具体风格加具体元素，还补了一条约束"视觉服务内容，不为炫技堆砌"，又划了一条反例"不要像普通课程作业页面"。给正面方向，也给反面边界，AI 才知道往哪走、不往哪走。
提示
"好看"无法验收，"深色科技风、有时间线、不像课程作业页"可以验收。需求里能被验收的词，才是有效的词。
三、设计内容流转：背后跑的是叙事逻辑
好的需求不只描述用户看到什么，还描述背后有什么在运转。
这份 Prompt 背后运转的不是数值系统，是叙事逻辑。它明确要求"不要堆砌资料，要形成清晰叙事"，并且把这条叙事线定死了：起点和早期思想，到技术路线变化，到关键突破推动阶段跃迁，再到当前方向与未来。
正是这条线，让页面从"一堆时间点的罗列"变成"一段能读下去的故事"。同样一批资料，按时间平铺只是资料库，按这条因果线组织才是科普。
提示
对工具类产品，"背后运转的"是数据和状态。对内容类产品，"背后运转的"是叙事逻辑和信息架构。这份 Prompt 抓的是后者。
四、想好阅读闭环：从首屏落到未来展望
它把开头和结尾都安排了。首屏负责入口和主视觉，结尾落在"未来展望"，让读者读完手里有个结论，而不是看到一半断掉。
这里有一点要说实话：这份 Prompt 的闭环是"阅读闭环"，比交互型产品的闭环弱。它没有要求分享按钮，也没有要求把结论收成一句可转发的话这类让内容扩散出去的设计。如果目标是让这页被传播，这是可以加码的地方。
提示
闭环不一定是"再来一次"按钮。对一篇科普页，最低限度的闭环是：读者滚到底，能拿到一个明确结论。这份 Prompt 用"落到未来展望"完成了这个最低闭环。
五、画技术红线：说清楚"不要做什么"
它划了几条红线：用 HTML/CSS/JS，所有代码放进一个 index.html，CDN 可以用，但不许用 React、Vue、Angular；保存后要能直接在浏览器打开运行；不许有无效代码、伪代码、占位内容；直接输出完整代码，不省略，不写解释。
告诉 AI"不要做什么"，比告诉它"要做什么"更关键。不画这条线，AI 很可能自作主张给你引一套构建框架，也可能在该写内容的地方塞一堆"待补充"的占位注释，最后给你一个跑不起来、打开是半成品的东西。
就像带实习生：你不说"不要用付费素材"，他可能买了一堆图回来找你报销。这份 Prompt 里"不许伪代码和占位内容"这一条，挡的正是这种半成品交付。
提示
红线分两种：技术栈红线（不用框架、单文件）和交付红线（不许占位、不许省略、直接能跑）。这份 Prompt 两种都写了，AI 就没有"自由发挥到跑偏"的空间。
一个容易看错的点：留白不等于歧义
这份 Prompt 有一句话看着像"没说清楚"："具体模块名称、内容顺序和信息密度由你根据资料和设计效果自行决定。"
这不是歧义，是主动授权。
歧义是 AI 会猜错、且猜错就返工的地方。授权是这件事本来就该交给执行方判断、怎么做都在可接受范围内的地方。模块叫什么名字、时间线放多密，属于后者：定死了反而限制发挥，交出去更好。
区分这两者很重要。该说清的地方含糊，是 bug；该放手的地方硬管，是浪费。这份 Prompt 把"必含哪几块、按什么逻辑讲、不许用什么"这些会影响结果的事定死了，把"具体怎么排版、用什么标题"这些不影响结果的事交了出去。这个分寸是它写得好的地方。
歧义是最贵的 Bug
顺着上面说。需求里真正的歧义，最后都会变成返工成本。两个经典例子：
"下班顺路买一斤包子带回来，如果看到卖西瓜的，买一个。" 买一个什么？西瓜还是包子？
"小明无法将奖杯放到口袋里，因为它太大了。" 什么太大了？奖杯还是口袋？
人能靠常识猜，AI 不行。AI 会严格按字面执行，然后给你一个"技术上正确、但完全不是你要的"东西。
这份「AI 发展史」Prompt 基本没有这类歧义。每个维度都用清单写死，留白的地方又明说了"由你决定"。该定的定了，该放的放了，AI 不需要猜。
信息不是越多越好
斯坦福那门课里有一篇阅读材料《长上下文是怎么失败的》，核心观点是：给 AI 塞太多信息，效果反而变差。因为 AI 会被无关信息干扰，就像你给实习生发 20 页参考资料，他反而找不到重点。
那这份 Prompt 不是挺长吗？
它长，但不杂。它的长是"按维度分块的清单式长"：目标、内容方法、内容组织、页面结构、设计方法、交互动效、技术要求、输出要求，每一块都是可验收的条目，没有一段在写"我个人很喜欢科技感""灵感来自某某网站"这种帮不上忙的话。
少而准胜过多而杂。这份 Prompt 走的是"多而准"，每一条都准，所以多也不拖后腿。
提示
判断一份长 Prompt 该不该删：逐条问"这条能不能拿来验收成品"。能，留着；不能（比如纯个人偏好、灵感来源），删掉。
写给 AI 的任务书：一份检查清单
斯坦福大学 2025 年秋季有一门课叫 CS146S: The Modern Software Developer，专门教"AI 时代怎么做软件"。它的一个核心观点是：Spec is the new source code，需求规格就是新的源代码。
课程给学生发了一份正式的设计文档模板，里面有十几个字段，覆盖现状、功能需求、非功能需求、设计决策、技术设计、实施计划、测试策略等。专业开发者写几十页设计文档才开工，你写五行就能让 AI 干活，这就是 AI 时代给普通人的杠杆。
把那份专业模板简化成新手能用的五条，正好对应前面拆出来的规律。下面用这五条对照这份「AI 发展史」Prompt：
| 检查项 | 问自己 | 这份 Prompt 怎么答的 |
|---|---|---|
| 问题陈述 | 用户要什么体验？一句话能说清吗？ | 能。面向普通人的 AI 发展史科普单页，要有科技感、历史感、未来感 |
| 方案描述 | 功能、模块、交互、视觉，具体了吗？ | 具体。5 个必含模块、4 步叙事、视觉元素清单、交互清单，全列了 |
| 技术约束 | 技术栈写了吗？ | 写了。HTML/CSS/JS，单文件 index.html，可用 CDN，禁三大框架 |
| 红线 | 说清楚"不要什么"了吗？ | 说了。不用框架、不许伪代码占位、不省略代码、不写解释 |
| 交付标准 | 怎么算做完？手机能用吗？有闭环吗？ | 保存后浏览器直接能跑，桌面和移动端都要好，叙事落到未来展望 |
五条全部命中。这就是这份 Prompt 读起来不像"聊天"、像"任务书"的原因。
提示
你写给 AI 的每一段 Prompt，本质上就是一份迷你设计文档。下次动手前拿这五条过一遍：问题陈述、方案描述、技术约束、红线、交付标准。缺哪条，补哪条。
小作业
利用上面的Prompt技巧生成一个你想要的网页，并且把截图发到群里
07 任务顺序与并行
本小节来介绍一下，在使用 codex 的过程中，如何进行任务顺序执行的管理以及任务的并行操作。
我们使用codex开发obsidian新手教程网站作为示例：来说明任务的顺序执行管理和并行操作
1.顺序执行
选择本地项目/创建新的项目，该项目实际上就对应我们本地的一个文件夹，它存储在我们的本地。
然后点击创建新的对话。
我们向 CodeX 发送任务，让他帮我们设计一个网站，这个时候他就会开始执行。
在这个任务没有执行的过程中，如果我们去给他下达新的命令，就只能等待。显示的是下面这种情况：
这种相当于当前他正在执行一个任务，我们给他的另外两个命令就需要排队，必须等前面的任务执行完成之后才能执行。
但是如果我们想修改一下要求，比如想让他明确这个网站的背景风格为“手绘风格”，如果等他设计完成之后再去修改就会比较麻烦。我希望他在正在设计的时候就知道我的风格要求。
这时候，我们可以点击引导选项。这样操作后，他就会执行一个“插队”的操作：
原本的任务顺序：
(a) 执行网站设计
(b) 介绍技术选型
(c) 执行手绘风格要求（原定第三个任务）插队后的效果：
我们想让“手绘风格”在设计过程中就发挥作用，通过点击引导提示，这个任务就会直接插队到当前正在执行的任务当中。
这实际上就是通过这样一个过程，演示如何对顺序执行的任务进行管理以及相关的插队操作。
2.如何并行
实际上就是一个项目（Project）里面，我们同时去执行多个任务。
这个时候，我们只需要在左侧边栏点击“新建对话”就可以了。这样的话，它的几个任务就会并行执行，互不干扰。
08 权限管理
这一节介绍 Codex 中常见的权限与审批模式。不同入口的界面文案可能会略有差异，但核心问题始终是一样的：Codex 能不能自动改文件、能不能自动执行命令、哪些操作需要你确认。
最后核对
官方资料最后核对日期：2026-05-27。本文参考 OpenAI Codex CLI – Getting Started 与 Using Codex with your ChatGPT plan。具体名称、入口和可用选项请以你当前使用的客户端界面为准。
三种常见模式
Suggest
这是最保守的模式。Codex 可以读取文件并提出修改建议，但真正改文件或执行命令前，通常仍需要你确认。它适合初次了解陌生仓库、做代码审查、或者你希望全程掌控关键操作的时候使用。Auto Edit
这个模式通常允许 Codex 自动写文件，但在执行 shell 命令时仍会保留人工确认。它适合你已经比较了解项目结构，想让 Codex 快速完成重构、批量改文档或局部实现，但又不想完全放开命令执行权限的场景。Full Auto
这是自主性最高的模式。Codex 会在受限环境中自动读取、写入并执行命令，适合较长的连续任务，比如修复构建、跑一轮验证或完成一个边界明确的小功能。因为风险更高，最好只在版本可回退、任务范围清晰、并且你理解当前沙盒边界时使用。
怎么选更稳妥
- 第一次进入新项目，优先从
Suggest开始。 - 需要批量修改文档、样式或测试时，可以考虑
Auto Edit。 - 只有在任务边界明确、仓库可回滚、并且你接受它连续执行命令时，再考虑
Full Auto。
使用时的提醒
- 不同客户端可能不会把权限模式写成完全一样的中文名，建议优先认官方英文模式名。
- 即使使用更自动化的模式，也要保留对高风险操作的复核，比如安装依赖、删除文件、访问网络、推送代码或处理敏感信息。
- 如果你不确定当前模式会不会执行某个动作，先让 Codex 说明它准备运行哪些命令、会改哪些文件，再决定是否继续。
09 Skills 和插件
这一节介绍 Codex 里的 Skills 和 Plugins。不同版本的 App 或工作区里，入口位置和展示方式可能会调整，但核心区别相对稳定：Skill 更像可复用的工作流程说明，Plugin 更像把一组能力打包后分发和安装的方式。
最后核对
官方资料最后核对日期：2026-05-27。本文参考 Codex Skills 与 Using Codex with your ChatGPT plan。如果你的界面与本文截图不完全一致，请优先以当前客户端和工作区可用功能为准。
如果你在 App 中看到了和技能、插件相关的入口，可以结合下面的概念来理解它们：
Skill 是什么
Skill 可以理解为一份让 Codex 稳定执行重复任务的操作手册。当某个工作流已经很固定，例如“审查 PR”“整理文档”“补案例索引”，就可以把它沉淀成一个 Skill，减少每次重复描述的成本。
一个 Skill 通常会包含：
- 一个
SKILL.md文件
这里会写清触发场景、执行步骤、输出格式和注意事项。 - 必要时配套脚本、模板或参考文件
用来帮助 Codex 更稳定地完成任务。
常见使用方式是：
- 先准备或安装可用的 Skill。
- 在发起任务时明确说明你希望使用哪个 Skill。
- 让 Codex 按这个 Skill 的流程执行，再根据结果继续追问或迭代。
有些工作区会提供更直接的安装或启用方式；也有一些场景里，需要先把 Skill 放到约定目录，或者通过现有插件能力来分发。稳妥起见，不建议把“给一个 GitHub 链接就一定能自动安装”写成固定结论，更好的表述是：可以把 Skill 来源交给 Codex 协助识别和安装，但具体流程会受客户端能力和工作区设置影响。
Plugin 是什么
Plugin 更像一种打包和分发机制，用来把可复用工作流、应用集成、MCP 服务配置等能力组合起来，方便在项目或团队中统一安装和使用。
简单理解：
Skill关注“这件事应该怎么做”。Plugin关注“把哪些能力打包起来，方便安装和复用”。
所以 Skill 往往是具体流程本身，而 Plugin 更像承载这些流程和集成能力的安装单元。
怎么理解它们的关系
你可以把两者想成：
- Skill 是“工作说明书”
- Plugin 是“装着说明书、工具和连接配置的工具箱”
有些插件里会包含一个或多个 Skills，也可能附带应用集成或 MCP 配置。这样团队在迁移环境时，不用手动一个个配置。
使用时的提醒
- 插件和技能的具体入口会随版本变化，不要把某个截图里的按钮位置当成永远不变。
- 如果插件涉及外部系统、浏览器、邮箱、知识库或项目管理工具，先确认它是只读还是可写。
- 涉及安装、写回外部系统或共享给团队时，最好保留人工复核。
10 自动化
这一节介绍 Codex 中的 Automation。如果说 Skill 更关注“怎么做”，那么 Automation 更关注“什么时候自动去做”。
最后核对
官方资料最后核对日期：2026-05-27。本文参考 Using Codex with your ChatGPT plan 与 Codex use cases。不同客户端、工作区套餐和权限设置下，自动化入口和可选项可能会有所不同。
当一个工作流已经足够稳定、而且会重复发生时，就可以考虑把它交给 Automation，在后台按计划触发，而不是每次都手动发起。
适合自动化的任务包括：
- 定期检查文档死链
- 每周整理一次 issue 或 PR 摘要
- 每天汇总 failing CI
- 在固定时间提醒补复盘或更新文档
可以怎么理解自动化
一个自动化任务通常至少会包含三部分：
- 目标对象
它对应哪个项目、仓库或线程。 - 触发时机
比如固定时间、固定间隔，或者稍后回到当前任务继续跟进。 - 执行内容
也就是让 Codex 到时具体去完成什么。
常见使用流程
在支持 Automations 的界面里，你通常会经历类似下面的流程：
- 选择对应的项目、仓库或当前线程。
- 设定执行时间或执行周期。
- 写清楚自动化任务本身的目标、输出格式和边界。
- 保存后观察第一次运行结果，再决定是否长期保留。
这里最容易被忽略的一点是：自动化 prompt 要尽量写成”自包含”的任务说明。不要默认它会记得你之前说过什么，最好把检查范围、输出格式和验证要求写完整。
❌ 不够自包含的写法：
请检查一下文档里的链接有没有问题。✅ 推荐的写法：
请检查 docs/ 目录下所有 .md 文件中的外部链接是否有效。
检查范围：仅检查以 http:// 或 https:// 开头的链接，忽略锚点和相对路径。
输出格式：按”文件路径 | 行号 | 链接 | 状态”列出失效链接；全部正常时输出”全部链接正常”。
验证方式：对每个链接发起 HEAD 请求，超时 5 秒视为失效。
限制：不修改任何文件，不创建新文件。两者的区别在于：第一种每次触发时 Codex 都要靠猜测来填补缺失的细节，结果容易不稳定；第二种把边界、格式、验证方式都写明白了，无论在哪次执行、哪个上下文里，行为都是一致可预期的。
使用时的提醒
- 不同工作区里的自动化能力可能并不完全一样，有些支持项目级任务，有些更偏向提醒和跟进。
- 第一次配置时，建议先从低风险、只读型任务开始。
- 如果自动化会写文件、访问外部系统或触发通知，最好先确认权限边界和人工复核方式。
11 个性化入口
前段时间，Codex 新增了一个会陪你工作的桌面小宠物。它不只是一个装饰，还会把 Codex 当前在忙什么实际显示出来。
这个宠物最大的价值在于状态的可视化：
- 任务进度一目了然： 不用一直切换回 Codex 的界面，就能看到当前任务的进度。
- 实时状态反馈：
- 它会在 Codex 忙碌的时候显示忙碌的画面。
- 在需要你确认的时候会发出提醒。
- 任务完成之后，它也会让你知道可以去检查结果了。
1. 安装
打开”设置” → “外观”，往下滑到”宠物”这一栏。在这里可以选择喜欢的宠物类型并点击”唤醒”，桌面上就会出现选定的小宠物了。
快捷命令方式： 如果不想进设置，也可以直接在聊天框中输入 /，选择”宠物”选项，同样可以唤醒或收起桌面宠物。
2. 使用
唤醒之后，像平常一样下达指令，然后去做其他事情。小宠物会在屏幕上陪伴着你，实时显示任务完成进度。
比如下面这个情况：它正在进行搜索，并执行我们的任务。
任务完成之后，会显示一个绿色对勾，提示任务已完成。也就是说，我们可以实时看到它的执行过程以及完成结果，完全不需要盯着 Codex 窗口等待。
12 CLI 安装与登录
本页先覆盖 Codex CLI 的安装与登录。桌面端、ChatGPT、Cloud 和 IDE 入口会在 入口地图 中分别展开。
最后核对
官方资料最后核对日期：2026-05-27。CLI 系统要求与安装方式参考 openai/codex 官方仓库、CLI install 文档 和 Codex CLI Help Center。
安装前检查
官方仓库当前给出的 CLI 运行环境建议：
| 项目 | 建议 |
|---|---|
| 操作系统 | macOS 12+、Ubuntu 20.04+/Debian 10+、Windows 11 通过 WSL2 |
| Git | 推荐 2.23+，便于 PR 辅助能力 |
| 内存 | 4GB 起步，8GB 更稳 |
本地先确认：
node -v
npm -v
git --version
安装 CLI
常见安装方式：
npm install -g @openai/codex更新到最新版本：
npm install -g @openai/codex@latest检查版本：
codex --version
登录方式
运行：
codex根据终端提示完成登录。官方资料说明 Codex 可以通过 ChatGPT 账号在多个入口中使用，具体可用计划、限额和组织策略以 Codex in ChatGPT Help Center 为准。
第一次只读任务
进入一个本地项目根目录：
cd path/to/your/project
codex先让 Codex 只读仓库：
请先阅读这个仓库的目录结构、README、包管理器配置和测试配置。不要修改文件。请总结：
1. 项目用途
2. 主要技术栈
3. 如何安装依赖和运行测试
4. 你建议我下一步交给你的 3 个低风险任务
安装失败时怎么判断
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
codex 命令找不到 | npm global bin 未进 PATH | 查看 npm bin -g，把目录加入 shell PATH |
| 登录后仍提示无权限 | 账号计划、组织策略或会话状态问题 | 重新登录，并查看 Help Center 中的计划说明 |
| Windows 运行异常 | 未使用 WSL2 或 shell 环境不完整 | 按官方建议使用 Windows 11 + WSL2 |
| 仓库命令跑不起来 | 项目依赖未安装或本地环境缺失 | 先安装项目依赖，再让 Codex 读取测试配置 |
完成后继续：第一次让 Codex 改代码。
13 第一次让 CLI 改代码
第一次实战不要选择“重构整个项目”。选择一个小、可验证、失败也容易回滚的任务，先建立你和 Codex 的协作节奏。
最后核对
官方资料最后核对日期：2026-05-27。本文参考 Codex CLI features、openai/codex getting started、AGENTS.md guide 与 Codex security。
选择第一个任务
适合新手：
- 修复一个文案错别字。
- 给一个纯函数补测试。
- 更新 README 里的过期命令。
- 解释一个小模块，并补充必要注释。
- 修复一个已经有失败测试覆盖的 bug。
- 为文档站补一段截图占位说明。
暂时避开：
- 大规模架构重构。
- 跨多个服务的迁移。
- 没有测试的核心业务逻辑改动。
- 涉及生产凭据、账单、权限和删除数据的操作。
- 需要同时修改十几个文件的需求。
第一步：只读建图
先让 Codex 理解仓库：
请只读分析当前仓库，不要修改文件。
请输出：
1. 项目用途
2. 关键目录
3. 安装、测试、构建命令
4. 当前任务适合从哪里开始
5. 你建议我第一次交给你的低风险任务
第二步：给出小任务
推荐复制这个模板：
请修复当前仓库中最小范围的一个测试失败。
要求：
1. 先运行测试，确认失败信息。
2. 阅读相关代码和测试，不做无关重构。
3. 修改最少必要文件。
4. 修复后重新运行相关测试。
5. 最后总结：失败原因、改了哪些文件、验证命令和剩余风险。如果任务是文档：
请更新 [文档文件] 中关于 [主题] 的说明。
要求：
1. 先读取相关官方资料和现有文档结构。
2. 保持中文教程风格，避免整段翻译官方原文。
3. 涉及操作步骤时添加截图占位。
4. 修改后运行文档站构建。
5. 最后列出来源链接和需要人工补图的位置。
第三步：观察过程
重点观察五件事：
| 观察点 | 说明 |
|---|---|
| 是否先读上下文 | 好结果通常来自充分阅读相关文件 |
| 是否控制范围 | 第一次任务不追求顺手重构 |
| 是否解释命令 | 命令执行前应说明目的 |
| 是否运行验证 | 修改完成后要跑相关测试或构建 |
| 是否说明风险 | 没能验证的部分要如实记录 |
第四步：检查 diff
完成后自己再看一遍：
git diff可以让 Codex 自查：
请 review 你刚才的改动，不要继续修改文件。
请重点检查：
1. 是否有无关改动
2. 是否遗漏测试
3. 是否引入安全或兼容风险
4. 是否还有未验证的地方
第五步：提交前记录
提交前让 Codex 给出一段摘要：
请用提交前摘要格式输出：
- 改动目标
- 修改文件
- 验证命令
- 验证结果
- 剩余风险
- 建议 commit message如果结果满意，再提交：
git add .
git commit -m "fix: resolve failing test"第一次失败怎么办
| 失败现象 | 处理方式 |
|---|---|
| 改动太大 | 让 Codex 停下，只保留最小修复思路 |
| 测试跑不起来 | 先让它解释环境缺口和命令来源 |
| 方向不对 | 回到只读分析，让它列出文件依据 |
| 输出太泛 | 要求按文件、命令、风险分段输出 |
| 误改无关文件 | 用 git diff 确认，再手动决定保留或丢弃 |
完成标准
第一次实战完成后，你应该拿到：
- 一个很小的 diff。
- 一条可复现的验证命令。
- 一段清楚的改动摘要。
- 一个可复用的任务模板。
- 对 Codex 权限和审批的初步理解。
下一步继续读：了解 Codex 基本组成。
14 VS Code 中使用 Codex
最后核对
官方资料最后核对日期：2026-05-27。本章以 VS Code 为例演示插件安装与基本用法，操作界面以实际版本为准。
本章介绍如何在 VS Code 代码编辑器中安装 Codex 插件，并通过插件完成开发任务。相比桌面 App，在 VS Code 中使用 Codex 可以更直接地看到文件目录结构和修改前后的对比，适合习惯在编辑器里工作的开发者。
安装 Codex 插件
打开 VS Code，点击左侧边栏的「扩展」图标，在搜索框中输入 Codex，选择第一个结果，点击「安装」即可。
提示
这里安装的是 OpenAI 官方发布的 ChatGPT 插件，其中集成了 Codex 的对话与代码辅助能力。
打开插件对话窗口
安装完成后，在 VS Code 中打开任意一个项目文件，右上角会出现 ChatGPT 的图标。点击该图标，右侧边栏就会展开 Codex 的对话窗口。
开始使用
对话窗口打开后，直接输入需求，Codex 就会开始辅助完成开发任务，用法与 Codex 桌面 App 基本一致。
使用 @ 指定文件：
在对话框中输入 @ 后选择具体文件，Codex 会直接定位到该文件进行分析或修改，比让它全局搜索更快、更准确。建议在任务目标明确时优先使用 @ 指定相关文件。
App 与 VS Code 插件怎么选
| Codex 桌面 App | VS Code 插件 | |
|---|---|---|
| 适合场景 | 多任务管理、Skills、Automations | 边写代码边调用，贴近编辑器工作流 |
| 文件结构可见性 | 需要切换界面 | 直接在编辑器里查看 |
| 修改前后对比 | 独立查看 | 可结合编辑器 diff 查看 |
| 推荐用户 | 需要并行任务或插件协作 | 日常编码开发者 |
根据自己的使用习惯选择即可，两者可以配合使用。
15 AGENTS.md 项目规则
对于 Codex 而言，我们每开启一个新的对话窗口，它都会进入一个全新的上下文。它不记得之前发生了什么，对于整个项目的记忆都是空白的。
所以 Codex 提供了记忆系统来解决这样的问题
AGENTS.md 是给 Codex 这类编码代理看的项目说明文件。它可以描述项目结构、开发命令、测试要求、代码风格和协作边界。
最后核对
AGENTS.md 机制请以 Codex AGENTS.md 官方文档 和 openai/codex GitHub repository 为准。最后核对日期：2026-05-27。
为什么需要 AGENTS.md
没有项目规则时，Codex 需要从仓库里推断很多事情：
- 用哪个包管理器。
- 如何运行测试。
- 哪些目录是生成物。
- 哪些文件不能改。
- 提交前要跑哪些检查。
AGENTS.md 能把这些规则显式写下来，减少反复解释。
建议放在仓库哪里
针对于我们打开的项目，我们可以在项目根目录下创建一个 agents.md 的文件。
它是 Codex 的记忆文件，Codex 在开始工作之前会先读取 agents.md 的内容。我们可以测试一下：
- 在 agents.md 文件里面写入一些内容。
- 回到 Codex 对话窗口问它：“这是一个什么样的系统？”
从这里可以看出，Codex 会读取 agents.md 文件，把里面的内容自动带入到新的对话，作为它们的上下文。
当然，在当前目录根目录下创建 agents.md 只对当前文件夹生效，并不是全局生效的。
如果想要全局生效，有以下两种方式：
设置全局文件后，对于所有的项目都会生效。所以它们的作用域和作用范围是不一样的，这一点大家需要了解一下。
推荐模板
# AGENTS.md
## 项目概览
- 项目类型：
- 主要语言：
- 关键目录：
## 常用命令
- 安装依赖：`...`
- 本地开发：`...`
- 运行测试：`...`
- 类型检查：`...`
- 格式化：`...`
## 代码规范
- 遵循现有代码风格。
- 不做无关重构。
- 新增功能必须补充或更新测试。
## 安全边界
- 不读取或提交 `.env`、密钥和私有凭据。
- 不执行删除生产数据的命令。
- 修改数据库迁移前先说明影响。
## 交付要求
- 说明改动文件。
- 说明验证命令和结果。
- 说明未验证项和剩余风险。写作建议
- 越具体越好。
运行测试：pnpm test比“记得测试”有用。 - 把生成目录、构建产物、锁文件策略写清楚。
- 如果是 monorepo，请说明每个包的边界。
- 如果有特殊 lint、格式化或代码生成流程，写在命令区。
- 对安全敏感项目，单独写“禁止事项”。
最小可用版本
# AGENTS.md
## 项目命令
- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 构建：`pnpm build`
## 改动规则
- 修改前先阅读相关文件。
- 保持现有代码风格。
- 不提交构建产物和环境变量文件。
## 验证要求
- 文档改动运行：`pnpm build`
- 代码改动运行相关测试。
## 安全边界
- 不读取 `.env` 或任何私有凭据。
- 不执行发布、部署、数据库迁移和删除数据命令。16 沙盒与审批
Codex 可以读取文件、修改代码、运行命令。能力越强，越需要清楚的边界。
最后核对
官方资料最后核对日期：2026-05-27。安全相关说明请以 Codex security 和 openai/codex sandbox 文档 为准。
你需要关心什么
先把风险拆成几个层面：
- 文件系统：能读写哪些目录。
- 网络：是否允许访问外网。
- 命令：是否允许安装依赖、启动服务、跑迁移。
- 凭据：是否可能接触密钥、token、cookie。
- 数据：是否会修改数据库、对象存储或生产资源。
低风险任务
通常可以较快推进：
- 修改文档。
- 补充测试。
- 修复本地可复现 bug。
- 更新非敏感配置。
- 运行项目已有的测试命令。
高风险任务
建议先确认计划：
- 删除文件或批量移动文件。
- 数据库迁移。
- 修改认证、权限、支付、账单逻辑。
- 访问生产服务。
- 上传、下载或处理敏感数据。
- 引入新依赖或大规模升级依赖。
给 Codex 的安全提示词
请在动手前先说明你计划运行的命令和可能影响的文件。不要读取 `.env`、密钥、token 或任何私有凭据。不要执行删除数据、发布、部署或迁移命令，除非我明确确认。Codex 桌面 App 中的审批流程
在 Codex 桌面 App 里，当 Codex 要执行写入文件、运行命令、访问网络等敏感操作时，会暂停并弹出审批提示，列出它打算做的事。你可以：
- 放行：确认操作合理，继续执行
- 拒绝：取消该步骤，Codex 会尝试其他方案
- 修改提示词：告诉它换一种方式做
这个机制在前面的实战案例中多次出现——比如 Playwright MCP 操作浏览器时，每一步填写输入框、打开网页都需要手动放行。
养成习惯：不确定的操作先看清楚再放行，尤其是涉及删除文件、写入配置或访问外部服务的步骤。
团队建议
- 在
AGENTS.md写清楚禁止事项。 - 把高风险命令放进人工审批流程。
- 给测试、lint、类型检查提供明确命令。
- 避免把生产凭据放在普通开发环境里。
- 对 Codex 产出的 PR 仍然执行正常代码审查。
17 Codex Cloud
Codex Cloud 是一种不依赖本地环境的使用方式。你不需要在自己电脑上打开 App 或 CLI，直接在浏览器里连接 GitHub 仓库，让 Codex 在云端完成任务。
提示
CLI 的使用方式见 CLI 安装与登录，IDE 插件见 在 VS Code 中使用 Codex，桌面 App 的使用见 Codex 桌面 App 下载与安装。
适合场景
- 较长的任务，不想占用本地资源
- 多个任务并行推进
- 让 Codex 在独立环境里分析仓库、提出 PR
- 不在电脑旁、只有浏览器时临时使用
如何使用
第 1 步：打开 Codex Cloud
访问：https://chatgpt.com/codex/cloud
连接成功后会跳转到任务页面：
第 2 步：授权并选择仓库
Cloud 模式直接在 GitHub 仓库中运行，需要先完成授权。你可以授权全部仓库，也可以只选择特定仓库：
第 3 步：下达指令，查看任务进度
下达指令后，Codex 会在云端执行任务，进度显示在页面下方的任务列表里：
点击任务可以查看每一步的执行过程和中间状态。任务完成后也可以查看最终回答和产出内容：
与桌面 App 模式的区别
| Codex 桌面 App | Codex Cloud | |
|---|---|---|
| 运行环境 | 本地电脑 | 云端（GitHub 环境） |
| 是否需要安装 | 需要下载电脑端客户端 | 不需要，浏览器直接访问 |
| 适合任务 | 本地代码、插件、自动化 | 远程仓库分析、PR 生成 |
| 并行任务 | 支持 | 支持 |
18 排障手册
本页收集 Codex 使用中的常见问题。欢迎通过 PR 持续补充。
Codex 找不到项目上下文
可能原因：
- 你不在项目根目录。
- 仓库缺少 README、测试命令或项目说明。
- monorepo 没有说明包边界。
处理方式：
- 先让 Codex 只读目录并总结项目结构。
- 添加或更新
AGENTS.md。 - 在任务说明里指定相关目录。
Codex 改动范围太大
处理方式：
- 明确“只修改这些文件”。
- 要求“先输出计划，不要动手”。
- 把任务拆成更小的步骤。
- 在 review 时拒绝无关重构。
测试跑不起来
处理方式：
- 让 Codex 先定位测试命令。
- 检查依赖是否安装。
- 区分环境问题和代码问题。
- 如果是环境问题，让 Codex 记录阻塞，而不是继续乱改。
生成内容不准确
处理方式：
- 要求 Codex 引用它依据的文件。
- 对官方事实要求附链接。
- 让它区分“已确认”和“推测”。
- 让它先读代码再写文档。
登录或权限问题
处理方式：
- 更新 Codex CLI 到最新版本。
- 重新运行登录流程。
- 检查当前账号计划和组织策略。
- 查看官方 Help Center 的 Codex 相关文章。
切换 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，不要把它当成官方认证或账号切换工具。