> For the complete documentation index, see [llms.txt](https://docs.xxooapi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xxooapi.com/gu-zhang-pai-cha.md).

# 故障排查

代理、权限、网络报错怎么办 —— 用 AI 一步步排查

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

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

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

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

### 万能提示词模板

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

> 我是命令行新手，不理解终端里各种信息的含义。我的核心目标只有一个：**\[替换成你的目标，比如"安装 Node.js 并确认能正常使用"或"让 Claude Code 连上** xxooAPI **并发出第一条消息"]**。我会把终端报错原样文字或截图发给你，请你根据我发的内容一步一步告诉我该做什么。
>
> 要求：
>
> 1. 始终围绕核心目标，不要跑题。
> 2. 每次只告诉我当前这一步该做什么，不要一次给很多步骤。
> 3. 用新手能听懂的话解释，不要默认我懂命令行。
> 4. 明确告诉我：现在该输入什么、按什么键、看到什么算正常。
> 5. 如果终端出现报错、警告、选择题或权限提示，请根据我发的原文帮我判断，不要让我自己猜。
> 6. 如果某一步成功了，请明确告诉我"这一步完成，接下来做什么"。
> 7. 请把自己当成远程陪我操作的人：我贴终端输出或截图，你判断下一步，直到目标完成。

然后贴报错截图，按 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% 情况）

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

### 彻底检查

让 AI 带你查三样东西：

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

**手动清除 npm 代理**：

```bash
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`           | 去 [数据看板](https://xxooapi.com/console) 查余额，可能需要充值                         |
| `5xx` / 请求偶发失败                         | 过几分钟重试；持续出现请发邮件到 <support@xxooapi.com>                                   |
| 其他看不懂的英文                               | 截图发 AI（⑤）                                                                |

## xxooAPI 特有问题

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

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

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

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

### Codex 报 404

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

### 余额明明有为什么扣不到

查 [使用日志](https://xxooapi.com/console/log)：月卡用户当日额度优先；额度用完会自动切按量付费余额。若按量余额也为 0 就会失败。

***

**查完还是不行？** 发邮件到 [**support@xxooapi.com**](mailto:support@xxooapi.com)，附上：

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

[入门使用手册\
Claude Code / Codex 日常操作 —— 切模型、整理对话、看 Token 明细](/ru-men-shi-yong-shou-ce.md)

[常见问题      xxooAPI 使用中的常见问题解答](/chang-jian-wen-ti.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xxooapi.com/gu-zhang-pai-cha.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.