Astra GateEnglish

提供商

添加上游服务商、配置密钥与计费、测试连接

提供商(Provider)是 Astra 的上游入口:一个接口地址 + 一种协议 + 一份凭据。可以同时添加多个——比如同一个 DeepSeek 账号建两个条目用不同倍率,或官方 API 与 OpenRouter 并存。

提供商列表

提供商列表;行内显示协议、模型数与价格表

每行从左到右:

  • 图标与名称 — 点击进入详情;
  • 徽标 — 绑定的客户端(绿色,如「Codex」),「未设置密钥」(橙色)提醒补 Key,「模板更新」表示模板有新版本(GitHub Copilot 订阅的模板会在服务启动时自动更新,你改过的值保持不变);
  • 详情行 — 协议 · 模型数 · 价格表 · 倍率(非 1.0 时显示);
  • 开关 — 临时停用某个提供商(停用后请求不再路由到它)。

添加提供商

点右上角 添加提供商,弹出两步向导:

第一步:选择模板(支持搜索与分类筛选)
  1. 选择模板 — 模板自带接口地址、协议与默认模型列表。分类:官方 / 订阅(OAuth 登录)/ 编程套餐(用 API Key 的 Coding Plan)/ 国内 / 聚合平台 / 推理平台 / 本地。没有匹配的就选「自定义提供商」,手填任意 OpenAI / Anthropic / Gemini 兼容接口;
  2. 填写信息 — 名称、API Key 与价格表;自定义提供商还要填接口(每种协议一个地址,通常以 /v1 结尾)和认证方式。 展开 更多选项 可以在创建时就设置:接口地址(模板的默认地址可改、可增删协议,可设为完整 URL)、上游协议优先级、认证方式、 额外请求头、HTTP 代理、价格倍率、初始模型(留空则用模板自带的模型)和备注。这些创建后都能在详情页「设置」里再改。

从其他应用导入

已经在别的工具里配置过中转或官方 Key?点右上角 从其他应用导入,Astra 会只读扫描本机以下位置并列出可导入的提供商:

来源读取位置
CC Switch~/.cc-switch/cc-switch.db(旧版为 config.json)
Alma系统用户配置目录下 alma/chat_threads.db
Claude Code~/.claude/settings.json(遵循 CLAUDE_CONFIG_DIR)
Codex~/.codex/config.toml(遵循 CODEX_HOME,只读自定义 [model_providers.*] 且带内联 token 的条目)
Magpie~/.config/magpie/providers.json
  • 列表里每一行显示名称、协议与地址、遮掩后的 Key、模型数和状态:新增(默认勾选)、已存在(同地址同 Key,不可选)、同地址(地址相同但 Key 不同,可选并作为新提供商导入)、已停用(来源里已关闭,默认不勾选)、无法导入(附原因);
  • 只读、不修改来源;API Key 由服务端直接读取并加密保存,不经过浏览器,预览里也只有遮掩值;
  • 同一来源里 Key 与主机都相同的多条配置会合并成一个提供商的多个端点;Magpie 里一个提供商的多个 Key 会各导入成一个提供商;
  • 官方登录(Claude / ChatGPT / Copilot 等订阅登录)、路由、限流、余额、会话与用量不会导入;导入不会绑定或改动任何客户端配置,也不会发起上游请求——导入后可用「测试连接」确认。

备份与恢复

右上角 备份与恢复 把提供商和它们的模型导出成一个 JSON 文件(astra-providers-<日期>.json),换机器或重装后可以从这个文件恢复。

导出时选择 API 密钥怎么处理:

选项文件里的密钥限制
不含密钥(默认)没有,导入后需要重新填写任何管理会话都可以导出
用口令加密密钥每个密钥用口令加密(PBKDF2-SHA256 + AES-256-GCM),口令至少 8 个字符,丢失后无法找回只能在本机操作
明文密钥明文,拿到文件的人可以直接使用只能在本机操作,请只存放在你自己保管的位置

文件包含提供商配置(地址、协议、认证方式、额外请求头、代理、价格倍率、设置)和每个模型的覆盖项与启用状态。不包含 OAuth 订阅账号、客户端绑定、令牌、MCP 服务器、插件提供商和「统一网关」提供商。

恢复时选择文件,Astra 先预览:每个提供商显示 新增、地址已存在(地址相同但密钥不同,可选)、已存在,跳过(同地址同密钥)或 无效(附原因)。预览里只有遮掩后的密钥;口令加密的文件要先输入口令才能预览。导入的提供商与现有重名时自动加序号,重复导入同一个文件不会产生重复的提供商。

模型列表里可以多选后点 移除所选,一次删除多个模型。

云端备份(WebDAV)

