最近一个多月我把日常编码里的 AI 辅助从浏览器网页切到了 VS Code 终端里的 Codex CLI并且整套环境落在 WSL 里跑。这个组合理论上很简单实际装的时候却能把人绕晕——光是 wsl --install 卡住、版本太旧、登录授权失败、接第三方模型时端点报错我就见过不下十种问法。写这篇就是想把 VS Code Codex 在 WSL 中使用的正确姿势一次讲清楚适合刚接触 WSL 想配 Codex 的人也适合已经在用但老被各种诡异报错打断的人。1. 为什么我要把 Codex 放在 WSL 里跑而不是直接装 Windows 版1.1 Windows 原生环境的四个别扭先说我踩过的坑。Codex CLI 本质上是一个 Node.js 写的命令行工具在 Windows 上用原生 Node 跑理论可行但日常用起来总有四件事让人难受第一是 Node 版本管理。Windows 上装 nvm-windows 不是不行但切换版本要开管理员终端有时候还要手动改 PATH和 Linux 下的 nvm 体验差了一个量级。Codex 对 Node 版本有要求版本不对会直接拒绝启动这时候你就会被迫去折腾版本切换。第二是路径和换行符。Codex 会读取项目里的文件喂给模型Windows 的路径分隔符、CRLF 换行、文件权限位在多文件项目里偶尔会引发莫名其妙的行为。尤其是从仓库里拉下来的 shell 脚本经常因为换行符问题直接跑不了。第三是环境不一致。你本地写代码、跑命令、让 Codex 改文件最后代码要部署到 Linux 服务器上。本地是 Windows远端是 Linux两边行为对不上很容易出现本地好好的一上线就崩的尴尬。第四是 VS Code 本身对 WSL 的支持已经非常成熟与其在 Windows 侧装一大堆插件去兼容 Linux 工具链不如直接把整套开发环境搬进 Linux 用户空间让 VS Code 远程连进去用。1.2 WSL2 的边界感是虚拟机但不是传统虚拟机WSL2 的底层是轻量虚拟机但它和 VMware、VirtualBox 那种完整虚拟机完全不同。你不用管理虚拟磁盘不用手动配网络不用装桌面环境打开终端就是干净的 Ubuntu 用户空间默认还和你 Windows 的文件系统互通。但这里有个关键边界必须清楚WSL2 里访问 Windows 侧文件的性能是灾难级的。你如果从 WSL 里读取 /mnt/c/Users/你的名字/Projects 下的文件IO 会经过 9P 协议转换速度比读 Linux 原生文件系统慢很多尤其在 node_modules 这种动辄几万个小文件的目录里慢到怀疑人生。所以正确的做法从第一天就要养成项目放在 WSL 自己的文件系统里比如 ~/projects 下Windows 侧只用 VS Code 的界面去连。这个习惯直接影响你后续用 Codex 改代码时的整体顺畅程度。Codex 要在工作区里跑 git 命令、读文件、创建文件这些操作都发生在 WSL 内部天然是 Linux 行为和服务器端保持一致。2. 装 WSL 和 VS Code 时最容易卡壳的三个地方2.1 wsl --install 卡住和版本太旧的处置很多人的第一个坑出现在安装阶段。Windows 10 或 Windows 11 上执行wsl --install如果卡在下载进度条不动或者过一会儿报错退出大概率是内核更新包没有拉下来。另一个高频错误是运行任何 wsl 命令时提示 your version of windows subsystem for linux is too old. run the command wsl --update字面意思是 WSL 组件版本太旧需要更新。我的处理顺序是这样的# 第一步先更新 WSL 自身的内核组件 wsl --update # 如果上面卡住用强制走网络安装的方式 wsl --update --web-install # 更新完之后装发行版 wsl --install -d Ubuntu-22.04如果你第一次用wsl --install已经把默认发行版装好了只是后续更新内核卡住可以直接去微软官方文档页面找到 WSL 的安装包手动下载更新双击装完重启终端就行。这个方法在面对公司网络、校园网等网络波动大的场景时特别管用比反复重试命令行可靠得多。还有一个小提醒安装完发行版之后第一次启动会让你设置 Linux 用户名和密码。这个用户名会写进 WSL 的默认用户配置里后面 VS Code 连接时用的就是它。不要顺手设一个和 Windows 账户完全一样的密码尽量独立减少暴露面。2.2 发行版装好后的初始化必做项进入 Ubuntu 终端之后别急着装 Codex先把基础环境打牢。我每次在新 WSL 里都会按顺序执行这几条sudo apt update sudo apt upgrade -y sudo apt install -y curl git build-essential unzipbuild-essential 里有 gcc、make 等编译工具很多 npm 包在安装时要本地编译原生模块没有它就会报 node-gyp 相关的错误。git 和 curl 更是不用说Codex 本身也要调用 git 来理解你的代码变更。初始化完最好顺手看一眼 DNS 配置。WSL2 的网络走 NAT正常情况下外网访问是通的但如果你之前折腾过自定义 DNS、或者系统里有一些网络优化软件可能会把 /etc/resolv.conf 改坏表现就是 apt update 超时、curl 任何网址都失败。遇到这种情况最简单粗暴的办法是重启 WSL 网络栈# 在 Windows 的 PowerShell 里执行 wsl --shutdown然后重新打开 WSL 终端WSL 会自动重新生成 /etc/resolv.conf。如果重启之后还是不通再手动检查这个文件里的 nameserver 是不是指向了一个可达的地址。2.3 VS Code 的 Remote 扩展和字体观感VS Code 侧只需要装一个扩展WSL扩展名叫 WSL官方发布者。装完之后在 WSL 终端里进入项目目录执行code .VS Code 会自动以远程模式打开并在第一次连接时往 WSL 里安装一个 VS Code Server。这个过程需要下载所以如果网络不好会卡在那个 Installing VS Code Server 的进度条上。等一次装完后面再连接就非常快。字体是很多人忽略的体验项。热词里有个wsl ubuntu写代码最推荐的字体接近macos的体验说明大家都想要 macOS 那种清晰的等宽字体观感。我实测下来比较省心的组合是字体特点适用场景Cascadia Code微软官方出品自带连字Windows Terminal 默认想要开箱即用JetBrains Mono字符间距舒适长时间看眼不累追求接近 macOS 的细腻感Ubuntu Mono和 Ubuntu 终端风格统一想保持系统一致性Noto Sans Mono字重均匀中文支持好经常混排中文注释在 Windows Terminal 的设置里把字体改成 JetBrains Mono再把 VS Code 的terminal.integrated.fontFamily和editor.fontFamily也同步设置整套观感立刻提升一个档次几乎感觉不到和 macOS 终端的差别。3. Codex CLI 的安装、登录和自定义模型接入3.1 用 nvm 管理 Node再全局安装 CodexWSL 里的 Node 安装方式我强烈建议用 nvm而不是直接 apt install nodejs。apt 源里的 Node 版本通常偏旧而 Codex CLI 对 Node 版本有明确要求版本不够会直接报错。nvm 的安装非常简单# 拉 nvm 安装脚本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并使用最新 LTS 版本 nvm install --lts nvm use --lts装完 Node 之后全局安装 Codexnpm install -g openai/codex装完一定要验证一下codex --version如果提示 command not found多半是 npm 的全局 bin 目录不在 PATH 里。nvm 模式下的路径一般是 ~/.nvm/versions/node/当前版本/bin把这一行加进 ~/.bashrc 的 export PATH 里就行。3.2 登录授权浏览器授权那一步的坑Codex 的登录用的是 OpenAI 账户授权。执行codex login之后终端会显示一个授权链接按提示复制到浏览器打开登录并同意授权。这里有个 WSL 特有的小问题WSL 里默认不一定能直接唤起 Windows 浏览器所以别傻等它弹浏览器直接手动复制链接到 Windows 侧打开就行。授权完成之后凭证会写到 WSL 里的 ~/.codex/auth.json 文件。注意这个文件是纯文本存储令牌不要把它提交到 git 仓库也不要随意分享给别人。登录失败最常见的两个原因一是授权回调端口被占用Codex 在本地等回调时会监听一个随机端口如果已经被别的程序占了浏览器授权完就没法回到终端这时候重新执行 login 一般就好。二是选择的账户权限不对需要在 OpenAI 侧开通对应的模型访问权限。我自己的习惯是登录成功之后立刻备份一份 auth.json 到安全位置因为后面接第三方模型时还要动配置文件万一改错了可以把原来的恢复回来。3.3 通过 config.toml 接入 DeepSeek 这类兼容服务现在很多人不满足于默认官方接口想接 DeepSeek 这类价格更友好的 OpenAI 兼容服务。Codex CLI 本身支持自定义 model provider配置写在 ~/.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然后把自己的密钥通过环境变量提供而不是写进配置文件echo export DEEPSEEK_API_KEY你的密钥 ~/.bashrc source ~/.bashrc这里有几个点要强调。base_url必须以服务提供的 OpenAI 兼容路径为准DeepSeek 的官方文档里给的 v1 路径要完整复制漏掉 /v1 会导致请求 404。wire_api是 Codex 和提供方通信的协议格式官方接口走的是新版 responses 协议很多第三方服务还没完全兼容所以通常要设成chat让 Codex 用传统的 chat completions 协议去请求。如果你用官方模型这一项不需要改。配置完可以跑一条最简单的命令验证codex exec 用一句话解释 WSL2 和传统虚拟机的区别如果能正常返回结果说明自定义接入成功。如果报错优先检查密钥是否真的导入了环境变量echo $DEEPSEEK_API_KEY 看一下以及 base_url 是不是拼对了。4. 端点报错和上下文塞满两座绕不开的山4.1 访问 /responses 端点的连接失败问题不少人在接第三方模型或者网络环境复杂时会遇到 Codex 发起请求就报错的状况报错里经常能看到 /responses 这个路径。Codex 新版默认的请求入口就是 /responses 端点所以很多连接问题都集中在这个路径上。我给的排查顺序是固定的第一步先验证网络基础连通性。用 curl 直接探测你配置的 base_url 是否可达curl -I https://api.deepseek.com/v1如果这一步就超时问题出在网络层和 Codex 本身无关。第二步检查 DNS。在 WSL 里执行cat /etc/resolv.conf确认 nameserver 是否合理。WSL2 的 NAT 网络下外网 DNS 解析一般没问题但如果之前改过可能导致解析不了 API 域名。第三步检查本地环境变量。很多人的 shell 配置里残留着指向 127.0.0.1 某个端口的环境变量这个端口上如果并没有服务在监听Codex 的请求就会先撞到空端口然后失败。我在排查时习惯先执行env | grep -i http看看有没有这类残留有的话先临时清掉再试。第四步如果上述都正常但还是报错考虑重装网络栈。执行wsl --shutdown之后重新打开终端实测能解决相当一部分莫名奇妙连不上的问题。这个排查链路我基本固定下来了每次都有效。不要一上来就怀疑 Codex 坏了绝大多数时候是环境问题。4.2 ran out of room in the models context 的真正含义另一个高频报错是 codex ran out of room in the models context翻译过来就是模型的上下文窗口被塞满了。Codex 在会话里会不断累积你给它看的文件内容、命令输出、你的反馈当这些内容超过模型上下文窗口的容纳上限时它就没法继续工作了。这个报错本身不可怕可怕的是很多人不理解它是设计使然以为是 bug 去重装。Codex 的每个会话有自己的记忆这个记忆有物理上限不是软件坏了。我的处理办法有三条第一新开会话。交互界面里输入/new或者退出重进立刻恢复清爽。代价是之前的对话上下文会丢失所以重要的结论要提前记到文件里。第二主动控制喂给模型的内容量。不要一次性让它读几百个文件把范围收窄到当前要改的那几个文件上。Codex 的/readonly和/read指令可以精确控制读取范围善用它们比反复靠上下文压缩高效得多。第三把关键决策沉淀到项目的 AGENTS.md 里。Codex 在启动会话时默认会读取 AGENTS.md 作为项目级提示词你上次会话里确认过的技术选型、代码约定、注意事项写进这个文件就等于把长期记忆交给了实际载体而不是依赖会话上下文。我在一个大型重构项目里连续工作了接近两周靠的就是每次会话结束把结论写进 AGENTS.md新会话开局就能快速进入状态。5. 让这套组合每天更顺手的小配置5.1 在 VS Code 里给 Codex 留一条快速通道Codex CLI 虽然跑在终端里但日常使用完全可以不离开 VS Code。我习惯把 WSL 终端面板固定在编辑器下方项目目录直接在终端里打开然后给codex起个短别名echo alias cxcodex exec ~/.bashrc source ~/.bashrc这样想让它干个杂活直接cx 给这个函数补上单元测试就行。如果喜欢用 VS Code 自带的任务系统也可以建一个 tasks.json 任务绑定一个快捷键来执行 codex把 AI 调用做得像一个编辑器原生功能。5.2 项目位置决定后期体验前面提过 /mnt/c 的性能问题这里再说具体一点。同样的项目放在 /mnt/c/Users/xxx/Projects 和放在 ~/projects用 Codex 分析代码时的体感差距是很明显的。在 Windows 侧访问 WSL 文件有 \wsl$ 通道但反过来在 WSL 里频繁读写 Windows 挂载盘的文件IO 开销非常大。所以项目一定要建在 WSL 内部。另外给 WSL 里的 git 做一个换行符设置避免仓库里的文件在 Linux 侧被改得面目全非git config --global core.autocrlf input这个设置让 git 在提交时把 CRLF 转换成 LF检出时保持 LF在 WSL 里用起来最省心。5.3 配置目录的备份与迁移整套环境里真正值钱的文件不多但每一个都值得备份~/.codex 目录里面是 config.toml 和 auth.json、~/.bashrc、~/.gitconfig。我每周会把它们打包一次。换机器的时候装好 WSL、Node、Codex把这三个文件恢复回去整个环境五分钟就能回到原来的状态中间踩过的那些配置坑完全不用重复踩。最后再分享一个我自己的习惯每周五下班前我会把当周 Codex 会话里所有确认过的关键决策整理进对应项目的 AGENTS.md。Codex 的上下文是会话级的真正长久的记忆只能靠这套手工沉淀。这个动作坚持下来之后我再也没有出现过上周 AI 改到一半这周打开新会话完全失忆的窘境连续几周的大型改动也不会迷路。如果你打算把 Codex 作为日常主力工具这个习惯值得从第一天就开始养。