Windows & Codex 实操手册

Windows 端 Codex 接入第三方 API 完全指南

涵盖 Codex CLI 命令行与 Codex 桌面端（GUI）· 适配 OpenRouter、DeepSeek、聚合网关与自建反代

步骤一：打开全局配置文件 config.toml

无论 CLI 还是桌面客户端，Codex 均强制读取用户全局配置。

文件位置：C:\Users\<你的用户名>\.codex\config.toml

在 Windows 下按快捷键 Win + X 选择打开 PowerShell，执行以下命令即可自动建好目录并用记事本打开：

PowerShell 一键打开配置 
New-Item -ItemType Directory -Force -Path "$HOME\.codex"
notepad "$HOME\.codex\config.toml"

编辑配置文件内容

关键协议提示： Codex 必须配置 wire_api = "responses"（基于 OpenAI Responses API 规范）。如果是桌面端，务必加上 requires_openai_auth = false。
config.toml（通用标准模板） 
# 默认调用的模型（根据第三方提供商实际支持的模型名字填写）
model = "deepseek-chat"

# 默认使用的 Provider 标识（与下方块名称一致）
model_provider = "my_custom_api"

[model_providers.my_custom_api]
name = "My Custom Provider"

# 第三方 API Base URL（通常末尾需要带 /v1）
base_url = "https://api.your-provider.com/v1"

# 存放 API Key 的系统环境变量名字
env_key = "CUSTOM_API_KEY"

# 协议规范：必须为 responses
wire_api = "responses"

# 桌面端防卡登录关键项：跳过 OpenAI 官方账号强制鉴权
requires_openai_auth = false

步骤二：设置 Windows 环境变量（API Key）

Codex 出于安全考虑，通过读取系统环境变量来提取 Key。我们需要将真实的 API Key 写入 Windows 用户环境变量：

PowerShell（写入永久用户变量） 
[Environment]::SetEnvironmentVariable("CUSTOM_API_KEY", "sk-你的真实API密钥", "User")

* 设置完成后，如果需要终端运行 CLI，必须关闭并重新打开终端窗口环境变量才生效。

⚠️ 步骤三：如果是 Codex 桌面端（GUI），特别注意这 3 点

桌面端是图形化 Electron 应用，相比 CLI 有几个非常致命的踩坑点：

  1. 必须配置 requires_openai_auth = false
    桌面端如果检测不到官方 token 会默认卡在登录页面。加上此参数才能正常直连第三方 API。
  2. 必须是系统级环境变量：
    在 PowerShell 临时运行 $env:KEY="xxx" 对桌面端无效！桌面端由 Windows Explorer 直接启动，只能读取通过步骤二写入的 Windows 用户永久环境变量。
  3. 彻底退出后台托盘（关键！）：
    点击桌面端窗口右上角的 “X” 只会最小化到任务栏右下角托盘，程序并未重启，导致新配置无法加载！
    必须在任务栏右下角展开托盘，右键 Codex 小图标 -> 选择 Quit / Exit，然后再重新打开软件。

步骤四：启动与多 Profile 切换

1. 启动验证

2. 多配置文件切换（Profile）

如果你需要在“官方 API”与“第三方中转”之间随意切换，可以创建多个 Profile：

  1. 在 ~/.codex/ 目录下创建 work.config.toml。
  2. 启动时加上参数：codex --profile work

步骤五：高频问题与排雷速查

症状 / 报错 可能原因 解决办法
404 Not Found 第三方 API 仅支持 /chat/completions，不支持 Responses 协议；或 URL 路径少写了 /v1 确认服务商支持 Responses API；或在本地使用网关工具（如 CC Switch）进行协议转换；检查 base_url 拼接。
API Key not found 桌面端未读取到环境变量；或 env_key 变量名拼写错误 检查 env_key 是否一致；右键托盘彻底退出桌面端；若仍不行，注销或重启一次 Windows。
桌面端卡在登录界面 未关闭官方强校验 确认在 [model_providers.xxx] 中添加了 requires_openai_auth = false。
第三方 API 响应极慢 / 超时 国内网络直连海外 API 节点阻断或波动 推荐使用 Cloudflare Worker 搭建轻量反代（见下方脚本）。

步骤六（拓展）：Cloudflare Worker 极速免费反代脚本

如果你的第三方接口访问不稳定，可在 Cloudflare Workers 中部署以下轻量代码作为专属反代网关：

Worker.js 
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    // 替换为你的目标上游 API 地址
    const targetUrl = new URL(url.pathname + url.search, "https://api.openai.com");

    const newHeaders = new Headers(request.headers);
    newHeaders.set("Host", targetUrl.host);

    const newRequest = new Request(targetUrl, {
      method: request.method,
      headers: newHeaders,
      body: request.body,
      redirect: "follow"
    });

    return fetch(newRequest);
  }
};

部署后获得的 https://xxx.workers.dev/v1 直接填入 config.toml 的 base_url 即可。