最近折腾完一套“Windows 主机 WSL 里的 Ubuntu VS Code Remote-WSL OpenAI Codex CLI”的开发环境说实话这套组合用顺了以后我再也不想切回纯 Windows 命令行写东西了。 VS Code 负责编辑体验Codex 负责在终端里做 AI 结对编程WSL 则把它们俩接到一个正经的 Linux 环境里项目里跑的编译、调试、依赖安装全都是 Linux 原生行为。这篇文章我不会讲太虚的理念直接把我从零搭到能干活的全过程、配置文件、还有踩过的几个坑一并写出来给想在 WSL 里用 Codex 的朋友一份可以照着抄的作业。1. 为什么要在 WSL 里同时用 VS Code 和 Codex1.1 WSL2 和虚拟机到底差在哪很多人第一次听说 WSL第一反应是“这不就是个轻量虚拟机吗”。真用下来体感完全不是一回事。虚拟机是把你整个操作系统虚拟化开机、资源占用、文件共享都笨重WSL2 虽然底层也跑在一个轻量虚拟化平台上但它和 Windows 共享网络、共享文件系统进程之间协作非常顺滑。你在 Windows 的C:\projects\my-app里放一份代码WSL 里通过/mnt/c/projects/my-app能直接读写反过来也一样。关键在于WSL 是专门给开发者设计的“桥接式 Linux 环境”不是一台需要维护的完整虚拟电脑。VS Code 的 Remote-WSL 扩展就是把这个桥接体验拉满的那块砖。它的工作机制不是“把 Linux 塞进 VS Code 窗口这么简单”而是 Windows 上的 VS Code 客户端负责界面渲染真正的语言服务、调试器、终端进程全部跑在 WSL 的 Linux 侧。你在 VS Code 里装一个 Python 扩展它会自动安装到 WSL 的远端环境中使用的解释器是 WSL 里的/usr/bin/python3而不是 Windows 下的 Python。这样代码在编辑器里看到的路径、环境变量、依赖树和你在 WSL 终端里手动运行看到的完全一致几乎没有“环境不一致”的折腾空间。1.2 Codex 放到 WSL 里的三个直接好处Codex 是 OpenAI 出的 CLI 编程工具核心交互方式是在终端里用自然语言描述任务然后它会在当前目录上下文里读取文件、生成代码、执行命令甚至直接改文件。这种工具对运行环境的要求特别“Linux 原生”。如果直接装在 Windows 上会遇到路径分隔符、权限模型、符号链接、Node.js 原生模块编译等一堆细碎问题。而 WSL 提供了一个干净的用户空间npm 全局安装、~/.codex配置目录、shell 环境变量全部遵循 Linux 习惯基本不踩 Windows 的坑。第二个好处是工具链打通。Codex 不只写代码它经常会自己跑测试、执行构建命令、检查报错。在 WSL 里这些命令面对的是 Linux 的 gcc、python、docker、bash和你的部署环境基本一致。AI 生成的apt install指令、文件权限调整、日志路径在 WSL 里执行多少遍都不会污染 Windows 系统。第三个好处是权限和路径清晰。Codex 会读取项目里的.gitignore和.codexignore在 WSL 的 home 目录下管理自己的配置文件权限是 600普通用户可读不会出现 Windows 下那种要管理员权限才能改配置的尴尬。尤其当你需要同时操作几个项目时~/.codex放在 Linux 文件系统里备份、迁移都非常清爽。2. 零基础搭建 WSL VS Code 开发环境2.1 wsl --install 一步到位但要注意这些细节Windows 10 版本比较新的机器上安装 WSL 的官方姿势已经简化成一条命令在“管理员权限的 PowerShell 或 Windows Terminal”里执行wsl --install这条命令会默认启用 WSL2下载并安装 Ubuntu 发行版。如果你之前没开过虚拟机平台它会提示你重启电脑。重启后第一次启动 Ubuntu会让你设置 Linux 用户名和密码这个用户名不需要和 Windows 登录名一样密码也不是 Windows 密码它是 WSL 内部独立的。实际操作中很多人会被“下载慢”卡住尤其是wsl --update或wsl --install长时间停在进度条不动。我的经验是先别慌确认 Windows Update 已经装到最新然后重新在管理员终端里跑wsl --update --web-download wsl --install --web-download--web-download是官方提供的下载方式能够绕过一些本地组件更新障碍实测对一部分卡住的情况有效。如果还是慢就干脆先做别的事让它挂着不要反复强杀进程。WSL 内核和发行版镜像的下载体积本身不小网络波动时慢是正常的网上那些所谓“加速脚本”我劝你别碰很容易把 WSL 的发行版注册信息搞坏到时候想卸载都麻烦。装完之后建议立刻执行sudo apt update sudo apt upgrade -y把 Ubuntu 的软件源刷新到最新。这是后续安装 Node.js、构建工具的前提跳过这一步后面装包容易遇到版本过老的问题。2.2 VS Code Remote-WSL 让扩展跑在 Linux 侧VS Code 本体安装在 Windows 侧就行不需要在 Linux 里单独装。装好 VS Code 后打开扩展面板搜索 “Remote – WSL”点 Install。这个扩展是微软官方的安装后 VS Code 的左下角会出现一个绿色的连接图标点击它就能选择 WSL 发行版和目录也可以直接在 WSL 终端的项目目录里输入code .VS Code 会自动以 WSL 连接模式打开当前目录。第一次连接会提示“安装 VS Code Server”这是正常现象VS Code 需要在 WSL 侧放一个轻量服务端进程用来接收 Windows 客户端的指令。这个过程可能需要一两分钟取决于当前网络和机器性能。到这里有个关键点Remote-WSL 连接模式下扩展分为“本地扩展”和“WSL 扩展”。界面美化类的主题、快捷键扩展可以装在本地而语言服务、调试器、格式化工具这类和项目强相关的扩展一定要安装在 WSL 侧。比如你要写 Python打开扩展面板搜索 Python安装时注意面板上会有两个下拉框选择 “Install in SSH: WSL” 或 “Install in WSL: Ubuntu”。否则你装了 Python 扩展但解释器路径还是指到 Windows 的 Python那这不是白折腾吗。顺手提一下很多人进入 WSL 终端后发现字体发虚、中文显示难看。VS Code 默认终端字体在 Linux 下表现一般我后面会在第 4 节给出一个接近 macOS 观感的配置方案。3. 在 WSL 里安装 Codex CLI 并接入 DeepSeek 等模型3.1 用 nvm 安装 Node.js绕开 Windows 权限问题Codex CLI 是 Node.js 应用官方推荐用 npm 全局安装。WSL 默认的 Ubuntu 源里自带的 Node.js 版本比较老直接sudo apt install nodejs装出来很可能不满足 Codex 的版本要求。我建议用 nvm 安装管理 Node.js这样不仅版本可控而且不会因为sudo npm -g产生权限问题。在 WSL 终端里执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后新开一个终端或者执行export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh然后安装最新 LTS 版本并确认版本nvm install --lts nvm use --lts node -v npm -v看到node -v输出 v20 或更高版本就可以继续装 Codex 了npm install -g openai/codex codex --version如果你在 npm 全局安装时遇到权限报错大概率是 Node.js 安装方式有问题回到 nvm 这步重新来。用 nvm 装的 Node.js全局包会写到当前用户的~/.nvm/versions/node/...目录下不需要 sudo这也是为什么我推荐在 WSL 里用 nvm 而不是直接 apt 装。3.2 登录 Codex 的两种姿势与 API Key 管理Codex CLI 支持两种鉴权方式一种是直接用你的 OpenAI 账号做浏览器登录第一次运行codex login时终端会输出一个链接复制到浏览器授权即可。另一种是使用 API Key把 key 设置成环境变量OPENAI_API_KEY就行。我自己的习惯是用 API Key因为可复用、可控量、方便切换。不要把 API Key 写死在项目文件里更不要贴到代码仓库。正确做法是写到你的 shell 配置文件中echo export OPENAI_API_KEY你的key ~/.bashrc source ~/.bashrcCodex 在启动时会自动读取这个环境变量。如果你同时配了多个模型服务商Codex 的配置也支持分别管理不同 provider 的 key。配置文件在~/.codex/config.toml下面会详细说。注意~/.codex目录默认只有当前用户可读这是正确的不要为了省事 chmod 777。密钥文件一旦被其他用户或进程读到后果你自己能想到。3.3 改一行配置把 Codex 接到 DeepSeekCodex CLI 最吸引我的地方是它不锁死模型厂商。它支持通过 OpenAI 兼容的接口配置第三方模型服务比如 DeepSeek 这类提供 OpenAI 兼容 API 的服务商。这样你不需要 OpenAI 账号也能用上 Codex 的交互体验。在~/.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然后同样在~/.bashrc里导出export DEEPSEEK_API_KEY你的DeepSeek key重启 WSL 终端或者source ~/.bashrc再运行codex此时 Codex 就会使用 DeepSeek 的模型来完成对话和代码生成。我自己用下来DeepSeek 的推理质量在代码任务上表现相当稳定关键是费用比直接调 OpenAI 便宜不少。除了 DeepSeek任何提供 OpenAI 兼容/v1/responses或/v1/chat/completions接口的服务都可以这么接。甚至你本地跑一个 vLLM 或其他推理框架只要把base_url指到http://localhost:8000/v1Codex 也能直接连本地模型。这套灵活性是我最喜欢 Codex CLI 的地方它把“AI 编程助手”从单一厂商的产品变成了一个可插拔工具链。4. VS Code 集成 Codex 的实操技巧与终端调优4.1 在 VS Code 集成终端里跑 Codex 的日常操作有了 WSL 和 Codex CLI 之后日常开发我基本不跳出 VS Code。按Ctrl \ 打开集成终端默认已经进入 WSL 的 bash 环境。在这个终端里直接输入codex就会进入 Codex 的交互式 REPL。常用几个命令记录一下codex进入交互模式在提示符后面描述任务例如“给当前目录下的 main.py 添加参数校验”。codex 帮我写一个 bash 脚本统计当前目录下所有 .log 文件的行数非交互模式跑完直接结束适合快速问问题或生成一次性脚本。codex exec 给这个项目加一个 README.md 并初始化 gitexec子命令适合 CI 或脚本调用。不过日常我更喜欢用纯交互模式因为 Codex 在交互模式里能记住前面的上下文连续多轮修改同一个文件非常方便。实操中我习惯先把项目在 VS Code 里打开确认左侧资源管理器能看到目标文件然后再启动 Codex。因为 Codex 会读取当前工作目录下的文件结构如果目录不对它很容易在错误的位置创建文件。另外Codex 会尝试执行命令完成任务执行前一般会询问你注意看它的执行计划不要在项目目录里乱放敏感命令。4.2 装一个 Codex 扩展让 AI 直接出现在编辑区如果你不想只在终端里和 Codex 对话VS Code 的扩展市场里也能找到 Codex 相关的扩展。以官方或社区维护的 Codex 扩展为例安装到 WSL 侧后你可以直接用鼠标选中代码右键选择“Ask Codex”结果会出现在侧边栏面板中。我实际用下来的感受是扩展适合做局部代码解释、生成单元测试、解释报错信息这类“细颗粒度”任务而大型重构、跨文件修改还是终端里用 Codex 的完整会话模式更顺手。因为终端模式里 Codex 拥有完整的 shell 权限可以自己跑测试、自己看报错扩展模式目前还做不到这么自主。如果你装的 Codex 扩展没有出现在 WSL 侧可以在扩展面板里找到该扩展点击设置选择“Install in WSL: Ubuntu”。如果扩展本身不支持 Linux 远端那就保持终端模式使用别硬装后面我会说我踩过的扩展兼容性坑。4.3 终端和字体调优让 WSL 里有 macOS 的清爽感很多人从 macOS 切到 Windows WSL最不习惯的是终端字体渲染。WSL 终端里的默认字体常常又细又虚看久了眼睛累。VS Code 里可以通过设置面板调整打开设置Ctrl,搜索字体把editor.fontFamily和terminal.integrated.fontFamily设成{ editor.fontFamily: Cascadia Code, JetBrains Mono, Fira Code, monospace, editor.fontSize: 14, editor.fontLigatures: true, terminal.integrated.fontFamily: Cascadia Code, JetBrains Mono, monospace, terminal.integrated.fontSize: 14, terminal.integrated.lineHeight: 1.2 }Cascadia Code是微软出品的等宽字体最接近 Windows Terminal 原生观感JetBrains Mono是我个人在 WSL 里最喜欢的一款字重清晰和 macOS 上 SF Mono 的清爽感比较接近。启用字体连字fontLigatures后-、、会显示成连贯字符写代码的“顺滑感”会明显提升。顺便把 WSL 集成终端的默认配置文件指定为 bash。在 VS Code 设置里搜索defaultProfile选择 Linux 的 bash 即可。这样每次打开终端都是干净的 Linux 环境不会再弹到 Windows PowerShell。5. 我踩过的五个坑问题定位与修复实录5.1 下载慢、更新慢WSL 安装卡的通用解法我在一开始搭建时wsl --install就卡在“正在安装 Ubuntu”半天不动。后来发现是 Windows 侧的组件版本太旧。解决办法是去 Windows Update 把系统补丁打到最新然后重新在管理员终端执行wsl --update --web-download等它跑完后再次wsl --install。如果你已经安装好 WSL但启动时提示版本太老一般也要跑这个命令更新。另外发行版的下载如果非常慢可以换一个思路去微软商店或者 WSL 发行版官网手动下载.wsl或.appx安装包然后使用wsl --import导入。这个方法更适合网络穿透性差的场景虽然是手动操作但胜在可控。重要不到万不得已不要用第三方脚本强行加速。WSL 涉及底层系统组件一旦搞坏重装成本远大于耐心等待的成本。5.2 本地网络切换失败导致 Codex 接口报错我是这样处理的在 WSL 里跑 Codex 时偶尔会遇到一个和本地网络切换相关的报错大概意思是“在处理 Codex 端点时本地转发服务切换失败”。我遇到这个报错时Codex 还没真正把请求发出去就直接退出了。排查思路是WSL 的网络栈和 Windows 的底层网络设置不是完全同步的Windows 侧网络发生变化后WSL 内可能还保留着旧的网络状态。我试过最有效的办法是彻底重启 WSL在 Windows 管理员 PowerShell 里执行wsl --shutdown然后重新打开 WSL 终端再次运行codex。如果还是报错再检查~/.codex/config.toml里的base_url是否能正常访问直接用curl -I验证一下接口连通性。这类问题绝大多数不是 Codex 本身坏了而是运行环境网络状态没刷新。5.3 models context 不够用compact 失败的解决思路用 Codex 时间长了多轮对话后它会提示上下文超长尝试自动 compact压缩历史摘要时偶尔会报 “ran out of room in the models context”。这个错误说白了就是模型窗口塞不下当前会话的完整历史了压缩历史的动作本身也需要消耗 token结果也放不进去了。解决方案不是去调大窗口而是减少单次会话的信息量。最直接的方法是输入/new开启新会话把已经完成的对话清空。如果你的项目文件很大Codex 会自动读取部分文件内容作为上下文这时可以新建一个.codexignore文件把不必要的目录排除掉node_modules/ dist/ build/ *.min.js *.log .git/这样 Codex 就不会把整个巨型项目都读进上下文。需要长会话时我还会显式配置模型提供商的上下文窗口上限避免它尝试塞入超出实际能力的文本。5.4 顺手解决 C/C 头文件红波浪线既然在 WSL 里写代码很多人会顺带开 C/C 项目。一个经典问题是用 VS Code 打开 WSL 项目时#include stdio.h这类头文件下面出现红色波浪线提示找不到文件。这是因为 VS Code 的 C/C 扩展不认识 WSL 的编译器路径。解决方式是在项目根目录新建.vscode/c_cpp_properties.json把 includePath 指向 WSL 系统头文件目录{ configurations: [ { name: Linux, includePath: [ ${workspaceFolder}/**, /usr/include/**, /usr/local/include/** ], defines: [], compilerPath: /usr/bin/gcc, cStandard: c17, cppStandard: c17, intelliSenseMode: linux-gcc-x64 } ], version: 4 }关键就是compilerPath和intelliSenseMode这两项告诉扩展去 WSL 里找编译器和头文件。设置后重启 VS Code红波浪线基本就消失了。5.5 Codex 扩展在 WSL 侧失效时怎么保证工作流不断有一阵子我用的 Codex 扩展更新后在 WSL 远端一直转圈怎么装都进不了侧边栏。查了半天发现是扩展最新版对 Linux 远端的 Node 版本要求变了旧版 Node.js 不匹配。解决办法很简单先把 WSL 里的 Node.js 升级到 lts 最新版然后重新加载 VS Code 窗口扩展就正常了。如果遇到的扩展问题没法快速解决我的兜底方案是回到集成终端用 Codex CLI。反正终端模式功能完整只是界面没那么花哨工作流不会断。这让我意识到用 CLI 工具的好处之一就是它不依赖某个 IDE 扩展的维护节奏哪怕扩展坏了核心能力一直可用。我自己后来把 Codex 扩展的自动更新关掉了固定在一个稳定版本避免版本漂移导致 WSL 环境又出幺蛾子。毕竟工具是拿来干活的稳定比花哨重要得多。这套组合我目前已经连续用了小半年日常写 Python、Shell、Go 项目都直接在 VS Code 里完成Codex 帮我处理重复性代码、写测试、查文档省下的时间非常可观。最后再分享一个我自己的小习惯每次开始一个新任务前先给 Codex 一条简短的“项目背景”提示比如“这是一个 FastAPI 项目代码在 app/ 目录下测试用 pytest”它会明显减少后续对话里的误解生成的代码也更贴合项目风格。环境搭好只是起点怎么把工具用出效率还是得靠慢慢磨合。