Windows 安装 Codex 配置 DeepSeek V4 Pro 完全指南Windows 10/11 · DeepSeek V4 Pro API · Node.js 22 · Codex CLI v0.130.0 · 2026-05-20一、这篇教程解决什么问题一句话定位在中国大陆 Windows 环境下从零安装 OpenAI Codex CLI 并接入 DeepSeek V4 Pro 模型绕过三个关键障碍——npm 直连慢、OpenAI API 不可达、Codex Responses API 与 DeepSeek Chat Completions 协议不兼容。跳读指南Node.js 已经装好的直接跳到 第三节 安装 Codex CLI。只想看 DeepSeek 配置的跳到 第四节 配置 DeepSeek V4 Pro推荐用 dsv4-cc-proxy-tray双击 exe 即用。遇到报错的跳到 Debug 章节 按关键字匹配。对为什么必须用代理没概念的务必先看 第四节 4.1 为什么需要代理这是全文最关键的概念节点。阅读前提一台 Windows 101809或 Windows 11 电脑有管理员权限有一个 DeepSeek API Key从 platform.deepseek.com 注册获取新用户有免费额度能打开 PowerShell 或 Windows Terminal读完能得到什么一个在终端里正常运行的codex命令接入 DeepSeek V4 Pro一份可随时切换 GPT / DeepSeek 的双模型配置理解 Codex DeepSeek 的协议转换机制出问题知道从哪里排查二、环境准备2.1 依赖清单组件最低版本说明WindowsWindows 10 1809 / Windows 11Win11 推荐Win10 1909 实测可用Node.js22.x LTSnpm 全局安装的前置。18 可跑但 22 最稳Git2.23克隆代理仓库用非严格必须但强烈建议DeepSeek API Key—platform.deepseek.com → API Keys2.2 逐条验证打开Windows Terminal不是老 cmd.exe逐条跑# Node.js 版本node--version# 预期v22.x.x 或更高# npm 版本npm--version# 预期10.x.x 或更高# Git 版本git--version# 预期git version 2.23.x 或更高如果缺少某个组件Node.js到 nodejs.org 下载 22 LTS 的.msi安装包一路 Next 完成安装。装完关掉终端重开再验证。国内访问 nodejs.org 慢的话用 npmmirror 的 Node 镜像https://npmmirror.com/mirrors/node/Git到 git-scm.com/download/win 下载安装包使用推荐设置即可。Git 下载也慢的话用淘宝镜像https://npmmirror.com/mirrors/git-for-windows/2.3 配置 npm 国内镜像npm configsetregistry https://registry.npmmirror.com验证npm config get registry# 预期https://registry.npmmirror.com这一步非常关键。不配镜像的话npm install -g openai/codex大概率超时或半天不动。三、安装 Codex CLI3.1 安装命令npm install-g openai/codex包名是openai/codex不是codex。npm 上存在一个 2012 年的无关codex包装错不会有任何有用功能这是最常见的安装翻车点。安装过程约 1 分钟。安装完成后验证codex--version预期输出版本号以实际为准Codex CLI v0.130.03.2 如果 codex 命令找不到npm install -g之后codex可能不在 PATH 里。先查 npm 全局 bin 路径npm bin-g把这个路径加到用户环境变量 PATH 中Win R →sysdm.cpl→ 高级 → 环境变量在用户变量中找到Path编辑 → 新建 → 粘贴上一步输出的路径确定关掉终端重开再跑codex --version3.3 Windows 沙箱模式必读Codex 在 Windows 上有三种运行方式配置文件路径同为C:\Users\用户名\.codex\config.toml模式配置说明原生 elevated推荐[windows]sandbox elevated需要管理员提权创建专用沙箱用户文件系统和网络隔离最完整原生 unelevated降级[windows]sandbox unelevated不需管理员权限在当前用户下施加受限 Token隔离较弱WSL2在 WSL 内安装Linux 沙箱实现最稳定但项目文件要在 WSL 文件系统里建议策略先在原生 PowerShell 里跑 elevated 模式。如果遇到 “sandbox setup refresh failed” 报错再切 unelevated。企业管控电脑如果两种都失败上 WSL2。本节不展开 WSL2 路径Linux 环境下的安装逻辑相同npm install -g openai/codex一条命令即可后续配置统一以原生 Windows 为例。四、配置 DeepSeek V4 Pro4.1 为什么必须用代理——三个不兼容这是全篇最关键的概念节点理解它比照抄配置更重要。Codex 和 DeepSeek V4 之间存在三个层面的不兼容层面Codex 的期望DeepSeek V4 的能力结果API 协议Responses API/v1/responsesChat Completions/v1/chat/completions直接对接 404wire_api 字段仅支持wire_api responses0.128.0 废弃了chat无 Responses 端点写chat直接拒绝发请求消息格式Responses API 格式input、previous_response_idChat Completions 格式messages数组工具调用断裂、reasoning_content 丢失用一句话概括Codex 说的是 Responses 语DeepSeek 说的是 Chat Completions 语中间缺一个翻译。解决方案有两种dsv4-cc-proxy-tray本文推荐专门为 Windows DeepSeek V4 场景开发的本地代理一个 .exe 双击运行同时兼容 Claude Code 和 Codex CLI无需 Python、npm 或终端CC-Switch 桌面端可选配合提供 GUI 配置管理和托盘切换但 CodexDeepSeek 仍需外部代理配合CC-Switch 自身不做 Responses→Chat 翻译本文先讲 dsv4-cc-proxy-tray 推荐方案4.3 节再讲 CC-Switch 可选配合4.4 节最后给出方案对比表4.5 节。4.2 获取 DeepSeek API Key打开 platform.deepseek.com注册/登录左侧菜单 → API Keys → 创建新 Key复制 Key格式sk-xxxxxxxx存好只显示一次截至 2026 年 5 月新注册用户有免费额度V4 Pro 定价见 DeepSeek 官方定价页。4.3 安装 dsv4-cc-proxy-tray推荐dsv4-cc-proxy-tray 是专门为 Windows 用户开发的 DeepSeek API 兼容代理。一个 .exe 双击运行同时处理 Claude Code 和 Codex CLI 的协议转换。内置 5 项兼容性修复#问题表现修复方式1tool_use消息缺少thinking块reasoning_content400 错误自动注入空 thinking 块2DeepSeek 强行输出 SSE thinking 事件Tool result missing due to internal error从 SSE 流剥离 thinking 事件3thinking.typeadaptivereasoning_effort不兼容流截断 / 400 错误标准化为disabled 剥离 reasoning_effort4Codex 说 Responses APIDeepSeek 只给 Chat Completions404 / 协议不匹配Responses → Chat 请求转换 SSE 回译5DeepSeek Chat SSE 流含reasoning_contentCodex 拒绝非预期字段从 Chat SSE 流剥离 reasoning_content4.3.1 下载与启动到 Releases 下载dsv4-cc-proxy-tray.exe双击运行。国内 GitHub 下载慢的话用 ghproxy 加速https://ghproxy.net/https://github.com/Friend-Xu/dsv4-cc-proxy-tray/releases/latest/download/dsv4-cc-proxy-tray.exe启动后看到 GUI 窗口——绿点表示代理运行中端口16889。无需 Python、npm 或终端零依赖。GUI 提供启动/停止按钮、实时彩色日志、配置面板上游 URL、监听地址、日志级别设置保存到~\.dsv4-cc-proxy-tray.json。4.3.2 配置 DeepSeek API Key在 GUI 配置面板中最少设置一个环境变量# 永久写入用户环境变量推荐[Environment]::SetEnvironmentVariable(DEEPSEEK_API_KEY,sk-你的DeepSeek-Key,User)设置完关掉终端重开。4.3.3 配置 Claude Code在C:\Users\用户名\.claude\settings.local.json中加一行{env:{ANTHROPIC_BASE_URL:http://localhost:16889,ANTHROPIC_AUTH_TOKEN:sk-你的DeepSeek-Key}}4.3.4 配置 Codex CLI编辑C:\Users\用户名\.codex\config.tomlopenai_base_url http://localhost:16889/v1 model deepseek-v4-pro代理自动识别请求路径/v1/messages→ Claude Code 处理链路/v1/responses→ Codex 处理链路不需要手动选模式。4.3.5 验证代理运行curl http://localhost:16889/health预期输出{status:ok,version:1.8.0,upstream:https://api.deepseek.com/anthropic}4.4 CC-Switch 可选配合如果你同时用 Claude Code 和 Codex可以用 CC-Switch75K GitHub Stars统一管理配置。但注意CC-Switch 自身不做 Codex 的 Responses→Chat 翻译——它在这个场景下只充当 config.toml 的图形化编辑器协议转换仍然由 dsv4-cc-proxy-tray 完成。配置方法在 CC-Switch 的 Codex 页签中手动添加一个自定义供应商base_url填http://localhost:16889/v1即可通过托盘图标快速切换模型。4.5 方案对比对比维度dsv4-cc-proxy-tray推荐CC-Switch 配合手动代理安装方式下载 .exe双击运行.msi 安装 手动配 base_urlgit clone 编辑 .env 手写 config.toml协议翻译内置 5 项修复Responses↔Chat不翻译需配合 dsv4-cc-proxy-tray内置 Responses↔ChatClaude Code 支持/v1/messagesthinking 修复托盘快捷切换无启动方式GUI 一键支持系统托盘随 CC-Switch 自启每次手动node proxy.mjs用量追踪无内置仪表盘token/费用无适合人群大多数 Windows 用户同时用多工具 需用量追踪的用户极简命令行用户五、启动与验证5.1 启动代理双击dsv4-cc-proxy-tray.exeGUI 窗口显示绿点即代理运行中。代理会常驻系统托盘右键可快速启停。5.2 启动 Codex打开终端cd 你的项目目录 codex因为config.toml中openai_base_url已指向代理所有对话自动走 DeepSeek V4 Pro。你问什么模型它就回 DeepSeek不需要带-p参数。5.3 验证模型身份在 Codex 交互界面中输入你用的是哪个模型请回复你的模型名称和提供商。预期回复类似我使用的是 DeepSeek V4 Pro由 DeepSeek 提供。5.4 端到端功能验证做一个最简单的代码操作测试在当前目录创建一个 hello.py 文件内容是打印 Hello from DeepSeek V4 然后运行它如果 Codex 能成功创建文件并执行说明整个链路——代理翻译 → API 调用 → 工具执行——全部正常。Debug 章节Debug #1 — npm 安装成功但 codex 没有任何反应报错日志PSC:\Users\用户名 npm install-g openai/codex# 看起来安装成功PSC:\Users\用户名 codex--version codex : 无法将codex项识别为 cmdlet、函数、脚本文件或可运行程序的名称。根因npm install -g的全局 bin 目录不在系统 PATH 中。这在 Windows 上很常见尤其是用 nvm-windows 或 fnm 管理 Node 版本时每个版本管理器有自己的全局路径策略。一览对比表对比维度修复前修复后npm 全局 bin 路径存在于 npm 配置中但不在 PATH已添加到用户 PATHcodex --version无法识别Codex CLI v0.130.0排查手段不知道去哪找 codex.exenpm bin -g直接定位代码修复Step 1— 找到 npm 全局 bin 路径npm bin-g# 输出示例C:\Users\用户名\AppData\Roaming\npmStep 2— 把这个路径加到用户 PATHWin R →sysdm.cpl→ 高级 → 环境变量在用户变量列表中找到Path→ 编辑新建 → 粘贴 Step 1 输出的路径 → 确定Step 3— 关掉所有终端窗口重开验证。验证codex--version# Codex CLI v0.130.0Debug #2 — sandbox setup refresh failed报错日志windows sandbox: setup refresh failed with status exit code: 1根因这不是用户的配置错误而是 Codex elevated sandbox 在刷新阶段尝试修改项目根目录的 ACL访问控制列表失败了。具体原因elevated sandbox 每次执行命令前会先跑一个非提权刷新setup refresh检查 workspace 根的写入权限刷新逻辑调用SetNamedSecurityInfoW(DACL_SECURITY_INFORMATION)尝试给沙箱用户添加 ACE访问控制条目如果项目目录的所有者不是当前用户比如目录是 Administrator 创建的、或者位于非系统盘当前用户没有WRITE_DAC权限ACL 写入被拒绝返回 ERROR_ACCESS_DENIED (5)常见于项目放在 D 盘/E 盘、外接硬盘、或者目录是从其他机器拷贝过来的。一览对比表对比维度修复前修复后项目目录所有者Administrators / SYSTEM / 其他用户当前用户当前用户的 DACL 权限读取 写入但无 WRITE_DAC读取 写入 修改权限即 WRITE_DACsandbox 刷新结果exit code: 1正常通过命令执行每次都卡在刷新阶段正常执行代码修复方案一推荐修改项目目录的所有者为当前用户。以管理员身份打开 PowerShelltakeown/FD:\你的项目目录/R/D Y icaclsD:\你的项目目录/grant$env:USERNAME:F/Ttakeown拿回所有权icacls授予完全控制权。/R和/T递归应用到所有子目录和文件。方案二快速降级切换到 unelevated sandbox。在C:\Users\用户名\.codex\config.toml中添加[windows] sandbox unelevated验证重启 Codex执行一条简单命令运行 Get-Location 告诉我当前路径能正常返回路径即修复成功。Debug #3 — 代理连接被拒绝 (ECONNREFUSED)报错日志FetchError: request to http://localhost:4000/v1/responses failed, reason: connect ECONNREFUSED 127.0.0.1:4000根因Codex 去访问localhost:4000时代理没有在运行。可能的原因按频率排序根本没启动代理最常见忘了在另一个终端里跑node proxy.mjs代理已崩溃退出.env里没设DEEPSEEK_API_KEY代理启动后首次收到请求时发现没 key 直接报错退出端口冲突4000 端口被其他程序占用一览对比表对比维度修复前修复后curl http://localhost:4000/healthConnection refused{status:ok,...}代理终端窗口不存在 / 已停止正在运行显示listening on http://localhost:40004000 端口状态未监听 / 被其他程序占用由 node proxy.mjs 监听代码修复Step 1— 检查代理是否在运行curl http://localhost:4000/health如果Connection refused进入 Step 2。Step 2— 检查 4000 端口是否被占用netstat-ano|findstr :4000如果有输出说明其他程序占了 4000 端口改代理端口在.env中加一行PROXY_PORT4001同时更新config.toml中的base_urlbase_url http://localhost:4001/v1Step 3— 确认.env中已设DEEPSEEK_API_KEY重新启动代理node proxy.mjs验证curl http://localhost:4000/health# {status:ok,providers:{deepseek:true,...},default_provider:deepseek}Debug #4 — GitHub Releases 下载 .exe 失败报错日志无法访问 github.com下载 dsv4-cc-proxy-tray.exe 超时根因中国大陆部分网络环境尤其是移动宽带、公司内网直连 GitHub 不稳定TCP 443 端口连接超时。这不是本地配置问题是网络层的阻断。一览对比表对比维度修复前修复后下载方式直连github.com/Friend-Xu/.../releases通过 ghproxy 加速下载速度超时或几十 KB/s正常代码修复用 ghproxy 加速下载Invoke-WebRequest-Urihttps://ghproxy.net/https://github.com/Friend-Xu/dsv4-cc-proxy-tray/releases/latest/download/dsv4-cc-proxy-tray.exe-OutFile$env:USERPROFILE\Downloads\dsv4-cc-proxy-tray.exe验证dir$env:USERPROFILE\Downloads\dsv4-cc-proxy-tray.exe# 预期显示文件存在双击即可运行Debug #5 — wire_api “chat” 已废弃报错日志Support for the chat wire API is deprecated and will soon be removed.紧接着An assistant message with tool_calls must be followed by tool messages responding to each tool_call_id. (insufficient tool messages following tool_calls message)根因Codex 从 v0.128.0 起正式废弃wire_api chat只保留wire_api responses。很多旧教程2025 年及以前的博客、Gist、CSDN 帖子给的都是wire_api chat的配置写法直接用会触发两个错误弃用警告Codex 检测到chat后打印警告工具调用断裂即使勉强发出去DeepSeek 的 Chat Completions 工具调用格式与 Responses API 的工具期望不匹配出现insufficient tool messages错这就是为什么 2026 年不能照抄 2025 年的配置教程。如果你看到教程里写了wire_api chat那篇教程已经过时。一览对比表对比维度旧方案2025 教程新方案本文wire_apichatresponses或通过代理自动转换直达 DeepSeek直接base_url https://api.deepseek.com/v1不可行协议不兼容工具调用多轮后断裂insufficient tool messages代理修复后正常thinking 模式reasoning_content字段缺失代理缓存并回填代码修复不要这样写已失效# ❌ 错误2025 年的写法2026 年已失效 [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat # ← 这一行导致报错正确写法2026 年有效# ✅ 正确通过本地代理wire_api responses或不写默认就是 responses [model_providers.deepseek_proxy] name DeepSeek Proxy base_url http://localhost:4000/v1 env_key DEEPSEEK_API_KEY # wire_api 不写默认是 responses协议转换的工作交给代理做代理内部把 Responses 格式翻译成 Chat Completions 发给 DeepSeekCodex 本身只跟代理说 Responses 语。验证启动 Codex 后不应再看到Support for the chat wire API is deprecated警告。确认配置正确codex-p deepseek# 应该直接进入 TUI无弃用警告在 Codex 中运行一个多步操作创建文件 编辑 运行确认工具调用没有断裂创建一个 test.py内容为 print(11)然后运行它最后告诉我运行结果如果完整执行返回2说明整个工具调用链路正常。六、日常维护6.1 启停命令# 启动双击 dsv4-cc-proxy-tray.exeGUI 绿点运行中# 停止点击 GUI 的 Stop 按钮或右键托盘图标退出# 日志GUI 窗口实时显示彩色日志无需额外配置6.2 更新命令# 更新 Codex CLInpm install-g openai/codexlatest# 更新 dsv4-cc-proxy-tray# 到 Releases 页下载最新 .exe 覆盖即可无安装流程6.3 排查日志如果在 GUI 中看不到足够细节可在配置面板将日志级别设为info所有请求/响应头会实时显示。需要更深度的流量 dump 时设PROXY_DUMP_DIR环境变量指定输出目录注意dump 文件含对话内容排查完记得清空。七、速查卡7.1 文件路径汇总文件绝对路径dsv4-cc-proxy-tray下载的 .exe 所在位置Codex 配置文件C:\Users\用户名\.codex\config.tomlClaude Code 配置文件C:\Users\用户名\.claude\settings.local.json代理设置文件C:\Users\用户名\.dsv4-cc-proxy-tray.jsonnpm 全局 binnpm bin -g输出路径7.2 端口/环境变量端口/变量服务/用途验证命令16889dsv4-cc-proxy-tray 默认端口curl http://localhost:16889/healthDEEPSEEK_API_KEYDeepSeek API 认证$env:DEEPSEEK_API_KEYPROXY_UPSTREAM上游 DeepSeek API 地址默认https://api.deepseek.com/anthropicGUI 配置面板查看7.3 常见报错 → 解决方案报错解决无法将codex项识别为 cmdletnpm 全局 bin 未在 PATH见 Debug #1sandbox setup refresh failed with status exit code: 1项目目录 ACL 权限问题见 Debug #2connect ECONNREFUSED 127.0.0.1:16889dsv4-cc-proxy-tray 未启动双击 exe 启动fatal: unable to access github.comGitHub 直连超时用 ghproxy 加速下载 .exewire_api chat is deprecated配置过时使用 dsv4-cc-proxy-tray 替代直接配置npm install长时间无响应先配国内镜像npm config set registry https://registry.npmmirror.comreasoning_content400 错误代理未运行或 upstream 配置错误检查 healthCreateRestrictedToken failed: 87Windows sandbox 底层错误尝试sandbox unelevated降级或用 WSL2八、扩展阅读dsv4-cc-proxy-tray 仓库 — 本文推荐的一站式代理MIT 开源含 Claude Code Codex 双协议支持CC-Switch 官网 — 跨平台 AI CLI 配置管理工具可配合 dsv4-cc-proxy-tray 使用DeepSeek API 官方文档 — 编码 Agent 接入指南 — DeepSeek 官方给出的 Claude Code / OpenCode 接入方案Codex 官方 Windows 文档 — elevated/unelevated sandbox 的详细行为说明和排错指南DeepSeek V4 进阶指南 — V4 Pro/Flash 模型参数、thinking 模式、工具调用参考文献Friend-Xu/dsv4-cc-proxy-tray — Windows DeepSeek 代理双协议支持MIT 开源HosheaLi/dsv4-cc-proxy — 源仓库代理核心逻辑OpenAI Codex CLI — Windows Setup — 官方 Windows 安装文档sandbox 三种模式说明OpenAI Codex CLI — Quickstart — 官方快速入门OpenAI Codex CLI — Advanced Configuration — 自定义 model provider 和 profiles 的字段详解farion1231/cc-switch — 跨平台桌面 AI CLI 管理工具可选配合使用DeepSeek API Docs — 接入 Agent 工具 — DeepSeek 官方 Claude Code / OpenCode 接入说明DeepSeek V4 进阶指南 — V4 Pro/Flash 的模型参数、thinking 模式、工具调用详解codeproxy/cli — npm 包形式的本地翻译代理手动方案备选DeepSeek API Docs — 接入 Agent 工具 — DeepSeek 官方对于 Claude Code / OpenCode 的接入说明DeepSeek V4 进阶指南 — V4 Pro/Flash 的模型参数、thinking 模式、工具调用详解Codex CLI 在 Windows 上完全安装指南 (ofox.ai) — 国内用户视角整理的 Codex Windows 安装教程Configure OpenAI Codex CLI to use DeepSeek models (GitHub Gist) — 记录了 wire_api“chat” 方案从可用到被废弃的完整时间线