2026 最新 Codex CLI 国内安装与使用全攻略（Windows / Mac / Linux）

Codex CLI 适合直接在终端里完成代码阅读、修改、生成测试和自动化任务。第一次使用时，真正容易出错的往往不是安装命令，而是 Node.js 版本、配置文件位置、API Key 与接口地址没有对应上。

本文按“确认环境 -> 安装 CLI -> 写入 dkai-codex 配置 -> 做最小验证”的顺序说明。完成后再接入 VS Code 或桌面端，排错成本会低很多。

一、开始前先确认三件事

1. 电脑能安装 Node.js，并能打开终端。
2. 已准备好 dkai-codex 的 API Key，可从 dkai-codex 获取接入信息。
3. 使用的是当前用户的主目录，而不是随意在项目目录中创建 .codex。

建议先在终端检查 Node.js 与 npm：

node --version
npm --version

如果两条命令都能输出版本号，就可以继续。通常使用 Node.js LTS 版本更省心；Node.js 22 或更高版本是较稳妥的选择。

二、Windows：安装与首次检查

1. 安装 Node.js 和终端工具

从 Node.js 官网 下载 LTS 安装包，按默认选项完成安装。安装结束后重新打开 PowerShell，执行：

node --version
npm --version

如果你需要在 Windows 上使用 Bash 风格命令，可额外安装 Git for Windows；但安装 Codex CLI 本身使用 PowerShell 即可。

2. 安装 Codex CLI

在 PowerShell 执行：

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

第二条命令输出版本号，说明程序已加入命令行环境。若提示找不到 codex，先关闭当前终端并重新打开；仍不生效时，再检查 npm 全局目录是否被加入 PATH。

3. 创建配置目录

在 PowerShell 中运行：

New-Item -ItemType Directory -Force "$HOME\.codex"
notepad "$HOME\.codex\auth.json"
notepad "$HOME\.codex\config.toml"

Windows 的实际路径通常是：

C:\Users\你的用户名\.codex\

文件资源管理器默认可能隐藏该目录，不影响终端访问。

三、macOS：安装与首次检查

1. 使用 Homebrew 安装 Node.js

已安装 Homebrew 的用户可执行：

brew install node
node --version
npm --version

没有 Homebrew 时，也可以从 Node.js 官网 下载安装包。只需任选一种方式，不要混用两种安装来源。

2. 安装 Codex CLI

打开 Terminal，执行：

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

如果全局安装遇到权限错误，不要马上用 sudo 覆盖处理。先检查当前 Node.js 的安装方式与 npm 全局目录，统一由 Homebrew 或 Node.js 安装包管理通常更稳定。

3. 准备配置文件

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

后续内容与 Linux 使用同一套配置。

四、Linux：安装与首次检查

Linux 发行版较多，核心目标是获得可用的 Node.js 与 npm。Ubuntu / Debian 用户可先检查仓库中的版本：

sudo apt update
sudo apt install -y nodejs npm
node --version
npm --version

若发行版仓库中的版本过旧，请按 Node.js 官方文档安装 LTS 版本。Fedora、RHEL 或 Arch 用户应使用各自发行版的包管理器安装 nodejs 与 npm。

然后安装 CLI：

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

创建配置目录：

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

五、配置 dkai-codex API

Windows、macOS 与 Linux 的配置字段一致，只是文件路径不同。请用你自己的 Key 替换示例中的 sk-xxx，不要把真实 Key 提交到 Git 仓库、截图或发到公开讨论区。

1. 写入 auth.json

~/.codex/auth.json（Windows 为 %USERPROFILE%\\.codex\\auth.json）内容如下：

{
  "OPENAI_API_KEY": "sk-xxx"
}

2. 写入 config.toml

将下面内容保存到同目录的 config.toml：

model_provider = "dkai-codex"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.dkai-codex]
name = "dkai-codex"
base_url = "https://codex.dakeai.cc/v1"
wire_api = "responses"
requires_openai_auth = true

这里最重要的是两项：

• model_provider 与 [model_providers.dkai-codex] 的名称必须相同。
• base_url 使用 https://codex.dakeai.cc/v1，不要混入其他服务商的地址。

model_reasoning_effort 可以按任务调整为 low、medium 或 high。先用默认的 high 完成验证，确认稳定后再根据速度与成本需要调整。

六、首次启动与最小验证

配置保存后，关闭并重新打开终端，进入一个可以测试的项目目录：

cd your-project-folder
codex

打开后先发送一个范围很小的任务，例如：

请只读取当前目录，列出主要文件及其用途，不要修改任何文件。

能获得正常回答，说明安装、Key 与接口配置已连通。再需要命令行方式执行任务时，可先查看帮助：

codex --help

更多常用命令和场景可阅读：Codex CLI 常用命令详解（含示例） 。

七、VS Code 和桌面端如何复用配置

完成上述用户级配置后，VS Code 中的 Codex 扩展通常能读取同一套配置。安装扩展、定位设置和最小验证步骤见：VSCode 使用 Codex 教程 。

使用 Codex Desktop App 时，也应先确认它读取的用户配置路径正确。桌面端安装、界面语言与 API Key 设置请看：Codex Desktop App 怎么安装和使用？ 。

八、常见问题排查顺序

codex: command not found 或“不是内部或外部命令”

1. 运行 node --version 和 npm --version，确认 Node.js 正常。
2. 重新执行 npm install -g @openai/codex。
3. 关闭终端并重新打开，检查 PATH 是否刷新。

401 Unauthorized

1. 检查 auth.json 是否是合法 JSON。
2. 确认 OPENAI_API_KEY 已替换为实际 Key，没有保留 sk-xxx。
3. 确认 Key 权限与模型访问范围符合当前平台要求。

请求超时、连接中断或偶发失败

1. 先用一个简短任务反复验证，而不是直接运行复杂项目任务。
2. 确认 base_url 为 https://codex.dakeai.cc/v1。
3. 将并发和任务范围降到最小，记录具体报错后再逐项处理。

关于国内网络场景下的稳定性评估与排查方法，可继续阅读：Codex API 国内可用方案与稳定性排查 。

修改配置后仍像没有生效

最常见的原因是文件放错目录，或终端仍在使用旧进程。确认配置文件确实位于当前用户的 .codex 下，然后完全关闭并重新打开终端或 IDE，再进行最小验证。

九、建议的使用节奏

首次接入时，不要一开始就让 Codex 改动整个仓库。推荐先完成下面四步：

1. 执行 codex --version，确认 CLI 安装正常。
2. 检查 auth.json 与 config.toml 的路径和内容。
3. 用只读、小范围任务测试响应。
4. 再逐步让它完成测试、重构或批量修改等复杂工作。

按这个顺序操作，大多数安装和配置问题都能在早期定位。若需要更简洁的一键安装方案，可回到 Codex CLI 安装教程（国内版） 。