Providers 与模型

OpenSquilla 通过同一套配置入口支持多个 LLM provider。你可以运行直连的单模型模式，或启用 SquillaRouter 进行分层路由。

当你需要配置 provider、查看模型支持情况，或在直连模型模式与 router 模式之间选择时，请使用本页。

查看 provider

列出本地安装中的 provider 元数据：

opensquilla providers list
opensquilla providers list --json

从运行中的 gateway 查看运行时 provider 诊断：

opensquilla providers status
opensquilla providers status openrouter --json
opensquilla providers status --probe-models

providers list 不需要运行中的 gateway。providers status 需要。

配置 provider

交互式：

opensquilla providers configure openrouter

非交互式、onboarding 风格的配置：

export OPENROUTER_API_KEY="sk-..."
opensquilla configure provider --provider openrouter --api-key-env OPENROUTER_API_KEY

直连 provider 示例：

opensquilla configure provider --provider openai --model gpt-5.4-mini --api-key-env OPENAI_API_KEY
opensquilla configure provider --provider anthropic --model claude-sonnet-4-5 --api-key-env ANTHROPIC_API_KEY
opensquilla configure provider --provider gemini --model gemini-2.5-flash --api-key-env GEMINI_API_KEY
opensquilla configure provider --provider ollama --model llama3.1

API key 优先使用环境变量引用，避免将密钥直接写入配置文件。

端点（base URL）解析

llm.base_url 按 显式配置 → 派生环境变量 → provider 默认值 解析：

你保存过的自定义端点（Web UI 高级选项、config.set，或手写在 TOML 中的 base_url）始终优先。
如果配置从未选择过端点——没有 base_url，或该字段仍是 provider 自身的默认 URL——则应用派生环境变量（OPENAI_BASE_URL、OPENROUTER_BASE_URL、<PROVIDER>_BASE_URL）。当你想让整批机器指向企业代理而不逐一修改配置文件时，这就是可用的抓手。
OPENSQUILLA_LLM_BASE_URL 在配置模型构建阶段（OPENSQUILLA_LLM_* 设置层）介入：当 TOML 未设置 base_url 时它会填入该值，解析器随后将其视为显式值——因此它优先于上面的 provider 派生变量，而写在 TOML 中的 base_url 仍优先于它。

API key 通过 api_key / api_key_env 遵循同样的显式配置优先规则。

Onboarding 已验证的 provider

该构建为以下 provider 提供 onboarding 支持：

TokenRhythm
OpenRouter
OpenAI
Anthropic
Ollama
DeepSeek
Gemini
DashScope / Qwen
Moonshot AI
Zhipu / Z.AI
Baidu Qianfan
Volcengine Ark

provider 注册表中可能包含面向进阶或自托管场景的其他兼容 provider。请在你的安装上运行 opensquilla providers list 查看当前目录。

OpenAI：`openai` vs `openai_responses`

OpenAI 以两个 provider id 暴露，二者共享同一个 OPENAI_API_KEY 和 base URL（https://api.openai.com/v1）：

openai —— chat/completions 请求形态。用于标准的 chat 式 turn 和广泛的工具兼容性。
openai_responses —— 原生 Responses-API 形态（能力为 chat 和 responses）。当你想要 Responses-API 行为而非 chat/completions 入口时使用。

两者读取相同的 key 和 base URL，因此在它们之间切换只需更改 provider。

Volcengine Ark：常规端点 vs coding-plan 端点

常规 Ark chat/completions 模型使用 volcengine。其默认 base URL 是 OpenAI 兼容端点 https://ark.cn-beijing.volces.com/api/v3。

Volcengine 的 OpenAI Responses 兼容 coding-plan 订阅入口使用 volcengine_coding_plan。其默认 base URL 为 https://ark.cn-beijing.volces.com/api/coding/v3；OpenSquilla 在发送请求时会追加 /responses。

export VOLCENGINE_API_KEY="..."
opensquilla configure provider --provider volcengine_coding_plan --model <model> --api-key-env VOLCENGINE_API_KEY

对于期望 Anthropic Messages 协议的工具或部署，使用 volcengine_coding_plan_anthropic。其默认 base URL 为 https://ark.cn-beijing.volces.com/api/coding；OpenSquilla 会追加 /v1/messages。

export VOLCENGINE_API_KEY="..."
opensquilla configure provider --provider volcengine_coding_plan_anthropic --model <model> --api-key-env VOLCENGINE_API_KEY

不要将任一 coding-plan provider 指向常规的 /api/v3 URL。常规 Ark URL 不会消耗 Coding Plan 配额。

腾讯 TokenHub：国内、Anthropic 协议与国际端点

腾讯混元的 hy3 / hy3-preview 模型在 TokenHub 平台上提供（旧的 api.hunyuan.cloud.tencent.com 平台正在退役，且从未上线 hy3）。三个实验性 provider id 对应文档记载的端点：

