Merge pull request #611 from yrooogerg/feat/volcengine-providers

feat(providers): add Volcengine Ark presets

Adds canonical presets for the three Ark billing routes: pay-as-you-go, Coding Plan, and Agent Plan.

Credential-destination evidence gate settled from opened primary sources; ledger in the PR comment thread. Volcengine publishes a first-party Codex CLI integration guide and lists Claude Code / OpenCode / OpenClaw as supported clients, and each user supplies their own plan key, so this is documented client use rather than aggregation.

Both Plan presets disclose the coding-tools-only restriction and its account-ban consequence, resolved by destination so a preset saved under a custom name keeps the warning.

Outstanding: named maintenance owner for the static catalogs.

Author: lidge-jun

docs-site/src/content/docs/guides/providers.md

@@ -190,7 +190,7 @@ selectors, then retry. Signing in from a machine with no existing `kiro-cli` ses
 
 ## 3. API-key catalog
 
-opencodex ships 62 built-in presets: 51 key-based, seven OAuth, three local, and the default
+opencodex ships 65 built-in presets: 54 key-based, seven OAuth, three local, and the default
 ChatGPT-forward preset. The dashboard's **Add provider** picker opens a key provider's dashboard,
 validates the key, and stores it. Notable entries:
 
@@ -219,6 +219,7 @@ validates the key, and stores it. Notable entries:
 | Qwen Cloud | Token plan (default): `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · Pay as you go: `https://dashscope.aliyuncs.com/compatible-mode/v1` · or Custom |
 | Tencent Cloud Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` |
 | SiliconFlow | `https://api.siliconflow.cn/v1` |
+| Volcengine Ark · Coding Plan · Agent Plan | `https://ark.cn-beijing.volces.com/api/v3` · `https://ark.cn-beijing.volces.com/api/coding/v3` · `https://ark.cn-beijing.volces.com/api/plan/v3` |
 | Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` |
 | Kilo | `https://api.kilo.ai/api/gateway` |
 | GitLab Duo | `https://cloud.gitlab.com/ai/v1/proxy/openai/v1` |
@@ -227,6 +228,24 @@ validates the key, and stores it. Notable entries:
 
 Most use the `openai-chat` adapter with a bearer key; a few that expose only an Anthropic-compatible
 endpoint (e.g. **Xiaomi MiMo**) use the `anthropic` adapter (`x-api-key`).
+Volcengine Agent Plan uses its native Responses endpoint through `openai-responses`.
+
+> **Three Volcengine billing routes:** `volcengine` is the pay-as-you-go Ark API,
+> `volcengine-coding-plan` consumes Coding Plan quota, and `volcengine-agent-plan` consumes Agent
+> Plan quota. Use the key and endpoint issued for the same product; the ordinary `/api/v3` endpoint
+> can incur pay-as-you-go charges even when a Plan subscription exists.
+> The presets use curated static model catalogs because Ark's `/models` response also includes
+> embedding, image, video, and 3D resources, the Coding gateway returns that same broad catalog,
+> and the Agent Plan gateway has no `/models` resource. Pay-as-you-go defaults to
+> `doubao-seed-2-1-pro-260628`; its curated catalog also includes current DeepSeek and GLM text
+> models. Coding Plan defaults to `ark-code-latest`, while Agent Plan defaults to
+> `deepseek-v4-pro`.
+
+> **Volcengine Plan usage restriction:** Volcengine documents Coding Plan and Agent Plan quota as
+> valid only inside supported AI coding tools, and warns that using a plan key for general API
+> calls may suspend the subscription or ban the account. Routing Codex or Claude Code through
+> opencodex is the documented use; pointing other automation at a plan key is not. The
+> pay-as-you-go `volcengine` route carries no such restriction.
 
 **DeepInfra discovery.** The key-based `deepinfra` OpenAI Chat Completions provider uses the
 `openai-chat` adapter with a Bearer API key. Its registry-owned model-list URL keeps only rows tagged

docs-site/src/content/docs/ja/guides/providers.md

