CodexGuide

CodexGuide：面向全球初学者、创作者、开发者与团队的 Codex 实践指南

作者freestylefly 仓库freestylefly/CodexGuide ↗ 星标★ 3,696 字数68,181 许可MIT 阅读1

GitHub 原文 ↗

摘要GitHub README 适合快速了解项目，真正学习时更推荐打开网站阅读：网站里有更完整的导航、搜索、侧边栏目录、截图、设置速查图、学习路线和实战案例。每篇关键资料都会尽量标注最后核对日期，方便你判断内容是否需要回到 OpenAI 官方资料重新确认。

面向全球初学者、创作者、开发者与团队的 Codex 实践指南

简体中文 · English · 在线阅读 · 主题皮肤 · 学习路线 · 快速上手 · 进阶教程 · 实战案例 · 参考手册 · 社区共建图

从第一次上手，到把 Codex 接入真实工作流；帮助不同背景的人用 Codex 完成开发、创作、研究、自动化与团队协作。如果这个项目帮你节省了摸索时间，欢迎点亮 Star，让更多人看到它。

感谢packyapi的独家赞助

在线网站

CodexGuide 的在线阅读地址是 codexguide.ai。

GitHub README 适合快速了解项目，真正学习时更推荐打开网站阅读：网站里有更完整的导航、搜索、侧边栏目录、截图、设置速查图、学习路线和实战案例。每篇关键资料都会尽量标注最后核对日期，方便你判断内容是否需要回到 OpenAI 官方资料重新确认。

如果你正在第一次接触 Codex，可以直接从网站的学习路线开始；如果你已经知道自己要用 CLI、桌面 App、Cloud 或 IDE，可以先看快速上手和进阶教程。

主题皮肤

CodexGuide 的主题皮肤站地址是 theme.codexguide.ai。

这里可以预览 Codex Themes 的官方主题、使用方法和下载入口，适合想给 Codex 桌面工作区换上个性化视觉风格的用户。

项目愿景

Codex 正在从“帮你写代码的工具”，演进为一套覆盖 CLI、Cloud/Web、IDE extension、桌面 App、移动端协同、浏览器和自动化能力的 AI 工作流系统。

CodexGuide 想做的不是命令速查表，而是一份面向真实任务的实践知识库。它关注三个问题：

怎么开始：初学者应该从哪个入口、哪个任务、哪个设置开始。
怎么交付：如何把需求讲清楚，让 Codex 读项目、改文件、跑命令、给出可检查结果。
怎么沉淀：如何把一次成功任务变成团队可复用的模板、规则、案例和安全边界。

这份教程主要以中文组织内容，但目标并不局限在中文用户或开发者。它也会覆盖创作者、研究者、产品、运营、技术写作者、团队负责人，以及需要把 Codex 接入日常工作的非开发场景。

适合谁

第一次使用 Codex 的小白：跟着桌面 App、订阅、设置、手机协同和第一个任务跑通完整闭环。
想把 Codex 用进项目的开发者：学习 CLI、IDE、Git、测试、CI、AGENTS.md、沙盒与审批。
内容创作者与知识工作者：把 Codex 用在写作、PPT、资料整理、知识库、浏览器和工作流自动化里。
团队负责人和工具建设者：建立团队规则、任务模板、权限边界、复盘结构和可迁移案例库。
正在选入口的人：对比桌面 App、CLI、Cloud、IDE、ChatGPT 手机端和插件生态的适用场景。

❤️ 赞助商

想出现在这里？添加微信时请备注你的产品名和项目赞助说明。

赞助商	介绍
	感谢 PackyCode（PackyAPI）对本项目的独家赞助！PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务，具备自动故障转移、智能路由和无限并发等功能，让 AI 编程成为真正的生产力工具。通过此链接注册，立即开始使用。
	感谢 APIMart 赞助了本项目！APIMart 是专注 AI 图片/视频生成的低价 API 平台，GPT-Image-2 低至 `$0.006/张`，1 美元可出图 160+ 张。图片、视频一套异步 API 通吃，提交任务拿 ID、回调取结果，跑批万张不超时、换模型不改代码。按量付费、无月费，通过此注册链接注册即可开用。
	PayForChat 支持 ChatGPT、Claude 会员开通与充值：微信直付、无需海外信用卡，官方渠道为你自己的账号充值，不成功全额退款，中文售后、可开收据。点击这里注册体验。
	AI-MEMBER 面向个人用户、开发者与团队，提供 ChatGPT Plus+Pro充值、Claude Pro、Gemini Pro、Gork Super 等正价会员代充服务。点击这里了解服务，查看教程。
	GetGPT Pro 提供 ChatGPT、Claude 等 AI 订阅开通与充值服务，支持自助下单、快速到账与售后支持。
	项目赞助。PPToken 提供 ChatGPT、Claude、Gemini 等主流 AI 模型 API 中转与密钥分发服务，支持低延迟、高可用、按量计费与订阅套餐灵活选择。
	感谢随想AI中转站对本项目的赞助！随想AI中转站是一家可靠高效的 API 中继服务提供商，提供 Claude、Codex、Gemini 等的中继服务。注重隐私的中转站·无数据倒卖·无模型掺水，隐私，透明，极速售后。新账户注册每日签到就送 0.5 元测试额度，充值额度 1:1，无需订阅，按量付费。多线路冗余、跨区域容灾、自动故障切换，长链路 SSE 不中断。99.9% 可用性，关键调用从不掉队。
	接入二狗，稳如老狗。二狗 API 中转站，全站 0.1x～0.2x 超低倍率，提供 Claude / GPT / Grok 等多个国内外 100% 纯血大模型接口。顶级 IPLC 线路 + 住宅双 ISP 冗余，确保全国范围稳定低延迟访问。欢迎各位开发者、工作室注册使用。

你会在这里看到什么

内容	说明
入门路线	从安装、登录、订阅、设置、手机协同、API 连接到第一个低风险任务
入口地图	解释桌面 App、CLI、Cloud、IDE、ChatGPT 和集成生态该怎么选
配置专题	覆盖 CLI 选项、`config.toml` 和项目规则配置
工作流方法	任务设计、验证方式、团队 playbook
实战案例	PPT、Draw.io、浏览器、Obsidian、临床文献综述、飞书、Figma、Notion、CI 修复等场景
官方资料索引	汇总 OpenAI 官方资料、GitHub 仓库和关键事实来源

快速入口

模块	适合解决什么问题
学习路线	从入门、进阶到团队化的阅读顺序
快速上手	桌面 App、账号、首个任务和任务闭环
手机端协同桌面任务	用 ChatGPT 手机 App 中的 Codex 入口跟进桌面任务
CLI 安装与登录	在本地终端安装 Codex CLI 并完成登录
第一次让 Codex 改代码	用 CLI 进入真实仓库，完成一次可检查的代码任务
进阶教程	CLI、IDE、Cloud、权限、AGENTS.md、自动化和团队实践
参考手册	OpenAI 官方资料、Codex 更新记录和参考来源
AGENTS.md	给 Codex 编写项目级规则和协作边界
沙盒与审批	文件、命令、网络、凭据和生产资源的安全边界
自动线程管理	继续、分叉、移交和整理 Codex 任务
Cloud、IDE 与桌面 App	不同 Codex 使用入口的适用场景
实战案例库	可复制到真实项目的任务模板和复盘结构

内容框架

CodexGuide
├─ guide         # 学习路线
├─ start         # 快速上手
├─ advanced      # 进阶教程
├─ recipes       # 实战案例
├─ manual        # 参考手册
└─ community     # 社区共建图与贡献方向

当前已搭建：

Codex 桌面 App 入门路径。
ChatGPT 手机 App 协同桌面任务。
Codex CLI 和 IDE 使用路径。
Codex 多入口使用地图和选择建议。
Codex 配置与扩展专题。
任务说明、提示词模板和验证方法。
团队实践方法。
AGENTS.md 项目规则模板。
沙盒、审批和安全边界说明。
Cloud、IDE、桌面 App、ChatGPT 使用场景对照。
内容生产、知识库、浏览器、CI 修复等案例模板。
在线文档站、官方资料索引和社区贡献模板。

本地预览

环境要求：

Node.js 22.12+，且低于 25
pnpm 10.33.0

pnpm install
pnpm dev

构建静态站点：

pnpm build

默认开发服务会启动 VuePress 文档站。线上版本会发布到 codexguide.ai。

设计原则

官方优先：功能、价格、可用性、安全策略以 OpenAI 官方资料为准。
小白友好：每个入门章节尽量说明“为什么这样做”和“什么时候不要这样做”。
真实任务导向：减少抽象概念堆砌，多给可复制的任务流程、输入、输出和验证方式。
安全边界清晰：涉及文件写入、命令执行、联网、凭据、浏览器和电脑操控时明确风险。
可沉淀：鼓励把一次成功任务整理成 AGENTS.md、模板、案例、复盘和团队规范。

Star 趋势图

社区共建

欢迎加入 CodexGuide 交流群，与同频伙伴一起交流 Codex 使用经验、实践案例和最新动态。点击加入 Codex 交流群即可加入，也欢迎微信扫码关注公众号苍何，获取更多 AI 工具与效率实践。

微信扫码关注公众号苍何

事实来源

本仓库优先引用官方资料，并会在关键页面标注“最后核对日期”。当前骨架参考：

参与贡献

欢迎提交：

新手友好的教程改写。
可复现的真实案例。
常见错误和解决方案。
团队实践、模板和工作流。
官方文档变更同步。

请先阅读贡献指南。如果你还不确定怎么贡献，可以从社区共建图或 good first issue 开始。

开源协议

本项目采用 MIT License 开源。你可以在保留许可声明的前提下自由使用、修改、分发与二次开发。

声明

本项目是社区维护的 Codex 实践知识库，并非 OpenAI 官方项目。涉及功能、计划、价格、可用性和安全策略等时间敏感信息时，请以 OpenAI 官方资料为准。

index

description: "CodexGuide 学习路线，围绕说清楚、执行、验证、交付的闭环展开，帮助中文读者找到适合自己的入口。"

::: tip 最后核对官方资料最后核对日期：2026-06-29。本文用于规划 CodexGuide 阅读顺序，Codex 的入口、能力边界和账号可用性请以 Codex 文档入口、Codex App docs、Codex CLI features 与 Codex Cloud docs 为准。 :::

