Codex 安装与使用教程（2026 最新）：一键安装、npm 国内镜像、config.toml 接第三方 API

想接第三方 API，往下翻到「接第三方 API：两种写法」。本文所有命令都在 2026 年 10 月 15 日用最新的 Codex CLI 0.162.1 实测过。

先看这张表：你该用哪种装法

装出来的是同一个程序。只选一种装，装了两种以后，终端里到底运行的是哪一个，取决于 PATH 的先后顺序，容易乱。

Codex 是什么

Codex 是 OpenAI 出的 AI 编程助手。它在你的电脑上读项目代码、改文件、运行命令，你用中文描述要做什么，它自己规划步骤去完成，和 Claude Code 是同一类工具。

它有几种用法：

• 命令行（Codex CLI）：在终端里用，功能最全，本文主要讲这个。
• 编辑器插件：VS Code、Cursor、Windsurf 里装 Codex 插件，在侧边栏用。
• ChatGPT 桌面应用：2026 年起原来的 Codex 桌面版并进了 ChatGPT 桌面应用，在里面直接用 Codex。
• 云端：在 chatgpt.com 上把任务交给云端跑。

2026 年和老教程不一样的地方：

• 官方出了一键安装脚本，不用再先装 Node.js。
• 配置里的 wire_api = "chat" 已经不能用了。
• 老写法 [profiles.xxx] 从 0.134.0 起也失效了。

网上很多教程还停在旧版本，照着做会报错，下文「报错」一节有原文。

安装前准备

• 系统：macOS、Linux、Windows 都行，Windows 上可以原生运行，也可以装在 WSL2 里。
• 不需要先装 Node.js：一键安装装的是独立程序。只有选 npm 方法才需要 Node.js，建议用 22 版。
• 想清楚怎么付费：
  • ChatGPT 免费版、Go 版：只能在 ChatGPT 桌面应用里有限地用。
  • 命令行和编辑器插件：需要 Plus（每月 20 美元）及以上订阅。
  • 不想订阅：用 OpenAI 的 API Key 按用量付费，或者接兼容的第三方 API 服务。

方法一：官方一键安装（推荐）

Mac / Linux，打开「终端」运行：

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

我们在 Mac 上实测 14 秒装完，输出是这样的：

==> Installing Codex CLI
==> Detected platform: macOS (Apple Silicon)
==> Resolved version: 0.162.1
==> Downloading Codex CLI
==> Installing standalone package to ~/.codex/packages/standalone/releases/0.162.1-aarch64-apple-darwin
==> Current terminal: export PATH="~/.local/bin:$PATH" && codex
==> Future terminals: open a new terminal and run: codex
==> PATH was added to ~/.zprofile
Codex CLI 0.162.1 installed successfully.

注意倒数第二行：安装脚本已经自动把 ~/.local/bin 加进了 ~/.zprofile，所以关掉终端、重新打开一个，codex 命令就能用了。如果你不想重开，按它提示的那条 export PATH=… 在当前窗口运行一次也行。

Windows，打开 PowerShell 运行：

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

-ExecutionPolicy ByPass 是官方命令自带的，作用是只对这一次安装放开 PowerShell 的脚本限制，不会改你电脑的设置。Windows 上程序装在 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin。

方法二：npm 安装（国内网络推荐）

一键安装要从 chatgpt.com 和 GitHub 下载，国内网络常常下不动，用 npm 国内镜像最省事。先确认装了 Node.js：

node -v

然后：

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

实测 2 秒装完，国内镜像上的版本和官方同步（同样是 0.162.1）：

added 2 packages in 2s

「2 个包」一个是 @openai/codex 本身，一个是你电脑对应的程序本体（比如 Apple 芯片 Mac 是 @openai/codex-darwin-arm64）。如果第二个没装上，运行时会报 spawn … ENOENT，见下文报错 3。

方法三：Homebrew（Mac）

brew install --cask codex

Homebrew 上的版本更新得很及时，我们查的时候也是最新的 0.162.1。以后用 brew upgrade --cask codex 更新。

装完检查

1. 看版本号。打开一个新终端窗口：

codex --version

codex-cli 0.162.1

2. 体检。运行 codex doctor，它会逐项检查安装、配置、登录、网络、Git 等，不会启动对话。刚装好还没登录时，大概是这样：

