命令无法识别、配置不生效、401、模型无响应……
遇到这些问题，先别急着卸载重装。排错前只需要判断两件事：
codex --version、claude --version没有版本号：检查安装、终端和 PATH；可以显示版本号，但启动后无法回复：检查配置文件、密钥、API 地址和模型 ID。
按照下面的顺序排查，大多数 Windows 安装配置问题都能快速定位。
还没部署双工具的，看📌：Windows 版 Codex + Claude Code 下载、安装、配置教程（2026年8月版）
📌 一、快速定位
先在 PowerShell、CMD 或 Git Bash 中运行：
git --version node -v npm -v codex --version claude --version根据输出结果判断问题位置：
| 当前现象 | 优先检查 |
|---|---|
git无法识别 | Git for Windows |
node、npm无法识别 | Node.js、终端环境 |
codex无法识别 | Codex 全局安装 |
claude无法识别 | Claude Code 安装目录、PATH |
| 命令有版本号但不能回复 | 配置文件、密钥、API |
出现401 | API Key 内容与密钥类型 |
出现fetch failed | 网络、代理、接口地址 |
| CLI 正常，桌面端异常 | config.toml读取路径 |
| 指定模型无法调用 | 模型 ID、平台权限 |
判断：没有版本号，查安装和 PATH；有版本号但不能回复，查配置、密钥和 API。
⚙️ 二、检查 Windows 环境
1. 终端是否匹配
PowerShell、CMD 和 Git Bash 支持的命令并不完全相同，复制命令前先确认当前终端。
Claude Code 的 PowerShell 安装命令：
irm https://claude.ai/install.ps1 | iexCMD 安装命令：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd常见报错：
'irm' 不是内部或外部命令说明你可能在 CMD 中运行了 PowerShell 命令。
The token '&&' is not a valid statement separator说明你可能在 PowerShell 中运行了 CMD 命令。
遇到这类问题，不要改命令内容，切换到对应终端重新执行即可。
2. 终端是否刷新
安装程序、修改 PATH 或调整配置后，已经打开的终端可能仍在使用旧环境。
正确操作顺序：
保存修改；
关闭当前终端；
重新打开 PowerShell、CMD 或 Git Bash；
再运行版本命令。
很多“明明安装成功，命令却无法识别”的问题，重新打开终端后就能解决。
3. PowerShell 是否禁用脚本
如果出现：
running scripts is disabled on this system或者：
PSSecurityException说明 PowerShell 执行策略阻止了脚本运行。
确认报错一致，并了解修改执行策略的影响后，可运行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned关闭并重新打开 PowerShell，再执行安装命令。
4. 文件后缀是否正确
Windows 可能隐藏文件扩展名，导致配置文件实际变成：
auth.json.txt config.toml.txt settings.json.txt正确文件名必须是：
auth.json config.toml settings.json可以在文件资源管理器中开启：
查看 → 显示 → 文件扩展名5. 网络是否正常
出现403、offline或fetch failed时，优先检查：
当前网络是否稳定；
是否存在代理或防火墙限制；
安装地址能否正常访问；
API 地址是否填写完整；
第三方接口当前是否可用。
网络异常时，不要连续切换多种安装方式，以免出现重复安装和版本混乱。
🚀 三、排查 Codex
1.npm无法识别
如果出现：
'npm' 不是内部或外部命令先运行：
node -v npm -v本系列使用的安装环境为：
Node.js 22+；
npm 10+。
如果都没有版本号，先完成 Node.js 安装，再重新打开终端。
2.codex无法识别
如果出现：
'codex' 不是内部或外部命令重新执行全局安装：
npm install -g @openai/codex完成后关闭终端，重新打开并检查：
codex --version如果安装过程没有报错，先刷新终端，不要连续重复安装。
3. 配置没有生效
如果codex --version正常，但启动后无法回复，重点检查：
C:\Users\<你的用户名>\.codex\目录中需要有：
auth.json config.toml依次确认：
文件是否放在正确目录；
文件是否被保存成
.txt；auth.json是否填入完整 API Key；密钥类型是否选择
codex；是否误用了 Claude Code 类型密钥；
config.toml中的模型和 API 地址是否正确。
Codex 的个人配置默认位于~/.codex/config.toml，Windows 下对应%USERPROFILE%\.codex\config.toml。
4. 出现 401
出现401、鉴权失败或无权限提示时，按顺序检查：
API Key 是否复制完整；
密钥前后是否多了空格；
密钥类型是否为
codex；auth.json是否位于正确目录；API 地址是否与平台后台一致；
修改后是否重新打开终端。
💡 API Key 以
sk-开头，不代表密钥类型一定正确。Codex 和 Claude Code 的密钥不能混用。
5. 模型调用失败
Codex 配置重点检查：
model_provider model base_url本教程使用：
model = "gpt-5.6-sol"确认以下内容：
model_provider与提供商配置块名称一致；模型 ID 与平台后台完全一致；
base_url填写完整；顶层配置位于提供商配置块之前；
没有把 Claude Code 模型填进 Codex。
切换模型不需要重新安装 Codex。修改config.toml，保存后重新打开终端即可。
6. 桌面端不生效
如果 Codex CLI 可以正常回复，但桌面端没有使用相同配置，通常是两边读取的config.toml不一致。
Windows 用户配置路径：
C:\Users\<你的用户名>\.codex\config.toml在桌面端进入：
Settings → Configuration → Open config.toml确认打开的是刚才配置的用户文件。保存后重新启动桌面应用，再输入一条简单指令测试。
💡 CLI 正常、桌面端异常时，先检查配置路径，不需要重装 Codex CLI。
💻 四、排查 Claude Code
1. 安装命令失败
Windows 下选择一种安装方式即可。
PowerShell：
irm https://claude.ai/install.ps1 | iexCMD：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdWinGet：
winget install Anthropic.ClaudeCode如果命令无法识别或出现语法错误，先检查终端是否匹配；如果出现403、fetch failed，优先检查网络和安装地址。
三种安装方式选择一种，不要重复安装。
2.claude无法识别
常见报错：
The term 'claude' is not recognized或者：
claude 不是内部或外部命令Claude Code 原生安装在 Windows 下的常见路径为：
C:\Users\<你的用户名>\.local\bin如果该目录没有加入用户 PATH：
打开“系统属性”；
进入“环境变量”；
找到用户变量中的
Path；点击“编辑”；
添加安装目录；
保存并重新打开终端。
然后运行：
claude --versionWindows 原生安装程序默认将claude.exe放在%USERPROFILE%\.local\bin。
3. 配置没有生效
Claude Code 的 Windows 用户配置文件为：
C:\Users\<你的用户名>\.claude\settings.json重点检查：
ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL ANTHROPIC_MODEL确认：
ANTHROPIC_AUTH_TOKEN已替换为完整密钥；密钥类型选择的是 Claude Code；
没有误用 Codex 类型密钥；
ANTHROPIC_BASE_URL与平台后台一致；ANTHROPIC_MODEL是完整模型 ID；文件没有变成
settings.json.txt；JSON 的双引号、大括号和逗号完整。
Windows 下的~/.claude对应%USERPROFILE%\.claude，用户级配置文件为~/.claude/settings.json。
4.Invalid API Key
如果出现：
Invalid API Key · Please run /login使用自定义 API 地址时，先不要反复登录，重点检查：
API Key 是否复制完整；
密钥类型是否为 Claude Code；
settings.json路径是否正确；ANTHROPIC_AUTH_TOKEN拼写是否正确；API 地址是否与平台后台一致；
修改后是否重新打开终端。
ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL均是 Claude Code 支持的环境变量；
5. 模型无法调用
本教程使用：
"ANTHROPIC_MODEL": "claude-opus-5"如果出现模型不存在、无权限或调用失败，检查：
模型 ID 是否与平台后台一致；
当前密钥是否具有对应模型权限；
是否自行缩写了模型名称；
是否误填了 Codex 模型。
第三方平台的模型名称可能调整，以后台当前配置模板为准。
6. 显示offline
出现offline不一定代表 API 完全不可用，可以先输入：
阅读当前项目，概括目录结构和主要功能，暂时不要修改任何文件。根据结果判断：
可以正常回复：以实际调用结果为准；
无法回复：检查网络、代理、API 地址和密钥；
同时出现
fetch failed：优先排查网络环境。
✅ 五、快速对照
| 报错或现象 | 优先检查 |
|---|---|
npm无法识别 | Node.js、npm、重新打开终端 |
codex无法识别 | Codex 是否完成全局安装 |
| PowerShell 禁止脚本 | 执行策略、设备限制 |
| Codex 401 | auth.json、Codex 类型密钥 |
| Codex 模型调用失败 | config.toml、模型 ID、API 地址 |
| CLI 正常，桌面端异常 | 桌面端读取的配置路径 |
| Claude 安装命令报错 | 终端和安装命令是否匹配 |
claude无法识别 | .local\bin、用户 PATH |
Invalid API Key | Claude Code 类型密钥、settings.json |
offline、fetch failed | 网络、代理、API 地址 |
| Claude 模型调用失败 | ANTHROPIC_MODEL、模型权限 |
两款工具的配置文件不要混用：
| 工具 | Windows 配置文件 |
|---|---|
| Codex | %USERPROFILE%\.codex\auth.json、config.toml |
| Claude Code | %USERPROFILE%\.claude\settings.json |
💡 六、排错总结
Windows 双工具排查顺序：
命令版本 → 终端与 PATH → 配置路径 → 文件扩展名 → 密钥类型 → API 地址 → 模型 ID
最后记住两个判断：
命令没有版本号：检查安装和 PATH。
命令有版本号但不能回复：检查配置、密钥和 API。
Codex 与 Claude Code 使用不同的配置目录、密钥类型和模型 ID，不要混用。修改 PATH 或配置文件后，重新打开终端再测试。
先判断问题卡在哪一层，再处理对应环节，通常比反复卸载重装更快。
