10 KiB
OpenRelay 常见问题与解答 (FAQ)
遇到问题先查这里。如果未解决，请到 GitHub Issues 提问。
目录
安装与启动
Q: 怎么安装 OpenRelay？
从 GitHub 下载最新版本：https://github.com/romgX/openrelay/releases
支持平台：macOS (ARM64)、Windows (x64)。
二进制版本不需要 Node.js，开箱即用。
Q: 怎么启动？
二进制版本：
# macOS
./openrelay
# Windows
.\openrelay-windows-x64.exe
npm 安装版本（需要 Node.js >= 18）：
npm install -g openrelay
openrelay
macOS 首次运行需授权 Keychain：
./openrelay --setup
启动后打开浏览器访问 http://localhost:18765 — 所有配置都在 Web 面板中完成。
Q: 怎么测试所有 Provider 连接？
./openrelay --test
Q: 怎么设置开机自启？
目前没有内置的开机自启命令。推荐方式：
macOS：将启动命令添加到 Login Items，或创建 LaunchAgent plist。
Windows：将快捷方式放入 shell:startup 文件夹。
连接与配置
Q: 怎么连接 Claude Code？
方法一：Web 面板一键配置（推荐）
打开 http://localhost:18765 → Work 标签页 → 为 Claude Code 选择 Provider → 开启开关 → 重新打开终端。
方法二：手动设置环境变量
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 没有运行。启动它：
./openrelay # macOS
.\openrelay-windows-x64.exe # Windows
如果已经启动但仍报错，检查端口是否被占用：
# 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 都限流：
- 等几分钟后重试（大部分免费配额按分钟/小时重置）
- 在 Web 面板添加更多 Provider
- 检查是否有 Provider 的 Key 失效了
Q: 403 Forbidden（CloudFlare 拦截）
部分 Provider（如 Claude Desktop）使用 CloudFlare 防护。OpenRelay 会自动刷新 Cookie 并重试。
如果持续 403：
- 检查启动日志中 impit 是否已加载
- 重启 OpenRelay
- 重新打开 Claude Desktop 让它刷新 Cookie
Q: ECONNRESET 或 socket hang up
网络不稳定或 Provider 服务端断开连接。通常是临时问题，重试即可。
如果频繁出现：
- 检查网络连接
- 如果使用代理（Clash 等），将 Provider 域名加入直连规则
- 在 Web 面板切换到其他 Provider
Q: 启动时报 EADDRINUSE
端口 18765 已被占用。可能是另一个 OpenRelay 实例在运行。
# 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 已启动并检查可用模型：
curl http://localhost:18765/v1/models
确保环境变量设置正确。最简单的方法：在 Web 面板 Work 标签页中配置，然后重新打开终端。
Q: Cursor 连不上 OpenRelay
- 确认 OpenRelay 已启动
- 在 Web 面板 IDE 标签页启动 Cursor RPC 代理
- 必须通过面板的启动按钮打开 Cursor（直接打开 Cursor 会绕过代理）
- 首次使用需要信任 TLS 证书（面板会提示操作步骤）
Q: Kiro 显示断开连接
Kiro 的 AWS Token 约 1 小时过期。解决方法：
- 打开 Kiro IDE 让它刷新 Token
- 回到 Web 面板点击「重新连接」
- 也可以在面板中使用「切换账户」重新登录
Q: 响应速度很慢
- 检查当前使用的 Provider 和模型 — 大模型（如 405B）比小模型慢
- 切换到速度更快的 Provider（Groq、Cerebras 速度最快）
- 检查网络延迟
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 的安全设计：
- 凭据不离开本机 — 所有 API Key、Token、Cookie 只在你电脑的本地内存中使用，不会上传到任何地方。
- 直连 AI 后端 — 请求从你的机器直接发到 AI Provider，中间没有任何第三方服务器。
- 不记录聊天内容 — 日志只包含错误信息和请求元数据（哪个 Provider、哪个模型、状态码），你的对话内容从不被记录或缓存。
- 代码可审计 — 凭据处理的核心代码（
cookie.ts）公开可查，不放心可以自己看。
你的数据只存在 ~/.openrelay/config.json 里，想彻底删除执行 rm -rf ~/.openrelay/ 即可。
LINUX DO Connect
Q: LINUX DO 登录有什么用？
LINUX DO 社区用户可以使用 linux.do 账号登录 OpenRelay，获得社区专属权益。在 Dashboard 右上角点击 LINUX DO 按钮即可登录。
Q: 登录后影响原来的账号吗？
不影响。LINUX DO 登录与 OpenRelay 的注册/Pro 付费是两套独立系统，互不干扰。
最后更新：2026-03-29
如果你的问题不在列表中，请到 GitHub Issues 提问，我们会及时补充到本文档。