Codex 是什么
Codex 是 OpenAI 做的编程智能体（coding agent）。你用自然语言交代一个开发任务，它会自己去读项目里的文件、想好怎么改、动手改代码、运行命令验证，直到任务完成或者需要你拍板。它的开源部分（Codex CLI）托管在 github.com/openai/codex，用 Rust 编写。
这一页回答几个入门问题：Codex 能做什么、有哪几种用法、和你已经用过的 AI 工具有什么不同、你适不适合用它，以及这套教程该怎么读。
一句话理解：它在你的项目里干活
聊天网页里的 AI 只能看到你贴给它的那几段代码，给出的答案要你自己复制回编辑器、自己运行、自己发现哪里不对再回去问。Codex 不一样，它直接在你的项目文件夹里工作：
- 需要了解代码时，它自己打开文件、搜索关键字、看目录结构；
- 需要改代码时，它直接写入文件，改完给你看 diff；
- 需要验证时，它运行测试、编译、lint，看输出再决定下一步；
- 遇到权限边界（比如要联网、要改工作区外的文件），它停下来问你。
这种「读 → 想 → 改 → 跑 → 看结果 → 再改」的循环，就是常说的 Agent 循环，细节见 核心概念。
它能替你做什么
| 任务类型 | 典型说法 | Codex 实际会做的事 |
|---|---|---|
| 读懂陌生项目 | 「这个仓库的登录流程是怎么走的？」 | 搜索路由、中间件、服务层代码，按调用顺序讲给你 |
| 写新功能 | 「给订单列表加按日期筛选」 | 找到列表接口和页面，改后端查询和前端表单，补测试 |
| 修 bug | 「运行 npm test 有两个用例失败，修好它」 | 先跑测试复现，读报错定位，改代码后再跑一遍确认 |
| 代码审查 | /review | 对比当前改动，按严重程度列出问题和建议 |
| 重构与迁移 | 「把这些回调改成 async/await」 | 批量修改，同时保持测试通过 |
| 杂活 | 「写个脚本把 CSV 转成 JSON」「补一份 README」 | 写文件、试运行、把用法告诉你 |
它最擅长的是边界清楚、可以验证的任务。「把网站做得高级一点」这种说法它也会尽力，但效果远不如「把首页按钮改成圆角 8px，主色用 #2563eb，改完截图给我看」。怎么把任务说清楚，见 提示词最佳实践。
它不会替你承担判断
Codex 能写出能跑的代码，但「这个需求该不该做」「这个架构三年后撑不撑得住」「这次改动会不会影响线上用户」仍然需要你来判断。把它当成一个手很快、需要你审稿的同事，而不是可以撒手不管的外包。
几种形态
Codex 不是单一的一个软件，而是同一个智能体的几种入口：
| 形态 | 在哪里用 | 适合场景 |
|---|---|---|
| Codex CLI | 终端里运行 codex | 喜欢命令行、远程服务器上开发、脚本和 CI 自动化 |
| IDE 扩展 | VS Code、Cursor、Windsurf 等编辑器的侧边栏 | 边看代码边对话，选中代码直接提问 |
| 桌面应用 | 2026 年 7 月 10 日之后并入 ChatGPT 桌面端，在其中以 Codex 模式使用 | 图形界面、多个项目和任务并行、看 diff 更直观 |
| 云端（Codex Web） | chatgpt.com/codex | 把任务交给云端容器跑，关掉电脑也不影响，适合并行处理多个任务 |
| GitHub 集成 | 在 PR 里 @Codex 或开启自动审查 | 让它审 PR、按评论修改 |
前三种在你的电脑上运行，读写的是本地文件；云端形态在 OpenAI 的隔离容器里克隆你的仓库运行，结果以 diff 或 PR 的形式交回来。各形态的细节分别在 桌面应用与界面、IDE 扩展、云端任务与 GitHub 里讲。
在 CLI 里运行 codex app 可以直接打开桌面端（没装会引导你去安装），会话里的 /app 命令能把当前会话转到桌面端继续。
本地形态共用一份配置
CLI、IDE 扩展、桌面端在本机共用 ~/.codex 目录（Windows 是 %USERPROFILE%\.codex）：
~/.codex/
├── config.toml # 模型、提供方、沙箱、MCP 等配置
├── auth.json # 登录凭据或 API Key
├── AGENTS.md # 对所有项目生效的个人习惯
└── sessions/ # 会话记录，可以恢复这意味着你只要配置一次——比如按 接入 HiveGPT 写好 config.toml 和 auth.json——三种本地形态都能用上同一个模型和同一套习惯。目录里各文件的完整说明见 安装与登录。
和其他 AI 编程工具的区别
市面上的 AI 编程工具大致可以分成三类：
| 对比项 | 代码补全（Copilot 早期形态等） | 聊天网页 | 编程智能体（Codex） |
|---|---|---|---|
| 交互方式 | 你敲代码，它猜下一行 | 你提问，它回答 | 你给目标，它执行到完成 |
| 能看到的范围 | 当前文件附近 | 你贴进去的内容 | 整个工作目录，可主动搜索 |
| 能不能改文件 | 只能插入建议 | 不能 | 能，直接写入 |
| 能不能运行命令 | 不能 | 不能（少数有代码沙箱） | 能，在沙箱里运行 |
| 怎么验证结果 | 靠你 | 靠你 | 它自己跑测试，你再审 |
| 适合粒度 | 一行到一个函数 | 一个问题 | 一个完整任务 |
三者不是替代关系。写代码时开着补全，查概念时问聊天，有成块的活交给 Codex，这是很多人的日常组合。
还有一个常被忽略的区别：智能体会产生真实的副作用。它运行的命令真的会执行，删掉的文件真的会消失。所以 Codex 默认带沙箱和审批机制，把能做的事限制在工作目录内、联网前先问你。别急着关掉这些保护，先读 沙箱与审批。
适合谁
- 有一点编程基础的开发者：能看懂代码、会用终端和 Git，用 Codex 收益最大，因为你能审得动它的改动。
- 零基础想做点东西的人：也能用，但建议配合本站的 C 路线 一步步来，至少学会看 diff 和用 Git 回退。
- 独立开发者和小团队：把 CRUD、测试、脚手架、文档这些重复劳动交出去，自己专注在业务判断上。
- 接手老项目的人：先让它通读代码、画出模块关系、解释关键流程，上手速度会快很多。
不太适合的情况：你完全不打算看它改了什么；任务依赖大量只存在于你脑子里或内部系统里的知识，又不打算告诉它；直接在生产服务器上让它随意执行命令。
用 Codex 要花什么
Codex 本身（CLI 和 IDE 扩展）免费下载，花钱的是背后的模型调用。常见的三种方式：
- ChatGPT 账号登录：使用 ChatGPT 套餐里包含的 Codex 额度，各套餐具体额度以 OpenAI 官方说明 为准。
- OpenAI API Key：按 API 用量计费。
- 兼容的第三方接口：比如本站的 HiveGPT，国内网络可直接访问，按量从余额扣费；也可以接 DeepSeek 等其他模型。
本教程怎么读
教程按左侧边栏分成五个板块，从上往下读是最顺的路线：
| 板块 | 内容 | 建议 |
|---|---|---|
| 开始 | 是什么、核心概念、安装登录、接入模型、第一个任务 | 新手必读，读完就能干活 |
| 使用形态 | 桌面应用、IDE 扩展、云端与 GitHub、Windows | 挑你用的形态读 |
| CLI 详解 | 斜杠命令、命令行参数、config.toml、沙箱、模型 | 用熟以后当手册查 |
| 进阶 | 提示词、AGENTS.md、Skills、MCP、子代理、钩子、电脑操控 | 想让 Codex 更懂你的项目时读 |
| 实战 | 非交互与 CI、Worktree 并行、工作流、安全、速查表、排错 | 团队落地和遇到问题时读 |
如果你只有半小时：读 核心概念 → 安装与登录 → 接入 HiveGPT → 第一个任务，就能独立完成一个小改动。
版本说明
Codex 更新很快，命令和配置项会变。本教程以 2026 年 10 月的 Codex CLI 0.142 版和开源仓库为准。遇到对不上的地方，运行 codex --help、在会话里输入 / 看当前版本的实际列表，或者查 官方文档。
小结
- Codex 是在你的项目里自主读代码、改代码、跑命令的编程智能体，不只是回答问题。
- 它有 CLI、IDE 扩展、桌面端（已并入 ChatGPT 桌面端）、云端和 GitHub 几种入口，本地形态共用
~/.codex配置。 - 和补全、聊天工具相比，它能完成整块任务并自我验证，但也会产生真实副作用，所以有沙箱和审批。
- 模型可以来自 ChatGPT 账号、OpenAI API Key，或 HiveGPT、DeepSeek 等兼容接口。
下一步：核心概念