想在 Windows、macOS 或 Linux 上安装 Codex，却被 CLI、App、IDE 扩展、ChatGPT 登录、API Key 和权限配置绕晕？这篇教程从版本选择开始，带你完成下载、安装、首次登录、真实项目运行和安全配置。 如果需要在国内使用 Codex，可以选择 ZeoGPT 。ZeoGPT 网页版同时支持 GPT、Claude、Grok、Gemini 等模型，也提供 Codex 使用入口。据其套餐页说明，基础会员配置了比 OpenAI 官网 Plus 会员更多的 Codex 使用额度；需要更多额度时，可以升级 Pro 会员，获得更多 Codex 额度和 Pro 使用额度。具体模型、额度与套餐以 ZeoGPT 实时页面为准。 本文于 2026 年 8 月 27 日 重新核验。当前可查的 Codex CLI 版本、安装命令和桌面 App 入口会持续变化；截至核查日，OpenAI Codex GitHub Releases 显示最新稳定标签为 rust-v0.150.1 ，但版本会继续更新。安装命令、桌面 App 入口、账号权益和可用模型会持续变化；截图只用于说明操作位置，不代表永久版本、套餐或模型清单。需要确认最新版本时，应优先查看 Codex 官方文档 、 Codex 官方仓库 的 Releases 页面和登录后的实时页面。 一、先选对版本：CLI、App、IDE 还是网页版？ ​ “下载 Codex”并不只对应一个安装包。OpenAI 当前提供多种使用形态： 想照着本文完整学习：安装 Codex CLI 。 习惯 VS Code 或 Cursor：再安装 Codex IDE 扩展 。 不喜欢终端：查看官方 Codex App 实时下载页。 暂时不想安装：打开 Codex Web 。 CLI、IDE 扩展和桌面 App 是不同入口。CLI 支持 Windows、macOS、Linux 的当前安装方式；桌面 App 是否向你的系统提供下载按钮，应以 Codex 官方落地页 实时显示为准。 二、安装前准备：先做这 6 件事 ​ 确认项目已备份或纳入 Git ：至少先运行一次 git status 。 不要第一次就在生产目录测试 ：先建一个小型练习仓库。 准备可用的认证方式 ：ChatGPT 账号或 OpenAI API Key 二选一。 使用官方安装源 ：只信任 chatgpt.com 、 openai.com 、 github.com/openai 和 npmjs.com/package/@openai/codex 。 npm 路线需要 Node.js ：建议安装仍受维护的 Node.js LTS，而不是多年未更新的旧版本。 公司代码先看制度 ：确认代码、日志和提示词能否发送给外部 AI 服务。 安装完成后，统一用下面两条命令检查： 三、Windows 安装 Codex ​ Windows 现在可以使用官方 PowerShell 安装器或 npm 安装 CLI， 不等于所有 Codex 开发方式都不需要 WSL2 。如果你是从源码构建，或项目依赖 Linux 工具链，再把 WSL2 作为对应路线；普通预编译 CLI 安装不必先安装 WSL2。 方法 A：官方 PowerShell 安装脚本 ​ 打开 PowerShell，运行： 完成后关闭并重新打开 PowerShell，再检查： irm ... | iex 会下载并立即执行脚本。本文列出的是 OpenAI 官方 chatgpt.com 域名，但你仍应核对拼写，并理解远程脚本执行的风险。公司电脑应先遵循管理员的软件安装流程。 方法 B：使用 npm 安装 ​ 已经装好 Node.js 和 npm 的用户，可运行： 如果 PowerShell 提示脚本执行被禁用，可以先改用“命令提示符”运行，或只对当前 PowerShell 进程临时放开： 不要为了省事长期关闭整个系统的脚本安全策略。 方法 C：下载官方二进制文件 ​ 不想使用远程脚本或 npm，可以前往 OpenAI Codex Releases ，选择与 Windows 架构对应的文件。下载后把可执行文件放入受信任目录，并将目录加入 PATH 。 项目本身在 Linux 环境运行； 团队脚本大量依赖 Bash、GNU 工具或 Linux 权限； Windows 原生环境出现难以解决的依赖差异； 希望把开发环境与 Windows 主系统进一步隔离。 在管理员终端安装 WSL2 通常可使用： 该操作可能要求重启。进入 Ubuntu 等 WSL 发行版后，再按本文的 Linux 方法安装 Codex。 四、macOS 安装 Codex ​ 同样要先确认域名确实是 chatgpt.com ，不要执行聊天群或网盘里来源不明的同名脚本。 方法 B：Homebrew ​ Apple Silicon 与 Intel Mac 的文件架构不同。手动下载二进制时，要在 官方 Releases 中选择与本机架构匹配的版本。 五、Linux 安装 Codex ​ 方法 C：官方 Releases ​ 服务器环境或不方便安装 Node.js 时，可以从 OpenAI Codex Releases 下载对应的 Linux x64/arm64 文件。确认文件来源后赋予执行权限，并放入当前用户的可执行路径。 不要一遇到权限错误就使用 sudo npm 全局目录权限错误时，优先修复当前用户的 npm 全局目录、使用 Node 版本管理器，或改用官方独立安装方式。盲目用 sudo npm install -g 可能留下由 root 所有的缓存和配置文件。 六、Codex App、IDE 扩展与网页版入口 ​ 官方 Codex 仓库当前给出了下面的桌面入口： 如果当前系统没有可用客户端或命令没有打开 App，请直接访问 Codex App 官方落地页 ，以页面当时提供的系统和下载方式为准。 官方 IDE 文档列出了 VS Code、Cursor 和 Windsurf。建议从编辑器扩展市场核对发布者，再按 Codex IDE 官方说明 完成登录。 https://chatgpt.com/codex 网页版、桌面端、IDE 和 CLI 的界面不同，但安全原则相同：先确认项目范围，再授权修改，最后查看 diff 和测试结果。 七、第一次登录：ChatGPT 账号还是 API Key？ ​ 客户端通常会让你选择使用 ChatGPT 登录或其他认证方式。 图中是迁移自旧教程的客户端界面示例。按钮名称和布局可能随版本变化。 方案 A：使用 ChatGPT 登录 ​ 对已经有合适 ChatGPT 套餐的个人或团队用户，这通常是最省事的路径。OpenAI 当前帮助文档列出了 Plus、Pro、Business、Edu、Enterprise 等 Codex 使用路径，具体额度与权益以账号页面为准。 远程服务器没有可用浏览器时，可尝试设备码登录： 方案 B：使用 OpenAI API Key ​ API Key 适合需要按 API 用量独立结算、统一管理开发凭据或不走 ChatGPT 账号授权的用户。 ChatGPT 订阅与 OpenAI API 是两套计费体系 ； API Key 只能从你信任的 OpenAI Platform 账户获取； 不要把 Key 写进 Markdown、 AGENTS.md 、Git 仓库、截图或公开的 config.toml 。 当前 CLI 支持从标准输入读取 API Key。不要把完整 Key 直接写在命令参数里，以免进入终端历史。PowerShell 可按当前会话临时读取： macOS/Linux 可使用隐藏输入： 如果你当前版本的提示或参数不同，以 Codex API Key 认证文档 和 codex login --help 为准。 八、第一次在真实项目中使用 ​ 本章只演示第一次任务的最短路线。完整的“分析仓库 → 制定计划 → 修改文件 → 运行测试 → 查看 Diff”案例，请继续阅读 Codex 写代码项目实战 。 先进入项目目录，不要在用户主目录或整块磁盘根目录直接启动： 第一次不要直接说“把整个项目都改好”。先用只读任务确认它理解了仓库： 确认分析正确后，再给一个边界清楚的小任务： 一个可靠的 Codex 工作流应该是： 这张旧版截图只用于展示项目列表、对话区和审批入口。右下角型号是当时界面记录， 不能用于判断当前 Codex 默认模型 ；实际模型和界面以你的客户端为准。 九、config.toml 基础配置 ​ Codex 的全局配置位于 $CODEX_HOME/config.toml ，默认通常是： Windows： %USERPROFILE%\.codex\config.toml macOS/Linux： ~/.codex/config.toml 受信任的仓库还可以使用项目级 .codex/config.toml 。不要从陌生仓库直接接受高权限项目配置。 这代表 Codex 可以在工作区内完成正常修改，超出允许边界时再向你请求授权。不同版本支持的键和值可能变化，修改前可查 基础配置 与 完整配置参考 。 为什么不建议一开始固定 model？ ​ Codex 的模型名称、默认路由和账号可用范围都会变化。如果你没有明确的团队要求，先让当前客户端使用其默认推荐配置，通常比从旧教程复制一个过期模型名称更稳妥。 config.toml 里不要放什么？ ​ OpenAI API Key、第三方 Key、密码； 公司内部 Token、数据库连接串； 从论坛复制且看不懂的自定义 Base URL； 为了“省去弹窗”而长期设置的全权限组合； 与当前 Codex 文档不匹配的旧模型映射。 十、审批策略与沙箱：这是两套不同设置 ​ 很多教程会把“审批”和“权限”混为一谈，实际上： approval_policy ：什么时候向你申请额外授权； sandbox_mode ：Codex 当前能读写哪些文件、能否访问网络和执行哪些操作。 approval_policy 常见值 ​ never 不等于“自动拥有所有权限”。它只表示不向你请求审批。 sandbox_mode 常见层级 ​ 新手不要为了少点几次“允许”，就长期关闭隔离。删除文件、安装软件、访问工作区外目录、读取敏感文件和调用外部网络，都应该知道 Codex 为什么需要。

