2026-05-07 调研版

零基础照着做：把 Codex 跑起来，并变成你的开发搭档

这是一份面向中文用户的 Codex 课程草稿。页面结构参考你喜欢的教程站：左侧是课程地图，中间是完整教程，右侧是页内目录。内容先按官方文档、帮助中心和开源仓库整理，后续可以继续加入你的经验、案例和视频。

适合：第一次接触 Codex 目标：完成第一条可验证任务形态：单文件静态教程页

codex workspace

$ codex "先阅读项目，再帮我实现并验证这个需求"

读上下文 扫描文件、说明、报错、现有风格。

定计划 拆步骤，确认风险，选择最小改动。

做修改 编辑文件，运行命令，保留证据。

交付说明改了什么，验证了什么。

Codex 是什么

Codex 是 OpenAI 的编码智能体。它不只是回答问题，还能在你授权的范围内读取文件、修改代码、运行命令、做代码审查、整理资料、生成报告，并把结果留在你当前项目里。

对新手来说，最重要的理解是：Codex 不是一次性问答工具，更像一个需要上下文、规则和验收标准的队友。你给它的目标越清楚，它能检查自己工作的机会越多，结果就越稳定。

最小成功标准： 第一次学习不要追求复杂自动化。先让 Codex 在一个安全目录里完成一件小事，例如创建一个页面、解释一个项目、修复一个可复现的小 bug，并且跑一次你能看懂的检查。

选择入口：App、CLI、IDE、Web

Codex 现在有多个使用入口。你不需要全部掌握，先选一个最贴近你当前工作的入口即可。

入口	适合谁	最常见用法
Codex App	想在桌面里管理多个线程、项目、自动化和改动审查的人。	本地项目协作、并行线程、工作树、浏览器预览、提交前审查。
Codex CLI	喜欢终端、脚本和命令行工作流的人。	运行 `codex` 进入交互式 TUI，或用 `codex exec` 做脚本化任务。
IDE Extension	主要在 VS Code、Cursor、Windsurf、JetBrains 系列 IDE 中写代码的人。	把打开文件、选中文本、当前项目直接交给 Codex 处理。
Codex Web / Cloud	想把任务委托到云端、并行跑、从 GitHub 开 PR 的团队。	连接 GitHub 后，让 Codex 在独立云环境里处理任务并产出 PR。

推荐起步： 你现在就在 Codex 桌面环境里，适合优先学 App 的项目、线程、权限、浏览器预览和文件改动流程；同时了解 CLI，因为很多教程和高级配置都围绕 CLI 展开。

准备 3 样东西

一个 ChatGPT 账号或 API Key

使用 ChatGPT 账号登录通常最省心。不同计划包含的 Codex 权益、速率限制和可用功能会变，具体以官方帮助中心和定价页为准。

一个明确的项目文件夹

Codex 本地线程会围绕当前项目工作。新手最好先建一个练习目录，确认它只改你允许它改的文件。

一条能验证的任务

不要只说“帮我优化”。改成“把首页标题改成 X，保证移动端不换行溢出，最后打开页面检查”。

安装与登录

如果你使用 Codex App，下载并安装 Windows 或 macOS 版本，打开后登录 ChatGPT 账号，选择一个项目文件夹，然后发送第一条消息。App 适合新手，因为它把线程、文件改动、审查面板和自动化放在同一个地方。

如果你使用 CLI，官方文档给出的 npm 安装方式如下：

npm i -g @openai/codex
codex

Windows 用户可以在 PowerShell 中原生运行 Codex；如果你需要 Linux 原生工具链，也可以用 WSL2。第一次运行时按提示用 ChatGPT 账号或 API Key 登录。

第一条成功任务

学 Codex 的第一步不是背命令，而是跑通一个完整闭环：描述目标，让它读项目，让它做最小修改，让它验证，再让它汇报结果。

可以直接复制的第一条消息

请先查看当前文件夹结构，判断这是一个什么项目。然后创建一个简单的 index.html 教程页，页面包含标题、三个步骤、一个代码块和资料来源区域。完成后请检查文件是否存在，并说明我应该如何打开它。

这条消息之所以适合新手，是因为它包含了目标、上下文探索、具体产物、验收动作和交付说明。你能清楚看见 Codex 是否真的做完了。

