出海数字营销宝典 Logo
出海数字营销宝典evaoo.com

Codex 零基础入门教程:8000 字详解环境配置与工作流实战

2026-11-06govin.eth | G哥 @goan999999约 28 分钟阅读

作者:govin.eth | G哥(@goan999999)•发布日期:2026-09-02•8000 字实战长文

8000 字讲透 Codex 零基础入门教程8000 字讲透 Codex 零基础入门教程

这份《Codex 零基础入门教程》记录了从首次打开软件,到完成可验收任务的完整路线。全文不堆砌生僻术语,零编程基础也能跟着一步步跑通。

第一次打开 Codex 时,我犯的错误和很多人一样:把它当成一个“更会写代码的 ChatGPT”。我在输入框里写了一句“帮我做一个网站”,然后盯着它生成文件。几分钟后页面确实能打开,但部分按钮点不动,移动端会溢出,刷新后数据消失,我也不知道它改了哪些文件。

那一刻我才明白:会生成代码,不等于能交付项目。Codex 的核心能力是直接进入真实项目目录,依次读取文件、理解约束和修改代码,再运行命令检查结果,最后根据反馈继续迭代。它是一个能直接操作电脑和项目环境的执行者。

用好 Codex 需要的不只是写提示词。你还要做好四件事:选对工作目录、给准权限、提供适量上下文,以及写清验收标准。这四件事没处理好,模型能力越强,跑偏的速度反而越快。

这篇教程不要求你有编程基础。你只要会建文件夹、装软件和复制命令,并在每一步核对结果就行。下面我们以“个人任务看板”为练习项目,依次走完安装、首次对话、需求拆解、修改代码和测试审查,最后整理长期规则。跟着做完一遍,你就能掌握一套通用的工作方法,后续做网页、自动化脚本、数据工具和 AI 产品都能复用。


一、先理解 Codex:替你跑完整个工作循环

Codex 工作循环:理解目标、检查环境、制定计划、执行修改、验证结果、审查差异、交付说明Codex 工作循环:理解目标、检查环境、制定计划、执行修改、验证结果、审查差异、交付说明

过去用普通 AI 编程工具时,常见流程是我描述问题、AI 给代码、我复制到编辑器,报错后再把报错粘回聊天框。上下文在聊天框、编辑器和终端之间来回搬运,大量精力都耗在解释“我刚才做了什么”上。

Codex 把这几个环节串了起来。它能在授权范围内读取项目、搜索和编辑代码,还能直接运行构建或测试命令,再根据输出决定下一步动作。一个完整的工作循环包含 7 步:

  1. 理解目标:确认你要解决的具体问题。
  2. 检查环境:读取目录结构、关键文件、项目说明和依赖。
  3. 制定计划:把大任务拆成可验证的小步骤。
  4. 执行修改:创建或编辑文件,按需运行命令。
  5. 验证结果:运行测试、构建、类型检查或本地预览。
  6. 审查差异:确认没有误改无关文件,也没有引入回归问题。
  7. 交付说明:汇报改动文件、验证结果和剩余风险。

最关键的是第五步和第六步。只生成代码的工具容易给人“已经写完”的错觉,合格的 Agent 必须用运行结果证明代码可用。每次下发任务时,我都会在末尾加上这句话:

完成后请运行与本次修改相关的检查,并告诉我:改了哪些文件、运行了哪些验证、结果如何、还有哪些未验证风险。不要只说“已完成”。

这句话看起来简单,却能大幅减少“代码写完却跑不通”的情况。


二、四种入口怎么选:新手先选离工作最近的那个

Codex 四种入口对比:桌面应用、IDE 扩展、CLI 命令行、Web 与云端Codex 四种入口对比:桌面应用、IDE 扩展、CLI 命令行、Web 与云端

Codex 目前提供四种使用入口:桌面应用、IDE 扩展、CLI 命令行和 Web 云端。这四种形态各有分工,分别对应不同的工作场景。

桌面应用

适合刚接触 Codex 的新手。不用先学终端命令,就能直接选择本地项目、查看文件改动和并行开多个任务。它相当于一个通用工作台,既能写代码,也能处理文档、表格和网页等文件任务。

IDE 扩展

适合平时在 VS Code、Cursor 或 Windsurf 里写代码的人。它能直接读取当前打开的文件、选中的代码段和编辑器报错。做局部修改、解释代码或排查当前报错时最顺手。

CLI(命令行)

适合习惯终端工作流的人。它直接在项目目录里运行,方便做批量修改、脚本调用、CI 集成和高频命令执行。本文重点演示 CLI,带你直观看到它读取项目、申请权限和验证结果的过程。

Web / 云端

