博客

Windows 使用 Codex 常见问题：PowerShell、WSL2、PATH 及代理全攻略

Windows 使用 Codex 常见问题：PowerShell、WSL2、PATH 及代理全攻略

在 Windows 系统上使用 Codex 进行 AI 编程时，开发者经常会遇到 PowerShell 执行策略阻止、WSL2 环境配置复杂、PATH 路径不生效、代理设置混乱等问题。本文将逐一拆解这些常见坑点，并提供经过验证的解决方案。

Windows 上最常见的 Codex 问题

根据社区反馈，Windows 用户在使用 Codex 时遇到频率最高的问题包括：

  1. PowerShell 执行策略拦截：默认情况下 PowerShell 禁止运行脚本，导致 Codex 安装失败
  2. command not found：安装后终端提示找不到 codex 命令
  3. WSL2 配置复杂：在 WSL2 中使用 Codex 时需要额外的网络和工具链配置
  4. 代理不生效：Windows 和 WSL2 的代理设置相互独立
  5. Node.js 版本兼容：Windows 上的 Node.js 版本管理（nvm-windows）与 Linux 不同
  6. 路径包含空格：Windows 用户名或目录路径包含中文或空格导致安装异常

TeamoRouter：Windows 快速接入方案

在 Windows 上使用 TeamoRouter 接入 Codex 是最简单的方案。无需处理 OpenAI API 的代理问题，直接配置 baseUrl 即可。

Windows 下配置 TeamoRouter：

powershell
# PowerShell 中设置环境变量
$env:CODEX_BASE_URL="https://api.teamorouter.com/v1"
$env:CODEX_API_KEY="your-teamorouter-key"

# 设置为系统环境变量（持久化）
[System.Environment]::SetEnvironmentVariable('CODEX_BASE_URL', 'https://api.teamorouter.com/v1', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('CODEX_API_KEY', 'your-teamorouter-key', [System.EnvironmentVariableTarget]::User)

Windows 是否支持 Codex？

完全支持。Codex 官方支持 Windows、macOS 和 Linux 三大平台。在 Windows 上可以通过以下方式使用：

  • PowerShell：原生 Windows 终端，直接执行 Codex 命令
  • CMD：传统命令行界面，功能完整
  • WSL2：Linux 子系统环境，提供接近 Linux 原生体验
  • Git Bash：集成在 Git for Windows 中的轻量级终端

PowerShell 安装 Codex

安装 Node.js（如未安装）：

powershell
# 使用 winget 安装 Node.js
winget install OpenJS.NodeJS.LTS

# 验证安装
node --version
npm --version

安装 Codex：

powershell
# 全局安装 Codex
npm install -g @openai/codex

设置执行策略（如遇权限错误）：

powershell
# 查看当前执行策略
Get-ExecutionPolicy

# 设置为 RemoteSigned（允许本地脚本，远程脚本需签名）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

WSL2 安装 Codex

WSL2 是 Windows 上体验 Codex 的最佳环境之一。

安装 WSL2：

powershell
# 以管理员身份运行 PowerShell
# 安装 WSL
wsl --install

# 设置 WSL2 为默认版本
wsl --set-default-version 2

# 查看已安装的 Linux 发行版
wsl -l -v

在 WSL2 中安装 Codex：

bash
# 更新包管理器
sudo apt update && sudo apt upgrade -y

# 安装 Node.js（使用 NodeSource）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 验证
node --version
npm --version

# 全局安装 Codex
npm install -g @openai/codex

# 验证安装
codex --version

PATH 路径问题

PowerShell 中 Codex 命令找不到：

powershell
# 查看 npm 全局安装路径
npm config get prefix
# 通常在 C:\Users\<用户名>\AppData\Roaming\npm

# 手动添加 PATH（PowerShell 持久化）
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\$env:USERNAME\AppData\Roaming\npm",
    "User"
)

# 立即生效（当前会话）
$env:Path = [Environment]::GetEnvironmentVariable("Path", "User")

WSL2 中 Codex 命令找不到：

bash
# 检查 npm 全局 bin 路径
npm bin -g
# 通常在 /usr/local/bin 或 /home/<用户>/.npm-global/bin

