sub2api Provider

简体中文 | English

简体中文

在 VS Code Chat 和 GitHub Copilot Agent 模式中直接使用兼容 sub2api 的 API。扩展不绑定特定服务地址，也不会内置服务器地址或 API Key。

运行 sub2api：打开文档 时，扩展会根据当前 VS Code 显示语言自动打开中文或英文文档。也可以使用上方语言链接手动切换。

主要功能

支持 VS Code Stable 1.130+ 和 VS Code Insiders
支持 OpenAI Responses、OpenAI Chat Completions 和 Anthropic Messages 协议
默认使用 Responses API，支持加密推理重放、稳定的隐式缓存路由，以及可选的 GPT-5.6 显式缓存断点
支持流式文本、图片、函数工具和工具结果
在原生模型菜单中按模型选择上下文大小和思考级别
在源码管理提交消息框正上方的工具栏中一键生成标准 Conventional Commit，并可独立配置语言、模型和思考级别
使用模型官方上下文窗口，并能学习网关实际限制
可配置按端点和 API Key 的请求并发度，并安全重试并发限制错误
支持取消连接测试、限制模型/用量请求超时，并合并并发用量刷新
默认省略上游错误正文，仅在显式启用调试日志时记录脱敏内容
实时显示请求/会话 Token、缓存命中率和可选的服务端余额
API Key 存储在 VS Code SecretStorage 中

快速开始

从 Visual Studio Marketplace 或 VSIX 安装扩展。
运行 sub2api：配置服务地址，输入 API 基础地址。
运行 sub2api：设置 API Key。
保持 sub2api.apiFormat 为默认的 openai-responses，或选择其他兼容协议。
运行 sub2api：测试连接，打开 Chat，然后从 sub2api 提供器中选择模型。

VS Code Stable 与 VS Code Insiders 使用不同的扩展安装和 SecretStorage 数据库。如果两个版本都在使用，需要分别配置一次服务地址和 API Key。

生成 Git 提交消息

打开源码管理，点击提交消息输入框正上方工具栏中的星光按钮。扩展会把所选 Git 差异发送到已配置的 sub2api 服务，生成简洁的提交消息；只有收到完整响应后才会替换消息框中的现有内容。

在多仓库工作区中，按钮只作用于点击所在的仓库：仅读取该仓库的更改，也只更新该仓库的提交消息框。不同仓库可以同时独立生成；同一仓库在本次生成完成前重复点击不会启动第二次生成。

存在暂存更改时仅总结暂存区，使消息与下一次提交保持一致；没有暂存更改时总结工作区和未跟踪文件。未跟踪的二进制文件及大于 1 MB 的文件只发送元数据，大型文本差异会限制在所选模型的安全提示预算内。扩展不会修改源文件或 Git 索引。

生成结果遵循 Conventional Commits 1.0.0，格式为 type(scope)!: 标题说明；仅在差异确有需要时添加正文及 BREAKING CHANGE: 页脚。类型限定为 feat、fix、docs、refactor、perf、test、build、ci、chore、style、revert；首行目标约 50 个字符、最多 72 个字符，生成的正文按 72 个字符换行。扩展要求模型返回结构化数据，再由本地代码校验并组装最终消息，因此格式不只依赖提示词约束。

默认使用简体中文、gpt-5.6-terra 和 medium 思考级别。可运行 sub2api：配置 Git 提交消息生成，或打开独立的 sub2api 提供器 › Git 提交消息 设置分类，修改 sub2api.commitMessageLanguage、sub2api.commitMessageModel 和 sub2api.commitMessageReasoningEffort；提交消息模型与 Chat 模型列表及 Chat 全局思考级别相互独立。

运行 sub2api：打开文档 时，扩展会读取当前 VS Code 的显示语言：语言代码以 zh 开头时打开中文，否则打开英文。扩展内文档可使用顶部按钮切换语言；扩展详情页可使用顶部同页链接切换中英文段落。

配置指南

打开配置

可以使用以下任一入口：

运行 sub2api：管理提供器，在一个菜单中访问服务地址、API Key、连接测试、用量、思考级别、上下文、文档、设置和日志。
运行 sub2api：配置 Git 提交消息生成，依次选择语言、模型和思考级别。
打开 VS Code 设置，搜索 @ext:vortelyn.sub2api-provider。
从命令面板运行 首选项：打开用户设置 (JSON)，直接编辑 settings.json 中的 sub2api.* 属性。服务地址等机器级设置由 VS Code Stable 和 Insiders 分别保存。

API Key 是例外：请运行 sub2api：设置 API Key 配置。它保存在 VS Code SecretStorage 中，不要写入 settings.json。

配置服务地址和 API Key

运行 sub2api：配置服务地址。
输入兼容网关的基础地址，建议包含 API 版本前缀，例如 https://gateway.example.com/v1。
运行 sub2api：设置 API Key，输入网关密钥。
选择与网关匹配的 sub2api.apiFormat。
运行 sub2api：测试连接，选择一个已启用模型，并确认出现连接成功通知。

服务地址命令既接受基础地址，也接受已知的完整推理 URL。最终请求地址由所选协议决定：

配置值	API 格式	最终请求地址
`https://gateway.example.com/v1`	`openai-responses`	`https://gateway.example.com/v1/responses`
`https://gateway.example.com/v1`	`openai-completions`	`https://gateway.example.com/v1/chat/completions`
`https://gateway.example.com/v1`	`anthropic-messages`	`https://gateway.example.com/v1/messages`

如果输入的完整地址以 /responses、/chat/completions 或 /messages 结尾，切换 sub2api.apiFormat 时会替换该已知后缀。末尾斜杠会被移除。仅接受 HTTP 和 HTTPS 地址，并拒绝 URL 中嵌入的凭据。

完整设置参考

先运行 sub2api：账号、订阅与模型 → 连接 Sub2API 账号，登录当前推理 API Key 所属的账号。支持邮箱、密码及两步验证码；不保存密码。账号访问令牌和刷新令牌按服务器 API 地址分别存入 VS Code 安全存储，支持时自动续期。网站要求浏览器验证码或单点登录时，先在网页登录，再从浏览器开发者工具 → 应用/存储 → 本地存储取得该网站现有的 auth_token，通过插件的使用账号访问令牌入口输入；只填入插件的密码输入框，不写入设置、日志或聊天。手动导入的访问令牌过期后需重新连接。账号接口按当前服务器的对应 /api/v1 路径访问；账号 API 位于另一个域名的部署暂不支持此登录方式。

插件精确查找当前 API Key，根据其分组 ID 匹配同一用户、同一分组的有效订阅，并检查生效时间、到期时间和撤销状态。账号的其他套餐不会扩大当前 Key 的模型范围。账号页面展示匹配的套餐/分组、到期时间和周期额度；余额型普通分组会单独识别。没有登录账号时，订阅身份保持未确认；仍可使用推理 Key 读取网关提供的账号模型清单。

自动发现读取 Sub2API 按当前 Key 返回的 Codex 模型清单（/models?client_version=...）。Chat、Auto 和 Git 共用经过筛选的模型：清单标为可见、支持 API，与当前协议兼容，并具有可信的文本聊天能力和上下文预算。插件已补齐 GPT-6.1 Sol 的原生参数；网关向当前 Key 开放后会自动加入。对于 Sub2API 自动生成的别名描述，还需有已核实的原生参数或明确的 supported_endpoints；默认填写的可见性、API 支持标记和上下文数值不足以确认协议兼容性。有效的新清单直接替换旧清单，移除已消失的模型，空清单同样生效。模型范围取决于网关和当前 Key 的配置。

清单给出的最大上下文用于限制客户端预算，未提供最大值时使用默认预算，并以已核实的原生上限为限。GPT-6.1 Sol 的原生上下文为 1,050,000 Token，最大输出为 128,000 Token；网关可以开放较小的预算。支持的思考级别为 low、medium、high、xhigh 和 max。Responses 支持工具调用，Chat Completions 按无工具调用的能力展示；GPT-6 Sol、Luna 通过 Chat Completions 调用工具时使用 none 思考级别。未知的原生输出上限保持为空，请求使用配置的输出预算。