Codex Doctor v0.162.1 · macos-aarch64
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
  ✓ runtime      standalone (…)
  ✓ install      consistent
  ✓ search       file exists (bundled …)
  ✓ git          git executable found; execution not verified
  ✓ config       loaded

✗ auth 是因为还没登录，下一步就解决。打 ✓ 的项都正常；有 ✗ 或 ⚠ 的，后面会写原因和建议。

第一次使用：两种登录方式

进入项目文件夹，启动 Codex：

cd 你的项目文件夹
codex

第一次启动会让你登录，有两种选择：

1. 用 ChatGPT 账号登录（Sign in with ChatGPT）：浏览器里登录，用的是你 ChatGPT 订阅里包含的额度。
2. 用 API Key 登录：按用量付费。OpenAI 官方的 Key 在 OpenAI 开放平台创建；第三方服务商发的 Key 也走这条路，见下一节。

随时可以用 codex login status 查看当前是哪种登录，codex logout 退出登录。

接第三方 API：两种写法

Codex 支持把请求发到 OpenAI 以外的服务。前提是服务商支持 OpenAI 的 Responses 接口（/v1/responses）。新版 Codex 只会走这个接口，只提供 Chat Completions（/v1/chat/completions）的服务接不上。

配置文件在 ~/.codex/config.toml（Windows 是 C:\Users\你的用户名\.codex\config.toml），没有就新建一个。下面以 api.foo 为例，换成别家只要改地址和密钥。

写法一：改地址 + 用 API Key 登录（最省事）

适合只用第三方服务、不用 ChatGPT 账号的人。config.toml 里只写两行：

model = "gpt-6.1-sol"
openai_base_url = "https://api.foo/v1"

然后把密钥登录进去（Mac / Linux）：

printf 'sk-你的密钥' | codex login --with-api-key

Windows PowerShell：

"sk-你的密钥" | codex login --with-api-key

看到 Successfully logged in 就好了。密钥保存在 ~/.codex/auth.json 里，命令行和 VS Code 插件都能用。

写法二：单独的配置文件，和 ChatGPT 登录随时切换

适合平时用 ChatGPT 订阅、偶尔想换到第三方服务的人。

1. 新建 ~/.codex/apifoo.config.toml（文件名里的 apifoo 可以随便起）：

model = "gpt-6.1-sol"
model_provider = "apifoo"

[model_providers.apifoo]
name = "api.foo"
base_url = "https://api.foo/v1"
env_key = "APIFOO_API_KEY"

2. 把密钥设成环境变量 APIFOO_API_KEY。Mac 写进 ~/.zshrc：

echo 'export APIFOO_API_KEY="sk-你的密钥"' >> ~/.zshrc && source ~/.zshrc

Windows PowerShell 运行下面这行，然后重新打开终端：

setx APIFOO_API_KEY "sk-你的密钥"

3. 想用第三方服务时加上 --profile，不加就还是原来的 ChatGPT 登录：

codex --profile apifoo

怎么确认配好了

运行 codex，启动信息里能看到当前的模型和 provider。我们故意用一把错误的密钥测试这两种写法，Codex 都把请求发到了 api.foo，并收到了 api.foo 的回复：

model: gpt-6.1-sol
provider: apifoo
ERROR: unexpected status 401 Unauthorized: 无效的令牌 (request id: …), url: https://api.foo/v1/responses

url 是服务商的地址、报错是服务商返回的，说明配置已经生效，剩下的只是密钥对不对。换成正确的密钥就能正常用。

几点说明：

• 地址要带 /v1。Codex 会在后面直接接 /responses，大多数服务商要求完整的 …/v1/responses。api.foo 两种写法都能用，其他家不一定。
• model 要写服务商支持的模型名，以服务商的模型列表为准。
• 项目里的 .codex/config.toml 不能改服务商。地址、model_provider 这些只能写在用户目录的配置里，写在项目里会被忽略并提示警告。
• 写法二的环境变量只对从终端启动的程序有效。在 Mac 上直接从程序坞打开的 VS Code，可能读不到 ~/.zshrc 里的变量，插件里报「Missing environment variable」时，改用写法一。

中转站要支持什么接口、每个设置项是干什么的、怎么接 DeepSeek 官方 API、换服务商后历史记录不见了怎么办，见 Codex 接中转站 / 第三方 API 配置教程。