详见 Codex 安全文档 。 十一、用 AGENTS.md 告诉 Codex 怎么工作 ​ 这里只提供最小示例。需要六段式任务写法、20 个可复制 Prompt 和更完整的仓库规则，请阅读 Codex 提示词与 AGENTS.md 最佳实践 ；如果想把一套流程连同脚本和参考资料反复复用，则继续看 Codex Skills 安装、创建与导入教程 。 AGENTS.md 是写给编程代理的仓库说明文件，适合记录安装命令、测试命令、目录边界和审查要求。 大型仓库可以在子目录放置更具体的 AGENTS.md ，让规则只作用于对应子树。它适合保存“如何工作”， 不适合保存任何秘密 。 官方说明： AGENTS.md 指南 。 MCP 可以让 Codex 连接文档、数据库或内部工具，但每多接一个服务器，就多一组需要审查的权限和数据边界。 添加 HTTP MCP 服务器： 添加本地 stdio 服务器： 如果 HTTP 服务器使用 OAuth： codex mcp add 会把配置写入全局 ~/.codex/config.toml 。只连接你信任的服务器，并确认它能读取哪些文件、提示词和返回结果。更多参数以 Codex MCP 文档 为准。 十三、ZeoGPT 与第三方 Codex 服务怎么判断？ ​ 如果你正在比较 ChatGPT 账号、OpenAI API 与第三方 Codex 相关服务，先阅读 Codex 国内使用方案 ，避免把三套账号和计费体系混在一起。 ZeoGPT 是本站在 Codex 教程中介绍的第三方服务， 不是 OpenAI 官方软件、ChatGPT 订阅或 OpenAI API 账户 。注册或购买前至少核对： 服务商是否明确写出 Codex 或当前 API 协议的兼容范围； Base URL 是否要求完整路径； 是否支持工具调用、流式输出和当前认证方式； Key 泄露后如何撤销和轮换； 不要直接复制旧文章里的 auth.json 、模型名称、Base URL 或第三方配置。ZeoGPT 网页账号也不能自动等同于 OpenAI API Key；只有平台实时文档明确说明的配置方式才可作为操作依据。 升级时可重新运行对应的官方安装方式，或从 Releases 获取新版本。不要假设存在 codex update 、 codex --upgrade 等未核实命令，先运行 codex --help 查看当前版本实际支持的参数。 1. codex: command not found ​ 检查 npm 全局可执行目录是否在 PATH ； Windows 可尝试 where codex ，macOS/Linux 可尝试 which codex ； 仍失败时改用官方独立安装器或 Releases。 2. PowerShell 提示“禁止运行脚本” ​ 优先改用命令提示符，或只对当前窗口执行： 操作结束、窗口关闭后该临时设置失效。 3. 登录后浏览器没有跳回 ​ 把终端显示的登录 URL 复制到浏览器； 确认浏览器与终端使用的是同一台设备； 远程服务器使用 codex login --device-auth ； 运行 codex login status 检查认证状态； 仍失败时先 codex logout ，再重新登录。 如果浏览器已经显示授权成功，但终端报 token_exchange_failed 、localhost 回调失败、state mismatch 或 403，请不要反复重装。按 Codex 登录失败、localhost 回调与 token 交换排查 判断故障发生在哪个阶段。 4. API Key 报 401 或认证失败 ​ 确认使用的是 OpenAI Platform Key，而不是 ChatGPT 密码或第三方网页账号； 检查 API 项目的计费和权限； Key 曾出现在截图、日志或 Git 中时，立即撤销并创建新 Key。 5. 提示操作被拒绝或无法写文件 ​ 先判断是 sandbox 拦截 还是 approval policy 没有授权 。让 Codex 说明具体被拒绝的路径和命令，收窄操作范围后重试；只有在理解原因时，才为该次操作增加权限。 6. Codex 读不到整个项目 ​ 检查 .gitignore 、权限和符号链接； 先让 Codex 列出它实际能看到的顶层目录； 不要把整个用户目录作为项目根目录。 7. MCP 已添加但不可用 ​ 核对服务器命令、URL、环境变量和 OAuth 状态；需要授权时运行 codex mcp login <name> ，然后重开 Codex 会话。 8. 第三方 API 返回 404、模型不存在或工具调用失败 ​ 这通常不是重新安装 Codex 能解决的问题。检查服务商当前文档中的 Base URL、模型名、协议兼容范围和账户余额。不要用旧截图或旧配置猜测新接口。 每次让 Codex 修改重要项目之前，快速检查： [ ] 当前目录正确， git status 已查看； [ ] 已排除 .env 、私钥、生产数据库和用户数据； [ ] 任务范围写清楚，没有授权“顺便重构全部项目”； [ ] 新仓库先使用只读或更保守的审批方式； [ ] 删除、安装、联网、访问工作区外目录时逐项确认； [ ] 修改完成后查看 git diff ； [ ] 已运行测试、构建或静态检查； [ ] API Key 没有进入配置样例、日志、截图和 Git； [ ] 第三方 MCP/API 的数据政策已确认； [ ] 最终提交和部署仍由你决定。 Windows 能直接安装 Codex 吗？ ​ 可以。OpenAI 当前提供 Windows PowerShell 安装脚本，npm 包也包含 Windows 架构。WSL2 是项目依赖 Linux 或原生环境兼容性不佳时的备选方案之一。 安装 Codex 一定需要 Node.js 吗？ ​ 不一定。npm 安装需要 Node.js；官方独立安装脚本和 Releases 路线不以 npm 为前提。 有 ChatGPT Plus 就不用 API Key 吗？ ​ 选择 ChatGPT 登录时通常不需要再配置 API Key，但具体 Codex 权益和额度以你的 ChatGPT 账号页面为准。选择 API Key 路线时，API 会独立认证和计费。 ChatGPT 订阅费包含 OpenAI API 费用吗？ ​ 不包含。ChatGPT 与 OpenAI API 是两套产品和计费体系。 Codex 会自动提交或部署代码吗？ ​ 是否执行取决于你的任务、工具、沙箱和审批设置。不要默认授权提交、推送或部署；先检查改动和测试结果。 可以把 API Key 写进 config.toml 吗？ ​ 不建议。优先使用官方认证流程、环境变量或组织认可的密钥管理方式，避免 Key 进入同步盘、备份和 Git。 ZeoGPT 账号能直接登录 OpenAI Codex CLI 吗？ ​ ZeoGPT 是第三方服务，不是 OpenAI 的 ChatGPT 授权入口。网页账号不能直接当作 OpenAI API Key；是否提供其他 Codex 使用方式，必须以 ZeoGPT 登录后的实时说明和服务条款为准。 为什么截图里的模型和我的不一样？ ​ 截图记录的是某个时间点的界面。Codex 会更新客户端、默认模型和账号可用范围，应该以你当前客户端和官方文档为准。 十八、总结：最稳妥的 Codex 上手路线 ​ 如果你是第一次安装，按下面顺序最不容易出错： 选择官方 CLI 安装器、npm、Homebrew 或 Releases； 用 codex --version 确认安装成功； 在一个已纳入 Git 的测试仓库运行 codex ； 优先使用 ChatGPT 登录，或谨慎配置独立计费的 API Key； 先让 Codex 只读分析，再授权一个小范围修改； 使用 workspace-write + on-request 作为常见起点； 用 AGENTS.md 写清测试命令和目录边界； 查看 diff、运行测试，再决定提交和部署。 这比复制一份过期的高权限配置更可靠，也更适合长期使用。 如果你只遇到单一系统问题，可直接查看 Windows 的 PowerShell、npm、PATH 与登录排查 或 macOS 的 Homebrew、Apple Silicon 与权限排查 ；如果还没决定使用哪种客户端，先看 Codex Web、App、CLI 与 IDE 区别 。 OpenAI Codex 官方 GitHub 仓库 Codex 与 ChatGPT 账号说明 GPT-5.6 工具调用与 Multi-agent 指南 Codex 国内怎么用：账号、API 与第三方服务选择 Codex 登录失败与 token_exchange_failed 排查 Codex Skills 安装、创建与 GitHub 导入 Codex 提示词与 AGENTS.md 最佳实践 本文提供安装与配置说明，不代表 OpenAI 官方支持页面。软件版本、套餐、模型、权限和第三方服务规则可能变化，重要操作请以 OpenAI 官方实时文档及你所在组织的安全政策为准。