Codex CLI + VS Code 组合教程：从 Node.js 安装到接入国内中转站

刚开始用 Codex 时，我踩过一个很典型的坑：只装了 VS Code，以为新版编辑器已经把 Codex 集成好了，打开后却怎么也找不到入口；后来又直接执行 npm install，结果终端提示找不到 npm。

实际上，VS Code、Codex CLI 和 Codex 扩展是三个不同的东西。比较顺手的组合是：VS Code 负责看代码和管理文件，Codex 扩展负责编辑器内交互，Codex CLI 负责在终端里执行工程任务。

这篇以 Windows 10/11 为例，先安装 Node.js、npm 和 Codex CLI，再配置国内可用的统一 API 网关。确认 Codex 能正常工作后，我们直接在 Codex CLI 里用中文下达任务，让它继续安装 VS Code、中文语言包和官方 Codex 扩展，并重启验证。

本文实测和核对时间：2026 年 7 月 16 日。软件更新较快，如果界面有小变化，以当前版本显示为准。

一、先把几个容易混淆的概念说清楚

名称	作用	是否必须
Node.js	JavaScript 运行环境	安装 Codex CLI 时需要
npm	Node.js 的包管理工具	随 Node.js 一起安装，不用单独下载
VS Code	代码编辑器	推荐安装
Codex CLI	在终端中读取、修改项目并运行命令	本文核心工具
Codex 扩展	在 VS Code 侧边栏内使用 Codex	推荐安装，但不是 CLI 的替代品
中文语言包	把 VS Code 界面切换成简体中文	按个人习惯安装

最新版 VS Code 已经自带 Codex 插件了吗？

没有。

截至本文核对时，最新版 VS Code 并不会默认预装 OpenAI Codex 扩展，需要自己安装。VS Code 对 GitHub Copilot 的集成，不代表它自带 Codex，这两个产品不要混为一谈。

还有一个容易让人疑惑的地方：Codex 扩展当前的扩展 ID 是 openai.chatgpt，它在扩展市场中的完整名称是 Codex -- OpenAI's coding agent ，发布者是 OpenAI。用命令安装时应以扩展 ID 为准。

二、安装 Node.js 和 npm

Codex CLI 通过 npm 安装，所以第一步不是装 Codex，而是先准备 Node.js。

国内网络可以访问 Node.js 中文网：

https://nodejs.cn/download/

普通 Windows 用户下载 LTS（长期支持版） 的 .msi 安装包即可。安装过程保持默认选项，尤其不要取消"添加到 PATH"一类的选项。

需要注意：npm 会随 Node.js 一起安装，不需要再找一个 npm 安装包。

安装结束后，关闭旧终端，重新打开 PowerShell，依次执行：

node -v
npm -v

两条命令都能返回版本号，说明环境准备完成。

如果提示"无法将 node 或 npm 识别为命令"，先重开 PowerShell；仍然不行，再重新安装 Node.js，并检查系统 PATH 中是否有 Node.js 的安装目录。

三、安装 Codex CLI

Node.js 和 npm 正常后，在 PowerShell 中执行：

npm install -g @openai/codex@latest

安装完成后检查版本：

codex --version

以后更新 Codex CLI 仍然使用同一条命令：

npm install -g @openai/codex@latest

如果提示没有权限，可以先用管理员身份运行 PowerShell。若安装成功后仍提示找不到 codex，重开终端，并检查 npm 全局目录是否已经加入 PATH：

npm config get prefix

四、国内使用为什么还需要配置 API 接入

工具装好只代表本地环境完成了，真正调用模型时还涉及网络、账号认证、API Key、Base URL 和模型名。很多人卡住的地方不是 Codex 不会用，而是请求链路没有跑通。

我自己常用的一个 AI API 统一接入入口是：

https://kkflow.org

KKFlow 的作用是把 Key、模型、接口地址和用量放到同一个入口管理。配置 Codex 或其他 OpenAI 兼容客户端时，常用 Base URL 是：

