Windows 与 WSL

WSL 2 让 Windows 用户在完整 Linux 环境中运行 Codex、Claude Code、OpenCode、Aider 等工具。项目依赖 Linux 工具链或需要沙箱时，建议使用 WSL 2。

安装 WSL 2

以管理员身份打开 PowerShell：

wsl --install

重启电脑，首次打开 Ubuntu 时创建 Linux 用户名和密码。

检查版本：

wsl -l -v

目标发行版的 VERSION 应为 2。如果不是：

wsl --set-version Ubuntu 2

项目放在哪里

建议把项目放在 WSL 的 Linux 文件系统：

mkdir -p ~/code
cd ~/code
git clone https://github.com/owner/repo.git

不要长期在 /mnt/c/... 中运行大型 Node.js 或 Git 项目，文件 I/O、权限和符号链接更容易出问题。

Windows 文件管理器可通过以下地址访问：

\\wsl$\Ubuntu\home\你的用户名

配合 VS Code

1. 安装 VS Code 的 WSL 扩展。
2. 在 WSL 终端进入项目。
3. 运行：

code .

确认 VS Code 左下角显示 WSL: Ubuntu，集成终端路径应为 /home/...。

在 WSL 中安装 CLI

所有安装和配置命令都要在 WSL 终端执行。例如：

npm install -g @openai/codex@latest
npm install -g @google/gemini-cli@latest
curl -fsSL https://claude.ai/install.sh | bash

配置目录不是同一份

Windows 原生与 WSL 有各自的用户目录：

工具	Windows 原生	WSL
Codex	%USERPROFILE%\.codex	~/.codex
Claude Code	%USERPROFILE%\.claude	~/.claude
Gemini CLI	%USERPROFILE%\.gemini	~/.gemini
OpenCode	%USERPROFILE%\.config\opencode	~/.config/opencode

在 Windows 中配置过，不代表 WSL 内会自动生效。请在实际运行 CLI 的环境中配置。

环境变量持久化

在 WSL 的 ~/.bashrc 或 ~/.zshrc 中添加变量，例如：

export COFFEECAT_API_KEY="sk-你的令牌"

然后加载：

source ~/.bashrc

Shell 配置中的密钥

任何从该 Shell 启动的进程都可能读取环境变量。更高安全要求下，请使用系统密钥环、凭据助手或仅在当前会话设置。

常见问题

VS Code 找不到 CLI

确认 VS Code 是从 WSL 中通过 code . 打开的，并在集成终端运行 which codex 等命令。

WSL 网络无法访问

先在 WSL 中运行：

curl -I https://coffeecatbox.cc

检查 Windows 代理、防火墙、系统时间和 DNS。不要通过关闭 HTTPS 校验解决。

权限或换行问题

仓库放在 ~/code，并在 WSL 内使用 Git。脚本出现 ^M 时检查 Git 行尾配置和文件的 CRLF/LF。