From f1b07ee1c5a8465aaa28dee796b5a860ddf1090b Mon Sep 17 00:00:00 2001 From: romgX <156889089+romgX@users.noreply.github.com> Date: Thu, 12 Mar 2026 01:45:37 +0800 Subject: [PATCH] v0.8.7 --- faq-en.md | 189 ++++++++++++++++++++++++++++++--------------------- faq.md | 197 +++++++++++++++++++++++++++++++----------------------- 2 files changed, 227 insertions(+), 159 deletions(-) diff --git a/faq-en.md b/faq-en.md index ebb57f6..368f696 100644 --- a/faq-en.md +++ b/faq-en.md @@ -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 -# To force restart -openrelay restart +# Windows +netstat -ano | findstr 18765 +taskkill /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/` --- diff --git a/faq.md b/faq.md index 341c30d..d5a2323 100644 --- a/faq.md +++ b/faq.md @@ -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 -# 如果要强制重启 -openrelay restart +# Windows +netstat -ano | findstr 18765 +taskkill /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/` ---