sub2api Provider

English | 简体中文

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
• One clean picker entry per model, plus visible status-bar selectors for reasoning effort and context management
• 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

1. Install from the Visual Studio Marketplace or a VSIX.
2. Run sub2api: Configure Endpoint and enter your API base URL.
3. Run sub2api: Set API Key.
4. Keep sub2api.apiFormat at openai-responses, or select another compatible protocol.
5. 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

1. Run sub2api: Configure Endpoint.
2. Enter the base URL of the compatible gateway, preferably including its API version prefix, for example https://gateway.example.com/v1.
3. Run sub2api: Set API Key and enter the gateway key.
4. Select the matching sub2api.apiFormat.
5. 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 uses Sub2API's current-key Codex manifest (/models?client_version=...). Only descriptors explicitly marked visibility: list and supported_in_api: true, with known context metadata, enter Chat, Auto and the Git picker. A newly listed model can appear without a plugin update, regardless of its name. A model explicitly hidden or marked unsupported is removed immediately. A missing model is retained for up to 24 hours since it last supplied verified metadata, because the gateway can temporarily omit rate-limited upstream accounts even in an HTTP 200 response. The generic /models fallback list and synthetic generic context limits are not treated as subscription evidence. The manifest reflects the gateway's configured group or selected upstream account; it is not a claim to enumerate every upstream account in a pool, nor a live generation test. Gateways/platforms that do not provide this manifest remain unconfirmed and do not gain automatic additions.

A real manifest's maximum context (or its default budget when no maximum is supplied) limits the client budget, capped by verified native model limits. For example, GPT-6 Astra's catalog has a 1,050,000-token native context; if the account manifest limits it to 872,000, the extension uses 872,000. With the default 32,768 output budget and 8,192 safety margin, input is then 831,040. Missing context is never replaced with an invented 128K value. Synthetic fallback descriptors use only existing verified catalog metadata; unknown native output limits stay unknown and requests use the configured output budget.

Refresh runs at startup, every 15 minutes, on focus, and after endpoint/key changes. Successful background refreshes are separated by at least 60 seconds. sub2api: Refresh Models bypasses that success cooldown but still honors a pending error backoff or Retry-After. HTTP 429, timeouts, server failures, temporary account-status failures, empty/partial lists and unavailable context metadata keep recent verified models and schedule automatic retries, initially after 5 seconds and doubling up to 15 minutes; a longer Retry-After takes precedence. Retry recovery does not require window focus or the periodic timer.

Caches and retry cooldowns survive reloads and are isolated by endpoint, key and protocol. Each model expires 24 hours after its own last verified appearance; failed or partial refreshes do not extend the age of missing models. Nonempty 1.0.34–1.0.36 account-manifest caches migrate; old generic caches and poisoned empty v3 results are ignored. Explicit inference-key authentication failures or inactive/mismatched subscriptions clear automatic models immediately, including after reload; an error explicitly identified as an upstream OAuth failure does not revoke the local key. A fresh, valid empty manifest with no previous models remains empty. Cached availability is shown as such and does not guarantee generation will succeed while the upstream is rate limited. On unavailable metadata without a verified cache, existing manual selections remain unconfirmed. excludedModels hides specific IDs; disabling autoDiscoverModels uses manual selections only. No generation requests are made for discovery.

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 fallback when discovery is disabled or unconfirmed. Empty uses these five defaults; a confirmed account manifest replaces this list.
sub2api.autoDiscoverModels	true	Boolean	Synchronize visible, API-supported models from the current key account manifest with verified context metadata.
sub2api.modelRefreshMinutes	15	0–1440	Periodic synchronization interval. 0 disables only the timer; startup, endpoint/key changes, window focus 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. Prefer the Chat title or status-bar selector for interactive changes.
sub2api.autoReasoningMode	pinned	pinned, perTurn	pinned keeps one effort per conversation for cache locality; perTurn re-evaluates every 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 \u00b7 Auto Adaptive in the Chat model picker to route a task without an additional classifier API call. The router only considers model IDs currently listed in sub2api.enabledModels; disabling a model removes it from the automatic subscription scope.