启动、账号登录、修改地址或 Key、窗口获得焦点时自动刷新，默认每隔 5 分钟同步一次；用量刷新（定时及每次请求完成后）发现方案、有效状态或订阅到期时间变化时也会立即同步。成功的后台刷新至少间隔 60 秒，期间收到的刷新请求会在冷却结束时补做一次，不会被丢弃。因协议或上下文能力未确认而隐藏的模型会列在日志和 sub2api：账号、订阅与模型 中。sub2api：刷新模型列表可跳过成功后的冷却时间，并重新检查曾被接口拒绝的模型，仍遵守错误退避和服务器的 Retry-After。网络异常、HTTP 429/5xx、账号状态查询失败或清单格式异常时，保留近期验证过的模型并自动重试：从 5 秒开始逐次翻倍，最长 15 分钟；服务器要求更长等待时按其要求执行。有效的空清单、缩减清单及能力筛选结果立即生效。

缓存和重试冷却时间在重载后保留，按地址、Key 和协议隔离。临时通信故障期间，模型自最后一次成功取得可信参数起最多保留 24 小时；旧版宽松规则产生的缓存会重新验证。明确的 Key 认证失败、订阅停用或 Key 不匹配立即清空自动模型。真实调用明确返回“模型不存在”或“模型不受支持”时，该模型在当前接口范围内隐藏最多 24 小时，后台同步继续保留这一结果；手动刷新可重新检查已经修复的路由。额度不足、并发限制、请求参数错误及临时服务故障仍保留模型。开启自动发现但尚未取得可信清单或缓存时，选择器保持为空。excludedModels 可隐藏指定模型；关闭 autoDiscoverModels 后使用明确选择的手动模型。模型发现只发送元数据请求。

设置	默认值	可选值或范围	用途与建议
`sub2api.baseUrl`	空	HTTP 或 HTTPS URL	基础地址或完整推理 URL。应首先配置；为空时不会访问任何服务器。
`sub2api.apiFormat`	`openai-responses`	`openai-responses`、`openai-completions`、`anthropic-messages`	选择请求协议和路径。网关支持时优先使用 Responses。
`sub2api.enabledModels`	Sol、Terra、Luna、GPT-5.4 Mini、Codex Spark	模型 ID	关闭自动发现时的手动选择。为空时使用这五个默认模型；自动发现使用已验证的当前 Key 模型清单。
`sub2api.autoDiscoverModels`	`true`	布尔值	同步当前 Key 的模型，并筛选协议兼容且能力和上下文参数已确认的模型。
`sub2api.modelRefreshMinutes`	`5`	`0`–`1440`	定时同步间隔，单位为分钟。`0` 仅关闭定时器；启动、修改地址或密钥、窗口重新获得焦点、用量刷新发现订阅变化及手动刷新仍会同步。
`sub2api.excludedModels`	`[]`	模型 ID	从 Chat、Auto 和 Git 选择器中隐藏指定模型，优先于自动发现和 enabledModels。
`sub2api.commitMessageLanguage`	`zh`	`zh`、`en`	选择 Conventional Commit 标题说明和正文使用简体中文或英文；类型和作用域仍采用标准小写 ASCII。
`sub2api.commitMessageModel`	`gpt-5.6-terra`	模型 ID 或网关别名	专用于生成提交消息的模型，引导选择器包含自动发现的新模型。
`sub2api.commitMessageReasoningEffort`	`medium`	`none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`	专用于提交消息的思考级别；模型不支持的级别会自动调整。
`sub2api.showAutoModel`	`true`	布尔值	显示 `sub2api · Auto Adaptive`，它只会在已启用模型之间路由。
`sub2api.reasoningOverride`	`model`	`model`、`low`、`medium`、`high`、`xhigh`、`max`	默认思考级别。按模型保存的原生选择优先，交互调整使用模型菜单。
`sub2api.autoModelScope`	`sub2api`	`sub2api`、`all`、`selected`	Auto Adaptive 可使用的来源，外部来源沿用自己的认证和计费。
`sub2api.autoModelSources`	`["sub2api"]`	提供器 ID 数组	`selected` 模式允许的来源，可通过配置自动路由范围命令多选。
`sub2api.autoRoutingMode`	`adaptive`	`adaptive`、`pinned`	根据实质性新任务重新选择，或保持初始兼容模型。
`sub2api.autoReasoningMode`	`pinned`	`pinned`、`perTurn`	`pinned` 保持同一任务的档位，自适应路由遇到实质性新任务时可重新选择；`perTurn` 每轮重新评估。
`sub2api.contextWindowCap`	`0`	`0` 或 `16384`–`1050000`	`0` 使用网关元数据或模型目录限制。仅在明确知道网关上下文更小时设置自定义总限制。
`sub2api.maxOutputTokens`	`32768`	整数，最小 `1024`	最大输出预算，包含推理 Token。值越大，模型选择器公布的可用输入容量越小。
`sub2api.contextSafetyMarginTokens`	`8192`	`0`–`65536`	为分词差异和请求开销预留的输入 Token。网关在限制附近拒绝请求时可增大。
`sub2api.contextTrimMode`	`auto`	`auto`、`off`	接近已配置或已学习限制后，启用提供器侧自适应历史裁剪。
`sub2api.requestSafetyRatio`	`0.85`	`0.5`–`0.95`	创建新稳定裁剪边界时，保留已配置或已学习输入限制的比例。
`sub2api.includeEncryptedReasoning`	`true`	布尔值	请求并重放加密推理项，保持无状态 Responses 工具调用连续性。仅在网关不兼容时关闭。
`sub2api.promptCacheMode`	`auto`	`auto`、`explicit`、`implicit`、`off`	`auto` 使用兼容性优先的隐式缓存；确认网关支持 GPT-5.6 断点后才使用 `explicit`。
`sub2api.promptCacheScope`	`family`	`family`、`model`	`family` 在 GPT-5.6 别名间共享路由亲和性；`model` 为每个精确模型 ID 隔离路由。
`sub2api.requestTimeoutSeconds`	`600`	`30`–`3600`	单次模型请求总超时。长推理任务或慢网关可适当增大。
`sub2api.maxConcurrentRequests`	`16`	`1`–`100`	相同端点和 API Key 的最大并发请求数。请保持在网关和上游账号允许的范围内。
`sub2api.concurrencyRetryCount`	`3`	`0`–`5`	仅在尚未产生输出时，重试网关明确返回的并发限制错误。
`sub2api.concurrencyRetryDelaySeconds`	`3`	`0`–`30`	并发限制重试初始延迟，后续使用有上限的指数退避。
`sub2api.streamRetryCount`	`3`	`0`–`5`	在输出前针对已识别的瞬时 SSE 读取故障追加重试。重试复用同一逻辑请求 ID，但上游仍可能重复计费。
`sub2api.streamRetryDelaySeconds`	`1`	`0`–`30`	瞬时流故障重试初始延迟，后续使用有上限的指数退避。
`sub2api.preservePartialStreamOutput`	`true`	布尔值	瞬时流故障发生在输出开始后时，保留已交付给 Chat 的内容，不重放文本或工具调用。
`sub2api.connectionRetryCount`	`3`	`0`–`5`	重试能够证明发生在 TLS 或 HTTP 发送前的连接失败，不会造成重复计费。
`sub2api.connectionRetryDelaySeconds`	`1`	`0`–`10`	安全连接重试初始延迟，后续使用有上限的指数退避。
`sub2api.networkRetryCount`	`0`	`0`–`2`	对输出前但发送状态不明确的传输失败选择性重试。除非能接受重复请求和计费风险，否则保持 `0`。
`sub2api.networkRetryDelaySeconds`	`2`	`0`–`30`	可选不明确网络重试的初始延迟。
`sub2api.httpRetryCount`	`2`	`0`–`2`	仅在收到 HTTP 502/503/504 且尚未交付任何输出时追加重试。`0` 关闭自动恢复，仍可能重复计费。
`sub2api.httpRetryDelaySeconds`	`2`	`0`–`30`	HTTP 重试基础延迟。优先使用 Retry-After 秒数或 HTTP 日期，否则指数退避，每次等待最多 30 秒。
`sub2api.usageEndpoint`	`auto`	`auto`、空值或完整 URL	`auto` 推导 `/v1/usage`；空值关闭服务端额度请求；完整 URL 覆盖默认地址。
`sub2api.usageRequestTimeoutSeconds`	`30`	`5`–`300`	用量与余额请求超时；并发刷新会共享同一个在途请求。
`sub2api.usageRefreshMinutes`	`5`	`0`–`1440`	后台刷新用量和余额的分钟间隔；`0` 关闭周期刷新。
`sub2api.debugLogging`	`false`	布尔值	记录经过脱敏的请求元数据和 SSE 事件名。默认省略错误正文；启用后也会先脱敏再记录。

