Codex 下载、安装与配置指南：Windows、macOS、Linux CLI 与 App（2026）

如果你条件有限，强烈推荐国内 API 站

这是站主自主搭建纯 GPT API 站，无需梯子，实时更新 GPT 最新模型（仅支持电脑端），价格是官方的 三分之一，操作简单，连接稳定，价格便宜，保证没有任何掺水、收集信息等低劣行为，保证爽用 GPT。

• 考普 AI 官网入口

想在 Windows、macOS 或 Linux 上安装 Codex，却被 CLI、App、IDE 扩展、ChatGPT 登录、API Key 和权限配置绕晕？这篇教程从版本选择开始，带你完成下载、安装、首次登录、真实项目运行和安全配置。

本文于 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	PowerShell、Terminal、Shell	想让代理读取、修改、测试本地代码的开发者	是
Codex App	独立桌面客户端	喜欢图形界面、项目列表和对话工作流的用户	通常是
Codex IDE 扩展	VS Code、Cursor、Windsurf	不想离开编辑器的开发者	是
Codex Web	浏览器	想使用云端任务或先体验 Codex 的用户	视任务而定

最简单的选择方法

• 想照着本文完整学习：安装 Codex CLI。
• 习惯 VS Code 或 Cursor：再安装 Codex IDE 扩展。
• 不喜欢终端：查看官方 Codex App 实时下载页。
• 暂时不想安装：打开 Codex Web。

不要把四种形态混成一个安装包

CLI、IDE 扩展和桌面 App 是不同入口。CLI 支持 Windows、macOS、Linux 的当前安装方式；桌面 App 是否向你的系统提供下载按钮，应以 Codex 官方落地页实时显示为准。

二、安装前准备：先做这 6 件事

1. 确认项目已备份或纳入 Git：至少先运行一次 git status。
2. 不要第一次就在生产目录测试：先建一个小型练习仓库。
3. 准备可用的认证方式：ChatGPT 账号或 OpenAI API Key 二选一。
4. 使用官方安装源：只信任 chatgpt.com、openai.com、github.com/openai 和 npmjs.com/package/@openai/codex。
5. npm 路线需要 Node.js：建议安装仍受维护的 Node.js LTS，而不是多年未更新的旧版本。
6. 公司代码先看制度：确认代码、日志和提示词能否发送给外部 AI 服务。

安装完成后，统一用下面两条命令检查：

codex --version
codex --help

三、Windows 安装 Codex

Windows 现在可以使用官方 PowerShell 安装器或 npm 安装 CLI，不等于所有 Codex 开发方式都不需要 WSL2。如果你是从源码构建，或项目依赖 Linux 工具链，再把 WSL2 作为对应路线；普通预编译 CLI 安装不必先安装 WSL2。

方法 A：官方 PowerShell 安装脚本

打开 PowerShell，运行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

完成后关闭并重新打开 PowerShell，再检查：

codex --version

为什么远程脚本需要谨慎？

irm ... | iex 会下载并立即执行脚本。本文列出的是 OpenAI 官方 chatgpt.com 域名，但你仍应核对拼写，并理解远程脚本执行的风险。公司电脑应先遵循管理员的软件安装流程。

方法 B：使用 npm 安装

已经装好 Node.js 和 npm 的用户，可运行：

npm install -g @openai/codex
codex --version

如果 PowerShell 提示脚本执行被禁用，可以先改用“命令提示符”运行，或只对当前 PowerShell 进程临时放开：

Set-ExecutionPolicy -Scope Process Bypass

不要为了省事长期关闭整个系统的脚本安全策略。

方法 C：下载官方二进制文件

不想使用远程脚本或 npm，可以前往 OpenAI Codex Releases，选择与 Windows 架构对应的文件。下载后把可执行文件放入受信任目录，并将目录加入 PATH。

WSL2 什么时候有用？

以下情况可以考虑 WSL2：

• 项目本身在 Linux 环境运行；
• 团队脚本大量依赖 Bash、GNU 工具或 Linux 权限；
• Windows 原生环境出现难以解决的依赖差异；
• 希望把开发环境与 Windows 主系统进一步隔离。

在管理员终端安装 WSL2 通常可使用：

wsl --install

该操作可能要求重启。进入 Ubuntu 等 WSL 发行版后，再按本文的 Linux 方法安装 Codex。

四、macOS 安装 Codex