@@ -119,7 +119,7 @@ Kiro のログインには Kiro CLI が必要です。Unix では `curl -fsSL ht
 
 ## 3. API キーカタログ
 
-opencodex には組み込みプリセットが 62 個含まれています。キー方式 51、OAuth 7、ローカル 3、
+opencodex には組み込みプリセットが 65 個含まれています。キー方式 54、OAuth 7、ローカル 3、
 デフォルト ChatGPT 転送プリセット 1 です。ダッシュボードの **Add provider** ピッカーはキー発行ページを開き、
 入力したキーを検証した後保存します。主な項目は以下のとおりです:
 
@@ -148,6 +148,7 @@ opencodex には組み込みプリセットが 62 個含まれています。キ
 | Qwen Cloud | トークンプラン(デフォルト): `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · 従量課金: `https://dashscope.aliyuncs.com/compatible-mode/v1` · またはカスタム |
 | Tencent Cloud Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` |
 | SiliconFlow | `https://api.siliconflow.cn/v1` |
+| Volcengine Ark · Coding Plan · Agent Plan | `https://ark.cn-beijing.volces.com/api/v3` · `https://ark.cn-beijing.volces.com/api/coding/v3` · `https://ark.cn-beijing.volces.com/api/plan/v3` |
 | Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` |
 | Kilo | `https://api.kilo.ai/api/gateway` |
 | GitLab Duo | `https://cloud.gitlab.com/ai/v1/proxy/openai/v1` |
@@ -156,6 +157,18 @@ opencodex には組み込みプリセットが 62 個含まれています。キ
 
 大半は bearer キーと共に `openai-chat` アダプターを使い、Anthropic 互換エンドポイントのみを公開する一部
 (例: **Xiaomi MiMo**)は `anthropic` アダプター(`x-api-key`)を使います。
+Volcengine Agent Plan は `openai-responses` アダプターでネイティブ Responses エンドポイントを使用します。
+
+> **Volcengine の 3 つの課金経路:** `volcengine` は従量課金 Ark API、
+> `volcengine-coding-plan` は Coding Plan の割り当て、`volcengine-agent-plan` は Agent Plan
+> の割り当てを使用します。同じ製品で発行されたキーとエンドポイントを組み合わせてください。
+> Plan 契約があっても通常の `/api/v3` 呼び出しには従量課金が発生する場合があります。
+> 3 つの preset は選別済みの静的モデルカタログを使用します。Ark の `/models` はテキストに加えて
+> Embedding、画像、動画、3D リソースも返し、Coding ゲートウェイも同じ広範なカタログを返します。
+> Agent Plan ゲートウェイには `/models` リソースがありません。従量課金のデフォルトは
+> `doubao-seed-2-1-pro-260628` で、静的カタログには現在の DeepSeek と GLM のテキストモデルも
+> 含まれます。Coding Plan のデフォルトは `ark-code-latest`、Agent Plan は
+> `deepseek-v4-pro` です。
 
 **DeepInfra の discovery:** キー方式の OpenAI Chat Completions プロバイダー `deepinfra` は、
 `openai-chat` アダプターと Bearer API キーを使います。registry が所有する DeepInfra のモデル一覧 URL から

docs-site/src/content/docs/ko/guides/providers.md

@@ -119,7 +119,7 @@ Kiro 로그인에는 Kiro CLI가 필요합니다. Unix에서는 `curl -fsSL http
 
 ## 3. API 키 카탈로그
 
-opencodex에는 빌트인 프리셋이 62개 들어 있습니다. 키 방식 51개, OAuth 7개, 로컬 3개,
+opencodex에는 빌트인 프리셋이 65개 들어 있습니다. 키 방식 54개, OAuth 7개, 로컬 3개,
 기본 ChatGPT 포워드 프리셋 1개입니다. 대시보드의 **Add provider** 선택기는 키 발급 페이지를 열고,
 입력한 키를 검증한 뒤 저장합니다. 주요 항목은 다음과 같습니다:
 
@@ -148,6 +148,7 @@ opencodex에는 빌트인 프리셋이 62개 들어 있습니다. 키 방식 51
 | Qwen Cloud | Token plan(기본): `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · 종량제: `https://dashscope.aliyuncs.com/compatible-mode/v1` · 또는 사용자 지정 |
 | Tencent Cloud Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` |
 | SiliconFlow | `https://api.siliconflow.cn/v1` |
+| Volcengine Ark · Coding Plan · Agent Plan | `https://ark.cn-beijing.volces.com/api/v3` · `https://ark.cn-beijing.volces.com/api/coding/v3` · `https://ark.cn-beijing.volces.com/api/plan/v3` |
 | Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` |
 | Kilo | `https://api.kilo.ai/api/gateway` |
 | GitLab Duo | `https://cloud.gitlab.com/ai/v1/proxy/openai/v1` |
