如何安装 Codex：CLI、桌面端与 IDE 的完整教程（2026）
发布与内容核验：2026 年 10 月 24 日 · GrokMirror 编辑组（独立教程，非 OpenAI 官方）
搜索“如何安装 Codex”的人，通常会遇到三个选择：在终端安装 Codex CLI，安装带图形界面的 Codex 桌面端，或者在 VS Code、Cursor 等编辑器里使用 Codex。三种方式解决的是同一个问题，但准备条件、工作习惯和适用场景不同。本文按照实际安装顺序，讲清楚如何选择入口、检查环境、完成登录、运行第一个任务，以及安装失败后怎样排查。
Codex 的版本、系统支持、账户权限和套餐规则会更新。本文给出通用方法，命令和可用功能以 OpenAI 官方文档、产品页面和你本机的 codex --help 为准。不要把第三方博客里的旧版本截图当成当前界面，也不要把 OpenAI API 的 openai 命令与 Codex CLI 的 codex 命令混为一谈。
先选择安装方式
| 方式 | 适合谁 | 优点 | 需要注意 |
|---|---|---|---|
| Codex CLI | 熟悉终端的开发者 | 轻量、可脚本化、适合 Git 项目 | 需要理解目录、权限和命令 |
| Codex 桌面端 | 初学者、希望查看文件和终端的人 | 有图形界面，便于管理项目和审查改动 | 需安装对应系统应用 |
| IDE 扩展 | 日常在编辑器里写代码的人 | 可在当前文件和项目上下文中工作 | 依赖编辑器版本和扩展支持 |
| 云端 Codex | 有明确 Issue 和验收标准的团队 | 适合异步任务和代码审查 | 受账户、组织和 rollout 条件影响 |
第一次使用建议从桌面端或 CLI 二选一，不要同时安装多个来源不明的封装工具。若你的目标是让 Codex 修改本地仓库、运行测试和查看 Git diff，CLI 或桌面端更直接；若只想在写代码时询问当前文件，IDE 扩展更顺手。
安装前检查
先确认电脑和项目环境：
bash
node --version
git --versionCodex CLI 的官方安装方式会随版本更新。当前官方快速入门页面给出的常见方式是通过 npm 安装 @openai/codex，然后运行 codex。如果你的项目使用 nvm、fnm、Homebrew 或其他 Node 版本管理工具，先确认当前终端里的 node、npm 和全局包路径来自同一个环境。
安装前还要做三件事：第一，确认工作区没有未保存的重要修改；第二，准备一个没有密钥和客户资料的练习项目；第三，确保终端可以访问 npm 或官方安装页面。安装工具不等于授权它读取所有文件，项目权限和数据边界仍需要你自己控制。
方式一：安装 Codex CLI
1. 使用 npm 安装
在终端运行官方文档提供的安装命令：
bash
npm install -g @openai/codex@latest安装完成后检查命令是否可用：
bash
codex --version
codex --help如果你希望锁定某个版本以便团队复现，可以把 latest 换成经过测试的具体版本号。锁版本时要在项目文档中写清原因和升级计划；不要一边锁旧版本，一边在文章里声称使用的是最新版。
2. 启动并登录
在项目目录运行：
bash
cd your-project
codex首次启动会进入登录或授权流程。按照终端显示的官方页面完成登录，不要把访问令牌、浏览器回调地址、终端截图或账号信息提交到 Git 仓库。登录完成后，先发一个只读请求：
请读取当前目录的 README 和 package.json，说明项目用途、可用脚本和建议的测试命令。不要修改任何文件。
如果 Codex 能正确复述项目，再让它完成一个很小的可回滚任务。这样可以同时验证登录、工作目录、文件权限和基本通信是否正常。
3. 更新和卸载
如果 CLI 提示有新版本，优先使用官方文档说明的升级方法，或重新执行经过确认的安装命令。升级后再次运行 codex --version。不要在多个 Node 全局目录里重复安装同一个包，否则可能出现“终端显示的版本”和“实际执行的版本”不一致。
需要卸载时，使用与你安装方式相匹配的包管理器检查全局包，再删除对应包。卸载前先保存项目规则和提示词；它们属于项目资产，不应随着 CLI 一起丢失。
方式二：安装 Codex 桌面端
Codex 也可以通过 ChatGPT 桌面应用中的 Codex 视图使用。桌面端适合希望在一个窗口里查看项目、对话、终端和变更的人。安装前到 OpenAI 官方产品或帮助中心确认当前提供的系统版本和下载入口，不要从搜索结果中的破解包、共享安装器或来路不明的镜像下载。
安装完成后，打开应用并登录 ChatGPT 账户，在应用中进入 Codex 视图，选择一个本地项目或工作区，再发送第一个只读任务。桌面端和 CLI 的工作原则一致：先读项目，再制定计划；先做小改动，再运行测试；最后审查 diff 和权限影响。桌面端能隐藏一部分终端细节，因此更要关注它准备修改的文件和运行的命令。
桌面端的可用功能可能与账户、系统版本、组织设置和产品 rollout 有关。看不到 Codex 不一定是安装失败，也可能是账户或版本尚未开放。先更新到官方支持的应用版本，再查看帮助中心的可用性说明。
方式三：在 IDE 中使用 Codex
如果你主要在 VS Code、Cursor 或其他支持的编辑器里工作，可以按照编辑器和 OpenAI 官方文档的安装说明添加 Codex 扩展。扩展安装后通常需要登录或连接到已有账户，再选择当前项目目录。第一次使用时同样从只读任务开始：让它解释当前文件、依赖关系和测试方法，不要马上重构整个项目。
IDE 扩展的优势是能看到当前文件和上下文，但它也更容易让人误以为“打开一行代码就理解了整个系统”。涉及路由、数据库、构建脚本或权限配置的任务，仍要让 Codex 读取项目级规则、README 和相关测试。不要只根据编辑器侧边栏里的简短总结判断任务完成。
安装后必须做的首次验证
| 验证项目 | 操作 | 通过标准 |
|---|---|---|
| 版本 | codex --version | 能输出版本且与预期一致 |
| 帮助 | codex --help | 能看到当前可用入口或参数 |
| 目录 | 在练习仓库启动 Codex | 读取的是目标项目，不是错误目录 |
| 只读任务 | 要求解释 README 和脚本 | 不修改文件，说明准确 |
| 小改动 | 修改一处文档或测试 | diff 清晰，能回滚 |
| 构建 | 运行项目已有命令 | 结果有真实终端输出 |
验证时不要只看 Codex 的自然语言回答。用 git status、git diff 和项目本身的测试命令确认结果。对于文档站点，还要检查图片路径、内部链接、页面标题和构建输出。
常见安装问题
找不到 codex 命令
先运行 which codex 或系统对应的命令，确认当前 shell 能看到全局安装目录。检查 Node 版本管理工具是否切换了环境，再重新打开终端。不要在未确认目录的情况下连续执行多个管理员命令。
npm 权限错误
优先修复 Node 和 npm 的用户级安装环境，避免把全局目录改成任何用户都可写。使用 nvm、fnm 或 Homebrew 时，按照对应工具的官方权限方式处理。将安装目录粗暴改成系统路径，可能导致后续升级和卸载更复杂。
登录页面打不开
确认网络、系统浏览器和终端提示的授权地址。不要把账号密码粘贴进终端，也不要使用陌生网站提供的“代登录”脚本。登录完成后检查 Codex 是否返回本地终端；若没有，记录完整错误和版本，再查看官方帮助中心。
安装后版本仍然旧
使用 which codex 找到实际执行路径，并检查是否存在多个 Node 全局包目录。卸载旧版本前先记录当前路径和版本，避免误删其他项目依赖。重新安装后关闭并打开终端，再次核对版本。
桌面端看不到 Codex
确认应用版本、账户、地区或组织设置是否满足当前产品条件。帮助中心说明，Codex 的可用入口和云端能力会按账户与 rollout 情况变化；桌面端、CLI 和云端并不代表完全相同的资格条件。
安装后的安全设置
不要把 API key、SSH 私钥、.env 文件、生产数据库连接串和客户资料放进 Codex 可读取的练习目录。使用 .gitignore 和环境变量保护本地配置，但也要检查日志、截图和提交记录是否意外包含敏感信息。涉及删除、部署、付款、数据库迁移或推送远程仓库的命令，要求 Codex 先解释影响，再由你明确执行。
在正式项目中创建 AGENTS.md，写清安装、测试、构建、允许修改的目录、禁止触碰的文件和完成条件。规则文件不能替代权限控制，但能减少误解。任务完成后查看 git diff，确认没有把缓存、构建产物或临时日志提交进去。
安装完成后的第一个项目设置
安装成功只是起点。进入真实项目前，先确认项目根目录、当前 Git 分支和工作区状态。让 Codex 读取 README、依赖文件、测试脚本和已有的 AGENTS.md，再要求它用三句话复述任务边界。若复述中出现不存在的框架、目录或命令，先纠正上下文，不要继续写文件。
对于内容站，可以先让 Codex 完成一项低风险工作，例如检查文章图片是否存在、统计页面标题或找出失效内链。对于代码仓库，可以先让它解释一个测试文件或补充一条文档。第一项任务的目的，是验证安装、登录、目录权限和项目规则都工作正常，而不是尽快完成复杂功能。
当你确认环境可靠后，再进行代码修改或文章生成。每次任务结束都查看 git status 和 git diff，并把测试命令和结果写进提交说明。这样未来升级 Codex 或切换电脑时，可以快速判断问题来自工具、项目配置还是具体任务。
FAQ：如何安装 Codex
Codex CLI 的安装命令是什么？
官方快速入门页面提供通过 npm 安装 @openai/codex 的方式，常见命令是 npm install -g @openai/codex@latest。安装后运行 codex --version 和 codex --help 验证。具体命令以当前官方文档为准。
不会写代码可以安装 Codex 吗？
可以安装并完成基础体验，但使用本地项目时仍需要理解文件、目录、终端和版本控制。建议先使用练习仓库，不要直接让它操作生产项目。
Codex CLI 和 OpenAI CLI 是同一个东西吗？
不是。Codex CLI 使用 codex 命令，面向软件开发 agent；OpenAI CLI 使用 openai 命令，面向 API 调用。安装前先确认你需要的是哪一个工具。
Codex 支持哪些系统？
系统支持会随 CLI 和桌面端版本变化。安装前查看 OpenAI 官方文档和下载页面，按你的系统选择对应方式，不要完全依据旧文章里的平台列表。
安装 Codex 需要 API key 吗？
取决于你使用的入口和功能。Codex CLI 的登录流程与 OpenAI API CLI 的 OPENAI_API_KEY 配置不是一回事；不要因为看到 API 教程就把密钥直接写进 Codex 项目。
安装失败应该把什么信息提供给 Codex？
提供操作系统、Node 和 npm 版本、完整错误、执行过的命令、which codex 结果以及是否使用了版本管理器。先删除密钥、邮箱和内部路径，再分享日志。