故障排查

安装和使用过程中遇到报错是正常的，本章给出通用的排查方法。

核心思路：让 AI 陪你一步步查

你不需要自己看懂所有英文报错。截图 + 提示词 + 让 AI 一步一步带，就能解决 90% 的问题。

推荐使用任何支持图片识别的 AI：豆包、ChatGPT、Claude 网页版，或者——如果 Codex 已经能用，直接问 Codex 最快。

万能提示词模板

打开 AI 的新对话，先发这段：

我是命令行新手，不理解终端里各种信息的含义。我的核心目标只有一个：[替换成你的目标，比如"安装 Node.js 并确认能正常使用"或"让 Claude Code 连上 CCSub 并发出第一条消息"]。我会把终端报错原样文字或截图发给你，请你根据我发的内容一步一步告诉我该做什么。

要求：

始终围绕核心目标，不要跑题。

每次只告诉我当前这一步该做什么，不要一次给很多步骤。

用新手能听懂的话解释，不要默认我懂命令行。

明确告诉我：现在该输入什么、按什么键、看到什么算正常。

如果终端出现报错、警告、选择题或权限提示，请根据我发的原文帮我判断，不要让我自己猜。

如果某一步成功了，请明确告诉我"这一步完成，接下来做什么"。

请把自己当成远程陪我操作的人：我贴终端输出或截图，你判断下一步，直到目标完成。

然后贴报错截图，按 AI 指示一步步操作即可。

截图方法：

macOS：Command + Shift + 4，框选区域
Windows：Win + Shift + S，框选区域

代理问题（最常见的坑）

如果你电脑上装了 Clash / V2Ray / Shadowsocks / 机场客户端等，它们可能悄悄影响终端的网络环境。典型症状：

npm install 卡住不动
ECONNREFUSED / ETIMEDOUT
UNABLE_TO_VERIFY_LEAF_SIGNATURE / SELF_SIGNED_CERT_IN_CHAIN
浏览器正常但终端命令连不上

快速尝试（解决 80% 情况）

完全退出代理软件（右键菜单选「退出」，不是最小化）
关掉当前终端窗口，重新开一个新终端（旧窗口里的环境变量不会自动刷新）
再次执行之前的命令

彻底检查

让 AI 带你查三样东西：

1. 当前系统有没有代理软件在运行
2. 终端环境变量里有没有设置代理（HTTP_PROXY / HTTPS_PROXY / ALL_PROXY）
3. npm 全局配置里有没有代理设置（npm config get proxy）

手动清除 npm 代理：

npm config delete proxy
npm config delete https-proxy
npm config set registry https://registry.npmmirror.com

按症状分类的排查

① 命令找不到（command not found / 不是内部或外部命令）

我在终端输入 [node / npm / claude / codex] 提示 "command not found"
（或"不是内部或外部命令"）。我刚用 npm 安装过了，请帮我排查为什么
找不到这个命令。一次一步，我做完发结果给你。我的系统是 [Mac / Windows]。

常见原因：PATH 环境变量没刷新 → 关闭终端重开；或全局包安装路径没加入 PATH。

② 权限错误（Permission denied / EACCES）

我在执行 [你的命令] 时报了权限错误（Permission denied 或 EACCES）。
请一步步带我解决，不要让我做可能破坏系统的危险操作。
我的系统是 [Mac / Windows]。

macOS/Linux 通常是 sudo npm install -g ...；Windows 上不需要 sudo。

③ 网络错误（timeout / fetch failed）

先按「代理问题」一节排查，确认无代理问题后再找 AI。

④ Node.js 版本不兼容

我安装了 [工具名]，但运行时提示版本不兼容或需要更高版本的 Node.js。
我的 Node.js 版本是 [贴 node -v 的输出]。请帮我判断要不要升级、怎么升级。
一次一步。我的系统是 [Mac / Windows]。

⑤ 看不懂的其他报错

截图发给 AI，配这段：

我在 [安装 / 使用] [工具名] 时遇到下面这个报错，完全看不懂。
请帮我判断是什么问题，然后一步步带我解决。一次一步。
我的系统是 [Mac / Windows]。

症状 → 排查起点速查表

症状关键词	先排查
`timeout` / `ECONNREFUSED` / SSL / 证书	代理问题（本章第二节）
`command not found` / 不是内部命令	PATH / 环境变量（①）
`Permission denied` / `EACCES`	权限（②）
`engine "node" is incompatible`	Node 版本（④）
`401 Unauthorized` / `invalid_api_key`	检查 `ANTHROPIC_AUTH_TOKEN` / `OPENAI_API_KEY` 是否拼错，或是否误把 Base URL 改成了官方地址
`402` / `insufficient_quota`	去 /dashboard 查余额，可能需要充值
`5xx` / 请求偶发失败	过几分钟重试；持续出现请发邮件到 [email protected]
其他看不懂的英文	截图发 AI（⑤）

CCSub 特有问题

配完环境变量还是连的官方

原因：旧终端窗口里已经加载了原来的变量。关闭所有终端，重新打开再启动工具。macOS 上如果用 launchd 启动的 GUI 工具（如 IDE 插件），可能需要重启该 GUI 程序。

Claude Code 一直显示 "Connecting..."

检查 ANTHROPIC_BASE_URL 是否为 https://www.ccsub.net（不要有多余斜杠、不要写 /v1）。

Codex 报 404

OPENAI_BASE_URL 必须是 https://www.ccsub.net/v1（带 /v1），和 Claude Code 的写法不一样。

余额明明有为什么扣不到

查使用记录：月卡用户当日额度优先；额度用完会自动切按量付费余额。若按量余额也为 0 就会失败。

查完还是不行？ 发邮件到 [email protected]，附上：

使用的工具和版本（claude --version / codex --version）
系统信息（Windows 11 / macOS 14 等）
完整的报错截图或文本
你的注册邮箱（不要发 API Key）