命令无法识别、配置不生效、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 | iex

CMD 安装命令：

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 或调整配置后，已经打开的终端可能仍在使用旧环境。

正确操作顺序：

1. 保存修改；

2. 关闭当前终端；

3. 重新打开 PowerShell、CMD 或 Git Bash；

4. 再运行版本命令。

很多“明明安装成功，命令却无法识别”的问题，重新打开终端后就能解决。

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、鉴权失败或无权限提示时，按顺序检查：

1. API Key 是否复制完整；

2. 密钥前后是否多了空格；

3. 密钥类型是否为 codex；

4. auth.json 是否位于正确目录；

5. API 地址是否与平台后台一致；

6. 修改后是否重新打开终端。

💡 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 | iex

CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

WinGet：

winget install Anthropic.ClaudeCode

如果命令无法识别或出现语法错误，先检查终端是否匹配；如果出现 403、fetch failed，优先检查网络和安装地址。

三种安装方式选择一种，不要重复安装。

2. claude 无法识别

常见报错：

The term 'claude' is not recognized

或者：

claude 不是内部或外部命令

Claude Code 原生安装在 Windows 下的常见路径为：

C:\Users\<你的用户名>\.local\bin

如果该目录没有加入用户 PATH：

1. 打开“系统属性”；

2. 进入“环境变量”；

3. 找到用户变量中的 Path；

4. 点击“编辑”；

5. 添加安装目录；

6. 保存并重新打开终端。

然后运行：

claude --version

Windows 原生安装程序默认将 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 地址时，先不要反复登录，重点检查：

1. API Key 是否复制完整；

2. 密钥类型是否为 Claude Code；

3. settings.json 路径是否正确；

4. ANTHROPIC_AUTH_TOKEN 拼写是否正确；

5. API 地址是否与平台后台一致；

6. 修改后是否重新打开终端。

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 或配置文件后，重新打开终端再测试。

先判断问题卡在哪一层，再处理对应环节，通常比反复卸载重装更快。