聊到 VS Code、WSL、Codex 这三个词最近不少人在折腾“Windows 上写代码怎么才能更顺”。尤其是从 macOS 切到 Windows 的开发者体验过类 Unix 终端之后回到 cmd 或 PowerShell 总觉得浑身不对劲。而 Codex 这种能在终端里自主读取项目、改文件、跑命令的 AI 编码代理又对执行环境非常敏感——你在 Windows 里让它跑grep、make、python3和让它跑.bat完全是两码事。这篇文章就是一份踩坑实录。我把自己在 WSL 里把 VS Code Codex 这套链路跑通的过程完整写下来包括 WSL 安装太慢怎么处理、VS Code 怎么正确连进 WSL、Codex 怎么安装登录、怎么接第三方模型比如 DeepSeek、Kimi以及几个高频报错的排查方法。适合刚准备入坑的同学也适合已经在用但被各种报错折磨的人直接照着操作基本能省下大半天时间。1. 为什么推荐把 Codex 跑在 WSL 里1.1 WSL 不是虚拟机是 Windows 里的“Linux 子系统”很多人一听 WSL2 觉得它就是个虚拟机这理解不够准确。WSL2 确实基于 Hyper-V 的轻量级虚拟机但它的启动速度、内存占用、文件访问体验都跟“开虚拟机”完全不同而且和 Windows 的集成度极高。你在 Windows 文件资源管理器里能直接访问 Linux 文件在终端里敲wsl就进入 Ubuntu在 VS Code 里能直接把 WSL 当成远程目标连进去。这种体验更像“Windows 里内置了一个 Linux 运行时”。Codex 做的事情不只是补全代码它要读文件、执行命令、看测试输出、根据报错反复调整。这就意味着它对“当前环境”的理解至关重要。你在 Windows cmd 里运行代码和在 Linux bash 里运行代码涉及到的路径、Shell 语法、换行符、权限模型都不同。如果让 Codex 在 WSL 这个真正的 Linux 环境里干活它给出的命令、路径、排查思路会更贴近实际部署环境这比在 Windows 终端里硬撑着高效得多。1.2 什么场景下最值得用这套组合我给周边朋友推荐这套组合主要是因为它能覆盖几类非常实际的开发场景本地写 Python、Go、Rust 或者做 Web 全栈经常要跟 Linux 命令和包管理器打交道。项目自带 Makefile、CMake、Shell 脚本必须有一个 POSIX 环境才能跑起来。做 AI 或机器学习要在 WSL 里装 CUDA 跑 PyTorch或者需要 Linux 工具链做数据处理。代码最终部署在 Linux 服务器上希望本地开发环境和线上尽量一致。想让 Codex 辅助写代码、改 Bug又希望它执行命令时的行为和服务器上一致。说白了这套组合解决的核心问题就一个在 Windows 上拥有一个贴近生产环境的开发环境同时享受 IDE 图形界面和 AI 编码代理的便利。没有 Mac也能有接近 Mac 的类 Unix 开发体验这话一点都不夸张。2. 前置准备把 WSL 装得又快又对2.1 Windows 10 与 Windows 11 安装 WSL 的操作差异如果你用的是 Windows 11安装 WSL 最简单管理员终端里直接执行wsl --install它会自动帮你启用需要的 Windows 功能、安装 WSL2 内核并默认安装一个 Ubuntu 发行版。如果不想用默认发行版也可以指定wsl --install -d Ubuntu-22.04Windows 10 相对麻烦一点。系统版本在 21H2 以上的同样支持wsl --install但更稳妥的做法是先手动启用两个功能“适用于 Linux 的 Windows 子系统”和“虚拟机平台”。在“启用或关闭 Windows 功能”里找到这两项勾选重启后再执行安装命令。老版本系统如果执行wsl --install没反应那就先检查系统更新把补丁打齐再试。装完之后顺手执行一句wsl --set-default-version 2确保默认使用 WSL2 而不是 WSL1。WSL1 是系统调用翻译层兼容性差很多依赖 Docker、CUDA、复杂文件系统的场景跑不起来直接用 WSL2 省心得多。2.2wsl --install或wsl --update太慢怎么办这是被问得最多的一个问题。wsl --install在执行时要下载内核和发行版镜像如果网络环境不理想确实可能卡在进度条上很久不动。我自己的做法是在这三个方案里来回切换首先如果安装卡住不要反复在同一终端里重试。先执行wsl --shutdown把 WSL 相关进程全部停掉再重新开一个管理员终端执行安装命令。其次可以跳过命令行的在线下载环节。微软在 GitHub 上发布了 WSL 的 Release 安装包直接下载最新的.msi文件双击运行然后执行wsl --version确认版本。这种方式对wsl --update同样适用在线更新慢就下载离线包覆盖安装。还有一种场景你已经装了 WSL但只是想换一个发行版或者重新导入一个 Linux 环境。可以从发行版官方渠道获取 rootfs 压缩包然后用wsl --import导入路径和名称自己指定完全可以绕开微软商店下载慢的问题。这种方式在 Win10 上尤其好用因为商店的下载进度经常死活不更新。2.3 提示 “Your version of WSL is too old” 怎么解决很多人在执行wsl --update或打开某些项目时会看到类似提示Your version of Windows Subsystem for Linux (WSL) is too old. Run the command wsl --update...这种情况一般是 WSL 内核或应用版本过低。解决办法很简单管理员 PowerShell 里执行wsl --update如果更新流程走不通还是那句话去下载最新的 WSL Release 离线包覆盖安装。升级完再执行wsl --version看到 2.x 版本号就正常了。Win10 用户如果连wsl --update都不识别先把系统更新到 2004 及以上版本然后检查 Windows 功能里是否启用了“虚拟机平台”。3. VS Code 连接 WSL 的完整配置3.1 Remote - WSL 插件的安装与连接VS Code 连接 WSL 依赖微软官方的Remote - WSL扩展。在扩展市场搜索“WSL”第一个就是安装后左侧活动栏会出现远程连接图标。连接流程非常简单按CtrlShiftP打开命令面板。输入WSL: Connect to WSL选择你的 Linux 发行版。等待 VS Code 在 WSL 内自动安装 Server 组件。连接成功后左下角会显示类似WSL: Ubuntu的标记。还有一种更常用的方式在 WSL 终端里直接进入项目目录并执行code .VS Code 会自动识别这是 WSL 环境并重新打开为一个 WSL 连接窗口直接定位到当前目录非常顺手。第一次连接时 VS Code 会在 WSL 里自动安装服务端需要一点时间别急着关窗口。连接后需要注意扩展的安装位置和语言、调试相关的扩展比如 Python、C/C、Rust要安装在 WSL 这一侧而主题、图标这类 UI 扩展Windows 侧就够了。VS Code 会自动提示你“是否在 WSL 中安装此扩展”点安装即可。3.2 字体、终端体验尽量贴近 macOS 的观感很多人关心 WSL 终端里的字体怎么设置才能好看。注意一点WSL 本身不决定字体终端字体由 VS Code 渲染。所以你只需要调整 VS Code 的设置项即可。我个人的配置是这样在settings.json里加进去{ terminal.integrated.fontFamily: Sarasa Term SC, JetBrains Mono, Menlo, Monaco, Courier New, monospace, editor.fontFamily: JetBrains Mono, Sarasa Term SC, Menlo, Monaco, Courier New, monospace, terminal.integrated.fontSize: 14, editor.fontSize: 14, terminal.integrated.lineHeight: 1.6, editor.lineHeight: 1.6 }解释一下这几个字体选择。Sarasa Term SC更纱黑体终端版在中文、英文、标点对齐上做得很均匀终端里同时存在中文和英文时不会出现参差不齐的情况。JetBrains Mono是 JetBrains 出的代码字体数字和运算符识别度高看代码不累。这两个字体组合起来配合 1.6 的行高整体视觉效果跟我之前在 macOS 上的终端体验已经很接近了。如果你遇到中文乱码或者方块字多半不是字体问题而是编码问题。检查文件是否 UTF-8 编码或者在 WSL 里执行sudo locale-gen zh_CN.UTF-8然后重新打开终端。3.3 在 WSL 里配置 C/C、Python 等基础环境VS Code 连上 WSL 之后空荡荡的 Linux 环境需要补一点基础工具链。执行sudo apt update sudo apt install -y build-essential gdb python3 python3-venv python3-pipbuild-essential会装好 gcc、g、make 等编译工具这是 C/C 开发的前提。装上之后如果 VS Code 里打开.c或.cpp文件时#include依然有红色波浪线通常是 IntelliSense 找不到编译器路径。解决方法是创建.vscode/c_cpp_properties.json把compilerPath指向{ configurations: [ { name: Linux, compilerPath: /usr/bin/gcc, intelliSenseMode: linux-gcc-x64, includePath: [${workspaceFolder}/**] } ], version: 4 }这一招对 WSL 环境下的 C 项目基本是通用解法。Python 环境则建议给每个项目建一个 venv避免全局包越装越乱。4. Codex CLI 的安装、登录和模型接入4.1 在 WSL 里安装 Codex强烈建议在 WSL 环境里安装 Codex而不是直接在 Windows 上装。Windows 下的 npm 全局安装经常遇到权限、路径、进程占用问题安装到一半失败是常事在 WSL 里路径机制和 Linux 服务器一致安装干净利落。先在 WSL 终端里确认 Node 环境node -v npm -v如果没有 Node先装一个sudo apt install -y nodejs npm建议用 nvm 管理 Node 版本避免系统包版本太旧。接着全局安装 Codex CLInpm install -g openai/codex安装完成后验证版本codex --version出现版本号就说明装好了。如果 npm 全局目录不在 PATH 中检查一下 npm 的 prefix 配置把$(npm prefix -g)/bin加进 PATH。4.2 Codex 登录OAuth 或 API KeyCodex 登录最常见的方式是交互式授权codex login终端会输出一个授权链接浏览器打开、登录账号、确认授权后本地 Codex 就能正常调起服务了。WSL 里偶尔会出现打开浏览器不顺畅的情况可以直接复制终端里的 URL手动到 Windows 侧浏览器打开。如果你更习惯用 API Key 方式执行codex login --help看看支持的参数。多数版本都支持 API Key 登录或者你也可以直接在配置文件里指定环境变量名称让 Codex 从环境变量里读取密钥这个下面一节会详细讲。注意不要把 Key 直接写进项目代码或公网仓库Key 是用来验证身份的泄露了等于把控制权交出去了。4.3 把 Codex 接到 DeepSeek、Kimi 等第三方模型Codex CLI 默认连接 OpenAI 官方服务但它的配置文件支持自定义模型提供方Model Provider。如果你用的是 DeepSeek、KimiMoonshot这类兼容 OpenAI 接口的服务完全可以改配置。Codex 的配置文件路径在~/.codex/config.toml。DeepSeek 的配置示例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你的Key之后再运行codex它就会走 DeepSeek 的模型。Kimi 也是一样的套路base_url 换成https://api.moonshot.cn/v1model 换成moonshot-v1-8k或服务商支持的其他型号即可。关于wire_api字段简单解释一下OpenAI 官方接口现在用的是responses协议很多兼容服务商用的是经典的chatChat Completions协议。Codex 需要知道目标服务的协议类型才能正确组织请求。判断不了的时候优先用chat绝大多数兼容服务都支持。不同版本 Codex 对配置字段的解析可能略有差异以你本机的codex --help和官方文档为准。除了 CLIVS Code 生态里也有各种 AI 插件可以接入兼容 API但核心逻辑都一样设置 base_url、填 Key、选模型。CLI 的好处是轻量、可脚本化而且能直接在终端里结合自动化流程。5. 高概率踩坑Codex 在 WSL 里的报错与排查5.1 “cc switch local proxy failed while handling codex endpoint” 怎么处理这个报错我在排查环境时见过几次。先看错误形态cc switch local proxy failed while handling codex endpoint /responses这个报错的典型场景是你用了某些 Codex 配置切换工具比如cc switch把 Codex 的 API 端点从官方地址切到本地某个代理端口用于本地调试、流量转发或者接入自建网关。切换之后Codex CLI 在请求/responses端点时发现本地代理服务不可用于是报错。排查步骤按顺序来打开~/.codex/config.toml确认当前base_url指向哪里。如果指向127.0.0.1或localhost的某个端口说明请求正在走本地代理链路。检查该端口是否真的在监听ss -tlnp | grep 端口号没有任何输出说明代理服务没起来。先启动你配置的那个本地服务再重试 Codex。如果不想走本地代理直接把base_url改回官方 API 地址或者删掉自定义 provider重新执行codex。检查环境变量里是否有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY指向不存在的地址。这种情况非常隐蔽环境变量会让所有 HTTP 请求都走一个死代理。临时验证可以执行unset HTTP_PROXY HTTPS_PROXY ALL_PROXY再跑 Codex。如果恢复正常说明就是环境变量的问题。想看更详细的请求日志用调试模式跑一次RUST_LOGdebug codex exec test可以看到请求发往哪个地址、在哪里失败。日志会明明白白告诉你问题出在连接还是协议上。5.2 “codex ran out of room in the model’s context” 上下文爆了的处理另一个高频报错是error running remote compact task: codex ran out of room in the models context这个错误的意思是当前会话的上下文窗口已经满了Codex 尝试自动压缩上下文以继续对话但压缩过程本身也因为上下文空间不足而失败。处理思路有几个方向。最直接的方法就是新开一个会话。在codex交互界面里退出重进之前对话的上下文就清空了。这是最简单有效的操作。更重要的是调整使用习惯。不要一次性把整个项目文件内容都塞给 Codex不要执行cat 大文件之后把全部输出贴进 prompt。你描述清楚需求让 Codex 自己去读文件、搜代码这样每次对话占用的上下文会少很多。如果模型本身上下文窗口就小可以考虑在配置里换用上下文更大的模型。比如很多第三方兼容模型有 64K 甚至 128K 的上下文版本对应 Codex 能记住的信息量也会增加。另外拆分任务也是一种解法把一个大型重构拆成多个小步骤每步单独开会话比让 Codex 一口气啃完整个项目要稳得多。5.3 其他常见报错速查表我在折腾这套环境的过程中还遇到过不少零碎问题整理成一个速查表方便你直接对号入座。现象可能原因处理思路Windows 下npm install -g openai/codex安装中断权限不足、路径冲突、杀毒拦截换到 WSL 里安装管理员终端重试codex login后浏览器不自动打开WSL 缺少默认浏览器关联复制终端里的授权链接手动用 Windows 浏览器打开VS Code 提示 WSL server 启动失败WSL 版本过旧或内核异常执行wsl --update再wsl --shutdown后重连打开 C 文件#include红波浪线没装编译器或 includePath 缺失apt install build-essential配置c_cpp_properties.json终端中文乱码locale 或字体问题设置zh_CN.UTF-8VS Code 字体换成 Sarasa 系列Codex 执行命令提示权限不够某些文件由 Windows 侧创建权限混杂用chmod修复文件权限或把项目放到 WSL 内部目录codex提示找不到命令npm 全局目录不在 PATH把$(npm prefix -g)/bin加入 PATH5.4 关于 WSL 里那些“顺便能救”的本地问题还有一个很容易忽略的点VS Code WSL 这套环境本身就能顺手解决很多在其他教程里看到的热门问题。比如你本地跑 Qt 5.9 项目配置不顺利、Spring Boot 项目启动报环境错误、甚至用 binwalk 做固件分析时缺依赖本质上都是“Linux 环境不完整”导致的。在 WSL 里安装对应开发库之后VS Code 的智能提示和 Codex 的代码分析能够一起工作解决这些问题的速度会快很多。所以不用把眼光局限在“AI 编码”上WSL 这一层先把环境基础打牢后面都是水到渠成的事。6. 一条个人认为最顺手的日常工作流6.1 从拉代码到让 Codex 干活现在说下我每天都在用的一条链路整体跑通之后基本是肌肉记忆wsl进入 Ubuntu。cd到项目目录。执行code .VS Code 自动连接 WSL 并打开项目。打开集成终端确保终端路径也在项目目录里。执行codex exec 分析一下当前项目的结构和启动方式先让 Codex 理解项目。接下来就是循环给它具体任务让它改代码、跑测试遇到报错直接把报错喂回去继续问。涉及批量替换或者大范围重构时用codex exec --full-auto让它自动搜索替换但执行前一定要先看git diff。这里有一个非常重要的习惯让 Codex 动手改代码之前先把当前状态提交一次 git。哪怕只是git add -A git commit -m before codex这样的临时提交也能在代码被改乱时随时回滚。AI 编码代理不是每次都百分之百正确的它很容易在某个细节上“自信地犯错”没有 git 兜底你会非常被动。6.2 进阶在 WSL 里让 Codex 配合复杂环境如果你要在 WSL 里跑 PyTorch 或者搞 CUDA 相关开发有几点可以说一下。WSL2 是支持 GPU 直通的Windows 侧安装好 NVIDIA 驱动之后WSL 内不用再装显卡驱动但需要在 WSL 里安装 CUDA toolkit 和 cuDNN。执行nvidia-smi能看到显卡信息就说明 GPU 环境基本就绪。Codex 在这种复杂环境里的价值在于它不会凭空猜而是会基于你当前环境里的报错信息去推理。你可以让它写一个 PyTorch 训练脚本它会考虑到 WSL 下的路径风格、CUDA 版本、Python 虚拟环境等因素。使用虚拟环境的习惯一定要养成python3 -m venv venv source venv/bin/activate pip install torch --index-url https://download.pytorch.org/whl/cu118装完之后在 Python 里执行import torch print(torch.cuda.is_available())如果输出True说明 GPU 环境已经通了。这种验证习惯同样可以迁移到 Codex 的用法上每次让它改完环境相关的东西记得先跑一条最小验证命令别急着跑大任务。对于 C、Spring Boot 这类项目WSL 里同样能用 Codex 做编译问题排查。它比搜索引擎强的地方在于能结合你本机的具体文件和报错一步步缩小问题范围。比如 CMake 配置出问题把 CMakeLists.txt 和相关报错贴给它它通常能快速定位到是路径写错还是依赖缺失。最后再分享一个小技巧Codex 的会话是有上下文限制的长时间使用后它会变得“健忘”。我的习惯是每完成一个小任务就让它输出一份简短的变更总结然后开新会话继续下一个任务。这样既保留了关键信息又能一直保持会话上下文的清澈报错率低很多。我实际使用下来的体会是VS Code、WSL、Codex 这三个工具单独拎出来都不稀奇但组合起来的体验提升是质变。尤其是对于主力机型是 Windows、又必须面向 Linux 环境开发的人来说这套组合能消掉绝大部分“环境不对”导致的烦躁。踩过几次坑之后最重要的一句话就是先把 WSL 和 VS Code 的底层环境弄稳再让 Codex 进场干活顺序别反了。环境不稳的时候AI 的聪明才智都浪费在和环境搏斗上了稳了之后才能真正体会到那种“想个思路就能看它帮你把活干了”的爽感。
VS Code + WSL + Codex：Windows上搭建Linux开发环境与AI编码代理实战
聊到 VS Code、WSL、Codex 这三个词最近不少人在折腾“Windows 上写代码怎么才能更顺”。尤其是从 macOS 切到 Windows 的开发者体验过类 Unix 终端之后回到 cmd 或 PowerShell 总觉得浑身不对劲。而 Codex 这种能在终端里自主读取项目、改文件、跑命令的 AI 编码代理又对执行环境非常敏感——你在 Windows 里让它跑grep、make、python3和让它跑.bat完全是两码事。这篇文章就是一份踩坑实录。我把自己在 WSL 里把 VS Code Codex 这套链路跑通的过程完整写下来包括 WSL 安装太慢怎么处理、VS Code 怎么正确连进 WSL、Codex 怎么安装登录、怎么接第三方模型比如 DeepSeek、Kimi以及几个高频报错的排查方法。适合刚准备入坑的同学也适合已经在用但被各种报错折磨的人直接照着操作基本能省下大半天时间。1. 为什么推荐把 Codex 跑在 WSL 里1.1 WSL 不是虚拟机是 Windows 里的“Linux 子系统”很多人一听 WSL2 觉得它就是个虚拟机这理解不够准确。WSL2 确实基于 Hyper-V 的轻量级虚拟机但它的启动速度、内存占用、文件访问体验都跟“开虚拟机”完全不同而且和 Windows 的集成度极高。你在 Windows 文件资源管理器里能直接访问 Linux 文件在终端里敲wsl就进入 Ubuntu在 VS Code 里能直接把 WSL 当成远程目标连进去。这种体验更像“Windows 里内置了一个 Linux 运行时”。Codex 做的事情不只是补全代码它要读文件、执行命令、看测试输出、根据报错反复调整。这就意味着它对“当前环境”的理解至关重要。你在 Windows cmd 里运行代码和在 Linux bash 里运行代码涉及到的路径、Shell 语法、换行符、权限模型都不同。如果让 Codex 在 WSL 这个真正的 Linux 环境里干活它给出的命令、路径、排查思路会更贴近实际部署环境这比在 Windows 终端里硬撑着高效得多。1.2 什么场景下最值得用这套组合我给周边朋友推荐这套组合主要是因为它能覆盖几类非常实际的开发场景本地写 Python、Go、Rust 或者做 Web 全栈经常要跟 Linux 命令和包管理器打交道。项目自带 Makefile、CMake、Shell 脚本必须有一个 POSIX 环境才能跑起来。做 AI 或机器学习要在 WSL 里装 CUDA 跑 PyTorch或者需要 Linux 工具链做数据处理。代码最终部署在 Linux 服务器上希望本地开发环境和线上尽量一致。想让 Codex 辅助写代码、改 Bug又希望它执行命令时的行为和服务器上一致。说白了这套组合解决的核心问题就一个在 Windows 上拥有一个贴近生产环境的开发环境同时享受 IDE 图形界面和 AI 编码代理的便利。没有 Mac也能有接近 Mac 的类 Unix 开发体验这话一点都不夸张。2. 前置准备把 WSL 装得又快又对2.1 Windows 10 与 Windows 11 安装 WSL 的操作差异如果你用的是 Windows 11安装 WSL 最简单管理员终端里直接执行wsl --install它会自动帮你启用需要的 Windows 功能、安装 WSL2 内核并默认安装一个 Ubuntu 发行版。如果不想用默认发行版也可以指定wsl --install -d Ubuntu-22.04Windows 10 相对麻烦一点。系统版本在 21H2 以上的同样支持wsl --install但更稳妥的做法是先手动启用两个功能“适用于 Linux 的 Windows 子系统”和“虚拟机平台”。在“启用或关闭 Windows 功能”里找到这两项勾选重启后再执行安装命令。老版本系统如果执行wsl --install没反应那就先检查系统更新把补丁打齐再试。装完之后顺手执行一句wsl --set-default-version 2确保默认使用 WSL2 而不是 WSL1。WSL1 是系统调用翻译层兼容性差很多依赖 Docker、CUDA、复杂文件系统的场景跑不起来直接用 WSL2 省心得多。2.2wsl --install或wsl --update太慢怎么办这是被问得最多的一个问题。wsl --install在执行时要下载内核和发行版镜像如果网络环境不理想确实可能卡在进度条上很久不动。我自己的做法是在这三个方案里来回切换首先如果安装卡住不要反复在同一终端里重试。先执行wsl --shutdown把 WSL 相关进程全部停掉再重新开一个管理员终端执行安装命令。其次可以跳过命令行的在线下载环节。微软在 GitHub 上发布了 WSL 的 Release 安装包直接下载最新的.msi文件双击运行然后执行wsl --version确认版本。这种方式对wsl --update同样适用在线更新慢就下载离线包覆盖安装。还有一种场景你已经装了 WSL但只是想换一个发行版或者重新导入一个 Linux 环境。可以从发行版官方渠道获取 rootfs 压缩包然后用wsl --import导入路径和名称自己指定完全可以绕开微软商店下载慢的问题。这种方式在 Win10 上尤其好用因为商店的下载进度经常死活不更新。2.3 提示 “Your version of WSL is too old” 怎么解决很多人在执行wsl --update或打开某些项目时会看到类似提示Your version of Windows Subsystem for Linux (WSL) is too old. Run the command wsl --update...这种情况一般是 WSL 内核或应用版本过低。解决办法很简单管理员 PowerShell 里执行wsl --update如果更新流程走不通还是那句话去下载最新的 WSL Release 离线包覆盖安装。升级完再执行wsl --version看到 2.x 版本号就正常了。Win10 用户如果连wsl --update都不识别先把系统更新到 2004 及以上版本然后检查 Windows 功能里是否启用了“虚拟机平台”。3. VS Code 连接 WSL 的完整配置3.1 Remote - WSL 插件的安装与连接VS Code 连接 WSL 依赖微软官方的Remote - WSL扩展。在扩展市场搜索“WSL”第一个就是安装后左侧活动栏会出现远程连接图标。连接流程非常简单按CtrlShiftP打开命令面板。输入WSL: Connect to WSL选择你的 Linux 发行版。等待 VS Code 在 WSL 内自动安装 Server 组件。连接成功后左下角会显示类似WSL: Ubuntu的标记。还有一种更常用的方式在 WSL 终端里直接进入项目目录并执行code .VS Code 会自动识别这是 WSL 环境并重新打开为一个 WSL 连接窗口直接定位到当前目录非常顺手。第一次连接时 VS Code 会在 WSL 里自动安装服务端需要一点时间别急着关窗口。连接后需要注意扩展的安装位置和语言、调试相关的扩展比如 Python、C/C、Rust要安装在 WSL 这一侧而主题、图标这类 UI 扩展Windows 侧就够了。VS Code 会自动提示你“是否在 WSL 中安装此扩展”点安装即可。3.2 字体、终端体验尽量贴近 macOS 的观感很多人关心 WSL 终端里的字体怎么设置才能好看。注意一点WSL 本身不决定字体终端字体由 VS Code 渲染。所以你只需要调整 VS Code 的设置项即可。我个人的配置是这样在settings.json里加进去{ terminal.integrated.fontFamily: Sarasa Term SC, JetBrains Mono, Menlo, Monaco, Courier New, monospace, editor.fontFamily: JetBrains Mono, Sarasa Term SC, Menlo, Monaco, Courier New, monospace, terminal.integrated.fontSize: 14, editor.fontSize: 14, terminal.integrated.lineHeight: 1.6, editor.lineHeight: 1.6 }解释一下这几个字体选择。Sarasa Term SC更纱黑体终端版在中文、英文、标点对齐上做得很均匀终端里同时存在中文和英文时不会出现参差不齐的情况。JetBrains Mono是 JetBrains 出的代码字体数字和运算符识别度高看代码不累。这两个字体组合起来配合 1.6 的行高整体视觉效果跟我之前在 macOS 上的终端体验已经很接近了。如果你遇到中文乱码或者方块字多半不是字体问题而是编码问题。检查文件是否 UTF-8 编码或者在 WSL 里执行sudo locale-gen zh_CN.UTF-8然后重新打开终端。3.3 在 WSL 里配置 C/C、Python 等基础环境VS Code 连上 WSL 之后空荡荡的 Linux 环境需要补一点基础工具链。执行sudo apt update sudo apt install -y build-essential gdb python3 python3-venv python3-pipbuild-essential会装好 gcc、g、make 等编译工具这是 C/C 开发的前提。装上之后如果 VS Code 里打开.c或.cpp文件时#include依然有红色波浪线通常是 IntelliSense 找不到编译器路径。解决方法是创建.vscode/c_cpp_properties.json把compilerPath指向{ configurations: [ { name: Linux, compilerPath: /usr/bin/gcc, intelliSenseMode: linux-gcc-x64, includePath: [${workspaceFolder}/**] } ], version: 4 }这一招对 WSL 环境下的 C 项目基本是通用解法。Python 环境则建议给每个项目建一个 venv避免全局包越装越乱。4. Codex CLI 的安装、登录和模型接入4.1 在 WSL 里安装 Codex强烈建议在 WSL 环境里安装 Codex而不是直接在 Windows 上装。Windows 下的 npm 全局安装经常遇到权限、路径、进程占用问题安装到一半失败是常事在 WSL 里路径机制和 Linux 服务器一致安装干净利落。先在 WSL 终端里确认 Node 环境node -v npm -v如果没有 Node先装一个sudo apt install -y nodejs npm建议用 nvm 管理 Node 版本避免系统包版本太旧。接着全局安装 Codex CLInpm install -g openai/codex安装完成后验证版本codex --version出现版本号就说明装好了。如果 npm 全局目录不在 PATH 中检查一下 npm 的 prefix 配置把$(npm prefix -g)/bin加进 PATH。4.2 Codex 登录OAuth 或 API KeyCodex 登录最常见的方式是交互式授权codex login终端会输出一个授权链接浏览器打开、登录账号、确认授权后本地 Codex 就能正常调起服务了。WSL 里偶尔会出现打开浏览器不顺畅的情况可以直接复制终端里的 URL手动到 Windows 侧浏览器打开。如果你更习惯用 API Key 方式执行codex login --help看看支持的参数。多数版本都支持 API Key 登录或者你也可以直接在配置文件里指定环境变量名称让 Codex 从环境变量里读取密钥这个下面一节会详细讲。注意不要把 Key 直接写进项目代码或公网仓库Key 是用来验证身份的泄露了等于把控制权交出去了。4.3 把 Codex 接到 DeepSeek、Kimi 等第三方模型Codex CLI 默认连接 OpenAI 官方服务但它的配置文件支持自定义模型提供方Model Provider。如果你用的是 DeepSeek、KimiMoonshot这类兼容 OpenAI 接口的服务完全可以改配置。Codex 的配置文件路径在~/.codex/config.toml。DeepSeek 的配置示例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你的Key之后再运行codex它就会走 DeepSeek 的模型。Kimi 也是一样的套路base_url 换成https://api.moonshot.cn/v1model 换成moonshot-v1-8k或服务商支持的其他型号即可。关于wire_api字段简单解释一下OpenAI 官方接口现在用的是responses协议很多兼容服务商用的是经典的chatChat Completions协议。Codex 需要知道目标服务的协议类型才能正确组织请求。判断不了的时候优先用chat绝大多数兼容服务都支持。不同版本 Codex 对配置字段的解析可能略有差异以你本机的codex --help和官方文档为准。除了 CLIVS Code 生态里也有各种 AI 插件可以接入兼容 API但核心逻辑都一样设置 base_url、填 Key、选模型。CLI 的好处是轻量、可脚本化而且能直接在终端里结合自动化流程。5. 高概率踩坑Codex 在 WSL 里的报错与排查5.1 “cc switch local proxy failed while handling codex endpoint” 怎么处理这个报错我在排查环境时见过几次。先看错误形态cc switch local proxy failed while handling codex endpoint /responses这个报错的典型场景是你用了某些 Codex 配置切换工具比如cc switch把 Codex 的 API 端点从官方地址切到本地某个代理端口用于本地调试、流量转发或者接入自建网关。切换之后Codex CLI 在请求/responses端点时发现本地代理服务不可用于是报错。排查步骤按顺序来打开~/.codex/config.toml确认当前base_url指向哪里。如果指向127.0.0.1或localhost的某个端口说明请求正在走本地代理链路。检查该端口是否真的在监听ss -tlnp | grep 端口号没有任何输出说明代理服务没起来。先启动你配置的那个本地服务再重试 Codex。如果不想走本地代理直接把base_url改回官方 API 地址或者删掉自定义 provider重新执行codex。检查环境变量里是否有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY指向不存在的地址。这种情况非常隐蔽环境变量会让所有 HTTP 请求都走一个死代理。临时验证可以执行unset HTTP_PROXY HTTPS_PROXY ALL_PROXY再跑 Codex。如果恢复正常说明就是环境变量的问题。想看更详细的请求日志用调试模式跑一次RUST_LOGdebug codex exec test可以看到请求发往哪个地址、在哪里失败。日志会明明白白告诉你问题出在连接还是协议上。5.2 “codex ran out of room in the model’s context” 上下文爆了的处理另一个高频报错是error running remote compact task: codex ran out of room in the models context这个错误的意思是当前会话的上下文窗口已经满了Codex 尝试自动压缩上下文以继续对话但压缩过程本身也因为上下文空间不足而失败。处理思路有几个方向。最直接的方法就是新开一个会话。在codex交互界面里退出重进之前对话的上下文就清空了。这是最简单有效的操作。更重要的是调整使用习惯。不要一次性把整个项目文件内容都塞给 Codex不要执行cat 大文件之后把全部输出贴进 prompt。你描述清楚需求让 Codex 自己去读文件、搜代码这样每次对话占用的上下文会少很多。如果模型本身上下文窗口就小可以考虑在配置里换用上下文更大的模型。比如很多第三方兼容模型有 64K 甚至 128K 的上下文版本对应 Codex 能记住的信息量也会增加。另外拆分任务也是一种解法把一个大型重构拆成多个小步骤每步单独开会话比让 Codex 一口气啃完整个项目要稳得多。5.3 其他常见报错速查表我在折腾这套环境的过程中还遇到过不少零碎问题整理成一个速查表方便你直接对号入座。现象可能原因处理思路Windows 下npm install -g openai/codex安装中断权限不足、路径冲突、杀毒拦截换到 WSL 里安装管理员终端重试codex login后浏览器不自动打开WSL 缺少默认浏览器关联复制终端里的授权链接手动用 Windows 浏览器打开VS Code 提示 WSL server 启动失败WSL 版本过旧或内核异常执行wsl --update再wsl --shutdown后重连打开 C 文件#include红波浪线没装编译器或 includePath 缺失apt install build-essential配置c_cpp_properties.json终端中文乱码locale 或字体问题设置zh_CN.UTF-8VS Code 字体换成 Sarasa 系列Codex 执行命令提示权限不够某些文件由 Windows 侧创建权限混杂用chmod修复文件权限或把项目放到 WSL 内部目录codex提示找不到命令npm 全局目录不在 PATH把$(npm prefix -g)/bin加入 PATH5.4 关于 WSL 里那些“顺便能救”的本地问题还有一个很容易忽略的点VS Code WSL 这套环境本身就能顺手解决很多在其他教程里看到的热门问题。比如你本地跑 Qt 5.9 项目配置不顺利、Spring Boot 项目启动报环境错误、甚至用 binwalk 做固件分析时缺依赖本质上都是“Linux 环境不完整”导致的。在 WSL 里安装对应开发库之后VS Code 的智能提示和 Codex 的代码分析能够一起工作解决这些问题的速度会快很多。所以不用把眼光局限在“AI 编码”上WSL 这一层先把环境基础打牢后面都是水到渠成的事。6. 一条个人认为最顺手的日常工作流6.1 从拉代码到让 Codex 干活现在说下我每天都在用的一条链路整体跑通之后基本是肌肉记忆wsl进入 Ubuntu。cd到项目目录。执行code .VS Code 自动连接 WSL 并打开项目。打开集成终端确保终端路径也在项目目录里。执行codex exec 分析一下当前项目的结构和启动方式先让 Codex 理解项目。接下来就是循环给它具体任务让它改代码、跑测试遇到报错直接把报错喂回去继续问。涉及批量替换或者大范围重构时用codex exec --full-auto让它自动搜索替换但执行前一定要先看git diff。这里有一个非常重要的习惯让 Codex 动手改代码之前先把当前状态提交一次 git。哪怕只是git add -A git commit -m before codex这样的临时提交也能在代码被改乱时随时回滚。AI 编码代理不是每次都百分之百正确的它很容易在某个细节上“自信地犯错”没有 git 兜底你会非常被动。6.2 进阶在 WSL 里让 Codex 配合复杂环境如果你要在 WSL 里跑 PyTorch 或者搞 CUDA 相关开发有几点可以说一下。WSL2 是支持 GPU 直通的Windows 侧安装好 NVIDIA 驱动之后WSL 内不用再装显卡驱动但需要在 WSL 里安装 CUDA toolkit 和 cuDNN。执行nvidia-smi能看到显卡信息就说明 GPU 环境基本就绪。Codex 在这种复杂环境里的价值在于它不会凭空猜而是会基于你当前环境里的报错信息去推理。你可以让它写一个 PyTorch 训练脚本它会考虑到 WSL 下的路径风格、CUDA 版本、Python 虚拟环境等因素。使用虚拟环境的习惯一定要养成python3 -m venv venv source venv/bin/activate pip install torch --index-url https://download.pytorch.org/whl/cu118装完之后在 Python 里执行import torch print(torch.cuda.is_available())如果输出True说明 GPU 环境已经通了。这种验证习惯同样可以迁移到 Codex 的用法上每次让它改完环境相关的东西记得先跑一条最小验证命令别急着跑大任务。对于 C、Spring Boot 这类项目WSL 里同样能用 Codex 做编译问题排查。它比搜索引擎强的地方在于能结合你本机的具体文件和报错一步步缩小问题范围。比如 CMake 配置出问题把 CMakeLists.txt 和相关报错贴给它它通常能快速定位到是路径写错还是依赖缺失。最后再分享一个小技巧Codex 的会话是有上下文限制的长时间使用后它会变得“健忘”。我的习惯是每完成一个小任务就让它输出一份简短的变更总结然后开新会话继续下一个任务。这样既保留了关键信息又能一直保持会话上下文的清澈报错率低很多。我实际使用下来的体会是VS Code、WSL、Codex 这三个工具单独拎出来都不稀奇但组合起来的体验提升是质变。尤其是对于主力机型是 Windows、又必须面向 Linux 环境开发的人来说这套组合能消掉绝大部分“环境不对”导致的烦躁。踩过几次坑之后最重要的一句话就是先把 WSL 和 VS Code 的底层环境弄稳再让 Codex 进场干活顺序别反了。环境不稳的时候AI 的聪明才智都浪费在和环境搏斗上了稳了之后才能真正体会到那种“想个思路就能看它帮你把活干了”的爽感。