同一个窗口里还可以把备份放到你自己的 WebDAV 服务(Nextcloud、坚果云等):填写服务地址、用户名、密码和文件夹(默认 astra),测试连接 通过后就能 立即备份 或 从云端恢复。

  • 只能在本机操作;密码加密保存,不会返回给页面,也不会出现在错误信息里;
  • 云端永远不会收到明文密钥:只能选「不含密钥」或「用口令加密密钥」,选明文会被拒绝;
  • 每次备份写两个文件:providers-<时间戳>.json 和 providers-latest.json;恢复读取后者,并走和文件恢复相同的预览,不会直接覆盖;
  • 服务器必须已有你填的地址(Astra 只创建最后一级文件夹);不会跟随重定向,请填最终地址;TLS 证书会被校验,局域网地址也可以使用。

提供商详情

详情页「设置」标签;右上角可测试连接

详情页有三个标签:

模型

该提供商暴露的模型列表。可以从上游拉取(从上游获取),也可以手动输入模型 ID。每个模型可单独覆盖参数与价格(覆盖后显示「已覆盖」,可一键重置为继承)。

「模型」标签里还有两个小分区:别名(settings.alias,开启设置里的「在模型 ID 后附加提供商别名」后,这个提供商的模型(选「仅多个提供商的模型」时只限与其他提供商同名的模型)写成「模型名@别名」,留空用提供商名称)和 模型映射。

响应超时(settings.first_byte_timeout_sec,「模型」标签里的「响应超时」):网关等这个提供商开始响应的最长秒数,留空不限制,最大 3600。超时算这个提供商失败:绑定了多个提供商的客户端和令牌的提供商池换下一个继续,否则调用方收到 504。响应开始后由设置里的「流式空闲超时」管。

账户 / API Key

订阅类提供商在这里管理订阅账户(见上文「订阅账号」);其他提供商在这里设置 API Key(加密存储,只显示掩码)并配置用量查询。

设置

按分区组织:

分区内容
基本信息名称、区域/版本、协议(OpenAI Chat / OpenAI Responses / Anthropic / Gemini)
认证认证方式(Bearer / x-api-key / x-goog-api-key / query-key);API Key 在「API Key」标签
接口每种协议一个地址;客户端协议与上游不同时 Astra 自动转换,转换时按「上游协议优先级」选择接口
计费价格表(决定用哪套模型价格,如 deepseek、openrouter)与 价格倍率(中转站按官方价 ×1.1 计费的场景)
高级仅此提供商生效的 HTTP 代理(订阅登录、刷新与额度查询同样走它)、额外请求头、「模拟 Claude Code」(仅 Anthropic 协议的非订阅提供商)、适配器设置(JSON)

更换模板

选错了模板(比如把按量 Key 填进了订阅模板)不用删掉重建:右上角 更多 → 更换模板,选新模板(有区域 / 版本的再选一个), 接口地址和上游协议优先级会换成新模板的;API Key、模型和你改过的设置(名称、倍率、请求头等)都保留,没改过的默认值跟随新模板。 订阅登录类和插件提供的提供商不能更换模板,也不能换成订阅或自定义模板。

用量查询

API Key 类提供商可以在 API Key → 用量查询 里打开余额 / 套餐用量查询(参考 cc-switch 的同名功能)。打开后,结果显示在提供商卡片底部和托盘的「额度与余额」里,并按间隔在后台刷新。

  • 默认关闭:同一个地址可能同时有余额接口和套餐接口,Astra 不替你猜,需要手动启用。
  • 凭据:默认用提供商自己的 API Key 和认证方式(Bearer / x-api-key / query-key 等)发请求,不需要再填一遍。
  • 失败只显示,不影响使用:查询失败(Key 无查询权限、限流、超时……)只在卡片上显示错误,并保留上一次成功的结果;提供商照常可用。
  • 自动查询间隔:全局默认 30 分钟(设置 → 通用 → 提供商用量查询,0 = 关闭),单个提供商可以单独设置;连续失败 3 次后间隔自动放大到 4 倍,成功一次即恢复。

内置模板(根据提供商模板或接口域名自动选中,也可以手动换):

模板类型请求
DeepSeek余额GET {origin}/user/balance
OpenRouter余额GET {origin}/api/v1/credits
SiliconFlow余额GET {origin}/v1/user/info(.cn 按人民币,.com 按美元)
StepFun余额GET {origin}/v1/accounts
Novita AI余额GET {origin}/v3/user/balance
New API / One API余额GET {origin}/api/user/self,需要填 用户 ID 和 系统访问令牌(个人设置里生成,不是 sk- 开头的 API Key;令牌加密保存,界面只显示「已保存」)
Kimi For Coding套餐用量GET https://api.kimi.com/coding/v1/usages
GLM Coding Plan套餐用量GET {origin}/api/monitor/usage/quota/limit(open.bigmodel.cn / api.z.ai)
MiniMax Coding Plan套餐用量GET {origin}/v1/api/openplatform/coding_plan/remains

