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