@@ -156,6 +157,17 @@ opencodex에는 빌트인 프리셋이 62개 들어 있습니다. 키 방식 51
 
 대부분은 bearer 키와 함께 `openai-chat` 어댑터를 사용하며, Anthropic 호환 엔드포인트만 노출하는 일부
 (예: **Xiaomi MiMo**)는 `anthropic` 어댑터(`x-api-key`)를 사용합니다.
+Volcengine Agent Plan은 `openai-responses` 어댑터로 네이티브 Responses 엔드포인트를 사용합니다.
+
+> **Volcengine의 세 가지 과금 경로:** `volcengine`은 종량제 Ark API,
+> `volcengine-coding-plan`은 Coding Plan 할당량, `volcengine-agent-plan`은 Agent Plan
+> 할당량을 사용합니다. 같은 상품에서 발급된 키와 엔드포인트를 함께 사용해야 하며, Plan 구독이
+> 있어도 일반 `/api/v3` 엔드포인트 호출에는 종량제 요금이 발생할 수 있습니다.
+> 세 preset은 선별된 정적 모델 카탈로그를 사용합니다. Ark의 `/models`는 텍스트와 함께
+> Embedding, 이미지, 비디오, 3D 리소스도 반환하고 Coding 게이트웨이도 같은 광범위한 카탈로그를
+> 반환합니다. Agent Plan 게이트웨이에는 `/models` 리소스가 없습니다. 종량제 기본값은
+> `doubao-seed-2-1-pro-260628`이며 정적 카탈로그에는 현재 DeepSeek와 GLM 텍스트 모델도
+> 포함됩니다. Coding Plan의 기본값은 `ark-code-latest`, Agent Plan은 `deepseek-v4-pro`입니다.
 
 **DeepInfra 검색:** 키 기반 OpenAI Chat Completions 제공자인 `deepinfra`는 `openai-chat` 어댑터와
 Bearer API 키를 사용합니다. registry가 소유하는 DeepInfra 모델 목록 URL에서 `chat` 태그가 있는 행만

docs-site/src/content/docs/ru/guides/providers.md

@@ -126,7 +126,7 @@ OAuth-провайдеры, чьи учётные данные содержат
 
 ## 3. Каталог API-ключей
 
-opencodex поставляется с 62 встроенными пресетами: 51 на основе ключей, семь OAuth, три локальных и
+opencodex поставляется с 65 встроенными пресетами: 54 на основе ключей, семь OAuth, три локальных и
 пресет ChatGPT-форварда по умолчанию. Селектор **Add provider** в дашборде открывает страницу
 выдачи ключей провайдера, проверяет ключ и сохраняет его. Наиболее заметные записи:
 
@@ -155,6 +155,7 @@ opencodex поставляется с 62 встроенными пресетам
 | Qwen Cloud | Token plan (по умолчанию): `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · Pay as you go: `https://dashscope.aliyuncs.com/compatible-mode/v1` · или Custom |
 | Tencent Cloud Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` |
 | SiliconFlow | `https://api.siliconflow.cn/v1` |
+| Volcengine Ark · Coding Plan · Agent Plan | `https://ark.cn-beijing.volces.com/api/v3` · `https://ark.cn-beijing.volces.com/api/coding/v3` · `https://ark.cn-beijing.volces.com/api/plan/v3` |
 | Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` |
 | Kilo | `https://api.kilo.ai/api/gateway` |
 | GitLab Duo | `https://cloud.gitlab.com/ai/v1/proxy/openai/v1` |
@@ -164,6 +165,18 @@ opencodex поставляется с 62 встроенными пресетам
 Большинство использует адаптер `openai-chat` с bearer-ключом; немногие провайдеры, предоставляющие
 только Anthropic-совместимую конечную точку (например, **Xiaomi MiMo**), используют адаптер
 `anthropic` (`x-api-key`).