The local scorer considers message/context size, diagnostic and code signals, multi-step requests, vision, advanced engineering keywords, and deep-reasoning indicators. It maps simple, balanced, and complex tasks to the closest enabled model tier, preferring Luna, Terra, and Sol respectively when those models are enabled. The model choice is pinned for later rounds of the same task so tool calls and prompt caches do not repeatedly move between models. The first request also selects an appropriate reasoning effort from the latest user turn; by default that effort is pinned with the model because real gateways can isolate cache entries by Low, Medium, High, XHigh, and Max. If the pinned model can no longer fit the estimated context, the router promotes to an enabled model with enough context.

This is a deterministic cost-saving heuristic, not a guaranteed semantic judgment. It adds no classifier tokens and logs only the score, reason labels, selected model, and enabled model IDs?not prompt text. Manually select a specific model when a task has unusual stakes or when you need guaranteed model choice.

Reasoning selector

Click the reasoning icon in the Copilot Chat title bar, or sub2api Reasoning in the status bar to choose Model, Low, Medium, High, XHigh, or Max. The selection is forwarded on subsequent requests. "Model" follows the selected model variant or a reasoning setting supplied by VS Code.

Each enabled upstream model now appears only once in the model picker. Reasoning depth is selected exclusively through the separate visible Chat-title/status-bar control, keeping Low, Medium, High, XHigh, and Max out of the model list. Legacy model::effort IDs remain accepted for existing chats.

With sub2api.autoReasoningMode: pinned (default), Auto Adaptive chooses effort once per conversation and keeps it stable for cache locality. Set it to perTurn only when adapting effort on every question matters more than the extra cold-cache cost. A manual change from Low to High/XHigh can likewise enter a different upstream cache partition even though the model ID and client cache key stay unchanged.

Context and compaction

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

A compatible gateway can expose a smaller effective limit than the upstream model. In automatic mode, the provider initially advertises the official limit. If the gateway returns a context-window error, the provider 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.

Click the context icon in the Copilot Chat title bar, or sub2api Context in the status bar, 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 each model's official total context window. 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

---

简体中文

在 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 中

快速开始

1. 从 Visual Studio Marketplace 或 VSIX 安装扩展。
2. 运行 sub2api：配置服务地址，输入 API 基础地址。
3. 运行 sub2api：设置 API Key。
4. 保持 sub2api.apiFormat 为默认的 openai-responses，或选择其他兼容协议。
5. 运行 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

1. 运行 sub2api：配置服务地址。
2. 输入兼容网关的基础地址，建议包含 API 版本前缀，例如 https://gateway.example.com/v1。
3. 运行 sub2api：设置 API Key，输入网关密钥。
4. 选择与网关匹配的 sub2api.apiFormat。
5. 运行 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 中嵌入的凭据。

推荐起始配置

默认值适合大多数兼容 Responses API 的网关。最小的显式用户配置示例如下：

{
  "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
}

不要把 API Key 加入这段 JSON，请使用 sub2api：设置 API Key。

完整设置参考

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

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

自动发现读取 Sub2API 按当前 Key 返回的 Codex 账号模型清单（/models?client_version=...）。仅清单中明确标为 visibility: list、supported_in_api: true 且具备可信上下文参数的聊天模型进入 Chat、Auto 和 Git 选择器。清单新增模型后无需升级插件；明确隐藏或标记为不支持 API 的模型立即移除。网关可能在上游限速时通过 HTTP 200 返回缺少部分模型的清单，因此暂时缺失的模型自最后一次取得可信参数起最多保留 24 小时。普通 /models 的默认列表和服务端合成的通用上下文参数不作为订阅依据。账号清单反映网关配置的分组或其选中的上游账号，不保证枚举账号池内所有上游账号，也不代表已经完成真实生成测试。不提供这种清单的网关或平台保持未确认，不自动增加模型。