适合需要长时间后台运行,或者要并行处理多个仓库问题的场景。任务托管在远程环境,关掉本地电脑也能继续执行。注意云端与本地环境独立,依赖、密钥和网络权限需要单独配置。

第一次学习用桌面应用或 CLI,日常写代码用 IDE,需要并行或后台长跑再用云端。不用一上来把四种入口全配齐,先把一种用熟,避免把精力耗在环境配置上。


三、开始前只准备三样东西:项目文件夹、Git 和一个可验证的小目标

很多教程一上来就讲模型、MCP、Skills 和复杂配置。我照着配置了一堆东西,最后连第一个任务都没跑通。后来我把准备工作缩成三项:

第一,准备一个独立项目文件夹:

首次使用时,不要让 Codex 直接扫描桌面、下载目录或整个硬盘。工作目录决定了它能看到哪些文件,也决定了默认能改哪些文件。建议新建一个专用练习目录:

mkdir codex-first-project cd codex-first-project

第二,安装 Git,并在任务前后留检查点:

Git 相当于项目的“撤销历史”,普通用户也能很快上手。让 Codex 动手前先提交一次,改完后再对比差异;就算结果不理想,也能清楚看到改了哪里并随时回退。

git init git add . git commit -m "before codex task"

第三,选择一个能在 30 分钟~60 分钟内验收的小目标:

第一次不要做“完整电商平台”“微信替代品”或“全自动赚钱系统”。目标越大,你越难判断问题来自需求、模型、环境还是代码。本文的练习目标是:

做一个本地运行的个人任务看板:支持新增、标记完成和删除任务,刷新页面后数据不丢失,界面适配手机屏幕,不接后端且无需登录。


四、安装 Codex 和 CLI:先用官方方式,再处理系统差异

安装 Codex 和 CLI:官方脚本与系统差异处理安装 Codex 和 CLI:官方脚本与系统差异处理

官方当前为 macOS 和 Linux 提供独立安装脚本。在终端中运行:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装后启动并验证版本:

codex --version codex --help

第一次启动时,按界面提示选择“使用 ChatGPT 登录”或其他可用的登录方式。

Windows 用户避坑要点:
优先使用官方 Windows 桌面应用或 WSL。务必把 Codex、Git、Node/Python 和项目文件放在同一套环境里。Windows 下最容易踩的坑是环境割裂:项目放在 Windows 磁盘,依赖装在 WSL 里,终端又从另一处启动,最终导致找不到命令或权限报错。


五、第一次不要让它写代码:先让它解释自己看到了什么

第一次上手时,先做一次只读检查最容易建立信任。你可以先输入这段指令:

先不要创建或修改任何文件。请检查当前目录,告诉我:

  1. 现在有哪些文件;
  2. 这是一个什么状态的项目;
  3. 为了完成“本地个人任务看板”,你建议采用什么最小技术方案;
  4. 需要我确认的选择有哪些。

这一步有三个作用:确认它在正确的目录里、确认它读懂了目标,以及在写代码前看清技术方案。接着让它把需求转成可验证的验收清单:

把需求改写成可验证的验收清单。每一项必须能通过页面操作或命令检查,不要写“体验良好”“代码优雅”这类无法判断的描述。先只输出清单,不要开始开发。


六、提示词不用写成论文,只要补齐四个字段

提示词四要素:目标 Goal、上下文 Context、约束 Constraints、完成标准 Done when提示词四要素:目标 Goal、上下文 Context、约束 Constraints、完成标准 Done when

新手写提示词常见的问题是缺少关键信息。一条清晰的任务指令需要包含四个字段:

1. 目标(Goal)

说明“要改变什么”。避免只写“优化一下”,直接写清“新增任务支持回车提交,并拦截纯空格输入”。

2. 上下文(Context)

指明“先看哪些资料”。列出相关文件、目录、截图、报错原文或参考代码,让 Agent 直接读取有效信息。

3. 约束(Constraints)

划定“不能碰的边界”。比如不引入新框架、不改公共接口、不读取 .env 文件,以及保持现有代码风格。

4. 完成标准(Done when)

定义“怎么算做完”。比如测试通过、构建成功、指定交互可复现,并且没有新增 lint 报错。

Codex 结构化 4 字段提示词组装器

七、权限怎么选:按需授权,刚好够用即可

Codex 权限三档体系::read-only、:workspace、:danger-full-accessCodex 权限三档体系::read-only、:workspace、:danger-full-access

Codex 可以执行命令、修改文件和访问网络。权限开得太大容易带来误操作风险,还会让你错过观察它执行细节的机会。

Codex 权限选择与安全边界评估台

日常授权可以记住这条规则:读代码用只读模式,改项目用工作区模式,装依赖和联网按次确认;涉及删文件、重置 Git 历史、强制推送或操作生产环境时,必须逐条人工核对。控制权限的目标,是把潜在失误的影响范围锁在可控边界内。


