Windows 在 WSL2 里安装与运行 Codex:完整步骤、跨盘卡顿优化与 VS Code 联动

在 Windows 上遇到原生沙箱权限受限、Bash 脚本斜杠报错或软链接失灵时,官方推荐切到 WSL2 环境运行 Codex。本文按官方文档讲清 WSL2 安装要求(不支持 WSL1)、原生脚本安装、避开 /mnt/c 慢速目录以及联动 VS Code 的标准步骤。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Plus 账号

结论先说

  1. 必须用 WSL2,不能用旧版 WSL1:官方明确说明自 Codex 0.115 版本将 Linux 沙箱底层迁移到 bubblewrap 起,已彻底停止对 WSL1 的支持。
  2. 头号性能铁律:代码仓库一定要放在 Linux 原生目录(如 ~/code/)下,千万别直接 cd 进 /mnt/c/Users/... 跑大项目,否则跨文件系统 I/O 会让搜索和装依赖慢上好几倍。
  3. WSL 里直接走 Linux 官方一行脚本安装,不要去调宿主机 Windows 盘符里装的那份 .exe。
  4. 编辑器从 WSL 内部敲 code . 拉起:配合官方 WSL 扩展,让 VS Code 窗口、集成终端和 Codex 全部处在同一个 Linux 上下文里。

Windows 原生与 WSL2 运行对比

图:本站根据 OpenAI Codex 官方文档 WSL 整理的示意图

本文根据 OpenAI Codex 官方文档《WSL》整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。

适用于谁

  • 搜「codex wsl 安装」「windows 用 wsl2 跑 codex」「codex 在 wsl 里很慢」的 Windows 开发者;
  • 在原生 Windows 环境碰到沙箱初始化报错(排查见 /guides/codex-windows-sandbox-setup-failed),或者项目本身重度依赖 Linux 编译工具链、Shell 脚本与软链接的人;
  • 在 VS Code 连接 WSL 后提示找不到 codex 命令,正在核对路径配置的同学。

如果你只想安装图形界面的 Windows 桌面客户端,可参考 /guides/codex-windows-app-download-install;本文专门讲把开发环境和 Codex CLI 完整放进 WSL2 Linux 子系统的官方方案。

一、三步在 WSL2 内装好并启动 Codex

第一步:确认开启 WSL2 发行版

以管理员身份打开 Windows PowerShell 或 Windows Terminal,安装默认 Linux 发行版(通常为 Ubuntu)并检查内核代数:

powershell
# 首次安装 WSL2 与默认 Ubuntu 发行版
wsl --install

# 若早已装过,确认 VERSION 列显示为 2(若过旧可顺手更新内核)
wsl --update
wsl -l -v

第二步:进入 Linux 子系统运行官方安装脚本

输入 wsl 进入 Linux Shell 后,直接使用官方安装命令(通用升级方法见 /guides/codex-cli-install-update):

bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

首次运行 codex 时按终端提示完成账号登录授权即可。

第三步:把项目克隆进 Linux 主目录(最关键的提速点)

很多刚从 Windows 切进 WSL 的开发者,习惯直接 cd /mnt/c/Project 接着改原来的文件夹,结果发现 git status、rg 全局搜索和 pnpm install 卡得要命。这是因为 /mnt/c 需要经过跨系统文件桥接,不仅大量小文件读写极慢,还经常闹出文件可执行权限与软链接报错。

官方推荐的标准姿势是在 Linux 自己的主目录下建工作区:

bash
mkdir -p ~/code && cd ~/code
git clone https://github.com/你的组织/你的仓库.git
cd 你的仓库

平时如果你需要在 Windows 文件资源管理器里直接查看或拖入文件,只需在资源管理器地址栏输入 \\wsl$\Ubuntu\home\<你的Linux用户名>\code 就能直接打开。

在 WSL2 安装并提速 Codex 四步

图:本站根据 OpenAI Codex 官方文档 WSL 整理的示意图

二、怎么和 VS Code 无缝配合

  1. 在宿主机 Windows 的 VS Code 里装好微软官方的 WSL 扩展(ms-vscode-remote.remote-wsl);
  2. 回到刚才的 WSL 终端,进入 ~/code/你的仓库 后敲 code .;
  3. 确认新弹出的 VS Code 左下角绿色状态栏显示 WSL: Ubuntu——这代表集成终端和扩展(插件加载排错见 /guides/codex-vscode-extension-install-not-loading)现在全部原生跑在 Linux 环境内。

如果在集成终端里报找不到 codex,在 WSL Shell 里敲 which codex 检查 ~/.local/bin(或 npm 全局 bin 目录)是否已写入 ~/.bashrc 或 ~/.zshrc 的 PATH 环境变量。在 Windows 工作站通过 ChatGPT 订阅账号日常高频使用 Codex 开发时,官方套餐说明也可参考 /chongzhi/chatgpt-plus。

