Codex 安装、配置与第一次运行
约 1744 字大约 6 分钟
2026-05-25
Codex 的关键不是安装成功，而是理解它如何读取项目、执行命令、展示 diff，并在权限边界内工作。本文事实口径核对时间：2026-05-25；具体安装入口、账号、额度和平台支持以 OpenAI 官方文档为准。
Codex 定位
Codex 是 AI Coding Agent。它可以读项目、修改文件、运行命令、协助调试，也能在桌面 App、CLI、IDE 或云端入口中承接任务。它不是普通聊天窗口：你给它的不是一个“问题”，而是一个需要在项目里执行并验证的任务。
OpenAI 官方介绍中，Codex App 被描述为面向多 Agent 并行和长期任务协作的命令中心；CLI 则是运行在终端里的本地 coding agent。OpenAI Help Center 对 Codex 的概括也很直接：它是一个帮助你 write, review, and ship code 的 AI agent。
使用前准备
| 准备项 | 为什么需要 |
|---|---|
| ChatGPT / OpenAI 账号 | 登录和使用 Codex 的基础 |
| Git | 查看修改、保护工作区、提交结果 |
| Node.js | Codex CLI 和前端项目常见依赖 |
| 可实验项目目录 | 第一次练权限、diff 和命令，不碰生产仓库 |
第一次安全边界
不要第一次就在重要生产仓库中尝试。不要随便允许删除文件、重置 Git、全局安装依赖、上传密钥、访问生产服务或修改部署配置。
官方入口
| 入口 | 适合谁 | 官方地址 / 安装方式 |
|---|---|---|
| 桌面 App | 想管理多个线程、项目和长任务的人 | Codex 页面；官方当前说明 macOS 和 Windows 可用 |
| CLI | 习惯终端、想轻量进入项目的人 | npm install -g @openai/codex 或 brew install codex；参考 npm 包页面 |
| IDE Extension | 想在编辑器里直接委派任务的人 | 参考 OpenAI Help Center 中的 Codex IDE extension 入口 |
| Codex Web | 想把任务委托到云端处理的人 | chatgpt.com/codex；需要连接 ChatGPT 账号，部分场景还需要 GitHub 连接 |
npm install -g @openai/codex
codex如果你不确定自己该用哪一种，第一次建议在 桌面 App 和 CLI 里二选一：
- 想看得更清楚：先用 App。
- 想直接贴着项目干活：先用 CLI。
不要第一次同时折腾多个入口。能稳定读项目、看 diff、跑安全任务，比装齐所有入口更重要。
界面重点
第一次打开 Codex，不急着让它写代码。先看懂下面四个对象：
项目目录：它决定 Codex 当前能读哪些文件、改哪些文件。线程：每个任务是单独上下文，不是所有历史都混在一起。命令执行：你要知道它跑了什么、为什么跑、输出是什么。diff：这是你判断“改动范围是否可接受”的主入口。
第一次运行
第一次进入项目后，按这个顺序走会更稳：
- 打开一个可实验项目，不要先碰生产仓库。
- 让 Codex 只读项目结构，不要立即写文件。
- 让它解释如何启动项目，不要先安装依赖。
- 让它检查 README、
package.json、配置文件是否一致。 - 最后才允许它做单文件、小范围修改。
第一次运行你至少要确认五件事：
- 它是否在正确项目目录里。
- 它是否能读到 README、
package.json、配置文件和源码目录。 - 它准备执行哪些命令。
- 它准备修改哪些文件。
- diff 是否小、清楚、符合你的目标。
第一个安全任务组
可以直接使用这些任务练习：
请阅读项目结构并总结技术栈，不要修改文件。请告诉我如何启动项目，不要执行安装命令。请检查 README 中的启动命令是否和 package.json 一致。如需修改，请先解释差异，不要直接改文件。请只修改一个文件，修复一个最小问题。修改前先列计划，修改后展示 diff，并告诉我如何验证。这几类任务的顺序不要反过来。先只读、再解释、再校验、最后才做最小修改。这样你能先看懂 Codex 的读取、分析和说明能力，再逐步建立对写文件和跑命令的信任。
权限和安全边界
| 操作 | 初学阶段建议 |
|---|---|
| 删除文件、批量移动目录 | 先让 Codex 解释影响，再看 diff |
git reset、强制推送 | 不授权，除非你完全知道后果 |
| 全局安装依赖 | 优先项目内依赖，避免污染系统 |
| 访问网络或上传内容 | 先确认是否包含密钥、私有代码或个人信息 |
| 修改配置、部署、CI | 让 Codex 给风险清单和回滚方案 |
如果你看不懂权限弹窗，默认做法应该是：先拒绝，然后让 Codex 用中文解释它打算执行什么、影响什么、为什么需要这个权限。第一次使用时，拒绝不确定操作 比 快速通过任务 更重要。
常见问题
| 问题 | 排查方向 |
|---|---|
找不到 codex 命令 | 检查 Node.js、npm 全局路径和安装是否成功 |
| 登录失败 | 以官方账号、地区、订阅和网络说明为准 |
| 项目依赖装不上 | 先让 Codex 解释依赖管理器、Node 版本和报错原因 |
| 权限弹窗看不懂 | 不确定就拒绝，要求 Codex 用中文解释会做什么 |
| AI 修改范围太大 | 中断任务，要求缩小到单文件或单模块，并先列计划 |
读完这篇后，你应该已经能做到三件事：
- 知道从 App、CLI、IDE、Web 里先选哪个入口。
- 知道第一次进入项目时该先看什么，而不是马上让 Codex 写代码。
- 知道如何用只读任务、小改动任务和 diff 审查来建立安全边界。