# 添加到 PATH（~/.bashrc）
export PATH=$PATH:/home/$(whoami)/.npm-global/bin
source ~/.bashrc

PowerShell 执行策略问题

PowerShell 的执行策略是 Windows 特有的安全机制，会阻止 Codex 相关脚本的运行。

常见错误：

text
无法加载文件 codex.ps1，因为在此系统上禁止运行脚本。

解决方案：

powershell
# 方法一：修改执行策略（推荐）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 方法二：绕过单个脚本（不推荐）
powershell -ExecutionPolicy Bypass -File "codex.ps1"

执行策略说明：

  • Restricted：默认配置，禁止所有脚本运行
  • RemoteSigned：本地脚本可运行，远程脚本需签名（推荐）
  • AllSigned：所有脚本需签名
  • Unrestricted：所有脚本可运行（不推荐）

Windows 与 WSL2 的代理差异

Windows 和 WSL2 的代理设置相互独立，这是最常见的混淆点。

Windows 系统代理设置：

powershell
# PowerShell 临时设置
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

# 系统级设置（控制面板 → Internet 选项 → 连接 → 局域网设置）

WSL2 代理设置（不能共用 Windows 的代理变量）：

bash
# 获取 Windows 宿主机 IP
export host_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')

# 设置代理指向宿主机
export HTTP_PROXY=http://$host_ip:7890
export HTTPS_PROXY=http://$host_ip:7890

核心区别：Windows 代理使用 127.0.0.1，WSL2 代理必须使用宿主机 IP（在 WSL2 中 127.0.0.1 指向 WSL2 自身，不是 Windows 宿主机）。

Node.js / Git 环境问题

Node.js 版本管理：

Windows 使用 nvm-windows 管理多版本 Node.js，与 Linux/macOS 的 nvm 不同。

powershell
# 安装 nvm-windows（用 winget）
winget install nvm-windows

# 安装指定版本
nvm install 22.0.0

# 使用指定版本
nvm use 22.0.0

# 查看已安装版本
nvm list

Git for Windows 配置：

powershell
# 安装 Git
winget install Git.Git

# 配置代理（与 Linux 相同）
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

常见 Node.js 兼容性问题：

powershell
# Node.js 版本过低导致 Codex 不兼容
# 升级到 LTS 版本
nvm install 22.0.0
nvm use 22.0.0

# npm 缓存问题
npm cache clean --force
npm install -g @openai/codex

快速开始

  1. 注册 TeamoRouter 获取 API Key
  2. 按 Codex 接入文档 配置 baseUrl 和 API Key
  3. 跑通第一个 Codex 任务

免费获取 Codex 配置 →

通过 TeamoRouter 稳定接入 Codex、Claude Code、Gemini CLI。

常见问题 (FAQ)

Q: Windows 上 Codex 提示 "command not found" 怎么办？ A: 检查 npm 全局安装路径是否在 PATH 中。通常在 C:\Users\<用户名>\AppData\Roaming\npm，需要手动添加到系统 PATH。

Q: WSL2 和 PowerShell 哪个更适合运行 Codex？ A: 两者都可以。WSL2 提供更接近生产 Linux 环境的体验，且 Node.js 管理更简单。PowerShell 则无需虚拟机层，直接运行。建议根据你的项目环境决定。

Q: Windows 上使用 TeamoRouter 有哪些优势？ A: 无需为 OpenAI API 配置代理，直接设置 baseUrl 到 TeamoRouter 端点即可。环境变量配置与 Linux/macOS 一致，跨平台迁移成本低。

Q: PowerShell 执行策略如何永久修改？ A: 运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。这只会影响当前用户，不会影响系统其他用户。

Q: Codex 在 Windows 上性能如何？ A: Codex 本身是轻量级 CLI，在 Windows 上性能表现良好。但如果使用 WSL2，文件系统 I/O（特别是跨 /mnt/c 操作）会有性能损耗，建议将项目放在 WSL2 原生文件系统（~/project）中。

准备好接入了吗？登录控制台 · 购买额度 · 创建 API Key，三步即可开始。
获取 API Key查看帮助文档
关闭文章
Windows 使用 Codex 常见问题：PowerShell、WSL2、PATH 及代理全攻略 · TeamoRouter