Codex 安装教程:macOS、Windows 与 Linux 分步说明

2026 年 10 月实测 Codex CLI 0.164 的安装:macOS、Windows、Linux 分步命令,安装后在 ~/.codex/config.toml 接入 API Key,附 PATH、npm、401 等常见报错的处理方法。

10 分钟阅读
Codex 安装教程:macOS、Windows 与 Linux 分步说明

安装 Codex CLI,最重要的不是把一条命令粘进终端,而是三件事:确认命令来自官方,安装后系统能找到 codex,并且版本和帮助信息都能正常输出。只要这三项都通过,后面的登录、配置 API Key 和使用就都有了可靠的起点。

这篇教程按操作系统拆开写,每个系统都给出安装命令、验证方法和常见问题。所有安装命令都来自 OpenAI Codex CLI 官方文档和 AI Code With 的 Codex 终端文档。如果你看到这里的命令和官方页面不一致,请以官方页面为准,因为安装方式会随着版本更新调整。

还没下载安装包?官方下载地址见《Codex 下载》。装好之后怎么用,看《Codex 怎么用》。

2026 年 10 月实测:当前版本和安装耗时

我们在 2026-10-26 用一台 Linux x64 机器把三条安装路线各跑了一遍,装完都执行 codex --version 确认版本。当天 npm 上的最新版本是 0.164.0(npm view @openai/codex version 的输出),官方安装脚本解析到的也是 0.164.0。

实测项命令耗时输出
官方安装脚本curl -fsSL https://chatgpt.com/codex/install.sh | sh约 4.8 秒Codex CLI 0.164.0 installed successfully.
npm 官方源npm install -g @openai/codex约 4.2 秒codex-cli 0.164.0
npm 国内镜像npm install -g @openai/codex --registry=https://registry.npmmirror.com/约 4.3 秒codex-cli 0.164.0
接入本站后最小对话codex exec "只回复:安装成功"约 3.0 秒返回「安装成功」
故意填错 Keycodex exec "hi"约 7.7 秒重连 5 次后报 401(见报错对照表)

耗时和网络环境关系很大,国内网络下官方脚本可能明显更慢,这时换 npm 镜像通常更快。0.164 这一版新增了哪些预设和推理强度切换,见《Codex CLI 0.164 更新:预设、模型与推理强度》。

安装前先选一条路线

OpenAI 目前提供四种安装入口:macOS/Linux 独立安装脚本、Windows 独立安装脚本、npm 和 Homebrew。它们装出来的都是同一个 Codex CLI,区别只在于依赖什么、以后怎么升级。

安装方式适合谁需要的前置条件升级方式
官方安装脚本(macOS/Linux)不想装 Node.js 的用户curl 和能访问官方地址的网络重新运行同一条安装命令
官方安装脚本(Windows)Windows 用户首选PowerShell重新运行同一条安装命令
npm已经在用 Node.js 的开发者Node.js 18+ 和 npmnpm install -g @openai/codex
HomebrewmacOS 上习惯用 brew 的用户Homebrewbrew upgrade --cask codex

如果你在国内网络环境下,官方安装脚本有时下载不稳定,这时 npm 加国内镜像通常更顺。AI Code With 文档里给出的就是 npm 路线,要求 Node.js 版本为 18 及以上。

macOS 安装步骤

方式一:官方安装脚本

打开「终端」,执行官方给出的独立安装命令:

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

以后需要升级时,再运行一次同一条命令即可。

方式二:Homebrew

如果你已经装了 Homebrew,可以用官方提供的 cask 安装:

bash
brew install --cask codex

升级命令是:

bash
brew upgrade --cask codex

方式三:npm

先确认 Node.js 已经安装,并且版本在 18 以上:

bash
node --version
npm --version

如果还没有 Node.js,可以按 AI Code With 文档的做法,用 Homebrew 安装:

bash
brew install node

然后安装 Codex CLI。国内用户可以加上镜像参数:

bash
npm install -g @openai/codex
npm install -g @openai/codex --registry=https://registry.npmmirror.com/

两条命令选一条执行就行,第二条走的是国内镜像。

macOS 验证安装

安装完成后,重新打开一个终端窗口,然后依次检查:

bash
command -v codex
codex --version
codex --help

第一条能输出 codex 的路径,第二条能输出版本号,第三条能打印帮助信息,就说明安装成功了。成功的标准不是"安装器没有报错",而是这三条都能正常输出。

Windows 安装步骤

方式一:官方 PowerShell 安装脚本

OpenAI 官方文档建议从新开的 PowerShell 窗口里执行下面这条命令:

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

不要长期照搬旧博客里的 PowerShell 命令。官方安装入口会更新,执行前最好打开官方页面确认一下当前命令。

方式二:npm

先去 Node.js 官网下载并安装 LTS 版本,然后按 Win + R,输入 powershell 打开 PowerShell,检查版本:

powershell
node --version
npm --version

确认 Node.js 版本在 18 以上之后,安装 Codex CLI:

powershell
npm install -g @openai/codex

国内用户可以改用镜像:

powershell
npm install -g @openai/codex --registry=https://npmreg.proxy.ustclug.org

如果 PowerShell 提示"在此系统上禁止运行脚本",AI Code With 文档给出的处理方式是:用管理员权限打开 PowerShell,执行 Set-ExecutionPolicy Unrestricted。这一步会放宽当前系统的脚本执行策略,请确认你理解它的影响后再操作。

Windows 验证安装

关闭当前 PowerShell,重新打开一个,然后检查:

powershell
Get-Command codex
codex --version
codex --help

如果 Get-Command codex 找不到命令,先不要重装,往下看"安装完却找不到 codex"一节。

Linux 安装步骤

方式一:官方安装脚本

Linux 和 macOS 用的是同一条独立安装命令:

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

方式二:npm

如果系统里还没有 Node.js,AI Code With 文档给出的 Debian/Ubuntu 安装方式是(需要 root 权限):

bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs

确认版本后安装 Codex CLI:

bash
node --version
npm install -g @openai/codex --registry=https://registry.npmmirror.com/

其他发行版请用自己的包管理器安装 Node.js LTS,然后执行同样的 npm 命令。

Linux 验证安装

bash
command -v codex
codex --version
codex --help

如果你是在没有图形界面的服务器上安装,下一步登录时浏览器流程可能走不通,这种情况的处理方法写在后面的常见问题里。

为什么每次都要重新打开终端

很多"装好了却找不到命令"的问题,其实只是终端没有重新打开。终端在启动时会读取一次环境变量,安装程序往 PATH 里加的新目录,只对之后新开的终端窗口生效。已经开着的窗口还在用旧的 PATH,自然找不到刚装好的 codex。

所以本文每个系统的验证步骤,都要求先关掉当前窗口、重新打开一个再检查。如果你在 VS Code 等编辑器的内置终端里安装,同样需要关闭整个编辑器再打开,只新建一个终端标签页有时不够。

另外,Windows 上如果你一会儿用 PowerShell、一会儿用命令提示符或 Git Bash,它们读取的环境变量可能不一样。建议安装和使用都固定在 PowerShell 里,排查问题时会简单很多。

安装完却找不到 codex

这是安装阶段最常见的问题。原因通常不是"没装上",而是系统 PATH 里没有 Codex 所在的目录,或者当前终端还在用旧的环境变量。

先排查 PATH,macOS / Linux:

bash
command -v codex
printf '%s\n' "$PATH"

Windows:

powershell
Get-Command codex -ErrorAction SilentlyContinue
$env:Path -split ';'

处理顺序建议是:先重新打开终端;还不行,再确认可执行文件实际装在哪个目录(npm 路线可以用 npm prefix -g 查看全局安装位置);最后只把这一个目录加进 PATH。不要把一个来源不明的目录整个加入系统 PATH。

安装后会多出哪些文件

