Windows 11 下安装 Codex CLI，并配置独立 API 模式与桌面端分离使用

1. 目的

本文记录在 Windows 11 中安装 Node.js、npm、Codex CLI，并配置一个独立的终端 API 环境，使其与 Codex 桌面端账号环境分离。

目标工作流如下：

Codex 桌面端 → 使用原有账号登录，保持不退出 PowerShell 终端模式 → 使用独立 API key 调用模型

这样做的好处是：

1. 桌面端账号保持原状态，不需要频繁退出或重新登录。
2. 终端中的 Codex CLI 可以单独使用 API key。
3. 两套环境通过不同的CODEX_HOME目录隔离，减少互相影响的风险。

2. 安装 Node.js LTS

在 Windows PowerShell 中运行：

winget install--id OpenJS.NodeJS.LTS

如果提示是否接受协议，输入：

y

安装完成后，关闭当前 PowerShell，重新打开一个新的 PowerShell，然后检查：

node-v

成功时会显示类似：

v24.x.x

再检查 npm：

npm.cmd-v

注意：在 PowerShell 中直接运行：

npm-v

有时可能会报执行策略错误，例如：

无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。

这通常不是 npm 没装好，而是 PowerShell 执行策略拦截了npm.ps1。此时使用：

npm.cmd-v

即可。

3. 安装 Codex CLI

使用 npm 安装 Codex CLI：

npm.cmd install-g @openai/codex

安装完成后检查：

where.exe codex codex.cmd--version

如果安装成功，会看到类似输出：

C:\Users\<用户名>\AppData\Roaming\npm\codex C:\Users\<用户名>\AppData\Roaming\npm\codex.cmd codex-cli x.x.x

如果where.exe codex没有输出，可以查看 npm 全局安装路径：

npm.cmd config get prefix

常见路径是：

C:\Users\<用户名>\AppData\Roaming\npm

如有必要，可以临时加入当前 PowerShell 的 PATH：

$env:Path+=";C:\Users\<用户名>\AppData\Roaming\npm"where.exe codex codex.cmd--version

4. 创建终端 API 专用 Codex 环境

不要直接使用默认 Codex 配置目录。默认目录通常是：

C:\Users\<用户名>\.codex

为了避免影响桌面端账号环境，建议为终端 API 模式单独建立一个目录：

$env:CODEX_HOME="$HOME\.codex-api-openai"New-Item-ItemType Directory-Force$env:CODEX_HOME|Out-Nullnotepad"$env:CODEX_HOME\config.toml"

这里的核心是：

$env:CODEX_HOME="$HOME\.codex-api-openai"

它表示当前 PowerShell 窗口中的 Codex CLI 会使用：

C:\Users\<用户名>\.codex-api-openai

而不是默认的：

C:\Users\<用户名>\.codex

这样可以把终端 API 模式和桌面端账号模式隔离开。

5. 编写config.toml

在打开的记事本中粘贴以下内容：

model_provider = "OpenAI" model = "<供应商提供的模型名>" review_model = "<供应商提供的模型名>" model_reasoning_effort = "xhigh" disable_response_storage = true network_access = "enabled" windows_wsl_setup_acknowledged = true [model_providers.OpenAI] name = "OpenAI" base_url = "https://<你的API服务地址>/v1" wire_api = "responses" env_key = "OPENAI_API_KEY" [features] goals = true

保存并关闭记事本。

需要替换的内容有两处：

<供应商提供的模型名> https://<你的API服务地址>/v1

例如，如果供应商文档给出的模型名是：

example-model

API 地址是：

https://api.example.com/v1

则对应写成：

model = "example-model" review_model = "example-model" [model_providers.OpenAI] base_url = "https://api.example.com/v1"

注意：不要把真实 API key 写入config.toml。

6. 不要使用requires_openai_auth = true

如果目标是使用 API key，不建议在配置中写：

requires_openai_auth = true

因为它表示使用账号认证，而不是环境变量中的 API key。

终端 API 模式中应使用：

env_key = "OPENAI_API_KEY"

这表示 Codex 会从 PowerShell 环境变量OPENAI_API_KEY中读取 API key。

7. 设置 API key 并运行 Codex CLI

每次要使用终端 API 模式时，打开 PowerShell，运行：

$env:CODEX_HOME="$HOME\.codex-api-openai"$env:OPENAI_API_KEY="<你的API_KEY>"codex.cmd

注意：

不要把真实 API key 写入文章 不要把真实 API key 写入 config.toml 不要截图暴露 API key 不要把 API key 发给他人

API key 只保存在当前 PowerShell 窗口的临时环境变量中。关闭 PowerShell 后，这个临时变量会失效。

8. 判断当前是否处于 API 模式

可以在 PowerShell 中运行：

Get-ChildItemEnv:CODEX_HOMEGet-ChildItemEnv:OPENAI_API_KEY

如果看到类似：

CODEX_HOME C:\Users\<用户名>\.codex-api-openai OPENAI_API_KEY <已设置>

