A AstraRelay FIELD MANUAL / 使用教程

ASTRARELAY / 操作手册 01

AstraRelay
使用教程。

从第一步开始,把接入做对。这里包含注册、充值、Key、分组模型、CC Switch 官方下载与配置、各类开发工具、手动配置和直接 API 调用;重要操作都配有真实界面图或可复制示例。

公开页面 真实截图 跟随站点主题
READ IN ORDER 01—10 注册 / Key / 模型 / 协议 / 工具 / 排错

00 / CONTACT

遇到问题,先把信息带齐

群内主要用于教程更新和配置交流。需要人工确认时,请同时提供客户端名称、模型、Base URL 和报错截图。

微信群 扫码加入交流 教程更新 / 配置交流
QQ群 扫码加入交流 电脑端截图 / 远程说明
微信客服 Reyant03 充值 / Key / 客户端配置
QQ 客服 2485682995 适合电脑端截图和远程说明

START HERE

先记住这条路线

不要一上来改配置文件。先让账号、Key、协议三件事对上,再进入客户端。

先看这里

API Key 和模型必须属于同一分组。GPT/Codex 常用 `/v1`,Claude Code 的 Anthropic Messages 地址不要加 `/v1`。

01 / ACCOUNT

注册账号

打开官网,完成注册或第三方登录。登录后先确认自己已经进入控制台,而不是停在登录页。

01

打开 AstraRelay,找到登录 / 注册入口

访问 https://astra-relay.com。在首页中央区域选择注册或登录。

下一步:创建账号
图 01 先确认站点地址,再进入注册流程。
02

创建 AstraRelay 账号

可以使用邮箱注册,也可以按页面提供的第三方登录方式继续。邮箱注册按提示完成验证。

注意不要把 API Key 当成注册密码,也不要把 Key 发到群里。
下一步:进入控制台
图 02 填写注册信息后,按页面提示完成验证。
03

确认已经进入控制台

登录后先看左侧导航和页面标题。后面的充值、兑换码、Key 管理都从这里进入。

下一章:余额到账
图 03 先认清控制台入口,不要急着填写客户端配置。

02 / BALANCE

充值与兑换

这一步只解决余额到账。已经有兑换码就走兑换入口;需要网站充值就从充值入口进入。

04

找到充值入口

从左侧导航进入充值页面。截图只用于确认入口位置,当前页面显示什么就以当前页面为准。

页面不同如果没有订阅购买按钮,不代表配置错误,按当前控制台状态操作即可。
图 04 先找到充值页面,再按页面提示继续。
05

使用兑换码到账

进入兑换入口,粘贴兑换码并提交。余额到账后,再回到 API Key 管理页面。

下一章:创建 API Key
图 05 输入兑换码后提交,确认余额已经到账。

03 / API KEY

创建 API Key

Key 决定你能调用哪个分组。先进入 Key 管理,再创建、选择分组、保存。

06

进入 API Key 管理

从左侧导航打开 API Key / 密钥管理页面,确认自己在 Key 列表,而不是调用记录页面。

图 06 先确认页面标题,再点击新建 Key。
07

填写名称并选择分组

名称可以写成你自己能认出的用途,例如 CodexClaude Code。然后打开分组选择。

安全创建成功后,完整 Key 通常只在首次出现时显示,请立即复制并妥善保存。
图 07 先给 Key 起一个能看懂的名字,再选择分组。
08

按模型用途选对分组

选择与模型和协议匹配的分组。GPT、Claude、DeepSeek、Gemini 不要混着猜,先按第 04 章的表核对。

不要选错GLM 仍处于测试状态,本教程不把它作为稳定使用选项。
下一章:查看分组与模型
图 08 分组选择决定后面该使用哪种协议和模型名。

04 / GROUPS & MODELS

先选对分组,再复制模型名

Key 绑定的分组决定可用模型和协议。模型写进客户端不代表 Key 自动获得权限,先按用途选分组,再从下面复制模型名。