八、先掌握这 8 个常用命令,其余按需再查

/status

查看当前会话、上下文用量和配额状态。长任务执行中途建议定期看一眼。

/model

切换当前任务使用的模型。简单改动选轻量快速模型,复杂架构和长任务换高阶模型。

/reasoning

调整推理深度。低档适合边界清晰的小改动,中高档适合跨文件排错。

/permissions

切换当前会话的操作权限(只读、工作区写入或全盘访问)。

/init

生成项目的 AGENTS.md 初始模板,生成后需结合项目实际精简和补充。

/plan

开启规划模式。遇到需求模糊或改动范围大的任务,先确认实施步骤再写代码。

/review

对未提交的改动或指定分支做代码审查,重点排查潜在缺陷。

/compact

会话过长时压缩早期记录,保留核心目标、约束和结论,减少旧信息干扰。


九、AGENTS.md:把每次都要重复的话变成项目规则

AGENTS.md 项目规则:项目目标、修改规则、验证规则AGENTS.md 项目规则:项目目标、修改规则、验证规则

我曾连续三次在对话里提醒 Codex:改用 pnpm 而非 npm、改完代码要跑测试、别碰自动生成目录。反复提醒之后,我才体会到 AGENTS.md 的作用。它相当于写给 Agent 的项目说明书,Codex 进入目录时会自动读取对应层级的规则。

MARKDOWN18 行
1# AGENTS.md 极简黄金范本
2
3## 项目目标
4
5- 这是一个零依赖的本地任务看板练习项目。
6- 优先保持代码简单、可读,避免过度抽象。
7
8## 修改规则
9
10- 使用原生 HTML、CSS、JavaScript,不新增框架或远程依赖。
11- 不修改与当前任务无关的文件。
12- 不读取或输出任何密钥、环境变量和个人文件。
13
14## 验证规则
15
16- 修改 JavaScript 后,检查浏览器控制台无新增错误。
17- 每次交付都验证新增、完成切换、删除和刷新持久化。
18- 最终说明必须列出修改文件、验证结果和剩余风险。

编写 AGENTS.md 的两个避坑原则:一是别写成几千字的空洞口号(比如堆砌“深度思考”这类模糊词);二是别塞入一次性临时需求(比如“今天把按钮改成绿色”)。写进文件的长期规则必须具体、可验证且能反复复用。


十、完整跑通一次:计划、执行、验证和审查

真正跑通一次:计划、执行、验证与审查全流程真正跑通一次:计划、执行、验证与审查全流程

现在回到个人任务看板项目。第一轮先别管视觉细节,让 Codex 先把核心功能跑通:

现在按已确认的验收清单实现第一版。先完成可用性,不做额外动画和复杂组件。每完成一个阶段就运行能执行的检查;如果环境缺少必要工具,先说明最小解决办法,不要擅自扩大依赖。完成后停止,等待我验收。

第一版跑起来后,先手动做一轮验收:依次测试新增三条任务、纯空格拦截、标记完成和删除任务,再刷新页面并切到手机窄屏检查布局。遇到 Bug 时,直接给它提供最小可复现步骤:

我发现一个可复现问题:新增任务“A”,标记为完成,刷新页面后任务仍存在,但完成状态丢失。请先定位根因并解释数据在哪一步没有被保存,再做最小修改。不要重构无关代码。修复后按这组步骤重新验证,并补一个能防止同类回归的检查。

功能验收通过后,再单独开一轮调整界面样式,最后运行 /review 检查代码差异。把报错拆成可定位、可修复和可回归验证的具体问题,才能真正练出稳定的项目交付能力。


十一、上下文管理:给得太少会猜,给得太多会迷路

你可以把项目上下文拆成四层来管理:

  1. 当前任务:说明这次要做什么、问题怎么复现、完成标准是什么,保持简短明确。
  2. 项目规则:写进 AGENTS.md,包含目录结构、常用命令和工程约束。
  3. 可复用流程:反复执行的固定步骤(如代码审查清单、发版流程),封装成 Skill。
  4. 外部动态数据:保存在 GitHub、Sentry 或 Figma 里且实时变化的信息,通过 MCP 按需读取。

请先整理当前任务上下文,只保留:目标、核心约束、已确认决策、已修改文件、验证结果、未解决问题和下一步计划。删除已被推翻的方案与重复讨论。


十二、模型与推理强度:按任务难度选,不要把最高档当默认

  • 低~中推理强度:适合解释代码、微调文案和边界清晰的单文件修改。
  • 中~高推理强度:适合跨文件开发新功能、常规重构和补全测试。
  • 高~最高推理强度:适合排查疑难 Bug、架构迁移、长流程任务和安全审查。