说明当前 PowerShell 窗口处于 API 模式。

也可以查看配置文件：

notepad"$env:CODEX_HOME\config.toml"

确认其中包含：

env_key = "OPENAI_API_KEY"

并且不包含：

requires_openai_auth = true

9. 退出 API 模式

最简单的方法是：

直接关闭当前 PowerShell 窗口

因为下面两个变量都是当前 PowerShell 窗口中的临时环境变量：

$env:CODEX_HOME$env:OPENAI_API_KEY

如果不想关闭窗口，也可以手动清除：

Remove-ItemEnv:CODEX_HOME-ErrorAction SilentlyContinueRemove-ItemEnv:OPENAI_API_KEY-ErrorAction SilentlyContinue

确认清除结果：

Get-ChildItemEnv:CODEX_HOME-ErrorAction SilentlyContinueGet-ChildItemEnv:OPENAI_API_KEY-ErrorAction SilentlyContinue

如果没有输出，说明当前窗口已经退出 API 模式。

10. 平常使用工作流

10.1 使用 Codex 桌面端

平常使用桌面版 Codex 时：

直接打开 Codex 桌面端 保持原账号登录 不要退出登录 不要重新登录 不要点 logout

桌面端继续使用原来的账号环境。

10.2 使用终端 API 版 Codex

需要使用 API 模式时，打开 PowerShell，运行：

$env:CODEX_HOME="$HOME\.codex-api-openai"$env:OPENAI_API_KEY="<你的API_KEY>"codex.cmd

此时终端 Codex 使用：

C:\Users\<用户名>\.codex-api-openai

不会使用默认的：

C:\Users\<用户名>\.codex

10.3 从 API 模式切回桌面端模式

关闭 PowerShell 窗口即可。

然后继续使用 Codex 桌面端。桌面端不需要退出，也不需要重新登录。

11. 推荐习惯

建议长期保持两套环境分离：

Codex 桌面端 → 原账号环境 PowerShell + .codex-api-openai → API key 环境

不要在 API 模式中运行：

codex.cmd logout

也不要在桌面端随意点击退出登录。

如果同时打开桌面端和终端 Codex，建议不要让它们同时修改同一个项目文件夹。更稳妥的做法是：

同一时间只让一个 Codex 修改项目文件 另一个 Codex 只用于查看、讨论或等待

12. 常见问题

问题 1：npm -v报执行策略错误

报错类似：

无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。

解决方式：

npm.cmd-v npm.cmd install-g @openai/codex

不需要修改系统执行策略。

问题 2：where.exe codex找不到

先检查 npm 全局路径：

npm.cmd config get prefix

如果输出类似：

C:\Users\<用户名>\AppData\Roaming\npm

则可以临时加入 PATH：

$env:Path+=";C:\Users\<用户名>\AppData\Roaming\npm"where.exe codex

问题 3：Codex CLI 启动后要求账号登录

通常说明配置没有走 API key。检查：

Get-ChildItemEnv:CODEX_HOMEGet-ChildItemEnv:OPENAI_API_KEY notepad"$env:CODEX_HOME\config.toml"

确认config.toml中有：

env_key = "OPENAI_API_KEY"

并且没有：

requires_openai_auth = true

问题 4：API 报 404、unsupported endpoint 或 invalid request

优先检查 API 地址是否正确。例如有些服务需要：

base_url = "https://api.example.com/v1"

有些服务可能要求：

base_url = "https://api.example.com"

需要按照供应商文档填写。

另外，如果配置中使用：

wire_api = "responses"

则要求 API 服务兼容对应的接口形式。如果供应商只兼容普通 chat completions，而不兼容 responses 接口，Codex CLI 可能无法正常使用。

13. 最终命令速查

首次安装 Node.js：

winget install--id OpenJS.NodeJS.LTS

重新打开 PowerShell 后：

node-v npm.cmd-v

安装 Codex CLI：

npm.cmd install-g @openai/codex where.exe codex codex.cmd--version

创建 API 专用配置目录：

$env:CODEX_HOME="$HOME\.codex-api-openai"New-Item-ItemType Directory-Force$env:CODEX_HOME|Out-Nullnotepad"$env:CODEX_HOME\config.toml"

日常启动 API 版 Codex：

$env:CODEX_HOME="$HOME\.codex-api-openai"$env:OPENAI_API_KEY="<你的API_KEY>"codex.cmd

退出 API 模式：

关闭 PowerShell 窗口

桌面端模式：

保持 Codex 桌面端登录，不退出，不 logout

14. 最终结构

最终建议形成如下结构：

Codex 桌面端 └── 使用原账号环境 └── 保持登录，不退出 PowerShell 终端 Codex CLI └── 使用独立 CODEX_HOME └── 使用环境变量 OPENAI_API_KEY 调用 API

这样可以实现桌面端和终端 API 模式的相对隔离，降低误退出、误覆盖配置或误触发重新登录的风险。