Key 分组常用模型首选协议适合场景
Gpt plus gpt-5.5gpt-5.4gpt-5.4-minigpt-image-2 OpenAI Responses 日常 Codex、GPT 文本与图片
Gpt pro Plus 全部;gpt-5.5-progpt-5.4-progpt-5.6-sol / terra / luna OpenAI Responses GPT Pro 与 GPT 5.6
GPT 订阅 GPT Pro、GPT 5.6、gpt-image-2 OpenAI Responses 套餐已经生效时使用
Gemini gemini-3-flash-previewgemini-3-pro-previewgemini-3.1-pro-preview 及图片模型 Gemini 原生 Gemini 文本与图片共用一把 Key
Claude claude-opus-4-8claude-sonnet-5claude-fable-5claude-haiku-4-5 Anthropic Messages Claude Code、Cline、Hermes
Deepseek deepseek-v4-prodeepseek-v4-flash,也支持 Claude 别名 Anthropic Messages Claude Code、Agent、网关工具
不知道选哪个分组时,按这 6 条判断
  1. 普通 Codex、GPT 文本或 gpt-image-2,先用 Gpt plus
  2. 需要 GPT Pro 或 GPT 5.6,改用 Gpt pro;Plus Key 调 GPT 5.6 会报 model not found。
  3. 只有套餐已经购买并生效时,才把 Key 绑定到 GPT 订阅。当前看不到公开购买入口属于正常状态。
  4. Gemini 文本和图片统一使用 Gemini,不再单独建图片 Key。
  5. Claude Code 跑原生 Claude 用 Claude;跑 DeepSeek 用 Deepseek
  6. GLM【测试中】不作为本教程的稳定使用选项。
DeepSeek 使用 Claude 别名时怎么路由

claude-opus-*claude-fable-* 映射到 deepseek-v4-proclaude-sonnet-*claude-haiku-* 映射到 deepseek-v4-flash

客户端显示的是请求别名时,最终走到哪个模型要以 AstraRelay 控制台的调用记录为准。

05 / ROUTING

先确认协议,再填写地址

最常见的错误不是 Key 本身,而是把所有工具都填成同一个 Base URL。按协议看这一张表。

用途协议Base URL常见工具
GPT / Codex OpenAI Responses https://astra-relay.com/v1 Codex、OpenCode、GPT OpenClaw
原生 Claude Anthropic Messages https://astra-relay.com Claude Code、Cline、Hermes
DeepSeek Messages / Responses 兼容 https://astra-relay.com Claude Code、Agent、网关工具
Gemini Gemini 原生 https://astra-relay.com Gemini CLI、Gemini API 客户端
不要一律加

Claude Code 的 Anthropic Messages 地址填站点根地址,不要加 /v1

不要重复

如果客户端会自动补 /v1,就不要再手动写成 /v1/v1

完整端点速查:Base URL 和请求 URL 不要混
接口完整请求 URL用途
OpenAI Responseshttps://astra-relay.com/v1/responsesGPT 主接口;Codex、Agent、OpenClaw
OpenAI Chat 兼容https://astra-relay.com/v1/chat/completions只支持 Chat Completions 的传统客户端
OpenAI Imageshttps://astra-relay.com/v1/images/generationsgpt-image-2
Anthropic Messageshttps://astra-relay.com/v1/messagesClaude、DeepSeek、GPT Messages 兼容
Gemini 原生https://astra-relay.com/v1beta/models/{model}:generateContentGemini 文本与图片

新配置优先使用 Responses;只有客户端明确只支持 Chat Completions 时,才使用 Chat 兼容入口。

06 / CC SWITCH

用 CC Switch 接入工具

先从官方地址安装 CC Switch,再按目标工具添加供应商。每个工具要使用与自身协议对应的供应商,不能把 Codex 的 OpenAI 配置直接套给 Claude Code。

DOWNLOAD / 官方下载

先安装 CC Switch,再继续看下面的截图

只从官方文档或官方 GitHub 下载。进入 Releases 后展开最新版本的 Assets,选择与你系统相符的安装包。

  1. Windows:在 Releases 的 Assets 中选择 Windows 安装包;安装后从开始菜单打开。
  2. macOS:选择对应芯片架构的 macOS 安装包;首次打开若被拦截,按系统安全提示确认来源。
  3. Linux:选择发行版支持的安装包;无法使用桌面程序时,跳到第 07 章手动配置。