选模型时主要看三点:任务有多复杂、出错代价有多高,以及你能不能快速验证结果。


十三、MCP、Skills 和插件:先跑通人工流程,再自动化

MCP、Skills 与插件演进路线:先跑通人工流程,再自动化MCP、Skills 与插件演进路线:先跑通人工流程,再自动化

实用原则:还没手动跑通三次的流程,先不要做自动化。

建议新手按这个顺序逐步升级:先跑通纯本地项目 → 写好 AGENTS.md → 把重复检查封装成 Skill → 最后按需接入外部 MCP。


十四、新手常踩的 10 个坑与修正方法

  1. 在错误目录启动:启动后先核对当前工作目录和文件列表。
  2. 一句话要求做完大型项目:先定好最小可用范围,把大目标拆成每轮可验收的小任务。
  3. 不留 Git 检查点:动手前先提交一次 Git,改完先看 diff 再决定去留。
  4. 只说要做什么,不说禁区:提前写清依赖、接口、目录和数据安全边界。
  5. 把“运行没报错”当成“需求已完成”:按真实用户操作写验收清单,跑通测试只是其中一项证据。
  6. 遇到 Bug 就让它大改重构:先让它定位根因,再做最小改动,最后补上防回归检查。
  7. 一上来就给全盘权限:先用只读模式看方案,日常开发用工作区模式,高风险命令逐次确认。
  8. 每次都在提示词里重复贴规则:把长期规则写进 AGENTS.md,把固定流程做成 Skill。
  9. 在一个超长会话里混做多件事:一个会话只处理一个目标;对话太长就用 /compact 压缩,换新任务就重开会话。
  10. 只信口头总结,不看实际改动:亲自核对改动文件、终端输出、测试结果和 Git diff,一切以执行记录为准。

十五、5 个可以直接复制的入门提示词

  1. 陌生项目快速理解

先不要修改文件。请从当前项目中识别:项目用途、主要目录、启动入口、依赖管理方式、构建/测试命令和最可能出问题的三个区域。每个结论都标明依据文件。最后给我一条从零启动项目的最短路径;如果信息不足,明确说缺什么,不要猜。

  1. 把模糊想法变成可执行需求

我想做【填写想法】。先不要写代码,请像产品经理和工程师一起审需求:指出目标用户、核心场景、最小功能闭环、明确不做的范围、关键风险和可验证验收标准。最多向我提出 5 个会影响方案的关键问题;等我回答后,再输出分阶段实施计划。

  1. 安全地实现一个功能

目标:【功能】。上下文:【相关文件/报错/参考】。约束:【不能改的接口、依赖、目录和风格】。完成标准:【测试、构建和用户操作结果】。先读取相关文件并给出最多 6 步计划;只做与目标有关的最小修改;完成后运行相关验证,列出修改文件、命令结果和剩余风险。

  1. 修复可复现 Bug

问题现象:【实际结果】。复现步骤:1.【步骤】2.【步骤】3.【步骤】。预期结果:【应该发生什么】。请先定位根因并指出证据,不要立即重构;然后提出最小修复方案。实施后按同一组步骤验证,并补充能防止回归的测试或检查。不要修改无关文件。

  1. 任务结束前交付自检

在结束前做一次交付审查:逐条对照原始目标和验收标准;查看 Git diff 是否包含无关修改;运行与本次变更相关的测试、构建、lint 或类型检查;检查错误处理和边界场景。最后只输出四部分:已完成、验证证据、未完成、风险与下一步。没有证据的项目不要标记为完成。


十六、交付质量公式与下一步实践

用了一段时间后,我对 Codex 最大的认知变化是:提示词只是任务入口,真正决定结果的是工作系统。

一套可靠的工作系统包含这些环节:选对工作目录、留好 Git 检查点、划清目标与边界,同时配好权限、定好验收标准,并在每次交付后跑测试和更新规则。模型能力越强,这套系统越关键。Agent 执行速度很快,方向对了能成倍提效,前提错了也会加速跑偏。

Codex 交付质量公式

Codex 交付质量 = 清晰目标 × 有效上下文 × 合理权限 × 可执行验收

上面四项只要有一项缺失,交付结果就会大打折扣。你现在就可以新建一个空文件夹,照着本文把“个人任务看板”从头跑通一遍。

作者简介:govin.eth | G哥,韩国硕士,大厂 AI 产品经理,持续分享 AI 工具、Agent 产品、Codex 实战与自动化经验。X 账号:@goan999999。

Codex 实战

觉得本文有启发?一键复制标准引用摘要

自带原文归因链接与核心摘要,可直接粘贴至团队飞书/Slack 知识库、技术周报或大模型上下文。