装好并登录之后,Codex 会在你的用户目录下使用一个配置目录,默认是 ~/.codex(可以通过环境变量 CODEX_HOME 改到别的位置)。新手最需要知道的是两个文件:

  • config.toml:Codex 的配置文件,模型、Provider、权限等设置都写在这里;
  • auth.json:登录缓存。官方文档说明,Codex 会把登录信息缓存在这个明文文件里,或者存进系统的凭据库。

如果你更希望把凭据放进系统凭据库,而不是明文文件,官方提供了 cli_auth_credentials_store 这个配置项,可选值有 file、keyring、auto 和 ephemeral:file 存在 auth.json 里;keyring 存进系统凭据库,凭据库不可用时会报错;auto 优先用凭据库,不可用时退回 auth.json;ephemeral 只在当前进程的内存里保存。个人电脑上用默认设置就够了;如果是多人共用的机器,建议考虑 keyring。

不管用哪种方式,都要记住:auth.json 里有访问令牌,等同于密码。不要把它提交到 Git 仓库,不要贴进工单,也不要发到群里。分享配置给同事时,只发 config.toml,并且先确认里面没有直接写入密钥。

公司网络和代理环境下安装

很多公司网络会经过 TLS 代理,或者使用私有根证书。这种环境下,安装脚本能下载成功,但第一次登录时可能报证书错误。官方给出的做法是:在登录之前,把环境变量 CODEX_CA_CERTIFICATE 设置为公司提供的 PEM 证书文件路径,然后再运行登录命令:

bash
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

如果没有设置 CODEX_CA_CERTIFICATE,Codex 会退回使用 SSL_CERT_FILE。这个证书设置同时作用于登录、普通 HTTPS 请求和 WebSocket 连接,所以设置一次就能覆盖后续的调用。证书文件请向公司 IT 部门索取,不要从网上随便下载。

另外,如果你需要通过代理才能访问外网,npm 路线可以先配置 npm 自己的代理,或者直接改用国内镜像,这通常比折腾系统代理更省事。

换一种安装方式之前,先卸载旧的

如果你一开始用 npm 装了,后来又想换成官方脚本或 Homebrew,最好先把旧的卸载掉,否则 PATH 里可能先找到旧版本,出现"明明升级了,版本号却没变"的情况。

npm 安装的,用 npm 卸载:

bash
npm uninstall -g @openai/codex

Homebrew 安装的,用 Homebrew 卸载:

bash
brew uninstall --cask codex

卸载后重新打开终端,用 command -v codex(Windows 用 Get-Command codex)确认已经找不到旧命令,再用新的方式安装。卸载 CLI 不会自动删除 ~/.codex 目录,你的配置和登录缓存还在,重新安装后可以直接继续使用。

第一次启动和登录

进入一个测试项目,再启动 Codex:

bash
cd /你的/测试项目
codex

第一次运行时,官方文档说明你可以选择 Sign in with ChatGPT 或其他可用的登录方式。常见的两种是:

  • ChatGPT 账号登录:运行 codex login,在弹出的浏览器里完成登录,用的是订阅额度。
  • API Key 登录:官方给出的写法是 printenv OPENAI_API_KEY | codex login --with-api-key,走 API Key 的用量。

登录后可以用 codex login status 查看当前使用的认证方式。登录信息会缓存在本地的 ~/.codex/auth.json 或系统凭据库里,这个文件相当于密码,不要提交到 Git,也不要发给别人。

用 AICodeWith 的 API Key 接入 Codex

装好 Codex 以后,不用 codex login,直接在全局配置文件里加一个自定义 Provider 就能用本站的 Key。配置文件位置:macOS / Linux 是 ~/.codex/config.toml,Windows 是 %USERPROFILE%\.codex\config.toml。文件不存在就新建一个。

toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "你的 API Key"

