OPERATOR MANUAL / REV 01

接入手册。

从兑换额度到第一次响应,一步一步完成。

01 / BALANCE

兑换码充值

  1. 从本站购买按钮进入发卡网,核对商户、面额、兑换规则及售后政策后付款。
  2. 保存订单号与兑换码;登录中转站控制台,在「钱包 / 充值」中找到兑换入口(名称随版本变化)。
  3. 粘贴兑换码并提交一次。若响应超时,先检查余额与充值记录,避免重复提交。
  4. 进入「令牌」创建 API Key,设置适当额度、模型权限与分组。兑换码不是 API Key。
购买后请在当前站点绑定的控制台兑换;不要向任何人发送完整密钥。
02 / ENVIRONMENT

配置本机环境

在首页复制对应系统的命令。脚本下载后先审阅,再运行;输入 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 在用户环境变量中删除这四项。需要恢复旧供应商时重新填写原配置。

03 / ANTHROPIC MESSAGES

Claude Code

  1. 先按 Claude Code 官方指南安装 CLI。
  2. 运行一键脚本并打开新终端。确认 ANTHROPIC_BASE_URL 是网关根地址,不带 /v1。若存在旧 ANTHROPIC_AUTH_TOKEN,请移除冲突项。
  3. 从控制台确认已开通的 Claude 模型 ID。网关必须支持 /v1/messages、工具调用和流式响应。
  4. 在项目目录运行下方命令,将模型 ID 替换为实际值;发送一条短消息后核对控制台用量。
Claude Code 启动命令
claude --model REPLACE_WITH_AVAILABLE_CLAUDE_MODEL_ID
运行后安全输入 API Key;请勿将密钥粘贴到网页。

缓存依赖相同前缀、模型及有效期;切换上游可能丢失缓存。CLI 环境变量配置不保证桌面应用继承。参考 官方网关兼容文档。

04 / OPENAI RESPONSES

Codex

  1. 按 官方说明安装 Codex CLI;运行安装脚本设置 OPENAI_API_KEY。
  2. 备份并编辑 ~/.codex/config.toml(Windows 为 %USERPROFILE%\\.codex\\config.toml),合并以下配置,避免重复表或顶层字段。
  3. 将模型 ID 替换为控制台提供且支持 Responses API 的模型。仅设置 OPENAI_BASE_URL 不代表已切换 Codex 的 provider。
config.toml
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 配置。

05 / OPENAI COMPATIBLE

Cline

  1. 安装 Cline,进入设置,API Provider 选择「OpenAI Compatible」。
  2. Base URL 填 https://api.hoverrelay.xyz/v1,API Key 填中转站 Key,Model ID 填控制台的精确模型名。
  3. 按模型实际能力设置上下文窗口、最大输出、图片和工具调用;不能仅凭系列名称开启全部能力。
  4. 保存后发送简短测试消息,核对控制台用量,再执行代码任务。

Cline 的配置界面通常需要单独填写,不保证自动读取这四个环境变量。以 Cline 官方配置说明为准。

06 / DIAGNOSTICS

先定位,再重试。

现象可能原因排查动作
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、兑换码、聊天内容或未经脱敏的日志。