真实清单给出的最大上下文（未给最大值时使用其默认预算）用于限制客户端预算，同时不超过已核实的模型原生上限。例如 GPT-6 Astra 的目录原生上下文为 1,050,000；若账号清单返回最大 872,000，插件实际采用 872,000。按默认输出预算 32,768 和安全余量 8,192，输入预算为 831,040。缺少上下文时不再填入猜测的 128K。合成的通用模型描述只能沿用已有的已核实目录参数；原生输出上限未知时保持未知，请求仍采用配置的输出预算。

启动时、每隔 15 分钟、窗口获得焦点及修改地址或 Key 后自动刷新；成功的后台刷新至少间隔 60 秒。sub2api：刷新模型列表可跳过成功后的冷却时间，但仍遵守错误退避和服务器的 Retry-After。遇到 HTTP 429、超时、服务端错误、账号状态查询暂时失败、空清单、部分清单或缺失上下文参数时，保留近期验证过的模型并自动重试：从 5 秒开始逐次翻倍，最长 15 分钟；服务器要求更长等待时按其要求执行。自动恢复不依赖切回窗口或周期刷新。

缓存与重试冷却时间在重载后保留，按地址、Key 和协议隔离。每个模型自最后一次取得可信参数起最多保留 24 小时；失败或部分刷新不会延长缺失模型的有效期。兼容迁移 1.0.34–1.0.36 的非空账号清单缓存，忽略旧通用缓存及被不完整响应写入的 v3 空缓存。明确的推理 Key 认证失败、订阅停用或 Key 不匹配立即移除自动模型，重载后也不会恢复；明确标记为上游 OAuth 异常的错误不会当作本地 Key 失效。首次取得有效空清单且没有历史模型时保持为空。缓存模型会标明缓存状态，上游限速时真实生成仍可能失败。没有可信缓存且接口信息不可用时，保留原有手动选择并标记为未确认。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	关闭发现或信息未确认时的手动选择。为空时使用这五个默认模型；已确认的账号清单会替代此列表。
sub2api.autoDiscoverModels	true	布尔值	同步当前 Key 账号清单中可见、支持 API 且上下文参数已确认的模型。
sub2api.modelRefreshMinutes	15	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	默认思考级别。交互调整建议使用 Chat 标题栏或状态栏选择器。
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，即可在不增加分类器 API 调用的情况下自动路由任务。路由器只会考虑当前账号清单或手动模式中启用的模型。

本地评分会考虑消息和上下文长度、诊断与代码信号、多步骤请求、图片、工程关键词和深度推理信号，并把任务分为简单、均衡和复杂三个等级。启用对应模型时，会分别优先选择 Luna、Terra 和 Sol。模型会在同一任务的后续轮次中保持固定，避免工具调用和提示词缓存反复切换后端。

这是一个不消耗额外 Token 的确定性成本优化规则，并不保证语义判断绝对准确。高风险任务或必须指定模型时，请手动选择具体模型。

思考级别

点击 Copilot Chat 标题栏中的思考图标，或状态栏中的 sub2api 思考级别，可以选择跟随模型、Low、Medium、High、XHigh 或 Max。选择会用于后续请求。

每个上游模型在模型选择器中只出现一次。思考深度由独立控件管理，旧会话中的 model::effort 标识仍可继续使用。

sub2api.autoReasoningMode 默认为 pinned：Auto Adaptive 会在会话首次请求时选择思考级别，并在该会话中保持固定，以提高上游缓存局部性。将其改为 perTurn 后会逐轮重新评估，但思考级别变化可能进入不同的缓存分区。

上下文与压缩

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

最大输入 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

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

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

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

点击 Chat 标题栏中的上下文图标或状态栏中的 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