几个容易填错的地方:

  • base_url 是 Codex 专用地址 https://api.aicodewith.ai/chatgpt/v1,不要换成其他客户端用的地址;
  • name = "aicodewith" 和 model_provider = "aicodewith" 要对应同一个 Provider;
  • Key 写在 experimental_bearer_token 里,配置写在全局文件,不要放进项目仓库,也不要提交到 Git。

创建 API Key →

写好后在任意测试目录跑一次最小调用:

bash
codex exec --skip-git-repo-check "只回复:安装成功"

我们实测的输出开头会打印当前使用的模型和 Provider,看到 provider: aicodewith 就说明配置生效了:

text
OpenAI Codex v0.164.0
--------
model: gpt-6.1-sol
provider: aicodewith
approval: never
sandbox: read-only
reasoning effort: medium
--------
user
只回复:安装成功
codex
安装成功

更完整的接入步骤和可用模型见 Codex 接入 AICodeWith,配置项的含义和优先级见《Codex config.toml 配置指南》。用起来以后额度怎么算、为什么有时掉得快,见《Codex 怎么收费、额度为什么掉得快》。

常见报错对照表

报错或现象常见原因解决方法
command not found: codex / Get-Command 找不到安装目录不在 PATH 里,或终端没有重新打开重开终端;用 npm prefix -g 找到安装位置,只把这一个目录加进 PATH
npm: command not found没装 Node.js,或 Node.js 没加入 PATH先装 Node.js LTS,确认 node --version 和 npm --version 都能输出
npm 安装后启动报错,Node 版本过低AI Code With 文档要求 Node.js 18+升级 Node.js 到 LTS 版本后重装
PowerShell 提示"在此系统上禁止运行脚本"Windows 脚本执行策略限制管理员 PowerShell 执行 Set-ExecutionPolicy Unrestricted(了解影响后再改)
npm 下载很慢或超时访问 npm 官方源不稳定加上 --registry=https://registry.npmmirror.com/ 等国内镜像
服务器上 codex login 打不开浏览器无图形界面,或本地回调端口 localhost:1455 被拦截用 codex login --device-auth 设备码登录,或用 SSH 转发 1455 端口
公司网络下登录报证书错误企业 TLS 代理或私有根证书登录前设置 CODEX_CA_CERTIFICATE 指向 PEM 证书文件
首次启动提示 "this folder is not version controlled"当前目录不是 Git 仓库,Codex 在确认权限在测试目录可以按提示选择;正式项目建议先 git init 再用
WARNING: Multiple managed Codex installs can be ambiguous because PATH order decides which one runs.官方安装脚本发现机器上已有 npm 装的 Codex留一种安装方式:先 npm uninstall -g @openai/codex,再用 command -v codex 确认实际调用的是哪一个
unexpected status 401 Unauthorized: {"error":"请在请求中提供有效的 API Key。"}experimental_bearer_token 填错、多了空格,或 Key 已停用重新复制 Key 粘到配置里;报错前出现的 Reconnecting... 1/5 到 5/5 是 Codex 自动重试,不用等它
调用报 404 或路径错误base_url 少了 /chatgpt/v1,或填成了其他客户端的地址改回 https://api.aicodewith.ai/chatgpt/v1,并确认 wire_api = "responses"
装完提示要把 PATH 写进 shell 配置官方脚本默认装到 ~/.local/bin,会把 PATH 追加到 ~/.profile按提示在当前终端执行一次 export,或者直接新开一个终端

如果装好之后调用时遇到 401 或 429,那就不是安装问题了,分别看《Codex 401 Unauthorized 怎么解决》和《Codex 429 Too Many Requests 怎么解决》。

常见问题

Codex CLI 安装需要 Node.js 吗?

不一定。官方独立安装脚本(macOS/Linux 的 install.sh、Windows 的 install.ps1)不依赖 Node.js;只有走 npm 路线时才需要,AI Code With 文档要求 Node.js 18 及以上。

Windows 上应该用哪种方式安装?

优先用官方 PowerShell 安装脚本。如果你已经在用 Node.js,或者官方脚本下载不稳定,可以改用 npm 加国内镜像。两种方式装出来的是同一个 Codex CLI。