+Volcengine Agent Plan использует нативную конечную точку Responses через адаптер `openai-responses`.
+
+> **Три маршрута тарификации Volcengine:** `volcengine` — Ark API с оплатой по факту,
+> `volcengine-coding-plan` расходует квоту Coding Plan, а `volcengine-agent-plan` — квоту Agent
+> Plan. Используйте ключ и конечную точку одного продукта; обычный `/api/v3` может тарифицироваться
+> отдельно даже при активной подписке Plan.
+> Все три preset используют отобранные статические каталоги моделей. Ark `/models` возвращает
+> текстовые, embedding-, графические, видео- и 3D-ресурсы, а шлюз Coding выдаёт тот же широкий
+> каталог. У шлюза Agent Plan ресурса `/models` нет. Для pay-as-you-go модель по умолчанию —
+> `doubao-seed-2-1-pro-260628`; его статический каталог также включает актуальные текстовые модели
+> DeepSeek и GLM. Для Coding Plan модель по умолчанию — `ark-code-latest`, для Agent Plan —
+> `deepseek-v4-pro`.
 
 **Discovery для DeepInfra.** `deepinfra` — провайдер OpenAI Chat Completions с аутентификацией по
 ключу; он использует адаптер `openai-chat` и Bearer API-ключ. Принадлежащий registry URL списка

docs-site/src/content/docs/zh-cn/guides/providers.md

@@ -111,7 +111,7 @@ Kiro 登录需要 Kiro CLI：Unix 使用 `curl -fsSL https://cli.kiro.dev/instal
 
 ## 3. API 密钥目录
 
-opencodex 内置 62 个预设：51 个密钥预设、7 个 OAuth 预设、3 个本地预设，以及默认的
+opencodex 内置 65 个预设：54 个密钥预设、7 个 OAuth 预设、3 个本地预设，以及默认的
 ChatGPT 转发预设。仪表盘的 **Add provider** 选择器会打开密钥提供商的控制台，验证并保存密钥。
 主要条目包括：
 
@@ -140,13 +140,24 @@ ChatGPT 转发预设。仪表盘的 **Add provider** 选择器会打开密钥提
 | Qwen Cloud | Token plan（默认）: `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` · 按量付费: `https://dashscope.aliyuncs.com/compatible-mode/v1` · 或自定义 |
 | 腾讯云 Coding Plan | `https://api.lkeap.cloud.tencent.com/coding/v3` |
 | SiliconFlow | `https://api.siliconflow.cn/v1` |
+| 火山方舟 · Coding Plan · Agent Plan | `https://ark.cn-beijing.volces.com/api/v3` · `https://ark.cn-beijing.volces.com/api/coding/v3` · `https://ark.cn-beijing.volces.com/api/plan/v3` |
 | Xiaomi MiMo | `https://api.xiaomimimo.com/anthropic` |
 | Kilo | `https://api.kilo.ai/api/gateway` |
 | GitLab Duo | `https://cloud.gitlab.com/ai/v1/proxy/openai/v1` |
 | Cloudflare AI Gateway | `https://gateway.ai.cloudflare.com/v1/{account-id}/{gateway}/anthropic` |
 | ……以及更多 | opencode zen、Vercel AI Gateway、Venice、NanoGPT、Synthetic、Qianfan、Alibaba、Parallel、ZenMux、LiteLLM |
 
 大多数使用带 bearer 密钥的 `openai-chat` adapter；少数仅暴露 Anthropic 兼容端点的提供商（例如 **Xiaomi MiMo**）使用 `anthropic` adapter（`x-api-key`）。
+火山方舟 Agent Plan 通过 `openai-responses` adapter 使用原生 Responses 端点。
+
+> **三条火山方舟计费线路：**`volcengine` 是按量付费方舟 API，`volcengine-coding-plan`
+> 消耗 Coding Plan 额度，`volcengine-agent-plan` 消耗 Agent Plan 额度。密钥与端点需要属于
+> 同一产品；已经订阅 Plan 时调用普通 `/api/v3` 端点仍可能产生按量费用。
+> 三个 preset 使用经过筛选的静态模型目录：方舟 `/models` 同时返回文本、Embedding、图片、
+> 视频和 3D 资源，Coding 网关也会返回这份宽泛目录，Agent Plan 网关没有 `/models` 资源。
+> 按量付费默认使用 `doubao-seed-2-1-pro-260628`，静态目录还包含当前 DeepSeek 和 GLM
+> 文本模型。Coding Plan 默认使用 `ark-code-latest`，Agent Plan 默认使用
+> `deepseek-v4-pro`。
 
 **DeepInfra 发现：**`deepinfra` 是使用 `openai-chat` adapter 和 Bearer API 密钥的密钥型
 OpenAI Chat Completions 提供商。registry 固定的 DeepInfra 模型列表 URL 仅保留带 `chat` 标签的记录，

gui/src/components/AddProviderModal.tsx