学习路线

欢迎来到 CodexGuide。本网站提供给初学者完善的 Codex 快速上手栏目，也提供了希望进一步了解 Codex 所需的进阶教程，以及非常使用的实战案例。

Codex 是 OpenAI 官方出品的智能体，能够读项目、写代码、运行命令、调用工具，也能帮你整理资料、生成内容。随着官方不断完善功能，这款产品正在越来越受人们的喜爱。并非局限于开发者，律师、会计、HR等各种职业都在探索如何使用 Codex 来改善工作流。现如今我们已经看到了非常可观的效率提升。

本教程近期正在积极改进中。如果有修改建议，欢迎提出 issue，或者参与社区共建。反馈会得到及时处理。

初步了解 Codex
如何在 macOS / Windows 上安装桌面 App
准备 ChatGPT 订阅
接入第三方API
Codex 的基本组成
通过对话或在项目内工作，完成你的第一个任务
如何更好地描述任务使效率更高
如何验证并提升任务的完成质量
使用手机远程连接 Codex

如果你是开发者，除了上述基于Codex APP的教程，还有面向CLI、IDE、Cloud的快速入门教程：

安装 Codex CLI
运行 Codex CLI
入门 CLI 的选项和命令
在 VS Code 中使用 Codex
使用 Codex Cloud

进阶教程

这个栏目则会以更专业的角度解释这个软件的运行机制，引入更多高级特性和最佳实践。适合学有余力，希望深入了解 Codex 工作原理的用户。

你会学到：

理解费用、token 和上下文
理解 APP 页面的权限
编写 AGENTS.md
使用 config.toml 和 profiles
理解 Skills、Plugins
使用 Automation
使用 Hooks
理解沙盒与审批机制
管理线程、工作树和 subagent
将 Codex 接入团队流程
排查常见问题

实战案例

学了许多知识却无从下手？CodexGuide 提供了 17 个真实场景的示例，学习真实的 Codex 工作流经验分享：

用 PPT Skill 生成演示文稿
用 Draw.io MCP 绘制架构图
用 Playwright MCP 操作浏览器
用 HyperFrames 生成动画视频
在 Obsidian 中生成配图
用飞书 CLI 处理协作数据
在 Obsidian 中搭建 LLM Wiki
用 Figma MCP 读取设计稿
用 Notion MCP 打通知识空间
用 DKFile 发布网页
远程定位并修复服务器 Bug
用 Chrome 插件控制网页
自动修复 GitHub Actions CI
整理临床文献综述
用 Hatch Pet 生成桌面宠物
用安卓手机远程操控 Codex
用桌面宠物显示任务状态

一个实用的起点

如果一定要给一个顺序：先完成快速上手的第一个任务，利用 Codex 完成第一个任务，然后按你的需求进入进阶教程或实战案例。

但不用强迫自己按顺序读完。Codex 的能力足够强大，也许花时间探索这个软件比看教程更高效。当你认为使用 Codex 存在明显困惑的时候，也许可以来本网站，看看有没有解决方案。

或许你更想要有一个地方能提出疑问，与其他人交流 AI 使用心得？可以先阅读付费交流群说明，了解收费原因和服务边界，再决定是否加入。

app installation

description: "Codex 桌面 App 下载与安装教程，说明 macOS、Windows 安装入口、账号登录和首次启动前的准备工作。"

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

Codex 桌面 App 下载与安装

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

下载

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

如果第一次注册，也可以接受邀请：chatgpt.com/codex/

macOS：

Codex 桌面 App 下载页 macOS

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

打开下载好的 .dmg 文件
把 Codex 图标拖进「Applications（应用程序）」文件夹
首次启动时，macOS 可能弹出「无法验证开发者」——无需担心，打开「系统设置 → 隐私与安全性」，点击「仍要打开」即可

Windows：

Codex 桌面 App 下载页 Windows

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

如果点击后微软商店打不开、白屏，或一直卡在「获取」/「正在安装」，可以改用离线安装方式。核心思路是：不走微软商店客户端，直接从微软服务器解析 Codex 安装包，再手动安装。

打开 store.rg-adguard.net，左侧选择 ProductId，输入 Codex 的产品 ID：9PLM9XGG6VKS，右侧选择 RP，点击对勾解析。
在结果里找到文件名包含 OpenAI.Codex 的最新安装包。普通 Windows 电脑通常选 x64 架构，后缀可能是 .msix、.msixbundle 或 .appxbundle。
如果浏览器直接点击无法下载，可以右键复制安装包链接，粘贴到浏览器地址栏下载，或在 PowerShell 里用 curl.exe -L "安装包链接" -o Codex.msix 下载。
下载完成后双击安装包。如果双击无法安装，在安装包所在目录打开 PowerShell，再执行：

Add-AppxPackage -Path ".\Codex.msix"

::: warning 安全提醒这个方法只是绕开微软商店客户端，安装包仍应来自微软下载服务器。如果 PowerShell 提示缺少依赖包，再回到解析结果里下载对应架构的 Microsoft.VCLibs、Microsoft.UI.Xaml 等依赖包并先安装。不要安装网盘、群文件或不明来源的二次打包文件。 :::

安装后验证

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

下一步

下一步：订阅 ChatGPT Plus / Pro。

account plan

description: "ChatGPT Plus 与 Pro 订阅指南，整理 Codex 可用性、账号准备、支付路径和订阅前需要核对的信息。"

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

订阅 ChatGPT Plus / Pro

为什么需要订阅

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

套餐	月费（美元）	Codex 可用情况
Free	免费	仅限试用，额度极少
Go	$8	在Codex中与Free没有区别
Plus	$20	完整 Codex 访问，日常开发够用
Pro 5x	$100	Plus 的 5 倍额度，适合中高强度
Pro 20x	$200	Plus 的 20 倍额度，最大化额度
Bussiness / Enterprise	与销售团队联系	更高级的服务支持

对大多数个人开发者来说，Plus（$20/月）是性价比最高的起点。

前提条件

能正常访问国际网络（需要代理工具，这里不展开）
一个注册好的 ChatGPT / OpenAI 账号
支持国际支付的方式（详见下方）

如果还没有账号，需要先准备一个国外手机号用于接收注册验证码，可以使用专门的接码平台完成注册。

可以试试：https://hero-sms.com

Hero SMS 注册验证码平台示例

方法一：苹果礼品卡（最稳定，推荐优先尝试）

支付宝购买

适合已有 iOS 设备或愿意准备一台的用户。整个流程在国内支付宝内完成充值，不需要境外银行卡。

准备物品：

一台苹果设备（iPhone / iPad，可以是二手，能正常使用 App Store 即可）
已注册好的海外区 Apple ID（注册时选美国或新加坡，不需要绑定国内手机号）
国内支付宝（正常使用即可）

操作步骤：

在苹果设备上退出国内 Apple ID，登录准备好的海外区 Apple ID
打开支付宝，将定位切换为「美国旧金山」，支付宝会自动切换为国际版界面
在支付宝功能区找到「苹果礼品卡」，购买 $20 额度
购买成功后复制兑换码，打开 App Store，点击头像 → 「兑换礼品卡或代码」，粘贴充值
打开 ChatGPT App，登录账号，进入设置订阅 Plus，选择 Apple ID 余额支付

支付宝购买苹果礼品卡示例

给Apple id充值礼品卡：

Apple ID 兑换礼品卡示例

::: tip 如果支付宝购买偶尔不稳定，可以通过代理访问苹果官网直接购买礼品卡，一次性多充值几个月额度，后续续订不需要重复操作。 :::

苹果官网购买

前提准备：

1、一个美区的APPID。 2、招行 VISA 卡

操作步骤：

1、Clash 代理选择台湾地区（非必须，可视情况）

2、打开苹果官方礼品卡购买页面：

地址：https://applegiftcard.apple.com

点击这里的 buy：

选择 Email：

填写相关信息，接收人和赠送人姓名和邮箱。（这里名字可以随便填）

然后点 add to Bag

然后选择 check out，这里需要登录你的美区 appid

选择支付方式 VISA 卡：

然后这个地方填自己的 VISA 卡信息就好啦：

::: tip 这里的地址和电话就实际选择国内地址和手机即可。 :::

最后一个是确认：

::: tip 这里如果用的是招行 visa 卡，金额过多，会触发人工审核，一般会被拒绝掉，建议分多次购买。 :::

第三方

https://shop.pockyt.io/index

这里也可以购买，信息来源于社区，建议自行甄别。

方法二：土耳其区 App Store（第三方经验，价格优先）

如果你的核心诉求是降低长期订阅成本，可以参考低价区 App Store 的做法：单独准备一个土耳其区 Apple ID，通过该区礼品卡给 Apple ID 余额充值，再在 ChatGPT iOS App 里用 App Store 应用内购订阅。

::: warning 来源与风险本小节整理自第三方文章 App Store Price《没有海外信用卡也能稳定订阅 ChatGPT/Claude》，源文发布于 2026-03-06，作者/发布方为 App Store Price。下图也来自该文。如有问题，请联系作者删除

这不是 OpenAI 或 Apple 官方订阅说明。跨区账号、礼品卡余额、汇率、App Store 定价和风控策略都可能变化，存在充值失败、订阅失败、余额无法退款、账号触发安全验证或后续续费不稳定等风险。正式操作前建议先小额验证，不要把主 Apple ID 频繁切区。 :::

App Store Price 提供的 ChatGPT Plus 各区价格对比示例

图源：App Store Price 文章。本小节后续截图除特别说明外，均整理自同一篇文章。价格、排名和汇率只代表源文截图时的状态，实际付款前一定以 App Store 结算页显示为准。

适合谁：

已经有 iPhone / iPad，愿意单独维护一个海外区 Apple ID。
能接受第三方礼品卡渠道的不确定性。
更看重订阅价格，而不是最省心的官方直连支付体验。

详细流程

第一步：核对当前低价区

先打开 App Store Price 的 ChatGPT 价格页，选择 ChatGPT Plus 月付项，看当前各地区价格。源文截图显示土耳其区价格较低，但低价区会随 App Store 定价、汇率和税费变化，操作前必须重新核对。

