命令无法识别、配置改完没反应、出现 401、模型一直无响应……

遇到这些问题，先别急着卸载重装。判断思路其实很简单：

• 没有版本号：检查安装、PATH 和权限；

• 有版本号但不能回复：检查配置、密钥、API 地址和模型 ID；

• CLI 正常、桌面端异常：检查两边读取的配置路径。

按照“命令 → PATH → 权限 → 配置 → API → 模型”的顺序排查，通常很快就能找到问题。

还没部署双工具的，看📌：Mac 版 Codex + Claude Code 下载、安装、配置保姆级教程（2026 最新版）

---

📌 一、快速定位

打开 Mac“终端”，依次运行：

node -v
npm -v
which -a codex
which -a claude
codex --version
claude --version

根据结果快速判断：

报错或现象	优先检查
node、npm 无法识别	Node.js、终端环境
codex 无法识别	Codex 安装、npm 全局路径
claude 无法识别	~/.local/bin、PATH
Permission denied、EACCES	安装目录权限
Codex 出现 401	auth.json、Codex 类型密钥
Invalid API Key	settings.json、Claude Code 类型密钥
offline、fetch failed	网络、代理、API 地址
CLI 正常，桌面端异常	config.toml 读取路径
模型无法调用	模型 ID、密钥权限

---

⚙️ 二、检查环境

1. PATH 未生效

查看当前 Shell、PATH 和命令位置：

echo $SHELL
echo $PATH
which -a codex
which -a claude

判断方法：

• 没有输出：工具未安装，或安装目录未加入 PATH；

• 只有一个路径：继续检查版本号；

• 出现多个路径：可能存在重复安装或旧版本冲突。

修改 PATH 后，重新打开终端测试。使用 Zsh 时，也可以运行：

source ~/.zshrc

2. 目录权限不足

出现以下报错：

Permission denied
EACCES

通常说明当前用户没有安装目录的写入权限。

Codex 使用 npm 安装时，先查看全局目录：

npm config get prefix

Claude Code 重点检查：

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

显示 not writable，说明对应目录存在权限问题。

3. 网络或兼容异常

出现以下提示：

403
fetch failed
offline
Failed to fetch version

重点检查：

• 网络是否稳定；

• 代理或防火墙是否拦截请求；

• API 地址是否完整；

• 第三方接口是否正常；

• 修改配置后是否重新打开终端。

如果出现 dyld、Abort trap 等错误，再检查 macOS 版本和芯片架构：

sw_vers -productVersion
uname -m

---

🚀 三、排查 Codex

1. node、npm 找不到

出现：

zsh: command not found: npm

运行：

node -v
npm -v

本系列使用的环境为：

• Node.js 22+；

• npm 10+。

两个命令都没有版本号，先完成 Node.js 安装，再重新打开终端。

2. codex 找不到

常见报错：

zsh: command not found: codex

确认未正确安装后，再执行：

npm install -g @openai/codex

安装完成后重新打开终端，检查：

which -a codex
codex --version

npm 显示安装成功，但仍找不到 codex，继续运行：

npm config get prefix

确认该目录下的 bin 路径已经加入 PATH。

3. 401 或模型无响应

codex --version 正常，但无法回复，重点检查：

~/.codex/auth.json
~/.codex/config.toml

可以直接打开配置目录：

open ~/.codex

按照下面的顺序排查：

1. 文件是否位于 ~/.codex/；

2. 文件名是否变成 auth.json.txt 或 config.toml.txt；

3. API Key 是否复制完整；

4. 密钥类型是否为 Codex；

5. base_url 是否与平台后台一致；

6. model_provider 是否对应正确的提供商配置块；

7. 模型 ID 是否填写完整。

本系列使用：

model = "gpt-5.6-sol"

💡 API Key 以 sk- 开头，不代表密钥类型一定正确。Codex 与 Claude Code 的密钥不能混用。