完整实操课：从打开 Codex 到交付结果

这一课是一条从进入 Codex、选择环境、连接仓库、发起任务、查看执行日志、处理结果到复盘修正的完整实操路线。用户照着做完后，应当知道每个界面解决什么问题、应该检查什么、失败时从哪里回退。

这一课的目标： 让学习者完成一次真实 Codex App 任务，并能交付一个可检查、可复盘、可继续迭代的结果。

步骤 01

打开 Codex 首页，理解产品入口

先让学员看到 Codex 的主界面：顶部是产品与账号入口，中间是开始任务区域，周围是项目、线程或示例入口。

讲清楚 Codex 能做代码修改、解释、审查、运行命令。
强调它会围绕工作区文件行动，不是普通聊天窗口。

步骤 02

创建或选择一个工作区

引导学员选择本地项目文件夹或连接仓库。新手建议先用练习目录，避免一开始就把真实项目交给 Codex 大改。

确认目录里有可识别的入口文件、README 或 package 配置。
如果是空目录，也要明确要生成什么文件。

步骤 03

设置环境与权限

环境、命令输出和配置区域是理解“安全边界”的重点：Codex 能不能联网、能不能写文件、需要不需要审批，都会影响执行方式。

新手用默认权限即可，先理解每次审批意味着什么。
团队项目要先读项目里的 AGENTS.md 和权限策略。

步骤 04

写第一条任务提示

不要让学员只输入“帮我做个网站”。这一课要示范一条完整提示：目标、上下文、约束和验收标准一起写。

目标：做一个 Codex 中文教程页面。
约束：参考文档站布局，左侧目录，中间正文，右侧页内目录。
验收：文件可打开，移动端不乱，最后说明资料来源。

步骤 05

让 Codex 先读项目再计划

计划、日志和步骤区域是 Codex 的执行轨迹。学员要学会先看计划，而不是急着接受代码。

检查它有没有读到正确文件。
检查计划是否覆盖设计、内容、验证三个部分。

步骤 06

观察命令输出和中间结果

当 Codex 运行命令或读取文件时，终端输出不是噪音，而是证据。课程要教学生看 exit code、错误信息、缺失依赖和测试结果。

成功输出要能对应到任务目标。
失败输出要先定位原因，再决定是否改提示或改配置。

步骤 07

查看文件改动和差异

代码、文件和结果区域用来训练“不要盲接收改动”。学员要知道新增了哪些文件、改了哪些段落、有没有越界改动。

看新增文件是否和目标一致。
看是否修改了不相关配置、锁文件或敏感文件。

步骤 08

用浏览器验证界面

对页面类任务，必须打开浏览器看结果。课程里要检查桌面视口、移动端视口、长页面滚动、目录点击和搜索框交互。

桌面端检查三栏布局是否稳定。
移动端检查侧栏是否自然下沉，文字是否溢出。

步骤 09

失败时如何追问

如果页面空白、命令报错、链接打不开，不要重新开一个模糊任务。直接把错误贴回同一线程，让 Codex 基于现场继续排查。

给它完整报错，而不是只说“不行”。
要求先定位根因，再做最小修复。

步骤 10

把好用的要求沉淀进 AGENTS.md

当你发现某些提醒每次都要说，就把它写成项目规则。例如“页面改动后必须浏览器验证”“中文教程不要堆术语”“引用资料要列链接”。

全局规则适合个人习惯。
项目规则适合团队约定和特定目录。

步骤 11

把稳定任务做成可复用流程

当一个流程反复出现，就适合讲 Skills、MCP 和自动化：先手动跑通，再封装，再定期运行。

Skills 适合固定流程和模板。
MCP 适合接外部资料、浏览器、设计稿或内部系统。
Automations 适合已经稳定的重复任务。

步骤 12

交付总结：改动、验证、风险

每节课最后都要让学员看到标准交付格式。Codex 不只要说“完成了”，还要交代它改了什么、跑了什么检查、哪些地方没能验证。

改动：列文件和核心内容。
验证：列命令、浏览器检查结果。
风险：列未覆盖、依赖外部变化、需要人工补充的内容。

这一课的课堂练习

请学员选择一个空文件夹，发出一条完整任务提示，让 Codex 创建一个单页教程；完成后检查文件、打开页面验证，然后把好用的要求写进 AGENTS.md。