HTTP 502/503/504 自动恢复默认最多追加两次请求（合计三次尝试），复用同一逻辑请求 ID、Idempotency-Key 和完整 body，包括缓存字段；这些状态不会触发缓存降级。取消会结束等待并阻止下一次尝试，此策略不会重放已经交付的文本、工具调用或其他输出。HTTP 400/401/403 不参与瞬时 HTTP 重试，原有针对受支持错误状态的显式缓存兼容性回退仍独立保留。网络、并发和流式重试预算各自独立，错误类型变化时可能增加尝试次数。自动恢复不能保证成功；预算耗尽后显示简短本地化错误，脱敏诊断保留在 sub2api 输出频道。502 不能证明上游尚未执行请求或未计费，网关也可能忽略 Idempotency-Key，因此仍可能重复执行或重复计费。

修改模型、协议、上下文或缓存设置后，如需进行干净对比，请新建 Chat。曾拒绝显式缓存的网关在升级或重新配置后，可运行 sub2api：重新检测提示词缓存兼容性 清除检测记录。

插件会把已识别的 stream_read_error、SSE 提前终止及同类上游流故障与普通网络重试分开处理。输出开始前会使用同一逻辑请求 ID 自动退避重试；输出开始后默认保留部分响应并结束本轮，不重放已经交付的内容。

API 格式

sub2api.apiFormat 控制请求协议：

设置	请求路径	思考字段
`openai-responses`（默认）	`/v1/responses`	`reasoning.effort`
`openai-completions`	`/v1/chat/completions`	`reasoning_effort`
`anthropic-messages`	`/v1/messages`	扩展思考 Token 预算

扩展会把所选协议的路径自动追加到基础地址。切换格式时，已知的完整推理路径会被替换。仅接受 HTTP 和 HTTPS 地址，并拒绝 URL 中嵌入的凭据。

Responses 请求会发送 stream: true、store: false 和稳定的 prompt_cache_key。默认的 auto 模式优先使用兼容性更好的隐式缓存，因为部分 sub2api 网关会把 GPT-5.6 显式缓存字段转换为不透明的 HTTP 502。只有确认网关支持这些字段时才应选择 explicit。

自动模型路由

在 Chat 模型选择器中选择 sub2api · Auto Adaptive 即可使用内置本地分类，不需要 Jev Key、额外服务或分类器 API 调用。默认仅在当前账号清单或手动模式启用的 sub2api 模型中选择。

运行命令 sub2api：配置自动路由范围，或在“管理提供器”中打开“自动路由范围”，可选择：

仅 sub2api（默认）：只使用已启用且与当前协议兼容的 sub2api 模型。
全部可用来源：考虑 VS Code 各提供器公开的模型，排除自动路由器和能力不匹配的模型。
指定来源：多选提供器，例如 sub2api、copilot 或已安装的其他来源。来源使用 VS Code 的 vendor ID；同一提供器下的多个账号不能由此分别勾选。没有可用候选时会报错，不会越过勾选范围回退。

对应设置为 sub2api.autoModelScope（sub2api、all、selected）和 sub2api.autoModelSources（默认 ["sub2api"]）。它们保存在用户级配置。选择外部来源后，本次对话会交给该提供器，沿用它自己的认证、协议、配额和计费；首次使用可能由 VS Code 提示授权。sub2api 密钥不会转交，sub2api 用量栏也不统计外部来源费用。

分类只分析当前用户任务，工具返回和历史日志不会单独提高难度。简单、均衡和复杂任务分别优先匹配轻量、通用和高能力模型；sub2api 中通常对应 Luna、Terra、Sol。默认 sub2api.autoRoutingMode: adaptive 允许实质性新请求升级模型或在短上下文中降级；工具往返、“继续”和相同请求复用路由。估算历史达到 8K Token 时抑制降级，以减少缓存重建；能力或上下文不匹配仍会重新选择。pinned 保留原来的固定模型策略。

sub2api 内自动思考只采用所选模型声明的原生档位，名称保持 low、medium、high、xhigh、max 等。VS Code 未统一公开外部模型的思考配置 schema，因此外部来源沿用自身默认配置，不转发 sub2api 的思考参数。工具和图片任务只选择已公开相应能力的模型；外部请求还会使用提供器的 Token 计数检查输入上限。

这是启发式路由，并未使用实时价格或质量评测，不能保证最高性价比或确定节省比例。日志记录来源、模型、判断原因和切换决策，不记录分类文本。必须指定模型时，直接在 Chat 中选择该模型。

思考级别

在直接使用扩展模型配置的 Copilot Chat 中，打开模型菜单并点击 sub2api 模型右侧的箭头，可以选择“上下文大小”和“思考级别”。VS Code 按模型保存选择，只显示该模型支持的思考级别。Auto Adaptive 还提供“自动”选项。原生菜单中的思考级别优先于旧的全局选择器。

VS Code Insiders 1.141 的 Agent Host 会通过 BYOK 桥接重新生成菜单。已核对的构建 e468533536 只传递思考档位与模型 Token 上限，不传递扩展的上下文选项及档位显示名称，因此菜单可能只有“思考层级”，并显示“高”“极高”等宿主本地化名称。插件默认提供独立的上下文状态栏入口，点击即可选择输入额度，不依赖宿主提供原生上下文菜单。

状态栏默认显示 sub2api 用量和“sub2api 上下文 256K”。点击上下文入口，或运行 sub2api：选择上下文大小，可选择模型最大值、256K、512K、768K、1M；选择保存在用户级 sub2api.inputTokenCap，默认 256000（256K），0 使用全部可用额度。自定义默认值从 256K 起步，旧的较小全局额度在升级后自动调整为 256K。该设置作为各类客户端的共同默认值，适用于通过插件发送的请求（含 Auto 路由）。按模型或按请求设置的上下文大小优先，可以在模型及网关允许的范围内超过此默认值。输出预算与安全余量单独保留。选择后刷新原生菜单默认值，未单独设置上下文的请求使用新设置。

VS Code Insiders 1.144 的分页模型选择器会把每个提供方页签的高度统一为内置 Copilot 页签的高度；该页签只有 Auto 时，sub2api 页签只能显示约一行，需要滚动查看。状态栏的“sub2api 模型”入口（也可运行 sub2api：选择聊天模型（完整列表））会打开完整列表，按自动、强力、均衡、轻量分组，并显示上下文大小和思考级别；可输入名称或模型 ID 筛选。选中后通过 VS Code 自带的 workbench.action.chat.changeModel 命令切换当前窗口的聊天输入框。模型同时提供原生选择器的类别标签；清单缓存、权限未确认或已学习的网关上限会显示在模型悬停提示中。

Language Model API 客户端可通过 modelOptions.contextSize 传入额度；原生 modelConfiguration 和桥接 configuration 同样支持。请求显式传入的 modelOptions 优先，其次采用宿主的 modelConfiguration 或桥接 configuration，以免宿主自动填充的默认值覆盖请求选择。

