最近折腾完一套“Windows 主机 + WSL 里的 Ubuntu + VS Code Remote-WSL + OpenAI Codex CLI”的开发环境，说实话，这套组合用顺了以后，我再也不想切回纯 Windows 命令行写东西了。 VS Code 负责编辑体验，Codex 负责在终端里做 AI 结对编程，WSL 则把它们俩接到一个正经的 Linux 环境里，项目里跑的编译、调试、依赖安装全都是 Linux 原生行为。这篇文章我不会讲太虚的理念，直接把我从零搭到能干活的全过程、配置文件、还有踩过的几个坑一并写出来，给想在 WSL 里用 Codex 的朋友一份可以照着抄的作业。
1. 为什么要在 WSL 里同时用 VS Code 和 Codex
1.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 接到 DeepSeek
Codex 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/v1，Codex 也能直接连本地模型。这套灵活性是我最喜欢 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 并初始化 git"exec子命令适合 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 model's context 不够用：compact 失败的解决思路
用 Codex 时间长了，多轮对话后它会提示上下文超长，尝试自动 compact（压缩历史摘要）时偶尔会报 “ran out of room in the model's 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": "c++17", "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”，它会明显减少后续对话里的误解，生成的代码也更贴合项目风格。环境搭好只是起点，怎么把工具用出效率，还是得靠慢慢磨合。