第二步：确认网络节点与账号地区一致

源文建议先准备土耳其节点，并在 IP 检测页面确认当前出口地区。核心原则是：注册 Apple ID、填写地区信息、登录 App Store 时，地区信息要尽量保持一致，减少触发安全验证的概率。

土耳其节点 IP 检测示例

第三步：注册土耳其区 Apple ID

打开 account.apple.com 注册新的 Apple ID。注册时选择土耳其地区，按页面提示填写邮箱、手机号和验证码。源文说明旧的 appleid.apple.com 入口也可用，但 Apple 当前页面名称可能会变化，以实际页面为准。

Apple ID 注册页面示例

::: caution 建议为这条订阅路线单独准备 Apple ID，不要频繁切换自己的主力 Apple ID 地区。跨区账号可能涉及 Apple 当前服务条款、账单地址真实性和后续风控，请自行确认能接受这些风险。 :::

第四步：补齐 Payment Address

注册完成后，在 Apple 账号或 iPhone / iPad 的 App Store 账户设置里补齐 Payment Address。即使不绑定土耳其本地银行卡，Apple 也可能在购买或兑换时要求补充账单地址。

App Store 账户 Payment Address 示例

第五步：购买土耳其区 App Store 礼品卡

源文提到土耳其区礼品卡可以通过淘宝、闲鱼等渠道购买，也可以在土耳其数字商品平台购买。它以 oyunfor.com 为示例：注册并登录后，在站内找到 App Store 礼品卡，选择所需面值并加入购物车。

Oyunfor 礼品卡选择页面示例

::: warning CodexGuide 不推荐具体商家，也不保证任何第三方礼品卡渠道的稳定性。礼品卡一旦兑换通常不可退款，建议先小额测试。 :::

第六步：选择支付方式并付款

源文示例中，Oyunfor 支持信用卡和 Binance Pay。信用卡页面里会出现不同支付通道，部分通道可能要求土耳其本地支付方式，源文选择了可用的国际卡通道。截图中的示例为 1000 土耳其里拉礼品卡，并叠加约 2.5% 手续费，实际手续费以付款页为准。

Oyunfor 支付方式选择示例

随后进入支付页，填写银行卡信息并确认付款。源文里的银行卡信息已经做了遮挡；你自己操作时不要把银行卡、验证码、礼品卡兑换码截图发给任何人。

银行卡支付页面示例

如果银行或支付通道要求 3D Secure / 短信验证码，按页面提示完成验证。

银行卡验证码验证页面示例

第七步：收取并兑换礼品卡

付款成功后，礼品卡通常会通过邮件发送。源文的邮件截图中露出了兑换码，所以这里不再放图。拿到兑换码后，打开 App Store，点击头像，进入「兑换礼品卡或代码」，把土耳其区礼品卡兑换到同一个土耳其区 Apple ID。

App Store 兑换礼品卡示例

第八步：在 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（备选）

Visa 卡购买

适合没有 iOS 设备、但拥有能够境外支付的 Visa 卡的用户。整个流程在 Google Play 与手机 ChatGPT 上完成。

准备物品：

一台 Android 设备（能够正常安装 Google Play 即可）
注册好的 Google 账号
注册好的 ChatGPT 账号
一张能够进行海外支付的 Visa 卡

操作步骤：

进入 PC 端 Google Play，登录谷歌账号，点击右上角头像，将该页面拉到最下方，找到服务条款项目：

服务条款

找到其中的国家/地区版本，记住此时的地区：

国家/地区版本

打开你的 Clash 等代理，选择相同的地区。

回到 Google Play 页面，点击右侧下拉菜单中的「付款和订阅」：

付款和订阅

点击「添加支付方式」，添加信用卡和借记卡，此时添加你能够支付的 Visa 卡。注意地区与前面服务条款中的地区保持一致；必要时可使用 DeepSeek 等生成真实的国外地址。

添加支付方式

完成后查看手机端 Google Play，点击头像打开设置：

打开设置

点击「常规」下的「账号和设备偏好设置」：

账号和设备偏好设置

查看「国家/地区和个人资料」，确认地区与上文服务条款中的地区一致：

在手机端 Google Play 中下载 ChatGPT，登录账号后直接点击升级 Plus，然后支付即可。若支付不成功，检查该 Visa 卡是否支持人民币付款；部分卡只支持对应地区货币。

升级 Plus 支付情况

方法四：AI MEMBER 卡密自助充值（省去海外支付步骤-操作更简单）

如果不想折腾海外 Apple ID、礼品卡或地区切换，也可以购买一张 ChatGPT Plus 充值卡密，再到 AI MEMBER 充值中心自助提交。整个流程都在浏览器里完成，适合已经有 ChatGPT 账号、但不方便使用海外支付方式的用户。

::: tip 第三方服务说明

AI MEMBER 是第三方充值服务，并非 OpenAI 官方渠道。商品价格、库存、处理时间、支持的账号类型和售后规则，以下单页面实际显示为准。

:::

准备物品：

购买卡密地址：https://www.ai-member.icu

一个可以正常登录的 ChatGPT 账号

支付宝或商品页当前支持的其他付款方式

AI MEMBER 网站购买后得到的 CDKEY

其他ChatGPT Pro 100刀、200刀、Claude Pro、Grok Super等会员充值也可参考此文档

第一步：选择适合自己账号的 Plus 商品

打开 AI MEMBER 发卡网，在「ChatGPT」分类里选择支持卡密自助提交的 Plus 商品。本文截图使用的是其中的 GPT Plus 官方ios充值商品。

下单前先把商品说明看完，尤其要确认自己的账号状态是否符合要求。

第二步：填写订单信息并付款

在商品页填写常用联系方式，再设置一个订单查询密码。这个密码只用于查询订单，不是 ChatGPT 密码，建议单独设置并自己记好。随后填写验证码，选择页面当前可用的支付方式，按提示完成付款。

AI MEMBER Plus 商品下单信息示例

付款完成后先别急着关闭页面，保存好订单号，并复制订单中自动发放的 CDKEY。如果暂时没有看到卡密，可以打开订单查询，使用订单号或下单时填写的联系方式查询。

第三步：进入充值中心并验证卡密

打开 AI MEMBER 充值中心，确认页面顶部选中的是「GPT」和「中文」。把刚才得到的 CDKEY 粘贴到输入框，点击「验证卡密」。

AI MEMBER ChatGPT Plus 充值中心

验证通过后，页面会进入 Session 提交步骤。如果提示卡密不可用、商品不匹配或当前状态不能提交，先核对订单和商品类型，不要反复提交。

第四步：在同一个浏览器中获取 Session

这里最容易出错的地方，是拿错了登录账号。请在当前浏览器中点击「打开 ChatGPT 官网」，确认登录的就是准备充值的账号；然后返回充值页，点击「打开 Session 页面」。

官方 Session 页面地址是：

https://chatgpt.com/api/auth/session

页面打开后会显示一段 JSON 内容。使用 Ctrl + A 全选、Ctrl + C 复制，内容不要删减，也不要手动修改。

ChatGPT 官网登录与 Session 获取步骤

::: warning Session 要当作密码保护

Session 中包含临时登录凭证。只在地址栏确认是 https://recharge.ai-member.icu/ 时粘贴，不要把 Session 发到群聊、客服私聊或公开截图里。如果 Session 页面没有显示当前账号信息，先重新登录 ChatGPT，再打开一次。

:::

第五步：返回充值页并提交

回到充值中心，把刚才复制的完整内容粘贴到 Session 输入框。页面如果弹出账号邮箱确认，请认真核对，确定是要充值的账号后再提交。

点击「提交充值」后保持页面打开，不要重复点击。处理完成后，当前页面会显示商品、账号、完成时间和处理状态。

第六步：确认 Plus 是否到账

重新打开 ChatGPT，在账号设置中查看当前套餐是否已经变为 Plus。若充值页显示成功，但 ChatGPT 暂时没有更新，可以先重新登录 ChatGPT。

常见问题

Q：订阅后 Codex 额度够用吗？

Plus 按 token 计费（2026 年 4 月起），日常开发任务普通使用量通常可以撑一整个月。如果额度用完，可以单独购买额外额度，也可以等下月重置。

Q：Plus 和 Pro 区别大吗？

Pro 的 Codex 使用额度是 Plus 的 5 倍，适合重度用户或需要大量并行任务的场景。普通开发者先从 Plus 开始，不够用再升级。

Q：可以用现有手机而不买二手设备吗？

可以。如果你的设备能正常使用海外区 Apple ID，不需要专门买二手。建议不要在自己常用的国内账号设备上频繁切换 ID，长期使用建议准备一台专用设备。

订阅后验证

下一步

下一步：连接第三方 API。

app overview

description: "Codex 桌面 App 基本组成说明，介绍项目工作区、对话、设置入口、任务状态和常见界面区域，方便快速定位功能。"

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

了解 Codex 基本组成

认识对话和项目

打开 Codex，左侧栏就两个入口：Chat（对话） 和 Project（项目）。

Codex 桌面 App 主界面

Chat 对话

和 ChatGPT 网页版差不多，随手问问题。各对话互不相干，也不共享文件夹。

Project 项目

需要动本地文件时用它——写代码、改文档、做 PPT 都可以。项目里的所有对话共用同一个文件夹，方便一起管理。

Project 工作区界面

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

对话框功能说明

Codex 的对话框和 ChatGPT 网页版类似，支持：

添加上下文：可以附加文件、截图或其他参考内容
切换模型：在不同模型之间切换

并额外支持：

控制权限：设定 Codex 在当前任务中的操作权限
选择工作目录：指定 Codex 在哪个本地文件夹下执行任务

对话框功能区

插件与技能

包括 OpenAI 官方定制或推荐的插件与技能。

Codex 插件与技能

Skills 默认包含 Skills Creator、Skills Installer、OpenAI Docs 等技能，用来创建、安装技能，或获取 OpenAI 官方最新文档。在对话框中使用 $ 即可调用 Skills：

Codex Skills 调用

插件是 OpenAI 定义的外部工具入口，也可能包含 Skills、MCP、脚本等能力。常见插件包括 Computer Use、Browser Use、PPT、Docs、Excel、Slack、GitHub 等。不同插件可能有额外配置。