https://kkflow.org/v1

模型列表测试接口是：

https://kkflow.org/v1/models

先登录 KKFlow 后台创建 API Key。真实 Key 不要截图发到文章、群聊或 Git 仓库，本文统一用 sk-你的KKFlow密钥 代替。

五、给 Codex CLI 配置 KKFlow

Codex 的主要配置放在用户目录下的 .codex 文件夹中。Windows 对应路径是：

%USERPROFILE%\.codex\

这次需要准备两个文件：

文件	作用
.codex\config.toml	模型、Provider、Base URL、推理强度和上下文参数
.codex\auth.json	保存 API Key

1. 配置 config.toml

在 PowerShell 中创建配置目录并打开 config.toml：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

写入下面这份 KKFlow 配置：

model_provider = "kkflow"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"

disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true

model_context_window = 400000
model_auto_compact_token_limit = 360000

[model_providers.kkflow]
name = "KKFlow"
base_url = "https://kkflow.org/v1"
wire_api = "responses"
requires_openai_auth = true

这份配置各字段的作用如下：

配置项	作用
model_provider	指定使用下面定义的 kkflow Provider
model	Codex 默认使用的模型
review_model	执行代码审查时使用的模型
model_reasoning_effort	推理强度，xhigh 更适合复杂工程任务，但响应时间和消耗也会增加
disable_response_storage	不请求服务端存储响应
network_access	允许 Codex 在任务需要时访问网络
windows_wsl_setup_acknowledged	记录已经了解 Windows/WSL 环境提示
model_context_window	按 400000 Token 配置模型上下文窗口
model_auto_compact_token_limit	上下文接近 360000 Token 时自动压缩，给后续输出预留空间
base_url	KKFlow 的 OpenAI 兼容 API 地址
wire_api	使用 Responses API 协议
requires_openai_auth	从 Codex 认证信息中读取 OPENAI_API_KEY

为什么供应商要写成 kkflow

配置中的这两处名称必须对应：

model_provider = "kkflow"

[model_providers.kkflow]

这里的 kkflow 是我们给这条自定义模型供应商配置起的内部标识。它告诉 Codex：不要使用内置的 OpenAI 或 Azure Provider，而是读取 [model_providers.kkflow] 下面定义的 base_url、接口协议和认证方式，把请求发送到 KKFlow。

这个标识也可以换成其他名称，但上下两处必须完全一致。例如写成 model_provider = "myapi"，下面就必须同时改成 [model_providers.myapi]。为了让配置一眼就能看出实际接口来源，本文直接使用 kkflow。

使用这类非 OpenAI、非 Azure 的自定义 Provider 时，如果服务端没有提供 Codex 官方链路使用的远程上下文压缩能力，Codex 会在本地完成上下文整理和自动压缩。配合：

model_context_window = 400000
model_auto_compact_token_limit = 360000

当对话上下文接近设定阈值时，Codex 会先在本地压缩较早的对话和任务信息，再继续请求模型。这样长任务不容易因为上下文越来越大而突然中断，整个过程通常会更连续、流畅。

需要注意，触发本地压缩的关键是当前使用的是自定义 Provider，以及对应接口是否支持远程压缩能力，并不是单纯把供应商名称改成 kkflow 就能获得加速。压缩是否流畅还会受到模型速度、网络情况、上下文大小和中转接口负载影响。

这里的 gpt-5.6-sol 按本文实测配置填写。模型上下架和分组权限可能变化，如果启动时出现 model not found，进入 KKFlow 后台复制当前实际可用的模型 ID，并同时替换 model 和 review_model，不要继续照抄已经失效的名称。

model_context_window 和 model_auto_compact_token_limit 也要与模型实际能力匹配。如果后台模型的上下文没有 400000 Token，应按实际规格调低，建议让自动压缩阈值比上下文上限低 10% 左右。