方法 A：官方安装脚本

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

同样要先确认域名确实是 chatgpt.com，不要执行聊天群或网盘里来源不明的同名脚本。

方法 B：Homebrew

brew install --cask codex
codex --version

方法 C：npm

npm install -g @openai/codex
codex --version

Apple Silicon 与 Intel Mac 的文件架构不同。手动下载二进制时，要在 官方 Releases中选择与本机架构匹配的版本。

五、Linux 安装 Codex

方法 A：官方安装脚本

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

方法 B：npm

npm install -g @openai/codex
codex --version

方法 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 仓库当前给出了下面的桌面入口：

codex app

如果当前系统没有可用客户端或命令没有打开 App，请直接访问 Codex App 官方落地页，以页面当时提供的系统和下载方式为准。

IDE 扩展

官方 IDE 文档列出了 VS Code、Cursor 和 Windsurf。建议从编辑器扩展市场核对发布者，再按 Codex IDE 官方说明完成登录。

Codex Web

无需本地安装时可访问：

https://chatgpt.com/codex

网页版、桌面端、IDE 和 CLI 的界面不同，但安全原则相同：先确认项目范围，再授权修改，最后查看 diff 和测试结果。

七、第一次登录：ChatGPT 账号还是 API Key？

首次运行：

codex

客户端通常会让你选择使用 ChatGPT 登录或其他认证方式。

图中是迁移自旧教程的客户端界面示例。按钮名称和布局可能随版本变化。

方案 A：使用 ChatGPT 登录

对已经有合适 ChatGPT 套餐的个人或团队用户，这通常是最省事的路径。OpenAI 当前帮助文档列出了 Plus、Pro、Business、Edu、Enterprise 等 Codex 使用路径，具体额度与权益以账号页面为准。

常用登录命令：

codex login
codex login status

远程服务器没有可用浏览器时，可尝试设备码登录：

codex login --device-auth

退出当前账号：

codex logout

方案 B：使用 OpenAI API Key

API Key 适合需要按 API 用量独立结算、统一管理开发凭据或不走 ChatGPT 账号授权的用户。

使用前必须理解三点：

1. ChatGPT 订阅与 OpenAI API 是两套计费体系；
2. API Key 只能从你信任的 OpenAI Platform 账户获取；
3. 不要把 Key 写进 Markdown、AGENTS.md、Git 仓库、截图或公开的 config.toml。

当前 CLI 支持从标准输入读取 API Key。不要把完整 Key 直接写在命令参数里，以免进入终端历史。PowerShell 可按当前会话临时读取：

$env:OPENAI_API_KEY = Read-Host "OpenAI API Key"
$env:OPENAI_API_KEY | codex login --with-api-key
Remove-Item Env:OPENAI_API_KEY

macOS/Linux 可使用隐藏输入：

read -s OPENAI_API_KEY
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY

如果你当前版本的提示或参数不同，以 Codex API Key 认证文档和 codex login --help 为准。

两种方式怎么选？

对比项	ChatGPT 登录	OpenAI API Key
认证主体	ChatGPT 账号	OpenAI Platform 项目/Key
计费方式	取决于 ChatGPT 套餐与额度	API 独立按当前规则计费
适合场景	个人开发、团队席位、快速上手	项目化成本管理、API 账户管理
密钥管理	浏览器授权为主	必须自行保护和轮换 Key

八、第一次在真实项目中使用

本章只演示第一次任务的最短路线。完整的“分析仓库 → 制定计划 → 修改文件 → 运行测试 → 查看 Diff”案例，请继续阅读 Codex 写代码项目实战。

先进入项目目录，不要在用户主目录或整块磁盘根目录直接启动：

cd path/to/your-project
git status
codex

第一次不要直接说“把整个项目都改好”。先用只读任务确认它理解了仓库：

先只读分析这个项目，不要修改文件。
告诉我：
1. 项目使用什么技术栈；
2. 正确的安装、启动和测试命令；
3. 最需要注意的三个风险；
4. 如果要修复首页报错，你建议先检查哪些文件。

确认分析正确后，再给一个边界清楚的小任务：

只修复首页提交按钮重复触发的问题。
修改前先说明原因和计划；不要改动无关文件。
完成后运行相关测试，并总结修改文件、测试结果和仍有风险。

一个可靠的 Codex 工作流应该是：