Codex 插件配置

自动化

Codex 支持自动化执行任务，包括使用 MCP 服务器、钩子和插件等。

Codex 自动化总览

自动化会执行你指定的命令，你可以指定工作树、项目地址和定时的间隔。在下图中输入你的指令，并且配置即可。

Codex 创建自动化

::: tip 注意自动化任务以默认沙盒设置运行。若工具调用需修改工作空间外文件、访问网络或操作电脑应用，该操作将执行失败。可通过规则选择性允许特定命令在沙盒外运行。 :::

设置面板

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

设置面板详情

左侧是设置菜单。里面包含丰富的配置选项，详情如下：

::: warning 先用默认配置截图里的开关只是示例。尤其是「完全访问权限」、浏览器控制、电脑操控、钩子和 MCP 服务器，先按任务逐步开启。配置选项可参考如下。 :::

设置说明

大部分情况下都是保持默认配置即可。配置很多时候都是按需开启。

个人

常规

工作模式：编程模式保留更多技术细节；日常工作模式更适合问答、整理和写作。
权限：提供三个权限选项。
- 默认权限：在沙盒环境中运行，安全但部分操作可能受限，例如访问工作目录外的文件、修改本机环境变量。
- 自动审核：也称“替我审批”，部分越权命令可以在模型审核认定安全后自动使用，无须用户授权。
- 完全访问权限：只在明确需要时临时开启，例如启用 computer use。
常规：可配置：文件打开位置、集成终端 Shell、Codex UI 的语言、底部面板、速度（指模型生成的速度）、代码审查、建议提示、从其他AI应用中导入工作内容，打开源许可证。
通常而言，模型生成速度默认标准即可。仅在Pro 5x及以上的套餐才会推荐启用快速模式（消耗更多配额）。
编辑器：可配置：上下文窗口使用情况、跟进行为、需按 ^ + 回车键发送长文本提示。
弹出窗口：可配置：弹出窗口快捷键、默认使用无项目聊天。
听写：可配置：按住听写快捷键、切换听写快捷键、保持听写栏可见、听写词典、最近的听写记录。
通知：可配置：轮次完成通知、权限通知、问题通知。。

个人资料

查看账号资料、Token 活动

资料：头像、名称、用户名。
用量：活动、token、任务记录等个人统计。

外观

调整 UI 和配色方案。可配置：主题导入、主题复制、强调色、背景、前景、UI 字体、代码字体、半透明侧边栏、对比度、指针光标、动态效果、字号、差异标记、宠物外观。

配置

管理 agent 的执行边界和config.toml的配置

自定义 config.toml 设置：Codex 的核心配置文件。详情见：config.toml 参考
工作空间依赖项：可配置 Codex 安装随附的Node.js和Python、进行诊断和重置并安装工作空间。

个性化

选择 Codex 的性格，配置自定义指令和记忆。

键盘快捷键

查看、搜索和重设快捷键。

使用情况和计费

查看额度和套餐状态。

集成

MCP 服务器

给 Codex 接入外部工具和上下文，比如文档、浏览器、设计工具或内部系统。

浏览器

让 Codex 打开网页、点击、输入、截图和检查页面状态。需要在插件处下载。可配置：清除浏览数据、批注截图、打开网站前审批、网站权限。

电脑操控

让 Codex 看屏幕、点应用、输入内容。Codex会读取本机上已经安装的APP，然后通过视觉识别和脚本发起键鼠操作。需要在插件处下载。

编码

钩子

在 Codex 的生命周期事件中运行自定义脚本。可用于日志、提示检查、记忆整理、验证检查和按目录调整提示。详情见：Hooks。

连接

管理设备远程连接。可通过手机/SSH的方式远程连接Codex。

Git

让 Codex 按你的偏好处理 Git。可配置：分支前缀、PR 合并方法、侧边栏 PR 图标、强制推送、草稿 PR、旧工作树自动清理、保留数量、提交信息和 PR 标题/描述生成指令。

环境

指定一个项目目录，告诉 Codex 这个项目该怎么构建和运行。可配置：设置脚本，清理脚本，自定义操作。例如安装依赖、构建项目、启动开发服务器和运行测试。

工作树

让 Codex 为不同任务准备独立的工作区。适合同时修不同问题、比较不同方案，或把长任务放到一边继续做别的事。使用前先确认当前改动已经保存或提交。

已归档

已归档对话

收起不再活跃的对话。可恢复。

::: tip 注意设置页里的名称会随着客户端迭代变化。遇到和教程截图不一致时，先看 OpenAI 官方的 Codex App docs，再回到本教程查中文场景解释。 :::

下一步

下一步：用 Codex 完成第一个任务。

first task

description: "用 Codex 完成第一个任务的入门教程，带你选择工作目录、输入任务、查看结果并完成基础验证，形成操作习惯。"

::: tip 最后核对官方资料最后核对日期：2026-06-29。本章以桌面 App 第一个任务为例，Codex App 的项目、工作区、权限和任务执行入口请以 Codex App docs、Settings 与 Agent approvals & security 为准。 :::

用 Codex 完成第一个任务

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

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

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

::: warning 文件夹路径中尽量不要包含中文，避免部分工具出现兼容性问题。 :::

新建本地文件夹

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

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

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

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

第三步：添加工作目录

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

选择工作目录

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

确认工作目录

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

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

输入任务并发送

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

任务完成

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

内置浏览器预览

第五步：逐步迭代

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

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

上下文使用情况

::: info 什么是上下文窗口？每次对话都有容量上限，每一轮问答都会占用一定空间。当上下文接近满载时，建议在项目中新建一个对话继续处理后续任务——新对话仍然共享同一工作目录，不需要重新配置。 :::

项目中新建对话

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

下一步

下一步：任务设计。

cli installation

description: "Codex CLI 安装与登录教程，覆盖 Node 环境、安装命令、版本检查、登录流程和首次运行准备。"

::: tip 最后核对官方资料最后核对日期：2026-05-27。CLI 系统要求与安装方式参考 openai/codex 官方仓库、CLI install 文档和 Codex CLI Help Center。 :::

安装CLI

本页先覆盖 Codex CLI 的安装与登录。桌面端、ChatGPT、Cloud 和 IDE 入口会在入口地图中分别展开。

安装前检查

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

项目	建议
操作系统	macOS 12+、Ubuntu 20.04+/Debian 10+、Windows 11 通过 WSL2
Git	推荐 2.23+，便于 PR 辅助能力
内存	4GB 起步，8GB 更稳

本地先确认：

node -v
npm -v
git --version

codex-cli-prerequisite-version-check

安装 CLI

常见安装方式：

npm install -g @openai/codex

更新到最新版本：

npm install -g @openai/codex@latest

检查版本：

codex --version

codex-cli-version-check

登录方式

运行：

codex

根据终端提示完成登录。官方资料说明 Codex 可以通过 ChatGPT 账号在多个入口中使用，具体可用计划、限额和组织策略以 Codex in ChatGPT Help Center 为准。

codex-cli-login-account-selection

第一次只读任务

进入一个本地项目根目录：

cd path/to/your/project
codex

先让 Codex 只读仓库：

请先阅读这个仓库的目录结构、README、包管理器配置和测试配置。不要修改文件。请总结：
1. 项目用途
2. 主要技术栈
3. 如何安装依赖和运行测试
4. 你建议我下一步交给你的 3 个低风险任务

codex-cli-readonly-first-task

安装失败时怎么判断

现象	可能原因	处理方式
`codex` 命令找不到	npm global bin 未进 PATH	查看 `npm bin -g`，把目录加入 shell PATH
登录后仍提示无权限	账号计划、组织策略或会话状态问题	重新登录，并查看 Help Center 中的计划说明
Windows 运行异常	未使用 WSL2 或 shell 环境不完整	按官方建议使用 Windows 11 + WSL2
仓库命令跑不起来	项目依赖未安装或本地环境缺失	先安装项目依赖，再让 Codex 读取测试配置

下一步

下一步：第一次让 Codex 改代码。

cli first run

description: "第一次让 Codex CLI 改代码的教程，说明如何选择低风险任务、让 Codex 读仓库、修改文件并运行验证。"

::: tip 最后核对官方资料最后核对日期：2026-05-27。本文参考 Codex CLI features、openai/codex getting started、AGENTS.md guide 与 Codex security。 :::

运行 CLI

第一次实战不要选择“重构整个项目”。选择一个小、可验证、失败也容易回滚的任务，先建立你和 Codex 的协作节奏。

选择第一个任务

适合新手：

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

暂时避开：

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

第一步：只读建图

先让 Codex 理解仓库：

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

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

codex-cli-repo-overview-response

第二步：给出小任务

推荐复制这个模板：

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

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

如果任务是文档：

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

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

codex-cli-small-task-response

第三步：观察过程

重点观察五件事：

观察点	说明
是否先读上下文	好结果通常来自充分阅读相关文件
是否控制范围	第一次任务不追求顺手重构
是否解释命令	命令执行前应说明目的
是否运行验证	修改完成后要跑相关测试或构建
是否说明风险	没能验证的部分要如实记录

第四步：检查 diff

完成后自己再看一遍：

git diff

可以让 Codex 自查：

请 review 你刚才的改动，不要继续修改文件。

请重点检查：
1. 是否有无关改动
2. 是否遗漏测试
3. 是否引入安全或兼容风险
4. 是否还有未验证的地方

codex-cli-review-diff-result

第五步：提交前记录

提交前让 Codex 给出一段摘要：

请用提交前摘要格式输出：
- 改动目标
- 修改文件
- 验证命令
- 验证结果
- 剩余风险
- 建议 commit message

如果结果满意，再提交：

git add .
git commit -m "fix: resolve failing test"

第一次失败怎么办

失败现象	处理方式
改动太大	让 Codex 停下，只保留最小修复思路
测试跑不起来	先让它解释环境缺口和命令来源
方向不对	回到只读分析，让它列出文件依据
输出太泛	要求按文件、命令、风险分段输出
误改无关文件	用 git diff 确认，再手动决定保留或丢弃

完成标准

第一次实战完成后，你应该拿到：

一个很小的 diff。
一条可复现的验证命令。
一段清楚的改动摘要。
一个可复用的任务模板。
对 Codex 权限和审批的初步理解。