常见问题

Q:代码已经挪到了 ~/code/ 下,跑超大单体仓库构建时还是觉得内存吃紧怎么办?

WSL2 默认分配的内存上限取决于宿主机物理内存比例。先在 PowerShell 运行 wsl --update 与 wsl --shutdown 重启清爽实例;若编译重型项目仍报内存不足,可在 Windows 用户目录下的 .wslconfig 文件中适度调高分配给 WSL2 虚拟机的 memory 和 processors 配额。

Q:在 WSL2 里登录一次账号后,Windows 原生终端里还要重新登吗?

WSL2 内部拥有独立的 Linux 用户主目录(~/.codex/),与宿主机 Windows 的 %USERPROFILE%\.codex\ 是两套互不干扰的文件系统,因此两边如果都要用,各自登录和维护独立配置最干净,也避免了跨系统换行符(CRLF 与 LF)把配置文件改乱。

Q:在 WSL2 终端敲 codex 登录时,弹不出宿主机 Windows 浏览器授权页怎么办?

正常情况下 WSL2 支持自动调用宿主机默认浏览器打开回调地址;若你的精简发行版未装浏览器桥接组件导致未自动弹窗,直接按住 Ctrl 点击终端里打印出的完整认证链接(或复制贴进 Windows 浏览器)完成登录,本地回环端口同样能正常接住授权回调。

Q:克隆代码进 ~/code/ 后,怎么复用我平时在 Windows 上已经配好的 Git 凭据?

可以在 WSL2 内的 ~/.gitconfig 将 credential.helper 指向宿主机 Git 自带的 Windows 凭据管理器(Git Credential Manager),或者为 WSL2 单独生成一对 SSH 公钥登记到代码托管平台,这样 Codex 在子系统内拉取分支时就不会因为卡在密码输入提示上而超时。

相关教程

参考资料

  • OpenAI Codex 官方文档:WSL — https://learn.chatgpt.com/docs/windows/wsl
  • OpenAI Codex 开发者中心 — https://developers.openai.com/codex

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    多 Agent 协同开发怎么落地:「一个写、一个审」双代理工作流搭建指南

    多 Agent 协同开发里投入产出比最高的模式就是「一个写、一个审」。本文依据 Anthropic 与 OpenAI 官方编码最佳实践,讲清为什么同会话自审容易漏问题,以及用只读子代理、跨模型交叉审查(Claude Code + Codex)和自动化闭环落地的具体方法。

    ClaudeCodex0
  2. 02

    codebase-memory 类 MCP 是什么、怎么用:基于语法树图谱的本地代码索引原理与配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一类本地代码图谱 MCP 服务器:用 Tree-sitter 把仓库解析成函数与调用关系的 SQLite 图库,帮编码助手查调用链并省下读整份文件的额度。

    ClaudeCodex0
  3. 03

    Chrome DevTools MCP 怎么用、怎么保留登录态:安装配置、独立目录与远程调试端口连接

    Chrome DevTools MCP 本身免费且无需注册账号,大家搜「登录」通常是为了让 AI 调试需要登录的网页后台。本文按官方仓库文档讲清安装命令,以及用 --userDataDir 持久化独立配置目录、用 --browserUrl 挂载已登录浏览器的两种标准做法。

    ClaudeCodex0
  4. 04

    Codex 接入 Amazon Bedrock 与 Google Cloud Vertex AI 教程:企业云托管配置

    企业合规要求模型流量统一走自家 AWS 或 GCP 云账单时,不需要硬拼第三方代理。本文根据 OpenAI Codex 官方文档,讲清原生接入 Amazon Bedrock(四种 AWS 凭证方式)与 Google Cloud Vertex AI(ADC 认证与区域驻留)的完整步骤。

    Codex0
  5. 05

    Codex 自动审查 GitLab Merge Request 怎么配:公有云与自托管实例接入指南

    代码托管在 GitLab 的团队同样可以用上 OpenAI 官方的云端代码审查。本文根据官方文档讲清 GitLab.com 与企业自托管实例的服务账号配置、Developer 权限、Webhook 开启与 AGENTS.md 规则约束。

    ChatGPTCodex0
  6. 06

    Codex 接入 Linear 怎么用:指派 Issue、评论 @Codex 自动改码与 Triage 分流教程

    用 Linear 管研发任务单的团队,可以直接把 Issue 指派给 Codex 或在评论区 @Codex 自动拉起云端环境改代码。本文按 OpenAI 官方文档讲清云端环境前置准备、连接器安装、多仓库指定技巧以及 Triage 规则自动派单配置。

    ChatGPTCodex0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~