如果你已经装好了 Codex，却卡在 401、invalid_api_key、model not found 这些报错上，不用怀疑人生。大概率不是你操作不对，而是几个配置细节藏得有点深，没被发现。

这篇东西不讲虚的。我们只保留那些真正能让你在10分钟内，从零开始在终端里正常启动 Codex，并且在 VSCode 里顺畅用起来的步骤。照着做就行。

这篇教程能帮你解决什么

简单来说，就这几样东西：

• 跨平台安装：Windows、macOS、Linux 全覆盖，一个不落。
• 讲清楚 auth.json 与 config.toml 这两个配置文件到底该怎么写，才不会报错。
• 给你可以直接复制粘贴的命令和配置模板。
• 附上常见报错排查清单，万一出问题，能快速定位到根儿上。

Windows 版本教程

先从大家最熟悉的 Windows 说起。

系统要求

• 操作系统：Windows 10 或 Windows 11
• Node.js 22+
• npm 10+
• 网络连接正常（这个不用多说）

安装步骤

说个小细节：Windows 用户记得先装个 Git Bash。去 Git 官网下载对应版本，一路“下一步”装好就行，这是很多命令行的基础环境。

1. 装 Node.js
   去 Node.js 官网，下载并安装最新的 LTS 版本。

2. 装 Codex
   打开 CMD 或 PowerShell，执行下面这条命令：
   npm install -g @openai/codex

3. 验证安装
   确认一下安装成功了没：
   codex --version

配置 API（核心中的核心）

这步是重头戏，大部分报错都出在这里。

1. 获取 Token173 API Key
   访问 token173.com，进入控制台 → API令牌 → 添加令牌。注意几个关键点：

   • 令牌分组：必须选 codex专属 这个分组，选错直接报错。
   • 令牌名称：随便起个名就行。
   • 额度：建议设为无限额度，省心。
   • 其他选项保持默认，直接点“新建”。

2. 配置文件位置
   路径是：C:\Users\你的用户名\.codex。如果没有 .codex 这个文件夹，就自己手动创建一个。里面需要放两个文件：auth.json 和 config.toml。

3. auth.json（直接复制）
   用记事本创建文件，写入以下内容：
   { "OPENAI_API_KEY": "sk-xxx" }
   把 sk-xxx 替换成你刚才在 token173.com 生成的那个 Key。

4. config.toml（直接复制）
   再创建一个文件，写入以下内容：
   model_provider = "token173"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.token173]
name = "token173"
base_url = "https://api.token173.com/v1"
wire_api = "responses"

启动 codex

关键一步：重启终端！重启终端！重启终端！这步不做，配置不会生效。

然后进入你的项目目录：
cd 你的项目目录
再敲：
codex

VSCode 插件

在扩展商店里直接搜索 codex，找到并安装就行，没什么特别的。

macOS 版本教程

Mac 用户这边走。

系统要求

• macOS 12+
• Node.js 22+
• npm 10+

安装 Node.js（推荐 Homebrew）

Homebrew 是 Mac 上最顺手的包管理器。执行这两步：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
然后：
brew install node

安装 codex

直接全局安装：
npm install -g @openai/codex
验证一下：
codex --version

配置 API

1. 获取 Token173 Key
   流程一样：token173.com → 控制台 → API令牌 → 添加令牌。分组务必选 codex专属。

2. 创建配置文件
   在终端里执行：
   mkdir -p ~/.codex
   然后：
   touch ~/.codex/auth.json ~/.codex/config.toml

3. auth.json
   用 vi 或其他编辑器打开：
   vi ~/.codex/auth.json
   写入：
   { "OPENAI_API_KEY": "sk-xxx" }

4. config.toml
   用 vi 打开：
   vi ~/.codex/config.toml
   写入的内容和 Windows 版完全一样：
   model_provider = "token173"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.token173]
name = "token173"
base_url = "https://api.token173.com/v1"
wire_api = "responses"

启动

直接在终端里敲：
codex

Linux 版本教程

Linux 用户也别着急，操作和 Mac 大同小异。

系统要求

• Ubuntu 20.04+ / Debian 10+ / CentOS 7+
• Node.js 22+

安装 Node.js

Ubuntu/Debian
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

CentOS/RHEL/Fedora
sudo dnf install nodejs npm

安装 codex

sudo npm install -g @openai/codex
验证：
codex --version

配置

操作和 Mac 完全一样：
mkdir -p ~/.codex
touch ~/.codex/auth.json ~/.codex/config.toml
然后往 auth.json 和 config.toml 里填入和上面完全一致的内容。

启动

codex

常见报错排查

问题到底出在哪？我们直击要害：

• 401 / invalid_api_key

  • 检查一下你的 Key 在复制时有没有多余的空格。
  • 确认令牌分组是否选的是 codex专属。
  • 最终确认一下，这个 Key 是不是在 token173.com 控制台生成的。

• model not found

  • 检查 config.toml 里的 model 字段，必须是 gpt-5-codex，不能写错。
  • base_url 必须是 https://api.token173.com/v1，多加个斜杠或漏个字母都不行。

• 连不上 / 超时

  • 确保你的网络能正常访问 token173.com。
  • 特别注意：不要给这个地址加任何袋里或镜像。