需要修改全局思考默认值时，可在命令面板运行 sub2api：选择思考级别，或从“管理提供器”菜单进入；宿主明确传入的思考档位仍然优先。

每个上游模型在模型选择器中只出现一次，旧会话中的 model::effort 标识仍可继续使用。

sub2api.autoReasoningMode 默认为 pinned：Auto Adaptive 保持同一任务的思考级别以提高缓存局部性；使用自适应路由时，实质性新任务可以重新选择。将其改为 perTurn 后会逐轮重新评估，但思考级别变化可能进入不同的缓存分区。扩展提供的档位名称保持模型原生名称，不将 GPT 的 xhigh 套用到只支持 max 的模型；Agent Host 的显示名称受上述宿主行为影响。

上下文与压缩

原生“上下文大小”控制输入 Token 上限，输出额度和安全余量单独预留。预设额度为 256K、512K、768K、1M，另保留有效的自定义默认值和当前最大值，并按模型及网关上限筛选。本身可用输入不足 256K 的模型只显示真实最大值。初始值采用 sub2api.inputTokenCap，默认为 256000（256K），其中 0 使用全部可用输入额度。全局 sub2api.contextWindowCap 仍用于限制总上下文；调用方显式传入的较小请求额度也继续生效。当前输入本身超过所选额度时，需要增大上下文或缩短输入。

模型目录保存总上下文窗口和最大输出。扩展按下式计算模型选择器中公布的输入上限：

最大输入 Token = 总上下文窗口 - 所选输出预算 - 安全余量

默认输出预算为 32,768，安全余量为 8,192。对于 1.05M 上下文模型，可用输入因此为 1,009,040 Token，而不是始终预留完整的 128K 最大输出。

模型	总上下文窗口	最大输出
GPT-5.3 Codex Spark	128,000	32,000
Codex Mini	200,000	100,000
GPT-5.2、GPT-5.4 Mini	400,000	128,000
GPT-5.4、GPT-5.5、GPT-5.6 系列、GPT-6 Astra	1,050,000	128,000

自动发现时，扩展读取当前 Key 模型清单中的 max_context_window，缺失时读取 context_window，再以已核实的模型原生上限为限；两个字段均缺失时沿用内置模型参数。Sub2API 可能根据配置规则生成这些字段，因此清单中的数值按网关声明的预算处理。Copilot 原生菜单展示扩展提供的额度，不额外探测上游最大容量。

兼容网关可能设置更小的实际限制。如果网关返回上下文窗口错误，扩展仍会学习一个保守的端点、模型和协议专属输入预算，将其保存到 VS Code 全局状态，并自动重试一次。

如果学习上限已经过时，或来自网关的临时错误，可在上下文菜单中选择清除已学习的网关上限。该操作只恢复当前服务地址和 API 格式的模型目录上限，不会删除其他服务地址的学习记录。

自适应裁剪会保留带指纹的稳定边界。后续轮次复用相同前缀，直到会话再次接近已学习的限制，减少每轮移动首条保留消息导致的冷缓存请求。

在命令面板运行 sub2api：管理上下文与压缩，或从“管理提供器”菜单进入上下文管理，可以：

仅压缩下一次请求；
启用自适应裁剪（默认）；
关闭提供器侧自动裁剪；
清除当前服务地址和 API 格式的学习上限；
打开上下文设置。

sub2api.contextWindowCap 保持为 0 时使用网关元数据与模型目录确定的总上下文窗口。仅在明确知道网关限制更小时设置该值，且自定义值不得低于 16384。

提供器侧裁剪只能保留最近的序列化消息，不能生成语义摘要。语义压缩由 VS Code/Copilot 管理；旧细节很重要时，请使用 Chat 的压缩功能或新建会话。

用量、缓存与余额

用量状态栏会在 /v1/usage 返回额度数据时显示已用和剩余美元额度，否则显示最近缓存命中率及当前 VS Code 会话累计 Token。悬停可查看输入、缓存读取、未缓存输入、缓存写入、输出和会话总量；点击可打开用量面板。

当 sub2api.usageEndpoint 为 auto 时，扩展从 API 地址推导 /v1/usage，默认每五分钟及请求完成后刷新。即使该接口不可用，仍会从推理响应中统计请求和会话 Token。

状态栏、悬停详情、选择器、通知和命令标题会在 VS Code 显示语言以 zh 开头时使用中文，否则使用英文。

默认的 sub2api.promptCacheScope: family 在 GPT-5.6 Sol、Terra、Luna 和基础别名之间共享稳定路由键。该键可提高网关亲和性，但不能让不同模型后端共享模型专属 KV 缓存。若网关要求按精确模型路由，可改为 model。

在 explicit 模式下，扩展会按端点路径、协议和模型记住被拒绝的缓存功能，记录不包含 API Key 或提示词数据，并在七天后过期。升级或重新配置网关后，可运行 sub2api：重新检测提示词缓存兼容性 清除记录。

隐私与安全

API Key 存储在 VS Code SecretStorage 中，不写入设置。
提示词内容和 API Key 不会写入日志。
配置服务地址前，扩展不会预设或访问任何端点。
请自行审查所用服务的隐私、数据保留和计费政策。

联系与支持

官方网站：vortelyn.cn
技术支持与商务联系：contact@vortelyn.cn

故障排查

运行 sub2api：显示日志 查看请求编号、匿名请求指纹、协议、模型、输入限制、Token 估算、缓存策略、缓存断点、路由指纹、用量和服务端错误正文。日志不会包含提示词或 API Key。

SUB2API_CONTEXT_WINDOW_EXCEEDED 表示网关拒绝了官方或已学习的上下文限制。扩展会学习该错误并重试一次；若仍然失败，请检查日志中的学习预算，降低 sub2api.contextWindowCap，或新建会话。

SUB2API_CONCURRENCY_LIMIT 表示网关拒绝了同一账户的并发请求。扩展会在同一 VS Code 扩展宿主内，按端点来源和 API Key 串行化请求；只有尚未输出文本或工具调用时才会安全重试。

顶层 fetch failed 表示没有收到完整 HTTP 响应。扩展会记录经过清理的 DNS、连接、TLS、Socket 和 Undici 超时代码。能够证明发生在 TLS 或 HTTP 发送前的失败默认重试三次；发送状态不明确的传输重试默认关闭，以免重复计费。

SUB2API_STREAM_TERMINATED 表示网关在所选协议正常完成前关闭了 SSE。请检查上游和反向代理超时以及 SSE 心跳。扩展不会盲目重试不完整的生成结果，以免重复消耗 Token 或重复执行工具调用。

许可证

MIT

English

Use a sub2api-compatible API directly in VS Code Chat and GitHub Copilot Agent mode. The provider is endpoint-neutral: no server address or API key is bundled.

Run sub2api: Open Documentation to open the English or Chinese document automatically based on the current VS Code display language. Use the language links above to switch documents manually.

Highlights

VS Code Stable 1.130+ and VS Code Insiders
OpenAI Responses, OpenAI Chat Completions, and Anthropic Messages protocols
Responses is the default and retains encrypted reasoning replay, stable implicit cache routing, and optional GPT-5.6 explicit cache breakpoints
Streaming text, vision, function tools, and tool results
Native model-picker controls for per-model context size and reasoning effort
One-click Conventional Commit generation from the toolbar directly above the Source Control input, with independent language, model, and reasoning settings
Official model context windows plus adaptive gateway-limit learning and stable-boundary compaction
Configurable per-endpoint/key request concurrency and safe concurrency-limit retries
Cancellable connection tests, bounded model/usage timeouts, and single-flight usage refreshes
Sanitized diagnostics that omit upstream error bodies unless debug logging is explicitly enabled
Live request/session tokens, cache-hit rate, and optional server balance
API keys stored in VS Code SecretStorage

Get started

Install from the Visual Studio Marketplace or a VSIX.
Run sub2api: Configure Endpoint and enter your API base URL.
Run sub2api: Set API Key.
Keep sub2api.apiFormat at openai-responses, or select another compatible protocol.
Run sub2api: Test Connection, open Chat, and choose a model from the sub2api provider.