Codex 国内站使用教程

这一节讲国内用户如何用第三方国内站跑通 Codex：先确认入口和服务规则，再完成注册、订阅、客户端安装、CC-Switch 接入，最后用一个小任务验证配置是否可用。

先说清楚： 国内站是第三方服务，不是 OpenAI 官方订阅。价格、额度、模型名、入口和可用性都可能变化；购买前以当前页面显示为准。账号、API Key、付款信息和私有代码都属于敏感信息，不要发到公开聊天、课程素材或仓库里。

适合谁

适合被网络、手机号、官方支付或模型权限卡住，但想先体验 Codex 编程 Agent 和图像能力的用户。

先做什么

先用空目录和小任务验证流程，不要一开始连接公司仓库、主力账号或长期 Key。

怎么判断成功

能登录、能生成 API Key、能在客户端发起任务、能看到结果和用量，就算第一阶段跑通。

注册、订阅与下载

打开入口并注册

示例登录入口：codex.maynor1024.live/login。如果你在国外网络环境，也可以尝试 codex.chatgpt-plus.top/login。打开后先确认域名、HTTPS 状态、登录方式和服务说明。

选择套餐或充值

购买入口示例：maynorai.jichiyun.sbs/buy/30。购买前看清楚按量、包月、每日额度、支持模型、退款和售后规则。

下载客户端

Mac 可下载 Codex.dmg；Windows 优先使用微软商店，也可按课程提供的安装包方式安装。下载来源变化时，以当前可访问页面为准。

CC-Switch 接入

新建 API Key

在国内站后台找到 API Key 管理页，新建一个专门给 Codex 使用的 Key。建议给它单独命名，方便以后停用或更换。

填写 URL 和 Key

打开 CC-Switch，把国内站提供的接口地址和 API Key 填进去。保存前检查 URL、Key、空格和换行，复制错一个字符都会导致鉴权失败。

选择模型

代码任务把模型名设置为 gpt-5.5；图像任务使用 GPTimage2 对应入口或模型配置。模型名称以站点后台实际显示为准。

能力	适合任务
GPT-5.5	代码生成、项目重构、复杂调试、自动化脚本、把多个开发步骤串成 Agent 工作流。
GPTimage2	公众号配图、小红书封面、海报草图、网站视觉素材和内容创作者的图片需求。

第一次国内站任务

第一次不要直接让 Codex 改真实项目。建一个空文件夹，明确告诉它要做什么、不要碰什么、怎么验证。任务越小，越容易判断国内站、Key、模型和客户端是否配置正确。

帮我修改首页文案
帮我整理 README
帮我加一个英文版页面
帮我修复样式问题
帮我把项目推送到 GitHub

步骤 01

确认账号和额度

发任务前先看账号是否已登录、套餐或余额是否正常、模型是否可用。额度和计费信息只看当前后台，不要记死教程里的旧数字。

确认当前使用的是测试目录。
确认没有上传敏感文件或长期凭据。

步骤 02

写清楚任务提示

国内站也要按“目标、上下文、约束、完成标准”来写。不要只写“帮我做一个网站”，否则模型很难判断边界。

目标：生成一个 Codex 入门教程页。
约束：单文件 HTML，不读取账号、Key、余额等敏感信息。
完成：说明生成文件、打开方式和验证结果。

步骤 03

观察执行过程

执行时重点看三件事：任务有没有开始、有没有报错、有没有消耗额度。报错时保留完整错误文字，后续排查比只描述“失败了”更有效。

鉴权失败：优先检查 URL、Key 和模型名。
额度失败：检查套餐、余额或每日限制。

步骤 04

检查生成结果

如果任务生成了文件，先检查文件名和内容是否符合要求，再打开页面或运行验证命令。不要只看模型回复“完成了”。

页面类任务：打开 HTML 或预览地址。
代码类任务：运行最相关的测试、构建或命令。

步骤 05

把可复用要求保存下来

如果某些要求每次都要说，比如“不要输出 API Key”“先说明改动范围”“最后列验证结果”，就写进项目的 AGENTS.md 或自己的提示词模板里。

固定流程写成模板。
安全要求写成项目规则。

国内站常见问题

它是官方订阅吗？