@@ -142,6 +142,7 @@ export default function AddProviderModal({
         baseUrl: p.baseUrlChoices?.length
           ? baseUrlForChoice(p.baseUrlChoices, choiceId, p.baseUrl)
           : p.baseUrl,
+        responsesPath: p.responsesPath,
         authMode: p.auth,
         apiKey: "",
         apiKeyTransport: undefined,

gui/src/components/provider-catalog/provider-presets.ts

@@ -15,6 +15,7 @@ export interface CatalogPreset {
   label: string;
   adapter: string;
   baseUrl: string;
+  responsesPath?: string;
   defaultModel?: string;
   /** "oauth": account login · "forward": ChatGPT passthrough · "key": API key · "local": local scaffold. */
   auth: "oauth" | "forward" | "key" | "local";
@@ -67,4 +68,3 @@ export function filterPresets(presets: CatalogPreset[], query: string): CatalogP
   if (!q) return presets;
   return presets.filter(p => p.label.toLowerCase().includes(q) || p.id.toLowerCase().includes(q));
 }
-

gui/src/components/provider-workspace/ProviderDetails.tsx

@@ -151,7 +151,7 @@ export default function ProviderDetails({
         <ProviderIcon name={item.name} adapter={item.adapter} baseUrl={item.baseUrl} cls="pws-detail-icon" />
         <div className="pws-detail-title-wrap">
           <h2 className="pws-detail-title">
-            {formatProviderDisplayName(item.name)}
+            {formatProviderDisplayName(item.name, t)}
             {local && <span className="pwi-rail-badge pwi-rail-badge--local">{t("modal.badge.local")}</span>}
             {!local && free && <span className="pwi-rail-badge pwi-rail-badge--free">{t("modal.badge.free")}</span>}
           </h2>

gui/src/components/provider-workspace/ProviderOverviewDashboard.tsx

@@ -127,7 +127,7 @@ export default function ProviderOverviewDashboard({
               >
                 <ProviderIcon name={item.name} adapter="" baseUrl="" cls="pws-dashboard-row-icon" />
                 <div className="pws-dashboard-row-info">
-                  <span className="pws-dashboard-row-name">{formatProviderDisplayName(item.name)}</span>
+                  <span className="pws-dashboard-row-name">{formatProviderDisplayName(item.name, t)}</span>
                   <span className="pws-dashboard-row-meta muted">{localizeAttentionReason(item.reason)}</span>
                 </div>
                 <IconChevron className="pws-dashboard-row-chevron" aria-hidden="true" />
@@ -155,7 +155,7 @@ export default function ProviderOverviewDashboard({
                 >
                   <ProviderIcon name={item.name} adapter={item.adapter} baseUrl={item.baseUrl} cls="pws-dashboard-row-icon" />
                   <div className="pws-dashboard-row-info">
-                    <span className="pws-dashboard-row-name">{formatProviderDisplayName(item.name)}</span>
+                    <span className="pws-dashboard-row-name">{formatProviderDisplayName(item.name, t)}</span>
                     <span className="pws-dashboard-row-meta muted">
                       {t("pws.dashboard.checkedAgo", { time: formatRelativeTime(report.updatedAt, timeLabels) })}
                     </span>
@@ -209,7 +209,7 @@ export default function ProviderOverviewDashboard({
                   onClick={() => onSelectProvider(provider.name)}
                 >
                   <ProviderIcon name={provider.name} adapter="" baseUrl="" cls="pws-dashboard-row-icon" />
-                  <span className="pws-dashboard-row-name">{formatProviderDisplayName(provider.name)}</span>
+                  <span className="pws-dashboard-row-name">{formatProviderDisplayName(provider.name, t)}</span>
                   <span className="pws-dashboard-row-count muted">
                     {t("pws.dashboard.requests", { count: formatRequestCount(provider.requests, locale) })}
                   </span>

gui/src/components/provider-workspace/ProviderRail.tsx

@@ -75,7 +75,7 @@ export function RailRow({ item, selected, tabbable, modelCount, isDefault, showC
   const free = isFreeProvider(item);
   const local = isLocalProvider(item);
   const status = statusLabel(item, t);
-  const displayName = formatProviderDisplayName(item.name);
+  const displayName = formatProviderDisplayName(item.name, t);
   const nameTitle = showConfigId ? `${displayName} (${item.name})` : displayName;
   const suffix = `${isDefault ? t("pws.rail.suffixDefault") : ""}${local ? t("pws.rail.suffixLocal") : free ? t("pws.rail.suffixFree") : ""}`;
   const countLabel = modelCount !== undefined && modelCount > 0