Stable and Insiders use separate extension installations and SecretStorage databases. Configure the endpoint and key once in each edition you use.

Generate a Git commit message

Open Source Control and click the sparkle button in the toolbar directly above the commit-message input. The provider sends the selected Git diff to the configured sub2api endpoint, generates a concise message, and replaces the current input-box value only after a complete response is received.

In a multi-repository workspace, the button is scoped to the repository where it was clicked: only that repository's changes are read, and only its input box is updated. Different repositories can generate messages independently at the same time; a repeated request for the same repository is ignored until its current generation finishes.

If staged changes exist, only the staged changes are summarized so the message matches the next commit. If nothing is staged, working-tree and untracked changes are summarized. Untracked binary files and files larger than 1 MB are represented by metadata only; large text diffs are bounded to the selected model's safe prompt budget. Source files and the Git index are never modified.

Generated messages follow Conventional Commits 1.0.0: type(scope)!: subject, with a body and BREAKING CHANGE: footer only when justified by the diff. Types are restricted to feat, fix, docs, refactor, perf, test, build, ci, chore, style, and revert; headers target about 50 characters and are normalized to at most 72, while generated body lines are wrapped at 72. The extension asks the model for structured data and then validates and formats the final message locally, so formatting does not depend solely on prompt compliance.

The default is Simplified Chinese with gpt-5.6-terra at medium reasoning. Run sub2api: Configure Git Commit Message Generation, or open the dedicated sub2api Provider › Git Commit Messages Settings category, to change sub2api.commitMessageLanguage, sub2api.commitMessageModel, and sub2api.commitMessageReasoningEffort. This model selection is independent of the Chat model list and the global Chat reasoning selector.

Configuration

Open the configuration

Use any of these routes:

Run sub2api: Manage Provider to access the endpoint, API key, connection test, usage, reasoning, context, documentation, settings, and logs from one menu.
Run sub2api: Configure Git Commit Message Generation for a guided language, model, and reasoning selector.
Open VS Code Settings and search for @ext:vortelyn.sub2api-provider.
Open settings.json and add sub2api.* properties directly. Use Preferences: Open User Settings (JSON) from the Command Palette. Machine-scoped settings such as the endpoint are stored separately by VS Code Stable and Insiders.

The API key is the exception: configure it with sub2api: Set API Key. It is stored in VS Code SecretStorage and must not be added to settings.json.

Endpoint and API key

Run sub2api: Configure Endpoint.
Enter the base URL of the compatible gateway, preferably including its API version prefix, for example https://gateway.example.com/v1.
Run sub2api: Set API Key and enter the gateway key.
Select the matching sub2api.apiFormat.
Run sub2api: Test Connection, select an enabled model, and verify that the success notification appears.

The endpoint command accepts either a base URL or a complete known inference URL. The selected protocol determines the final request URL:

Configured value	API format	Request URL
`https://gateway.example.com/v1`	`openai-responses`	`https://gateway.example.com/v1/responses`
`https://gateway.example.com/v1`	`openai-completions`	`https://gateway.example.com/v1/chat/completions`
`https://gateway.example.com/v1`	`anthropic-messages`	`https://gateway.example.com/v1/messages`

If a complete URL ending in /responses, /chat/completions, or /messages is entered, switching sub2api.apiFormat replaces that known suffix. Trailing slashes are removed. Only HTTP and HTTPS URLs are accepted, and credentials embedded in a URL are rejected.

Recommended starting configuration

The defaults are suitable for most compatible Responses gateways. A minimal explicit user configuration is:

{
  "sub2api.baseUrl": "https://gateway.example.com/v1",
  "sub2api.apiFormat": "openai-responses",
  "sub2api.enabledModels": [
    "gpt-5.6-sol",
    "gpt-5.6-terra",
    "gpt-5.6-luna",
    "gpt-5.4-mini",
    "gpt-5.3-codex-spark"
  ],
  "sub2api.showAutoModel": true,
  "sub2api.commitMessageLanguage": "zh",
  "sub2api.commitMessageModel": "gpt-5.6-terra",
  "sub2api.commitMessageReasoningEffort": "medium",
  "sub2api.promptCacheMode": "auto",
  "sub2api.contextWindowCap": 0,
  "sub2api.maxOutputTokens": 32768
}

Do not add the API key to this JSON. Use sub2api: Set API Key instead.

Complete settings reference

Run sub2api: Account, Subscription and Models → Connect Sub2API account once to read your subscriptions. Sign in using the same account that owns the configured inference API key; email/password and two-factor authentication are supported. The password is not saved. Access/refresh tokens are stored in VS Code SecretStorage separately for each server API root, and renewed when supported. For browser CAPTCHA or SSO sites, sign in on the website and use Use an account access token with its existing auth_token from browser developer tools → Application/Storage → Local Storage. Enter it only in the extension's protected input; never in settings, logs, or chat. Imported access tokens require reconnecting when they expire. Account requests use the matching /api/v1 path on the configured server; deployments hosting their account API on another origin are not supported by this login flow.

The extension locates the exact current API key, follows its group ID, and matches an active subscription for that group and user, including start/expiry and revocation checks. Other subscriptions do not expand this key's model list. The account view shows the matched plan/group, subscription expiry and period quotas. A standard balance group is identified separately from a subscription. Without account login, subscription identity stays unconfirmed, while a gateway account manifest may still be read with the inference key.

Automatic model discovery reads the current-key Codex manifest (/models?client_version=...). Chat, Auto and Git share the models that are visible, API-supported, compatible with the selected protocol and have usable text-chat/context capabilities. Native metadata includes GPT-6.1 Sol; it appears automatically when the gateway advertises it for the current key. Generated Sub2API aliases require verified native metadata or explicit supported_endpoints, because generated visibility, API-support and context defaults alone do not establish compatibility. A valid refreshed manifest replaces the previous list, including missing or empty results. Model availability follows the configured gateway and key; publishing a model at OpenAI does not add it to a gateway account.

The manifest's maximum context (or its default budget when no maximum is supplied) limits the client budget, capped by a verified native limit when one is known. GPT-6.1 Sol has a documented 1,050,000-token context and 128,000-token maximum output; the gateway may expose a smaller budget. Its supported reasoning efforts are low, medium, high, xhigh and max. It supports tool calling through Responses; Chat Completions is advertised without tools. GPT-6 Sol/Luna use none reasoning for Chat Completions tool calling. Unknown native output limits remain unknown and requests use the configured output budget.

Models synchronize at startup, every 5 minutes, on window focus and after endpoint/key changes or account login. Usage refreshes (periodic and after each completed request) also trigger a sync when the reported plan, validity or subscription expiry changes. Successful background refreshes have a 60-second minimum interval; a refresh requested inside that interval runs once when it ends instead of being dropped. The log and sub2api: Account, Subscription and Models list models hidden because their protocol or context capabilities are unverified. sub2api: Refresh models bypasses that success cooldown and rechecks models previously rejected by the route, while respecting error backoff and Retry-After. Network, HTTP 429/5xx, account-status and malformed-manifest failures retain recent verified models and retry from 5 seconds up to 15 minutes, or longer when the server requires it. Valid empty, reduced or capability-filtered manifests take effect immediately.

Caches and retry cooldowns survive reloads and are isolated by endpoint, key and protocol. Verified availability expires 24 hours after its last successful appearance during transport failures. Older permissive caches are revalidated. Explicit key authentication failures or inactive/mismatched subscriptions clear automatic models immediately. A generation error explicitly identifying a nonexistent or unsupported model hides that model for the current route for up to 24 hours; background refreshes preserve the rejection and manual refresh rechecks it. Quota, concurrency, parameter and temporary service failures keep model availability intact. While automatic discovery is unconfirmed and has no verified cache, the pickers stay empty. excludedModels hides specific IDs; disabling autoDiscoverModels uses the explicitly selected manual models. Discovery makes metadata requests only.