常见报错与解决办法

1. command not found: codex

一键安装已经把路径写进了 ~/.zprofile，但已经打开的终端窗口不会自动生效。关掉终端重新打开就好。用的是 bash 的 Linux，确认 ~/.bashrc 或 ~/.profile 里有 export PATH="$HOME/.local/bin:$PATH"。

npm 装的，检查 npm config get prefix 显示的目录下的 bin 是否在 PATH 里。

2. 装了两个 Codex，运行的不是你想要的那个

WARNING: Multiple managed Codex installs can be ambiguous because PATH order decides which one runs.

用 which -a codex（Windows 用 where.exe codex）看看装了几个，保留一个，把其他的卸载掉（卸载命令见文末）。codex doctor 里的 install method 一行也会写当前运行的是哪种安装。

3. 运行时报 spawn … ENOENT

Error: spawn …/node_modules/@openai/codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin/codex/codex ENOENT

这是我们自己电脑上真实遇到过的：npm 装的 Codex 程序本体丢了，常见于版本太旧或者升级中断。重新装一遍最新版就好：

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

4. wire_api = "chat" is no longer supported

Error loading config.toml: `wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.

照着旧教程写了 wire_api = "chat"。新版只支持 Responses 接口，把这一行删掉（默认就是 responses）。如果删掉后服务商返回 404，说明它不支持 Responses 接口，只能换服务商。

5. --profile cannot be used while config.toml contains legacy …

Error loading config.toml: --profile `apifoo` cannot be used while …/config.toml contains legacy `profile = "apifoo"` or `[profiles.apifoo]` config; move those settings into …/apifoo.config.toml and remove the legacy profile selector/table.

旧教程把配置写在 config.toml 里的 [profiles.apifoo] 下面，0.134.0 起不支持了。按报错说的，把这段内容挪到单独的 ~/.codex/apifoo.config.toml 里（去掉 [profiles.apifoo] 这一行，内容顶格写），再从 config.toml 里删掉。写法见上文写法二。

6. string values must be quoted

Error loading config.toml:
…/config.toml:1:9: string values must be quoted, expected literal string
  |
1 | model = gpt-6.1-sol
  |         ^^^^^^^^^^^

TOML 格式要求文字两边加英文双引号：model = "gpt-6.1-sol"。报错会指出第几行第几个字符，照着改就行。也要注意别用中文引号。

7. Missing environment variable: APIFOO_API_KEY

用的是写法二，但 Codex 读不到环境变量：没设置、设置后没重新打开终端，或者程序不是从终端启动的。照写法二第 2 步重新设置并重开终端；在编辑器插件里用的话，改用写法一。

8. 401 Unauthorized

ERROR: unexpected status 401 Unauthorized: 无效的令牌 …

请求到了服务商，但密钥不对：复制漏了字符、多了空格，或者把 A 家的密钥填到了 B 家的地址。重新复制密钥，用写法一的登录命令再登录一次。

9. 模型不可用

不同服务商的报错文字不一样。以 api.foo 为例：

分组 default 下模型 xxx 无可用渠道（distributor）

意思是这个模型名在服务商那里不存在或没开通。到服务商的模型列表里核对模型名，改 config.toml 里的 model，或者在会话里用 /model 换一个。

上手：常用操作

动手之前先用 Git 提交一次，改坏了随时可以退回去。

更新与卸载

更新：

卸载：

# npm
npm uninstall -g @openai/codex

# Homebrew
brew uninstall --cask codex

# 一键安装（Mac / Linux）：删掉程序和安装包
rm -f ~/.local/bin/codex ~/.local/bin/codex-code-mode-host
rm -rf ~/.codex/packages/standalone

一键安装还在 ~/.zprofile 里加了以 # >>> Codex installer >>> 开头、# <<< Codex installer <<< 结尾的几行，可以手动删掉。

卸载程序不会删除你的配置、登录信息和对话记录，它们都在 ~/.codex 文件夹里。想彻底清干净就删掉这个文件夹（删之前确认没有要留的东西）。

相关阅读

• Claude Code 安装教程：Mac、Windows、Linux 三种装法与国内常见问题
• API 中转站是什么？怎么选不踩坑