tencent_tokenhub —— OpenAI 兼容的 chat/completions，端点为 https://tokenhub.tencentmaas.com/v1（大陆版；key 来自国内 TokenHub 控制台，TENCENT_TOKENHUB_API_KEY）。hy3 的 thinking 使用 reasoning_effort 的 low/high，assistant 的 reasoning_content 会按 hy3 交错思考（interleaved-thinking）契约的要求在多个 turn 之间回放。
tencent_tokenhub_anthropic —— 同一部署的 Anthropic Messages 协议（https://tokenhub.tencentmaas.com + /v1/messages， x-api-key 鉴权，同一个 key）。
tencent_tokenhub_intl —— 国际部署，端点为 https://tokenhub-intl.tencentcloudmaas.com/v1 （TENCENT_TOKENHUB_INTL_API_KEY）。它是独立的腾讯云账号与 key 体系，其模型列表目前提供第三方模型（DeepSeek、GLM、Kimi、MiniMax），但不含 hy3。

export TENCENT_TOKENHUB_API_KEY="..."
opensquilla configure provider --provider tencent_tokenhub --model hy3 --api-key-env TENCENT_TOKENHUB_API_KEY

TokenHub 也在相同端点后托管第三方模型；OpenSquilla 不会为这些模型 id 注入 thinking 载荷，因为 TokenHub 没有在该 gateway 上记载它们的方言。

腾讯的 Token Plan 订阅（Hy Token Plan 包含 hy3 / hy3-preview；General 套餐在同一个 key 上额外提供 tc-code-latest、DeepSeek V4、GLM-5.x、Kimi 和 MiniMax 等模型 id）在套餐主机上以另外两个 provider id 暴露：

tencent_token_plan —— Chat Completions，端点为 https://api.lkeap.cloud.tencent.com/plan/v3（套餐端点不提供 Responses API）。
tencent_token_plan_anthropic —— Anthropic Messages，端点为 https://api.lkeap.cloud.tencent.com/plan/anthropic（+ /v1/messages），bearer 鉴权。

两者都读取 TENCENT_TOKEN_PLAN_API_KEY。套餐 key 是在 TokenHub Token Plan 控制台页面创建的专用 sk-tp-… 凭据——它们与按量付费的 TokenHub key 不可互换。注意腾讯的套餐条款将这些 key 限制在交互式 AI 工具用途，禁止非交互式的批量/自动化调用；无人值守的流水线应改用按量付费的 tencent_tokenhub provider。这些套餐是仅限大陆的产品——国际站只提供按量付费的 TokenHub。

模型查看

列出模型：

opensquilla models list

如果运行时模型查看无法连接，请启动 gateway：

opensquilla gateway run

对于不需要 gateway 的 provider 元数据，请使用：

opensquilla providers list

上下文窗口解析顺序

上下文预算、压缩阈值、用量压力报告以及 router 的能力事实，都通过相同的层级解析模型的上下文窗口，先命中者优先：

按模型覆写 —— 配置中的 [models.<provider_id>."<model_id>"] context_window。为目录不认识的模型（直连的 DashScope/TokenHub 模型 id、声明真实窗口的自托管 vLLM）设置该项，或用它纠正目录中的错误值。来源报告为 override（在 config.effective 中为 config，在用量上下文状态中为 model_override）。
全局覆写 —— llm.context_window_tokens（0 = 自动）。这是个粗粒度手段，作用于当前激活的任何模型；按模型覆写始终优先于它。
模型目录 —— 实时 OpenRouter 数据、随包附带的 models.dev 快照，然后是打包的修正数据。
默认值 —— 本地运行时使用保守的 8,192（请用覆写匹配你实际的 num_ctx/服务端窗口），其他情况为 200,000。

Web UI 在 Settings → Chat Model → Advanced 下暴露按模型覆写，并显示自动检测值 / 覆写值 / 生效值。

直连模型 vs Router

直连模型模式：

opensquilla configure router --router disabled
opensquilla configure provider --provider openai --model gpt-5.4-mini --api-key-env OPENAI_API_KEY

Router 模式：

opensquilla configure router --router recommended

模式	使用场景
直连模型	测试某个具体模型、复现 provider 行为，或审计 provider 计费时。
Router 模式	进行常规的个人 agent 使用，每个 turn 的成本与任务复杂度都会变化。

路由细节参见 features/squilla-router.md。

定价与成本估算

当 provider 返回真实计费成本时，OpenSquilla 会报告该成本；在其他所有情况下，则根据 token 用量在本地估算成本。每个用量行和按模型细分项都带有标签，让你能分辨看到的是哪一类数字。

成本如何估算

每次计价的调用被拆分为四个 token 桶——新输入（fresh input）、缓存读取（cache read）、缓存写入（cache write）、输出（output）——每个桶按各自费率计价。结果带有一个 basis 标签：

Basis	含义
`cache_aware`	该调用中出现的所有桶都有已知费率；四桶计算已执行。
`cache_blind`	该调用使用了缓存 token，但所需的某个缓存费率未知，因此 OpenSquilla 回退为按普通输入费率对每个输入 token（无论缓存或新输入）计价。这是保守的上界，不是真实费用——在缓存密集的 session 中预计它会高估成本。
`free`	模型或运行时是零价格的（见下文本地运行时）。

价格解析顺序

对于给定的 (model, provider) 组合，OpenSquilla 按以下层级解析价格，先命中者优先：