1. 读取仓库说明与相关文件；
2. 说明原因和实施计划；
3. 只修改任务范围内的文件；
4. 运行测试、构建或静态检查；
5. 检查 git diff；
6. 由你决定是否提交和部署。

这张旧版截图只用于展示项目列表、对话区和审批入口。右下角型号是当时界面记录，不能用于判断当前 Codex 默认模型；实际模型和界面以你的客户端为准。

九、config.toml 基础配置

Codex 的全局配置位于 $CODEX_HOME/config.toml，默认通常是：

• Windows：%USERPROFILE%\.codex\config.toml
• macOS/Linux：~/.codex/config.toml

受信任的仓库还可以使用项目级 .codex/config.toml。不要从陌生仓库直接接受高权限项目配置。

新手推荐的最小配置

approval_policy = "on-request"
sandbox_mode = "workspace-write"

这代表 Codex 可以在工作区内完成正常修改，超出允许边界时再向你请求授权。不同版本支持的键和值可能变化，修改前可查 基础配置与 完整配置参考。

为什么不建议一开始固定 model？

Codex 的模型名称、默认路由和账号可用范围都会变化。如果你没有明确的团队要求，先让当前客户端使用其默认推荐配置，通常比从旧教程复制一个过期模型名称更稳妥。

config.toml 里不要放什么？

• OpenAI API Key、第三方 Key、密码；
• 公司内部 Token、数据库连接串；
• 从论坛复制且看不懂的自定义 Base URL；
• 为了“省去弹窗”而长期设置的全权限组合；
• 与当前 Codex 文档不匹配的旧模型映射。

十、审批策略与沙箱：这是两套不同设置

很多教程会把“审批”和“权限”混为一谈，实际上：

• approval_policy：什么时候向你申请额外授权；
• sandbox_mode：Codex 当前能读写哪些文件、能否访问网络和执行哪些操作。

approval_policy 常见值

值	含义	适合场景
untrusted	更保守，较多操作需要确认	陌生仓库、初次审计
on-request	需要越过当前边界时申请	日常开发的平衡选择
never	不弹出审批，受限操作失败后返回	自动化环境，但必须预先设好边界

never 不等于“自动拥有所有权限”。它只表示不向你请求审批。

sandbox_mode 常见层级

值	大致边界	建议
read-only	只读分析，不写文件	审查陌生项目时优先
workspace-write	可写当前工作区，其他区域受限	大多数本地开发任务
danger-full-access	隔离限制显著减少	仅在你理解风险且确有需要时临时使用

新手不要为了少点几次“允许”，就长期关闭隔离。删除文件、安装软件、访问工作区外目录、读取敏感文件和调用外部网络，都应该知道 Codex 为什么需要。

详见 Codex 安全文档。

十一、用 AGENTS.md 告诉 Codex 怎么工作

这里只提供最小示例。需要六段式任务写法、20 个可复制 Prompt 和更完整的仓库规则，请阅读 Codex 提示词与 AGENTS.md 最佳实践；如果想把一套流程连同脚本和参考资料反复复用，则继续看 Codex Skills 安装、创建与导入教程。

AGENTS.md 是写给编程代理的仓库说明文件，适合记录安装命令、测试命令、目录边界和审查要求。

在仓库根目录创建：

AGENTS.md 示例

- 安装依赖：npm ci
- 本地开发：npm run dev
- 单元测试：npm test
- 生产构建：npm run build
- 只修改 src/ 和 tests/ 中与任务相关的文件
- 不要提交 .env、密钥、构建产物或用户数据
- 完成前必须运行测试，并说明未能运行的检查

大型仓库可以在子目录放置更具体的 AGENTS.md，让规则只作用于对应子树。它适合保存“如何工作”，不适合保存任何秘密。

官方说明：AGENTS.md 指南。

十二、配置 MCP 工具

MCP 可以让 Codex 连接文档、数据库或内部工具，但每多接一个服务器，就多一组需要审查的权限和数据边界。

查看已配置服务器：

codex mcp list

添加 HTTP MCP 服务器：

codex mcp add my-server --url "https://your-server.example/mcp"

添加本地 stdio 服务器：

codex mcp add local-server -- node ./path/to/server.js

如果 HTTP 服务器使用 OAuth：

codex mcp login my-server
codex mcp logout my-server

删除配置：

codex mcp remove my-server

codex mcp add 会把配置写入全局 ~/.codex/config.toml。只连接你信任的服务器，并确认它能读取哪些文件、提示词和返回结果。更多参数以 Codex MCP 文档为准。