目标工具 / 用途供应商类型Key 分组Base URL
Codex / OpenCode / GPT OpenClawOpenAI Compatible / ResponsesGpt plus / Gpt pro / 订阅https://astra-relay.com/v1
Claude Code 跑原生 ClaudeAnthropic Messages(原生)Claudehttps://astra-relay.com
Claude Code 跑 DeepSeekAnthropic Messages(原生)Deepseekhttps://astra-relay.com
Claude Code 跑 GPT 兼容Anthropic Messages(原生)GPT 分组https://astra-relay.com
Gemini CLIGemini 原生Geminihttps://astra-relay.com
09

打开 CC Switch,先认清工具标签

顶部或侧边的标签对应不同工具。右上角的加号用于新增供应商,列表里会显示当前服务商状态。

图 09 先切到目标工具,再新增对应供应商。
10

点击加号,添加自定义服务商

选择自定义供应商或兼容类型。不要把 Codex 的 OpenAI 配置直接当成 Claude Code 的供应商。

图 10 这一步只做一件事:进入正确的供应商配置页面。
11

填写 AstraRelay 的 OpenAI 兼容供应商

给 Codex、OpenCode 或 GPT OpenClaw 使用时,供应商类型选 OpenAI Compatible / Responses。

填写示例
名称:     AstraRelay
Base URL: https://astra-relay.com/v1
API Key:  sk-你的密钥
图 11 OpenAI 兼容路线使用 /v1 地址。
12

回到 Codex 页面,启用 AstraRelay

保存供应商后,回到 Codex 标签页,选中 AstraRelay 并启用。看到“使用中”即可确认切换状态。

图 12 Codex 看服务商行是否显示为“使用中”。
13

Claude Code 先添加 Claude 供应商

这是 Claude Code 的独立配置步骤:供应商类型选 Anthropic Messages(原生),地址填写站点根地址,不加 /v1

顺序不能反先保存 Claude 供应商,再回到 Claude Code 标签页切换。
图 13 Claude Code 的供应商配置和 Codex 不是同一种类型。
14

回到 Claude Code 页面切换并测试

保存上一张图的供应商后,回到 Claude Code 标签页,选择 AstraRelay 并启用。

查询失败不影响启用页面显示“查询失败”时,先看启用开关状态。需要主动测试连接,点击“启用”右边第三个图标。
下一章:没有 CC Switch 时怎么办
图 14 启用看开关;测试连接点启用右边第三个图标。

07 / MANUAL

没有 CC Switch 时,手动配置

手动配置适合服务器、无图形界面或排查真实请求地址。日常使用仍然建议优先使用上面的图形化流程。

CLAUDE CODEAnthropic Messages

Windows PowerShell:

环境变量
setx ANTHROPIC_BASE_URL "https://astra-relay.com"
setx ANTHROPIC_AUTH_TOKEN "sk-你的密钥"

macOS / Linux 写入 ~/.zshrc~/.bashrc

shell 环境变量
export ANTHROPIC_BASE_URL="https://astra-relay.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"
Windows 执行后重开终端;macOS / Linux 执行 source ~/.zshrc 或重开终端,再运行 claude
CODEX CLIOpenAI Responses

先安装 Codex CLI:

安装
npm i -g @openai/codex

配置文件:~/.codex/config.toml,Windows 对应当前用户目录下的 .codex 文件夹。

config.toml
model = "gpt-5.4"
model_provider = "astrarelay"

[model_providers.astrarelay]
name = "AstraRelay"
base_url = "https://astra-relay.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
requires_openai_auth = true

Windows PowerShell 设置 Key:

API Key
setx OPENAI_API_KEY "sk-你的密钥"
重开终端后在项目目录运行 codex。要用 GPT 5.6,先把 Key 换到 Gpt pro,再修改 model
OTHER TOOLSOpenCode / OpenClaw / Hermes

先按模型分组选择协议,再填写 Base URL、Key 和模型名。OpenAI Responses 路线使用 https://astra-relay.com/v1;Claude / DeepSeek 原生 Messages 路线使用 https://astra-relay.com

