夜雨聆风适合谁看：第一次准备安装 Codex 的开发者、技术负责人、产品工程师、数据分析师，以及想把 AI 编码从“试试看”变成“可复用工作流”的团队。本文参考 OpenAI 官方 Codex 文档整理。
图 1｜一张图看懂 Codex 入门路线
新手先跑通本地 CLI 或桌面 App；团队再补 AGENTS.md、配置文件、权限策略和云端任务。
最近很多人问我：Codex 到底应该怎么装？装完以后应该怎么用？为什么同样是 AI 编程，有的人几分钟修好 bug，有的人却把项目改得一团乱？答案往往不在“会不会提问”这么简单，而在于你有没有给 Codex 一个清晰、安全、可验证的工作环境。
Codex 不是单纯的聊天框。它的核心价值，是把“理解代码、修改文件、运行命令、验证结果、解释变更”串成一个工程闭环。你可以让它阅读一个陌生项目，定位测试失败原因，补齐单元测试，重构一个组件，写脚本处理数据，甚至在云端并行跑多个任务。但越强的工具，越需要正确的打开方式。
这篇教程不追求炫技，而是按真实上手顺序来：先讲清楚 Codex 的几个入口，再给出安装方法，然后解释第一次使用时最容易踩坑的权限、工作目录、Git 检查点和提示词写法。读完之后，你应该可以独立完成安装，并把 Codex 放进日常开发流程里。
01
先理解：Codex 到底是什么
用一句话概括：Codex 是 OpenAI 面向软件开发的 coding agent。它可以读取项目文件，修改代码，运行本地命令，根据结果继续迭代，并在结束时把改动和验证结果交给你检查。OpenAI 官方文档把它描述为可以帮助你写代码、理解陌生代码、修复 bug、做代码审查和处理开发任务的代理。
不要把 Codex 只当成“问答机器人”
问答机器人通常停在“给建议”；Codex 的差异在于它能进入你的工程现场。它会看目录结构、读报错日志、编辑文件、跑测试、根据失败信息再修一轮。你仍然是最终负责人，但它承担了大量探索、修改和验证的体力活。
Codex 目前有几个常见使用形态：桌面 App、命令行 CLI、IDE 扩展、Cloud 云端任务、SDK 和 MCP 集成。新手不需要一开始全部掌握。个人开发者建议从 CLI 或 App 入手；每天在 VS Code、Cursor、Windsurf 里写代码的人，可以装 IDE 扩展；团队想让任务在后台跑、并行处理多个 issue、生成 PR，则可以再看 Codex Cloud。
图 2｜不同入口适合不同工作方式
CLI
适合终端党、本地仓库、脚本化任务。
App
适合多线程、看 diff、跑本地项目。
IDE
适合边写边问、结合当前文件上下文。
Cloud
适合后台跑任务、并行处理、出 PR。
02
安装前准备：先把环境放对
安装 Codex 之前，建议先准备三件事：一个可用的 ChatGPT 账号或 OpenAI API key，一个本地能正常运行的开发环境，以及一个有 Git 管理的项目目录。官方文档说明，ChatGPT Plus、Pro、Business、Edu、Enterprise 等计划包含 Codex；第一次运行时可以用 ChatGPT 账号或 API key 登录，不过某些功能在 API key 登录下可能不可用。
账号：确认你能正常登录 ChatGPT，或已经准备好 OpenAI API key。
Git：项目最好已经初始化 Git，方便查看 diff、提交、回退。
依赖：Node.js、Python、包管理器、构建工具要尽量装齐，否则 Codex 会被环境问题拖住。
边界：不要把密钥、生产数据库、私有凭证随意暴露给测试任务；先从低风险仓库试手。
我建议新手先找一个“可坏掉也不心疼”的练习项目，比如个人工具、小 demo、旧脚本，或者新建一个临时仓库。第一次不要直接让 Codex 改生产核心模块。不是因为 Codex 不可靠，而是任何 coding agent 都需要通过你的项目结构、测试命令和团队约定来对齐工作方式。
03
安装方式一：桌面 App
如果你喜欢可视化界面，或者希望同时管理多个任务线程，建议先装 Codex App。官方文档把 App 称为 Codex 的 command center，它支持并行线程、内置 worktree、自动化、Git 功能、本地终端和预览能力。通俗说，它更像一个为 coding agent 准备的工作台。
App 安装步骤
1. 打开 OpenAI Codex App 官方页面。
2. 按你的系统下载 macOS 或 Windows 版本，Apple Silicon 和 Intel Mac 要选对应版本。
3. 安装后打开 App，用 ChatGPT 账号或 API key 登录。
4. 选择一个项目文件夹，确认让 Codex 在 Local 模式下工作。
5. 发出第一条任务，例如：“请阅读这个项目，概括目录结构和启动方式。”
App 的优势是清楚。你能看到线程、计划、文件改动、终端输出、Git diff 和任务总结，对初学者非常友好。尤其当你不确定 Codex 改了什么时，App 的 review 体验比纯终端更容易建立安全感。
04
安装方式二：CLI 命令行
如果你每天都在终端里工作，CLI 是最直接的入口。官方文档说明，Codex CLI 可以在 macOS、Windows、Linux 上使用；它会在你选择的目录里读取、修改、运行代码。CLI 的好处是轻、快、贴近工程习惯，也方便后续做自动化。
macOS / Linux 官方安装命令
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows 官方安装命令
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"也可以使用 npm 或 Homebrew
npm install -g @openai/codexbrew install --cask codex安装完成后，在终端里运行：
codex第一次运行会要求你登录。登录完成后，先不要急着让它改大项目，建议在项目根目录下问它：“请先只读这个项目，告诉我技术栈、主要目录、启动命令和测试命令，不要修改文件。”这能帮你确认它读到的是正确目录，也能让它先建立上下文。
小提醒：安装脚本不是越快越好
如果你在公司网络、代理环境、Windows PowerShell 执行策略、老版本 Node 或权限受限目录下安装，可能会遇到失败。先读清报错，再处理网络、权限或包管理器问题。不要反复复制多个来源不明的安装命令。
05
第一次使用：从“读项目”开始
很多人第一次用 coding agent，最容易犯的错误是直接丢一句“帮我优化一下项目”。这类任务太宽，目标不清，验证标准也不清，模型只能自己猜。更稳的做法是先让 Codex 了解环境，再逐步给它可验证的小任务。
图 3｜新手任务金字塔
推荐的第一条 prompt 是：
请先不要修改文件。请阅读当前项目，输出：1. 技术栈；2. 主要目录；3. 本地启动命令；4. 测试/构建/格式化命令；5. 你认为后续修改时需要注意的风险。
这条指令有两个作用。第一，防止它一上来就改文件；第二，让你快速判断它是否理解项目。接下来可以让它做更具体的任务，比如“修复这个测试失败”“给这个函数补边界测试”“把这个页面的空状态补齐”“帮我解释这段 SQL 为什么慢”。
一个稳定任务的四要素
目标：你希望最终变成什么样。
范围：哪些文件能改，哪些不能动。
约束：不能引入新依赖、不能改公共 API、要保持兼容等。
验证：跑哪个测试、构建或命令来证明完成。
06
权限与安全：让 Codex 在合适边界内工作
Codex 能运行命令和修改文件，所以权限不是小事。官方文档把本地默认权限描述为：Codex 可以在当前 workspace 中读写文件、运行常规本地命令；如果要使用互联网或越过 workspace 边界，会请求许可。这个默认状态适合大多数新手。
图 4｜权限模式怎么选
read-only
只读检查、代码解释、风险评估。
workspace-write
日常开发推荐，能改当前工作区。
danger-full-access
全访问，仅在你完全信任任务时使用。
新手建议：默认从 workspace-write 加 on-request 开始。也就是说，让 Codex 可以在当前项目中正常工作，但越界、联网或高风险命令要先问你。只有在临时实验、低风险目录、你明确知道后果时，再考虑 full access。不要为了省一个确认按钮，把生产电脑的边界全部放开。
安全底线
不要把生产密钥、客户隐私、未脱敏数据库直接交给 Codex 处理。
不要让它在你没看 diff 的情况下直接提交、推送、部署。
不要把“删除、覆盖、迁移、清库、批量改权限”这类任务交给它自动执行。
07
AGENTS.md：把团队约定写给 Codex
如果你只记住一个进阶技巧，那就是 AGENTS.md。官方文档说明，Codex 会在工作前读取 AGENTS.md，把它当成项目指导。你可以把仓库结构、运行命令、测试命令、编码规范、PR 要求、禁止事项写进去。这样每次开新会话，不必重复交代一遍。
一个简洁的 AGENTS.md 示例
# AGENTS.md## 项目说明- 本项目是一个 Next.js 应用，主要代码在 app/ 和 components/。- 修改 UI 前先查看已有组件和样式约定。## 常用命令- 安装依赖：pnpm install- 本地开发：pnpm dev- 类型检查：pnpm typecheck- 测试：pnpm test- 构建：pnpm build## 工作约定- 优先做小范围、高置信度修改。- 不要引入新依赖，除非先说明原因。- 修改完成后运行相关测试，并在最终回复里说明结果。- 不要修改 .env、密钥、生产配置。AGENTS.md 不要写成企业制度汇编。它越长越虚，效果越差。好的 AGENTS.md 应该短、准、可执行。比如“修改后运行 pnpm test”是好规则；“保持代码优雅、注重质量”就太空。官方最佳实践也建议，AGENTS.md 如果开始变大，可以把具体任务拆到单独文档里，再从主文件引用。
AGENTS.md 可以写什么
项目启动方式、测试方式、构建方式。
代码风格、组件目录、命名习惯。
哪些文件不能改，哪些依赖不能加。
完成标准：必须跑哪些检查，最终回复必须包含什么。
团队 review 偏好：优先指出风险，还是优先给改法。
08
日常工作流：让 Codex 稳定产出
真正好用的 Codex 工作流，不是“我一句话，它全自动做完”，而是“我给清晰目标，它探索、实现、验证，我审查、追问、合并”。把它当作一个靠谱但需要 review 的队友，你会更容易用出价值。
图 5｜推荐日常开发闭环
1. 建检查点：确认 Git 状态，必要时先 commit 或 stash。
2. 交代任务：说明目标、范围、约束、验证命令。
3. 让它实施：允许它读文件、修改、运行相关测试。
4. 看 diff：检查文件改动是否过大、是否偏题。
5. 要复盘：让它说明改了什么、为什么、验证结果如何。
6. 再提交：确认无误后由你决定 commit、push、开 PR。
一个好任务可以这样写：
请修复登录页在邮箱为空时仍然发送请求的问题。范围限制在 app/login 和相关测试文件，不要重构认证模块，不要引入新依赖。修改后运行对应测试；如果没有测试，请补一个最小测试。最后说明改动点和验证结果。
这个 prompt 的好处是边界清楚。Codex 知道目标是“空邮箱不发请求”，范围是登录页和测试，不要动认证模块，不要加依赖，完成后要运行测试。相比“帮我修一下登录页”，它更不容易偏航。
09
常用提示词模板：直接复制改字段
模板 1：陌生项目速读
请只读当前项目，不要改文件。请输出技术栈、目录结构、启动命令、测试命令、主要业务模块、潜在风险，以及你建议我下一步先看哪些文件。
模板 2：修复 bug
请修复 [现象]。复现路径是 [步骤]，期望结果是 [结果]。请先定位根因，再做最小修改。不要改无关文件。修改后运行 [测试命令]，并总结根因、改动和验证结果。
模板 3：补测试
请为 [函数/组件/接口] 补充测试，重点覆盖 [边界条件]。不要改变业务行为。测试风格请参考现有测试文件。完成后运行测试，并说明新增用例覆盖了什么。
模板 4：代码审查
请 review 当前未提交改动，优先找 bug、回归风险、安全问题、缺失测试。请按严重程度排序，给出文件和行号。没有问题就明确说没有发现高风险问题。
模板 5：渐进重构
请重构 [模块]，目标是 [目标]。保持外部 API 和现有行为不变，不要一次性大改。请先给计划，确认影响文件，再分步修改。每一步后运行相关检查。
提示词不是越长越好，而是越具体越好。你要尽量减少“它需要猜”的部分。范围、限制、完成标准写清楚，Codex 的表现会稳定很多。
10
进阶能力：Cloud、Skills、Plugins、MCP
当你已经熟悉本地使用，就可以逐步看进阶能力。Codex Cloud 适合把任务交给云端后台运行。官方 Quickstart 里提到，你可以打开 chatgpt.com/codex，设置 environment，连接 GitHub 仓库，启动任务，监控日志，完成后查看 diff 或创建 PR。它适合处理不需要你盯着终端的任务，比如修一批测试、探索架构、实现一个中等功能。
什么时候用 Cloud
任务可以在后台跑，不需要你实时插手。
你希望并行启动多个探索或修复任务。
你希望它完成后直接给 diff、分支或 PR。
你的仓库能在云端 environment 中正常安装依赖、构建、测试。
Skills 和 Plugins 则用于扩展 Codex。官方说明里，Skills 是可复用工作流的作者格式，可以把任务说明、资源和脚本打包起来；Plugins 是安装分发单元，可以把 skills、应用集成和 MCP 配置组合起来。简单理解：如果你发现自己总在重复一套流程，比如“生成公众号 HTML”“检查数据看板 SQL”“做 PR 审查”，就可以把它沉淀成 skill；如果要给团队安装和分发，再考虑 plugin。
MCP 可以让 Codex 接入更多工具和上下文，比如文档、数据库、浏览器、内部系统等。它很强，但也更需要权限治理。我的建议是：先把本地项目和 AGENTS.md 跑顺，再接 MCP；先接只读工具，再接能写入或触发外部动作的工具。
11
常见问题与排查
1. 安装后输入 codex，提示 command not found
通常是安装路径没有进入 PATH，或者终端会话没刷新。重开终端，检查安装日志，确认可执行文件所在目录。如果用 npm 安装，检查 npm 全局 bin 目录是否在 PATH 中。
2. Windows PowerShell 不让执行脚本
这类问题常见于 PowerShell 执行策略。官方 Windows 文档也提到，npm.ps1 或脚本可能因为策略被阻止。先确认你执行的是官方安装命令，再按公司安全规范调整执行策略。
3. Codex 改了很多无关文件
多半是任务范围太宽，或者没有约束“最小修改”。下一次要明确可改目录、不可改文件、不要重构、不要格式化全仓库。已经发生时，先看 Git diff，必要时只保留有价值的 patch。
4. 它跑不起来测试
先让它只做环境诊断：读取 package.json、README、CI 配置，找出正确命令。很多失败不是模型问题，而是项目依赖没装、环境变量缺失、Node/Python 版本不对。
5. 怎么判断任务完成了
不要只看它说“完成了”。要看 diff、测试结果、构建结果、运行截图、日志和边界条件。让 Codex 在最终回复里列出“改了什么、为什么、验证了什么、没验证什么”。
12
一套推荐的团队落地路径
个人用 Codex，重点是效率；团队用 Codex，重点是稳定性和一致性。不要一上来就要求所有人把大任务交给 AI。更好的路径是先从低风险、高重复、可验证的任务开始。
图 6｜团队落地四阶段
第 1 阶段：个人试用。修小 bug、解释代码、补测试、写脚本。
第 2 阶段：项目规范。补 AGENTS.md，整理测试命令和禁止事项。
第 3 阶段：协作审查。把 review、测试、PR 说明纳入固定流程。
第 4 阶段：自动化。用 Cloud、Skills、Plugins、MCP 支持更复杂任务。
团队最应该沉淀的，不是“提示词大全”，而是“可验证的工程约定”。比如：每个仓库必须有启动命令、测试命令、lint 命令；每次修改必须说明验证结果；涉及数据库迁移必须人工审批；涉及依赖升级必须列出影响。Codex 越清楚团队标准，越能像团队成员一样工作。
最后给新手的 7 条建议
1. 第一次先让 Codex 只读项目，不要急着改代码。
2. 每个任务都写清目标、范围、约束、验证方式。
3. 用 Git 做检查点，所有改动都看 diff。
4. 默认使用 workspace-write 和需要审批的模式。
5. 尽早写 AGENTS.md，但保持短、准、实用。
6. 让 Codex 跑测试，也让它说明没跑什么。
7. 把它当成需要 review 的同事，而不是全自动黑箱。
Codex 真正改变的，不只是“写代码快一点”。它改变的是开发工作的组织方式：过去你要在搜索、阅读、修改、运行、排错之间来回切换；现在可以把其中一部分交给 agent 连续完成。你要做的，是定义目标、把关边界、检查结果、沉淀规则。
当你第一次看到 Codex 读完项目、定位问题、修改文件、跑完测试、给出 diff 的时候，会很容易兴奋。但更重要的是第二次、第三次、第一百次，它是否仍然稳定。稳定来自清晰的项目结构、可执行的测试、明确的权限和持续更新的 AGENTS.md。把这些底座搭好，Codex 才会从“新鲜玩具”变成真正的生产力工具。
一句话总结：先让 Codex 在小范围里证明自己，再把规则写进项目，最后把可重复流程产品化。安装只是第一步，真正的分水岭在于你能否让它安全、稳定、可验证地参与工程交付。
参考资料（OpenAI 官方）
1. Codex Quickstart：https://developers.openai.com/codex/quickstart
2. Codex CLI：https://developers.openai.com/codex/cli
3. Codex App：https://developers.openai.com/codex/app
4. Sandboxing：https://developers.openai.com/codex/concepts/sandboxing
5. AGENTS.md：https://developers.openai.com/codex/guides/agents-md
6. Best practices：https://developers.openai.com/codex/learn/best-practices