下一步

下一步：CLI 选项与命令。

agents md

description: "AGENTS.md 项目规则指南，说明如何写入项目命令、代码风格、禁用事项、验证方式、团队约定和本地私有规则，让 Codex 更快理解项目。"

::: tip 最后核对官方资料最后核对日期：2026-06-19。AGENTS.md 机制请以 Codex AGENTS.md 官方文档、AGENTS.md 标准网站和 openai/codex GitHub repository 为准。 :::

AGENTS.md

对于 Codex，每开启一个新的对话窗口，它都会进入一个全新的上下文。它不知道这个项目用什么命令、有哪些目录边界、哪些文件不能改，也不知道团队平时怎么验证结果。

AGENTS.md 正是为了解决这类问题而存在的项目级指令文件。它是一个简单、开放的 Markdown 约定，目标是给不同 coding agent 提供一个稳定、可预测的项目指令入口，把项目结构、开发命令、测试要求、代码风格和协作边界显式写下来，减少反复解释。

更准确地说，AGENTS.md 是面向 coding agent 的 README。README 主要给人看，讲项目是什么、怎么上手；AGENTS.md 给 Codex 和其他 coding agent 看，告诉它们改代码前应该遵守哪些项目规则。

可以把它理解为：

对个人用户：减少重复解释“项目怎么跑、怎么测、哪些地方不能碰”。
对团队项目：把团队共同认可的 agent 使用规则沉淀到仓库里。
对多工具环境：让 Codex、IDE agent、CLI agent 等工具尽量读取同一份项目说明。

本质上就是一份普通的 Markdown 文件。

另外需要注意，截至目前，Claude Code 并不遵守 AGENTS.md 约定，取而代之的是 CLAUDE.md 约定。

存放位置与读取机制

文件位置

对于普通项目，最推荐的做法是在项目根目录创建 AGENTS.md。Codex 在开始处理任务前会自动读取它，并把内容作为工作上下文带入新的对话。

agents-md-editor-rule-example

若希望全局生效，可以撰写 Codex 的全局指令：

在 Codex_Home 目录中创建 AGENTS.md。默认位置通常是 ~/.codex/AGENTS.md；如果设置了 CODEX_HOME，则以对应目录为准。
在 Codex 桌面 App 里配置个人偏好或自定义指令。本质上也是写入 Codex_Home 的 AGENTS.md，与上述方法等价。

设置全局规则后，它会影响你打开的所有项目；项目级 AGENTS.md 只影响当前仓库。两者作用域不同，要分清。

codex-app-personalization-settings

请确保文件名始终为 AGENTS.md，并确认大小写是否正确。否则 Codex 不会自动识别。

读取顺序与合并规则

Codex 读取 AGENTS.md 遵循以下顺序：

先读取全局规则：默认读取 ~/.codex/AGENTS.md。如果同一位置存在 AGENTS.override.md，则优先读取它，适合临时覆盖全局规则。
然后读取项目规则：进入项目后，Codex 通常会从 Git 根目录开始，一路走到当前工作目录。沿途每一层目录，它会尝试读取项目指令文件。

项目指令文件的默认优先级是：

AGENTS.override.md
AGENTS.md

也就是说，同一目录里如果同时存在这两个文件，AGENTS.override.md 会覆盖 AGENTS.md。

Codex 会把读取到的指令从上到下合并。根目录的规则先出现，子目录的规则后出现。越靠近当前目录的规则越具体，因此也更适合写局部要求。

一个文件结构的示例：

AGENTS.md
apps/
  web/
    AGENTS.md
packages/
  database/
    AGENTS.md

上述示例中，根目录 AGENTS.md 写全仓库通用规则，apps/web/AGENTS.md 写前端规则，packages/database/AGENTS.md 写数据库迁移和测试要求。

注意事项：

如果你的项目已经有其他规则文件，可以通过 Codex 配置里的 project_doc_fallback_filenames 添加备用文件名。Codex 会在找不到 AGENTS.override.md 和 AGENTS.md 时，再尝试这些 fallback 文件。
Codex 还会限制合并后的项目指令大小。官方默认值是 project_doc_max_bytes = 32768，也就是 32 KiB。规则文件太大时，后面的内容可能不会进入上下文，所以尽量保持 AGENTS.md 精简。

团队协作

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

使用场景

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

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

文件分工

文件	作用	是否提交到 Git
`AGENTS.md`	团队共享的项目规则、命令、边界和交付要求	可以提交
`AGENTS.override.md`	Codex 官方识别的覆盖文件，适合临时覆盖同目录规则	通常不提交，除非团队明确约定
`AGENTS.local.md`	个人本地偏好、私有路径和临时规则	应加入 ignore

需要注意：AGENTS.local.md 不是 Codex 默认识别的标准文件名。如果你想让 Codex 读取它，需要借助 hooks、社区工具（见下方推荐），或在配置中把它加入 fallback 文件名。

无论是否使用本地规则，都应遵守：

不把 token、密钥、账号密码写进 AGENTS.local.md。
把 AGENTS.local.md 和 AGENTS.override.md 加入全局 gitignore 或项目 .gitignore。
不在本地规则里绕过团队的测试、审批和安全要求。
每次引入 hooks 工具前，先确认它是否会替换命令、执行仓库文件、访问网络或写入敏感目录。

社区工具推荐

社区工具 codex-agents-local 提供了 AGENTS.local.md 的本地覆盖方案。它通过 Codex hooks 在会话开始或提交提示词时同步本地规则。

安装前建议先让 Codex 审查安装提示词，再决定是否执行：

Read https://github.com/samzong/codex-agents-local/blob/main/INSTALL_PROMPT.md

Follow that prompt in Codex to install codex-agents-local.

::: warning 社区工具提示 codex-agents-local 不是 Codex 官方功能。安装前请检查脚本会改哪些文件、会启用哪些 hooks、是否符合你的团队安全要求。 :::

安装或修改本地规则后，可以用这些命令检查状态：

codex-agents-local doctor
codex-agents-local sync --cwd . --check
codex-agents-local sync --cwd . --json

如果还没有安装社区工具，可以先检查 ignore 状态：

git check-ignore -v AGENTS.local.md AGENTS.override.md

参考模板

# AGENTS.md

## 项目概览

- 项目类型：
- 主要语言：
- 关键目录：
- 不要修改的目录：

## 常用命令

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

## 代码规范

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

## 安全边界

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

## 交付要求

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

最佳实践

多利用市面上已有的、经过无数开发者验证的成熟辅助工具。比如写“运行测试：pnpm test”比写“记得自己检查一遍代码是否有问题”有用。
确保没有跟其他规范文档的指令产生冲突。
勤于更新。随着项目逐渐推进，里面的命令也需要与时俱进。
AGENTS.md 可以承担导航的作用。可以告诉 Codex 项目文档的阅读目录清单，而不是把文档写进 AGENTS.md里。

下一步

下一步：Skills 和 Plugins。

sandbox approvals

description: "Codex 沙盒与审批指南：面向新手解释为什么 Codex 有时会停下来问你，以及如何设置合适的权限。"

::: tip 最后核对官方资料最后核对日期：2026-06-18。本文依据 Codex Sandboxing、Agent approvals & security、Permissions、Rules、Windows 和 Auto-review 整理。 :::

沙盒与审批

Codex 能读取代码、修改文件、执行命令。这些操作需要受控边界：哪些目录可写、哪些命令可执行、什么情况下必须暂停并请求确认。

沙盒和审批就是这套边界。

对于绝大多数人而言，只需要把 Auto-Reivew 模式打开就够了。本文章旨在让你更好地理解 Codex 的沙盒机制和审批策略，同时补充一些进阶用法。

当你在利用沙盒和权限机制来约束 Codex 行为的时候，你已经在实践 Harness Engineering ，即“约束工程” 。

Codex 沙盒、审批策略、审批人与配置项关系图

三个概念

想象 Codex 在你的电脑里工作，就像在一个有玻璃墙和门禁的实验室里操作。

沙盒就是实验室的墙和门禁：它规定 Codex 能碰哪些设备、能不能连外网、能不能写入项目外文件夹。墙内的常规操作，Codex 可以自己做；墙外的事情，需要先获得许可。
审批策略就是门禁的触发规则：是「沙盒外区域每次请求确认」，还是「只在 Codex 越过沙盒边界时请求确认」，还是「完全不请求，自行处理」。
审批人就是谁来回答门禁：你自己看门放行，还是让另一个智能门禁系统（Auto-review）先判断一下。

三者加在一起，决定 Codex 在你的电脑上到底能做什么、不能做什么。

默认推荐

Codex 启动时会根据目录状态自动推荐权限：

版本控制目录（带有.git文件夹）：Auto，也就是 workspace-write + on-request。
非版本控制目录（不带有.git文件夹）：read-only。
某些情况下，Codex 会先保持 read-only，直到你明确信任当前工作目录。

日常开发最常用的是

沙盒设置：workspace write（工作区写入）
批准机制：on-request（按请求）

旧版写法（仍可用）：

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

新版 permission profiles 写法（beta）：

default_permissions = ":workspace"
approval_policy = "on-request"
approvals_reviewer = "user"

新旧配置不要混用。 这些配置通常写在 ~/.codex/config.toml。如果任意已加载配置里出现 sandbox_mode，或命令行传了 --sandbox，Codex 会使用旧版 sandbox 设置，而不是 default_permissions。

这段话什么意思？用上面的类比解释：

Codex 可以在当前项目文件夹（workspace）里正常操作：读取文件、修改文件、运行常规的本地命令（比如 git、测试脚本、编译）。
如果需要联网、写到项目外面、或者做越界的事情，就会触发审批，暂停并请求确认。

这是官方推荐的默认设置。它不会每一步都要求交互确认，也不会让 Codex 获取整台电脑的权限。

沙盒模式

三种沙盒模式，对应不同的权限边界：

模式	对应英文	范围	审批触发条件
只读	`read-only` / `:read-only`	主要用于读文件和回答问题；命令执行也受只读边界限制	修改文件、执行需要写入的命令或联网时触发审批
工作区写入	`workspace-write` / `:workspace`	可以在项目里读、写、运行常规命令	联网或写到项目外时触发审批
完全访问	`danger-full-access` / `:danger-full-access`	没有沙盒限制，可以访问任何位置	取决于审批策略

