1. 为什么 Windows 11 上跑 Codex 一定要先进 WSL2Codex CLI 在 Windows 11 上并不是不能跑而是直接跑在 PowerShell 里会踩一堆坑路径分隔符是反斜杠、换行符是 CRLF、很多项目脚本默认按 Linux 写、Docker 又同时装在 Windows 和 WSL 里互相打架。我试过把 Node.js 装在 Windows、项目放在 C 盘、Git 用 Windows 版结果 Codex 读到的node和项目实际用的node不是同一个排查半天才发现是环境分裂。所以这篇的目标很明确在 Windows 11 里用 WSL2 建一套统一结构让 Codex CLI、Git、Node.js、Python、Docker CLI 全部跑在接近 Linux 服务器的环境里Windows 只负责桌面工具VS Code、Windows Terminal、Docker Desktop。这样 Codex 看到的路径、命令、依赖版本和线上服务器一致工程化落地才稳。适合谁看刚接触 Codex、想在 Windows 上做正式项目开发、被路径和权限问题折磨过的开发者。预计 1.5 到 2 小时能走完全流程难度中等跟着命令敲就行。核心结构长这样Windows 11 ├── VS Code ├── Windows Terminal └── Docker Desktop │ ▼ WSL2 Ubuntu ├── Git ├── Node.js / npm ├── Python / venv ├── Codex CLI └── Docker CLI项目源码优先放在 WSL 的 Linux 文件系统里也就是~/projects不要长期放在/mnt/c/...。Docker 官方也建议 WSL2 开发时把代码放在 Linux 发行版文件系统中文件访问和容器开发体验都更好。2. TaoToken 前置统一 Key 与 API 通道Codex 这类工具在工程化落地时最烦的是每个项目、每个终端、每个 IDE 各配一套 Key 和地址改一次要翻好几个文件。TaoToken 的作用就是把这些收敛成一个统一入口一个 Key、一个 API 地址Codex CLI、IDE 扩展、桌面应用都指向它。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。你需要先在控制台创建一个 API Key后面写进 Codex 的config.toml里。几个常用入口按场景分流创建和管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite模型对话验证https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码 / Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Key 只存在本地配置文件里不要提交到 Git 仓库。后面.gitignore会专门处理这件事。3. 可复制配置WSL2 环境 config.toml 骨架3.1 安装并检查 WSL2先确认系统版本和虚拟化。按Win R输入winver确认是 Windows 11任务管理器 → 性能 → CPU确认「虚拟化已启用」。如果没启用进 BIOS/UEFI 打开 Intel VT-x 或 AMD-V。以管理员身份打开 PowerShellwsl --install这条命令会启用 WSL 组件、虚拟机平台并默认安装 Ubuntu。装完重启 Windows。如果只显示帮助信息先看可用发行版wsl --list --online wsl --install -d Ubuntu下载卡在 0.0% 时换 web 下载wsl --install --web-download -d Ubuntu重启后更新并设默认版本wsl --update wsl --set-default-version 2 wsl --list --verbose预期看到Ubuntu的 VERSION 是 2。如果显示 1wsl --set-version Ubuntu 2 wsl --set-default Ubuntu3.2 初始化 Ubuntu 并装基础工具从开始菜单打开 Ubuntu首次启动创建 Linux 用户名和密码这个密码不是 Windows 登录密码输入时不显示字符是正常的。进入后检查whoami pwd uname -a预期目录类似/home/developer。然后更新并装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y \ git curl wget ca-certificates \ build-essential unzip zip jq tree ripgrep \ python3 python3-pip python3-venv检查git --version curl --version python3 --version jq --version rg --version3.3 项目目录与 Git 配置mkdir -p ~/projects cd ~/projects不建议长期把活跃项目放在/mnt/c/Users/...跨文件系统访问慢权限也容易出问题。Windows 想访问 WSL 文件在资源管理器地址栏输入\\wsl$进Ubuntu → home → developer → projects或者在 WSL 里执行explorer.exe .直接打开当前目录。配置 Gitgit config --global user.name 你的姓名 git config --global user.email 你的邮箱 git config --global init.defaultBranch main git config --global pull.ff only git config --global core.autocrlf input git config --global --list生成 SSH Keyssh-keygen -t ed25519 -C 你的邮箱 eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519 cat ~/.ssh/id_ed25519.pub把公钥加到 GitHub / GitLab / Gitee测试ssh -T gitgithub.com3.4 Node.js 用 NVM 管理curl -o- \ https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh \ | bash source ~/.bashrc command -v nvm nvm install --lts nvm alias default lts/* node --version npm --version项目里固定版本cd ~/projects/你的项目 node --version .nvmrc nvm use3.5 Python 虚拟环境cd ~/projects/你的项目 python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -r requirements.txt deactivate.gitignore里加上.venv/、__pycache__/、*.pyc。3.6 安装 Codex CLInode --version npm --version npm install -g openai/codex codex --version3.7 config.toml 骨架Codex 的配置文件放在~/.codex/config.toml。先建目录mkdir -p ~/.codex写入骨架把 Key 换成你在 TaoToken 控制台创建的那一个# ~/.codex/config.toml model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api responses [profiles.default] model gpt-5-codex model_provider taotoken approval_policy on-request sandbox_mode workspace-writeKey 不直接写进 toml用环境变量注入避免误提交。在~/.bashrc末尾加export TAOTOKEN_API_KEY你的_TaoToken_Key然后source ~/.bashrc echo $TAOTOKEN_API_KEY | head -c 8只打印前 8 位确认已加载即可。注意base_url用https://taotoken.net/api不要带 UTM 参数那是给网页链接用的API 调用不需要。3.8 VS Code 与 WSL 扩展Windows 装好 VS Code 后在 PowerShell 里code --version code --install-extension ms-vscode-remote.remote-wsl code --install-extension OpenAI.chatgpt在 Ubuntu 里进项目并打开cd ~/projects/你的项目 code .VS Code 左下角应显示WSL: Ubuntu。打开终端检查pwd which node which python3 which git路径应来自 Linux比如/home/developer/...、/home/developer/.nvm/...、/usr/bin/git。如果显示C:\...说明当前不是 WSL 工作区。3.9 Docker Desktop 集成Windows 装 Docker DesktopSettings → General 确认勾选Use the WSL 2 based engineSettings → Resources → WSL Integration 打开 Ubuntu点Apply Restart。不要在 Ubuntu 里再单独装一套docker-ce/dockerd会和 Docker Desktop 冲突。Ubuntu 里验证docker version docker compose version docker run --rm hello-world4. 验证请求让 Codex 跑一次真实环境自检4.1 自检脚本mkdir -p ~/bin nano ~/bin/check-dev-env.sh内容#!/usr/bin/env bash set -u PASS0 FAIL0 check_command() { local command_name$1 if command -v ${command_name} /dev/null 21; then printf [PASS] %-15s %s\n \ ${command_name} \ $(command -v ${command_name}) PASS$((PASS 1)) else printf [FAIL] %-15s not found\n ${command_name} FAIL$((FAIL 1)) fi } echo System uname -a printf User: %s\n $(whoami) printf Home: %s\n ${HOME} printf PWD: %s\n $(pwd) echo echo Commands check_command git check_command node check_command npm check_command python3 check_command pip3 check_command codex check_command docker check_command jq check_command rg check_command code echo echo Versions git --version 2/dev/null || true node --version 2/dev/null || true npm --version 2/dev/null || true python3 --version 2/dev/null || true codex --version 2/dev/null || true docker --version 2/dev/null || true docker compose version 2/dev/null || true echo echo Result printf PASS%s\n ${PASS} printf FAIL%s\n ${FAIL} if [ ${FAIL} -gt 0 ]; then exit 1 fi赋权并运行chmod x ~/bin/check-dev-env.sh ~/bin/check-dev-env.sh预期git、node、npm、python3、pip3、codex、docker、jq、rg、code全部 PASS。4.2 用 Codex 验证整个环境建一个验证仓库mkdir -p ~/projects/codex-environment-lab cd ~/projects/codex-environment-lab git init npm init -y cat README.md EOF # Codex Environment Lab 用于验证 Windows 11 WSL2 VS Code Node.js Python Docker Codex 环境。 EOF git add README.md package.json git commit -m chore: initialize environment lab启动 Codexcodex输入提示词请检查当前开发环境不要修改任何文件。 需要验证 当前工作目录位于 WSL Linux 文件系统而不是 /mnt/c。 当前目录是 Git 仓库。 Git、Node.js、npm、Python、Codex、Docker 和 Docker Compose 可用。 输出各工具版本。 执行 git status。 执行 docker info但不要创建或删除容器。 检查 README.md 内容。 最后给出已通过项、失败项、修复建议。如果 Codex 能正确报出/home/...路径、Git 分支、Node 和 Python 版本、Docker 可用说明整条链路通了。执行完再git status工作区应保持干净。5. 本篇常见错排查5.1wsl --install无法执行以管理员身份运行 PowerShell执行wsl --status和wsl --update。仍失败就检查 Windows Update、虚拟机平台、Windows Subsystem for Linux 三个功能是否启用。5.2 Ubuntu 显示 WSL1wsl -l -v wsl --set-version Ubuntu 2 wsl --set-default-version 25.3nvm: command not foundsource ~/.bashrc grep -n NVM_DIR ~/.bashrc正常应包含export NVM_DIR$HOME/.nvm和加载nvm.sh的两行。没有就关掉终端重开。5.4codex: command not foundnpm config get prefix npm install -g openai/codexlatest command -v codex codex --version确认 Codex 是装在 WSL 里而不是只装在 Windows PowerShell 里。5.5 VS Code 终端用的是 Windows看左下角是否显示WSL: Ubuntu。不是的话在 Ubuntu 里cd到项目再code .重新打开。终端里uname -a应显示 Linux。5.6 Docker 命令不可用确认 Docker Desktop 在运行wsl -l -v能看到 UbuntuSettings → Resources → WSL Integration 里 Ubuntu 已开启并Apply Restart然后 Ubuntu 里重跑docker version。5.7 Docker 与 WSL 内 Docker 冲突which docker ps aux | grep dockerd如果之前在 Ubuntu 里装过 Docker Engine会和 Docker Desktop 冲突。按 Docker 官方建议用 Docker Desktop WSL2 Backend 时不要同时维护一套 WSL 内的 Docker Engine。5.8 项目在/mnt/c里很慢mkdir -p ~/projects cp -a /mnt/c/projects/你的项目 ~/projects/ code ~/projects/你的项目5.9 Git 文件全部显示被修改多半是换行符问题git config --global core.autocrlf input项目加.gitattributes* textauto eollf5.10 Python 包装进系统环境不要sudo pip install。正确方式python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt5.11 Codex 报 Key 或 401先确认环境变量已加载echo $TAOTOKEN_API_KEY | head -c 8再确认~/.codex/config.toml里base_url是https://taotoken.net/apienv_key写的是TAOTOKEN_API_KEY。Key 失效就去控制台重新生成https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite6. 下一步把环境接进日常编码流环境搭好只是起点。接下来建议做三件事一是把~/.codex/config.toml和~/.bashrc里的 Key 注入方式固定下来团队里每个人用同一套骨架只换自己的 Key二是把~/bin/check-dev-env.sh加进项目 onboarding 文档新人 clone 完先跑一遍三是长期编码和 Agent 任务走 Coding Plan把额度集中管理避免每个项目单独配。如果你在验证模型输出是否符合预期可以先用模型对话页面快速试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite长期跑 Codex 编码任务用 Coding Plan 更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后提醒一句config.toml里永远不要硬编码 Key.gitignore里加上.env、.env.*、*.pem、*.key提交前git status扫一眼。环境这东西一次搭对后面省的是几十次排查的时间。