{origin} 是提供商接口地址的协议 + 域名(例如 https://api.deepseek.com)。火山方舟的用量接口需要火山引擎 AK/SK 签名,暂不提供内置模板。

自定义查询

模板选「自定义」后,填写请求(方法、URL、认证方式、请求头)和提取规则。和 cc-switch 用 JavaScript 写提取函数不同,Astra 的提取规则是声明式 JSON:

代码json
{
  "isValid": "success",
  "invalidMessage": "message",
  "planLabel": "data.group",
  "unit": { "$const": "USD" },
  "remaining": { "$div": ["data.quota", 500000] },
  "used": { "$div": ["data.used_quota", 500000] },
  "total": { "$div": [{ "$add": ["data.quota", "data.used_quota"] }, 500000] }
}
  • 字符串是响应里的路径(data.balance、items[0].total),数字是常量;字符串常量要写成 { "$const": "USD" }。
  • 数组表示候选:按顺序取第一个存在的值(相当于 a || b)。
  • 运算:$add、$sub、$mul、$div、$scale(配 by)、$pctUsed({used, total} → 已用百分比)、$eq、$not、$case({on, cases, default})、$var(host、origin、baseUrl 等变量)、$time(秒 / 毫秒时间戳或日期字符串)。
  • 字段与 cc-switch 提取器的返回值一一对应:isValid、invalidMessage、remaining、total、used、unit、planName、extra;多个套餐 / 窗口用 plans 数组,每项可以用 each 遍历数组、where 过滤、first 只取第一个、when 条件显示,另有 usedPercent、resetsAt、windowMinutes。
  • 取不到的字段就是空的,绝不会被当成 0。
  • URL 和请求头里可以用占位符 {{origin}}、{{baseUrl}}、{{host}}、{{apiKey}},以及 {{userId}}、{{accessToken}}(在表单里填写,令牌加密保存)。

测试查询 用当前未保存的配置发一次真实请求,显示请求地址、HTTP 状态、提取结果和已脱敏的原始响应(其中的 Key 与令牌会被替换成 ••••),方便对照响应结构写提取规则。

测试连接

右上角 测试连接 会打开测试弹窗,用当前配置向上游发真实请求——这是排查 Key、地址与额度问题最快的办法。

  • 单模型:左侧选择测试模型(可选列表外的任意模型 ID)、测试协议(仅该提供商已配置的端点协议)、是否流式、最大输出 tokens 与提示词;右侧实时显示 HTTP 响应 / 首字等待 / 首字总延迟 / 完整耗时 四项指标,以及提供商回复的 预览(流式边生成边显示)与 原文(网关处理后的响应正文,凭据已脱敏,可复制)。
  • 选的是图片模型(gpt-image-*、chatgpt-image-*、dall-e-*)时,测试自动换成 OpenAI Images(提供商有 OpenAI 端点即可),流式与最大输出 tokens 换成图片参数,并多出 图片能力 切换:生成图片测 images/generations;编辑图片测 images/edits,Astra 默认把一张内置的 128×128 红色圆形图片(几百字节)以 multipart 上传,默认提示词让它把红色改成蓝色;也可以在「测试图片」里选自己的图片(PNG / JPEG / WebP,不超过 4 MB,按文件内容识别格式;点「恢复默认」回到内置图片)。其余参数:图片尺寸(auto 或 宽x高,留空由上游决定)、图片质量(auto / low / medium / high / standard / hd)与数量(1–4,每张都计费);提示词留空时用对应能力的默认提示词。模型 ID 看不出是图片模型时,也可以手动把测试协议选成 OpenAI Images。单模型测试的结果会直接在「预览」里显示生成 / 编辑出来的图片(可点「保存图片」);图片只回给正在看这一次测试的人,不会写进请求日志、调试抓取或「原文」。批量测试不显示图片,只给一行摘要。GitHub Copilot 的图片接口在 /v1/images/* 下,Astra 会自动用这个路径。
  • 批量模型:勾选多个模型(最多 3 个并发测试),每个模型按自己需要的接口请求——图片模型走 Images 接口(按「配置」里选的图片能力,表格里标出「生成图片」/「编辑图片」),其余模型走所选的聊天协议;表格逐行显示状态与耗时;「停止后续」取消尚未开始的模型,进行中的请求跑完;点「查看」可看单个模型的详细结果。

模拟 Claude Code(第三方上游)

给走 Anthropic 协议的 API Key / 第三方中转提供商,可以在详情页「设置 → 高级」打开「模拟 Claude Code」。开启后,发往该上游的请求会带上 Claude Code 的身份:claude-cli User-Agent、X-Stainless-* 指纹、完整 beta 集(不含 OAuth beta),请求体改写成三块 system 加 metadata.user_id。真正的 Claude Code 请求在直通时原样转发,不会被改写。

默认关闭。这是对客户端检查的伪装,只应用于允许这种用法的上游,风险自负。Claude 订阅(OAuth)提供商的同名开关在「使用策略」里,是同一个设置。