怎么升级 Codex CLI?

用什么方式装的,就用什么方式升级:安装脚本重新运行一次;npm 再执行一次 npm install -g @openai/codex;Homebrew 用 brew upgrade --cask codex。升级后用 codex --version 确认版本号变了。

安装成功了,但启动后要求登录,该选哪个?

有 ChatGPT 订阅就选 ChatGPT 登录,用的是订阅额度;想走 API 用量或在 CI 里用,就用 API Key。如果你想用 AI Code With 的 Key,先注册账号,再按 Codex 配置文档写入 Provider 配置。

没有图形界面的 Linux 服务器怎么登录?

官方推荐设备码登录:运行 codex login --device-auth,在另一台有浏览器的设备上打开链接并输入一次性代码。也可以在本机登录后,把 ~/.codex/auth.json 复制到服务器上的同一位置。

可以同时装多个版本吗?

不建议。npm、Homebrew 和安装脚本混装,很容易出现 PATH 里先找到旧版本的情况。选定一种方式,另一种卸载掉,再用 command -v codex 确认实际调用的是哪一个。

现在最新的 Codex CLI 是哪个版本?

以 2026-10-26 为准,npm 和官方安装脚本给出的都是 0.164.0。版本更新很快,自己查最准:npm view @openai/codex version 看线上最新版,codex --version 看本机版本。

官方安装脚本能装指定版本吗?

据官方 install.sh 脚本源码,它读取环境变量 CODEX_RELEASE(默认 latest)决定装哪个版本,读取 CODEX_INSTALL_DIR(默认 ~/.local/bin)决定装到哪里。需要固定版本时,用 npm 写明版本号更直观:npm install -g @openai/codex@0.164.0。

npm 路线到底要求哪个 Node.js 版本?

npm 包自己声明的下限是 Node.js 16(npm view @openai/codex engines 的输出是 { node: '>=16' }),AI Code With 文档建议 18 及以上。直接装当前 LTS 最省事。

怎么确认 Codex 走的是 AICodeWith?

运行 codex exec 时输出开头会打印 provider: 一行,显示 aicodewith 就对了。交互模式下也可以在会话里看当前模型和 Provider。

配置 Key 以后还需要 codex login 吗?

不需要。用 experimental_bearer_token 配好自定义 Provider 后,Codex 直接用这把 Key 发请求,我们实测没有执行 codex login 也能正常对话。

下一步

装好之后,建议按这个顺序继续:

查看 Codex 接入 AICodeWith 教程 →

创建 API Key →

资料来源

相关文章

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是 Vercel 在 2026 年 11 月 12 日发布的、给 Agent 用的行为(behaviors)库,版本 0.1.0-beta.1。行为写在与框架无关的 @ui-sdk/core 里,再由 React、Vue、Svelte、Solid 和 Web Components 适配器渲染。本文按官方文档整理它是什么、怎么安装、怎么给 Claude Code / Codex / Cursor 装 skill,并记录我们在测试机上的真实命令、耗时和输出。

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是 AWS 官方 2026 年 11 月 12 日(北京时间)正式发布的本地 AWS 模拟器,没有额外服务费、源码开放,不需要 AWS 账号,覆盖 200 多个服务。本文在 Debian 13 上实测 1.0.322:安装命令、AWS CLI 指向本地 endpoint 建 S3 桶和 DynamoDB 表、常见报错,以及让 Claude Code、Codex、Cursor 对着模拟器写代码跑测试的接法。

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是 pingdotgg 开源的编码 Agent 控制台,本身不带模型,调用你机器上已装好的 Claude Code、Codex、Cursor 等 CLI。本文在 Linux 上实测 T3 Code 0.1.9:讲清安装命令,Claude Code 和 Codex 先各自接上 AICodeWith API Key、再由 T3 Code 调用的配置方法,用 t3 thread 命令行跑通两端的过程,以及我们实际遇到的报错和解法。