Codex 配置中的沙盒设置选项

日常默认用工作区。 它为 Codex 提供足够的操作空间完成普通开发任务，同时守住项目边界。

不要轻易使用完全访问。 它等于拆掉了所有沙盒限制，Codex 可以写入系统文件、访问任意网络。如果正在做删除数据、部署到生产环境或批量修改文件之类的操作，用完全访问会把风险放大。CLI 里的 --dangerously-bypass-approvals-and-sandbox（别名 --yolo）就是这个模式。

另外，即使在「工作区」模式下，下面这些路径也会被只读保护：

.git 目录（你的版本控制数据）
.agents 目录（你的 agents 配置）
.codex 目录（Codex 自身的配置）

这些路径在默认 workspace-write 策略下是只读保护区。Codex 可以读取它们，但不能直接写入里面的内容。

审批策略

沙盒规定了边界，审批策略决定什么时候 Codex 必须暂停并请求确认。

策略	触发条件	说明
`untrusted`（不可信）	命令不属于已知安全的读取操作	只自动执行已知安全的读操作；可能修改状态、触发外部执行路径或危险 Git 操作的命令都需要确认
`on-failure`（失败时）	命令执行失败时	先在当前权限下尝试执行；失败后再请求确认。这个选项在部分 App 配置界面中可见，但不是当前官方文档的默认推荐
`on-request`（按请求）	操作越过沙盒边界	默认推荐。沙盒内自动执行，越界时请求确认
`never`（从不）	不触发	Codex 在既有权限内自行处理，不弹出审批

Codex 配置中的审批策略选项

on-request（按请求）是新手最友好的选择。 沙盒内自动执行，越界时暂停并请求确认。不需要审批每一个文件修改，只需要在关键时刻把关。

never 不是「自动变安全」。 它只是不请求确认。安全取决于沙盒边界是否足够窄。比如 read-only + never 是安全的，因为 Codex 本来就不能改东西；但 danger-full-access + never 是官方标注的高风险组合——没有沙盒限制，也没人确认。

Auto-review

如果一个命令需要越过沙盒，那么 Codex 就会发起请求。请求除了用户来批准以外，也可以使用 Auto-review 模式自动批准。

Auto-review 相当于：当 Codex 越过沙盒边界时，不是直接呈现给你，而是先交给 reviewer agent 判断。常见的有：

写入项目外目录
联网请求
请求更多权限
执行带副作用的 app 或 MCP 工具调用

沙盒内允许的操作，不会经过 Auto-review。 所以它不会改变日常操作的沙盒边界。

Auto-review 不会扩大沙盒边界。它不会扩展 Codex 的 workspace，不会自动给它网络权限，也不会让危险命令绕过沙盒。如果 reviewer agent 判断请求有风险，它会拒绝，Codex 需要选择更安全的替代方案，或者请求确认。

底层配置：

approval_policy = "on-request"
approvals_reviewer = "auto_review"

approval_policy 决定什么时候产生审批请求。on-request 表示沙盒内操作继续执行，越过沙盒边界时才请求审批。
approvals_reviewer 决定审批请求交给谁。默认是 "user"，即直接呈现给用户；改成 "auto_review" 后，符合条件的审批请求会先交给 reviewer agent。

这两个字段要一起理解。只写 approvals_reviewer = "auto_review" 不会让 Codex 主动产生更多审批请求；它只是改变已有审批请求的处理人。也就是说，Auto-review 的前提仍然是 approval_policy 处在会产生交互审批的模式，比如 "on-request" 或 granular。

如果你想保留沙盒边界，同时减少手动确认操作，可以这样写：

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "auto_review"

如果你已经改用新版 permission profiles，也可以这样写：

default_permissions = ":workspace"
approval_policy = "on-request"
approvals_reviewer = "auto_review"

网络权限

联网能解决问题，也能引入风险。Codex 需要联网时，通常是为了：

安装依赖（npm install、pip install）
查询信息
调用 GitHub API
测试时访问本地服务器

但联网也会带来风险：

提示词注入：恶意网页可能让 Codex 执行不该执行的命令
数据外发：你的代码、密钥、.env 文件可能意外泄露
供应链风险：安装的依赖本身可能不安全

所以：

如非必要，不要给网络权限。 如果只是修改本地文档，完全不需要联网。
搜索资料时，优先用 Codex 内置的受控 web search，而不是让 Codex 直接访问任意网页。
需要联网时，让 Codex 说明目标域名和用途，并且确认是访问可信任的网站。
永远不要把 .env、token、cookie、私钥交给会联网的命令。

进阶配置

如果你发现 Codex 经常因为沙盒边界过窄而频繁触发审批，推荐使用 Auto-review ，让 Codex 帮你审批，从而减少手动确认次数。

如果对项目安全边界要求很高，或者是处理一些敏感的操作，那么也有一些进阶配置可选：

1. 扩展 workspace（最推荐）

如果 Codex 需要同时修改两个项目目录，比如 ~/project-a 和 ~/project-b，你可以把第二个目录也加入可写范围。这是扩展 workspace，不是拆掉沙盒边界。

旧版写法：在 config.toml 的 sandbox_workspace_write.writable_roots 里添加。新版写法：在 permissions.<name>.workspace_roots 里添加。

旧版 sandbox 写法适合还在使用 sandbox_mode 的配置：

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
writable_roots = ["~/project-a", "~/project-b"]
network_access = false

新版 permission profiles 写法适合把文件系统和网络边界放在同一个 profile 里。这里的 my-docs-workspace 是自定义 profile 名称，可根据需要命名。

default_permissions = "my-docs-workspace"
approval_policy = "on-request"

[permissions.my-docs-workspace]
extends = ":workspace"

[permissions.my-docs-workspace.workspace_roots]
"~/project-a" = true
"~/project-b" = true

[permissions.my-docs-workspace.filesystem.":workspace_roots"]
"." = "write"
"**/*.env" = "deny"

[permissions.my-docs-workspace.network]
enabled = false

这两个写法二选一。只要已加载配置里出现 sandbox_mode，Codex 就会走旧版 sandbox 设置，而不是 default_permissions。

2. 为常用越界命令设置规则（rules）

Rules 控制的是 Codex 需要在沙盒外运行命令时怎么处理。你可以在 .rules 文件里写 prefix_rule，把某类命令设为 allow、prompt 或 forbidden。规则里可以写 match 和 not_match 做验证，减少误匹配。

3. 自定义 permission profiles（beta）

如果你需要更细的控制——比如「能写代码，但只能访问 GitHub 和 npm，不能访问别的网站」——可以定义一个自定义 profile。也就是上文提及的default_permissions写法。

default_permissions = "workspace-net"
approval_policy = "on-request"

[permissions.workspace-net]
extends = ":workspace"

