企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• 交互助手
• 工具调用
• MCP 服务
• Agent 记忆
• RAG

OpenSquilla 通过单一配置面接入多个 LLM Provider，既支持直接单模型模式，也支持启用 SquillaRouter 进行分层路由。本文以 docs/providers-and-models.md 为核心骨架，结合仓库源码与配置示例，完整讲解 Provider 的查看、配置、Endpoint 解析、模型检查、直连/路由模式选择、成本估算与故障排查，帮助你在同一套配置体系下管理 OpenAI、Anthropic、Gemini、Qwen Token Plan、Volcengine Ark、Tencent TokenHub、本地运行时与自定义兼容端点。

Inspect Providers：查看 Provider 元数据与运行时诊断

OpenSquilla 提供两组 Provider 查看命令：一组面向本地安装的静态元数据目录，另一组面向运行中的 Gateway 的实时诊断。

# 列出本地安装中的 provider 元数据（不需要运行 gateway） opensquilla providers list opensquilla providers list --json

# 查看运行中 gateway 的 provider 运行时诊断（需要 gateway 在运行） opensquilla providers status opensquilla providers status openrouter --json opensquilla providers status --probe-models

关键区别：providers list不依赖运行中的 Gateway；providers status依赖。从源码看，两者的实现路径不同：

• opensquilla providers list直接调用 onboarding/provider_specs.py 的provider_catalog_payload()/list_provider_setup_specs()，以表格输出 provider id、label、runtime（supported/disabled）、是否 requires key、是否 requires base url 与默认 base url；--json输出同一目录的机器可读负载，包含envKey、defaultBaseUrl、deployment（cloud/local/custom/oauth）、verification（verified/experimental）、canProbe、fields等字段。
• opensquilla providers status通过 cli/providers_cmd.py 的providers_status走 gateway RPC（providers.status），对每个 provider 输出 active / configured / buildable / model / error；--probe-models时额外探测模型列表，返回ok (N models)、error或degraded状态，并把失败细分为failureKind。
• 想要不发请求的配置级校验（例如未知 provider id、运行时不受支持），可使用opensquilla models probe，它枚举主[llm]与每个[llm_profiles.*]凭据配置，对绑定模型的凭据做 provider 有界的 chat 探测，未绑定模型的凭据做模型列表探测，失败信息经脱敏后输出（详见 cli/models_cmd.py）。

providers list的输出顺序由_CATALOG_RANK决定：TokenRhythm 排第一、OpenRouter 第二，其余按 label 排序——Web UI 下拉框、CLIproviders list与交互式 onboarding 选择器共用同一顺序。

Configure a Provider：交互式与非交互式配置

交互式配置（引导式表单，支持 Tab 补全与必填项校验）：

opensquilla providers configure openrouter

非交互式 onboarding 风格配置（适合脚本与 CI）：

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

底层实现上，opensquilla configure provider与providers configure都汇聚到 onboarding/mutations.py 的upsert_llm_provider，写入config.toml的[llm]段，并在需要重启时提示。关于密钥，官方建议优先使用环境变量引用（--api-key-env），避免把密钥明文写进配置文件——providers configure交互式表单会以 password 字段采集密钥，并支持“留空则从OPENROUTER_API_KEY等环境变量读取”的说明文案（见 provider_specs.py 的_fields_for）。

从 opensquilla.toml.example 可以看出常用 provider 的默认 base URL 一览（完整列表以你安装上的opensquilla providers list为准）：

Endpoint（base URL）解析顺序

llm.base_url的解析遵循显式配置 → 派生环境变量 → provider 默认值三层规则：

• 显式自定义 endpoint 永远优先：包括 Web UI 高级选项保存的自定义地址、config.set、或手写在 TOML 中的base_url。
• 派生环境变量次之：当配置从未选择过 endpoint（无base_url，或该字段仍持有 provider 自带默认 URL）时，OPENAI_BASE_URL、OPENROUTER_BASE_URL、<PROVIDER>_BASE_URL等派生变量生效。这是“不改任何 config 文件、把整批机器指向公司代理”的关键杠杆。
• OPENSQUILLA_LLM_BASE_URL进入的位置更早：它在 config-model 构造阶段（OPENSQUILLA_LLM_*设置层）生效，只要 TOML 未设置base_url就填充它，随后解析器将其视为显式值——因此它压过上述 provider 派生变量，但 TOML 中手写的base_url仍压过它。