OpenCodeOpenClawHermes AgentClineRoo Code
不同版本的字段名称可能不同,看到 API Host、Endpoint 或 Base URL 时,按协议表填写对应地址。
Claude Code 的三种 Key 应该怎么选
目标Key 分组请求与模型
原生 ClaudeClaudeAnthropic Messages;直接使用 claude-sonnet-5 等模型名
DeepSeekDeepseekAnthropic Messages;使用 DeepSeek 模型名或 Claude 别名
GPT 兼容Gpt plus / Gpt pro / 有效订阅Anthropic Messages 兼容;Opus / Sonnet / Haiku 映射到 GPT
手动配置后如何确认真的走了 AstraRelay
  1. 彻底关闭旧终端、编辑器和相关后台进程,再重新打开。
  2. 发送一条很短的测试请求,避免第一次排查就跑长任务。
  3. 到 AstraRelay 控制台的调用记录查看请求时间、Key、分组、最终模型和状态码。
  4. 如果客户端仍请求官方地址,优先检查环境变量、model_providerbase_url

08 / CLIENTS & PLUGINS

插件、编辑器和聊天客户端

CC Switch 能管理的工具优先走第 06 章。下面保留插件和客户端的手动入口,字段名称不同不要紧,核心始终是协议、Base URL、Key 和模型名。

Codex 插件:VS Code / Cursor / Trae
  1. 先按第 07 章完成 Codex CLI 的 config.tomlOPENAI_API_KEY
  2. 在 VS Code、Cursor 或 Trae 的扩展市场搜索 Codex 并安装。
  3. 彻底重启编辑器,让插件重新读取 ~/.codex/ 的配置和登录状态。
  4. 打开左侧 Codex 面板发送短请求,再到 AstraRelay 调用记录核对模型和状态码。

gpt-5.4 有时不会显示在插件下拉框里;只要 config.toml 已指定,实际请求仍可按配置发送。

Cline / Roo Code / Kilo Code:OpenAI 兼容填法
字段填写内容
API ProviderOpenAI Compatible
Base URL / API Hosthttps://astra-relay.com/v1
API Keysk-你的密钥
Model IDPlus:gpt-5.5 / gpt-5.4 / gpt-5.4-mini;Pro 可再用 GPT 5.6

不同版本可能把输入框叫作 API Host、Endpoint 或 API Address,本质都是同一个 Base URL。

Cursor:覆盖 OpenAI Base URL
  1. 打开 Settings → Models
  2. 开启 Override OpenAI Base URL
  3. OpenAI API Key 填 sk-你的密钥,OpenAI Base URL 填 https://astra-relay.com/v1
  4. 点击 Verify,再添加当前 Key 分组允许的模型。

Cursor 的 Base URL 覆盖通常是全局生效的。如果还要保留官方 OpenAI 连接,请分开配置或使用不同环境。

ChatBox / NextChat / Cherry Studio
字段填写内容
API 类型OpenAI / OpenAI Compatible
API Hosthttps://astra-relay.com
API Path/v1/chat/completions
API Keysk-你的密钥
Model选择当前 GPT Key 分组允许的模型

如果客户端只提供一个 Base URL 输入框,直接填 https://astra-relay.com/v1。Cherry Studio 官方下载:www.cherry-ai.com ↗

OpenCode:手动 provider 配置

配置文件:macOS / Linux 为 ~/.config/opencode/opencode.json,Windows 为 %USERPROFILE%\.config\opencode\opencode.json

opencode.json
{
  "provider": {
    "astrarelay": {
      "npm": "@ai-sdk/openai",
      "name": "AstraRelay",
      "options": { "baseURL": "https://astra-relay.com/v1" },
      "models": {
        "gpt-5.5": { "name": "GPT-5.5", "thinking": true },
        "gpt-5.4": { "name": "GPT-5.4", "thinking": true },
        "gpt-5.4-mini": { "name": "GPT-5.4 Mini" },
        "gpt-5.6-sol": { "name": "GPT-5.6 Sol", "thinking": true },
        "gpt-5.6-terra": { "name": "GPT-5.6 Terra", "thinking": true },
        "gpt-5.6-luna": { "name": "GPT-5.6 Luna", "thinking": true }
      }
    }
  }
}
  1. 在 OpenCode 执行 /connect,选择自定义服务商并输入 Key;也可以执行 opencode auth login
  2. 重启 OpenCode,选择 astrarelay/gpt-5.4 或其他已授权模型。
  3. GPT 5.6 需要 Gpt pro 或有效订阅 Key,写进配置不等于自动获得权限。