不是。它是第三方入口，适合解决国内访问和支付门槛。官方权益、限制和模型能力仍以 OpenAI 官方页面为准。

需要海外手机号吗？

课程入口主打降低注册门槛，但具体验证规则可能随服务调整。遇到变化时，以当前页面提示为准。

可以处理公司代码吗？

不建议一开始就处理公司私有代码。先用公开示例或练习目录跑通，确认服务条款、隐私规则和团队要求后再决定。

失败了先查什么？

按顺序查：账号状态、套餐余额、API Key、接口 URL、模型名称、客户端配置、任务提示和当前网络。

国内站第一条可复制提示

我正在用一个空目录练习 Codex。请先说明你能访问和修改哪些内容，再创建一个单文件中文教程页。页面包含标题、三个步骤、一个代码块和资料来源。不要读取或输出任何账号、API Key、余额、付款信息或私有仓库内容。完成后说明文件位置、打开方式和验证结果。

把需求说清楚：四件套

官方最佳实践把高质量任务提示拆成四个部分：目标、上下文、约束、完成标准。你不必每次都写长提示，但复杂任务最好按这个结构写。

目标 Goal

你到底想改什么、做什么、修什么。

上下文 Context

相关文件、错误日志、接口文档、用户反馈。

约束 Constraints

不要改哪些文件，要遵守什么风格，能不能加依赖。

完成标准 Done when

测试通过、页面可打开、bug 不复现、输出格式正确。

目标：把登录页表单改成两列布局，并保持移动端单列。
上下文：相关文件是 src/pages/Login.tsx 和 src/styles/login.css。
约束：不要引入新 UI 库，沿用现有颜色和间距变量。
完成标准：运行 npm test，打开页面检查 390px 和 1440px 两个视口。

先计划再动手

任务越复杂，越应该让 Codex 先计划。计划不是拖慢速度，而是让它先读上下文、暴露假设、拆解风险，再开始改文件。Codex 的官方最佳实践也建议在复杂、模糊、难描述的任务上使用 Plan mode 或先要求它采访你。

判断标准： 如果你自己也说不清要改哪些文件、怎么验收，先让 Codex 提问；如果你已经知道目标但担心范围过大，先让它列计划；如果只是改一个文案或单个样式，可以直接执行。

请先不要写代码。先阅读相关文件，给我一个 5 步以内的实现计划。
计划里标出你需要确认的问题、可能影响的文件、准备运行的验证命令。
我确认后你再开始实现。

验证与审查

Codex 的质量来自闭环。不要只让它“写完”，要让它“证明写完”。证明可以是测试、lint、类型检查、浏览器检查、构建日志、手动复现步骤，或者 diff 审查。

代码层

单元测试、类型检查、格式化、lint、构建。

界面层

启动开发服务器，打开浏览器，检查不同视口和关键交互。

交付层

让 Codex 总结改动、列出验证结果、说明未验证的风险。

完成后请：
1. 运行项目里最相关的测试或检查命令。
2. 如果是页面改动，启动本地服务并用浏览器检查。
3. 最后按“改动 / 验证 / 风险”三段总结。

线程、工作树与并行

Codex 里的 thread 可以理解为一个工作会话。一个线程适合处理一个连贯任务。长任务可以继续追问，也可以在上下文太长时压缩；不同方向的任务可以 fork 或新开线程。

并行是 Codex 的强项，但不要让两个线程同时改同一批文件。对真实项目，建议用 Git 分支或工作树隔离改动。Codex App 内置工作树支持，适合同时推进多个互不冲突的尝试。

AGENTS.md：把重复要求写成规则

如果你每次都要提醒 Codex “先读项目、不要乱加依赖、修改后跑测试”，那就应该写进 AGENTS.md。官方文档把它描述为给 Codex 的项目级自定义说明：Codex 在开始工作前会读取这些文件，并按目录层级组合指令。

# AGENTS.md

## 项目说明
- 这是一个中文教程站，主要入口是 index.html。
- 页面风格参考文档站：左侧目录，中间正文，右侧页内目录。

## 工作要求
- 修改前先说明会改哪些文件。
- 新增内容要保持中文表达清楚，不要堆术语。
- 页面改动后必须用浏览器检查桌面和移动端布局。

