1. 使用目标#

在同一台 Windows 电脑上同时运行两套互不干扰的 Codex：

• 正版 Codex App：继续使用 OpenAI 官方账号和默认配置。
• 第三方 Codex CLI：使用第三方 API、独立模型和独立配置。

实现方式是为第三方 Codex CLI 设置单独的 CODEX_HOME：

1
正版 Codex App：%USERPROFILE%\.codex
2
第三方 Codex CLI：%USERPROFILE%\.codex-relay

CODEX_HOME 决定 Codex 从哪里读取配置、认证、会话、日志、技能和插件。只在第三方 CLI 的启动进程中设置它，就不会影响正版 Codex App。

不要把 CODEX_HOME 设置成 Windows 全局或用户级环境变量，否则以后启动的 Codex App、IDE 扩展或其他 Codex 工具也可能读取第三方配置。

2. 准备隔离目录#

打开 PowerShell，创建第三方 CLI 专用目录：

1
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex-relay" | Out-Null

这条命令的含义：

• New-Item -ItemType Directory：创建文件夹。
• -Force：文件夹已经存在时不报错。
• $env:USERPROFILE：当前 Windows 用户的主目录，不需要填写真实用户名。
• Out-Null：不显示创建结果，让终端输出更简洁。

最终需要以下文件：

1
%USERPROFILE%\
2
├── .codex\                 # 正版 Codex 使用
3
├── .codex-relay\
4
│   ├── auth.json           # 第三方 API Key
5
│   └── config.toml         # 第三方模型配置
6
└── codex-relay.ps1         # 第三方 CLI 启动脚本

3. 配置 API Key#

创建：

1
%USERPROFILE%\.codex-relay\auth.json

内容如下：

1
{
2
  "OPENAI_API_KEY": "<在这里填写第三方 API Key>"
3
}

填写时注意：

• 只替换尖括号中的占位内容。
• 保留英文双引号、冒号和花括号。
• JSON 最后一项后面不能添加逗号。
• 文件保存为 UTF-8 编码。
• 不要把真实 API Key 提交到 Git、截图、聊天记录或公开教程中。

4. 配置第三方模型#

创建：

1
%USERPROFILE%\.codex-relay\config.toml

通用配置模板：

1
model_provider = "relay"
2
model = "<第三方实际支持的模型名称>"
3

4
[model_providers.relay]
5
name = "Relay API"
6
base_url = "https://relay.example.com/v1"
7
wire_api = "responses"
8
requires_openai_auth = true

需要根据第三方服务商文档修改：

• model：第三方实际支持的模型 ID。
• base_url：第三方 API 地址，是否包含 /v1 以服务商文档为准。
• model_provider：自定义 Provider 标识；必须和 [model_providers.relay] 后缀一致。

其余配置说明：

• wire_api = "responses"：使用 Responses API。
• requires_openai_auth = true：从当前 CODEX_HOME 下的 auth.json 读取 OPENAI_API_KEY。

第三方服务不仅要支持普通文本对话，还应完整兼容 Responses API、流式输出和工具调用，否则 Codex 可能出现能聊天但不能正常操作工具的问题。

5. 创建启动脚本#

创建：

1
%USERPROFILE%\codex-relay.ps1

写入：

1
$ErrorActionPreference = "Stop"
2

3
$relayHome = Join-Path $env:USERPROFILE ".codex-relay"
4
$authFile = Join-Path $relayHome "auth.json"
5

6
if (-not (Test-Path -LiteralPath $authFile)) {
7
    Write-Error "Auth file not found: $authFile"
8
    exit 1
9
}
10

11
$auth = Get-Content -LiteralPath $authFile -Raw -Encoding UTF8 | ConvertFrom-Json
12
$apiKey = [string]$auth.OPENAI_API_KEY
13

14
if ([string]::IsNullOrWhiteSpace($apiKey) -or $apiKey -eq "<在这里填写第三方 API Key>") {
15
    Write-Error "Set OPENAI_API_KEY in $authFile before starting Codex."
16
    exit 1
17
}
18

19
$env:CODEX_HOME = $relayHome
20
codex @args

脚本执行逻辑：

