8000字讲透 | Codex零基础入门教程
本《Codex零基础入门教程》保证你和你的兄弟姐妹都能看懂,只要小学毕业就能看明白。这不是功能词典,而是一名普通学习者从第一次打开 Codex,到真正让它完成一个可验收任务的完整路线,以最通俗易懂的语言传递给你。建议您先收藏,后边慢慢看!
第一次打开 Codex 时,我犯的错误和很多人一样:把它当成一个“更会写代码的 ChatGPT”。我在输入框里写了一句“帮我做一个网站”,然后盯着它生成文件。几分钟后页面确实能打开,但按钮有的不能点,移动端会溢出,刷新后数据消失,我也不知道它改了哪些文件。
那一刻我才明白:会生成代码,不等于会交付项目。Codex 真正厉害的地方,不是某一次回答写得多漂亮,而是它能进入一个真实项目,读取文件、理解约束、修改代码、运行命令、检查结果,再根据反馈继续迭代。它更像一个能操作电脑和项目环境的执行者,而不是只在聊天框里给建议的问答机器人。
但这也意味着,使用 Codex 的门槛并不只是“会不会写提示词”。你还要学会给它正确的工作目录、合适的权限、足够但不过量的上下文,以及明确的验收标准。只要这四件事没处理好,再强的模型也可能在错误方向上跑得很快。
这篇教程不要求你是程序员。你只需要会创建文件夹、安装软件、复制命令,并愿意在每一步查看结果。我会用一个“个人任务看板”作为练习项目,把安装、第一次对话、需求拆解、修改文件、运行测试、代码审查、长期规则和重复工作复用全部串起来。跟着做完,你得到的不只是一个 Demo,而是一套以后做网页、自动化脚本、数据工具和 AI 产品都能复用的方法。
一、先理解 Codex:它不是“替你写几段代码”,而是替你完成一段工作循环
过去我使用普通 AI 编程工具时,流程通常是:我描述问题,AI 给出代码,我复制到编辑器,报错后再把报错复制回来。上下文在聊天框、编辑器和终端之间来回搬运,最累的不是写代码,而是不断解释“我刚才做了什么”。
Codex 把这条链路接了起来。它可以在授权范围内查看项目文件、搜索代码、编辑文件、执行构建或测试命令,并把结果继续作为下一步判断依据。一个完整循环通常是:
- 理解目标:确认你到底要解决什么问题。
- 检查环境:读取目录、关键文件、项目说明和依赖。
- 制定计划:把大任务拆成可验证的小步骤。
- 执行修改:创建或编辑文件,必要时运行命令。
- 验证结果:执行测试、构建、类型检查或实际预览。
- 审查差异:确认没有误改文件,没有引入明显回归。
- 交付说明:告诉你改了什么、验证了什么、还剩什么风险。
真正有价值的是第五步和第六步。只生成代码的 Agent 很容易给你一种“已经完成”的错觉,而一个合格的 Agent 应该拿证据证明结果。以后每次下任务,我都会在结尾加一句:
1 | 完成后请运行与本次修改相关的检查,并告诉我:改了哪些文件、运行了哪些验证、结果如何、还有哪些未验证风险。不要只说“已完成”。 |
这一句看起来普通,却能明显减少“代码写完了但不能用”的情况。
二、四种入口怎么选:新手先选离工作最近的那个
Codex 目前不是单一形态。你会看到桌面应用、IDE 扩展、CLI 命令行和 Web/云端。它们不是谁替代谁,而是适合不同的工作位置。
**桌面应用:**适合第一次接触 Codex 的人。你可以选择本地项目、查看文件变化、开多个任务,也不必先熟悉终端。它更像一个“AI 工作台”,不仅能处理代码,也能处理文档、表格、网页和其他文件型任务。
**IDE 扩展:**适合已经在 VS Code、Cursor 或 Windsurf 里写代码的人。它能直接利用当前打开的文件、选中的代码和编辑器上下文。小范围修改、解释代码、修复当前报错时,IDE 入口通常最顺手。
CLI:适合想把 Codex 放进终端工作流的人。它能在项目目录中直接运行,适合批量改动、脚本化、CI 或需要频繁执行命令的任务。本文会重点讲 CLI,因为它最能让你看清 Codex 如何读取项目、申请权限和验证结果。
**Web/云端:**适合把任务交给远程环境长时间运行,或者并行处理多个项目问题。它的优势不是“界面更简单”,而是任务可以脱离你当前电脑持续执行。但云端环境与本地环境并不完全相同,依赖、密钥、网络权限需要单独配置。
我的选择方法很简单:第一次学习用桌面应用或 CLI;正在写代码时用 IDE;需要并行或长时间执行时再用云端。不要一开始把四种入口全部配置一遍。入口越多,不代表效率越高,反而容易把注意力耗在配置上。
三、开始前只准备三样东西:项目文件夹、Git 和一个可验证的小目标
很多教程一上来就讲模型、MCP、Skills 和复杂配置。我照着配置了一堆东西,最后连第一个任务都没跑通。后来我把准备工作缩成三项。
第一,准备一个独立项目文件夹。不要第一次就让 Codex 扫描桌面、下载目录或整个硬盘。工作目录既决定它看到什么,也决定它默认能改什么。新手最好创建一个专门练习目录:
1 | mkdir codex-first-project |
第二,安装 Git,并养成任务前后留检查点的习惯。Git 不是程序员专属工具,它更像项目的“撤销历史”。在 Codex 动手前提交一次,任务完成后再看差异,即使修改不满意,也能准确知道发生了什么。
1 | git init |
如果目录还是空的,可以先创建一个 README.md,再做第一次提交。你也可以用图形化 Git 工具,不必强迫自己背命令。核心不是命令,而是给每次自动修改留下可恢复的边界。
第三,选择一个能在 30 到 60 分钟内验收的小目标。第一次不要做“完整电商平台”“微信替代品”或“全自动赚钱系统”。目标越大,你越难判断问题来自需求、模型、环境还是代码。本文的练习目标是:
1 | 做一个本地运行的个人任务看板:能新增任务、标记完成、删除任务;刷新页面后数据仍保留;界面适配手机;不接后端,不需要登录。 |
这个目标足够小,却包含 UI、交互、数据保存和响应式布局,正好能练习一条完整交付链路。
四、安装 Codex 和 CLI:先用官方方式,再处理系统差异
官方当前为 macOS 和 Linux 提供独立安装脚本。在终端中运行:
1 | curl -fsSL https://chatgpt.com/codex/install.sh | sh |
安装后执行:
1 | codex |
第一次启动时,按界面提示选择“使用 ChatGPT 登录”或其他可用的登录方式。登录完成后,先检查版本和帮助信息:
1 | codex --version |
如果你已经有 Node.js 环境,也可以根据官方安装页面选择 npm 方式;如果习惯 Homebrew,也可以选择页面提供的 Homebrew 方式。不要同时用三种方式安装,否则系统可能存在多个 codex 可执行文件,更新后还在调用旧版本。
Windows 用户优先使用官方 Windows 桌面应用或官方页面当前提供的 Windows 安装路径。如果你的开发项目主要运行在 Linux 环境,也可以使用 WSL。关键不是“哪种方式更高级”,而是 Codex、Git、Node/Python 和项目文件必须处于同一个可访问环境。最常见的 Windows 坑,就是项目在 Windows 盘、依赖装在 WSL、终端又从另一个环境启动,最后表现为命令找不到或权限异常。
安装完成后,不要在任意目录直接开始。先进入刚才的练习目录,再启动:
1 | cd codex-first-project |
Codex 启动界面会显示当前模型、工作目录和上下文状态。先确认目录正确。如果目录错了,立刻退出并在正确目录重新启动。让 Agent 在错误目录工作,比提示词写得不好危险得多。
五、第一次不要让它写代码:先让它解释自己看到了什么
我第一次真正建立信任,不是因为 Codex 生成了页面,而是因为我先让它做了一次只读检查。我输入:
plaintext
1 | 先不要创建或修改任何文件。请检查当前目录,告诉我: |
这一步有三个作用。第一,确认它真的在正确目录。第二,确认它理解目标。第三,让我在写代码前看到技术选择。如果它一上来建议数据库、账号系统、Docker 和微服务,我就知道方案过度设计了。
一个理想的回答应该把方案压到足够小,例如使用 Vite + React,或者干脆用 HTML、CSS、JavaScript 和 localStorage。对于第一次练习,我更倾向于原生三件套,因为依赖少、启动简单、每个文件都看得懂。
接着让它把目标转换成验收清单:
plaintext
1 | 把需求改写成可验证的验收清单。每一项必须能通过页面操作或命令检查,不要写“体验良好”“代码优雅”这类无法判断的描述。先只输出清单,不要开始开发。 |
你应该得到类似结果:页面初次打开无报错;可以输入任务并新增;空内容不能提交;完成状态可切换;任务可删除;刷新后数据保留;375px 宽度下不横向溢出;没有未处理的控制台错误。
到这里,需求才从“我想做一个东西”变成“什么叫做完成”。
六、提示词不用写成论文,只要补齐四个字段
我后来发现,新手提示词的主要问题不是不够长,而是缺字段。官方最佳实践也把高质量任务归纳为四部分:目标、上下文、约束和完成标准。
目标(Goal):回答“要改变什么”。不要只说“优化一下”,而要说“新增任务时支持回车提交,并阻止纯空格内容”。
**上下文(Context):回答“应该先看哪里”。可以指定文件、目录、截图、报错、接口文档或参考实现。上下文不是越多越好,关键是让 Codex 先读真正相关的材料。
**约束(Constraints):回答“不能破坏什么”。例如不引入新框架、不修改公共接口、不读取 .env、保持现有视觉风格、只改当前模块。
**完成标准(Done when):回答“如何证明完成”。例如测试通过、构建成功、指定交互可复现、截图与参考图一致、没有新增 lint 错误。
把四部分组合起来,这次练习可以这样写:
plaintext
1 | 目标:在当前空目录中完成一个本地个人任务看板,支持新增、完成/取消完成、删除任务,并用 localStorage 持久化。 |
这类提示词不花哨,却比“你是一名世界级全栈工程师,请深度思考”更有用。角色设定不能替代项目事实,情绪化强调也不能替代验收标准。
七、权限怎么选:不是越大越省事,而是刚好够用
第一次看到权限提示时,我的本能是全部允许,免得反复确认。后来我意识到,Codex 能执行命令、修改文件和访问网络,权限过大不仅增加风险,也会让你失去观察它工作过程的机会。
当前 Codex 的权限可以理解为三档:
**:read-only**:适合阅读代码、解释项目、做方案、检查风险。它不能直接修改工作区。**:workspace**:允许在当前工作区内写入,并限制在选定范围内,适合绝大多数日常开发任务。**:danger-full-access**:移除本地沙箱限制。只有当你明确需要广泛访问,并且完全理解影响时才考虑。
新手默认选择工作区级权限就够了。探索陌生仓库时先用只读;确认方案后再切到工作区写入。不要为了少点两次确认就给全盘权限,也不要把包含私钥、钱包助记词、生产凭证或大量个人文件的目录直接作为工作区。
还要分清两个概念:“沙箱边界”决定命令能访问哪里,“**审批策略”**决定什么时候暂停并询问你。一个任务即使在工作区沙箱里,也可能因为需要联网、写入工作区外目录或执行高风险操作而请求批准。
我的简单规则是:读代码用只读,正常改项目用工作区,安装依赖和访问网络按次确认,删除文件、重置历史、强制推送和生产环境操作必须单独检查。权限的目标不是阻止 Codex 工作,而是让错误的影响半径可控。
八、必须认识的命令:先学 8 个,其他需要时再查
Codex 的斜杠命令会随你使用的入口和版本变化。输入 / 可以查看当前环境真正支持的命令。新手不需要背完整列表,先掌握下面这些:
/status:查看当前会话、上下文使用和限制状态。任务越长,越应该偶尔看一次。
/model:为当前任务选择模型。不要迷信永远使用最重的模型;明确的小修改可以优先速度,复杂架构、疑难调试和长任务再提高推理强度。
/reasoning:调整推理投入。低强度适合边界清楚的任务,中高强度适合跨文件修改和调试,最高档更适合真正困难且值得等待的任务。
/permissions:选择当前任务允许的操作范围。不同入口显示可能略有差异,以界面实际选项为准。
/init:为当前项目生成 AGENTS.md 初始模板。它不是生成后就完成,必须根据项目实际情况删改。
/plan:进入规划模式,适合需求尚不清楚或任务包含多个阶段时先把路线定下来。
/review:针对未提交修改、指定提交或基准分支进行代码审查。它的价值是换一个“审查视角”检查问题,而不是重复夸一遍刚才的实现。
/compact:当聊天很长时压缩早期上下文,保留目标、约束、决策和进度,减少旧信息干扰。
如果在 CLI 中,你还会常用恢复会话、分叉会话等功能。官方最佳实践提到 /resume、/fork 等命令,但可用命令会因客户端和环境而异,所以最可靠的做法仍然是输入 / 或查看官方当前命令页。
九、AGENTS.md:把每次都要重复的话变成项目规则
当我连续三次提醒 Codex“不要使用 npm,请用 pnpm”“修改后要跑测试”“不要碰生成目录”时,我才理解 AGENTS.md 的价值。它相当于写给 Agent 的项目说明,Codex 进入项目时会自动读取相关层级的规则。
你可以在项目根目录运行 /init 生成草稿,然后把它压缩成真正有用的内容。一个适合本教程项目的版本可以是:
markdown
1 | # AGENTS.md |
AGENTS.md 最容易犯两个错误。第一个是写成几千字的愿望清单,里面充满“高质量”“最佳实践”“深度思考”之类模糊要求。规则太长会占用上下文,也可能互相冲突。第二个是把一次性需求写进去,例如“今天把按钮改成绿色”。长期规则应该稳定、可执行、能反复使用。
更大的仓库可以分层放置规则:全局文件保存个人习惯,仓库根目录保存团队共同规范,子目录保存局部服务或模块规则。越靠近当前文件的具体规则优先级越高。你不需要第一天就设计完整体系;当同一个错误出现第二次,再把对应规则补进去。
十、真正跑通一次:计划、执行、验证、审查
现在回到任务看板。前面已经完成只读检查、验收清单和项目规则,接下来让 Codex 开始执行。
第一轮不要同时追求功能和精美视觉。先让它完成最小闭环:
plaintext
1 | 现在按已确认的验收清单实现第一版。先完成可用性,不做额外动画和复杂组件。每完成一个阶段就运行能执行的检查;如果环境缺少必要工具,先说明最小解决办法,不要擅自扩大依赖。完成后停止,等待我验收。 |
Codex 应该创建 index.html、styles.css、app.js 等必要文件,并用适合当前环境的方式启动或检查。你需要观察它实际运行了哪些命令。不要只看最终回复,因为执行日志能告诉你它是否真的验证过。
第一版出来后,我会自己做一轮手动验收:新增三条任务;输入空格看看是否被拦截;把一条标记完成;删除另一条;刷新页面看状态是否保留;把浏览器宽度缩到手机尺寸;打开控制台看有没有报错。
发现问题时,不要把所有现象揉成一句“还是不好用”。给 Codex 一个最小复现:
plaintext
1 | 我发现一个可复现问题:新增任务“A”,标记为完成,刷新页面后任务仍存在,但完成状态丢失。请先定位根因并解释数据在哪一步没有被保存,再做最小修改。不要重构无关代码。修复后按这组步骤重新验证,并补一个能防止同类回归的检查。 |
这种写法把现象、复现步骤、预期行为、修改边界和验证方式都说清楚了。它比“刷新有 bug,修一下”更容易得到稳定结果。
功能通过后,再单独做视觉轮次:
plaintext
1 | 在不改变现有功能和数据结构的前提下,优化界面层级:白色背景、深灰文字、蓝色强调色;内容区域最大宽度 720px;输入区和任务卡片在 375px 宽度下不溢出;完成状态要明显但不过度变淡。只修改样式和必要的语义标签。完成后对比修改前后,并再次验证全部功能。 |
最后运行 /review,让 Codex从审查角度检查未提交修改。审查重点可以写成:数据持久化是否可靠、用户输入是否安全、是否存在无法操作的交互、移动端是否溢出、是否有无关改动。审查发现的问题不要全部机械修复,要先看它是否真实、是否属于本次范围。
这条链路的关键不是“Codex 一次写对”,而是把失败变成可定位、可修复、可回归验证的问题。你真正训练的是交付能力,而不是抽卡能力。
十一、上下文管理:给得太少会猜,给得太多会迷路
Codex 的输出质量很大程度取决于它当前看到了什么。新手常见的两个极端是:只给一句需求,指望它自己找到一切;或者一次性塞进几十份文档、全部聊天记录和整个需求库。
我现在把上下文分成四层。
- 第一层是当前任务:这一次要做什么、问题如何复现、完成标准是什么。它应该短而明确。
- 第二层是项目规则:放在
AGENTS.md,包括目录结构、运行命令、工程约束和验证要求。 - 第三层是可复用流程:当同一套步骤会反复执行时,用 Skill 封装。例如固定的代码审查清单、发布说明生成、日志排查流程、内容排版规范。
- 第四层是外部动态信息:当数据存在 GitHub、Sentry、Figma、Notion、数据库或其他系统,并且会持续变化时,再通过 MCP 或插件连接。不要为了“看起来专业”接入所有工具;每增加一个工具,就增加一组权限、失败方式和上下文噪声。
当会话越来越长,先让 Codex整理状态,再使用 /compact:
plaintext
1 | 请先整理当前任务上下文,只保留:目标、核心约束、已确认决策、已修改文件、验证结果、未解决问题和下一步计划。删除已被推翻的方案与重复讨论。 |
如果任务已经分叉成两个互不依赖的问题,使用新会话或 /fork 比继续堆在一个聊天里更干净。一个会话最好围绕一个连贯目标,不要上午做前端、下午分析股票、晚上又继续同一个 Bug。
十二、模型与推理强度:按任务难度选,不要把最高档当默认
模型选择是最容易被营销话术带偏的地方。我一开始觉得,只要永远选最强模型、最高推理强度,结果就一定最好。实际使用后发现,小任务会变慢,长回答变多,而质量未必有明显提升。
我的划分方式是:
- 文件解释、文案微调、明确的单文件修改:优先低或中等推理。
- 多文件功能、常规重构、测试补全:中等或高推理。
- 疑难 Bug、架构迁移、长链路任务、安全审查:高或更高推理。
选择模型时看三个维度:任务是否复杂、错误代价是否高、你是否能快速验证。一个按钮文字修改没有必要用最慢配置;生产数据迁移即使代码不多,也值得更谨慎的推理和审查。
通过 /model 和 /reasoning 调整当前会话比频繁改全局配置更适合学习阶段。等你知道自己多数任务属于哪一类,再把稳定偏好写入 ~/.codex/config.toml。全局配置保存个人默认,项目级 .codex/config.toml 保存仓库特定设置,一次性命令行参数只处理临时例外。
十三、MCP、Skills 和插件:先跑通人工流程,再自动化
我曾经一次性安装很多 MCP 和插件,结果工具列表变得很长,授权请求变多,真正做任务时反而不知道应该调用哪个。后来我给自己定了一条规则:没有手动重复三次的流程,暂时不自动化。
MCP 适合连接外部系统,让 Codex 获取聊天框和仓库之外的实时信息。例如读取设计稿、查看错误监控、查询工单或访问内部知识库。它解决的是“上下文在哪里”的问题。
Skill 适合封装重复方法。它把触发条件、步骤、输入输出和必要脚本放在一起,让以后不必反复粘贴长提示词。它解决的是“这件事应该怎么稳定地做”的问题。
插件通常把 Skills、MCP 和相关能力打包,适合安装一整套与某个服务或工作流有关的能力。它解决的是“如何更方便地分发和启用一组能力”的问题。
判断是否值得接入,可以问三个问题:数据是否在项目外;数据是否经常变化;这个连接能否省掉持续复制粘贴。如果三个答案都是否,普通文件和提示词已经够用。
对新手最合理的升级顺序是:先完成一个纯本地项目;再写好 AGENTS.md;然后把重复出现的审查或发布流程做成一个 Skill;最后只接入一个真正需要的外部工具。能力是一层层长出来的,不是一次堆出来的。
十四、我踩过的 10 个坑,以及更直接的修正方式
- 在错误目录启动。修正:启动后第一件事查看工作目录和文件清单。
- 一句话要求完成大型项目。修正:先定义最小闭环,把大目标拆成每轮可验收的任务。
- 没有 Git 检查点。修正:任务前提交一次,完成后查看 diff,再决定是否保留。
- 只描述想要什么,不说不能改什么。修正:明确依赖、接口、目录和数据安全边界。
- 把“运行成功”当成“需求完成”。修正:用用户动作写验收清单,运行测试只是证据之一。
- 发现 Bug 后让它大规模重构。修正:先要求根因分析,再做最小修改,最后补回归检查。
- 一开始就给全盘权限。修正:只读探索,工作区执行,高风险动作单独确认。
- 把所有规则塞进每次提示词。修正:长期规则写入
AGENTS.md,重复流程做成 Skill。 - 同一个长会话处理不相关任务。修正:一个会话对应一个连贯目标,过长就整理并压缩,分叉就新开。
- 相信最终总结,不看实际差异。修正:查看修改文件、命令输出、测试结果和 Git diff。Agent 的自述不是证据,执行记录才是。
十五、5 个可以直接复制的入门提示词
1、陌生项目快速理解
plaintext
1 | 先不要修改文件。请从当前项目中识别:项目用途、主要目录、启动入口、依赖管理方式、构建/测试命令和最可能出问题的三个区域。每个结论都标明依据文件。最后给我一条从零启动项目的最短路径;如果信息不足,明确说缺什么,不要猜。 |
2、把模糊想法变成可执行需求
plaintext
1 | 我想做【填写想法】。先不要写代码,请像产品经理和工程师一起审需求:指出目标用户、核心场景、最小功能闭环、明确不做的范围、关键风险和可验证验收标准。最多向我提出 5 个会影响方案的关键问题;等我回答后,再输出分阶段实施计划。 |
3、安全地实现一个功能
plaintext
1 | 目标:【功能】。上下文:【相关文件/报错/参考】。约束:【不能改的接口、依赖、目录和风格】。完成标准:【测试、构建和用户操作结果】。先读取相关文件并给出最多 6 步计划;只做与目标有关的最小修改;完成后运行相关验证,列出修改文件、命令结果和剩余风险。 |
4、修复可复现 Bug
plaintext
1 | 问题现象:【实际结果】。复现步骤:1.【步骤】2.【步骤】3.【步骤】。预期结果:【应该发生什么】。请先定位根因并指出证据,不要立即重构;然后提出最小修复方案。实施后按同一组步骤验证,并补充能防止回归的测试或检查。不要修改无关文件。 |
5、任务结束前自检
plaintext
1 | 在结束前做一次交付审查:逐条对照原始目标和验收标准;查看 Git diff 是否包含无关修改;运行与本次变更相关的测试、构建、lint 或类型检查;检查错误处理和边界场景。最后只输出四部分:已完成、验证证据、未完成、风险与下一步。没有证据的项目不要标记为完成。 |
用后感悟!
用了一段时间后,我对 Codex 最大的认知变化是:提示词只是任务入口,真正决定结果的是工作系统。
一个可靠的系统包括正确的工作目录、可恢复的 Git 检查点、足够清楚的目标与边界、刚好够用的权限、能被执行的验收标准、持续更新的项目规则,以及任务完成后的测试和审查。模型能力越强,这套系统越重要,因为强大的 Agent 能更快放大正确方向,也能更快放大错误假设。
所以,新手不必先追求“让 Codex 一次生成完整产品”。先让它在正确目录里完成一个小任务,拿出可验证证据,再逐步扩大任务范围。你能看懂它为什么改、知道如何撤回、能判断是否完成,才算真正掌握了 Codex。
如果只记住一句话,可以记住这条公式:
> Codex 的交付质量 = 清晰目标 × 有效上下文 × 合理权限 × 可执行验收。
任何一项接近零,最终结果都会打折。把这四项练熟,你得到的就不只是一个会写代码的 AI,而是一套能持续放大个人执行力的工作方式。