2. 配置 auth.json

继续在 PowerShell 中打开认证文件：

notepad "$env:USERPROFILE\.codex\auth.json"

写入下面的 JSON，把占位符替换为自己在 KKFlow 后台创建的 API Key：

{
  "OPENAI_API_KEY": "sk-你的KKFlow密钥"
}

保存后，.codex 目录结构应该是：

.codex\
├── config.toml
└── auth.json

auth.json 里保存的是敏感凭据。不要把它上传到 Git 仓库，不要在 CSDN 截图中展示真实内容，也不要把真实 Key 发到评论区。文章截图可以把值统一替换成 sk-xxxxxx。

3. 首次启动 Codex CLI 并使用中转 Key 登录

配置文件保存后，直接在一个空目录中首次启动 Codex CLI：

New-Item -ItemType Directory -Force "$env:USERPROFILE\codex-setup" | Out-Null
Set-Location "$env:USERPROFILE\codex-setup"
codex

首次启动时，如果 Codex 显示登录方式选择界面，选择使用 API Key 登录，然后粘贴在 KKFlow 后台创建的中转 Key。不要选择 OpenAI 账号登录，否则不会使用前面配置的 KKFlow 接口。

如果已经按照上一节创建好 .codex\auth.json，Codex 通常会直接读取其中的 OPENAI_API_KEY，不再重复询问。进入 Codex 对话界面并正常回复后，就说明首次登录和中转配置已经可以使用，可以继续让 Codex 安装 VS Code。

粘贴 Key 时不要录屏或截图，也不要把真实 Key 写进教程、评论区或项目文件。

六、直接让 Codex CLI 安装 VS Code 和中文语言包

这里才是本文所说的"通过 Codex CLI 安装"：不是自己逐条执行安装命令，而是在 Codex CLI 的对话界面里直接描述目标，让 Codex 检查环境、调用 Windows 安装工具、安装扩展并验证结果。

如果电脑里已经打开了 VS Code，先保存正在编辑的文件并关闭窗口，避免重启时丢失未保存内容。然后在刚才启动的 Codex CLI 中直接发送下面这段话：

请帮我在这台 Windows 电脑上完成以下任务：

1. 先检查是否已经安装 VS Code，以及 code 命令是否可用。
2. 如果没有安装，优先使用 winget 安装 Microsoft Visual Studio Code 用户版，
   软件包 ID 使用 Microsoft.VisualStudioCode；如果需要管理员权限，先向我说明并请求确认。
3. 安装完成后刷新当前终端能够读取的 PATH；如果当前会话无法刷新，告诉我需要重开终端。
4. 使用 code 命令安装简体中文语言包，扩展 ID：
   MS-CEINTL.vscode-language-pack-zh-hans。
5. 检查是否已安装官方 Codex 扩展。如果没有，请安装
   Codex -- OpenAI's coding agent，发布者 OpenAI，扩展 ID：openai.chatgpt。
6. 将 VS Code 显示语言设置为 zh-cn。不要修改我的其他 VS Code 设置，
   不要卸载或禁用已有扩展。
7. 完成后启动或重新启动 VS Code，并执行以下验证：
   - code --version 能返回版本号；
   - code --list-extensions 中能找到中文语言包；
   - 能找到 openai.chatgpt；
   - VS Code 重启后界面语言为简体中文。
8. 最后把实际执行过的命令、安装结果和验证结果汇总给我。

请先检查环境，再逐步执行。遇到需要提权、关闭程序或存在多个安装方案时，先询问我。

Codex 会自动完成环境检查、软件安装、扩展安装和重启验证。执行过程中如果弹出提权或命令确认，应先看清操作内容再允许执行；最后确认 VS Code 可以正常打开、界面已经切换为简体中文，并且活动栏中出现 Codex 入口即可。

确认安装的是官方 Codex 扩展