本地运行时 —— ollama、lm_studio、ovms、vllm 和 local 始终免费，与模型 id 无关。
用户覆写 —— 配置中的 [models.<provider_id>."<model_id>"] （见 configuration.md 和 opensquilla.toml.example）。
模型目录 —— 随包附带的 models.dev 快照，包括上游发布的按模型缓存读取/缓存写入费率。
实时 OpenRouter 端点价格 —— 仅当 provider 为 openrouter 或未设置时才查询（第一方 provider id 从不查询 OpenRouter 市场）；OpenRouter 不可达时回退到静态表。
静态表 —— OpenSquilla 内置捆绑的定价表。
默认值 —— 无任何匹配时，按每百万输入/输出 token $3 / $15 计。

如果 OpenSquilla 对某个模型按错误的价格估算，请添加覆写，而不要等待目录刷新：

[models.openrouter."z-ai/glm-5.2"]
input_cost_per_mtok = 0.5        # USD per million input tokens
output_cost_per_mtok = 2.0       # USD per million output tokens
cache_read_cost_per_mtok = 0.05  # USD per million cached-prompt-read tokens
cache_write_cost_per_mtok = 0.6  # USD per million cached-prompt-write tokens

包含点或斜杠的模型 id 需要加引号。四个字段都是可选的——只设置你需要纠正的那些。config.set/patch/apply 以及 opensquilla gateway reload 会热应用这些覆写；更多示例（包括自托管 vllm 和 custom 端点）见 opensquilla.toml.example。

成本来源（`costSource`）

每个用量行和按模型细分项都带有 costSource（同时以 cost_source 双写形式暴露）：

`costSource`	含义
`provider_billed`	全部成本来自 provider 报告的真实账单。
`opensquilla_estimate`	没有可用的计费成本；该数字是本地估算值。
`mixed`	聚合行中同一模型既有已计费调用也有未计费调用——总额是计费成本加上其余部分的估算值，不是纯账单。
`unavailable`	既无定价表条目也无计费成本，因此无法给出美元金额。

行还携带两个附加字段：estimateBasis（即上文的 cache_aware / cache_blind / free 标签，仅当行中有部分为估算时出现）和 priceSource（哪一个解析层给出了价格——user_override、 catalog、live_openrouter、static_table、default 或 local_free）。Web UI 的按模型用量卡片会为 costSource 显示一个小的来源标记，并在底层 basis 为 cache_blind 时提示该数字是上界，而非真实的缓存折扣后成本。

哪些 provider 给出计费成本 vs 估算成本

能力	Providers
Provider 计费成本	仅 `openrouter`
可进行缓存感知（cache-aware）估算	`anthropic`、`deepseek`、`minimax`（Anthropic 形态）、ensemble 成员
仅缓存读取感知估算（无缓存写入费率）	`openai`、`openai_responses`、`azure`、`gemini`、`openai_codex`
缓存盲（cache-blind）估算（出现缓存 token 时回退为普通输入费率计价）	其他 OpenAI 兼容 provider 类型
免费	本地运行时（`ollama`、`lm_studio`、`ovms`、`vllm`、`local`）
订阅（没有可比对的账单）	coding-plan/订阅类 provider —— 任何报告的数字都应视为估算值，而非账单

使用 opensquilla providers status --probe-models 和 opensquilla cost --by-model 可查看你配置的 provider/模型在某个 session 中落在哪一类。

Turn 与 Router 预算闸门

存在两个按 turn 的 agent 预算，行为各不相同：

max_turn_billed_cost_usd 只在真实的 provider 计费成本上触发。在从不报告计费成本的 provider 或路径上它是惰性的（永不触发）——在 openrouter 之外不要只依赖它。
max_turn_cost_usd 在本节其他地方使用的同一个累计器上触发：provider 报告计费成本时用计费成本，否则用 cache-aware/cache-blind 估算值。它在每个 provider 上都有效。触发时，错误（turn_cost_budget_exceeded）会说明总额是计费、估算还是混合。

SquillaRouter 的 session 预算闸门（[squilla_router.budget]，见 features/squilla-router.md）会在每个 router_budget.warn/router_budget.cap 事件旁以及路由轨迹中记录一个 spend_source：

`spend_source`	含义
`billed`	累计开销是真实的 provider 计费成本。
`estimate`	累计开销是整个 session 的本地估算值。
`estimate_mixed`	该 session 混合了计费成本与估算成本。
`none`	尚未记录任何开销。
`unknown`	无法确定开销；闸门会暂停而不是基于猜测行动。

延伸阅读：usage-and-cost.md 介绍 opensquilla cost CLI 以及如何解读 session 的用量行。

Provider 排障

先从以下入手：

opensquilla doctor
opensquilla providers status
opensquilla diagnostics on

检查：

gateway 进程环境中已设置 API key 环境变量；
模型 id 与 provider 匹配；
兼容 API 的 base URL 正确；
代理设置与你的网络一致；
在排查某个具体 provider/模型时已禁用 router；
配置变更后已重启 gateway。

文档索引 · 产品指南 · 改进本页 · 反馈文档问题