OPERATOR MANUAL / REV 01
接入手册。
从兑换额度到第一次响应,一步一步完成。
兑换码充值
- 从本站购买按钮进入发卡网,核对商户、面额、兑换规则及售后政策后付款。
- 保存订单号与兑换码;登录中转站控制台,在「钱包 / 充值」中找到兑换入口(名称随版本变化)。
- 粘贴兑换码并提交一次。若响应超时,先检查余额与充值记录,避免重复提交。
- 进入「令牌」创建 API Key,设置适当额度、模型权限与分组。兑换码不是 API Key。
购买后请在当前站点绑定的控制台兑换;不要向任何人发送完整密钥。
配置本机环境
在首页复制对应系统的命令。脚本下载后先审阅,再运行;输入 Key 时不会回显。验证成功后写入以下变量:
ANTHROPIC_BASE_URL=https://api.hoverrelay.xyz
ANTHROPIC_API_KEY=<你的中转站 Key>
OPENAI_BASE_URL=https://api.hoverrelay.xyz/v1
OPENAI_API_KEY=<你的中转站 Key>macOS/Linux 写入权限为 600 的用户配置文件,并在 .bashrc / .zshrc 引用;Windows 写入用户级环境变量。重启终端和 IDE,勿打印 Key 或将其提交到代码仓库。
卸载:删除 shell 配置中的 relay-managed-env 行和 ~/.config/relay/env.sh(自定义 XDG_CONFIG_HOME 时使用对应路径);Windows 在用户环境变量中删除这四项。需要恢复旧供应商时重新填写原配置。
Claude Code
- 先按 Claude Code 官方指南安装 CLI。
- 运行一键脚本并打开新终端。确认 ANTHROPIC_BASE_URL 是网关根地址,不带 /v1。若存在旧 ANTHROPIC_AUTH_TOKEN,请移除冲突项。
- 从控制台确认已开通的 Claude 模型 ID。网关必须支持 /v1/messages、工具调用和流式响应。
- 在项目目录运行下方命令,将模型 ID 替换为实际值;发送一条短消息后核对控制台用量。
claude --model REPLACE_WITH_AVAILABLE_CLAUDE_MODEL_ID运行后安全输入 API Key;请勿将密钥粘贴到网页。缓存依赖相同前缀、模型及有效期;切换上游可能丢失缓存。CLI 环境变量配置不保证桌面应用继承。参考 官方网关兼容文档。
Codex
- 按 官方说明安装 Codex CLI;运行安装脚本设置 OPENAI_API_KEY。
- 备份并编辑 ~/.codex/config.toml(Windows 为 %USERPROFILE%\\.codex\\config.toml),合并以下配置,避免重复表或顶层字段。
- 将模型 ID 替换为控制台提供且支持 Responses API 的模型。仅设置 OPENAI_BASE_URL 不代表已切换 Codex 的 provider。
model_provider = "relay"
model = "REPLACE_WITH_AVAILABLE_MODEL_ID"
[model_providers.relay]
name = "Relay Gateway"
base_url = "https://api.hoverrelay.xyz/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"运行后安全输入 API Key;请勿将密钥粘贴到网页。在新终端运行 codex,检查当前 provider 后发送测试请求。网关需要实际支持 /v1/responses;模型列表成功不代表此接口可用。参考 OpenAI 官方自定义 provider 配置。
Cline
- 安装 Cline,进入设置,API Provider 选择「OpenAI Compatible」。
- Base URL 填
https://api.hoverrelay.xyz/v1,API Key 填中转站 Key,Model ID 填控制台的精确模型名。 - 按模型实际能力设置上下文窗口、最大输出、图片和工具调用;不能仅凭系列名称开启全部能力。
- 保存后发送简短测试消息,核对控制台用量,再执行代码任务。
Cline 的配置界面通常需要单独填写,不保证自动读取这四个环境变量。以 Cline 官方配置说明为准。
先定位,再重试。
| 现象 | 可能原因 | 排查动作 |
|---|---|---|
| 401 / invalid_api_key | 密钥错误、已禁用或仍在使用旧认证 | 在控制台重建 Key;重启终端和 IDE;检查是否残留 ANTHROPIC_AUTH_TOKEN 或旧登录配置。 |
| 403 / forbidden | 分组权限或来源限制 | 检查 Key 的模型白名单、分组和 IP 限制;检查边缘防火墙。 |
| 404 / model_not_found | 模型名不一致或路径重复 | 从 /v1/models 复制精确 ID;Claude Base URL 不加 /v1,OpenAI 兼容地址加一次 /v1。 |
| 429 / quota / rate_limit | 余额不足或并发达到限额 | 先查账单与余额,再降低并发;按 Retry-After 退避,不要连续重试。 |
| 502 / 503 / 504 | 上游不可用或超时 | 保留请求 ID 与时间;检查渠道健康和网关日志。避免盲目重放可能已计费的请求。 |
| 流式输出中断 | CDN、客户端或上游空闲超时 | 检查各层超时和流式支持;Nginx 600s 并不能覆盖 Cloudflare 或上游自身的限制。 |
| 变量设置后仍未生效 | 旧进程继承旧环境 | 关闭并重新打开终端和整个 IDE;macOS GUI 应用可能不继承 shell 变量。 |
| PowerShell 禁止执行脚本 | 本机执行策略阻止下载文件 | 先审阅脚本,再使用 Unblock-File .\relay-install.ps1;企业策略请遵循管理员要求,不永久降低执行策略。 |
提交问题时提供时间、请求 ID、状态码和脱敏后的模型名。不要发送完整 Key、兑换码、聊天内容或未经脱敏的日志。