Setting	Default	Allowed values / range	Purpose and guidance
`sub2api.baseUrl`	empty	HTTP or HTTPS URL	Base or complete inference URL. Configure this first; no server is contacted while it is empty.
`sub2api.apiFormat`	`openai-responses`	`openai-responses`, `openai-completions`, `anthropic-messages`	Selects the wire protocol and request path. Responses is recommended when supported.
`sub2api.enabledModels`	Sol, Terra, Luna, GPT-5.4 Mini, Codex Spark	Model IDs	Manual selection when discovery is disabled. Empty uses these five defaults; automatic discovery uses the verified current-key catalog.
`sub2api.autoDiscoverModels`	`true`	Boolean	Synchronize current-key models with compatible API protocol and verified capabilities/context.
`sub2api.modelRefreshMinutes`	`5`	`0`–`1440`	Periodic synchronization interval. `0` disables only the timer; startup, endpoint/key changes, window focus, subscription changes reported by usage refresh and manual refresh still synchronize.
`sub2api.excludedModels`	`[]`	Model IDs	Hide models from Chat, Auto and the Git picker; takes precedence over discovery and enabledModels.
`sub2api.commitMessageLanguage`	`zh`	`zh`, `en`	Selects Simplified Chinese or English for the Conventional Commit subject and body; type and scope remain standard lowercase ASCII.
`sub2api.commitMessageModel`	`gpt-5.6-terra`	Model IDs or gateway aliases	Dedicated model for commit-message generation; the guided picker includes discovered models.
`sub2api.commitMessageReasoningEffort`	`medium`	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`	Dedicated reasoning effort for commit messages. Unsupported levels are normalized for the selected model.
`sub2api.showAutoModel`	`true`	Boolean	Shows `sub2api · Auto Adaptive`. It only routes among enabled models.
`sub2api.reasoningOverride`	`model`	`model`, `low`, `medium`, `high`, `xhigh`, `max`	Default reasoning selection. Per-model native choices take priority; use the model menu for interactive changes.
`sub2api.autoModelScope`	`sub2api`	`sub2api`, `all`, `selected`	Eligible providers for Auto Adaptive. External providers retain their own authentication and billing.
`sub2api.autoModelSources`	`["sub2api"]`	Provider ID array	Allowed providers in `selected` scope; configure with the automatic routing scope command.
`sub2api.autoRoutingMode`	`adaptive`	`adaptive`, `pinned`	Reassess substantive new tasks, or retain the initial compatible model.
`sub2api.autoReasoningMode`	`pinned`	`pinned`, `perTurn`	`pinned` preserves effort within the same task; a substantive new task can reassess it in adaptive routing. `perTurn` re-evaluates each turn.
`sub2api.contextWindowCap`	`0`	`0` or `16384`–`1050000`	`0` uses gateway metadata or catalog limits. Set a custom total limit only when the gateway is known to expose less context.
`sub2api.maxOutputTokens`	`32768`	Integer, minimum `1024`	Maximum output budget including reasoning tokens. A larger value reduces advertised input capacity.
`sub2api.contextSafetyMarginTokens`	`8192`	`0`–`65536`	Input tokens reserved for tokenizer variance and request overhead. Increase it if a gateway rejects requests near the limit.
`sub2api.contextTrimMode`	`auto`	`auto`, `off`	Enables adaptive provider-side history trimming after a configured or learned limit is approached.
`sub2api.requestSafetyRatio`	`0.85`	`0.5`–`0.95`	Fraction of a configured or learned input limit retained when creating a new stable trim boundary.
`sub2api.includeEncryptedReasoning`	`true`	Boolean	Requests and replays encrypted reasoning items for stateless Responses tool-call continuity. Disable only for an incompatible gateway.
`sub2api.promptCacheMode`	`auto`	`auto`, `explicit`, `implicit`, `off`	`auto` is compatibility-first implicit caching; use `explicit` only after confirming GPT-5.6 breakpoint support.
`sub2api.promptCacheScope`	`family`	`family`, `model`	`family` shares routing affinity among GPT-5.6 aliases; `model` isolates every exact model ID.
`sub2api.requestTimeoutSeconds`	`600`	`30`–`3600`	Overall timeout for one model request. Increase it for long reasoning jobs or slow gateways.
`sub2api.maxConcurrentRequests`	`16`	`1`–`100`	Maximum simultaneous requests for the same endpoint and API key. Keep it within the gateway and upstream account limits.
`sub2api.concurrencyRetryCount`	`3`	`0`–`5`	Retries an explicit upstream concurrency rejection only before any output is emitted.
`sub2api.concurrencyRetryDelaySeconds`	`3`	`0`–`30`	Initial concurrency retry delay; later attempts use bounded exponential backoff.
`sub2api.streamRetryCount`	`3`	`0`–`5`	Additional attempts for recognized transient SSE read failures before output. The same logical request ID is reused, although upstream billing can still be duplicated.
`sub2api.streamRetryDelaySeconds`	`1`	`0`–`30`	Initial transient-stream retry delay; later attempts use bounded exponential backoff.
`sub2api.preservePartialStreamOutput`	`true`	Boolean	Keeps content already delivered to Chat when a transient stream fails after output starts, instead of replaying text or tool calls.
`sub2api.connectionRetryCount`	`3`	`0`–`5`	Retries failures proven to happen before TLS or HTTP transmission, where duplicate billing is not possible.
`sub2api.connectionRetryDelaySeconds`	`1`	`0`–`10`	Initial safe connection retry delay; later attempts use bounded exponential backoff.
`sub2api.networkRetryCount`	`0`	`0`–`2`	Opt-in retry for ambiguous transport failures before output. Keep `0` unless duplicate-request and billing risk is acceptable.
`sub2api.networkRetryDelaySeconds`	`2`	`0`–`30`	Initial delay for optional ambiguous network retries.
`sub2api.httpRetryCount`	`2`	`0`–`2`	Additional attempts after a received HTTP 502/503/504, only before any output. `0` disables this recovery; duplicate billing remains possible.
`sub2api.httpRetryDelaySeconds`	`2`	`0`–`30`	Base delay for HTTP retries. Uses Retry-After (seconds or HTTP date), otherwise exponential backoff, capped at 30 seconds per wait.
`sub2api.usageEndpoint`	`auto`	`auto`, empty, or full URL	`auto` derives `/v1/usage`; an empty value disables server quota requests; a full URL overrides the endpoint.
`sub2api.usageRequestTimeoutSeconds`	`30`	`5`–`300`	Timeout for usage and balance requests. Concurrent refreshes share one in-flight request.
`sub2api.usageRefreshMinutes`	`5`	`0`–`1440`	Background usage and balance refresh interval. `0` disables periodic refresh.
`sub2api.debugLogging`	`false`	Boolean	Logs sanitized request metadata and SSE event names. Error bodies are omitted unless debug logging is enabled and are sanitized before logging.

HTTP 502/503/504 recovery adds at most two requests by default (three attempts total), reusing the same logical request ID, Idempotency-Key and body, including cache fields. These statuses never trigger cache downgrades. Cancellation stops waiting and prevents another attempt; content already delivered, including tool calls, is never replayed by this policy. HTTP 400/401/403 do not use transient HTTP retries; the existing explicit-cache compatibility fallback for supported error statuses remains separate. Network, concurrency and stream retry budgets remain separate and can add attempts if the failure type changes. Recovery cannot guarantee success: an exhausted HTTP failure produces a short localized error, with sanitized diagnostics in the sub2api output channel. A 502 does not prove that the upstream did not execute or bill the request. The gateway may ignore Idempotency-Key, so repeated processing or billing remains possible.

After changing model, protocol, context, or cache settings, start a new Chat when you need a clean comparison. Use sub2api: Re-detect Prompt Cache Compatibility after upgrading or reconfiguring a gateway that previously rejected explicit caching.

Recognized stream_read_error, premature SSE termination, and equivalent upstream stream failures are recovered separately from generic network retries. Before output starts, the provider retries automatically with bounded backoff and the same logical request ID. After output starts, the default behavior preserves the partial response and completes the turn without replaying already delivered content.

API formats

The sub2api.apiFormat setting controls the wire protocol:

Setting	Request path	Reasoning field
`openai-responses` (default)	`/v1/responses`	`reasoning.effort`
`openai-completions`	`/v1/chat/completions`	`reasoning_effort`
`anthropic-messages`	`/v1/messages`	Extended-thinking token budget

A base URL receives the selected suffix automatically. A full known inference URL is replaced when you switch formats. Only HTTP and HTTPS endpoints are accepted, and credentials embedded in URLs are rejected.

Responses sends stream: true, store: false, and a stable prompt_cache_key. The default auto mode uses compatibility-first implicit caching because some sub2api gateways turn explicit GPT-5.6 cache fields into an opaque HTTP 502. Select explicit only for a gateway known to support those fields; it then uses a fixed startup breakpoint, the previous user boundary for reading the prior round's cache, and the current user boundary for writing the next round's cache. Compatibility fallback is attempted only when the server explicitly identifies an unsupported cache field. A generic 500/502 is never treated as permission to resend the full prompt. Chat Completions uses stream_options.include_usage. Anthropic Messages sends the required Anthropic version header as well as the configured gateway key.

Automatic model routing

Choose sub2api · Auto Adaptive in the Chat model picker to use the built-in local classifier. No Jev key, extra service or classifier API call is required. The default scope includes only enabled sub2api models from the current account catalog or manual configuration.

Run sub2api: Configure Automatic Routing Scope, also available from Manage Provider, to select:

sub2api only (default): enabled sub2api models compatible with the configured protocol.
All available sources: models exposed by VS Code providers, excluding automatic routers and incompatible capabilities.
Selected sources: select multiple providers by their VS Code vendor IDs. Separate accounts under the same vendor cannot be selected independently. An empty or incompatible scope fails without falling back outside the selected sources.

The user-level settings are sub2api.autoModelScope (sub2api, all, selected) and sub2api.autoModelSources (default ["sub2api"]). External requests send the conversation through the selected provider using its authentication, protocol, quota and billing. VS Code may ask for first-use consent. The sub2api API key is never forwarded, and its usage status does not include external-provider charges.

Classification evaluates the current user task rather than tool output or accumulated logs. Simple, balanced and complex tasks prefer lightweight, general and higher-capability models; within sub2api these typically correspond to Luna, Terra and Sol. The default sub2api.autoRoutingMode: adaptive upgrades for substantive harder requests and can downgrade in short conversations. Tool loops, continuations and repeated requests reuse the route. At an estimated 8K history tokens, downgrades are suppressed to preserve cache locality. Capability and context limits still require a compatible candidate. Set pinned to retain the initial model while compatible.

Automatic sub2api effort uses only the selected model's declared native levels, with raw labels such as low, medium, high, xhigh and max. VS Code does not expose a universal external reasoning configuration schema, so external models retain their provider defaults; sub2api reasoning parameters are not forwarded. Tool and image tasks require declared capabilities. External input is checked with the provider's token counter before sending.

Model tiers are heuristics without live pricing or calibrated quality measurements; optimal cost and savings are not guaranteed. Logs include source, model, reason labels and route decisions, not classification text. Select a model directly when an exact choice is required.

Reasoning selector

In Copilot Chat sessions that use extension model configuration directly, open the model picker and use the arrow beside a sub2api model to choose Context Size and Reasoning Effort. Choices are saved per model by VS Code. Only supported reasoning levels are shown; Auto Adaptive also offers Automatic. A native reasoning choice takes priority over the legacy global selector.

VS Code Insiders 1.141 Agent Host rebuilds the menu through its BYOK bridge. The verified build e468533536 forwards reasoning levels and model token limits, but not the extension's context options or effort display labels. Its menu can therefore show only Thinking Level, with host-localized labels. The extension provides its own context status bar entry by default, so selecting an input budget does not depend on the host exposing the native context menu.

The status bar shows sub2api usage and sub2api Context 256K by default. Click the context entry or run sub2api: Select Context Size to choose Model maximum, 256K, 512K, 768K or 1M. The selection is saved in the user-level sub2api.inputTokenCap; the default is 256000 (256K), and 0 uses the full available budget. Custom defaults start at 256K; older smaller global values are upgraded to 256K. This is a shared default for clients without a context selection. A per-model or per-request choice takes priority and can be larger than this default, within the model and gateway limits. Output tokens and safety margin remain separate. Selection refreshes the native menu default and applies to the next request without a per-model override. Language Model API clients can pass contextSize through modelOptions; native modelConfiguration and bridge configuration are also accepted. An explicit modelOptions value takes priority over the host's model configuration, which also contains automatically populated schema defaults.

VS Code Insiders 1.144's tabbed model picker sizes every provider tab to the built-in Copilot tab. When that tab holds only Auto, the sub2api tab shows about one row and must be scrolled. The status bar entry sub2api Models, also available as sub2api: Select Chat Model (Full List), opens the complete list grouped as Auto, Powerful, Versatile and Lightweight, with context size and reasoning levels; type to filter by name or model ID. The choice is applied through VS Code's own workbench.action.chat.changeModel command to the chat inputs in the current window. Models also carry the native picker category, and notes about a cached manifest, unconfirmed access or a learned gateway limit appear in the model hover.

To change the global reasoning default, run sub2api: Select Reasoning Effort from the Command Palette or open it through Manage Provider; an explicit effort supplied by the host still takes priority.

Each enabled upstream model appears only once in the model picker. Legacy model::effort IDs remain accepted for existing chats.

With sub2api.autoReasoningMode: pinned (default), Auto Adaptive keeps effort stable within the same task for cache locality. Adaptive routing can reassess effort for a substantive new task. Set perTurn to reassess every turn, accepting that changes may enter a different upstream cache partition. Extension-provided labels retain native names: GPT's xhigh is not imposed on models that support max instead. Agent Host display labels remain subject to the host behavior described above.

Context and compaction

The native Context Size control limits input tokens. Output tokens and the safety margin are reserved separately. Presets are 256K, 512K, 768K and 1M; a valid custom default and the current maximum are also included, within model and gateway limits. A model with less than 256K available input shows only its actual maximum. The initial selection follows sub2api.inputTokenCap, which defaults to 256000 (256K); 0 uses the full available input budget. The global sub2api.contextWindowCap remains a total-window cap. Smaller explicit request budgets supplied by callers are still honored. If the current input alone exceeds the selected budget, choose a larger size or shorten the input.

The catalog stores each model's total context window and maximum output. For each picker entry, the provider now calculates:

maxInputTokens = total context window - selected output budget - safety margin

With the default 32,768 output budget and 8,192 safety margin, this leaves 1,009,040 input tokens on a 1.05M model instead of permanently reserving the full 128K maximum output.

Models	Total context window	Maximum output	Source
GPT-5.3 Codex Spark	128,000	32,000	sub2api gateway-specific model limit
Codex Mini	200,000	100,000	OpenAI model page
GPT-5.2, GPT-5.4 Mini	400,000	128,000	GPT-5.2, GPT-5.4 Mini
GPT-5.4, GPT-5.5, GPT-5.6 variants, GPT-6 Astra	1,050,000	128,000	GPT-5.4, GPT-5.5, GPT-5.6 Sol

Automatic discovery reads max_context_window from the current-key manifest, falling back to context_window, and caps it at a verified native limit when known. When both fields are absent, it retains the built-in model limits. Sub2API can generate these fields from configured rules, so they are treated as gateway-declared budgets. Copilot's native menu displays the provider's budget; it does not independently probe the upstream maximum.

A compatible gateway can expose a smaller effective limit than the upstream model. If the gateway returns a context-window error, the provider still learns a conservative endpoint/model/protocol-specific input budget, persists it in VS Code global state, updates the picker limit, and retries once without collapsing the conversation to a fixed 120K suffix.

If a learned limit is stale or came from a transient gateway error, choose Clear learned gateway limits in the context menu. This restores catalog limits for the current endpoint and API format without removing limits learned for other endpoints.

Adaptive trimming preserves a fingerprinted boundary. Later turns reuse the same retained prefix until the conversation reaches the learned limit again; only then is a new boundary created with the configured headroom. This reduces the repeated cold-cache requests caused by shifting the first retained message on every turn.

Run sub2api: Manage Context and Compaction from the Command Palette, or open context management through Manage Provider, to:

compact the next request once;
enable adaptive trimming (default);
disable provider-side automatic trimming;
clear learned gateway limits for the current endpoint and API format; or
open context settings.

Leave sub2api.contextWindowCap at 0 to use the total context window determined from gateway metadata and the model catalog. Set it only when you already know the gateway's smaller total limit; custom values must be at least 16384. Version 1.0.15 automatically repairs legacy values from 1 through 16383 back to 0, because an accidental value such as 1 makes Copilot discard its entire prompt before invoking the provider. sub2api.requestSafetyRatio controls how much of a configured or learned input limit is retained when a new stable boundary is created; its default of 0.85 leaves room for several later turns.

Provider-side trimming keeps recent serialized messages but cannot create a semantic summary. VS Code/Copilot owns chat-level semantic compaction; when the old details are important, use Chat's compact action if available or start a fresh chat.

If Copilot invokes the provider with an empty message array, version 1.0.14 and later block the call locally before endpoint lookup or network I/O, so it cannot be billed. The most common confirmed cause is an invalid one-token sub2api.contextWindowCap; version 1.0.15 repairs that setting before registering the provider, allowing Copilot to render and send the real semantic-summary prompt.

Usage, cache, and balance

The usage status item shows spent and remaining USD allowance when /v1/usage supplies quota data; otherwise it shows the latest cache hit rate and cumulative tokens for this VS Code session. Hover it for input, cached, uncached, cache-write, output, and session totals. Click it to open the usage panel.

With sub2api.usageEndpoint: auto, the provider derives /v1/usage and refreshes it every five minutes and after completed requests. Compatible deployments can supply API-key quota (used, remaining, and limit), wallet balance, subscription daily/weekly/monthly windows, rate limits, today/total actual cost, and model statistics. If that endpoint is unavailable, request/session token metrics still work from inference responses. Status bars, hover details, selectors, notifications, and command titles automatically use Chinese when the VS Code display language starts with zh; otherwise they use English. Use a full sub2api.usageEndpoint override for deployments with a different path, or set it to an empty string to disable quota requests.

Responses cache routing is derived from the complete endpoint path, workspace, and cache scope. The default sub2api.promptCacheScope: family shares one affinity route and stable trim route across GPT-5.6 Sol, Terra, Luna, and base aliases; unrelated families remain isolated. Set it to model if a gateway requires exact-model routing. The shared key improves gateway affinity but cannot make model-specific KV tensors portable between different model backends. The route intentionally does not depend on the retained user message, so Copilot compaction, a changed trim boundary, and switching Max/XHigh do not change affinity. The gateway still requires an exact rendered prefix and can enforce stricter model-level isolation. Tool definitions and schemas are sorted, then a fixed developer content block marks the boundary immediately before the changing Copilot conversation. On each round, the two most recent user boundaries are marked: the older one reads the position written on the previous round, while the newest one writes the position needed by the next round. This follows the OpenAI GPT-5.6 prompt-caching guidance.

The first request after this cache-key upgrade, cache expiry, or changing the Copilot tool set is necessarily a cold cache write. Switching among compatible GPT-5.6 aliases no longer changes the client cache route, but a gateway that physically isolates caches by exact upstream model can still report a cold write. A cache cannot be read before an equivalent prefix has been written. Later independent chats can reuse the fixed startup prefix while the tool set and provider prefix remain identical. GPT-5.6 cache entries request a 30-minute TTL, and the usage log reports both cache reads and writes.

In explicit mode, rejected cache features are remembered in VS Code global state per endpoint path, protocol, and upstream model. The result contains no API key or prompt data and expires after seven days. Generic upstream 500/502 failures are not compatibility probes and are not automatically resent. Run sub2api: Re-detect Prompt Cache Compatibility after upgrading or reconfiguring a gateway if you want to test explicit mode again.

Privacy and security

Keys are stored in VS Code SecretStorage, never settings.
Prompt contents and keys are never written to logs.
No endpoint is preconfigured or contacted before you configure one.
Review the privacy, retention, and billing policy of your chosen endpoint.

Contact and support

Website: vortelyn.cn
Technical support and business inquiries: contact@vortelyn.cn

Troubleshooting

Run sub2api: Show Logs for request number, anonymized request fingerprint, protocol, model, advertised input limit, conservative estimate, cache strategy, breakpoint count, startup-boundary presence, anonymized tool/provider foundation and stable-prefix fingerprints, cache expectation/cold reason, route fingerprint, usage, and server error bodies. In explicit mode, two new-chat requests can reuse the startup cache only when promptCacheFoundation matches and promptCacheBreakpoints is greater than zero. In Auto/implicit mode, use the returned cached_tokens value as the authoritative result. Two different request numbers from one Agent action indicate separate Copilot model rounds, commonly an intermediate tool round followed by a final answer round.

SUB2API_CONTEXT_WINDOW_EXCEEDED means the gateway rejected the official or learned limit. The provider learns from that error and retries once; if it repeats, inspect the logged learned budget, set a lower sub2api.contextWindowCap, or start a new chat.

SUB2API_CONCURRENCY_LIMIT means the gateway rejected overlapping work for the account behind the API key. Requests using the same endpoint origin and key are serialized inside one VS Code extension host. A rejected request is retried with exponential backoff only if no text or tool call has been emitted, preventing blind retries of partially generated work. Configure sub2api.concurrencyRetryCount and sub2api.concurrencyRetryDelaySeconds if needed. This cannot stop another machine, another VS Code window with a separate extension host, or gateway-internal shared-account traffic.

A log message saying the gateway explicitly rejected only the request-wide cache policy is not fatal: the provider keeps explicit content breakpoints. If it explicitly rejects content breakpoints too, the gateway cannot provide reliable cross-conversation first-turn caching for GPT-5.6; update or reconfigure the Responses-compatible gateway. An ordinary Upstream request failed 500/502 now stops after one attempt instead of risking two more billed requests.

A top-level fetch failed means no complete HTTP response was received. The provider logs a sanitized cause chain, including common DNS, connection, TLS/socket, and Undici timeout codes when Node exposes them. Failures proven to happen before TLS or HTTP transmission are retried three times by default; configure this with sub2api.connectionRetryCount and sub2api.connectionRetryDelaySeconds. Ambiguous transport retries remain controlled by sub2api.networkRetryCount and sub2api.networkRetryDelaySeconds, defaulting to zero because a POST can reach and be billed by the upstream even when its response connection fails. A stable Idempotency-Key is reused across attempts, and retries never run after text or a tool call has been emitted.

SUB2API_STREAM_TERMINATED means the gateway closed SSE before the selected protocol completed. Check upstream/reverse-proxy timeouts and SSE heartbeat behavior. The provider does not blindly retry incomplete generated output because that can duplicate tokens and tool calls.

License

MIT

sub2api Provider

vortelyn

sub2api Provider

简体中文

主要功能

快速开始

生成 Git 提交消息

配置指南

打开配置

配置服务地址和 API Key

推荐起始配置

完整设置参考

API 格式

自动模型路由

思考级别

上下文与压缩

用量、缓存与余额

隐私与安全

联系与支持

故障排查

许可证

English

Highlights

Get started

Generate a Git commit message

Configuration

Open the configuration

Endpoint and API key

Recommended starting configuration

Complete settings reference

API formats

Automatic model routing

Reasoning selector

Context and compaction

Usage, cache, and balance

Privacy and security

Contact and support

Troubleshooting

License