打开 AstraRelay,找到登录 / 注册入口
访问 https://astra-relay.com。在首页中央区域选择注册或登录。
ASTRARELAY / 操作手册 01
从第一步开始,把接入做对。这里包含注册、充值、Key、分组模型、CC Switch 官方下载与配置、各类开发工具、手动配置和直接 API 调用;重要操作都配有真实界面图或可复制示例。
00 / CONTACT
群内主要用于教程更新和配置交流。需要人工确认时,请同时提供客户端名称、模型、Base URL 和报错截图。
START HERE
不要一上来改配置文件。先让账号、Key、协议三件事对上,再进入客户端。
API Key 和模型必须属于同一分组。GPT/Codex 常用 `/v1`,Claude Code 的 Anthropic Messages 地址不要加 `/v1`。
01 / ACCOUNT
打开官网,完成注册或第三方登录。登录后先确认自己已经进入控制台,而不是停在登录页。
访问 https://astra-relay.com。在首页中央区域选择注册或登录。
可以使用邮箱注册,也可以按页面提供的第三方登录方式继续。邮箱注册按提示完成验证。
登录后先看左侧导航和页面标题。后面的充值、兑换码、Key 管理都从这里进入。
02 / BALANCE
这一步只解决余额到账。已经有兑换码就走兑换入口;需要网站充值就从充值入口进入。
从左侧导航进入充值页面。截图只用于确认入口位置,当前页面显示什么就以当前页面为准。
进入兑换入口,粘贴兑换码并提交。余额到账后,再回到 API Key 管理页面。
03 / API KEY
Key 决定你能调用哪个分组。先进入 Key 管理,再创建、选择分组、保存。
从左侧导航打开 API Key / 密钥管理页面,确认自己在 Key 列表,而不是调用记录页面。
名称可以写成你自己能认出的用途,例如 Codex 或 Claude Code。然后打开分组选择。
选择与模型和协议匹配的分组。GPT、Claude、DeepSeek、Gemini 不要混着猜,先按第 04 章的表核对。
04 / GROUPS & MODELS
Key 绑定的分组决定可用模型和协议。模型写进客户端不代表 Key 自动获得权限,先按用途选分组,再从下面复制模型名。
| Key 分组 | 常用模型 | 首选协议 | 适合场景 |
|---|---|---|---|
| Gpt plus | gpt-5.5、gpt-5.4、gpt-5.4-mini、gpt-image-2 |
OpenAI Responses | 日常 Codex、GPT 文本与图片 |
| Gpt pro | Plus 全部;gpt-5.5-pro、gpt-5.4-pro、gpt-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-preview、gemini-3-pro-preview、gemini-3.1-pro-preview 及图片模型 |
Gemini 原生 | Gemini 文本与图片共用一把 Key |
| Claude | claude-opus-4-8、claude-sonnet-5、claude-fable-5、claude-haiku-4-5 |
Anthropic Messages | Claude Code、Cline、Hermes |
| Deepseek | deepseek-v4-pro、deepseek-v4-flash,也支持 Claude 别名 |
Anthropic Messages | Claude Code、Agent、网关工具 |
gpt-image-2,先用 Gpt plus。claude-opus-* 与 claude-fable-* 映射到 deepseek-v4-pro;claude-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。
| 接口 | 完整请求 URL | 用途 |
|---|---|---|
| OpenAI Responses | https://astra-relay.com/v1/responses | GPT 主接口;Codex、Agent、OpenClaw |
| OpenAI Chat 兼容 | https://astra-relay.com/v1/chat/completions | 只支持 Chat Completions 的传统客户端 |
| OpenAI Images | https://astra-relay.com/v1/images/generations | gpt-image-2 |
| Anthropic Messages | https://astra-relay.com/v1/messages | Claude、DeepSeek、GPT Messages 兼容 |
| Gemini 原生 | https://astra-relay.com/v1beta/models/{model}:generateContent | Gemini 文本与图片 |
新配置优先使用 Responses;只有客户端明确只支持 Chat Completions 时,才使用 Chat 兼容入口。
06 / CC SWITCH
先从官方地址安装 CC Switch,再按目标工具添加供应商。每个工具要使用与自身协议对应的供应商,不能把 Codex 的 OpenAI 配置直接套给 Claude Code。
DOWNLOAD / 官方下载
只从官方文档或官方 GitHub 下载。进入 Releases 后展开最新版本的 Assets,选择与你系统相符的安装包。
| 目标工具 / 用途 | 供应商类型 | Key 分组 | Base URL |
|---|---|---|---|
| Codex / OpenCode / GPT OpenClaw | OpenAI Compatible / Responses | Gpt plus / Gpt pro / 订阅 | https://astra-relay.com/v1 |
| Claude Code 跑原生 Claude | Anthropic Messages(原生) | Claude | https://astra-relay.com |
| Claude Code 跑 DeepSeek | Anthropic Messages(原生) | Deepseek | https://astra-relay.com |
| Claude Code 跑 GPT 兼容 | Anthropic Messages(原生) | GPT 分组 | https://astra-relay.com |
| Gemini CLI | Gemini 原生 | Gemini | https://astra-relay.com |
顶部或侧边的标签对应不同工具。右上角的加号用于新增供应商,列表里会显示当前服务商状态。
选择自定义供应商或兼容类型。不要把 Codex 的 OpenAI 配置直接当成 Claude Code 的供应商。
给 Codex、OpenCode 或 GPT OpenClaw 使用时,供应商类型选 OpenAI Compatible / Responses。
名称: AstraRelay
Base URL: https://astra-relay.com/v1
API Key: sk-你的密钥
/v1 地址。保存供应商后,回到 Codex 标签页,选中 AstraRelay 并启用。看到“使用中”即可确认切换状态。
这是 Claude Code 的独立配置步骤:供应商类型选 Anthropic Messages(原生),地址填写站点根地址,不加 /v1。
保存上一张图的供应商后,回到 Claude Code 标签页,选择 AstraRelay 并启用。
07 / MANUAL
手动配置适合服务器、无图形界面或排查真实请求地址。日常使用仍然建议优先使用上面的图形化流程。
Windows PowerShell:
setx ANTHROPIC_BASE_URL "https://astra-relay.com"
setx ANTHROPIC_AUTH_TOKEN "sk-你的密钥"
macOS / Linux 写入 ~/.zshrc 或 ~/.bashrc:
export ANTHROPIC_BASE_URL="https://astra-relay.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"
source ~/.zshrc 或重开终端,再运行 claude。
先安装 Codex CLI:
npm i -g @openai/codex
配置文件:~/.codex/config.toml,Windows 对应当前用户目录下的 .codex 文件夹。
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:
setx OPENAI_API_KEY "sk-你的密钥"
codex。要用 GPT 5.6,先把 Key 换到 Gpt pro,再修改 model。
先按模型分组选择协议,再填写 Base URL、Key 和模型名。OpenAI Responses 路线使用 https://astra-relay.com/v1;Claude / DeepSeek 原生 Messages 路线使用 https://astra-relay.com。
| 目标 | Key 分组 | 请求与模型 |
|---|---|---|
| 原生 Claude | Claude | Anthropic Messages;直接使用 claude-sonnet-5 等模型名 |
| DeepSeek | Deepseek | Anthropic Messages;使用 DeepSeek 模型名或 Claude 别名 |
| GPT 兼容 | Gpt plus / Gpt pro / 有效订阅 | Anthropic Messages 兼容;Opus / Sonnet / Haiku 映射到 GPT |
model_provider 和 base_url。08 / CLIENTS & PLUGINS
CC Switch 能管理的工具优先走第 06 章。下面保留插件和客户端的手动入口,字段名称不同不要紧,核心始终是协议、Base URL、Key 和模型名。
config.toml 与 OPENAI_API_KEY。~/.codex/ 的配置和登录状态。gpt-5.4 有时不会显示在插件下拉框里;只要 config.toml 已指定,实际请求仍可按配置发送。
| 字段 | 填写内容 |
|---|---|
| API Provider | OpenAI Compatible |
| Base URL / API Host | https://astra-relay.com/v1 |
| API Key | sk-你的密钥 |
| Model ID | Plus:gpt-5.5 / gpt-5.4 / gpt-5.4-mini;Pro 可再用 GPT 5.6 |
不同版本可能把输入框叫作 API Host、Endpoint 或 API Address,本质都是同一个 Base URL。
sk-你的密钥,OpenAI Base URL 填 https://astra-relay.com/v1。Cursor 的 Base URL 覆盖通常是全局生效的。如果还要保留官方 OpenAI 连接,请分开配置或使用不同环境。
| 字段 | 填写内容 |
|---|---|
| API 类型 | OpenAI / OpenAI Compatible |
| API Host | https://astra-relay.com |
| API Path | /v1/chat/completions |
| API Key | sk-你的密钥 |
| Model | 选择当前 GPT Key 分组允许的模型 |
如果客户端只提供一个 Base URL 输入框,直接填 https://astra-relay.com/v1。Cherry Studio 官方下载:www.cherry-ai.com ↗
配置文件:macOS / Linux 为 ~/.config/opencode/opencode.json,Windows 为 %USERPROFILE%\.config\opencode\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 }
}
}
}
}
/connect,选择自定义服务商并输入 Key;也可以执行 opencode auth login。astrarelay/gpt-5.4 或其他已授权模型。| 分组 | 协议 | Base URL |
|---|---|---|
| GPT | openai-responses | https://astra-relay.com/v1 |
| Claude | anthropic-messages | https://astra-relay.com |
| DeepSeek | anthropic-messages;也可用 Responses 兼容 | https://astra-relay.com |
| Gemini | Gemini 原生 | https://astra-relay.com |
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-你的密钥;请求成功后仍要到调用记录核对最终模型和费用。
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"
}'
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)
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 的新项目优先使用上一项。
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"}]
}'
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": "解释这段代码"}]
}'
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"}]
}]
}'
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 和客户端配置。
检查 API Key 是否完整、是否复制了多余空格,以及 Key 是否已经被删除或禁用。
确认余额已经到账,并检查当前 Key 绑定的分组是否和你选择的模型一致。
先降低并发或等待一段时间,再检查是否有多个客户端同时使用同一把 Key。
模型名必须来自当前控制台可见模型列表,并且要和 Key 分组匹配。不要直接猜模型名。
GPT / Codex 常用 https://astra-relay.com/v1;Claude Code 的 Anthropic Messages 使用 https://astra-relay.com,不要加 /v1。
这不影响启用。先看 AstraRelay 的启用开关是否成功;要测试连接,点击“启用”右边第三个图标。
当前公开订阅购买开关处于关闭状态,所以没有入口属于正常情况。普通余额与订阅套餐是两套状态,不要混着判断。
到控制台调用记录查看请求时间、Key、分组、最终模型、输入 / 输出 / 缓存 tokens、费用和状态码。不要只看客户端显示的模型别名。
速度受上游负载、提示词长度、输出长度、推理强度和客户端并发影响。先看状态码和调用记录;有成功记录但响应慢,通常不是 Key 失效。
支持流式响应。多设备可以共用 Key,但总并发不能超过 Key 上限;为了便于撤销和查账,更建议一个客户端使用一把独立 Key。
准备客户端完整报错截图、控制台同一时间的调用记录截图,并说明客户端名称、Key 分组、模型名和 Base URL 填法。