切换模型不需要重新安装。修改 config.toml、保存文件并重新打开终端即可。

4. 桌面端不生效

CLI 可以正常回复，桌面端却没有使用同一套配置，通常是两边读取的 config.toml 不一致。

在 Codex 桌面客户端进入：

Settings → Configuration → Open config.toml

确认打开的是：

~/.codex/config.toml

保存配置并重启桌面应用，再输入一条简单指令测试。

💡 CLI 正常、桌面端异常时，优先检查配置路径，不需要重装 Codex CLI。

---

💻 四、排查 Claude Code

1. claude 找不到

常见报错：

zsh: command not found: claude

先检查命令和安装文件：

which -a claude
ls -la ~/.local/bin/claude

Claude Code 原生安装的常见位置为：

~/.local/bin/claude

文件存在但命令无法识别，通常是目录没有加入 PATH。

可以先在当前终端测试：

export PATH="$HOME/.local/bin:$PATH"
claude --version

确认有效后，再将下面这行加入 ~/.zshrc：

export PATH="$HOME/.local/bin:$PATH"

保存后运行：

source ~/.zshrc

2. 多个版本冲突

运行：

which -a claude

如果返回多个路径，系统中可能同时存在原生安装、Homebrew、npm 或旧版本。

常见表现包括：

• 实际运行的是旧版本；

• 更新后版本号没有变化；

• PATH 指向错误位置；

• 配置修改后不生效。

建议只保留一种安装方式，避免 PATH 继续调用旧版本。

3. 密钥或模型报错

Claude Code 用户配置文件为：

~/.claude/settings.json

可以直接打开目录：

open ~/.claude

重点检查三个字段：

ANTHROPIC_AUTH_TOKEN
ANTHROPIC_BASE_URL
ANTHROPIC_MODEL

排查顺序：

1. settings.json 是否位于 ~/.claude/；

2. 文件是否变成 settings.json.txt；

3. API Key 是否复制完整；

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

5. ANTHROPIC_BASE_URL 是否与平台后台一致；

6. ANTHROPIC_MODEL 是否使用完整模型 ID；

7. JSON 的双引号、大括号和逗号是否完整。

本系列配置示例为：

"ANTHROPIC_MODEL": "claude-opus-5"

出现：

Invalid API Key · Please run /login

使用自定义 API 地址时，不要急着反复登录。优先检查密钥类型、配置路径、API 地址和字段拼写。

⚠️ Codex 密钥不能填入 ANTHROPIC_AUTH_TOKEN，Claude Code 模型也不能填进 Codex 配置。

4. offline 或 fetch failed

显示 offline 不一定代表 API 完全不可用，可以先输入：

阅读当前项目，概括目录结构和主要功能，暂时不要修改文件。

根据结果判断：

• 可以正常回复：以实际调用结果为准；

• 无法回复：检查网络、代理和 API 地址；

• 同时出现 fetch failed：优先排查网络；

• 提示模型不存在：检查模型 ID 和密钥权限。

还可以运行：

claude doctor

该命令可用于检查 Claude Code 的安装和环境状态。

---

✅ 五、完成检查

两款工具的配置文件、密钥类型和模型 ID 不要混用：

工具	配置文件	重点检查
Codex	~/.codex/auth.json、~/.codex/config.toml	Codex 密钥、base_url、model
Claude Code	~/.claude/settings.json	Claude Code 密钥、API 地址、模型字段

修改配置后，统一完成以下操作：

1. 保存配置文件；

2. 关闭当前终端；

3. 重新打开终端；

4. 检查版本号；

5. 输入一条简单指令测试。

Mac 双工具排错顺序：

命令版本 → PATH → 权限 → 配置路径 → 密钥类型 → API 地址 → 模型 ID

最后记住三个判断：

没有版本号：检查安装、PATH 和权限。

有版本号但不能回复：检查配置、密钥和 API。

CLI 正常、桌面端异常：检查配置文件读取路径。

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