1. 定位当前用户主目录下的 .codex-relay。
2. 检查 auth.json 是否存在。
3. 检查 API Key 是否为空或仍是占位符。
4. 只为当前脚本进程设置 CODEX_HOME。
5. 启动 Codex CLI，并把命令行参数继续传递给 codex。

脚本中的运行时提示使用英文，是为了兼容 Windows PowerShell 5.1 对无 BOM UTF-8 脚本的旧式解析行为。配置文件和笔记仍然可以使用 UTF-8 中文。

6. 启动第三方 Codex CLI#

1
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\codex-relay.ps1" -C "D:\Projects\ExampleProject"

1
cd "D:\Projects\ExampleProject"
2
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\codex-relay.ps1"

1
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\codex-relay.ps1" exec -C "D:\Projects\ExampleProject" "分析工程结构，先不要修改文件"

7. 第一次启动时选择沙箱#

新的 .codex-relay 第一次启动时，Codex CLI 可能要求选择 Windows 沙箱：

1
1. Set up default sandbox (requires Administrator permissions)
2
2. Use non-admin sandbox (higher risk if prompt injected)
3
3. Quit

推荐选择：

1
1. Set up default sandbox

操作步骤：

1. 使用方向键选中第 1 项。
2. 按 Enter 确认。
3. Windows 弹出管理员权限确认时选择“是”。

默认沙箱能更好地隔离文件和网络访问。第 2 项不需要管理员权限，但隔离能力较弱。

这只是新 CODEX_HOME 的首次初始化，不代表 Codex CLI 或项目内工具需要重新安装。

8. 项目级技能是否需要重新安装#

通常不需要。

如果技能、代理或工作流安装在项目内部，例如：

1
项目根目录\
2
├── .agents\skills\
3
├── .codex\agents\
4
├── .trellis\
5
└── AGENTS.md

那么正版 Codex App 和第三方 Codex CLI 打开同一个项目时，都可以读取这些项目级文件。

隔离 CODEX_HOME 后，不会自动共享的是用户级内容：

• 全局 Codex 配置
• 官方账号登录状态
• 全局技能和插件
• 会话历史
• 项目信任记录
• 沙箱初始化状态

如果某个工具安装在 %USERPROFILE%\.codex\skills 或 %USERPROFILE%\.codex\plugins，第三方 CLI 默认看不到它。此时应根据工具的安装方式，单独安装到 .codex-relay，或有选择地迁移相关目录，不要直接复制官方认证文件。

9. 如何区分两套 Codex#

1
%USERPROFILE%\.codex

1
%USERPROFILE%\codex-relay.ps1

1
%USERPROFILE%\.codex-relay

1
setx CODEX_HOME "$env:USERPROFILE\.codex-relay"

10. 验证隔离是否成功#

启动第三方 CLI 后检查界面顶部显示的模型和工作目录：

1
model:     <第三方模型名称>
2
directory: <当前项目目录>

也可以先执行一个只读测试任务：

1
分析当前项目的目录结构，只读取文件，不要修改代码。

同时保持正版 Codex App 正常运行。如果 App 仍然使用官方账号，而 CLI 显示第三方模型，说明隔离成功。

11. 常见问题#

1
%USERPROFILE%\.codex-relay\auth.json

1
model = "<第三方实际支持的模型名称>"
2
base_url = "https://relay.example.com/v1"

1
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\codex-relay.ps1"

12. 安全提醒#

• 发送给第三方 API 的提示词、代码和文件内容可能经过第三方服务器。
• 不要向不可信服务发送私钥、密码、证书、客户数据或未公开源码。
• 不要公开或提交 auth.json。
• 不要把 .codex-relay 放进项目 Git 仓库。
• 不要在公开教程中填写真实用户名、项目路径、公司名、中转域名和 API Key。
• 大幅修改代码前，先要求 Codex 说明修改逻辑并等待确认。

13. 最终使用速查#

启动第三方 Codex CLI：

1
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\codex-relay.ps1" -C "D:\Projects\ExampleProject"

使用正版 Codex App：

1
直接正常打开 Codex App。

两者能够同时运行，是因为它们分别使用 .codex-relay 和 .codex。