十四、升级与卸载

npm 安装

升级：

npm install -g @openai/codex@latest
codex --version

卸载：

npm uninstall -g @openai/codex

Homebrew 安装

升级：

brew upgrade --cask codex

卸载：

brew uninstall --cask codex

官方脚本或二进制安装

升级时可重新运行对应的官方安装方式，或从 Releases 获取新版本。不要假设存在 codex update、codex --upgrade 等未核实命令，先运行 codex --help 查看当前版本实际支持的参数。

十五、常见报错与解决方法

1. codex: command not found

按顺序检查：

node -v
npm -v
codex --version

• 关闭并重新打开终端；
• 检查 npm 全局可执行目录是否在 PATH；
• Windows 可尝试 where codex，macOS/Linux 可尝试 which codex；
• 仍失败时改用官方独立安装器或 Releases。

2. PowerShell 提示“禁止运行脚本”

优先改用命令提示符，或只对当前窗口执行：

Set-ExecutionPolicy -Scope Process Bypass

操作结束、窗口关闭后该临时设置失效。

3. 登录后浏览器没有跳回

• 把终端显示的登录 URL 复制到浏览器；
• 确认浏览器与终端使用的是同一台设备；
• 远程服务器使用 codex login --device-auth；
• 运行 codex login status 检查认证状态；
• 仍失败时先 codex logout，再重新登录。

如果浏览器已经显示授权成功，但终端报 token_exchange_failed、localhost 回调失败、state mismatch 或 403，请不要反复重装。按 Codex 登录失败、localhost 回调与 token 交换排查 判断故障发生在哪个阶段。

5. 提示操作被拒绝或无法写文件

先判断是 sandbox 拦截还是 approval policy 没有授权。让 Codex 说明具体被拒绝的路径和命令，收窄操作范围后重试；只有在理解原因时，才为该次操作增加权限。

6. Codex 读不到整个项目

• 确认你在正确项目目录启动；
• 检查文件是否位于工作区外；
• 检查 .gitignore、权限和符号链接；
• 先让 Codex 列出它实际能看到的顶层目录；
• 不要把整个用户目录作为项目根目录。

7. MCP 已添加但不可用

codex mcp list

核对服务器命令、URL、环境变量和 OAuth 状态；需要授权时运行 codex mcp login <name>，然后重开 Codex 会话。

十六、安全使用清单

每次让 Codex 修改重要项目之前，快速检查：

• [ ] 当前目录正确，git status 已查看；
• [ ] 已排除 .env、私钥、生产数据库和用户数据；
• [ ] 任务范围写清楚，没有授权“顺便重构全部项目”；
• [ ] 新仓库先使用只读或更保守的审批方式；
• [ ] 删除、安装、联网、访问工作区外目录时逐项确认；
• [ ] 修改完成后查看 git diff；
• [ ] 已运行测试、构建或静态检查；
• [ ] API Key 没有进入配置样例、日志、截图和 Git；
• [ ] 第三方 MCP/API 的数据政策已确认；
• [ ] 最终提交和部署仍由你决定。

十七、常见问题 FAQ

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。

为什么截图里的模型和我的不一样？

截图记录的是某个时间点的界面。Codex 会更新客户端、默认模型和账号可用范围，应该以你当前客户端和官方文档为准。

十八、总结：最稳妥的 Codex 上手路线

如果你是第一次安装，按下面顺序最不容易出错：

1. 选择官方 CLI 安装器、npm、Homebrew 或 Releases；
2. 用 codex --version 确认安装成功；
3. 在一个已纳入 Git 的测试仓库运行 codex；
4. 优先使用 ChatGPT 登录，或谨慎配置独立计费的 API Key；
5. 先让 Codex 只读分析，再授权一个小范围修改；
6. 使用 workspace-write + on-request 作为常见起点；
7. 用 AGENTS.md 写清测试命令和目录边界；
8. 查看 diff、运行测试，再决定提交和部署。

这比复制一份过期的高权限配置更可靠，也更适合长期使用。

如果你只遇到单一系统问题，可直接查看 Windows 的 PowerShell、npm、PATH 与登录排查 或 macOS 的 Homebrew、Apple Silicon 与权限排查；如果还没决定使用哪种客户端，先看 Codex Web、App、CLI 与 IDE 区别。