API key 遵循同样的显式配置优先规则，通过api_key/api_key_env控制：api_key明文优先于环境变量；只有两者都缺失时才从 provider 的约定 env（如OPENAI_API_KEY）读取。

Onboarding-Verified Providers：已验证 Provider 清单

本构建对以下 Provider 提供 onboarding 支持：

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

该清单与源码中的_ONBOARDING_VERIFIED_PROVIDER_IDS一致（见 provider_specs.py），含义是“完整 Agent 栈（工具、推理、回放）已对该 provider 实测通过”。此外，注册表中还包含大量 runtime-capable 但标记为 experimental 的 provider（如 Azure OpenAI、MiniMax 系列、Kimi Coding、SiliconFlow、AIHubMix、BytePlus、vLLM、LM Studio、OpenVINO Model Server、LiteLLM Proxy、OpenAI Codex OAuth、GitHub Copilot OAuth 等），以及volcengine_coding_plan、tencent_tokenhub等专门 id。以你安装上的opensquilla providers list为最终目录——不同构建的验证集合可能不同。

OpenAI：openaivsopenai_responses

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

• openai—— chat/completions 请求形态，用于标准 chat 风格轮次与广泛的工具兼容性。
• openai_responses—— 原生 Responses-API 形态（能力为chat和responses），想要 Responses-API 行为而非 chat/completions 表面时使用。

两者读取相同的 key 与 base URL，切换只需改provider字段。

Qwen Token Plan：OpenAI 与 Anthropic 双协议

Token Plan 独立于常规 DashScope 与 Bailian Coding Plan，必须使用专用的sk-sp-...密钥；标准 Model Studio 密钥无法消耗 Token Plan Credits。OpenSquilla 通过两个已验证 provider id 暴露大陆服务：

• qwen_token_plan—— OpenAI 兼容 Chat Completions，位于https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1。
• qwen_token_plan_anthropic—— Anthropic Messages，位于https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic（+/v1/messages），使用 bearer 认证。

两者都读取QWEN_TOKEN_PLAN_API_KEY，默认模型为qwen3.8-max-preview：

export QWEN_TOKEN_PLAN_API_KEY="sk-sp-..." opensquilla configure provider \ --provider qwen_token_plan \ --model qwen3.8-max-preview \ --api-key-env QWEN_TOKEN_PLAN_API_KEY

打包的模型目录是文档化的团队计划超集。个人计划可使用qwen3.8-max-preview、qwen3.7-max、qwen3.7-plus、qwen3.6-flash、glm-5.2、deepseek-v4-pro；团队计划额外包含qwen3.6-plus、DeepSeek V4 Flash / V3.2、Kimi K2.7 / K2.6 / K2.5、GLM 5.1 / 5 与 MiniMax M2.5。额度由服务端强制：Settings 与 onboarding 查询已验证的 OpenAI 兼容/models端点，使建议反映当前密钥的额度；Anthropic 配置文件刻意使用同一账户目录，而不是把打包超集当作实时结果呈现。

针对这种混合目录，OpenAI 兼容适配器应用模型家族所需的线上契约：Qwen 3.8 的强制思考与 0.6 温度下限、DeepSeek V4 的 effort 与推理回放、Kimi 工具调用推理回放、GLMtool_stream，以及思考模式工具选择归一化。Anthropic 适配器保留签名思考块，并钳制 Qwen 3.8 的温度下限。内置的 SquillaRouter 内联预设使用 Qwen 3.6 Flash → Qwen 3.7 Plus → Qwen 3.7 Max → Qwen 3.8 Max Preview 的梯级，图像路由为 Qwen 3.7 Plus。

Token Plan 还通过 OpenSquilla 的image_generate工具暴露原生图像生成——这与路由器的图像路由不同：路由器的图像模型理解图像输入，而 Wan 创建新的图像工件。配置wan2.7-image或wan2.7-image-pro：

