lywsvip/openrelay
1
0
Fork 0
mirror of https://github.com/romgX/openrelay.git synced 2026-09-03 06:53:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

v0.8.7

Browse Source
This commit is contained in:
romgX
2026-03-12 01:45:37 +08:00
parent 3d69e84627
commit f1b07ee1c5
2 changed files with 227 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
faq-en.md
View File

@@ -20,33 +20,50 @@
Download the latest release from GitHub: https://github.com/romgX/openrelay/releases
Supported platforms: macOS (arm64/x64), Windows (x64).
Supported platforms: macOS (ARM64), Windows (x64).
The binary release requires no Node.js. Running from source requires Node.js >= 18.
The binary release requires no Node.js — it's ready to use out of the box.
### Q: How do I start it?
```bash
openrelay start
```
Check status:
**Binary release:**
```bash
openrelay status
# macOS
./openrelay
# Windows
.\openrelay-windows-x64.exe
```
Default port: `18765`.
**npm install (requires Node.js >= 18):**
```bash
npm install -g openrelay
openrelay
```
First time on macOS — authorize Keychain access:
```bash
./openrelay --setup
```
Once started, open `http://localhost:18765` in your browser — all configuration is done through the Web dashboard.
### Q: How do I test all provider connections?
```bash
./openrelay --test
```
### Q: How do I set it to start on boot?
macOS:
There's no built-in auto-start command yet. Recommended approaches:
```bash
openrelay service install
```
macOS: Add the launch command to Login Items, or create a LaunchAgent plist.
This creates a LaunchAgent that starts automatically after login.
Windows: Place a shortcut in the `shell:startup` folder.
---
@@ -54,33 +71,40 @@ This creates a LaunchAgent that starts automatically after login.
### Q: How do I connect Claude Code?
Option 1: One-click setup
**Option 1: Web dashboard one-click setup (recommended)**
```bash
openrelay config set-app claude-code claude-sonnet-4-6
```
Open `http://localhost:18765` → **Work** tab → select a Provider for Claude Code → toggle on → **reopen your terminal**.
Option 2: Set environment variables manually
**Option 2: Set environment variables manually**
```bash
export ANTHROPIC_BASE_URL=http://localhost:18765
export ANTHROPIC_API_KEY=unused
```
### Q: How do I connect Cursor / Windsurf / Cline?
### Q: How do I connect Cursor?
```bash
openrelay config set-app cursor claude-sonnet-4-6
openrelay config set-app windsurf claude-sonnet-4-6
```
Open `http://localhost:18765` → **IDE** tab → Cursor section → select Provider and model → click **Start**.
Or set the API Base URL to `http://localhost:18765` in your IDE settings.
**Important**: After starting the proxy, you **must launch Cursor from the dashboard's launch button**. Opening Cursor directly will bypass the proxy.
### Q: How do I connect Windsurf / Antigravity / VS Code Copilot?
Open `http://localhost:18765` → **IDE** tab → select the IDE → choose Provider and model → click **Start**.
- **Windsurf** — auto-configured after Start. Reopen Windsurf to apply.
- **Antigravity** — auto-configured after Start. **Restart Antigravity** to apply.
- **VS Code Copilot** — auto-configured after Start. Select the Ollama model in Copilot Chat.
### Q: How do I connect Aider / Goose / Amp and other CLI tools?
Open `http://localhost:18765` → **Work** tab → select a Provider for each tool → toggle on → **reopen your terminal**.
### Q: How do I view current configuration?
```bash
openrelay config list
```
Open the Web dashboard at `http://localhost:18765` — all provider status, connections, and usage stats are shown there.
Config file location: `~/.openrelay/config.json`
---
@@ -88,27 +112,24 @@ openrelay config list
### Q: How do I add free providers?
```bash
openrelay provider add
```
**IDE Providers** (auto-discovered, no setup needed): Claude Desktop, Claude Code, Kiro, Windsurf, Antigravity, OpenCode, VS Code Copilot.
Interactive setup will guide you. Recommended free providers:
**Direct API Providers** (API key required): Open the Web dashboard → click an unconnected API provider in the sidebar → enter your API key.
Recommended free providers:
- **Groq** — 14,400 req/day, Llama 3.3 70B, extremely fast
- **Cerebras** — 1M tokens/day, Llama 70B
- **Google AI Studio** — Gemini series, generous free tier
- **Gemini** — generous free tier, 1M context
- **SambaNova** — Llama 405B, 200K tokens/day
- **OpenRouter** — 30+ free models
### Q: What happens when free quota runs out?
OpenRelay automatically fails over to the next available provider. If all providers are rate-limited, they'll recover in a few minutes. We recommend registering multiple providers for better reliability.
Use model groups (**Custom** tab) to combine multiple providers. When Groq runs out → auto-failover to Cerebras → then SambaNova. We recommend registering multiple providers for better reliability.
### Q: How do I check provider status?
```bash
openrelay provider list
```
Or open the Web dashboard at `http://localhost:18765`.
Open the Web dashboard at `http://localhost:18765` — green dots in the sidebar mean the provider is connected. Click any provider for detailed status and quota info.
---
@@ -118,48 +139,43 @@ Or open the Web dashboard at `http://localhost:18765`.
**This is a normal informational message, not an error.**
impit is an optional Chrome TLS fingerprint library used to bypass CloudFlare JA3/JA4 detection. Without it, OpenRelay automatically falls back to native fetch — **everything works normally**.
impit is an optional Chrome TLS fingerprint library used to bypass CloudFlare JA3/JA4 detection. The binary release cannot embed impit (it contains native .node files), so it falls back to native fetch automatically.
You do NOT need to install impit manually. Only relevant if you encounter persistent 403 errors with the Claude Desktop provider.
If you encounter persistent 403 errors with the Claude Desktop provider, use the npm install method (`npm install -g openrelay`) — impit will be installed and enabled automatically.
### Q: `connection refused localhost:18765`
OpenRelay is not running. Start it:
```bash
openrelay start
./openrelay # macOS
.\openrelay-windows-x64.exe # Windows
```
If already started but still getting errors, check if the port is in use:
```bash
# macOS
lsof -i :18765
# Windows
netstat -ano | findstr 18765
```
### Q: `401 Unauthorized`
API key expired or invalid. Check your provider keys:
API key expired or invalid. Open the Web dashboard and check the connection status of the affected provider.
```bash
openrelay config list
```
If it's a Claude Code OAuth token expiration:
```bash
claude auth login
```
OpenRelay will automatically pick up the new token after re-authentication.
For IDE providers (Claude Desktop, Kiro, etc.), try opening the corresponding IDE app to refresh its token, then click "Reconnect" in the dashboard.
### Q: `rate limit exceeded`
Current provider quota is exhausted. OpenRelay automatically switches to the next available provider.
Current provider quota is exhausted. OpenRelay automatically switches to the next available provider (if you've configured model groups).
If all providers are rate-limited:
1. Wait a few minutes and retry
2. Add more providers: `openrelay provider add`
3. Check if any provider keys have expired: `openrelay provider list`
1. Wait a few minutes and retry (most free quotas reset per minute/hour)
2. Add more providers in the Web dashboard
3. Check if any provider keys have expired
### Q: `403 Forbidden` (CloudFlare block)
@@ -167,58 +183,77 @@ Some providers (e.g., Claude Desktop) use CloudFlare protection. OpenRelay autom
If 403 persists:
1. Check if impit is loaded (look in startup logs)
2. Try restarting: `openrelay restart`
3. Clear cookie cache and retry
2. Restart OpenRelay
3. Reopen Claude Desktop to let it refresh cookies
### Q: `ECONNRESET` or `socket hang up`
Network instability or provider-side disconnection. Usually temporary — OpenRelay retries automatically.
Network instability or provider-side disconnection. Usually temporary — just retry.
If it happens frequently:
1. Check your network connection
2. Check if you need a proxy (`openrelay config set proxy http://...`)
3. Switch to a different provider
2. If using a proxy (Clash, etc.), add provider domains to your direct rules
3. Switch to a different provider in the Web dashboard
### Q: `EADDRINUSE` on startup
Port 18765 is already in use. Another OpenRelay instance may be running:
Port 18765 is already in use. Another OpenRelay instance may be running.
```bash
openrelay status
# If it shows running, no need to start again
# macOS — find the process
lsof -i :18765
kill <PID>
# To force restart
openrelay restart
# Windows
netstat -ano | findstr 18765
taskkill /PID <PID> /F
```
### Q: Using Clash or other proxy?
OpenRelay auto-detects Clash fake-ip (198.18.x.x) and uses DoH fallback. For best results, add `license.limitlessmeto.com` to your direct rules.
---
## IDE Integration
### Q: Claude Code shows `model not found`
Confirm OpenRelay is running and the model name is correct:
Confirm OpenRelay is running and check available models:
```bash
openrelay status
curl http://localhost:18765/v1/models
```
Make sure environment variables are set correctly (`ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY`).
Make sure environment variables are set correctly. The easiest way: configure in the Web dashboard **Work** tab, then reopen your terminal.
### Q: Cursor can't connect to OpenRelay
1. Confirm OpenRelay is running: `openrelay status`
2. In Cursor Settings → Models:
- API Base URL: `http://localhost:18765/v1`
- API Key: `unused` (any value works)
3. Test connection: `curl http://localhost:18765/v1/models`
1. Confirm OpenRelay is running
2. Start the Cursor RPC proxy in the Web dashboard **IDE** tab
3. **You must launch Cursor from the dashboard's launch button** (opening Cursor directly bypasses the proxy)
4. First-time use requires trusting the TLS certificate (the dashboard will guide you)
### Q: Kiro shows disconnected
Kiro's AWS token expires after ~1 hour. To fix:
1. Open Kiro IDE to let it refresh the token
2. Go back to the Web dashboard and click "Reconnect"
3. You can also use "Switch Account" in the dashboard to re-login
### Q: Responses are very slow
1. Check which provider/model is in use — larger models (e.g., 405B) are slower
2. Switch to faster providers (Groq and Cerebras are the fastest)
3. Check network latency (`ping` the provider's domain)
3. Check network latency
### Q: Where is my data?
Config file: `~/.openrelay/config.json`
Logs print to the terminal (stdout) where OpenRelay was launched. They contain only errors and request metadata (provider, model, status) — **no message content or credentials**.
To delete all data: `rm -rf ~/.openrelay/`
---

197
faq.md
View File

@@ -1,8 +1,6 @@
# OpenRelay 常见问题与解答 (FAQ)
> 遇到问题先查这里。如果未解决，请到 [GitHub Issues](https://github.com/romgX/openrelay/issues) 提问。
>
> 维护说明：发现新的用户问题时，及时更新本文档。
---
@@ -22,33 +20,50 @@
从 GitHub 下载最新版本：https://github.com/romgX/openrelay/releases
支持平台：macOS (arm64/x64)、Windows (x64)。
支持平台：macOS (ARM64)、Windows (x64)。
打包版本不需要 Node.js；源码运行需要 Node.js >= 18。
二进制版本不需要 Node.js，开箱即用。
### Q: 怎么启动？
```bash
openrelay start
```
检查运行状态：
**二进制版本：**
```bash
openrelay status
# macOS
./openrelay
# Windows
.\openrelay-windows-x64.exe
```
默认监听端口：`18765`。
**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：
目前没有内置的开机自启命令。推荐方式：
```bash
openrelay service install
```
macOS：将启动命令添加到 Login Items，或创建 LaunchAgent plist。
会创建 LaunchAgent，登录后自动启动。
Windows：将快捷方式放入 `shell:startup` 文件夹。
---
@@ -56,33 +71,40 @@ openrelay service install
### Q: 怎么连接 Claude Code？
方法一：一键配置
**方法一：Web 面板一键配置（推荐）**
```bash
openrelay config set-app claude-code claude-sonnet-4-6
```
打开 `http://localhost:18765` → **Work** 标签页 → 为 Claude Code 选择 Provider → 开启开关 → **重新打开终端**。
方法二：手动设置环境变量
**方法二：手动设置环境变量**
```bash
export ANTHROPIC_BASE_URL=http://localhost:18765
export ANTHROPIC_API_KEY=unused
```
### Q: 怎么连接 Cursor / Windsurf / Cline？
### Q: 怎么连接 Cursor？
```bash
openrelay config set-app cursor claude-sonnet-4-6
openrelay config set-app windsurf claude-sonnet-4-6
```
打开 `http://localhost:18765` → **IDE** 标签页 → Cursor 区域选择 Provider 和模型 → 点击 **启动**。
或在对应 IDE 的设置中，将 API Base URL 指向 `http://localhost:18765`。
**注意**：启动代理后，**必须通过控制面板的启动按钮打开 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: 怎么查看当前配置？
```bash
openrelay config list
```
打开 Web 面板 `http://localhost:18765`，所有 Provider 状态、连接配置、使用量都在面板中展示。
配置文件位置：`~/.openrelay/config.json`
---
@@ -90,27 +112,24 @@ openrelay config list
### Q: 怎么添加免费 Provider？
```bash
openrelay provider add
```
**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
- **Google AI Studio** — Gemini 系列，免费额度大
- **Cerebras** — 100 万 token/天，Llama 70B
- **Gemini** — 免费额度大，100 万上下文
- **SambaNova** — Llama 405B，200K token/天
- **OpenRouter** — 30+ 免费模型
### Q: 免费配额用完了怎么办？
OpenRelay 会自动切换到下一个可用 Provider（failover）。如果所有 Provider 都限流，等几分钟后会自动恢复。建议多注册几个 Provider，配额叠加更稳。
使用模型组功能（**Custom** 标签页），将多个 Provider 组合在一起。Groq 用完 → 自动切到 Cerebras → 再切 SambaNova。建议多注册几个 Provider，配额叠加更稳。
### Q: 怎么查看各 Provider 状态？
```bash
openrelay provider list
```
或打开 Web 管理面板：`http://localhost:18765`。
打开 Web 面板 `http://localhost:18765`，侧边栏绿点表示已连接。点击任一 Provider 可查看详细状态和配额信息。
---
@@ -120,107 +139,121 @@ openrelay provider list
**这是正常的提示信息，不是错误。**
impit 是可选的 Chrome TLS 指纹模拟库，用于绕过 CloudFlare 的 JA3/JA4 检测。没有它，OpenRelay 会自动降级到原生 fetch，**不影响正常使用**。
impit 是可选的 Chrome TLS 指纹模拟库，用于绕过 CloudFlare 的 JA3/JA4 检测。二进制版本中无法内嵌 impit（含原生 .node 文件），会自动降级到原生 fetch。
不需要手动安装 impit。只有在使用 Claude Desktop provider 时遇到持续 403 错误才需要关注。
如果使用 Claude Desktop Provider 遇到持续 403 错误，可改用 npm 安装方式（`npm install -g openrelay`），impit 会自动安装并启用。
### Q: `connection refused localhost:18765`
OpenRelay 没有运行。启动它：
```bash
openrelay start
./openrelay # macOS
.\openrelay-windows-x64.exe # Windows
```
如果已经启动但仍报错，检查端口是否被占用：
```bash
# macOS
lsof -i :18765
# Windows
netstat -ano | findstr 18765
```
### Q: `401 Unauthorized`
API Key 过期或无效。检查对应 Provider 的 Key：
API Key 过期或无效。打开 Web 面板检查对应 Provider 的连接状态。
```bash
openrelay config list
```
如果是 Claude Code 的 OAuth token 过期：
```bash
claude auth login
```
重新认证后，OpenRelay 会自动读取新 token。
如果是 IDE Provider（Claude Desktop、Kiro 等），尝试打开对应的 IDE 应用让它刷新 Token，然后在 Web 面板中点击「重新连接」。
### Q: `rate limit exceeded`
当前 Provider 配额用完了。OpenRelay 会自动切换到下一个可用 Provider。
当前 Provider 配额用完了。OpenRelay 会自动切换到下一个可用 Provider（如果配置了模型组）。
如果所有 Provider 都限流：
1. 等几分钟后重试
2. 添加更多 Provider：`openrelay provider add`
3. 检查是否有 Provider 的 Key 失效了：`openrelay provider list`
1. 等几分钟后重试（大部分免费配额按分钟/小时重置）
2. 在 Web 面板添加更多 Provider
3. 检查是否有 Provider 的 Key 失效了
### Q: `403 Forbidden`（CloudFlare 拦截）
部分 Provider（如 Claude Desktop）使用 CloudFlare 防护。OpenRelay 会自动刷新 Cookie 并重试。
如果持续 403：
1. 确认 impit 是否已加载（启动日志中查看）
2. 尝试重启 OpenRelay：`openrelay restart`
3. 清除 Cookie 缓存后重试
1. 检查启动日志中 impit 是否已加载
2. 重启 OpenRelay
3. 重新打开 Claude Desktop 让它刷新 Cookie
### Q: `ECONNRESET` 或 `socket hang up`
网络不稳定或 Provider 服务端断开连接。通常是临时问题，OpenRelay 会自动重试。
网络不稳定或 Provider 服务端断开连接。通常是临时问题，重试即可。
如果频繁出现：
1. 检查网络连接
2. 检查是否需要代理（`openrelay config set proxy http://...`）
3. 切换到其他 Provider
2. 如果使用代理（Clash 等），将 Provider 域名加入直连规则
3. 在 Web 面板切换到其他 Provider
### Q: 启动时报 `EADDRINUSE`
端口 18765 已被占用。可能是另一个 OpenRelay 实例在运行：
端口 18765 已被占用。可能是另一个 OpenRelay 实例在运行。
```bash
openrelay status
# 如果显示已运行，不需要再次启动
# macOS — 查找占用进程
lsof -i :18765
kill <PID>
# 如果要强制重启
openrelay restart
# 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 已启动且模型名称正确：
确认 OpenRelay 已启动并检查可用模型：
```bash
openrelay status
curl http://localhost:18765/v1/models
```
确保环境变量设置正确（`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）。
确保环境变量设置正确。最简单的方法：在 Web 面板 **Work** 标签页中配置，然后重新打开终端。
### Q: Cursor 连不上 OpenRelay
1. 确认 OpenRelay 已启动：`openrelay status`
2. 在 Cursor Settings → Models 中设置：
- API Base URL: `http://localhost:18765/v1`
- API Key: `unused`（任意值即可）
3. 测试连接：`curl http://localhost:18765/v1/models`
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）比小模型慢
1. 检查当前使用的 Provider 和模型 — 大模型（如 405B）比小模型慢
2. 切换到速度更快的 Provider（Groq、Cerebras 速度最快）
3. 检查网络延迟（`ping` 对应 Provider 的域名）
3. 检查网络延迟
### Q: 数据存在哪里？
配置文件：`~/.openrelay/config.json`
日志输出到启动 OpenRelay 的终端窗口（stdout），仅包含错误信息和请求元数据（Provider、模型、状态码），**不含消息内容或凭据**。
删除所有数据：`rm -rf ~/.openrelay/`
---