OpenClaw / Hermes:按协议选择上游
分组协议Base URL
GPTopenai-responseshttps://astra-relay.com/v1
Claudeanthropic-messageshttps://astra-relay.com
DeepSeekanthropic-messages;也可用 Responses 兼容https://astra-relay.com
GeminiGemini 原生https://astra-relay.com
Hermes 上游示例
GPT:
  base_url = https://astra-relay.com/v1
  api_key  = sk-你的密钥
  model    = gpt-5.4

Claude / DeepSeek:
  base_url = https://astra-relay.com
  api_key  = sk-你的密钥
  protocol = anthropic-messages

如果下游连接的是 Hermes 本地 API Server,下游填写 Hermes 的本地地址,再由 Hermes 转到 AstraRelay。

09 / DIRECT API

代码中直接调用

下面所有示例都使用占位 Key。先创建对应分组的 Key,再替换 sk-你的密钥;请求成功后仍要到调用记录核对最终模型和费用。

GPT:OpenAI Responses(新项目首选)
curl
curl https://astra-relay.com/v1/responses \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "写一个 Python hello world"
  }'
Python
from openai import OpenAI

client = OpenAI(
    base_url="https://astra-relay.com/v1",
    api_key="sk-你的密钥",
)

response = client.responses.create(
    model="gpt-5.4",
    input="写一个 Python hello world",
)
print(response.output_text)
GPT:Chat Completions 兼容入口
curl
curl https://astra-relay.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Chat 是兼容入口,GPT 请求会转到 Responses 处理;能使用 Responses 的新项目优先使用上一项。

Claude / DeepSeek:Anthropic Messages
Claude
curl https://astra-relay.com/v1/messages \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
DeepSeek
curl https://astra-relay.com/v1/messages \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "解释这段代码"}]
  }'
Gemini 原生与 GPT 图片
Gemini
curl "https://astra-relay.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: sk-你的密钥" \
  -H "content-type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Hello"}]
    }]
  }'
GPT Image
curl https://astra-relay.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a clean product photo on a white background"
  }'

10 / TROUBLESHOOTING

常见排错

先按现象定位,不要同时改 Key、模型、Base URL 和客户端配置。

401 / invalid api key+

检查 API Key 是否完整、是否复制了多余空格,以及 Key 是否已经被删除或禁用。

402 / Insufficient Balance+

确认余额已经到账,并检查当前 Key 绑定的分组是否和你选择的模型一致。

429 / 请求太频繁+

先降低并发或等待一段时间,再检查是否有多个客户端同时使用同一把 Key。

model not found+

模型名必须来自当前控制台可见模型列表,并且要和 Key 分组匹配。不要直接猜模型名。

Base URL 要不要加 /v1?+

GPT / Codex 常用 https://astra-relay.com/v1;Claude Code 的 Anthropic Messages 使用 https://astra-relay.com,不要加 /v1

Claude Code 显示“查询失败”+

这不影响启用。先看 AstraRelay 的启用开关是否成功;要测试连接,点击“启用”右边第三个图标。

为什么看不到订阅购买按钮?+

当前公开订阅购买开关处于关闭状态,所以没有入口属于正常情况。普通余额与订阅套餐是两套状态,不要混着判断。

如何确认请求实际走了哪个模型?+

到控制台调用记录查看请求时间、Key、分组、最终模型、输入 / 输出 / 缓存 tokens、费用和状态码。不要只看客户端显示的模型别名。

同一模型为什么有时快、有时慢?+

速度受上游负载、提示词长度、输出长度、推理强度和客户端并发影响。先看状态码和调用记录;有成功记录但响应慢,通常不是 Key 失效。

支持流式响应和多设备吗?+

支持流式响应。多设备可以共用 Key,但总并发不能超过 Key 上限;为了便于撤销和查账,更建议一个客户端使用一把独立 Key。

联系客服前要准备什么?+

准备客户端完整报错截图、控制台同一时间的调用记录截图,并说明客户端名称、Key 分组、模型名和 Base URL 填法。

NEED HUMAN HELP? 带上两张图,问题会快很多。

客户端报错截图 + AstraRelay 调用记录截图,再附上客户端名称和模型名。

查看联系方式