提供商
添加上游服务商、配置密钥与计费、测试连接
提供商(Provider)是 Astra 的上游入口:一个接口地址 + 一种协议 + 一份凭据。可以同时添加多个——比如同一个 DeepSeek 账号建两个条目用不同倍率,或官方 API 与 OpenRouter 并存。
提供商列表
每行从左到右:
- 图标与名称 — 点击进入详情;
- 徽标 — 绑定的客户端(绿色,如「Codex」),「未设置密钥」(橙色)提醒补 Key,「模板更新」表示模板有新版本(GitHub Copilot 订阅的模板会在服务启动时自动更新,你改过的值保持不变);
- 详情行 — 协议 · 模型数 · 价格表 · 倍率(非 1.0 时显示);
- 开关 — 临时停用某个提供商(停用后请求不再路由到它)。
添加提供商
点右上角 添加提供商,弹出两步向导:
- 选择模板 — 模板自带接口地址、协议与默认模型列表。分类:官方 / 订阅(OAuth 登录)/ 编程套餐(用 API Key 的 Coding Plan)/ 国内 / 聚合平台 / 推理平台 / 本地。没有匹配的就选「自定义提供商」,手填任意 OpenAI / Anthropic / Gemini 兼容接口;
- 填写信息 — 名称、API Key 与价格表;自定义提供商还要填接口(每种协议一个地址,通常以
/v1结尾)和认证方式。 展开 更多选项 可以在创建时就设置:接口地址(模板的默认地址可改、可增删协议,可设为完整 URL)、上游协议优先级、认证方式、 额外请求头、HTTP 代理、价格倍率、初始模型(留空则用模板自带的模型)和备注。这些创建后都能在详情页「设置」里再改。
从其他应用导入
已经在别的工具里配置过中转或官方 Key?点右上角 从其他应用导入,Astra 会只读扫描本机以下位置并列出可导入的提供商:
- 列表里每一行显示名称、协议与地址、遮掩后的 Key、模型数和状态:新增(默认勾选)、已存在(同地址同 Key,不可选)、同地址(地址相同但 Key 不同,可选并作为新提供商导入)、已停用(来源里已关闭,默认不勾选)、无法导入(附原因);
- 只读、不修改来源;API Key 由服务端直接读取并加密保存,不经过浏览器,预览里也只有遮掩值;
- 同一来源里 Key 与主机都相同的多条配置会合并成一个提供商的多个端点;Magpie 里一个提供商的多个 Key 会各导入成一个提供商;
- 官方登录(Claude / ChatGPT / Copilot 等订阅登录)、路由、限流、余额、会话与用量不会导入;导入不会绑定或改动任何客户端配置,也不会发起上游请求——导入后可用「测试连接」确认。
备份与恢复
右上角 备份与恢复 把提供商和它们的模型导出成一个 JSON 文件(astra-providers-<日期>.json),换机器或重装后可以从这个文件恢复。
导出时选择 API 密钥怎么处理:
文件包含提供商配置(地址、协议、认证方式、额外请求头、代理、价格倍率、设置)和每个模型的覆盖项与启用状态。不包含 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(加密存储,只显示掩码)并配置用量查询。
设置
按分区组织:
更换模板
选错了模板(比如把按量 Key 填进了订阅模板)不用删掉重建:右上角 更多 → 更换模板,选新模板(有区域 / 版本的再选一个), 接口地址和上游协议优先级会换成新模板的;API Key、模型和你改过的设置(名称、倍率、请求头等)都保留,没改过的默认值跟随新模板。 订阅登录类和插件提供的提供商不能更换模板,也不能换成订阅或自定义模板。
用量查询
API Key 类提供商可以在 API Key → 用量查询 里打开余额 / 套餐用量查询(参考 cc-switch 的同名功能)。打开后,结果显示在提供商卡片底部和托盘的「额度与余额」里,并按间隔在后台刷新。
- 默认关闭:同一个地址可能同时有余额接口和套餐接口,Astra 不替你猜,需要手动启用。
- 凭据:默认用提供商自己的 API Key 和认证方式(Bearer / x-api-key / query-key 等)发请求,不需要再填一遍。
- 失败只显示,不影响使用:查询失败(Key 无查询权限、限流、超时……)只在卡片上显示错误,并保留上一次成功的结果;提供商照常可用。
- 自动查询间隔:全局默认 30 分钟(设置 → 通用 → 提供商用量查询,0 = 关闭),单个提供商可以单独设置;连续失败 3 次后间隔自动放大到 4 倍,成功一次即恢复。
内置模板(根据提供商模板或接口域名自动选中,也可以手动换):
{origin} 是提供商接口地址的协议 + 域名(例如 https://api.deepseek.com)。火山方舟的用量接口需要火山引擎 AK/SK 签名,暂不提供内置模板。
自定义查询
模板选「自定义」后,填写请求(方法、URL、认证方式、请求头)和提取规则。和 cc-switch 用 JavaScript 写提取函数不同,Astra 的提取规则是声明式 JSON:
- 字符串是响应里的路径(
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)提供商的同名开关在「使用策略」里,是同一个设置。