# OpenRelay 常见问题与解答 (FAQ)

> 遇到问题先查这里。如果未解决，请到 [GitHub Issues](https://github.com/romgX/openrelay/issues) 提问。

---

## 目录

1. [安装与启动](#安装与启动)
2. [连接与配置](#连接与配置)
3. [Provider 与配额](#provider-与配额)
4. [报错排查](#报错排查)
5. [IDE 集成](#ide-集成)
6. [安全与隐私](#安全与隐私)
7. [LINUX DO Connect](#linux-do-connect)

---

## 安装与启动

### Q: 怎么安装 OpenRelay？

从 GitHub 下载最新版本：https://github.com/romgX/openrelay/releases

支持平台：macOS (ARM64)、Windows (x64)。

二进制版本不需要 Node.js，开箱即用。

### Q: 怎么启动？

**二进制版本：**

```bash
# macOS
./openrelay

# Windows
.\openrelay-windows-x64.exe
```

**npm 安装版本（需要 Node.js >= 18）：**

```bash
npm install -g openrelay
openrelay
```

macOS 首次运行需授权 Keychain：

```bash
./openrelay --setup
```

启动后打开浏览器访问 `http://localhost:18765` — 所有配置都在 Web 面板中完成。

### Q: 怎么测试所有 Provider 连接？

```bash
./openrelay --test
```

### Q: 怎么设置开机自启？

目前没有内置的开机自启命令。推荐方式：

macOS：将启动命令添加到 Login Items，或创建 LaunchAgent plist。

Windows：将快捷方式放入 `shell:startup` 文件夹。

---

## 连接与配置

### Q: 怎么连接 Claude Code？

**方法一：Web 面板一键配置（推荐）**

打开 `http://localhost:18765` → **Work** 标签页 → 为 Claude Code 选择 Provider → 开启开关 → **重新打开终端**。

**方法二：手动设置环境变量**

```bash
export ANTHROPIC_BASE_URL=http://localhost:18765
export ANTHROPIC_API_KEY=unused
```

### Q: 怎么连接 Cursor？

打开 `http://localhost:18765` → **IDE** 标签页 → Cursor 区域选择 Provider 和模型 → 点击 **启动**。

**注意**：启动代理后，**必须通过控制面板的启动按钮打开 Cursor**。直接打开 Cursor 将绕过代理。

### Q: 怎么连接 Windsurf / Antigravity / VS Code Copilot？

打开 `http://localhost:18765` → **IDE** 标签页 → 选择对应 IDE → 选择 Provider 和模型 → 点击 **启动**。

- **Windsurf** — 启动后自动配置，重新打开 Windsurf 即可生效
- **Antigravity** — 启动后自动配置，**需要重启 Antigravity** 才能生效
- **VS Code Copilot** — 启动后自动配置，在 Copilot Chat 中选择 Ollama 模型使用

### Q: 怎么连接 Aider / Goose / Amp 等 CLI 工具？

打开 `http://localhost:18765` → **Work** 标签页 → 为每个工具选择 Provider → 开启开关 → **重新打开终端**。

### Q: 怎么查看当前配置？

打开 Web 面板 `http://localhost:18765`，所有 Provider 状态、连接配置、使用量都在面板中展示。

配置文件位置：`~/.openrelay/config.json`

---

## Provider 与配额

### Q: 怎么添加免费 Provider？

**IDE Provider**（自动发现，无需配置）：Claude Desktop、Claude Code、Kiro、Windsurf、Antigravity、OpenCode、VS Code Copilot。

**直连 API Provider**（需要 API Key）：打开 Web 面板 → 点击侧边栏中未连接的 API Provider → 输入 API Key 即可。

推荐免费 Provider：
- **Groq** — 14,400 次/天，Llama 3.3 70B，速度极快
- **Cerebras** — 100 万 token/天，Llama 70B
- **Gemini** — 免费额度大，100 万上下文
- **SambaNova** — Llama 405B，200K token/天
- **OpenRouter** — 30+ 免费模型

### Q: 免费配额用完了怎么办？

使用模型组功能（**Custom** 标签页），将多个 Provider 组合在一起。Groq 用完 → 自动切到 Cerebras → 再切 SambaNova。建议多注册几个 Provider，配额叠加更稳。

### Q: 怎么查看各 Provider 状态？

打开 Web 面板 `http://localhost:18765`，侧边栏绿点表示已连接。点击任一 Provider 可查看详细状态和配额信息。

---

## 报错排查

### Q: `impit not available (Cannot find module 'impit/index.wrapper.js')`

**这是正常的提示信息，不是错误。**

impit 是可选的 Chrome TLS 指纹模拟库，用于绕过 CloudFlare 的 JA3/JA4 检测。二进制版本中无法内嵌 impit（含原生 .node 文件），会自动降级到原生 fetch。

如果使用 Claude Desktop Provider 遇到持续 403 错误，可改用 npm 安装方式（`npm install -g openrelay`），impit 会自动安装并启用。

### Q: `connection refused localhost:18765`

OpenRelay 没有运行。启动它：

```bash
./openrelay          # macOS
.\openrelay-windows-x64.exe   # Windows
```

如果已经启动但仍报错，检查端口是否被占用：

```bash
# macOS
lsof -i :18765

# Windows
netstat -ano | findstr 18765
```

### Q: `401 Unauthorized`

API Key 过期或无效。打开 Web 面板检查对应 Provider 的连接状态。

如果是 IDE Provider（Claude Desktop、Kiro 等），尝试打开对应的 IDE 应用让它刷新 Token，然后在 Web 面板中点击「重新连接」。

### Q: `rate limit exceeded`

当前 Provider 配额用完了。OpenRelay 会自动切换到下一个可用 Provider（如果配置了模型组）。

如果所有 Provider 都限流：
1. 等几分钟后重试（大部分免费配额按分钟/小时重置）
2. 在 Web 面板添加更多 Provider
3. 检查是否有 Provider 的 Key 失效了

### Q: `403 Forbidden`（CloudFlare 拦截）

部分 Provider（如 Claude Desktop）使用 CloudFlare 防护。OpenRelay 会自动刷新 Cookie 并重试。

如果持续 403：
1. 检查启动日志中 impit 是否已加载
2. 重启 OpenRelay
3. 重新打开 Claude Desktop 让它刷新 Cookie

### Q: `ECONNRESET` 或 `socket hang up`

网络不稳定或 Provider 服务端断开连接。通常是临时问题，重试即可。

如果频繁出现：
1. 检查网络连接
2. 如果使用代理（Clash 等），将 Provider 域名加入直连规则
3. 在 Web 面板切换到其他 Provider

### Q: 启动时报 `EADDRINUSE`

端口 18765 已被占用。可能是另一个 OpenRelay 实例在运行。

```bash
# macOS — 查找占用进程
lsof -i :18765
kill <PID>

# Windows
netstat -ano | findstr 18765
taskkill /PID <PID> /F
```

### Q: 使用 Clash/代理？

OpenRelay 自动检测 Clash fake-ip（198.18.x.x）并通过 DoH 回退。建议将 `license.limitlessmeto.com` 加入直连规则以获得最佳体验。

---

## IDE 集成

### Q: Claude Code 显示 `model not found`

确认 OpenRelay 已启动并检查可用模型：

```bash
curl http://localhost:18765/v1/models
```

确保环境变量设置正确。最简单的方法：在 Web 面板 **Work** 标签页中配置，然后重新打开终端。

### Q: Cursor 连不上 OpenRelay

1. 确认 OpenRelay 已启动
2. 在 Web 面板 **IDE** 标签页启动 Cursor RPC 代理
3. **必须通过面板的启动按钮打开 Cursor**（直接打开 Cursor 会绕过代理）
4. 首次使用需要信任 TLS 证书（面板会提示操作步骤）

### Q: Kiro 显示断开连接

Kiro 的 AWS Token 约 1 小时过期。解决方法：
1. 打开 Kiro IDE 让它刷新 Token
2. 回到 Web 面板点击「重新连接」
3. 也可以在面板中使用「切换账户」重新登录

### Q: 响应速度很慢

1. 检查当前使用的 Provider 和模型 — 大模型（如 405B）比小模型慢
2. 切换到速度更快的 Provider（Groq、Cerebras 速度最快）
3. 检查网络延迟

### Q: 数据存在哪里？

配置文件：`~/.openrelay/config.json`

日志输出到启动 OpenRelay 的终端窗口（stdout），仅包含错误信息和请求元数据（Provider、模型、状态码），**不含消息内容或凭据**。

删除所有数据：`rm -rf ~/.openrelay/`

---

## 安全与隐私

### Q: 用 OpenRelay 会不会被封号？

不会。OpenRelay 跟"反代"（反向代理）完全不同：

- **反代**：你的请求经过别人的服务器，多人共用一个 Key，容易被 Provider 检测到异常然后封号。
- **OpenRelay**：纯本地运行，请求从你自己的电脑直接发到 AI Provider，跟你手动调 API 没有任何区别。Provider 看到的就是一个正常用户在用自己的配额，不存在封号风险。

简单说：OpenRelay 只是帮你在本地管理和转发请求，不碰你的账号，不经过任何中间服务器。

唯一需要注意的是：如果某个 Provider 自己调整了免费额度政策（比如取消免费 tier），那是 Provider 的决定，跟用不用 OpenRelay 无关。这种情况下 OpenRelay 会自动切换到其他还有额度的 Provider，不影响使用。

### Q: 我的 API Key / Token 安全吗？会不会被上传？

绝对不会。OpenRelay 的安全设计：

1. **凭据不离开本机** — 所有 API Key、Token、Cookie 只在你电脑的本地内存中使用，不会上传到任何地方。
2. **直连 AI 后端** — 请求从你的机器直接发到 AI Provider，中间没有任何第三方服务器。
3. **不记录聊天内容** — 日志只包含错误信息和请求元数据（哪个 Provider、哪个模型、状态码），你的对话内容从不被记录或缓存。
4. **代码可审计** — 凭据处理的核心代码（`cookie.ts`）公开可查，不放心可以自己看。

你的数据只存在 `~/.openrelay/config.json` 里，想彻底删除执行 `rm -rf ~/.openrelay/` 即可。

---

## LINUX DO Connect

### Q: LINUX DO 登录有什么用？

[LINUX DO](https://linux.do) 社区用户可以使用 linux.do 账号登录 OpenRelay，获得社区专属权益。在 Dashboard 右上角点击 LINUX DO 按钮即可登录。

### Q: 登录后影响原来的账号吗？

不影响。LINUX DO 登录与 OpenRelay 的注册/Pro 付费是两套独立系统，互不干扰。

---

> 最后更新：2026-03-29
>
> 如果你的问题不在列表中，请到 [GitHub Issues](https://github.com/romgX/openrelay/issues) 提问，我们会及时补充到本文档。
