说实话Windows 上用 Codex 这件事我一开始是拒绝的。不是 Codex 本身不好用而是 Windows 原生环境跑这种偏 Linux 生态的命令行工具总会冒出各种“不说人话”的报错路径分隔符、shell 语法、权限模型、沙箱依赖每一项都像在打地鼠。后来我把环境整体迁到 WSL 里才算真正找到了“优雅”的姿势。这篇文章我会完整拆解一套我目前最顺手的方案Windows 上通过 WSL 安装、配置、使用 Codex包括环境准备、Codex CLI 的登录与模型配置、与 VS Code Remote-WSL 的组合打法以及我实际踩过的坑和排查记录。适合想在 Windows 上用 AI 编码工具、但又被桌面版和原生终端折腾到头疼的开发者。1. 为什么在 Windows 上用 Codex 首选 WSL1.1 Windows 原生用 Codex 的“膈应”点你可能也有这种感觉Codex 这类工具本质上是一个跑在终端里的 AI 编码代理它要做的核心事情无非三件——读代码、改文件、执行命令。这三件事在 Linux 下非常自然因为绝大多数服务端项目、脚本、依赖管理工具都是围绕 POSIX 环境设计的。但到了 Windows 原生环境问题就来了。第一是路径。Codex 生成的命令里全是/home/user/project这种正斜杠写法PowerShell 虽然新版支持/但 cmd、各种脚本、还有 Node/Python 生态里大量以字符串拼路径的代码在 Windows 上总会遇到\与/混用的问题。你让 Codex 改一个文件它可能生成sed -i命令Windows 上根本没有原生sed要么你装 Git Bash要么 WSL要么手动改每一步都在消耗精力。第二是 shell 兼容性。Codex 默认假设你的交互 shell 是 bash 或 zsh它给你生成的“运行测试”“装依赖”“起服务”这类命令基本都是 POSIX 风格。在 Windows 上你要么切到 Git Bash要么在 PowerShell 里手动改命令AI 的“自动执行”价值直接打了对折。第三是沙箱和权限。Codex 出于安全考虑会限制它执行的命令能访问哪些目录这个机制在 Linux 上有成熟的实现。Windows 原生版的沙箱要么不可用要么配置起来很别扭。而且 Windows 的权限模型和 Linux 完全是两套很多在 Linux 上顺理成章的“当前用户可写目录”到了 Windows 上会因为 UAC、符号链接权限、进程隔离这些因素冒出奇怪的错误。1.2 WSL 解决的其实是“上下文一致性问题”WSL 最有价值的点不是给你一个“能用的 Linux”而是让 Codex 看到的文件系统、shell、路径、权限模型和它平时训练数据里最常见的开发环境完全一致。你在 WSL 里执行pwd返回的是/home/yourname/projectCodex 生成一条mkdir -p src/utils就能直接创建目录它想跑pip install或go build走的就是真实 Linux 的包管理和进程模型。这个“上下文一致性”比任何性能优化都重要因为它消除了大量隐性问题——AI 生成代码时的假设和你实际运行环境的真实情况终于对上了。另外WSL2 是基于轻量级虚拟化技术实现的完整 Linux 内核系统调用兼容性极好。绝大多数的 Linux 二进制、Docker 容器、GCC 工具链、CUDA 环境都可以直接在 WSL2 里跑这给 Codex 的“自动执行命令”提供了最广阔的操作空间。1.3 WSL1 还是 WSL2直接 WSL2如果你是新装环境不用纠结直接选 WSL2。对比项WSL1WSL2内核实现系统调用翻译层完整 Linux 内核轻量虚拟机文件 IO 性能跨 OS 文件系统较快Linux 原生文件系统更快系统调用兼容性有限完整Docker 支持不支持原生支持systemd默认不支持支持新版本可开启与 Windows 互操作正常正常WSL1 在访问 Windows 盘符下的文件时速度有优势但既然目标是 Codex你的代码最好放在 Linux 文件系统里WSL2 的完整性和兼容性明显更值得。而且 WSL2 通过 localhost 就能让 Windows 访问到 WSL 里启动的服务开发调试非常方便。2. 安装与初始化把 WSL 调教到能跑 Codex2.1 一条命令装好 WSLWindows 10 2004 以上或 Windows 11直接用管理员权限打开 PowerShell 或 CMD执行wsl --install这条命令会默认开启所需的 Windows 功能下载并安装 WSL2 内核然后安装默认的 Ubuntu 发行版。安装完成后重启系统会进入 Ubuntu 初始化界面设置用户名和密码。这里有几个高频问题如果执行wsl --install卡住或者提示“无法解析服务器的名称或地址”通常是网络下载问题可以重试也可以去微软官方手动下载 WSL 更新包或 Ubuntu 的 appx 包离线安装。如果重启后进不了 Ubuntu先检查 BIOS 里虚拟化Intel VT-x / AMD SVM是否开启。老系统不想升级可以手动启用 “适用于 Linux 的 Windows 子系统” 和 “虚拟机平台” 两个功能再安装内核更新包最后装 Ubuntu。装完 Ubuntu 之后建议第一时间更新软件源和基础工具sudo apt update sudo apt upgrade -y sudo apt install -y git curl wget build-essential2.2 别把项目放在 /mnt/c文件系统和权限的讲究这是我最想提醒你的一点在 WSL 里用 Codex项目目录一定放 Linux 文件系统里也就是你的家目录下不要放在 /mnt/c。为什么WSL 里访问 Windows 盘符比如/mnt/c/Users/xxx/project走的是 9P 协议底层涉及 Windows 的文件系统IO 性能明显慢而且最要命的是权限模型不一致。在 /mnt/c 下Linux 的 chmod、符号链接、文件监听这些操作经常会“失灵”或表现诡异。Node.js 的node_modules在 /mnt/c 下安装慢、构建慢Python 的 venv 也会受影响。你让 Codex 在 /mnt/c 的项目里改文件、装依赖它会遇到很多“不明原因”的失败。所以我的习惯是在 WSL 家目录下建一个~/dev目录所有代码项目都放这里mkdir -p ~/dev cd ~/dev如果你确实需要操作 Windows 盘符下的文件可以挂载到 WSL但尽量只做“读取”或“少量修改”主力开发都在 Linux 侧。这样 Codex 执行的复制、移动、权限修改都发生在原生 Linux 文件系统上几乎没有额外的心智负担。2.3 WSL 与 Windows 的网络互通配置WSL2 默认是 NAT 网络模式WSL 内部的网络是一个独立的小局域网通过 Windows 主机做 NAT 访问外部网络。两个方向的访问逻辑你要记住从 Windows 访问 WSL 里的服务直接访问localhost或127.0.0.1就行WSL2 默认会端口转发。从 WSL 访问 Windows 上运行的服务需要知道 Windows 主机的 IP一般可以在 WSL 里通过ip route show | grep default拿到默认网关地址那就是 Windows 主机的 IP。从 WSL 访问外网默认就能上前提是 Windows 本身能上外网。如果你的开发环境需要配置 HTTP 代理才能访问外部 API比如公司网络策略可以在 WSL 的/etc/environment或~/.bashrc中设置export http_proxyhttp://Windows主机IP:代理端口 export https_proxyhttp://Windows主机IP:代理端口 export no_proxylocalhost,127.0.0.1,.local注意别把no_proxy漏了否则 WSL 访问本机的一些服务也会莫名其妙地走代理导致连接失败。新版 WSLWindows 11 22H2 之后的版本支持镜像网络模式你可以在C:\Users\你\\.wslconfig里写[wsl2] networkingModemirrored开启镜像网络后WSL 和 Windows 共享同一套网络接口回环地址也互通代理配置会更简单localhost两边都通。如果你在 Windows 上有本地代理工具WSL 里直接配http://localhost:代理端口就能访问。2.4 装齐基础依赖Node.js、git、bubblewrapCodex CLI 有几种安装方式其中 npm 方式最常用所以 Node.js 环境是必须的。我建议在 WSL 里用 nvm 安装和管理 Node.jscurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重新加载 shell 配置后 nvm install --lts node -v npm -v然后安装 Codex 沙箱依赖。Codex CLI 在 Linux 上默认使用 bubblewrap 做沙箱隔离如果系统没有这个工具Codex 启动时会警告或无法进入安全模式sudo apt install -y bubblewrap装完之后基础环境就齐了。你可以用wsl -l -v在 PowerShell 里确认当前使用的发行版和 WSL 版本确保是 VERSION 2。3. Codex CLI 安装、登录与模型配置3.1 安装 Codex CLI 的两种方式Codex 官方提供两种主流安装方式我个人更推荐 npm 全局安装版本切换和回滚都方便npm install -g openai/codex另一种是用官方安装脚本curl -fsSL https://codex.openai.com/install.sh | bash安装完成之后验证一下codex --version顺便说一句网上很多人问 Windows 桌面版 “Codex 安装未完成”“打不开”我的建议是既然你都准备用 WSL 了就直接用 CLI 版这是 Codex 最完整、更新最及时的形态。桌面版更像一个图形壳在 Windows 上跑还会有各种 GUI 层面的兼容问题反而干扰主要工作。3.2 登录与鉴权解决 WSL 唤起 Windows 浏览器的问题Codex 登录很简单执行codex login它会生成一个链接让你去浏览器里授权。问题是 WSL 里默认没有图形浏览器它唤起浏览器时会失败。解决办法有几种。第一种设置BROWSER环境变量让 WSL 调用 Windows 的浏览器。以 Edge 为例可以在~/.bashrc里加export BROWSER/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe然后重新加载配置再执行codex login它会自动调用 Windows 上的 Edge 打开授权页面。Chrome 同理把路径换成 Chrome 的chrome.exe即可。第二种如果设置BROWSER不生效或者不想折腾就手动复制codex login输出里的 URL粘贴到 Windows 浏览器里打开授权完成后回到 WSL 终端等它确认即可。登录成功后会生成~/.codex/auth.json保存你的凭证。注意这个文件的权限最好设置成只有自己可读chmod 600 ~/.codex/auth.json如果你不想走 OAuth 登录也可以直接用 API Key。设置环境变量OPENAI_API_KEY即可Codex 会优先读取它。3.3 配置第三方 OpenAI 兼容模型以 DeepSeek 为例很多人没有 OpenAI 的 Codex 访问权限但又想体验 Codex CLI 的交互和自动化能力。好消息是Codex CLI 支持通过自定义 model_provider 接入任何 OpenAI 兼容的接口。我自己试过接入 DeepSeek效果很稳。在~/.codex/config.toml里增加配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后设置对应的环境变量export DEEPSEEK_API_KEY你的API Key这里wire_api字段很关键它决定 Codex 用哪种协议格式访问你的接口。OpenAI 自家的接口一般是responses而大多数第三方兼容服务用的是chat也就是传统的/chat/completions。如果你请求时报 404 或者字段错误大概率是wire_api配错了。配置完可以简单测试codex exec 用 Python 写一个快速排序如果 DeepSeek 的 API Key 能正确读取Codex 就会正常返回结果并尝试执行代码。3.4 config.toml 核心参数逐项拆解~/.codex/config.toml是 Codex 的核心配置文件很多“莫名其妙”的行为都跟它有关。我总结几个最常用的参数参数作用我的建议model指定模型名称官方账户用gpt-5-codex之类第三方用具体模型名model_provider指定模型提供方不写默认 OpenAI第三方便配自定义 providersandbox_mode沙箱模式默认workspace-write需要更严格就sandboxauto_execute是否自动执行命令想安全一点就关掉手动确认temperature采样温度编码任务 0.2~0.4 比较稳notifications桌面通知WSL 里可关掉省得烦一个比较稳妥的日常配置示例model gpt-5-codex model_provider openai sandbox_mode workspace-write auto_execute true temperature 0.2注意不同版本对某些参数名可能有调整你装好之后可以用codex --help或者查看官方文档确认字段名。核心思路是model和model_provider决定了“用哪个模型”sandbox_mode和auto_execute决定了“Codex 能对我的电脑做到什么程度”。4. 实战在 WSL 中用 Codex 完成一次完整任务4.1 建一个“家目录”下的项目我强烈建议你在 WSL 里单独建一个开发目录和 Windows 侧的工作目录分开。以~/dev/demo为例mkdir -p ~/dev/demo cd ~/dev/demo git init然后直接在当前目录启动 Codexcodex进入交互模式后你可以直接描述需求比如“初始化一个 Python 项目包含 README、src/main.py 和一个可以运行的 hello world”。Codex 会读取当前目录结构空目录也没什么然后开始规划步骤。这里有个经验Codex 的交互模式一次只处理一个明确目标别一口气丢太多任务。比如“帮我搭一个 Flask 应用顺便写测试再配好 Dockerfile”它也能做但中途出错的概率更高。更好的做法是拆成几步每步都看结果有问题及时纠正。这样 Codex 每步的上下文窗口都能集中在当前问题上生成质量和执行成功率会高很多。4.2 沙箱与代码执行的权限设置Codex 在执行命令前会先进入沙箱评估操作范围。常见沙箱模式有三种sandbox最严格默认只能访问当前项目中的特定目录和系统白名单。workspace-write允许写当前工作区和相关临时目录比较适合日常开发。danger-full-access完全放行等同于让你自己手动执行命令。日常我推荐workspace-write既能让 Codex 自由创建文件、安装依赖又能限制它不乱动系统其他部分。配置在config.toml的sandbox_mode字段。如果你启动 Codex 时提示 sandbox 相关错误比如找不到bwrap说明 bubblewrap 没装好。装好之后重启终端再试sudo apt install -y bubblewrap codex执行环节有个容易忽略的坑Codex 在沙箱中运行命令时某些依赖编译过程需要更高权限比如apt install沙箱默认会拦截。遇到这种命令Codex 通常会自己提示“需要 sudo 权限”或“建议在沙箱外执行”你可以让它把命令输出给你手动在终端里执行。这是正常的不要指望所有命令都能在沙箱里完成。4.3 配合 VS Code Remote-WSL 的日常工作流文字交互只是 Codex 的一种用法我更推荐把它和 VS Code Remote-WSL 组合起来形成一整套工作流。在 Windows 侧安装 VS Code然后安装 “WSL” 扩展也叫 Remote-WSL。之后在 WSL 终端里进入项目目录直接执行code .VS Code 会以 WSL 连接模式打开当前目录左下角显示 “WSL: Ubuntu”。这时候你的编辑界面跑在 Windows GUI 上但文件操作、终端、调试器全部走 WSL 里的 Linux 环境。你在 VS Code 的集成终端里跑codex左边编辑代码右边和 Codex 对话体验非常顺。这个组合最大的好处是Codex 在终端里生成的代码会直接写进文件VS Code 的编辑器会实时刷新你在右侧窗口就能立刻 review Codex 改了什么。发现问题直接手动改不用来回切换窗口。而且 VS Code 集成的 Git 面板、变量监视、测试运行都能感知到 WSL 文件系统的变化整个链路是“原生”的。4.4 从 WSL 内部快速调用 Windows 工具即使主力环境在 WSL有时候也免不了要和 Windows 侧的工具打交道。WSL 支持 Windows 与 Linux 互操作几个实用命令我经常用# 用 Windows 资源管理器打开当前目录 explorer.exe . # 用 Windows 记事本打开配置文件 notepad.exe ~/.codex/config.toml # 执行一条 Windows 命令比如查看端口占用 cmd.exe /c netstat -ano | findstr :3000如果你发现这些命令提示“找不到”检查一下/etc/wsl.conf中的 interop 设置是否被关闭了默认是开启的[interop] enabledtrue通过这种互操作你可以在 WSL 里写代码和跑 Codex用 Windows 侧的工具进行文件管理、截图、浏览器调试两边各取所长互不干扰。5. 高频报错排查与避坑实录5.1 安装类报错桌面版卡住、npm 权限、脚本拉取失败很多人会遇到 “Codex Windows 安装未完成” 或者桌面版装到一半就没反应的情况。说实话桌面版在 Windows 上的安装器要处理的东西太多GUI、自动更新、权限、网络环境出问题的概率不低。我的建议就是放弃桌面版直接用 WSL 里的 CLI 版。CLI 版安装特别轻量本质上就是下载一个二进制包或 npm 全局包很少出幺蛾子。如果 npm 全局安装时报EACCES: permission denied是 npm 全局目录权限不对。用 nvm 安装 Node.js 可以规避这个问题因为 nvm 会把全局包安装到你用户目录下。如果你已经用系统 Node 装了试试把 npm 全局 prefix 改到用户目录npm config set prefix ~/.npm-global然后重新安装。原生安装脚本如果拉取失败多半是网络问题。检查你的 Windows 侧能否正常访问外网必要时按 2.3 的方式给 WSL 配好代理环境变量再重新执行安装命令。5.2 登录与鉴权类报错无法打开浏览器、auth.json 权限codex login在 WSL 里最常见的问题就是“打不开浏览器”。按前面说的设置BROWSER环境变量指向 Windows 浏览器路径或者干脆手动复制链接到 Windows 浏览器打开这两种方法任选。登录成功之后如果后续使用中报鉴权错误先确认~/.codex/auth.json还是否存在内容是否完整。有时候因为文件权限被改得太严比如其他用户不可读也可能导致 Codex 读取失败把属主设回当前用户即可chmod 600 ~/.codex/auth.json如果你设置了OPENAI_API_KEY又同时有 auth.jsonCodex 会优先用环境变量这个行为偶尔会让人困惑——明明登录了但用的还是 Key 对应的账号。想切换回登录账号就先把环境变量清掉。5.3 “cc switch local proxy failed while handling codex endpoint /responses” 排查这个报错是很多 Windows 用户切到 WSL 后会遇到的。报错里的/responses是 OpenAI responses API 的端点Codex 在访问你自己的模型提供方时切换本地代理失败。什么意思就是 Codex 客户端尝试通过你配置的网络代理去请求模型接口结果代理通道没建立成功。我整理了一张排查对照表可能原因排查方法解决办法代理环境变量指向错误echo $https_proxy看是否指向了不存在的端口修正为正确的代理地址或临时 unset 代理变量测试no_proxy 误伤请求的 endpoint 被 no_proxy 拦了或没被正确排除把 API 域名加入 no_proxy或调整 no_proxy 范围第三方 endpoint 协议不匹配用wire_api chat但实际走/responses逻辑改成与你服务匹配的 wire_apiWindows 防火墙/安全软件拦截WSL 到 Windows 代理端口不通放行对应端口或临时关闭安全软件测试网络本身不通在 WSL 里直接curl base_url测试确认基础网络连通性后再排查代理一个高效的临时排查手段执行curl -v 你的模型接口看能不能通。如果 curl 能通但 Codex 报错问题大概率出在 Codex 的代理配置上如果 curl 都不通那就是网络层的问题先解决网络再说。5.4 WSL 网络慢、DNS 解析异常、npm 拉包慢WSL2 的 DNS 偶尔会抽风典型表现是apt update超时、npm install卡住、git clone 很慢。先看/etc/resolv.conf里的 DNS 是否正常如果不正常可以直接手动改成公共 DNSsudo sh -c echo nameserver 8.8.8.8 /etc/resolv.conf但这种改动重启后可能被覆盖更持久的办法是配置 WSL 的.wslconfig或调整发行版内的 DNS 管理工具具体看你用的 WSL 版本。npm 拉包慢的话可以换镜像源npm config set registry https://registry.npmmirror.comapt 源也可以换成国内镜像这些都属于常规加速手段能显著提升 WSL 里的整体体验。最后说一个容易忽略的点尽量不要在 Windows 上同时跑一套 Codex桌面版又在 WSL 里跑一套 Codex CLI两边如果操作同一个项目目录会出现文件锁、目录权限、node_modules 不一致等奇怪问题。选一条路走到底我推荐 WSL CLI 这条路。个人体验上来讲把 Codex 放进 WSL 之后那些 Windows 专属的“玄学报错”几乎全消失了整个流程变得可控、可预期。如果你还在 Windows 原生环境里和安装器、路径、shell 搏斗不如按这篇文章的思路直接迁移到 WSL一次配置清楚后面真的能省下大量时间。