Codex / Claude Code 的 WSL 最佳安装方案

come11234

5730人浏览 · 2026-01-07 18:38:53

come11234 · 2026-01-07 18:38:53 发布

好，这一条我直接给你一份 “可落地、工程级、少踩坑” 的完整方案。
不是泛教程，而是 Codex + Claude Code 双栈、MCP 稳定运行 的 Windows + WSL 最佳实践。

你可以 按步骤照做。

一、总体推荐架构（先看全局）

结论先行：这是目前最稳的形态

Windows（只做 UI）
 ├─ VS Code / Cursor
 ├─ Codex UI
 ├─ Claude Code UI
 │
WSL2 (Ubuntu 22.04 / 24.04)
 ├─ node / npx
 ├─ python / uv
 ├─ git
 ├─ docker
 ├─ MCP servers
 ├─ Codex CLI / Claude Code CLI
 └─ agent / tool 执行

原则只有一句：

👉 凡是“要执行的”，都放 WSL
👉 Windows 只负责“展示和编辑”

二、Codex / Claude Code 的 WSL 最佳安装方案（一步步）

① 安装 WSL（如果已装可跳）

wsl --install -d Ubuntu

② WSL 内基础工具（非常关键）

Node.js（推荐 nvm）

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

nvm install --lts
nvm use --lts

确认：

node -v
npm -v
npx -v

Python（推荐 uv）

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

uv python install 3.11

Git

sudo apt install git -y

③ 安装 Codex / Claude Code（WSL 内）

Codex CLI（示例）

npm install -g @openai/codex

验证：

codex --version

Claude Code（官方 CLI）

npm install -g @anthropic-ai/claude-code

验证：

claude --version

⚠️ 不要在 Windows 装 CLI
Windows 只装 UI / 插件

④ VS Code / Cursor 连接 WSL（关键）

VS Code

安装插件：Remote - WSL
用 WSL 打开项目：

code .

📌 之后：

编辑器在 Windows
执行环境在 WSL

三、Windows → WSL MCP 迁移清单（重点）

你现在 Windows 下大概率已经有 MCP 配置了，迁移规则如下。

① MCP 配置文件位置

Windows（旧）

%LOCALAPPDATA%\codex\mcp_servers.toml
%LOCALAPPDATA%\claude\mcp_servers.toml

WSL（新，推荐）

~/.config/codex/mcp_servers.toml
~/.config/claude/mcp_servers.toml

② 迁移时要做的 5 件事

✅ 1. command 路径全部改成 Linux

❌ Windows：

command = "C:\\nodejs\\npx.cmd"

✅ WSL：

command = "npx"

或：

command = "/home/xxx/.nvm/versions/node/v20.x.x/bin/npx"

✅ 2. 删除所有 Windows 专属 env

删掉：

LOCALAPPDATA
APPDATA
USERPROFILE

✅ 3. 路径全部用 Linux 形式

args = ["--config", "/home/user/project/config.yaml"]

✅ 4. 统一 stdio MCP（不要 TCP）

transport = "stdio"

✅ 5. 一次只迁一个 MCP（排错友好）

③ 迁移完成后做一次验证

codex mcp list
claude mcp list

四、哪些 MCP 必须放 WSL？哪些可以留 Windows？

✅ 必须放 WSL（强烈建议）

这些 在 Windows 下必炸 或极不稳定：

MCP 类型	原因
npx / node MCP	路径 & shell
python MCP	venv / shebang
playwright-mcp	Linux only
docker MCP	WSL 原生
git MCP	大小写 / 权限
bash / shell MCP	❌ Windows
mcp_router	多进程 / stdio

👉 一句话：凡是会 exec 的，全放 WSL

⚠️ 勉强可 Windows，但不推荐

MCP	风险
filesystem MCP	路径问题
git（只读）	大小写
http-only MCP	低

✅ 可以留在 Windows 的（少数）

MCP	场景
purely remote API MCP	只发 HTTP
database cloud MCP	无本地执行
read-only 搜索类 MCP

📌 但就算这些，统一放 WSL 也没坏处

五、推荐的 MCP 最小稳定组合（WSL）

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "/home/user/project"]

[mcp_servers.python]
command = "python"
args = ["-m", "your_mcp_server"]

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp"]