[image_generation] enabled = true primary = "qwen_token_plan/wan2.7-image" size = "768x768" [image_generation.providers.qwen_token_plan] api_key_env = "QWEN_TOKEN_PLAN_API_KEY" base_url = "https://token-plan.cn-beijing.maas.aliyuncs.com/api/v1"

原生适配器使用文档化的多模态生成请求形态，把 OpenSquilla 的WIDTHxHEIGHT尺寸转换为服务的WIDTH*HEIGHT形式，并安全下载临时签名结果 URL。当 Token Plan 同时是活动 LLM provider 时，图像 provider 可复用其凭据——因为两个官方端点的 HTTPS 源相同；它不会复用不兼容的 chat API 路径。

注意：Token Plan 授权用于受支持的交互式 AI 编程与 Agent 工具，不是无人值守应用后端或通用批处理 API 负载的替代凭据，请遵守当前订阅的条款。

Custom OpenAI / Anthropic 兼容端点

custom用于 OpenAI Chat Completions 端点，custom_anthropic用于 Anthropic Messages 端点。两者都要求显式 model 与 base URL；API key 可选：

[llm] provider = "custom_anthropic" model = "vendor-model" base_url = "https://llm.example.com/anthropic" api_key_env = "CUSTOM_ANTHROPIC_API_KEY"

custom_anthropic会追加/v1/messages并发送 bearer token；custom会向带版本号的 base URL 追加/chat/completions，并读取CUSTOM_LLM_API_KEY。

高级本地部署还可以直接编辑config.toml，为每个 OpenAI 兼容 chat 请求附加端点专属 JSON 字段：

[llm] provider = "custom" model = "local-model" base_url = "http://127.0.0.1:8000/v1" temperature = 0.7 top_p = 0.9 thinking = "high" [llm.extra_body] top_k = 40 min_p = 0.05 repetition_penalty = 1.1 [llm.extra_body.chat_template_kwargs] enable_thinking = true

extra_body仅在主customprovider 上可用，且是仅限本地文件的高级设置：Web UI、环境变量、llm_profiles与配置 RPC 均不暴露或修改它。编辑文件后需重载配置或重启 OpenSquilla。temperature、top_p、token 限制、工具、流式与推理控制等一等字段仍归它们的一等设置所有，不能通过extra_body覆盖；嵌套对象原样发送，顶层合并是浅合并。不要在extra_body中存放凭据或其他密钥；旧版本 OpenSquilla 可能拒绝该字段，降级前请删除该表。

未知的自定义模型默认保持保守的 8k 上下文（升级兼容）。请在[models.custom."<model>"]或[models.custom_anthropic."<model>"]下声明端点的真实窗口——这对远程 gateway 和窗口更大的本地服务器都重要：

[models.custom."vendor-model"] input_cost_per_mtok = 0.5 output_cost_per_mtok = 2.0

custom与custom_anthropic默认零 token 成本估算——这不意味着远程服务、GPU 或其他基础设施免费。要估算付费端点，必须同时设置其精确 provider/model 覆盖的 input 与 output 价格；cache-read / cache-write 价格保持可选。若任一主价格缺失，通用自定义端点维持零价默认，且不会继承同名市场模型的价格。

当前自定义 provider 的边界是刻意显式的：

• 协议选择通过两个固定 provider id 提供；
• 支持 provider 作用域的模型覆盖、base URL、代理与可选 bearer key；
• 任意用户命名 provider id 与任意请求头尚不属于持久化 provider 契约；
• 自定义 Anthropic 认证目前仅可选 bearer（x-api-key与自定义认证模式不可配置），自定义协议选择暂不含 OpenAI Responses 或原生 Gemini；
• custom支持受保护的本地 TOMLextra_body；任意请求变换与自定义头不暴露；
• 推理方言绝不会从不被信任的自定义主机推断——仅在端点契约已知时才设置 provider 作用域的模型元数据。

Volcengine Ark：常规端点与 Coding Plan 端点

• volcengine—— 常规 Ark chat/completions 模型，默认 base URL 为 OpenAI 兼容端点https://ark.cn-beijing.volces.com/api/v3。
• volcengine_coding_plan—— Volcengine 的 OpenAI Responses 兼容 coding-plan 订阅面，默认 base URL 为https://ark.cn-beijing.volces.com/api/coding/v3；发送请求时 OpenSquilla 追加/responses。
• volcengine_coding_plan_anthropic—— 面向期望 Anthropic Messages 协议的工具或部署，默认 base URL 为https://ark.cn-beijing.volces.com/api/coding；OpenSquilla 追加/v1/messages。

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

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

