Codex 新手使用完整指南：从安装、登录到第一次让 AI 改代码

Codex 是 OpenAI 面向软件开发的编码代理，可以在本地终端、IDE、桌面 App 和云端环境中帮助开发者理解代码、修改文件、运行命令、审查差异和调试问题。根据 OpenAI Codex manual 2026 年 6 月 30 日抓取版本，Codex 当前覆盖 CLI、IDE extension、Codex app、Cloud tasks、worktrees、MCP、skills、AGENTS.md、web search、image input 和 code review 等能力；新手最稳的入门路径是先在一个 Git 仓库里用默认 workspace-write + on-request 权限运行小任务，再逐步启用 IDE、App、云端任务和自定义规则。不要一开始就给 Full Access，也不要让多个线程同时改同一批文件；Codex 的真正价值来自“清晰任务 + 可验证命令 + Git 审查”，而不是一次性把整套项目交给它自由发挥。

---

Codex 是什么？

Codex 是 OpenAI 的软件开发编码代理，能够阅读代码库、生成代码、修改文件、运行测试、解释逻辑、审查代码并协助调试。

与普通聊天机器人不同，Codex 会围绕一个线程持续工作：它读取项目上下文，制定计划，执行文件编辑和命令，遇到越权操作时向用户请求批准，最后给出修改摘要和验证结果。

对新手来说，可以先把 Codex 理解成四个入口：

入口	适合场景	新手建议
Codex CLI	终端里解释代码、改文件、跑测试	最适合程序员入门
IDE extension	VS Code、Cursor、Windsurf 等编辑器内使用	适合边看代码边提问
Codex app	桌面端多线程、worktree、浏览器预览、Git diff	适合更完整的项目工作流
Codex cloud	远程环境中并行处理任务	适合已有 GitHub 仓库和云环境的团队

OpenAI manual 明确说明，ChatGPT Plus、Pro、Business、Edu 和 Enterprise 计划包含 Codex；CLI 和 IDE extension 支持 ChatGPT 登录与 API key 登录，Codex cloud 需要 ChatGPT 登录。

第一步：安装 Codex CLI

Codex CLI 是最适合新手理解 Codex 工作方式的入口，因为你能看到它读了哪些文件、运行了哪些命令、改了哪些 diff。

macOS / Linux 可使用官方安装脚本：

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

Windows PowerShell 可使用官方安装脚本：

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

安装后检查命令是否可用：

codex doctor

如果你在 Windows 上开发，官方文档建议可以原生在 PowerShell 中运行，也可以在需要 Linux 原生工具链时使用 WSL2。

第二步：登录方式怎么选？

新手优先使用 ChatGPT 登录；自动化、CI/CD 或脚本场景再考虑 API key。

登录方式	适合场景	注意事项
ChatGPT 登录	日常本地开发、IDE、App、云端任务	使用 ChatGPT 计划内的 Codex 权益和工作区策略
API key 登录	CI/CD、脚本、私有自动化	按 OpenAI Platform API 计费，部分 ChatGPT 工作区能力不可用
Access token	企业可信自动化	面向 Enterprise 受控场景，不是普通 API 调用替代品

登录命令：

codex login

远程或无浏览器环境可以使用设备码登录：

codex login --device-auth

OpenAI manual 提醒：Codex 会缓存登录凭据，文件型缓存可能位于 ~/.codex/auth.json，应像密码一样保护，不能提交到仓库或粘贴到聊天里。

第三步：第一次任务怎么做？

第一次使用 Codex，不要让它“重构整个项目”，而是让它做一个可验证的小任务。

推荐流程：

1. 进入一个 Git 仓库。
2. 运行 git status，确认工作区是否干净。
3. 启动 Codex。
4. 让它先解释项目结构。
5. 再给一个小修改任务。
6. 要求它运行测试或 lint。
7. 用 Git diff 审查结果。

示例：

cd /path/to/your/repo
codex

进入交互界面后，可以这样问：

先阅读这个仓库，解释主要目录、启动命令和测试命令。不要修改文件。

确认它理解项目后，再给小任务：

给登录表单增加邮箱格式校验，并运行相关测试。修改后总结变更文件和验证结果。

如果只想快速问一次，也可以直接传入 prompt：

codex "解释这个代码库的主要模块，不要修改文件"

第四步：权限和沙箱怎么理解？

Codex 的安全边界由 sandbox mode 和 approval policy 两层组成：sandbox 决定它技术上能做什么，approval policy 决定什么时候必须停下来问你。

新手建议使用默认低风险组合：

codex --sandbox workspace-write --ask-for-approval on-request

三种常见权限模式：

模式	能做什么	适合场景
Read-only	读文件、解释代码，不主动修改	了解陌生项目、审查思路
Auto / workspace-write	在当前工作区读写和运行常规命令，越界时请求批准	日常开发首选
Full Access / danger-full-access	取消大部分边界，含更广文件和网络访问	只在可信环境和明确任务中短暂使用

官方文档说明，Codex 默认关闭命令级网络访问，本地工作默认限制在当前 workspace 内；当需要访问网络或写出工作区时，它会通过 approval flow 请求批准。

第五步：CLI、IDE、App 应该怎么选？

新手可以按“先 CLI，后 IDE，再 App”的顺序上手。

CLI：最适合理解 Codex 的工作循环

CLI 适合这些任务：

