Codex CLI 安装及配置卸载教程

Codex CLI 安装与配置教程

本教程适用于 Windows、macOS 和 Linux，包含 Codex CLI 的安装、API 配置、启动、升级以及卸载方法。

一、环境要求

安装 Codex CLI 前，请确保电脑满足以下要求：

• Windows 10 / Windows 11、macOS 或主流 Linux 系统
• Node.js 22+
• npm 10+
• 正常的网络连接

检查 Node.js 和 npm：

node --version
npm --version

如果能够正常显示版本号，即可继续安装。

二、安装 Node.js

Windows

访问：Node.js 官网

下载最新 LTS 长期支持版本并完成安装。

Windows 用户同时建议安装 Git：Git 官网

安装完成后重新打开 CMD 或 PowerShell。

macOS

推荐直接从官网下载：Node.js 官网

也可以使用 Homebrew：

brew install node

Linux

Ubuntu / Debian：

sudo apt update
sudo apt install nodejs npm

Fedora：

sudo dnf install nodejs npm

CentOS / RHEL：

sudo yum install nodejs npm

Arch Linux：

sudo pacman -S nodejs npm

如果 Linux 系统软件源提供的 Node.js 版本低于要求，请使用 NodeSource、nvm 等方式安装较新的 Node.js。

安装完成后统一检查：

node --version
npm --version

三、安装 Codex CLI

Windows、macOS 和 Linux 安装命令相同：

npm install -g @openai/codex

安装完成后检查：

codex --version

能够正常显示 Codex 版本号，即代表安装成功。

macOS / Linux 如果出现 EACCES 或 permission denied，通常是 npm 全局目录权限问题，建议检查 Node.js/npm 的安装方式以及全局目录权限。

四、获取 API Token

访问：NineClaw 依次进入：控制台 → API密钥 → 创建API密钥

创建 API密钥 时设置：

• 令牌名称可以自行填写
• 额度根据自己的需求设置
• 其他选项保持默认

创建完成后复制 API Key，例如：

nc-xxxxxxxxxxxxxxxx

请妥善保存 API Key，不要公开分享。如果 API Key 已经泄露，请立即删除旧 Token 并重新生成。

五、创建 Codex 配置文件

Codex 的配置文件保存在当前用户目录下的 .codex 文件夹中，手动编辑目录下的（config.toml 和 auth.json）这两个文件

不同系统的文件路径如下：

找不到的话可自行在 .codex 目录下创建这两个文件，Windows 用户请注意文件扩展名，确保文件不是 auth.json.txt 或 config.toml.txt。

macOS / Linux 可运行以下代码创建：

mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml

六、修改 Codex 配置文件

三个系统需要填写的配置内容完全相同。

1. 配置 auth.json

打开 .codex 目录中的：

auth.json

填写：

{
  "OPENAI_API_KEY": "nc-xxxxxxxxxxxxxxxx"
}

将：

nc-xxxxxxxxxxxxxxxx

替换成你在 NineClaw 创建的真实 API Key。

macOS / Linux 可以直接编辑：

nano ~/.codex/auth.json

2. 配置 config.toml

打开：

config.toml

填写：

model_provider = "nineclaw"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.nineclaw]
name = "nineclaw"
base_url = "https://api.nineclaw.cc/v1"
wire_api = "responses"
requires_openai_auth = true

macOS / Linux 可以直接编辑：

nano ~/.codex/config.toml

配置参数说明

支持的模型

八、启动 Codex

配置完成后，建议完全关闭终端并重新打开。

然后进入需要使用 Codex 的项目目录：

cd your-project-folder

启动 Codex：

codex

如果能够正常进入 Codex CLI，即代表安装和配置完成。

九、常用命令

启动 Codex：

codex

查看版本：

codex --version

查看帮助：

codex --help

升级 Codex：

npm install -g @openai/codex@latest

十、常见问题

1. 401 / Invalid token

如果出现：

401 Unauthorized
Invalid token

通常代表 API Key 无效、过期或配置错误。

检查：

.codex/auth.json

确认：

{
  "OPENAI_API_KEY": "nc-xxxxxxxxxxxxxxxx"
}

中的 API Key 是当前有效的 Token。

如果仍然出现 401，可以重新创建 API Token 并替换旧 Token。

2. model not found

如果出现：

model not found

检查：

model = "gpt-5.5"

模型名称必须与 API 服务商当前提供的模型 ID 完全一致。

3. 找不到 codex 命令

Windows PowerShell：

Get-Command codex

macOS / Linux：

which codex

如果已经安装 Codex，但仍然找不到命令，通常需要检查 npm 全局安装目录和 PATH 环境变量。

4. 检查是否安装了多个 Codex

Windows PowerShell：

Get-Command codex -All

macOS / Linux：

which -a codex

如果出现多个安装路径，说明系统中可能存在多套 Codex，建议只保留一套正常工作的版本。

十一、卸载 Codex CLI

npm 安装

Windows、macOS、Linux 通用：

npm uninstall -g @openai/codex

Homebrew 安装（macOS）

brew uninstall --cask codex

独立安装（macOS / Linux）

rm -f ~/.local/bin/codex
rm -rf ~/.codex/packages/standalone

十二、彻底清理 Codex 配置

**注意：**删除 .codex 目录会同时清除登录凭证、API 配置、第三方 Provider 配置、历史记录和缓存。如果只是普通升级或重新安装 CLI，不需要执行这一步。

Windows PowerShell

Remove-Item -Recurse -Force "$env:USERPROFILE\.codex"

macOS / Linux

rm -rf ~/.codex

十三、验证是否卸载成功

Windows PowerShell

Get-Command codex -All -ErrorAction SilentlyContinue
codex --version

macOS / Linux

which codex
codex --version

如果提示：

command not found

或者 Windows 出现：

The term 'codex' is not recognized

说明 Codex CLI 已经卸载完成。

如果需要重新安装：

npm install -g @openai/codex

建议先确认：

codex --version

能够正常运行，再重新配置 auth.json 和 config.toml。