Appearance
Codex Windows 安装与配置排障：PowerShell、PATH 和 API Key
Windows 上安装 Codex CLI 后，最常见的问题不是代码本身，而是终端、PATH 和环境变量没有对齐。下面按“命令找不到、变量不生效、权限错误、API 认证失败”的顺序排查。
先确认 Node.js 和 npm
在 PowerShell 运行：
powershell
node --version
npm --version
Get-Command node
Get-Command npm如果版本命令失败，先安装受支持的 Node.js LTS，并重新打开 PowerShell。Get-Command 可以确认当前终端实际调用的是哪个安装位置，避免系统里有多个 Node.js 版本。
检查 Codex 是否在 PATH
powershell
codex --version
Get-Command codex
$env:Path -split ';'安装后已经打开的终端不会总是自动刷新 PATH。关闭并重新打开 PowerShell，再检查一次。若存在多个全局 npm 目录，确认 Codex 安装到了当前 npm 使用的目录，而不是另一个 Node.js 版本。
设置 API Key 的正确方式
当前会话临时设置：
powershell
$env:OPENAI_API_KEY = "your-api-key"写入当前用户环境变量，供新终端使用：
powershell
[Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'your-api-key', 'User')设置后重新打开终端，并只检查是否存在：
powershell
if ($env:OPENAI_API_KEY) { 'API key is set' }不要在聊天、日志或截图中打印完整 Key。变量名和 Provider 配置必须一致，具体要求见 API Key 配置。
执行策略和权限错误
如果 PowerShell 阻止脚本执行，先阅读错误信息，确认被阻止的是 npm 的脚本入口还是项目脚本。不要为了绕过单个错误而长期放宽整台电脑的执行策略。可以在受控范围内使用当前用户策略，并遵循组织安全要求。
项目目录位于受保护路径时，也可能出现写入权限问题。把项目放在当前用户可写目录，或者让管理员明确授予必要权限，不要直接用管理员身份运行所有开发命令。
配置文件和工作目录
在正确的项目根目录启动 Codex：
powershell
Get-Location
Get-ChildItem package.json
Get-ChildItem .codex -Force -ErrorAction SilentlyContinue
codex用户级 .codex 配置和项目级配置可能同时存在。修改后确认当前终端、当前用户和当前项目读取的是同一套文件。遇到配置覆盖问题时，先备份并使用最小配置验证，不要直接删除所有文件。
常见错误速查
codex 找不到
重开终端，运行 Get-Command codex，确认 npm 全局 bin 在 PATH。仍失败时检查 Node.js 版本管理器是否切换了运行时。
Key 已设置但仍 401
确认新终端加载了变量、变量名与 Provider 一致、Key 没有多余引号或空格，并阅读 401 排障。
终端中文或路径异常
优先使用 PowerShell 7 或 Windows Terminal，项目路径避免特殊字符，并确认工具链使用 UTF-8。路径问题解决后再判断是否是 Codex 本身的错误。
FAQ
Windows 必须使用 PowerShell 吗？
不一定。PowerShell、Windows Terminal 和其他兼容终端都可以，但环境变量语法和 PATH 查看命令会不同。本文命令针对 PowerShell。
为什么设置的变量重开终端后消失？
$env:NAME = ... 只影响当前进程。需要持久化时使用用户环境变量设置方式，再打开新终端。
Windows 配置和 macOS/Linux 完全一样吗？
目标相同，但路径、环境变量语法、权限和 shell 命令不同。跨平台安装步骤见 Codex CLI 安装与使用。