• 解释陌生代码库
• 修改小 bug
• 跑测试和 lint
• 做本地 code review
• 用 codex exec 写自动化脚本

常用命令：

codex
codex "解释这个项目"
codex resume --last
codex exec "修复 CI 失败并总结原因"
codex completion zsh

在 CLI 里可以用 /permissions 切换权限，用 /model 切换模型，用 /review 做本地代码审查，用 /status 查看线程状态和上下文。

IDE extension：最适合边看代码边让 Codex 改

Codex IDE extension 可在 VS Code、Cursor、Windsurf 和 VS Code-compatible 编辑器中使用。它会利用打开文件和选中代码作为上下文，因此你可以写更短的 prompt。

示例：

参考 @example.tsx 的写法，在 @resources.ts 中新增一个资源列表页面。

IDE 中适合使用：

• 选中一段代码问“这里为什么会报错？”
• 让 Codex 完成 TODO
• 在当前文件基础上补测试
• 把云端任务应用回本地继续测试

Codex app：最适合完整项目工作流

Codex app 是桌面端体验，适合同时管理多个项目、线程和 worktree。它内置 Git diff、集成终端、浏览器预览、worktree、自动化和文件预览。

新手可以先用 Local 模式；当想让 Codex 独立尝试方案、不影响当前工作区时，再使用 Worktree。

第六步：模型怎么选？

OpenAI manual 建议，大多数 Codex 任务从 gpt-5.5 开始；轻量任务或子代理可考虑 gpt-5.4-mini；ChatGPT Pro 用户可在研究预览中使用 gpt-5.3-codex-spark 做更快的实时编码迭代。

设置默认模型：

# ~/.codex/config.toml
model = "gpt-5.5"

临时指定模型：

codex --model gpt-5.5

如果你是新手，不需要一开始频繁换模型。更重要的是把任务说清楚，并要求 Codex 验证结果。

第七步：怎么写高质量 prompt？

Codex 的 prompt 应该包含“目标、范围、约束、验证方式”四件事。

弱 prompt：

帮我优化一下项目。

强 prompt：

请只修改登录页面相关文件，修复邮箱格式校验缺失的问题。不要新增依赖。修改后运行登录表单相关测试，如果没有专门测试，请运行最接近的测试命令，并总结验证结果。

更适合 Codex 的表达方式：

• “先解释，不要修改文件。”
• “只改这 3 个文件。”
• “不要新增依赖。”
• “如果测试失败，先分析原因，不要盲目改。”
• “修改后运行 npm test 和 npm run lint。”
• “最后列出变更文件、验证命令和未完成风险。”

OpenAI manual 也强调：Codex 在能验证工作的情况下输出质量更高；复杂任务应拆成更小、更聚焦的步骤。

第八步：AGENTS.md、skills、MCP 什么时候用？

新手先用 prompt；当规则重复出现时，再把它沉淀到 AGENTS.md、skills 或 MCP。

机制	适合放什么	新手使用时机
AGENTS.md	项目约定、测试命令、目录规则、PR 要求	Codex 经常忘记同一条规则时
skills	可复用工作流、发布流程、内容生成流程	同类任务重复做很多次时
MCP	GitHub、Figma、文档、浏览器、内部系统等外部工具	Codex 需要访问本地仓库之外的系统时

最简单的 AGENTS.md：

# AGENTS.md

## Repository expectations

- 修改 JavaScript 或 TypeScript 文件后运行 `npm test`。
- 不要在未确认前新增生产依赖。
- 提交前总结修改文件、测试命令和剩余风险。

把它放在仓库根目录后，Codex 每次从该仓库启动都会读取。目录更深处的 AGENTS.md 或 AGENTS.override.md 可以覆盖上层规则。

新手常见问题

Q：Codex 会不会自动改坏我的代码？
有可能，所以新手应在 Git 仓库中使用，保持小步提交，用 git diff 审查结果。默认 workspace-write 模式会限制 Codex 的写入范围，越界操作需要批准。

Q：Codex CLI、IDE extension、Codex app 有什么区别？
CLI 适合终端工作流，IDE extension 适合边看代码边编辑，Codex app 适合多项目、多线程、worktree、浏览器预览和 Git diff。它们共享很多底层配置，但入口体验不同。

Q：我应该一开始就开 Full Access 吗？
不建议。Full Access 会扩大文件和网络访问边界，适合可信环境里的明确任务。新手使用 Auto / workspace-write 更稳。

Q：Codex 可以联网吗？
Codex 有 web search 工具；但本地命令级网络访问默认关闭，需要配置或批准。即使开启 web search，也要把网页内容视为不可信输入。

Q：Codex 适合做整个项目从零开发吗？
可以辅助，但新手不要一次性给过大的目标。更稳的做法是先让 Codex 搭骨架，再分步骤做页面、接口、测试、修复和代码审查。

参考资料与延伸阅读

• OpenAI Codex Overview：https://developers.openai.com/codex/overview
• Codex Quickstart：https://developers.openai.com/codex/quickstart
• Model Context Protocol：https://developers.openai.com/codex/mcp

时效性说明

本文基于 2026 年 6 月 30 日抓取的 OpenAI Codex manual 和官方文档整理。Codex 的模型、权限、云端任务、App/IDE 功能和安装方式更新较快，正式部署到团队流程前应再次核对 OpenAI 官方文档。