截至本文核对时，VS Code 不会默认预装 Codex。Codex CLI 检查或安装扩展时，应认准下面三项：

项目	正确信息
扩展名称	Codex -- OpenAI's coding agent
发布者	OpenAI
扩展 ID	openai.chatgpt

扩展 ID 不区分大小写，OpenAI.chatgpt 和 openai.chatgpt 都能被 VS Code 识别。命令和验证结果中通常会规范化显示为小写的 openai.chatgpt。

七、首次打开 VS Code 并验证 Codex

Codex 完成安装并重新打开 VS Code 后，第一次进入工作区可能会看到"你处于受限模式下"的提示。这是 VS Code 的工作区信任保护，不是 Codex 安装失败。

如果打开的是自己创建或确认安全的文件夹，点击左侧"在受信任的文件夹中"区域里的 信任。信任后，运行任务、调试、工作区设置和扩展能力才会完整启用。来源不明的项目不要直接信任。

完成信任后回到 VS Code 主界面。第二张图中可以看到三个结果：

• VS Code 菜单和欢迎页已经显示为简体中文；
• 右侧已经出现官方 Codex 面板；
• 在 Codex 面板发送"你好"后可以收到正常回复。

看到这个界面，就说明 VS Code、中文语言包和官方 Codex 扩展都已经安装成功。后面直接打开自己的文件夹，在右侧 Codex 面板描述任务即可，不需要再输入项目目录命令。

Codex 能提高读项目、改文件和运行验证的效率，但最终代码仍然需要开发者审核。

八、常见问题排查

问题	优先检查
node 或 npm 找不到	Node.js 是否安装，安装后是否重开终端，PATH 是否生效
codex 找不到	是否全局安装成功，npm 全局目录是否在 PATH
Codex 扩展安装后没图标	重载 VS Code 窗口，检查扩展是否被禁用
401 Unauthorized	API Key 是否正确、是否复制了空格、额度是否可用
404 或一直重试	Base URL 是否为 https://kkflow.org/v1，接口是否支持 Responses
model not found	模型 ID 是否与 KKFlow 后台当前显示完全一致
CLI 正常、扩展不能用	两者登录与接口配置可能不同，先检查扩展自身设置

还可以先测试 Key 和模型列表接口：

curl.exe "https://kkflow.org/v1/models" `
  -H "Authorization: Bearer sk-你的KKFlow密钥"

注意：带真实 Key 的命令不要截图或公开粘贴。

九、完整流程汇总

先手动安装 Node.js，再用 npm 安装 Codex CLI：

node -v
npm -v
npm install -g @openai/codex@latest
codex --version

然后配置 KKFlow，启动 codex 并把本文第六部分的完整中文任务发给它。由 Codex CLI 检查并安装 VS Code、简体中文语言包和官方 Codex 扩展，再启动 VS Code 完成验证。

安装验证通过后，在 VS Code 欢迎页点击"打开文件夹"，选择自己的项目，就可以在右侧 Codex 面板中直接描述任务。

整个流程可以概括成一句话：先用 Node.js 和 npm 装好 Codex CLI，通过 KKFlow 跑通模型调用，再直接告诉 Codex 安装 VS Code、中文语言包和官方 Codex 扩展，最后重启并验证。

如果配置时报错，先不要反复卸载。按 Node/npm → Codex 版本 → Base URL → API Key → 模型 ID → winget → code 命令 → 扩展 ID 的顺序检查，通常很快就能定位问题。

参考资料

• Node.js 中文网下载页：https://nodejs.cn/download/
• npm 中文网"下载和安装 Node.js 和 npm"：https://npm.nodejs.cn/downloading-and-installing-node-js-and-npm/
• KKFlow 主站及后台：https://kkflow.org
• 本文安装命令、扩展 ID 和"是否预装"的结论已于 2026 年 7 月 16 日在 Windows 环境核对；VS Code 实测版本为 1.126.0。