## 完成标准
- 文件能直接打开。
- 没有明显文字溢出、重叠或空白异常。
- 最终回复包含改动和验证结果。

可以有全局 ~/.codex/AGENTS.md，也可以有项目根目录的 AGENTS.md，还可以在子目录里放更具体的规则。越靠近当前目录的说明越具体，通常优先级越高。

config.toml 与权限

config.toml 用来保存 Codex 的持久配置，例如模型、推理强度、沙箱、审批策略、MCP 服务器和配置 profile。个人默认配置通常放在 ~/.codex/config.toml，可信项目可以使用 .codex/config.toml。

# ~/.codex/config.toml
model = "gpt-5.3-codex"
reasoning_effort = "medium"

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

[profiles.fast-local]
approval_policy = "never"
sandbox_mode = "workspace-write"

新手建议： 不要一开始就给 Codex 全电脑权限。先在练习目录里使用默认权限，理解它会读什么、改什么、什么时候需要审批，再逐步放宽。

MCP：把外部工具接进来

MCP 是 Model Context Protocol，用来把外部工具和上下文接给 Codex。例如文档检索、浏览器、Figma、内部系统、数据库只读查询等。官方文档说明，Codex 在 CLI 和 IDE extension 中支持 MCP server。

适合使用 MCP 的场景：上下文在仓库外、信息经常变化、你希望 Codex 调工具而不是靠复制粘贴、或者团队需要可复用集成。

# 例：通过 CLI 添加一个文档检索 MCP server
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 在 Codex TUI 中查看活跃 MCP
/mcp

Skills 与插件：把稳定流程封装起来

如果一个流程你反复使用，比如 PR 审查、故障排查、发布说明、数据报告，就可以把它做成 Skill。Skill 通常包含一个 SKILL.md，描述什么时候使用、怎么做、需要哪些脚本或模板。

初版 Skill 不要追求覆盖所有情况。先围绕 2 到 3 个真实任务写清楚输入、步骤和输出，跑顺后再扩展。团队共享时，可以把 Skill 打包进插件。

自动化：让稳定任务定期运行

当一个工作流已经稳定，可以用 Codex App 的 Automations 定时运行，例如每周总结提交、每天检查 CI 失败、定期草拟发布说明、扫描潜在 bug、生成站会摘要。

顺序很重要： 先手动跑通，再沉淀成 Skill，最后再变成 Automation。还需要频繁人工纠偏的流程，不适合直接自动化。

提示词模板

让 Codex 解释项目

请先阅读当前项目结构和关键文件，然后用中文说明：
1. 这个项目是做什么的。
2. 主要入口文件在哪里。
3. 本地运行、构建、测试命令分别是什么。
4. 新手继续开发时最需要注意的 3 件事。

让 Codex 修 bug

现象：描述 bug 如何出现。
复现：列出具体步骤和输入。
期望：说明正确行为。
约束：请先定位根因，不要大范围重构。
完成：修复后运行相关测试，并说明为什么这个修复覆盖了复现路径。

让 Codex 做教程内容

请基于官方文档和当前项目内容，整理一篇中文教程。
要求：
- 先给目录，再写正文。
- 每一节都要有“做什么、为什么、怎么验证”。
- 把不确定或会随时间变化的信息标注为“以官方页面为准”。
- 最后列出资料来源链接。

常见问题

我不会写代码，可以用 Codex 吗？

可以，但要从小任务开始。让 Codex 解释文件、生成简单页面、整理表格、写教程，比一上来让它重构大型系统更合适。

Codex 会不会乱改我的文件？

本地工作时它会在当前项目和权限范围内行动。新手应该使用练习目录、版本控制、默认审批和沙箱设置；在最终接受改动前查看 diff。

什么时候用 Cloud，什么时候用 Local？

本地适合你要立刻看文件、运行本机工具、检查页面的任务。Cloud 适合委托后台任务、并行尝试、从 GitHub 仓库开 PR 的任务。

教程里要不要写模型价格和限额？

可以写入口和查询方法，但具体价格、限额、包含计划变化很快，页面中应提示以官方定价页和帮助中心为准。

调研来源

这一版内容优先整合官方资料，再补充开源仓库信息。后续你加入自己的实操经验时，可以把“官方事实”和“个人经验”分开标注。