不要把任一 coding-plan provider 指向常规/api/v3URL——常规 Ark URL 不消耗 Coding Plan 配额。

Tencent TokenHub：CN、Anthropic 协议与国际端点

腾讯 Hunyuanhy3/hy3-preview在 TokenHub 平台提供服务（旧的api.hunyuan.cloud.tencent.com平台正在退役且从未接收hy3）。三个实验性 provider id 映射文档化端点：

• tencent_tokenhub—— OpenAI 兼容 chat/completions，位于https://tokenhub.tencentmaas.com/v1（大陆；CN TokenHub 控制台密钥，TENCENT_TOKENHUB_API_KEY）。hy3思考使用reasoning_effortlow/high，助手reasoning_content跨轮回放，以满足 hy3 交错思考契约。
• tencent_tokenhub_anthropic—— 同一部署的 Anthropic Messages 协议（https://tokenhub.tencentmaas.com+/v1/messages，x-api-key认证，同一密钥）。
• tencent_tokenhub_intl—— 国际部署https://tokenhub-intl.tencentcloudmaas.com/v1（TENCENT_TOKENHUB_INTL_API_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 注入思考负载，因为 TokenHub 未在该 gateway 上文档化它们的方言。

腾讯的 Token Plan 订阅（Hy Token Plan 携带hy3/hy3-preview；General 计划在同一密钥上添加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。计划密钥是在 TokenHub Token Plan 控制台页面创建的专用sk-tp-…凭据——与按量付费的 TokenHub 密钥不可互换。腾讯计划条款将这些密钥限制为交互式 AI 工具使用，禁止非交互式批处理/自动化调用；无人值守管道应改用按量付费的tencent_tokenhub。这些计划是大陆专属产品——国际站点仅提供按量付费 TokenHub。

Model Inspection：模型检查与上下文窗口解析

列出模型（需要运行中的 gateway）：

opensquilla models list

若运行时支撑的模型检查无法连接，先启动 gateway：

opensquilla gateway run

不需要 gateway 的 provider 元数据则使用：

opensquilla providers list

models list通过 gateway RPCmodels.list获取模型行，表格输出 ID、Provider、Context、Capabilities、Input/1k、Output/1k；--provider与--capability可过滤，--json输出机器可读数据（见 cli/models_cmd.py）。无法列出的 provider 会单独以黄色汇总报告错误，不会让整条命令失败。

Context-Window 解析顺序

上下文预算、压缩阈值、用量压力报告与路由器的能力事实都通过同一组层级解析模型的上下文窗口，先命中者胜：

1. 逐模型覆盖—— 配置中的[models.<provider_id>."<model_id>"]的context_window。用于目录不认识的模型（直连 DashScope/TokenHub id、声明真实窗口的自托管 vLLM）或纠正目录错误值。报告中以override为来源（config.effective中为config，用量上下文状态中为model_override）。
2. 全局覆盖——llm.context_window_tokens（0 = 自动）。作用于当前活动模型的钝性工具；逐模型覆盖总是压过它。
3. 模型目录—— 实时 OpenRouter 数据、vendored models.dev 快照，然后是打包修正。
4. 默认值—— 本地运行时保守的 8,192（用覆盖匹配你的真实num_ctx/服务器窗口），其余 200,000。

Web UI 在 Settings → Chat Model → Advanced 下暴露逐模型覆盖，带 auto-detected / override / effective 读数。从 registry.py 可见，本地运行时集合（ollama、lm_studio、ovms、custom、custom_anthropic、vllm、local）的未知模型 id 保持 8k 保守回退，其中KEYLESS_PROVIDERS同时解释了为什么这些 provider 的 API key 是可选的。

Direct Model vs Router：直连模式还是路由模式

直连模型模式：

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

路由模式：

opensquilla configure router --router recommended