[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"
"**/*.env" = "deny"

[permissions.workspace-net.network]
enabled = true

[permissions.workspace-net.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"
"*.npmjs.org" = "allow"

网络权限一旦开启，最好配合域名规则。"*" 也可以放行公共网络，但它的范围很大，不适合当默认示例。

4. 细粒度审批策略（granular，需手动配置）

如果你只想对特定类型的审批请求分别控制，而不是全部越过沙盒边界的操作都请求确认，可以用 granular 策略。它不在 UI 下拉菜单里，需要手动在 config.toml 里写：

approval_policy = { granular = {
  sandbox_approval = true,   # 沙盒越界时问
  rules = true,              # rules 触发时问
  mcp_elicitations = true,   # MCP elicitation 请求时问
  request_permissions = false,  # 权限请求自动拒绝
  skill_approval = false     # skill 脚本审批自动拒绝
} }

这里的 true 表示该类请求保持交互审批；false 表示自动拒绝。它是 on-request 的进阶替代，不是 UI 选项。

更多详情请阅读：Agent approvals & security：granular approval policy。

平台差异

不同系统的沙盒实现不同，但对你来说，用法是一样的：

macOS：使用系统自带的 Seatbelt 机制，无需额外配置。
Windows：原生 Windows 有两个版本。elevated 更强，使用独立低权限用户和防火墙；unelevated 是回退，使用当前用户的受限令牌。有些公司电脑的策略限制可能只能用 unelevated。IDE 里可以设置让 Codex 运行在 WSL2 里，这样用的是 Linux 的沙盒机制。
Linux / WSL2：需要安装 bubblewrap。如果缺少它，Codex 可能会弹出警告或性能下降。WSL1 从 Codex 0.115 起不再支持。

遇到报错时，记住两点：先检查 Codex 的权限模式设置，再查询对应平台的文档。无需记忆实现细节。

高风险判断

以下情况，建议让 Codex 先说明计划，再决定是否放行：

删除文件、批量移动文件、清理目录
数据库迁移、修改生产数据
修改认证、权限、支付、账单相关代码
访问生产服务器或外部 API
处理密钥、token、cookie、私有凭据
大规模安装或升级依赖
执行部署、发布、推送 release

判断标准：

有没有不可逆的副作用？（删除后无法恢复）
会不会涉及敏感数据？（密钥、用户数据）
会不会影响项目外面？（生产环境、别的系统）

如果你不确定，可以在任务开头贴这段提示词，让 Codex 更谨慎：

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

这段话不能代替沙盒，但能让 Codex 更早说明计划，减少误操作。

团队建议

统一配置标准。团队内统一审批策略和沙盒模式。有人用 never + danger-full-access，有人用 on-request + workspace-write，发生问题时难以排查。把推荐的配置通知给团队成员，按统一标准执行。
配置进版本控制。.rules、AGENTS.md 和项目级 config.toml 文件纳入版本控制，克隆仓库后权限一致。
敏感数据隔离。生产密钥不放在普通开发环境。用 profile 里的 deny 规则把 **/*.env 和 ~/.ssh 标记为禁区，比依赖人记忆更可靠。
高风险操作强制审批。对删除、部署、数据迁移等操作，用 granular 或 rules 强制走审批流程。
Codex 的改动仍然要 review。沙盒和审批负责边界控制，不负责代码质量。代码改动仍然走正常的 PR 流程。

下一步

下一步：自动线程管理。

team playbook

description: "Codex 团队实践指南，整理 AGENTS.md、PR、排障、知识库、任务模板和团队推广的协作方法。"

::: tip 最后核对官方资料最后核对日期：2026-06-29。本文参考 Codex AGENTS.md 官方文档、Permissions、Agent approvals & security 与 Codex App Worktrees。团队制度、审批边界和共享规则请结合本组织实际情况确认。 :::

团队实践

团队使用 Codex 的关键是把规则写清楚、把验证跑起来、把案例沉淀下来。

Codex 安全边界分层

团队接入清单

项目	建议
`AGENTS.md`	写清项目结构、命令、风格、安全边界
测试命令	提供最小相关测试和全量测试命令
PR 模板	要求说明 Codex 参与范围、验证结果和风险
安全规则	明确生产数据、密钥、发布、迁移的审批要求
案例库	把成功任务和失败复盘都沉淀下来

团队版 AGENTS.md 提纲

# AGENTS.md

## 项目概览

## 常用命令

## 目录边界

## 代码规范

## 测试要求

## 安全边界

## PR 交付要求

共享规则与个人偏好

团队的共同规则建议放进 AGENTS.md，例如项目结构、命令、测试要求、目录边界和安全红线。个人本机路径、私有工具习惯、临时限制和回复偏好，可以参考团队共享规则和本地私有规则拆到 AGENTS.local.md。

如果团队允许使用社区工具，可以评估 codex-agents-local。使用前先确认 AGENTS.local.md 和 AGENTS.override.md 已加入 ignore，并让 Codex 审查安装步骤对 ~/.local/bin 与 ~/.codex/hooks.json 的影响。

PR 描述模板

## 背景

## 改动

## Codex 参与范围

## 验证

## 风险

## 截图或日志

例会复盘问题

哪类任务 Codex 表现稳定？
哪类任务容易失控或需要更强约束？
哪些命令、规则、截图说明应该写入 AGENTS.md？
哪些成功案例可以沉淀成模板？
哪些失败案例应该写入排障手册？

::: info 截图占位请补充团队 PR 中 Codex 参与说明的截图。建议文件：docs/.vuepress/public/screenshots/cloud/03-pr-codex-summary.png。 :::

下一步

下一步：排障手册。

index

description: "Codex 参考手册，汇总 OpenAI 官方资料、Codex 更新记录、参考来源与致谢，帮助读者回到原始资料核对。" permalink: /manual/

::: tip 最后核对官方资料最后核对日期：2026-05-27。本文汇总 OpenAI Codex 官方资料、GitHub 仓库和关键事实来源；涉及价格、计划、模型、可用地区、功能开关和账号权限时，请优先打开原文确认。 :::

参考手册

本栏目整理 Codex 相关官方资料、更新记录和参考来源。涉及价格、计划、模型、可用地区、功能开关、账号权限等时间敏感信息时，请优先打开原文确认。

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

troubleshooting

description: "Codex 排障手册，汇总登录、安装、权限、依赖、命令失败和任务执行异常的定位与恢复路径，帮助快速继续工作。"

::: tip 最后核对官方资料最后核对日期：2026-06-29。本文参考 Codex 文档入口、Windows、Codex CLI 官方仓库与 Agent approvals & security。排障命令、路径和界面名称会随系统、客户端和 CLI 版本变化。 :::

排障手册

本页收集 Codex 使用中的常见问题。欢迎通过 PR 持续补充。

Codex 找不到项目上下文

可能原因：

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

处理方式：

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

Codex 改动范围太大

处理方式：

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

测试跑不起来

处理方式：

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

生成内容不准确

处理方式：

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

登录或权限问题

处理方式：

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

Desktop 一直显示 Reconnecting

Reconnecting 不是一个具体根因。它可能是主连接、会话恢复、WebSocket / SSE 流、代理协议、MCP worker 或服务端临时问题。不要一开始就重装 Codex、覆盖 config.toml，或者直接换账号。

::: tip 最后核对官方资料和 GitHub issue 最后核对日期：2026-06-14。本文参考 OpenAI Codex app troubleshooting、Environment variables、Use Codex with Amazon Bedrock、Model Context Protocol，以及社区排障库 Desktop Reconnecting / Proxy Triage。 :::

先按三层判断：

层级	现象	先做什么
主连接	新线程也一直 `Reconnecting`	验证 Codex 进程能不能走到正确代理
会话流	偶发 `stream disconnected before completion`	看是否是旧会话、WebSocket/SSE 或服务端连接问题
工具 worker	主界面恢复，但 MCP、Browser、node_repl 仍失败	再查 `config.toml` 里的 MCP 环境变量

如果你使用 macOS 代理：

scutil --proxy
launchctl getenv HTTP_PROXY
launchctl getenv HTTPS_PROXY
curl -sS --max-time 10 -x "http://127.0.0.1:<PORT>" "https://api.ipify.org?format=json"

端口和协议都验证通过后，再把最小代理变量放进 ~/.codex/.env，然后完全退出并重新打开 Codex Desktop：

export HTTP_PROXY="http://127.0.0.1:<PORT>"
export HTTPS_PROXY="http://127.0.0.1:<PORT>"
export ALL_PROXY="http://127.0.0.1:<PORT>"
export NO_PROXY="localhost,127.0.0.1,::1,*.local"

网上有 macOS 一键脚本会自动读取 scutil --proxy 并更新 ~/.codex/.env。可以把这类脚本当模板，但运行前至少确认它会备份原 .env、用 curl -x 验证代理协议、不会覆盖其他 secret，并且明确只适用于 macOS。

如果你使用 Windows 或 WSL：

Windows 原生 Desktop 优先检查 Windows 用户环境变量。
WSL 模式不要只写 ~/.bashrc，因为 Desktop 启动 WSL 进程时不一定经过 login shell。
修改环境变量后完全重启 Codex。

[Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://127.0.0.1:<PORT>", "User")
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:<PORT>", "User")

如果主界面已经恢复，但 MCP 或 node_repl 仍然断，再检查 MCP server 是否需要单独配置环境变量：

[mcp_servers.node_repl.env]
HTTP_PROXY = "http://127.0.0.1:<PORT>"
HTTPS_PROXY = "http://127.0.0.1:<PORT>"
NO_PROXY = "localhost,127.0.0.1,::1,*.local"

日志位置：

macOS app logs：~/Library/Logs/com.openai.codex/YYYY/MM/DD
会话记录：$CODEX_HOME/sessions，默认 ~/.codex/sessions

发 issue 或群里求助时，只贴脱敏后的错误字符串、时间点、Codex 版本、平台和网络拓扑。不要公开完整日志、邮箱、account id、conversation id、session id、真实出口 IP、本机路径、私有仓库名或 token。

Windows 桌面 App / CLI 专项排障

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

这个项目会把 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，不要把它当成官方认证或账号切换工具。

下一步

下一步：实战案例库。

index

description: "Codex 实战案例库，收录 PPT、Draw.io、Playwright、Obsidian、临床文献综述、Hatch Pet、安卓手机远程操控、飞书、Figma、Notion、CI 和远程排障案例。" permalink: /recipes/

::: tip 最后核对资料最后核对日期：2026-06-29。本页是实战案例索引，Codex 官方能力请以 Codex 文档入口、Codex Skills、Codex Plugins 与 Codex use cases 为准；第三方工具以各案例中的原仓库和官方页面为准。 :::

实战案例库

这里收集可复现、可改写、可迁移到真实工作流里的 Codex 使用案例。当前版本已收录 17 个案例，覆盖 Skill、MCP、浏览器自动化、知识库、临床文献综述、移动端协同、个性化工作台、设计稿、团队协作、远程排障和 CI 自动修复。

当前案例概览

类型	已收录案例	适合学习什么
内容生产与表达	PPT Skill、Draw.io MCP、HyperFrames	把一句话需求转成演示文稿、架构图和动画视频
知识库与个人工作台	Obsidian、LLM Wiki、Notion MCP	在笔记、Wiki、知识空间中组织资料和生成内容
医学科研与证据整理	临床文献综述	把研究问题拆成 PICO、证据表、局限性和安全边界
移动协同与个性化工作台	安卓手机远程操控、Hatch Pet、桌面宠物	在手机端跟进桌面任务，并用自定义宠物和桌面状态反馈优化工作台体验
浏览器与前端自动化	Playwright MCP、Chrome 浏览器插件	让 Codex 操作网页、检查页面、执行浏览器任务
设计与协作平台	Figma MCP、飞书 CLI	读取设计稿、处理飞书数据、连接团队工具
发布与工程运维	DKFile、云服务器远程修 Bug、GitHub Actions CI 修复	从本地/远程环境到自动修复流程的完整闭环

17 个案例清单

编号	案例	核心场景	推荐入口	验证重点
01	Codex × PPT Skill：一句话生成演示文稿	用 Skill 生成 PPT 初稿	桌面 App / Skills	结构、视觉一致性、导出效果
02	Codex × Draw.io MCP：AI 自动绘制架构图	通过 MCP 生成架构图	App / MCP	图形层级、节点关系、可编辑性
03	Codex × Playwright MCP：让 AI 操控浏览器	用 Playwright 驱动浏览器操作	App / MCP	点击路径、页面状态、截图结果
04	Codex × HyperFrames：用代码生成动画视频	生成可视化动画视频	App / CLI	动画脚本、渲染结果、素材路径
05	Codex × Obsidian：在知识库中自动生成配图	在本地笔记库中调用 Codex	CLI / Obsidian	文件路径、图片生成、笔记引用
06	Codex × 飞书 CLI：一句话处理飞书数据	处理飞书多维表格或协作数据	CLI	应用凭证、字段映射、写回权限
07	Codex × LLM Wiki：在 Obsidian 中搭建 AI 知识库	构建 AI 主题知识库	Obsidian / CLI	目录结构、引用来源、更新流程
08	Codex × Figma MCP：读懂设计稿	读取设计稿并辅助实现	MCP / IDE	设计 token、布局还原、组件边界
09	Codex × Notion MCP：打通知识空间	连接 Notion 做知识管理	MCP	数据库权限、页面结构、同步范围
10	Codex × DKFile：网页一键发布到公网	快速发布静态网页	CLI / API	构建产物、上传结果、访问地址
11	Codex × 云服务器：远程定位并修复 Bug	在远程容器里排查 Python 报错	CLI / Remote	连接方式、复现命令、修复验证
12	Codex × Chrome：让 AI 直接控制浏览器	通过浏览器插件执行网页任务	Browser Plugin	页面可见状态、动作确认、安全边界
13	Codex × GitHub Actions：CI 失败自动修复	CI 失败后自动触发 Codex 修复并开 PR	GitHub Actions	权限配置、失败提交、测试通过、PR 内容
14	Codex × 临床文献综述：把医学问题整理成可复核证据表	整理临床科研问题和文献证据	App / CLI / Obsidian	PICO、证据来源、局限性、医疗安全边界
15	Codex × Hatch Pet：用一张照片生成专属宠物	生成并安装自定义桌面宠物	桌面 App / Hatch Pet	素材质量、生成进度、宠物包路径
16	Codex × 安卓手机：扫码连接，远程操控	手机端配对并管理桌面任务	ChatGPT App / Desktop App	账号一致、网络、防火墙、连接状态
17	Codex × 桌面宠物：显示任务状态	用桌面宠物显示任务进度和完成状态	桌面 App	宠物唤醒、任务状态、提醒反馈

怎么选择先看哪个

如果你刚开始看实战案例，建议按目标选：

想快速看到效果：先看 PPT Skill、Draw.io MCP、DKFile。
想学习 MCP：先看 Playwright MCP、Figma MCP、Notion MCP。
想把 Codex 放进知识工作流：先看 Obsidian、LLM Wiki、飞书 CLI。
想做医学科研资料整理：先看临床文献综述，重点学习如何把事实、推断和安全边界分开。
想优化桌面工作台体验：先看 Hatch Pet 和桌面宠物，了解如何生成自定义宠物并查看任务状态。
想用手机跟进桌面任务：先看安卓手机远程操控，重点检查账号、网络和授权状态。
想做工程自动化：先看云服务器远程修 Bug、GitHub Actions CI 自动修复。
想理解浏览器控制能力：先看 Playwright MCP 和 Chrome 浏览器插件。

案例成熟度

状态	案例	说明
已形成完整流程	PPT Skill、Playwright MCP、Obsidian、飞书 CLI、临床文献综述、Hatch Pet、桌面宠物、安卓手机远程操控、远程修 Bug、GitHub Actions CI 修复	有明确安装、使用步骤或完整操作链路
偏工具接入教程	Draw.io MCP、Figma MCP、Notion MCP、DKFile、Chrome 浏览器插件	重点在接入方式、典型任务和安全边界
偏场景展示	HyperFrames、LLM Wiki	重点展示 Codex 与创作/知识库场景的组合方式

每个案例建议补齐什么

后续继续完善案例时，建议统一补齐这些信息：

背景：为什么要做这个案例。
环境：系统、工具版本、账号权限、依赖。
输入：原始 prompt、配置文件或数据源。
过程：Codex 做了哪些关键动作。
结果：截图、PR、网页地址、导出文件或日志。
验证：如何判断案例成功。
风险：权限、凭证、外部服务、写回操作、成本和失败场景。

参考来源

案例中涉及的第三方工具、仓库和文章来源统一整理在参考来源与致谢。

index

description: "Codex 快速上手教程，从认识 Codex、安装账号、桌面 App、第一个任务到开发者入口，帮助初学者先跑通。" permalink: /start/

::: tip 最后核对官方资料最后核对日期：2026-06-29。本页是快速上手索引，Codex 的安装、账号、CLI、IDE、Cloud 与移动端入口请以 Codex 文档入口、Codex in ChatGPT Help Center 和 Codex Cloud docs 为准。 :::

快速上手

这组教程面向第一次学习 Codex 的读者。

本教程涵盖从安装APP到运行你的第一个任务的完整流程。适合希望利用 Codex 进行日常工作的人群。

如果你是开发者，本教程也提供了额外 CLI、IDE、Cloud 等内容来入门 Codex 。

快速上手

如果你知道怎么跟AI对话，那么恭喜你，你已经准备好开始使用 Codex 了！跟着下方的教程，循序渐进地开始使用 Codex。

给开发者

很多时候 Codex APP 就能满足你的要求。

但如果你本身具备一定的开发基础，可以尝试使用 CLI、IDE 或 Cloud 来更深入地使用 Codex。

如果你是个终端迷，那么CLI是一个合适的选择。特别是你有 Vim 基础，喜欢折腾快捷键映射，配合类似于 tmux 的终端复用工具，你可以在你熟悉的环境中更高效地使用 Codex。

如果你更习惯在IDE的环境中开发，或者希望完全托管到云端中，那么IDE或Cloud是更好的选择。

学完能做到什么

知道 Codex 的主要入口和适合场景。
能安装并打开桌面 App。
能把一个本地文件夹交给 Codex 处理。
能写出目标、范围、验证方式都清楚的任务说明。
能检查 Codex 的改动，知道什么时候继续追问或停止。
能用 CLI、VS Code 和 Cloud 进入更真实的项目任务。

我已经学完了

如果你学有余力，可以尝试阅读进阶教程。这是非常具备技术含量的文档，能让你更进一步了解这个工具，充分发掘它的潜力，解放生产力。

下一步

下一步：Codex 是什么。

mobile control

description: "手机端跟进桌面 Codex 任务教程，说明 ChatGPT App 入口、跨设备连接、任务查看和协同边界。"

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

用手机远程操控 Codex

Codex 现在支持 Android 和 iOS 手机。在手机上发消息，就能操作电脑上的 Codex。

简单说：电脑上的 Codex 在跑，手机连过去，离开电脑时也能查看、回复、审批和调整任务。

把 ChatGPT App 更新到最新版，然后选择连接电脑上的 Codex。

ChatGPT 手机 App 中的 Codex 入口

连接桌面 Codex APP：

手机端连接桌面 Codex App

在 ChatGPT 里打开 Codex 就能用。

在 ChatGPT 手机 App 中打开 Codex

它能做什么

手机连上电脑后，你可以在以下场景派上用场：

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

任务实际还是在电脑上跑。文件、依赖、凭据、权限和本地配置不会因为连了手机就搬到手机上。

使用前提

使用前先确认：

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

不适合怎么用

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

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

毕竟电脑的大屏优势仍然是不可替代的。

一个典型流程

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

和 Codex Cloud 的区别

对比项	手机端连接桌面 App	Codex Cloud
执行位置	你的电脑、devbox 或远程环境	OpenAI / ChatGPT 连接的云端任务环境
文件与凭据	留在原机器上	依赖云端连接的仓库与授权
适合任务	跟进本地长任务、审批、查看结果	不依赖本地电脑的仓库任务
是否能离开电脑	可以，但要确保网络通畅	可以

下一步

下一步：安装与登录。

index

description: "Codex 进阶教程总览，整理费用上下文、AGENTS.md、Skills、权限管理、自动化、Hooks、沙盒、配置、团队协作和排障路径。" permalink: /advanced/

::: tip 最后核对官方资料最后核对日期：2026-06-29。本页是进阶教程索引，涉及费用、上下文、AGENTS.md、Skills、Plugins、权限、自动化、Hooks、沙盒、线程管理、配置和团队实践的细节，请以 Codex 文档入口与各章节引用的官方资料为准。 :::

进阶教程

相信你已经能通过快速上手完成了你到第一个任务。

如果你仍有好奇心，你可以按照下面的顺序深入了解 Codex 的各个方面。你将会学到一些很通用的 Agent 使用技巧。这意味着不少内容你都可以迁移到 Claude Code、KimiCode 等其他Agent上。

学完能做到什么

理解 token、上下文、缓存和成本。更清楚 Codex 是如何计费的。
了解 AGENTS.md 。知晓其作为常驻提示词的重要性。
了解 Skills 和 Plugins。了解规范，并能在实际项目中灵活运用这些强大的拓展工具。
了解APP页面的权限管理。明白为什么Auto-Review如此实用。
了解自动化。让 Codex 定时帮你干活。
了解 Hooks。让你能在 Codex 执行过程中插入自定义逻辑。
了解沙盒与审批。更进一步了解 Codex 的安全边界。
了解自动线程管理。明白作为Codex APP的一大特色功能如何重新改变工作流。
了解配置文件 config.toml。了解核心字段的影响
提供团队实践。让 Codex 进入生产环境开发的团队开发。
提供排障手册。帮助你快速定位和解决问题。

下一步

下一步：理解费用与上下文。

本文由 GitVP 从 GitHub 收录并在站内全文呈现，版权归原作者所有（MIT）。

← 回到全部文章

CodexGuide

面向全球初学者、创作者、开发者与团队的 Codex 实践指南

在线网站

主题皮肤

项目愿景

适合谁

❤️ 赞助商

你会在这里看到什么

推荐阅读路径

1. 第一次上手

2. 想用 Codex 改真实项目

3. 想把 Codex 放进团队

快速入口

内容框架

本地预览

设计原则

Star 趋势图

社区共建

事实来源

参与贡献

开源协议

声明

index

学习路线

导航

快速上手

进阶教程

实战案例

参考手册

一个实用的起点

app installation

Codex 桌面 App 下载与安装

下载

登录

安装后验证

下一步

account plan

订阅 ChatGPT Plus / Pro

为什么需要订阅

前提条件

方法一：苹果礼品卡（最稳定，推荐优先尝试）

支付宝购买

苹果官网购买

第三方

方法二：土耳其区 App Store（第三方经验，价格优先）

详细流程

方法三：安卓 Google Play（备选）

Visa 卡购买

方法四：AI MEMBER 卡密自助充值（省去海外支付步骤-操作更简单）

准备物品：

第一步：选择适合自己账号的 Plus 商品

第二步：填写订单信息并付款

第三步：进入充值中心并验证卡密

第四步：在同一个浏览器中获取 Session

第五步：返回充值页并提交

第六步：确认 Plus 是否到账

常见问题

订阅后验证

下一步

app overview

了解 Codex 基本组成

认识对话和项目

对话框功能说明

插件与技能

自动化

设置面板

设置说明

个人

集成

编码

已归档

下一步

first task

用 Codex 完成第一个任务

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

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

第三步：添加工作目录

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

第五步：逐步迭代

下一步