直连模式下，每一次请求都打向同一个 provider 与模型，便于隔离变量；路由模式下 SquillaRouter 根据任务复杂度在多个 tier（如 opensquilla.toml.example 中[squilla_router.tiers.c0]～c3与image_model的 TokenRhythm 梯级）之间选择。路由细节参见 features/squilla-router.md。

Pricing and Cost Estimation：定价与成本估算

OpenSquilla 在 provider 返回真实账单时报告真实计费成本，其余情况本地基于 token 用量估算。每条用量行与按模型分解项都带有标签，标明你看到的是哪类数字。

一次成本如何被估算

每次计价调用被拆成四个 token 桶——fresh input、cache read、cache write、output——每桶按各自费率计价。结果携带basis标签：

价格解析顺序

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

1. 本地运行时——ollama、lm_studio、ovms、vllm、local无论模型 id 如何总是免费。
2. 通用自定义端点——custom与custom_anthropic存在完整的显式 input/output 价格覆盖时使用它；否则解析为零，priceSource="custom_free"，并在目录、实时、静态或默认云端定价之前停止。
3. 用户覆盖—— 配置中的[models.<provider_id>."<model_id>"]（参见 configuration.md 与 opensquilla.toml.example）。
4. 模型目录—— vendored models.dev 快照，包括上游发布的逐模型 cache-read/cache-write 费率。
5. 实时 OpenRouter 端点价格—— 仅在 provider 为openrouter或未设置时查询（一方 provider id 从不查询 OpenRouter 市场）；OpenRouter 不可达时回退静态表。
6. 静态表—— OpenSquilla 内置的定价表。
7. 默认值—— 什么都没匹配时按每百万 input/output token 分别$3/$15。

如果估算价格不对，直接加覆盖，不要等目录刷新：

[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 必须加引号。对普通 provider 覆盖，四个字段全部可选；对custom与custom_anthropic，input_cost_per_mtok与output_cost_per_mtok必须同时设置才能启用非零估算，缓存费率仍可选。config.set/patch/apply与opensquilla gateway reload可热应用这些覆盖。

成本来源（costSource）

每条用量行与按模型分解项都携带costSource（同时以cost_source双命名暴露）：

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

哪些 Provider 产生计费 vs 估算成本

使用opensquilla providers status --probe-models与opensquilla cost --by-model可查看你的配置 provider/model 在给定会话中属于哪一类。

Turn 与 Router 预算门

两个逐轮 Agent 预算存在且行为不同：

• max_turn_billed_cost_usd只以真实 provider 计费成本为门。在从不报告计费成本的 provider 或路径上它是不起作用的（永不触发）——在openrouter之外不要单独依赖它。
• max_turn_cost_usd以本节其他地方使用的同一累计器为门：provider 报告时用计费成本，否则用 cache-aware/cache-blind 估算。它只能在调用有计费成本或非零本地估算时触发。没有完整 input/output 价格覆盖的通用自定义端点解析为零，所以对付费自定义端点要先配好两个费率再依赖此门。触发时，错误（turn_cost_budget_exceeded）会说明总数是计费、估算还是混合。

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

继续阅读 usage-and-cost.md 了解opensquilla costCLI 与如何阅读会话的用量行。

Provider Troubleshooting：故障排查

从以下命令开始：

opensquilla doctor opensquilla providers status opensquilla diagnostics on

检查清单：

• API key 环境变量已设置在 gateway 进程环境中；
• 模型 id 与该 provider 匹配；
• base URL 对兼容 API 是否正确；
• 代理设置与你的网络匹配；
• 调试某一个精确 provider/model 时已禁用 router；
• 配置变更后已重启 gateway。

逐项排除时，优先用opensquilla models probe --provider <id>做不发持久化的小探测：它会对该凭据做一次 provider 有界的 chat 探测（或模型列表探测），并输出脱敏后的失败分类，帮助区分配置级错误（invalid_config）与可达 provider 的实际失败。结合opensquilla providers status --probe-models可以一次性看到每个配置 provider 的 active / configured / buildable 状态与模型探测结果。

延伸阅读：Docs index · Product guide · configuration.md · usage-and-cost.md · features/squilla-router.md

• 人工智能
• 大模型
• AI Agent
• 交互助手
• 工具调用
• MCP 服务
• Agent 记忆
• RAG