pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-14 02:42:24 +03:00
Code Issues Packages Projects Releases Wiki Activity

fix(providers): retire common ChatGPT Web provider

Browse Source
This commit is contained in:
diegosouzapw
2026-08-27 03:13:19 -03:00
committed by Markus Hartung
parent 825f8fe425
commit 9c5dd6760c
172 changed files with 3193 additions and 11318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/README.md
View File

@@ -163,7 +163,7 @@ Prompt compression engines, rules, and language packs.
Provider-specific integration guides.
- [CLAUDE_WEB.md](providers/CLAUDE_WEB.md) — Claude Web (cookie-auth) provider.
- [CHATGPT_WEB.md](providers/CHATGPT_WEB.md) — ChatGPT Web (Plus/Pro + Codex) providers.
- [CHATGPT_WEB.md](providers/CHATGPT_WEB.md) — ChatGPT Web (Codex) provider and common-provider retirement note.
- [ALIBABA-QWEN-PROVIDER-FAMILIES.md](providers/ALIBABA-QWEN-PROVIDER-FAMILIES.md) — Alibaba and Qwen provider families.
- [AGENTROUTER.md](providers/AGENTROUTER.md) — AgentRouter setup.
- [ZED-DOCKER.md](providers/ZED-DOCKER.md) — Zed IDE integration under Docker.

181
docs/architecture/ARCHITECTURE.md
View File

@@ -17,7 +17,7 @@ It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic acr
Core capabilities:
- OpenAI-compatible API surface for CLI/tools (349 providers, 107 executors)
- OpenAI-compatible API surface for CLI/tools (351 providers, 107 executors)
- Request/response translation across provider formats
- Model combo fallback (multi-model sequence)
- Structured combo steps (`provider + model + connection`) with runtime ordering by `compositeTiers`
@@ -488,9 +488,6 @@ the global circuit breaker / connection cooldown / model lockout layers:
`claudeCodeToolRemapper.ts`
- Claude Code fingerprint shaping: `open-sse/services/claudeCodeFingerprint.ts`
- Claude Code obfuscation: `open-sse/services/claudeCodeObfuscation.ts`
- ChatGPT TLS client: `open-sse/services/chatgptTlsClient.ts` (curl-impersonate
style for ChatGPT-Web sessions)
- ChatGPT image cache: `open-sse/services/chatgptImageCache.ts`
For the full stealth playbook and operational guidance, see
[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md).
@@ -898,103 +895,103 @@ flowchart LR
Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
| Executor | Provider(s) | Special Handling |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamic URL/header config per provider |
| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing, 429 obfuscation |
| `AzureOpenAIExecutor` | Azure OpenAI | Deployment-based routing, api-version query enforcement |
| `BlackboxWebExecutor` | Blackbox AI (web-mode) | Web-session reverse with TLS fingerprint emulation |
| `ChatGPTWebExecutor` | ChatGPT web | TLS client + session cookie management (`chatgptTlsClient.ts`) |
| `ClaudeIdentityExecutor` | Claude.ai (CCH path) | Constraint + tool-remap pipelines, fingerprint shaping |
| `CliProxyApiExecutor` | CLIProxyAPI-compatible providers | Custom auth and protocol handling |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Account ID injection, Neurons-based usage tracking |
| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort |
| `CommandCodeExecutor` | Command Code | OAuth + per-session header rotation |
| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum |
| `DevinCliExecutor` | Devin CLI | Devin task lifecycle bridging via cloud agent module |
| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth + project-scoped routing |
| `GlmExecutor` | Z.AI GLM (incl. `glmt` preset) | Thinking-budget aware, GLMT preset constants |
| `GrokWebExecutor` | xAI Grok web | Web-session reverse, mode selection (think/standard) |
| `KieExecutor` | KIE | Custom token issuance with rotating session anchors |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion |
| `MuseSparkWebExecutor` | Muse Spark (web) | Web-session reverse with image-message bridging |
| `NlpCloudExecutor` | NLP Cloud | Provider-specific request body shape |
| `OpenCodeExecutor` | OpenCode | AI SDK compatible provider setup |
| `PerplexityWebExecutor` | Perplexity web | Web-session reverse for chat continuation |
| `PetalsExecutor` | Petals distributed inference | Decentralized swarm routing |
| `PollinationsExecutor` | Pollinations AI | No API key required, rate-limited requests |
| `QoderExecutor` | Qoder AI | PAT and OAuth support, multi-model free tier |
| `VertexExecutor` | Google Vertex AI | Service account auth, region-based endpoints |
| `DevinDesktopExecutor` | Devin Desktop | Imported API key + Connect-protobuf chat streaming |
| Executor | Provider(s) | Special Handling |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamic URL/header config per provider |
| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing, 429 obfuscation |
| `AzureOpenAIExecutor` | Azure OpenAI | Deployment-based routing, api-version query enforcement |
| `BlackboxWebExecutor` | Blackbox AI (web-mode) | Web-session reverse with TLS fingerprint emulation |
| `ClaudeIdentityExecutor` | Claude.ai (CCH path) | Constraint + tool-remap pipelines, fingerprint shaping |
| `CliProxyApiExecutor` | CLIProxyAPI-compatible providers | Custom auth and protocol handling |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Account ID injection, Neurons-based usage tracking |
| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex) | Browser-session Responses API bridge with thread/turn pinning |
| `CommandCodeExecutor` | Command Code | OAuth + per-session header rotation |
| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum |
| `DevinCliExecutor` | Devin CLI | Devin task lifecycle bridging via cloud agent module |
| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth + project-scoped routing |
| `GlmExecutor` | Z.AI GLM (incl. `glmt` preset) | Thinking-budget aware, GLMT preset constants |
| `GrokWebExecutor` | xAI Grok web | Web-session reverse, mode selection (think/standard) |
| `KieExecutor` | KIE | Custom token issuance with rotating session anchors |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion |
| `MuseSparkWebExecutor` | Muse Spark (web) | Web-session reverse with image-message bridging |
| `NlpCloudExecutor` | NLP Cloud | Provider-specific request body shape |
| `OpenCodeExecutor` | OpenCode | AI SDK compatible provider setup |
| `PerplexityWebExecutor` | Perplexity web | Web-session reverse for chat continuation |
| `PetalsExecutor` | Petals distributed inference | Decentralized swarm routing |
| `PollinationsExecutor` | Pollinations AI | No API key required, rate-limited requests |
| `QoderExecutor` | Qoder AI | PAT and OAuth support, multi-model free tier |
| `VertexExecutor` | Google Vertex AI | Service account auth, region-based endpoints |
| `DevinDesktopExecutor` | Devin Desktop | Imported API key + Connect-protobuf chat streaming |
All other providers (including custom compatible nodes) use the `DefaultExecutor`.
## Provider Compatibility Matrix
> **Note:** The matrix below is a representative sample of the 237 registered providers in
> **Note:** The matrix below is a representative sample of the 351 registered providers in
> OmniRoute v3.8.0. For the canonical and continuously-updated list, refer to
> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (auto-generated) or the source of
> truth at `src/shared/constants/providers.ts` (Zod-validated at load).
| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API |
| ----------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only |
| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API |
| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits |
| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots |
| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per request |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API Token + Acct ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | None (no key) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API Key (optional) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Service Account | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request |
| Z.AI / GLM | openai | API Key / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | API Key | ✅ | ✅ | ❌ | ⚠️ Per request |
| Kimi Coding | openai | OAuth / API Key | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Imported API key | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Per request |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Local CLI login | ✅ | ✅ | ❌ | ✅ Task API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Rate limits |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ Task API |
| AgentRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| ChatGPT-Web | openai | Session cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Session cookie | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Session cookie | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Session cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Session cookie | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API Key | ✅ | ✅ | ❌ | ⚠️ Quota policy |
| BazaarLink | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | None | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per request |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Custom | ✅ | ✅ | ❌ | ❌ |
| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API |
| ------------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only |
| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API |
| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits |
| ChatGPT Web (Codex) | openai-responses | Browser session | ✅ forced | ❌ | ❌ | ❌ |
| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots |
| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per request |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API Token + Acct ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | None (no key) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API Key (optional) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Service Account | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request |
| Z.AI / GLM | openai | API Key / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | API Key | ✅ | ✅ | ❌ | ⚠️ Per request |
| Kimi Coding | openai | OAuth / API Key | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Imported API key | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Per request |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Local CLI login | ✅ | ✅ | ❌ | ✅ Task API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Rate limits |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ Task API |
| AgentRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Session cookie | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Session cookie | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Session cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Session cookie | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API Key | ✅ | ✅ | ❌ | ⚠️ Quota policy |
| BazaarLink | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | None | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per request |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Custom | ✅ | ✅ | ❌ | ❌ |
## Format Translation Coverage

11
docs/architecture/CODEBASE_DOCUMENTATION.md
View File

@@ -233,7 +233,6 @@ v1/
├── audio/{speech, transcriptions}/ TTS + STT
├── batches/[id]/{cancel}, batches/ OpenAI Batches API
├── chat/completions/ Chat Completions (the main endpoint)
├── chatgpt-web/ ChatGPT-Web compat
├── completions/ Legacy text completions
├── embeddings/ Embeddings
├── files/[id]/, files/ Files API
@@ -292,7 +291,7 @@ table groups the actual directories and notable top-level files.
| `jobs/` | Background jobs (`autoUpdate.ts`, …) |
| `memory/` | Persistent memory: `store.ts`, `cache.ts`, `retrieval.ts`, `summarization.ts`, `extraction.ts`, `injection.ts`, `qdrant.ts`, `settings.ts`, `verify.ts`, `schemas.ts`, `types.ts` |
| `monitoring/` | `observability.ts` |
| `oauth/` | OAuth/import provider modules (22): `agy`, `antigravity`, `claude`, `cline`, `codebuddy-cn`, `codex`, `cursor`, `devin-desktop`, `ghe-copilot`, `github`, `gitlab-duo`, `grok-cli-oauth`, `grok-cli`, `kilocode`, `kimi-coding`, `kiro`, `qoder`, `raycast`, `trae`, `xai-oauth`, `zed-hosted`, `zed`, plus `services/`, `utils/`, and `constants/oauth.ts` |
| `oauth/` | OAuth/import provider modules (22): `agy`, `antigravity`, `claude`, `cline`, `codebuddy-cn`, `codex`, `cursor`, `devin-desktop`, `ghe-copilot`, `github`, `gitlab-duo`, `grok-cli-oauth`, `grok-cli`, `kilocode`, `kimi-coding`, `kiro`, `qoder`, `raycast`, `trae`, `xai-oauth`, `zed-hosted`, `zed`, plus `services/`, `utils/`, and `constants/oauth.ts` |
| `plugins/` | Plugin loader (`index.ts`) |
| `promptCache/` | `prefixAnalyzer.ts`, `index.ts` |
| `providerModels/` | Managed model lifecycle: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts` |
@@ -481,16 +480,16 @@ open-sse/
### 4.2 `open-sse/executors/`
101 provider executors, each extending `BaseExecutor` (`base.ts`):
107 provider executors, each extending `BaseExecutor` (`base.ts`):
`antigravity`, `azure-openai`, `blackbox-web`, `chatgpt-web`, `cliproxyapi`,
`cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`,
`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`,
`chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`,
`muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`,
`pollinations`, `qoder`, `vertex`, `devin-desktop`, plus `claudeIdentity.ts`
(shared identity helper) and `index.ts` (registry).
> Note: providers not listed here are served by `default.ts` using the generic
> OpenAI-compatible executor. The full provider catalog (338 providers) lives in
> OpenAI-compatible executor. The full provider catalog (351 providers) lives in
> `src/shared/constants/providers.ts`.
### 4.3 `open-sse/translator/`

4
docs/diagrams/free-tier-budget.svg
View File

@@ -1,4 +1,4 @@
<svg viewBox="0 0 1200 842" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="OmniRoute free-tier budget: about 1.51 billion free tokens per month steady, up to about 2.13 billion in the first month with signup credits. The catalog contains 455 rows, 448 active and 7 discontinued, grouped into 40 recurring pool keys; 20 pools have a published positive monthly token budget and 20 have a zero, uncapped, or keyless budget. Honest pool-deduped math counts each shared free pool once; 15 providers carry a terms-of-service avoid flag. The 20 quantified pools are Mistral 1 billion, LLM7 150 million, Nara 150 million, Gemini 60 million, Cerebras 30 million, Cloudflare AI 30 million, API Airforce 24 million, Ollama Cloud 20 million, Groq 15 million, Bluesminds 7.2 million, SambaNova 6 million, Arcee 4.8 million, Navy 4.5 million, BazaarLink 3.6 million, OpenRouter 1.2 million, Cohere 800 thousand, HuggingChat 500 thousand, Morph 400 thousand, Hugging Face 200 thousand, and Kiro 25 thousand. One-time signup credits add about 626 million. Uncapped providers and the OpenRouter top-up boost are shown separately so they do not inflate the headline. Live usage remains available at /dashboard/free-tiers.">
<svg viewBox="0 0 1200 842" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="OmniRoute free-tier budget: about 1.51 billion free tokens per month steady, up to about 2.13 billion in the first month with signup credits. The catalog contains 454 rows, 447 active and 7 discontinued, grouped into 40 recurring pool keys; 20 pools have a published positive monthly token budget and 20 have a zero, uncapped, or keyless budget. Honest pool-deduped math counts each shared free pool once; 15 providers carry a terms-of-service avoid flag. The 20 quantified pools are Mistral 1 billion, LLM7 150 million, Nara 150 million, Gemini 60 million, Cerebras 30 million, Cloudflare AI 30 million, API Airforce 24 million, Ollama Cloud 20 million, Groq 15 million, Bluesminds 7.2 million, SambaNova 6 million, Arcee 4.8 million, Navy 4.5 million, BazaarLink 3.6 million, OpenRouter 1.2 million, Cohere 800 thousand, HuggingChat 500 thousand, Morph 400 thousand, Hugging Face 200 thousand, and Kiro 25 thousand. One-time signup credits add about 626 million. Uncapped providers and the OpenRouter top-up boost are shown separately so they do not inflate the headline. Live usage remains available at /dashboard/free-tiers.">
<desc>Pool-deduplicated chart of the 20 recurring free-token pools with positive published budgets, plus signup credits and uncapped providers shown separately.</desc>
<defs>
<pattern id="gridPaperF" width="32" height="32" patternUnits="userSpaceOnUse">
@@ -64,7 +64,7 @@
<text x="60" y="228" font-family="Consolas, 'Courier New', monospace" font-size="104" font-weight="800" fill="url(#gradBrandF)">~1.51B</text>
<text x="62" y="266" font-family="Consolas, 'Courier New', monospace" font-size="15" letter-spacing="3" font-weight="700" fill="#a1a1aa">FREE TOKENS / MONTH &#183; <tspan fill="#22c55e">STEADY</tspan></text>
<text x="62" y="298" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="16" fill="#F7F6FC">up to <tspan font-weight="800" fill="#22c55e">~2.13B</tspan> in your first month &#8212; signup credits</text>
<text x="62" y="326" font-family="Consolas, 'Courier New', monospace" font-size="12" fill="#71717a">documented free tiers &#183; <tspan fill="#8b5cf6">40 recurring pools</tspan> &#183; <tspan fill="#8b5cf6">455 catalog entries</tspan> &#183; one endpoint</text>
<text x="62" y="326" font-family="Consolas, 'Courier New', monospace" font-size="12" fill="#71717a">documented free tiers &#183; <tspan fill="#8b5cf6">40 recurring pools</tspan> &#183; <tspan fill="#8b5cf6">454 catalog entries</tspan> &#183; one endpoint</text>
<!-- ═══ Panel · The honest math ═══ -->
<rect x="680" y="84" width="460" height="216" rx="14" fill="#161b22" stroke="#ffffff" stroke-opacity="0.08" stroke-width="1"/>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

2
docs/diagrams/promise-pillars.svg
View File

@@ -73,7 +73,7 @@
<circle cx="6.6" cy="6.6" r="1.4" fill="#fdcb6e" stroke="none"/>
</g>
<text x="862" y="170" font-size="18" font-weight="800" fill="#fdcb6e">$0 to start</text>
<text x="826" y="204" font-size="13.5" fill="#a1a1aa">90+ providers with a free tier, 56 free</text>
<text x="826" y="204" font-size="13.5" fill="#a1a1aa">90+ providers with a free tier, 55 free</text>
<text x="826" y="226" font-size="13.5" fill="#a1a1aa">forever — Qoder, Pollinations, Cloudflare,</text>
<text x="826" y="248" font-size="13.5" fill="#a1a1aa">SiliconFlow… No card needed.</text>
</g>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

6
docs/getting-started/FREE-TIERS-GUIDE.md
View File

@@ -1,6 +1,6 @@
# Free Tiers Guide: Understand and Combine Free AI Access
> **TL;DR**: OmniRoute registers 350 provider IDs, with **154 provider-catalog entries marked `hasFree`**. The stricter audited free-model catalog covers **40 recurring pool keys / 455 entries** (448 active + 7 discontinued). Connect several suitable providers for broader fallback capacity; every quota, approval rule, privacy policy, and paid-overage condition still applies.
> **TL;DR**: OmniRoute registers 351 provider IDs, with **154 provider-catalog entries marked `hasFree`**. The stricter audited free-model catalog covers **40 recurring pool keys / 454 entries** (447 active + 7 discontinued). Connect several suitable providers for broader fallback capacity; every quota, approval rule, privacy policy, and paid-overage condition still applies.
---
@@ -163,8 +163,8 @@ The live, pool-deduplicated catalog currently reports:
| ---------------------------------------------------- | -----------------------------------------------: | ----------------------------------------------------------------------------------------- |
| Recurring quantified grant | **~1.51B tokens/month** | Shared pools counted once; excludes uncapped providers from the sum |
| First month with signup grants | **~2.13B tokens** | Recurring total plus one-time and recurring credits |
| Audited free-model inventory | **40 recurring pool keys / 455 catalog entries** | 448 active + 7 discontinued; distinct from the 350-provider catalog |
| Recurring/keyless free-forever providers represented | **56** | Unique providers across recurring daily/monthly/credit/uncapped and keyless catalog types |
| Audited free-model inventory | **40 recurring pool keys / 454 catalog entries** | 447 active + 7 discontinued; distinct from the 351-provider catalog |
| Recurring/keyless free-forever providers represented | **55** | Unique providers across recurring daily/monthly/credit/uncapped and keyless catalog types |
| Provider catalog entries marked `hasFree` | **154 / 350** | Broader provider metadata; not all have a quantifiable recurring quota |
These values are computed from `open-sse/config/freeModelCatalog.ts`; see the

2
docs/getting-started/PROVIDERS-GUIDE.md
View File

@@ -21,7 +21,7 @@ Think of a provider like a **phone carrier**. Just as you need a phone carrier t
| **Free** | No payment required | Kiro, OpenCode Free, Pollinations | $0 |
| **API Key** | You need an API key | OpenAI, Anthropic, Google | Pay per use |
| **OAuth** | Login with your account | Claude Code, GitHub Copilot | Subscription |
| **Web Cookie** | Uses your browser session | ChatGPT Web, Gemini Web | $0 (uses your account) |
| **Web Cookie** | Uses your browser session | ChatGPT Web (Codex), Gemini Web | $0 (uses your account) |
### Web Cookie Providers

16
docs/getting-started/WEB-COOKIE-GUIDE.md
View File

@@ -80,14 +80,14 @@ The exact credentials required depend on the provider.
Different websites store authentication differently. Some require only cookies, while others may require additional headers or tokens.
| Provider | Credential Format | Provider Guide |
| ----------- | -------------------------------------------------------------- | ------------------------------- |
| Claude Web | Full Cookie request header | `docs/providers/CLAUDE_WEB.md` |
| ChatGPT Web | Full Cookie header or `__Secure-next-auth.session-token` value | `docs/providers/CHATGPT_WEB.md` |
| Gemini Web | _(verify)_ | |
| Copilot Web | _(verify)_ | |
| Grok Web | _(verify)_ | |
| ... | ... | ... |
| Provider | Credential Format | Provider Guide |
| ------------------- | -------------------------- | ------------------------------- |
| Claude Web | Full Cookie request header | `docs/providers/CLAUDE_WEB.md` |
| ChatGPT Web (Codex) | Full Cookie header | `docs/providers/CHATGPT_WEB.md` |
| Gemini Web | _(verify)_ | |
| Copilot Web | _(verify)_ | |
| Grok Web | _(verify)_ | |
| ... | ... | ... |
> Update this table as new Web Cookie providers are added or existing providers change their authentication requirements.

179
docs/i18n/pl/docs/architecture/ARCHITECTURE.md
View File

@@ -488,9 +488,6 @@ globalnych warstwach circuit breaker / connection cooldown / model lockout:
`claudeCodeToolRemapper.ts`
- Kształtowanie fingerprint Claude Code: `open-sse/services/claudeCodeFingerprint.ts`
- Obfuskacja Claude Code: `open-sse/services/claudeCodeObfuscation.ts`
- Klient TLS ChatGPT: `open-sse/services/chatgptTlsClient.ts` (styl curl-impersonate
dla sesji ChatGPT-Web)
- Cache obrazów ChatGPT: `open-sse/services/chatgptImageCache.ts`
Pełny playbook stealth i wskazówki operacyjne: zob.
[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md).
@@ -898,103 +895,103 @@ flowchart LR
Każdy dostawca ma wyspecjalizowany executor rozszerzający `BaseExecutor` (w `open-sse/executors/base.ts`), który zapewnia budowanie URL, konstrukcję nagłówków, retry z exponential backoff, hooki odświeżania poświadczeń oraz metodę orkiestracji `execute()`.
| Executor | Provider(s) | Specjalna obsługa |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamiczna konfiguracja URL/nagłówków per dostawca |
| `AntigravityExecutor` | Google Antigravity | Niestandardowe ID project/session, parsowanie Retry-After, obfuskacja 429 |
| `AzureOpenAIExecutor` | Azure OpenAI | Routing oparty na deployment, egzekwowanie query api-version |
| `BlackboxWebExecutor` | Blackbox AI (web-mode) | Reverse sesji web z emulacją fingerprint TLS |
| `ChatGPTWebExecutor` | ChatGPT web | Klient TLS + zarządzanie cookie sesji (`chatgptTlsClient.ts`) |
| `ClaudeIdentityExecutor` | Claude.ai (CCH path) | Potoki constraint + tool-remap, kształtowanie fingerprint |
| `CliProxyApiExecutor` | CLIProxyAPI-compatible providers | Niestandardowa obsługa auth i protokołu |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Injekcja Account ID, śledzenie użycia oparte na Neurons |
| `CodexExecutor` | OpenAI Codex | Wstrzykuje instrukcje systemowe, wymusza reasoning effort |
| `CommandCodeExecutor` | Command Code | OAuth + rotacja nagłówków per sesja |
| `CursorExecutor` | Cursor IDE | Protokół ConnectRPC, kodowanie Protobuf, podpisywanie żądań przez checksum |
| `DevinCliExecutor` | Devin CLI | Mostkowanie cyklu życia zadań Devin przez moduł cloud agent |
| `GithubExecutor` | GitHub Copilot | Odświeżanie tokenu Copilot, nagłówki imitujące VSCode |
| `GitlabExecutor` | GitLab Duo | OAuth GitLab + routing w zakresie projektu |
| `GlmExecutor` | Z.AI GLM (incl. `glmt` preset) | Świadomy thinking-budget, stałe presetu GLMT |
| `GrokWebExecutor` | xAI Grok web | Reverse sesji web, wybór trybu (think/standard) |
| `KieExecutor` | KIE | Niestandardowe wydawanie tokenów z rotującymi kotwicami sesji |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | Konwersja binarnego formatu AWS EventStream → SSE |
| `MuseSparkWebExecutor` | Muse Spark (web) | Reverse sesji web z mostkowaniem image-message |
| `NlpCloudExecutor` | NLP Cloud | Kształt body żądania specyficzny dla dostawcy |
| `OpenCodeExecutor` | OpenCode | Konfiguracja dostawcy zgodna z AI SDK |
| `PerplexityWebExecutor` | Perplexity web | Reverse sesji web dla kontynuacji czatu |
| `PetalsExecutor` | Petals distributed inference | Zdecentralizowany routing swarm |
| `PollinationsExecutor` | Pollinations AI | Klucz API niewymagany, żądania z rate limitem |
| `QoderExecutor` | Qoder AI | Wsparcie PAT i OAuth, darmowy tier multi-model |
| `VertexExecutor` | Google Vertex AI | Auth service account, endpointy oparte na regionie |
| `DevinDesktopExecutor` | Devin Desktop | Importowany klucz API + strumieniowanie czatu Connect-protobuf |
| Executor | Provider(s) | Specjalna obsługa |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamiczna konfiguracja URL/nagłówków per dostawca |
| `AntigravityExecutor` | Google Antigravity | Niestandardowe ID project/session, parsowanie Retry-After, obfuskacja 429 |
| `AzureOpenAIExecutor` | Azure OpenAI | Routing oparty na deployment, egzekwowanie query api-version |
| `BlackboxWebExecutor` | Blackbox AI (web-mode) | Reverse sesji web z emulacją fingerprint TLS |
| `ClaudeIdentityExecutor` | Claude.ai (CCH path) | Potoki constraint + tool-remap, kształtowanie fingerprint |
| `CliProxyApiExecutor` | CLIProxyAPI-compatible providers | Niestandardowa obsługa auth i protokołu |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Injekcja Account ID, śledzenie użycia oparte na Neurons |
| `CodexExecutor` | OpenAI Codex | Wstrzykuje instrukcje systemowe, wymusza reasoning effort |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex) | Most Responses API przez sesję przeglądarki z przypięciem wątku/turn |
| `CommandCodeExecutor` | Command Code | OAuth + rotacja nagłówków per sesja |
| `CursorExecutor` | Cursor IDE | Protokół ConnectRPC, kodowanie Protobuf, podpisywanie żądań przez checksum |
| `DevinCliExecutor` | Devin CLI | Mostkowanie cyklu życia zadań Devin przez moduł cloud agent |
| `GithubExecutor` | GitHub Copilot | Odświeżanie tokenu Copilot, nagłówki imitujące VSCode |
| `GitlabExecutor` | GitLab Duo | OAuth GitLab + routing w zakresie projektu |
| `GlmExecutor` | Z.AI GLM (incl. `glmt` preset) | Świadomy thinking-budget, stałe presetu GLMT |
| `GrokWebExecutor` | xAI Grok web | Reverse sesji web, wybór trybu (think/standard) |
| `KieExecutor` | KIE | Niestandardowe wydawanie tokenów z rotującymi kotwicami sesji |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | Konwersja binarnego formatu AWS EventStream → SSE |
| `MuseSparkWebExecutor` | Muse Spark (web) | Reverse sesji web z mostkowaniem image-message |
| `NlpCloudExecutor` | NLP Cloud | Kształt body żądania specyficzny dla dostawcy |
| `OpenCodeExecutor` | OpenCode | Konfiguracja dostawcy zgodna z AI SDK |
| `PerplexityWebExecutor` | Perplexity web | Reverse sesji web dla kontynuacji czatu |
| `PetalsExecutor` | Petals distributed inference | Zdecentralizowany routing swarm |
| `PollinationsExecutor` | Pollinations AI | Klucz API niewymagany, żądania z rate limitem |
| `QoderExecutor` | Qoder AI | Wsparcie PAT i OAuth, darmowy tier multi-model |
| `VertexExecutor` | Google Vertex AI | Auth service account, endpointy oparte na regionie |
| `DevinDesktopExecutor` | Devin Desktop | Importowany klucz API + strumieniowanie czatu Connect-protobuf |
Wszystkie pozostałe dostawcy (w tym niestandardowe węzły kompatybilne) używają `DefaultExecutor`.
## Macierz kompatybilności dostawców
> **Uwaga:** Poniższa macierz to reprezentatywna próbka spośród 237 zarejestrowanych dostawców w
> **Uwaga:** Poniższa macierz to reprezentatywna próbka spośród 351 zarejestrowanych dostawców w
> OmniRoute v3.8.0. Kanoniczna i stale aktualizowana lista: zob.
> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (auto-generowana) lub źródło
> prawdy w `src/shared/constants/providers.ts` (walidowane Zod przy ładowaniu).
| Dostawca | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API |
| ----------------- | ---------------- | ----------------------- | ---------------- | ---------- | ------------- | ------------------ |
| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Tylko Admin |
| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Pełne API quota |
| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ wymuszony | ❌ | ✅ | ✅ Rate limity |
| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Snapshoty quota |
| Cursor | cursor | Niestandardowy checksum | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limity użycia |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per żądanie |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API Token + Acct ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | Brak (bez klucza) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API Key (opcjonalny) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Service Account | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per żądanie |
| Z.AI / GLM | openai | API Key / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | API Key | ✅ | ✅ | ❌ | ⚠️ Per żądanie |
| Kimi Coding | openai | OAuth / API Key | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Importowany klucz API | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Na żądanie |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Lokalne logowanie CLI | ✅ | ✅ | ❌ | ✅ Task API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Rate limity |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ Task API |
| AgentRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| ChatGPT-Web | openai | Cookie sesji + TLS | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Cookie sesji | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Cookie sesji | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Cookie sesji + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Cookie sesji | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API Key | ✅ | ✅ | ❌ | ⚠️ Polityka quota |
| BazaarLink | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | Brak | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per żądanie |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Custom | ✅ | ✅ | ❌ | ❌ |
| Dostawca | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API |
| ------------------- | ---------------- | ----------------------- | ---------------- | ---------- | ------------- | ------------------ |
| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Tylko Admin |
| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Pełne API quota |
| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ wymuszony | ❌ | ✅ | ✅ Rate limity |
| ChatGPT Web (Codex) | openai-responses | Sesja przeglądarki | ✅ wymuszony | ❌ | ❌ | ❌ |
| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Snapshoty quota |
| Cursor | cursor | Niestandardowy checksum | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limity użycia |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per żądanie |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API Token + Acct ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | Brak (bez klucza) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API Key (opcjonalny) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Service Account | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per żądanie |
| Z.AI / GLM | openai | API Key / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | API Key | ✅ | ✅ | ❌ | ⚠️ Per żądanie |
| Kimi Coding | openai | OAuth / API Key | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Importowany klucz API | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Na żądanie |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Lokalne logowanie CLI | ✅ | ✅ | ❌ | ✅ Task API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Rate limity |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ Task API |
| AgentRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Cookie sesji | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Cookie sesji | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Cookie sesji + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Cookie sesji | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API Key | ✅ | ✅ | ❌ | ⚠️ Polityka quota |
| BazaarLink | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | Brak | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per żądanie |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Custom | ✅ | ✅ | ❌ | ❌ |
## Pokrycie tłumaczenia formatów

9
docs/i18n/pl/docs/architecture/CODEBASE_DOCUMENTATION.md
View File

@@ -234,7 +234,6 @@ v1/
├── audio/{speech, transcriptions}/ TTS + STT
├── batches/[id]/{cancel}, batches/ OpenAI Batches API
├── chat/completions/ Chat Completions (główny endpoint)
├── chatgpt-web/ compat ChatGPT-Web
├── completions/ Legacy text completions
├── embeddings/ Embeddings
├── files/[id]/, files/ Pliki API
@@ -482,16 +481,16 @@ open-sse/
### 4.2 `open-sse/executors/`
84 executory providerów, każdy rozszerza `BaseExecutor` (`base.ts`):
107 executorów providerów, każdy rozszerza `BaseExecutor` (`base.ts`):
`antigravity`, `azure-openai`, `blackbox-web`, `chatgpt-web`, `cliproxyapi`,
`cloudflare-ai`, `codex`, `commiCode`, `cursor`, `default`, `devin-cli`,
`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`,
`chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commiCode`, `cursor`, `default`, `devin-cli`,
`muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`,
`pollinations`, `qoder`, `vertex`, `windsurf`, plus `claudeIdentity.ts`
(współdzielony helper identity) i `index.ts` (rejestr).
> Uwaga: providery niewymienione tutaj są obsługiwane przez `default.ts` z generycznym
> executorem zgodnym z OpenAI. Pełny katalog providerów (329 wpisów) jest w
> executorem zgodnym z OpenAI. Pełny katalog providerów (351 wpisów) jest w
> `src/shared/constants/providers.ts`.
### 4.3 `open-sse/translator/`

24
docs/i18n/pl/docs/getting-started/PROVIDERS-GUIDE.md
View File

@@ -15,7 +15,7 @@ Traktuj providera jak **operatora komórkowego**. Tak jak potrzebujesz operatora
| **Free** | Bez płatności | Kiro, OpenCode Free, Pollinations | $0 |
| **API Key** | Wymagany klucz API | OpenAI, Anthropic, Google | Płatność za użycie |
| **OAuth** | Logowanie kontem | Claude Code, GitHub Copilot | Subskrypcja |
| **Web Cookie** | Używa sesji przeglądarki | ChatGPT Web, Gemini Web | $0 (korzysta z Twojego konta) |
| **Web Cookie** | Używa sesji przeglądarki | ChatGPT Web (Codex), Gemini Web | $0 (korzysta z Twojego konta) |
### Providery Web Cookie
@@ -67,17 +67,17 @@ Zobacz **[WEB-COOKIE-GUIDE.md](./WEB-COOKIE-GUIDE.md)** — ogólna konfiguracja
Te providery oferują **darmowy dostęp** bez karty kredytowej:
| Provider | Darmowy limit | Modele | Jak połączyć |
| ----------------- | ----------------- | ---------------------------------------- | ------------------ |
| **Kiro AI** | 50 credits/mies. | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | Bez auth |
| **OpenCode Free** | Brak opublikowanego capu; limity obowiązują | GPT-4o, Claude, Gemini | Bez auth |
| **Pollinations** | Bez klucza | GPT-5, Claude, Gemini, DeepSeek, Llama 4 | Bez auth |
| **LongCat** | 10M jednorazowo | LongCat-2.0 | Klucz API + KYC |
| **Cloudflare AI** | 10K neurons/dzień | 50+ modeli | Bez auth |
| **NVIDIA NIM** | ~40 RPM | 129 modeli | Wymagany klucz API |
| **Cerebras** | 1M tokenów/dzień | Qwen3 235B, GPT-OSS 120B | Wymagany klucz API |
| **Qwen** | Brak opublikowanego capu; limity obowiązują | Qwen3-coder-plus/flash/next | Bez auth |
| **Qoder** | Brak opublikowanego capu; limity obowiązują | Kimi-K2, DeepSeek-R1, Qwen3-coder | Bez auth |
| Provider | Darmowy limit | Modele | Jak połączyć |
| ----------------- | ------------------------------------------- | ---------------------------------------- | ------------------ |
| **Kiro AI** | 50 credits/mies. | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | Bez auth |
| **OpenCode Free** | Brak opublikowanego capu; limity obowiązują | GPT-4o, Claude, Gemini | Bez auth |
| **Pollinations** | Bez klucza | GPT-5, Claude, Gemini, DeepSeek, Llama 4 | Bez auth |
| **LongCat** | 10M jednorazowo | LongCat-2.0 | Klucz API + KYC |
| **Cloudflare AI** | 10K neurons/dzień | 50+ modeli | Bez auth |
| **NVIDIA NIM** | ~40 RPM | 129 modeli | Wymagany klucz API |
| **Cerebras** | 1M tokenów/dzień | Qwen3 235B, GPT-OSS 120B | Wymagany klucz API |
| **Qwen** | Brak opublikowanego capu; limity obowiązują | Qwen3-coder-plus/flash/next | Bez auth |
| **Qoder** | Brak opublikowanego capu; limity obowiązują | Kimi-K2, DeepSeek-R1, Qwen3-coder | Bez auth |
**Wskazówka**: Podłącz kilka darmowych providerów, aby zwiększyć pokrycie fallbacku.
Brak opublikowanego limitu tokenów nie oznacza nieograniczonej dostępności.

16
docs/i18n/pl/docs/getting-started/WEB-COOKIE-GUIDE.md
View File

@@ -80,14 +80,14 @@ Dokładne wymagane poświadczenia zależą od dostawcy.
Różne witryny przechowują uwierzytelnianie na różne sposoby. Niektóre wymagają tylko ciasteczek, inne mogą wymagać dodatkowych nagłówków lub tokenów.
| Dostawca | Format poświadczeń | Przewodnik dostawcy |
| ----------- | ----------------------------- | ------------------------------ |
| Claude Web | Pełny nagłówek żądania Cookie | `docs/providers/CLAUDE_WEB.md` |
| ChatGPT Web | _(verify)_ | |
| Gemini Web | _(verify)_ | |
| Copilot Web | _(verify)_ | |
| Grok Web | _(verify)_ | |
| ... | ... | ... |
| Dostawca | Format poświadczeń | Przewodnik dostawcy |
| ------------------- | ----------------------------- | ------------------------------- |
| Claude Web | Pełny nagłówek żądania Cookie | `docs/providers/CLAUDE_WEB.md` |
| ChatGPT Web (Codex) | Pełny nagłówek Cookie | `docs/providers/CHATGPT_WEB.md` |
| Gemini Web | _(verify)_ | |
| Copilot Web | _(verify)_ | |
| Grok Web | _(verify)_ | |
| ... | ... | ... |
> Aktualizuj tę tabelę, gdy dodawani są nowi dostawcy Web Cookie lub gdy istniejący dostawcy zmieniają wymagania uwierzytelniania.

2
docs/i18n/pl/docs/security/BAN_DETECTION.md
View File

@@ -87,7 +87,7 @@ do scraperów OAuth/subskrypcyjnych. Wynikowy stan terminalny dotyczy **połącz
nie providera.
Przy tym wbudowane _łańcuchy_ są zorientowane na providery subskrypcyjne/OAuth
z realnym ryzykiem bana (ChatGPT Web, Claude Web, Codex, Muse Spark, Antigravity).
z realnym ryzykiem bana (ChatGPT Web Codex, Claude Web, Codex, Muse Spark, Antigravity).
Provider z kluczem API odpali detektor tylko wtedy, gdy ciało błędu dosłownie
zawiera jeden z podciągów.

26
docs/i18n/pl/docs/security/STEALTH_GUIDE.md
View File

@@ -6,7 +6,7 @@ lastUpdated: 2026-06-28
# Przewodnik po stealth
> **Source of truth:** `open-sse/utils/tlsClient.ts`, `open-sse/services/{chatgptTlsClient,claudeCodeCCH,claudeCodeFingerprint,claudeCodeObfuscation,claudeCodeCompatible}.ts`, `open-sse/config/cliFingerprints.ts`, `src/mitm/`
> **Source of truth:** `open-sse/utils/tlsClient.ts`, `open-sse/services/{claudeCodeCCH,claudeCodeFingerprint,claudeCodeObfuscation,claudeCodeCompatible}.ts`, `open-sse/config/cliFingerprints.ts`, `src/mitm/`
> **Last updated:** 2026-06-28 — v3.8.40
> **Audience:** Engineers maintaining provider-specific stealth integrations.
@@ -14,7 +14,7 @@ OmniRoute integruje się z providerami, których edge aktywnie fingerprintuje ni
## Uwaga prawna i etyczna
Funkcje stealth istnieją po to, by OmniRoute mógł działać jako warstwa kompatybilności między oficjalnymi kontami użytkownika (Claude Code CLI, ChatGPT Desktop/Web, Antigravity, Cursor itd.) a ujednoliconym API OmniRoute. **Nie** służą do omijania fraud detection, współdzielenia poświadczeń ani naruszania Terms of Service providera. Maintainerzy oczekują, że operatorzy będą przestrzegać upstream ToS, które zaakceptowali przy tworzeniu kont.
Funkcje stealth istnieją po to, by OmniRoute mógł działać jako warstwa kompatybilności między oficjalnymi kontami użytkownika (Claude Code CLI, Codex, Antigravity, Cursor itd.) a ujednoliconym API OmniRoute. **Nie** służą do omijania fraud detection, współdzielenia poświadczeń ani naruszania Terms of Service providera. Maintainerzy oczekują, że operatorzy będą przestrzegać upstream ToS, które zaakceptowali przy tworzeniu kont.
---
@@ -29,20 +29,6 @@ Lazy-loaded sesja `wreq-js`, która impersonuje **Chrome 124 na macOS**. Używan
- Timeout: `TLS_CLIENT_TIMEOUT_MS` (dziedziczy z `FETCH_TIMEOUT_MS`, domyślnie 600000)
- Response z `wreq-js` jest zgodny z fetch (`headers`, `text()`, `json()`, `clone()`, `body`).
### `open-sse/services/chatgptTlsClient.ts` — tls-client-node (Firefox 148)
Dedykowany impersonator TLS dla `chatgpt.com`. Konfiguracja Cloudflare ChatGPT pinuje `cf_clearance` do JA3/JA4 + kolejności ramek HTTP/2 SETTINGS — handshake undici dostaje `cf-mitigated: challenge` nawet przy poprawnych cookies.
- Profile: `firefox_148` (musi pasować do wysyłanego `User-Agent` Firefox 148)
- Mode: `runtimeMode: "native"` (shared library ładowana przez koffi; unika managed sidecar HTTP)
- `withRandomTLSExtensionOrder: true`
- `tlsFetchChatGpt(url, options)` obsługuje streaming (zapisuje body do pliku tymczasowego, tailed jako `ReadableStream`)
- Hang detection: `raceWithTimeout` + `TlsClientHangError` wywołuje `resetClientCache()`, więc kolejne wywołanie respawnuje binding
- Proxy resolution (priority): per-call `proxyUrl` → `OMNIROUTE_TLS_PROXY_URL` → `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` (natywny binding **nie** czyta tych env sam; trzeba je przekazać)
- Errors: `TlsClientUnavailableError` (brak binary), `TlsClientHangError` (binding w deadlocku)
---
## Pakiet stealth Claude Code
Gdy `cliCompatMode` jest włączony, OmniRoute przekształca wychodzące żądania Claude tak, by były nieodróżnialne od ruchu `claude-cli`. Współpracują trzy moduły:
@@ -253,17 +239,17 @@ OmniRoute czyści inbound nagłówki klienta przed forwardem, by żądanie przyc
2. Wyodrębnij JA3/JA4 i literową kolejność nagłówków
3. Zaktualizuj odpowiedni wpis `CLI_FINGERPRINTS[...]`
4. Podbij pasujący domyślny `*_USER_AGENT` w `.env.example`
5. Jeśli zmienił się sam TLS handshake: zaktualizuj `chatgptTlsClient.ts::CHATGPT_PROFILE` lub opcję wreq-js `browser:`
6. Odpal `chatgptTlsClient.test.ts` i ręcznego canary przeciwko żywemu providerowi
5. Jeśli zmienił się sam TLS handshake, zaktualizuj odpowiedni wrapper providera lub opcję wreq-js `browser:`
6. Odpal testy TLS danego providera i ręcznego canary przeciwko żywemu providerowi
7. Wypuść w patch release; udokumentuj w `CHANGELOG.md`
---
## Testy
- `open-sse/services/__tests__/chatgptTlsClient.test.ts` — priorytet resolution proxy, obsługa abort, hang recovery
- `open-sse/services/__tests__/claudeTlsClient.test.ts` — zachowanie współdzielonego wrappera TLS
- `tests/unit/anthropic-cache-fingerprint.test.ts` — determinizm fingerprintu
- `tests/unit/chatgpt-web.test.ts` — end-to-end ścieżka stealth dla ChatGPT
- `tests/unit/chatgpt-web-source-retirement.test.ts` — wspólne źródło ChatGPT Web pozostaje nieobecne, a Codex Web pozostaje zachowany
---

179
docs/i18n/pt-BR/docs/architecture/ARCHITECTURE.md
View File

@@ -469,9 +469,6 @@ camadas globais de disjuntor / cooldown de conexão / bloqueio de modelo:
`claudeCodeToolRemapper.ts`
- Modelagem de impressão digital do Claude Code: `open-sse/services/claudeCodeFingerprint.ts`
- Ofuscação do Claude Code: `open-sse/services/claudeCodeObfuscation.ts`
- Cliente TLS do ChatGPT: `open-sse/services/chatgptTlsClient.ts` (estilo de
impersonação curl para sessões do ChatGPT-Web)
- Cache de imagem do ChatGPT: `open-sse/services/chatgptImageCache.ts`
Para o guia completo de furtividade e orientações operacionais, veja
[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md).
@@ -879,35 +876,35 @@ flowchart LR
Cada provedor tem um executor especializado que estende `BaseExecutor` (em `open-sse/executors/base.ts`), que fornece construção de URL, construção de cabeçalhos, tentativas com retrocesso exponencial, ganchos de atualização de credenciais e o método de orquestração `execute()`.
| Executor | Provedor(es) | Tratamento Especial |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Configuração dinâmica de URL/cabeçalho por provedor |
| `AntigravityExecutor` | Google Antigravity | IDs de projeto/sessão personalizados, análise de Retry-After, ofuscação de 429 |
| `AzureOpenAIExecutor` | Azure OpenAI | Roteamento baseado em implantação, aplicação de consulta de api-version |
| `BlackboxWebExecutor` | Blackbox AI (modo web) | Reversão de sessão web com emulação de impressão digital TLS |
| `ChatGPTWebExecutor` | ChatGPT web | Gerenciamento de cliente TLS + cookie de sessão (`chatgptTlsClient.ts`) |
| `ClaudeIdentityExecutor` | Claude.ai (caminho CCH) | Pipelines de restrição + remapeamento de ferramentas, modelagem de impressão digital |
| `CliProxyApiExecutor` | Provedores compatíveis com CLIProxyAPI | Manipulação personalizada de autenticação e protocolo |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Injeção de ID de conta, rastreamento de uso baseado em Neurons |
| `CodexExecutor` | OpenAI Codex | Injeções de instruções do sistema, força de esforço de raciocínio |
| `CommandCodeExecutor` | Código de Comando | Rotação de cabeçalho por sessão + OAuth |
| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificação Protobuf, assinatura de requisições via checksum |
| `DevinCliExecutor` | Devin CLI | Conexão do ciclo de vida da tarefa Devin via módulo de agente em nuvem |
| `GithubExecutor` | GitHub Copilot | Atualização de token do Copilot, cabeçalhos imitando VSCode |
| `GitlabExecutor` | GitLab Duo | Roteamento baseado em projeto + OAuth do GitLab |
| `GlmExecutor` | Z.AI GLM (incl. preset `glmt`) | Consciente do orçamento de pensamento, constantes do preset GLMT |
| `GrokWebExecutor` | xAI Grok web | Reversão de sessão web, seleção de modo (pensar/padrão) |
| `KieExecutor` | KIE | Emissão de token personalizada com âncoras de sessão rotativas |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binário do AWS EventStream → conversão para SSE |
| `MuseSparkWebExecutor` | Muse Spark (web) | Reversão de sessão web com integração de imagem-mensagem |
| `NlpCloudExecutor` | NLP Cloud | Formato de corpo de requisição específico do provedor |
| `OpenCodeExecutor` | OpenCode | Configuração de provedor compatível com AI SDK |
| `PerplexityWebExecutor` | Perplexity web | Reversão de sessão web para continuidade de chat |
| `PetalsExecutor` | Inferência distribuída Petals | Roteamento de enxame descentralizado |
| `PollinationsExecutor` | Pollinations AI | Nenhuma chave de API necessária, requisições limitadas por taxa |
| `QoderExecutor` | Qoder AI | Suporte a PAT e OAuth, nível gratuito multi-modelo |
| `VertexExecutor` | Google Vertex AI | Autenticação de conta de serviço, endpoints baseados em região |
| `DevinDesktopExecutor` | Devin Desktop | Chave de API importada + streaming de chat Connect-protobuf |
| Executor | Provedor(es) | Tratamento Especial |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Configuração dinâmica de URL/cabeçalho por provedor |
| `AntigravityExecutor` | Google Antigravity | IDs de projeto/sessão personalizados, análise de Retry-After, ofuscação de 429 |
| `AzureOpenAIExecutor` | Azure OpenAI | Roteamento baseado em implantação, aplicação de consulta de api-version |
| `BlackboxWebExecutor` | Blackbox AI (modo web) | Reversão de sessão web com emulação de impressão digital TLS |
| `ClaudeIdentityExecutor` | Claude.ai (caminho CCH) | Pipelines de restrição + remapeamento de ferramentas, modelagem de impressão digital |
| `CliProxyApiExecutor` | Provedores compatíveis com CLIProxyAPI | Manipulação personalizada de autenticação e protocolo |
| `CloudflareAiExecutor` | Cloudflare Workers AI | Injeção de ID de conta, rastreamento de uso baseado em Neurons |
| `CodexExecutor` | OpenAI Codex | Injeções de instruções do sistema, força de esforço de raciocínio |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex) | Ponte Responses API por sessão de navegador com fixação de thread/turn |
| `CommandCodeExecutor` | Código de Comando | Rotação de cabeçalho por sessão + OAuth |
| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificação Protobuf, assinatura de requisições via checksum |
| `DevinCliExecutor` | Devin CLI | Conexão do ciclo de vida da tarefa Devin via módulo de agente em nuvem |
| `GithubExecutor` | GitHub Copilot | Atualização de token do Copilot, cabeçalhos imitando VSCode |
| `GitlabExecutor` | GitLab Duo | Roteamento baseado em projeto + OAuth do GitLab |
| `GlmExecutor` | Z.AI GLM (incl. preset `glmt`) | Consciente do orçamento de pensamento, constantes do preset GLMT |
| `GrokWebExecutor` | xAI Grok web | Reversão de sessão web, seleção de modo (pensar/padrão) |
| `KieExecutor` | KIE | Emissão de token personalizada com âncoras de sessão rotativas |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binário do AWS EventStream → conversão para SSE |
| `MuseSparkWebExecutor` | Muse Spark (web) | Reversão de sessão web com integração de imagem-mensagem |
| `NlpCloudExecutor` | NLP Cloud | Formato de corpo de requisição específico do provedor |
| `OpenCodeExecutor` | OpenCode | Configuração de provedor compatível com AI SDK |
| `PerplexityWebExecutor` | Perplexity web | Reversão de sessão web para continuidade de chat |
| `PetalsExecutor` | Inferência distribuída Petals | Roteamento de enxame descentralizado |
| `PollinationsExecutor` | Pollinations AI | Nenhuma chave de API necessária, requisições limitadas por taxa |
| `QoderExecutor` | Qoder AI | Suporte a PAT e OAuth, nível gratuito multi-modelo |
| `VertexExecutor` | Google Vertex AI | Autenticação de conta de serviço, endpoints baseados em região |
| `DevinDesktopExecutor` | Devin Desktop | Chave de API importada + streaming de chat Connect-protobuf |
Todos os outros provedores (incluindo nós compatíveis personalizados) usam o `DefaultExecutor`.
@@ -918,65 +915,65 @@ Todos os outros provedores (incluindo nós compatíveis personalizados) usam o `
> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (gerada automaticamente) ou a fonte
> de verdade em `src/shared/constants/providers.ts` (validada pelo Zod na carga).
| Provedor | Formato | Autenticação | Stream | Não-Stream | Atualização de Token | API de Uso |
| ----------------- | ---------------- | -------------------------- | ---------------- | ---------- | -------------------- | -------------------- |
| Claude | claude | Chave de API / OAuth | ✅ | ✅ | ✅ | ⚠️ Somente Admin |
| Gemini | gemini | Chave de API / OAuth | ✅ | ✅ | ✅ | ⚠️ Console da Nuvem |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ API de cota total |
| OpenAI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ forçado | ❌ | ✅ | ✅ Limites de taxa |
| GitHub Copilot | openai | OAuth + Token Copilot | ✅ | ✅ | ✅ | ✅ Capturas de cota |
| Cursor | cursor | Checksum personalizado | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites de uso |
| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | Chave de API | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | Token de API + ID da conta | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | Nenhum (sem chave) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | Chave de API (opcional) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Conta de Serviço | ✅ | ✅ | ✅ | ⚠️ Console da Nuvem |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| Z.AI / GLM | openai | Chave de API / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | Chave de API | ✅ | ✅ | ❌ | ⚠️ Por solicitação |
| Kimi Coding | openai | OAuth / Chave de API | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Chave de API importada | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Por solicitação |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Login local da CLI | ✅ | ✅ | ❌ | ✅ API de Tarefas |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Limites de taxa |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ API de Tarefas |
| AgentRouter | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| ChatGPT-Web | openai | Cookie de sessão + TLS | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Cookie de sessão + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | Chave de API | ✅ | ✅ | ❌ | ⚠️ Política de cota |
| BazaarLink | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | Nenhum | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Personalizado | ✅ | ✅ | ❌ | ❌ |
| Provedor | Formato | Autenticação | Stream | Não-Stream | Atualização de Token | API de Uso |
| ------------------- | ---------------- | -------------------------- | ---------------- | ---------- | -------------------- | -------------------- |
| Claude | claude | Chave de API / OAuth | ✅ | ✅ | ✅ | ⚠️ Somente Admin |
| Gemini | gemini | Chave de API / OAuth | ✅ | ✅ | ✅ | ⚠️ Console da Nuvem |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ API de cota total |
| OpenAI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ forçado | ❌ | ✅ | ✅ Limites de taxa |
| ChatGPT Web (Codex) | openai-responses | Sessão de navegador | ✅ forçado | ❌ | ❌ | ❌ |
| GitHub Copilot | openai | OAuth + Token Copilot | ✅ | ✅ | ✅ | ✅ Capturas de cota |
| Cursor | cursor | Checksum personalizado | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites de uso |
| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | Chave de API | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | Token de API + ID da conta | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | Nenhum (sem chave) | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | Chave de API (opcional) | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | Conta de Serviço | ✅ | ✅ | ✅ | ⚠️ Console da Nuvem |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| Z.AI / GLM | openai | Chave de API / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | Chave de API | ✅ | ✅ | ❌ | ⚠️ Por solicitação |
| Kimi Coding | openai | OAuth / Chave de API | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | Chave de API importada | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ Por solicitação |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | Login local da CLI | ✅ | ✅ | ❌ | ✅ API de Tarefas |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Limites de taxa |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ API de Tarefas |
| AgentRouter | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | Cookie de sessão + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | Chave de API | ✅ | ✅ | ❌ | ⚠️ Política de cota |
| BazaarLink | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | Nenhum | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Por solicitação |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | Personalizado | ✅ | ✅ | ❌ | ❌ |
## Cobertura de Tradução de Formato

221
docs/i18n/zh-CN/docs/architecture/ARCHITECTURE.md
View File

@@ -19,7 +19,7 @@ OmniRoute 是基于 Next.js 构建的本地 AI 路由网关和控制台。
核心能力：
- OpenAI 兼容的 API 接口，供 CLI/工具使用（237 个服务商、68 个执行器）
- OpenAI 兼容的 API 接口，供 CLI/工具使用（351 个服务商、107 个执行器）
- 跨服务商格式的请求/响应转换
- 模型 Combo 容灾（多模型序列）
- 结构化 Combo 步骤（`服务商 + 模型 + 连接`），通过 `compositeTiers` 在运行时排序
@@ -487,9 +487,6 @@ FSM 状态转换反馈到 Auto Combo 的评分中，使后台/自动化任务偏
`claudeCodeToolRemapper.ts`
- Claude Code 指纹塑造：`open-sse/services/claudeCodeFingerprint.ts`
- Claude Code 混淆：`open-sse/services/claudeCodeObfuscation.ts`
- ChatGPT TLS 客户端：`open-sse/services/chatgptTlsClient.ts`（为 ChatGPT-Web 会话
提供 curl-impersonate 风格的 TLS 指纹）
- ChatGPT 图片缓存：`open-sse/services/chatgptImageCache.ts`
完整隐身策略和操作指南参见
[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md)。
@@ -896,104 +893,104 @@ flowchart LR
每个服务商都有一个继承 `BaseExecutor`（在 `open-sse/executors/base.ts` 中）的专用执行器，该基类提供了 URL 构建、Header 构造、带指数退避的重试、凭据刷新钩子以及 `execute()` 编排方法。
| 执行器 | 服务商 | 特殊处理 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA 等 | 每服务商动态 URL/Header 配置 |
| `AntigravityExecutor` | Google Antigravity | 自定义项目/会话 ID、Retry-After 解析、429 混淆 |
| `AzureOpenAIExecutor` | Azure OpenAI | 基于部署的路由、api-version 查询参数强制执行 |
| `BlackboxWebExecutor` | Blackbox AI (web-mode) | Web 会话反向 + TLS 指纹模拟 |
| `ChatGPTWebExecutor` | ChatGPT web | TLS 客户端 + 会话 Cookie 管理（`chatgptTlsClient.ts`）|
| `ClaudeIdentityExecutor` | Claude.ai (CCH 通道) | 约束 + Tool 重映射管线、指纹塑造 |
| `CliProxyApiExecutor` | CLIProxyAPI 兼容服务商 | 自定义认证和协议处理 |
| `CloudflareAiExecutor` | Cloudflare Workers AI | 帐户 ID 注入、基于 Neurons 的用量追踪 |
| `CodexExecutor` | OpenAI Codex | 注入系统指令、强制推理力度 |
| `CommandCodeExecutor` | Command Code | OAuth + 每会话 Header 轮换 |
| `CursorExecutor` | Cursor IDE | ConnectRPC 协议、Protobuf 编码、基于校验和的请求签名|
| `DevinCliExecutor` | Devin CLI | Devin 任务生命周期桥接（通过云代理模块） |
| `GithubExecutor` | GitHub Copilot | Copilot Token 刷新、VSCode 模仿 Header |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth + 项目级路由 |
| `GlmExecutor` | Z.AI GLM（含 `glmt` 预设） | Thinking Budget 感知、GLMT 预设常量 |
| `GrokWebExecutor` | xAI Grok web | Web 会话反向、模式选择（think/standard） |
| `KieExecutor` | KIE | 自定义 Token 签发 + 轮换会话锚点 |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream 二进制格式 → SSE 转换 |
| `MuseSparkWebExecutor` | Muse Spark (web) | Web 会话反向 + 图片消息桥接 |
| `NlpCloudExecutor` | NLP Cloud | 服务商专属请求体形状 |
| `OpenCodeExecutor` | OpenCode | AI SDK 兼容服务商初始化 |
| `PerplexityWebExecutor` | Perplexity web | Web 会话反向，用于聊延续 |
| `PetalsExecutor` | Petals distributed inference | 去中心化集群路由 |
| `PollinationsExecutor` | Pollinations AI | 无需 API Key、带速率限制的请求 |
| `QoderExecutor` | Qoder AI | PAT 和 OAuth 支持、多模型免费层 |
| `VertexExecutor` | Google Vertex AI | 服务帐户认证、基于区域的端点 |
| `DevinDesktopExecutor` | Devin Desktop | 导入的 API 密钥 + Connect-protobuf 聊天流 |
| 执行器 | 服务商 | 特殊处理 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA 等 | 每服务商动态 URL/Header 配置 |
| `AntigravityExecutor` | Google Antigravity | 自定义项目/会话 ID、Retry-After 解析、429 混淆 |
| `AzureOpenAIExecutor` | Azure OpenAI | 基于部署的路由、api-version 查询参数强制执行 |
| `BlackboxWebExecutor` | Blackbox AI (web-mode) | Web 会话反向 + TLS 指纹模拟 |
| `ClaudeIdentityExecutor` | Claude.ai (CCH 通道) | 约束 + Tool 重映射管线、指纹塑造 |
| `CliProxyApiExecutor` | CLIProxyAPI 兼容服务商 | 自定义认证和协议处理 |
| `CloudflareAiExecutor` | Cloudflare Workers AI | 帐户 ID 注入、基于 Neurons 的用量追踪 |
| `CodexExecutor` | OpenAI Codex | 注入系统指令、强制推理力度 |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex) | 浏览器会话 Responses API 桥接与线程/轮次固定 |
| `CommandCodeExecutor` | Command Code | OAuth + 每会话 Header 轮换 |
| `CursorExecutor` | Cursor IDE | ConnectRPC 协议、Protobuf 编码、基于校验和的请求签名 |
| `DevinCliExecutor` | Devin CLI | Devin 任务生命周期桥接（通过云代理模块） |
| `GithubExecutor` | GitHub Copilot | Copilot Token 刷新、VSCode 模仿 Header |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth + 项目级路由 |
| `GlmExecutor` | Z.AI GLM（含 `glmt` 预设） | Thinking Budget 感知、GLMT 预设常量 |
| `GrokWebExecutor` | xAI Grok web | Web 会话反向、模式选择（think/standard） |
| `KieExecutor` | KIE | 自定义 Token 签发 + 轮换会话锚点 |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream 二进制格式 → SSE 转换 |
| `MuseSparkWebExecutor` | Muse Spark (web) | Web 会话反向 + 图片消息桥接 |
| `NlpCloudExecutor` | NLP Cloud | 服务商专属请求体形状 |
| `OpenCodeExecutor` | OpenCode | AI SDK 兼容服务商初始化 |
| `PerplexityWebExecutor` | Perplexity web | Web 会话反向，用于聊延续 |
| `PetalsExecutor` | Petals distributed inference | 去中心化集群路由 |
| `PollinationsExecutor` | Pollinations AI | 无需 API Key、带速率限制的请求 |
| `QoderExecutor` | Qoder AI | PAT 和 OAuth 支持、多模型免费层 |
| `VertexExecutor` | Google Vertex AI | 服务帐户认证、基于区域的端点 |
| `DevinDesktopExecutor` | Devin Desktop | 导入的 API 密钥 + Connect-protobuf 聊天流 |
其余所有服务商（含自定义兼容节点）使用 `DefaultExecutor`。
## 服务商兼容性矩阵
> **注意：** 下表是 OmniRoute v3.8.0 中 237 个已注册服务商的代表性样本。
> **注意：** 下表是 OmniRoute v3.8.0 中 351 个已注册服务商的代表性样本。
> 完整且持续更新的列表请参阅
> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md)（自动生成）或数据源头
> `src/shared/constants/providers.ts`（加载时通过 Zod 校验）。
| 服务商 | 格式 | 认证 | 流式 | 非流式 | Token 刷新 | 用量 API |
| ----------------- | ---------------- | --------------------- | -------------- | ---------- | ----------- | ----------------- |
| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ 仅管理员 |
| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ 完整配额 API |
| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ 强制 | ❌ | ✅ | ✅ 速率限制 |
| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ 配额快照 |
| Cursor | cursor | 自定义校验和 | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream)| ❌ | ✅ | ✅ 用量限制 |
| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API Token + 帐户 ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | 无需密钥 | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API Key（可选） | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | 服务帐户 | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| Z.AI / GLM | openai | API Key / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | API Key | ✅ | ✅ | ❌ | ⚠️ 每请求 |
| Kimi Coding | openai | OAuth / API Key | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | 导入的 API 密钥 | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ 每请求 |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | 本地 CLI 登录 | ✅ | ✅ | ❌ | ✅ 任务 API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ 速率限制 |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ 任务 API |
| AgentRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| ChatGPT-Web | openai | 会话 Cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | 会话 Cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API Key | ✅ | ✅ | ❌ | ⚠️ 配额策略 |
| BazaarLink | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | 无需密钥 | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | 自定义 | ✅ | ✅ | ❌ | ❌ |
| 服务商 | 格式 | 认证 | 流式 | 非流式 | Token 刷新 | 用量 API |
| ------------------- | ---------------- | --------------------- | ---------------- | ------ | ---------- | ---------------- |
| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ 仅管理员 |
| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ 完整配额 API |
| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ 强制 | ❌ | ✅ | ✅ 速率限制 |
| ChatGPT Web (Codex) | openai-responses | 浏览器会话 | ✅ 强制 | ❌ | ❌ | ❌ |
| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ 配额快照 |
| Cursor | cursor | 自定义校验和 | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ 用量限制 |
| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API Token + 帐户 ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | 无需密钥 | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API Key（可选） | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | 服务帐户 | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| Z.AI / GLM | openai | API Key / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT (preset) | claude | API Key | ✅ | ✅ | ❌ | ⚠️ 每请求 |
| Kimi Coding | openai | OAuth / API Key | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | 导入的 API 密钥 | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ 每请求 |
| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | 本地 CLI 登录 | ✅ | ✅ | ❌ | ✅ 任务 API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ 速率限制 |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ 任务 API |
| AgentRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | 会话 Cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | 会话 Cookie | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API Key | ✅ | ✅ | ❌ | ⚠️ 配额策略 |
| BazaarLink | openai | API Key | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | 无需密钥 | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每请求 |
| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | 自定义 | ✅ | ✅ | ❌ | ❌ |
## 格式转换覆盖
@@ -1029,25 +1026,25 @@ flowchart LR
## 支持的 API 端点
| 端点 | 格式 | 处理器 |
| --------------------------------------------------- | ------------------ | ----------------------------------------------------------------- |
| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |
| `POST /v1/messages` | Claude Messages | 同一处理器（自动检测） |
| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` |
| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |
| `GET /v1/embeddings` | 模型列表 | API 路由 |
| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` |
| `GET /v1/images/generations` | 模型列表 | API 路由 |
| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | 带模型校验的专用每服务商路由 |
| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | 带模型校验的专用每服务商路由 |
| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | 带模型校验的专用每服务商路由 |
| `POST /v1/messages/count_tokens` | Claude Token Count | API 路由 |
| `GET /v1/models` | OpenAI Models 列表 | API 路由（聊 + 向量嵌入 + 图片 + 自定义模型） |
| `GET /api/models/catalog` | 目录 | 按服务商 + 类型分组的所有模型 |
| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API 路由 |
| `GET/PUT/DELETE /api/settings/proxy` | 代理配置 | 网络代理配置 |
| `POST /api/settings/proxy/test` | 代理连通性 | 代理健康/连通性测试端点 |
| `GET/POST/DELETE /api/provider-models` | 服务商模型 | 服务商模型元数据，支撑自定义和管理可用模型 |
| 端点 | 格式 | 处理器 |
| -------------------------------------------------- | ------------------ | --------------------------------------------- |
| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |
| `POST /v1/messages` | Claude Messages | 同一处理器（自动检测） |
| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` |
| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |
| `GET /v1/embeddings` | 模型列表 | API 路由 |
| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` |
| `GET /v1/images/generations` | 模型列表 | API 路由 |
| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | 带模型校验的专用每服务商路由 |
| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | 带模型校验的专用每服务商路由 |
| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | 带模型校验的专用每服务商路由 |
| `POST /v1/messages/count_tokens` | Claude Token Count | API 路由 |
| `GET /v1/models` | OpenAI Models 列表 | API 路由（聊 + 向量嵌入 + 图片 + 自定义模型） |
| `GET /api/models/catalog` | 目录 | 按服务商 + 类型分组的所有模型 |
| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API 路由 |
| `GET/PUT/DELETE /api/settings/proxy` | 代理配置 | 网络代理配置 |
| `POST /api/settings/proxy/test` | 代理连通性 | 代理健康/连通性测试端点 |
| `GET/POST/DELETE /api/provider-models` | 服务商模型 | 服务商模型元数据，支撑自定义和管理可用模型 |
## 旁路处理器

265
docs/i18n/zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md
View File

@@ -10,18 +10,18 @@
## 1. 技术栈
| 关注领域 | 技术选型 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| Web 框架 | **Next.js 16**（App Router，独立输出，无全局中间件） |
| 语言 | **TypeScript 6.0+** — 目标 `ES2022`，`module: esnext`，`moduleResolution: bundler`，`strict: false` |
| 运行时 | **Node.js** `>=22.22.2 <23` 或 `>=24.0.0 <27`（通过 `engines` + `SUPPORTED_NODE_RANGE` 强制） |
| 数据库 | **SQLite**，基于 `better-sqlite3`（单例，WAL 日志模式） |
| 桌面端 | **Electron 41** + `electron-builder` 26.10（独立工作空间 `electron/`） |
| 测试 | **Node 原生测试运行器**（单元/集成）、**Vitest**（MCP、autoCombo、缓存）、**Playwright**（端到端 + 协议端到端） |
| 构建 | Next.js 独立模式，通过 `scripts/build/build-next-isolated.mjs` |
| 代码检查 | ESLint flat 配置 + Prettier（Husky pre-commit 触发 `lint-staged`） |
| 模块系统 | 全局 ESM（`"type": "module"`） |
| 工作空间 | npm workspace — `open-sse` 是唯一的子工作空间 |
| 关注领域 | 技术选型 |
| -------- | --------------------------------------------------------------------------------------------------------------- |
| Web 框架 | **Next.js 16**（App Router，独立输出，无全局中间件） |
| 语言 | **TypeScript 6.0+** — 目标 `ES2022`，`module: esnext`，`moduleResolution: bundler`，`strict: false` |
| 运行时 | **Node.js** `>=22.22.2 <23` 或 `>=24.0.0 <27`（通过 `engines` + `SUPPORTED_NODE_RANGE` 强制） |
| 数据库 | **SQLite**，基于 `better-sqlite3`（单例，WAL 日志模式） |
| 桌面端 | **Electron 41** + `electron-builder` 26.10（独立工作空间 `electron/`） |
| 测试 | **Node 原生测试运行器**（单元/集成）、**Vitest**（MCP、autoCombo、缓存）、**Playwright**（端到端 + 协议端到端） |
| 构建 | Next.js 独立模式，通过 `scripts/build/build-next-isolated.mjs` |
| 代码检查 | ESLint flat 配置 + Prettier（Husky pre-commit 触发 `lint-staged`） |
| 模块系统 | 全局 ESM（`"type": "module"`） |
| 工作空间 | npm workspace — `open-sse` 是唯一的子工作空间 |
路径别名（`tsconfig.json`）：
@@ -85,20 +85,20 @@ App Router 同时暴露仪表盘 UI 和公开/管理 HTTP API。**不存在全
`src/app/` 下的顶层段：
| 路径 | 用途 |
| ------------------------------------------------------------------------------ | --------------------------------- |
| `api/` | 所有 HTTP API 路由（详见下文分解）|
| `a2a/` | A2A JSON-RPC 2.0 端点（`POST /a2a`）|
| `.well-known/agent.json/` | A2A Agent Card 发现文档 |
| `(dashboard)/` | 仪表盘 UI（路由组，无 URL 前缀） |
| `auth/`、`login/`、`forgot-password/`、`callback/` | 认证流程 |
| `landing/` | 市场/落地页 |
| `docs/` | 嵌入式 API 文档查看器 |
| `status/`、`maintenance/`、`offline/` | 运维页面 |
| `privacy/`、`terms/` | 法律页面 |
| `400/`、`401/`、`403/`、`408/`、`429/`、`500/`、`502/`、`503/` | 静态错误页面 |
| `error.tsx`、`global-error.tsx`、`not-found.tsx`、`forbidden/`、`loading.tsx` | 框架错误/加载边界 |
| `layout.tsx`、`page.tsx`、`globals.css`、`manifest.ts` | 根外壳 |
| 路径 | 用途 |
| ----------------------------------------------------------------------------- | ------------------------------------ |
| `api/` | 所有 HTTP API 路由（详见下文分解） |
| `a2a/` | A2A JSON-RPC 2.0 端点（`POST /a2a`） |
| `.well-known/agent.json/` | A2A Agent Card 发现文档 |
| `(dashboard)/` | 仪表盘 UI（路由组，无 URL 前缀） |
| `auth/`、`login/`、`forgot-password/`、`callback/` | 认证流程 |
| `landing/` | 市场/落地页 |
| `docs/` | 嵌入式 API 文档查看器 |
| `status/`、`maintenance/`、`offline/` | 运维页面 |
| `privacy/`、`terms/` | 法律页面 |
| `400/`、`401/`、`403/`、`408/`、`429/`、`500/`、`502/`、`503/` | 静态错误页面 |
| `error.tsx`、`global-error.tsx`、`not-found.tsx`、`forbidden/`、`loading.tsx` | 框架错误/加载边界 |
| `layout.tsx`、`page.tsx`、`globals.css`、`manifest.ts` | 根外壳 |
#### 3.1.1 `src/app/(dashboard)/dashboard/` — UI 页面
@@ -218,7 +218,6 @@ v1/
├── audio/{speech, transcriptions}/ TTS + STT
├── batches/[id]/{cancel}, batches/ OpenAI Batches API
├── chat/completions/ 对话补全（主要端点）
├── chatgpt-web/ ChatGPT-Web 兼容
├── completions/ 旧版文本补全
├── embeddings/ 嵌入
├── files/[id]/, files/ Files API
@@ -254,46 +253,46 @@ v1/
始终通过这些模块导入数据、同步、OAuth、技能、记忆等。下表按实际目录和重要顶层文件分组。
| 模块 | 用途 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/` | A2A 协议服务器：`taskManager.ts`、`streaming.ts`、`taskExecution.ts`、`routingLogger.ts`、`skills/`（6 个技能：成本分析、健康报告、服务商发现、配额管理、智能路由、列出能力） |
| `acp/` | Agent-Control-Protocol：`index.ts`、`manager.ts`、`registry.ts` |
| `api/` | 内部 API 辅助工具：`requireManagementAuth.ts`、`requireCliToolsAuth.ts`、`errorResponse.ts` |
| `auth/` | `managementPassword.ts`（密码重置/哈希） |
| `batches/` | OpenAI Batches API 服务（`service.ts`） |
| `catalog/` | OpenRouter 目录同步（`openrouterCatalog.ts`） |
| `cloudAgent/` | 云代理注册表：`api.ts`、`baseAgent.ts`、`db.ts`、`index.ts`、`registry.ts`、`types.ts`、`agents/{codex, devin, jules}.ts` |
| `combos/` | Combo 解析辅助工具 |
| `compliance/` | 审计 + 服务商审计：`index.ts`、`providerAudit.ts` |
| `config/` | 运行时配置粘合层 |
| `db/` | SQLite 领域模块（见 §3.2.1） |
| `display/` | API 响应使用的 UI/展示辅助工具 |
| `embeddings/` | 嵌入服务注册表 |
| `env/` | 环境变量加载 + 自检 |
| `evals/` | 评估框架运行时 |
| `guardrails/` | `piiMasker.ts`、`promptInjection.ts`、`visionBridge.ts`、`visionBridgeHelpers.ts`、`registry.ts`、`base.ts` |
| `jobs/` | 后台任务（`autoUpdate.ts` 等） |
| `memory/` | 持久化记忆：`store.ts`、`cache.ts`、`retrieval.ts`、`summarization.ts`、`extraction.ts`、`injection.ts`、`qdrant.ts`、`settings.ts`、`verify.ts`、`schemas.ts`、`types.ts` |
| `monitoring/` | `observability.ts` |
| `oauth/` | OAuth 服务商（14 个）：`antigravity`、`claude`、`cline`、`codex`、`cursor`、`gemini`、`github`、`gitlab-duo`、`kilocode`、`kimi-coding`、`kiro`、`qoder`、`qwen`、`windsurf`，以及 `services/`、`utils/{pkce, server, banner, codexAuthFile, ui}`、`constants/oauth.ts` |
| `plugins/` | 插件加载器（`index.ts`） |
| `promptCache/` | `prefixAnalyzer.ts`、`index.ts` |
| `providerModels/` | 托管模型生命周期：`modelDiscovery.ts`、`managedModelImport.ts`、`managedAvailableModels.ts`、`cursorAgent.ts` |
| `providers/` | 服务商辅助工具：`catalog.ts`、`validation.ts`、`imageValidation.ts`、`claudeExtraUsage.ts`、`codexConnectionDefaults.ts`、`codexFastTier.ts`、`webCookieAuth.ts`、`managedAvailableModels.ts`、`requestDefaults.ts` |
| `resilience/` | `settings.ts` — 熔断器、冷却、锁定的设置 |
| `runtime/` | 运行时特性检测 |
| `search/` | `executeWebSearch.ts` |
| `services/` | 嵌入式服务框架：`ServiceSupervisor.ts`（通用子进程管理器，带操作锁、环形缓冲区、健康检查器）、`bootstrap.ts`（进程级注册和自动启动）、`registry.ts`（工具 → 管理器映射）、`apiKey.ts`（AES-256-GCM Key 存储）、`modelSync.ts`（定期模型同步）、`ringBuffer.ts`（5 MB 环形日志缓冲）、`healthCheck.ts`（HTTP 健康探测）、`types.ts`、`embedWsProxy.ts`（WebSocket 代理）、`installers/{ninerouter,cliproxy}.ts`。详见 `docs/frameworks/EMBEDDED-SERVICES.md` |
| `agentSkills/` | Agent Skills 目录 + 生成器：`catalog.ts`（getCatalog/getSkillById/filterCatalog/computeCoverage）、`generator.ts`（generateAgentSkills → 写入 `skills/{id}/SKILL.md`）、`openapiParser.ts`（从 OpenAPI 规范提取 REST 端点）、`cliRegistryParser.ts`（从 bin/cli-registry 提取 CLI 子命令）、`schemas.ts`（Zod：AgentSkillSchema、SkillCoverageSchema、ListQuerySchema、GenerateBodySchema）、`types.ts`（AgentSkill、SkillCoverage、SkillMarkdown、GeneratorReport）。被 REST 路由（`/api/agent-skills/*`）、MCP 工具（`omniroute_agent_skills_*`）和 A2A 技能 `list-capabilities` 消费。参见 [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md)。 |
| `skills/` | 技能框架：`registry.ts`、`executor.ts`、`interception.ts`、`injection.ts`、`sandbox.ts`、`custom.ts`、`hybrid.ts`、`builtins.ts`、`a2a.ts`、`providerSettings.ts`、`schemas.ts`、`skillssh.ts`、`types.ts`，以及 `builtin/browser.ts` |
| `spend/` | `batchWriter.ts`（写后缓冲） |
| `sync/` | `bundle.ts`、`tokens.ts`（云同步） |
| `system/` | 系统级辅助工具 |
| `translator/` | 顶层翻译器粘合层（委托到 `open-sse/translator/`） |
| `usage/` | 用量核算：`costCalculator.ts`、`tokenAccounting.ts`、`usageHistory.ts`、`aggregateHistory.ts`、`usageStats.ts`、`callLogs.ts`、`callLogArtifacts.ts`、`fetcher.ts`、`providerLimits.ts`、`migrations.ts` |
| `versionManager/` | 自动更新 + 版本清单 |
| `ws/` | WebSocket 桥接 |
| `zed-oauth/` | Zed 编辑器 OAuth 流程 |
| 模块 | 用途 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `a2a/` | A2A 协议服务器：`taskManager.ts`、`streaming.ts`、`taskExecution.ts`、`routingLogger.ts`、`skills/`（6 个技能：成本分析、健康报告、服务商发现、配额管理、智能路由、列出能力） |
| `acp/` | Agent-Control-Protocol：`index.ts`、`manager.ts`、`registry.ts` |
| `api/` | 内部 API 辅助工具：`requireManagementAuth.ts`、`requireCliToolsAuth.ts`、`errorResponse.ts` |
| `auth/` | `managementPassword.ts`（密码重置/哈希） |
| `batches/` | OpenAI Batches API 服务（`service.ts`） |
| `catalog/` | OpenRouter 目录同步（`openrouterCatalog.ts`） |
| `cloudAgent/` | 云代理注册表：`api.ts`、`baseAgent.ts`、`db.ts`、`index.ts`、`registry.ts`、`types.ts`、`agents/{codex, devin, jules}.ts` |
| `combos/` | Combo 解析辅助工具 |
| `compliance/` | 审计 + 服务商审计：`index.ts`、`providerAudit.ts` |
| `config/` | 运行时配置粘合层 |
| `db/` | SQLite 领域模块（见 §3.2.1） |
| `display/` | API 响应使用的 UI/展示辅助工具 |
| `embeddings/` | 嵌入服务注册表 |
| `env/` | 环境变量加载 + 自检 |
| `evals/` | 评估框架运行时 |
| `guardrails/` | `piiMasker.ts`、`promptInjection.ts`、`visionBridge.ts`、`visionBridgeHelpers.ts`、`registry.ts`、`base.ts` |
| `jobs/` | 后台任务（`autoUpdate.ts` 等） |
| `memory/` | 持久化记忆：`store.ts`、`cache.ts`、`retrieval.ts`、`summarization.ts`、`extraction.ts`、`injection.ts`、`qdrant.ts`、`settings.ts`、`verify.ts`、`schemas.ts`、`types.ts` |
| `monitoring/` | `observability.ts` |
| `oauth/` | OAuth 服务商（14 个）：`antigravity`、`claude`、`cline`、`codex`、`cursor`、`gemini`、`github`、`gitlab-duo`、`kilocode`、`kimi-coding`、`kiro`、`qoder`、`qwen`、`windsurf`，以及 `services/`、`utils/{pkce, server, banner, codexAuthFile, ui}`、`constants/oauth.ts` |
| `plugins/` | 插件加载器（`index.ts`） |
| `promptCache/` | `prefixAnalyzer.ts`、`index.ts` |
| `providerModels/` | 托管模型生命周期：`modelDiscovery.ts`、`managedModelImport.ts`、`managedAvailableModels.ts`、`cursorAgent.ts` |
| `providers/` | 服务商辅助工具：`catalog.ts`、`validation.ts`、`imageValidation.ts`、`claudeExtraUsage.ts`、`codexConnectionDefaults.ts`、`codexFastTier.ts`、`webCookieAuth.ts`、`managedAvailableModels.ts`、`requestDefaults.ts` |
| `resilience/` | `settings.ts` — 熔断器、冷却、锁定的设置 |
| `runtime/` | 运行时特性检测 |
| `search/` | `executeWebSearch.ts` |
| `services/` | 嵌入式服务框架：`ServiceSupervisor.ts`（通用子进程管理器，带操作锁、环形缓冲区、健康检查器）、`bootstrap.ts`（进程级注册和自动启动）、`registry.ts`（工具 → 管理器映射）、`apiKey.ts`（AES-256-GCM Key 存储）、`modelSync.ts`（定期模型同步）、`ringBuffer.ts`（5 MB 环形日志缓冲）、`healthCheck.ts`（HTTP 健康探测）、`types.ts`、`embedWsProxy.ts`（WebSocket 代理）、`installers/{ninerouter,cliproxy}.ts`。详见 `docs/frameworks/EMBEDDED-SERVICES.md` |
| `agentSkills/` | Agent Skills 目录 + 生成器：`catalog.ts`（getCatalog/getSkillById/filterCatalog/computeCoverage）、`generator.ts`（generateAgentSkills → 写入 `skills/{id}/SKILL.md`）、`openapiParser.ts`（从 OpenAPI 规范提取 REST 端点）、`cliRegistryParser.ts`（从 bin/cli-registry 提取 CLI 子命令）、`schemas.ts`（Zod：AgentSkillSchema、SkillCoverageSchema、ListQuerySchema、GenerateBodySchema）、`types.ts`（AgentSkill、SkillCoverage、SkillMarkdown、GeneratorReport）。被 REST 路由（`/api/agent-skills/*`）、MCP 工具（`omniroute_agent_skills_*`）和 A2A 技能 `list-capabilities` 消费。参见 [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md)。 |
| `skills/` | 技能框架：`registry.ts`、`executor.ts`、`interception.ts`、`injection.ts`、`sandbox.ts`、`custom.ts`、`hybrid.ts`、`builtins.ts`、`a2a.ts`、`providerSettings.ts`、`schemas.ts`、`skillssh.ts`、`types.ts`，以及 `builtin/browser.ts` |
| `spend/` | `batchWriter.ts`（写后缓冲） |
| `sync/` | `bundle.ts`、`tokens.ts`（云同步） |
| `system/` | 系统级辅助工具 |
| `translator/` | 顶层翻译器粘合层（委托到 `open-sse/translator/`） |
| `usage/` | 用量核算：`costCalculator.ts`、`tokenAccounting.ts`、`usageHistory.ts`、`aggregateHistory.ts`、`usageStats.ts`、`callLogs.ts`、`callLogArtifacts.ts`、`fetcher.ts`、`providerLimits.ts`、`migrations.ts` |
| `versionManager/` | 自动更新 + 版本清单 |
| `ws/` | WebSocket 桥接 |
| `zed-oauth/` | Zed 编辑器 OAuth 流程 |
`src/lib/` 中的顶层文件：
@@ -357,23 +356,23 @@ v1/
纯业务逻辑，无 I/O。被路由和处理器导入。
| 文件 | 用途 |
| -------------------------------------------- | --------------------------------- |
| `policyEngine.ts` | 顶层策略解析器 |
| `fallbackPolicy.ts` | 容灾决策树 |
| `costRules.ts` | 成本计算规则 |
| `lockoutPolicy.ts` | 模型锁定决策 |
| `tagRouter.ts` | 基于标签的路由 |
| `comboResolver.ts` | Combo 解析（请求 → 目标列表） |
| `connectionModelRules.ts` | 按连接过滤模型 |
| `modelAvailability.ts` | 模型可用性检查 |
| `degradation.ts` | 降级模式切换 |
| `providerExpiration.ts` | 过期账户/Key 检测 |
| `quotaCache.ts` | 缓存配额决策 |
| `responses.ts`、`omnirouteResponseMeta.ts` | 响应格式辅助工具 |
| `configAudit.ts` | 配置变更审计 |
| `assessment/` | 模型评估（按 RFC，部分实现） |
| `types.ts` | 共享领域类型 |
| 文件 | 用途 |
| ------------------------------------------ | ----------------------------- |
| `policyEngine.ts` | 顶层策略解析器 |
| `fallbackPolicy.ts` | 容灾决策树 |
| `costRules.ts` | 成本计算规则 |
| `lockoutPolicy.ts` | 模型锁定决策 |
| `tagRouter.ts` | 基于标签的路由 |
| `comboResolver.ts` | Combo 解析（请求 → 目标列表） |
| `connectionModelRules.ts` | 按连接过滤模型 |
| `modelAvailability.ts` | 模型可用性检查 |
| `degradation.ts` | 降级模式切换 |
| `providerExpiration.ts` | 过期账户/Key 检测 |
| `quotaCache.ts` | 缓存配额决策 |
| `responses.ts`、`omnirouteResponseMeta.ts` | 响应格式辅助工具 |
| `configAudit.ts` | 配置变更审计 |
| `assessment/` | 模型评估（按 RFC，部分实现） |
| `types.ts` | 共享领域类型 |
### 3.4 `src/server/` — 服务端专用
@@ -442,35 +441,35 @@ open-sse/
### 4.1 `open-sse/handlers/`
| 处理器 | 用途 |
| ------------------------- | ------------------------------------------ |
| `chatCore.ts` | 主对话管道（缓存、速率限制、Combo 路由、执行器调度）|
| `responsesHandler.ts` | OpenAI Responses API 入口 |
| `embeddings.ts` | 嵌入 |
| `imageGeneration.ts` | 图像生成 |
| `audioSpeech.ts` | Text-to-speech |
| `audioTranscription.ts` | Speech-to-text |
| `videoGeneration.ts` | 视频生成 |
| `musicGeneration.ts` | 音乐生成 |
| `rerank.ts` | 重排序 |
| `moderations.ts` | 内容审核 |
| `search.ts` | 网页搜索 |
| `sseParser.ts` | SSE 事件解析器 |
| `usageExtractor.ts` | 从上游流中提取 Token 计数 |
| `responseSanitizer.ts` | 去除服务商专用噪音 |
| `responseTranslator.ts` | 服务商响应与翻译器层之间的粘合 |
| 处理器 | 用途 |
| ----------------------- | ---------------------------------------------------- |
| `chatCore.ts` | 主对话管道（缓存、速率限制、Combo 路由、执行器调度） |
| `responsesHandler.ts` | OpenAI Responses API 入口 |
| `embeddings.ts` | 嵌入 |
| `imageGeneration.ts` | 图像生成 |
| `audioSpeech.ts` | Text-to-speech |
| `audioTranscription.ts` | Speech-to-text |
| `videoGeneration.ts` | 视频生成 |
| `musicGeneration.ts` | 音乐生成 |
| `rerank.ts` | 重排序 |
| `moderations.ts` | 内容审核 |
| `search.ts` | 网页搜索 |
| `sseParser.ts` | SSE 事件解析器 |
| `usageExtractor.ts` | 从上游流中提取 Token 计数 |
| `responseSanitizer.ts` | 去除服务商专用噪音 |
| `responseTranslator.ts` | 服务商响应与翻译器层之间的粘合 |
### 4.2 `open-sse/executors/`
68 个服务商执行器，各自扩展 `BaseExecutor`（`base.ts`）：
107 个服务商执行器，各自扩展 `BaseExecutor`（`base.ts`）：
`antigravity`、`azure-openai`、`blackbox-web`、`chatgpt-web`、`cliproxyapi`、
`cloudflare-ai`、`codex`、`commandCode`、`cursor`、`default`、`devin-cli`、
`antigravity`、`azure-openai`、`blackbox-web`、`cliproxyapi`、
`chatgpt-web-codex`、`cloudflare-ai`、`codex`、`commandCode`、`cursor`、`default`、`devin-cli`、
`muse-spark-web`、`nlpcloud`、`opencode`、`perplexity-web`、`petals`、
`pollinations`、`qoder`、`vertex`、`windsurf`，以及 `claudeIdentity.ts`
（共享身份标识辅助）和 `index.ts`（注册表）。
> 注意：未在此列出的服务商由 `default.ts` 通过通用 OpenAI 兼容执行器提供服务。完整的服务商目录（237 条目）位于 `src/shared/constants/providers.ts`。
> 注意：未在此列出的服务商由 `default.ts` 通过通用 OpenAI 兼容执行器提供服务。完整的服务商目录（351 条目）位于 `src/shared/constants/providers.ts`。
### 4.3 `open-sse/translator/`
@@ -500,21 +499,21 @@ open-sse/
重点关注（完整列表见 `open-sse/services/`）：
| 关注领域 | 文件 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Combo 路由 | `combo.ts`（17 种策略）、`comboConfig.ts`、`comboMetrics.ts`、`comboManifestMetrics.ts`、`comboAgentMiddleware.ts` |
| Auto Combo 引擎 | `autoCombo/` — `engine.ts`、`scoring.ts`、`taskFitness.ts`、`virtualFactory.ts`、`modePacks.ts`、`autoPrefix.ts`、`persistence.ts`、`providerDiversity.ts`、`providerRegistryAccessor.ts`、`routerStrategy.ts`、`selfHealing.ts`、`index.ts` |
| 容灾 | `accountFallback.ts`（冷却 + 锁定）、`errorClassifier.ts`、`emergencyFallback.ts`、`rateLimitManager.ts`、`rateLimitSemaphore.ts`、`accountSemaphore.ts`、`accountSelector.ts` |
| 配额 | `quotaMonitor.ts`、`quotaPreflight.ts`、`bailianQuotaFetcher.ts`、`codexQuotaFetcher.ts`、`deepseekQuotaFetcher.ts`、`crofUsageFetcher.ts`、`antigravityCredits.ts` |
| 缓存 | `reasoningCache.ts`、`searchCache.ts`、`signatureCache.ts`、`requestDedup.ts` |
| 路由智能 | `intentClassifier.ts`、`taskAwareRouter.ts`、`backgroundTaskDetector.ts`、`volumeDetector.ts`、`wildcardRouter.ts`、`workflowFSM.ts`、`specificityDetector.ts`、`specificityRules.ts`、`specificityTypes.ts` |
| 模型处理 | `modelCapabilities.ts`、`modelDeprecation.ts`、`modelFamilyFallback.ts`、`modelStrip.ts`、`model.ts`、`provider.ts`、`providerRequestDefaults.ts`、`providerCostData.ts`、`payloadRules.ts` |
| 压缩 | `compression/` — 完整的压缩引擎接线 |
| Token + 会话 | `tokenRefresh.ts`、`sessionManager.ts`、`apiKeyRotator.ts`、`contextManager.ts`、`contextHandoff.ts`、`systemPrompt.ts`、`roleNormalizer.ts`、`responsesInputSanitizer.ts`、`toolSchemaSanitizer.ts`、`toolLimitDetector.ts`、`thinkingBudget.ts` |
| 层级 / 清单 | `tierResolver.ts`、`tierConfig.ts`、`tierDefaults.json`、`tierTypes.ts`、`manifestAdapter.ts` |
| IP / 网络 | `ipFilter.ts`、`webSearchFallback.ts` |
| 批次 | `batchProcessor.ts` |
| 用量 | `usage.ts` |
| 关注领域 | 文件 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Combo 路由 | `combo.ts`（17 种策略）、`comboConfig.ts`、`comboMetrics.ts`、`comboManifestMetrics.ts`、`comboAgentMiddleware.ts` |
| Auto Combo 引擎 | `autoCombo/` — `engine.ts`、`scoring.ts`、`taskFitness.ts`、`virtualFactory.ts`、`modePacks.ts`、`autoPrefix.ts`、`persistence.ts`、`providerDiversity.ts`、`providerRegistryAccessor.ts`、`routerStrategy.ts`、`selfHealing.ts`、`index.ts` |
| 容灾 | `accountFallback.ts`（冷却 + 锁定）、`errorClassifier.ts`、`emergencyFallback.ts`、`rateLimitManager.ts`、`rateLimitSemaphore.ts`、`accountSemaphore.ts`、`accountSelector.ts` |
| 配额 | `quotaMonitor.ts`、`quotaPreflight.ts`、`bailianQuotaFetcher.ts`、`codexQuotaFetcher.ts`、`deepseekQuotaFetcher.ts`、`crofUsageFetcher.ts`、`antigravityCredits.ts` |
| 缓存 | `reasoningCache.ts`、`searchCache.ts`、`signatureCache.ts`、`requestDedup.ts` |
| 路由智能 | `intentClassifier.ts`、`taskAwareRouter.ts`、`backgroundTaskDetector.ts`、`volumeDetector.ts`、`wildcardRouter.ts`、`workflowFSM.ts`、`specificityDetector.ts`、`specificityRules.ts`、`specificityTypes.ts` |
| 模型处理 | `modelCapabilities.ts`、`modelDeprecation.ts`、`modelFamilyFallback.ts`、`modelStrip.ts`、`model.ts`、`provider.ts`、`providerRequestDefaults.ts`、`providerCostData.ts`、`payloadRules.ts` |
| 压缩 | `compression/` — 完整的压缩引擎接线 |
| Token + 会话 | `tokenRefresh.ts`、`sessionManager.ts`、`apiKeyRotator.ts`、`contextManager.ts`、`contextHandoff.ts`、`systemPrompt.ts`、`roleNormalizer.ts`、`responsesInputSanitizer.ts`、`toolSchemaSanitizer.ts`、`toolLimitDetector.ts`、`thinkingBudget.ts` |
| 层级 / 清单 | `tierResolver.ts`、`tierConfig.ts`、`tierDefaults.json`、`tierTypes.ts`、`manifestAdapter.ts` |
| IP / 网络 | `ipFilter.ts`、`webSearchFallback.ts` |
| 批次 | `batchProcessor.ts` |
| 用量 | `usage.ts` |
### 4.6 `open-sse/mcp-server/`
@@ -624,14 +623,14 @@ bin/
常用命令：
| 命令 | 运行内容 |
| --------------------------------------------------------- | -------------------------------------------------------------- |
| `npm run test:unit` | `tests/unit/*.test.ts` 全部（Node 测试运行器，并发 10） |
| `npm run test:vitest` | Vitest 套件（MCP、autoCombo、缓存） |
| `npm run test:e2e` | Playwright UI 套件 |
| `npm run test:protocols:e2e` | MCP + A2A 协议端到端 |
| `npm run test:coverage` | 覆盖率门槛（行/语句/函数/分支 ≥ 60%） |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | 单文件运行 |
| 命令 | 运行内容 |
| -------------------------------------------------------- | ------------------------------------------------------- |
| `npm run test:unit` | `tests/unit/*.test.ts` 全部（Node 测试运行器，并发 10） |
| `npm run test:vitest` | Vitest 套件（MCP、autoCombo、缓存） |
| `npm run test:e2e` | Playwright UI 套件 |
| `npm run test:protocols:e2e` | MCP + A2A 协议端到端 |
| `npm run test:coverage` | 覆盖率门槛（行/语句/函数/分支 ≥ 60%） |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | 单文件运行 |
---
@@ -696,11 +695,11 @@ bin/
### 容灾运行时状态（三种机制）
| 机制 | 范围 | 位置 |
| -------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| 服务商熔断器 | 整个服务商 | `src/shared/utils/circuitBreaker.ts`，持久化于 `domain_circuit_breakers` |
| 连接冷却 | 单个账户/Key | `src/sse/services/auth.ts` 中的 `markAccountUnavailable()`；由 `accountFallback.checkFallbackError()` 消费 |
| 模型锁定 | 服务商 + 连接 + 模型| `open-sse/services/accountFallback.ts`，持久化于 `domain_lockout_state` |
| 机制 | 范围 | 位置 |
| ------------ | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| 服务商熔断器 | 整个服务商 | `src/shared/utils/circuitBreaker.ts`，持久化于 `domain_circuit_breakers` |
| 连接冷却 | 单个账户/Key | `src/sse/services/auth.ts` 中的 `markAccountUnavailable()`；由 `accountFallback.checkFallbackError()` 消费 |
| 模型锁定 | 服务商 + 连接 + 模型 | `open-sse/services/accountFallback.ts`，持久化于 `domain_lockout_state` |
参见 [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) 和 [CLAUDE.md](../../CLAUDE.md) 中的专门章节。

168
docs/i18n/zh-CN/docs/reference/ENVIRONMENT.md
View File

@@ -83,28 +83,28 @@ echo "OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -base64 32)"
OmniRoute 使用 **SQLite**（通过 `better-sqlite3`）进行所有持久化存储。以下变量控制数据位置、加密和生命周期。
| 变量 | 默认值 | 源文件 | 说明 |
| -------------------------------------- | -------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATA_DIR` | `~/.omniroute/` | `src/lib/db/core.ts` | SQLite 数据库、备份和数据文件的根目录。在 Docker 卷或自定义路径中可覆盖。 |
| `STORAGE_ENCRYPTION_KEY` | _(空 = 禁用)_ | `src/lib/db/encryption.ts` | 用于 SQLite 数据库静态全量加密的 AES 密钥。使用 `openssl rand -hex 32` 生成。 |
| `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/build/bootstrap-env.mjs`, `electron/main.js` | 加密密钥的版本标签。进行密钥轮换时递增，以支持解密旧备份。 |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | `src/lib/db/backup.ts` | 设为 `true` 时，跳过每次启动前迁移时运行的自动数据库备份。 |
| `OMNIROUTE_CRYPT_KEY` | _(未设置)_ | `src/lib/db/encryption.ts` | `STORAGE_ENCRYPTION_KEY` 的**旧版别名**。主变量缺失时作为回退被接受。 |
| `OMNIROUTE_API_KEY_BASE64` | _(未设置)_ | `src/lib/db/encryption.ts` | **旧版别名**（Base64 编码形式），作为回退被接受。使用前自动解码。 |
| `OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS` | _(未设置)_ | `src/lib/db/core.ts` | 覆盖定期 SQLite 健康检查的间隔（毫秒）。未设置时根据 `NODE_ENV` 推导默认值。 |
| `OMNIROUTE_SKIP_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts`, `src/lib/db/healthCheck.ts` | 设为 `1` 可在启动时完全跳过数据库健康检查。适用于短生命周期任务和集成测试。 |
| `OMNIROUTE_FORCE_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts` | 设为 `1` 可强制开启数据库健康检查循环，即使正常会被跳过（如短生命周期任务）。 |
| `OMNIROUTE_SKIP_POSTINSTALL` | `0` | `scripts/postinstall.mjs` | 设为 `1` 可在 `npm install` 期间跳过原生运行时预热。适用于 CI/无头安装，此时 sqlite 已构建好。 |
| `OMNIROUTE_MIGRATIONS_DIR` | _(自动检测)_ | `src/lib/db/migrationRunner.ts` | 覆盖迁移运行器扫描的目录。在自定义构建中打包迁移文件时很有用。 |
| 变量 | 默认值 | 源文件 | 说明 |
| -------------------------------------- | -------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATA_DIR` | `~/.omniroute/` | `src/lib/db/core.ts` | SQLite 数据库、备份和数据文件的根目录。在 Docker 卷或自定义路径中可覆盖。 |
| `STORAGE_ENCRYPTION_KEY` | _(空 = 禁用)_ | `src/lib/db/encryption.ts` | 用于 SQLite 数据库静态全量加密的 AES 密钥。使用 `openssl rand -hex 32` 生成。 |
| `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/build/bootstrap-env.mjs`, `electron/main.js` | 加密密钥的版本标签。进行密钥轮换时递增，以支持解密旧备份。 |
| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | `src/lib/db/backup.ts` | 设为 `true` 时，跳过每次启动前迁移时运行的自动数据库备份。 |
| `OMNIROUTE_CRYPT_KEY` | _(未设置)_ | `src/lib/db/encryption.ts` | `STORAGE_ENCRYPTION_KEY` 的**旧版别名**。主变量缺失时作为回退被接受。 |
| `OMNIROUTE_API_KEY_BASE64` | _(未设置)_ | `src/lib/db/encryption.ts` | **旧版别名**（Base64 编码形式），作为回退被接受。使用前自动解码。 |
| `OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS` | _(未设置)_ | `src/lib/db/core.ts` | 覆盖定期 SQLite 健康检查的间隔（毫秒）。未设置时根据 `NODE_ENV` 推导默认值。 |
| `OMNIROUTE_SKIP_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts`, `src/lib/db/healthCheck.ts` | 设为 `1` 可在启动时完全跳过数据库健康检查。适用于短生命周期任务和集成测试。 |
| `OMNIROUTE_FORCE_DB_HEALTHCHECK` | `0` | `src/lib/db/core.ts` | 设为 `1` 可强制开启数据库健康检查循环，即使正常会被跳过（如短生命周期任务）。 |
| `OMNIROUTE_SKIP_POSTINSTALL` | `0` | `scripts/postinstall.mjs` | 设为 `1` 可在 `npm install` 期间跳过原生运行时预热。适用于 CI/无头安装，此时 sqlite 已构建好。 |
| `OMNIROUTE_MIGRATIONS_DIR` | _(自动检测)_ | `src/lib/db/migrationRunner.ts` | 覆盖迁移运行器扫描的目录。在自定义构建中打包迁移文件时很有用。 |
| `OMNIROUTE_EXTRA_MIGRATIONS_DIRS` | _(未设置)_ | `src/lib/db/migrationRunner/extraDirs.ts` | 以 `namespace=dir` 形式追加的迁移目录，条目之间用平台路径分隔符分隔（例如 `ee=/opt/app/enterprise/db/migrations`）。其中的文件会以 `<namespace>-<number>` 记录版本，因此自带迁移的发行版永远不会与上游的数字槽位冲突。条目格式错误、命名空间非法或目录缺失会在启动时抛错，而不是静默跳过该 schema。 |
| `OMNIROUTE_MAX_PENDING_MIGRATIONS` | `50` | `src/lib/db/migrationRunner.ts` | 大量待处理迁移的安全阈值（#3416）。如果现有数据库上有超过此数量的待处理迁移，启动将中止（防止跟踪表被清空）。恢复旧备份时提高此值；设为 `0` 可禁用检查。 |
| `OMNIROUTE_SPEND_FLUSH_INTERVAL_MS` | _(代码内默认值)_ | `src/lib/spend/batchWriter.ts` | 批量消费/成本写入器的刷新间隔（毫秒）。值越小写合并越少；值越大数据库争用越少。 |
| `OMNIROUTE_SPEND_MAX_BUFFER_SIZE` | _(代码内默认值)_ | `src/lib/spend/batchWriter.ts` | 强制刷新前的最大缓存消费条目数。在高 QPS 部署中提高；在内存受限场景下降低。 |
| `OMNIROUTE_PROXY_FETCH_DEBUG` | _(未设置)_ | `open-sse/utils/proxyFetch.ts` | 设为 `"true"` 可在 Vercel 中继路径上发出 `[ProxyFetch]` 调试日志。默认关闭以避免泄露路由提示。 |
| `BATCH_RETRY_DURATION_MS` | `86400000`（24小时） | `open-sse/services/batchProcessor.ts` | 单个批次项的最大重试窗口（毫秒）。超过此时间的项被标记为失败。 |
| `BATCH_BACKOFF_BASE_MS` | `5000` | `open-sse/services/batchProcessor.ts` | 批次项重试时指数退避的基础延迟（毫秒）。 |
| `BATCH_BACKOFF_MAX_MS` | `3600000`（1小时） | `open-sse/services/batchProcessor.ts` | 批次项重试时指数退避的上限（毫秒）。 |
| `BATCH_MAX_CONCURRENT` | `1` | `open-sse/services/batchProcessor.ts` | 并发处理的批次最大数量。提高以增加吞吐量；保持低值以避免速率限制风暴。 |
| `OMNIROUTE_MAX_PENDING_MIGRATIONS` | `50` | `src/lib/db/migrationRunner.ts` | 大量待处理迁移的安全阈值（#3416）。如果现有数据库上有超过此数量的待处理迁移，启动将中止（防止跟踪表被清空）。恢复旧备份时提高此值；设为 `0` 可禁用检查。 |
| `OMNIROUTE_SPEND_FLUSH_INTERVAL_MS` | _(代码内默认值)_ | `src/lib/spend/batchWriter.ts` | 批量消费/成本写入器的刷新间隔（毫秒）。值越小写合并越少；值越大数据库争用越少。 |
| `OMNIROUTE_SPEND_MAX_BUFFER_SIZE` | _(代码内默认值)_ | `src/lib/spend/batchWriter.ts` | 强制刷新前的最大缓存消费条目数。在高 QPS 部署中提高；在内存受限场景下降低。 |
| `OMNIROUTE_PROXY_FETCH_DEBUG` | _(未设置)_ | `open-sse/utils/proxyFetch.ts` | 设为 `"true"` 可在 Vercel 中继路径上发出 `[ProxyFetch]` 调试日志。默认关闭以避免泄露路由提示。 |
| `BATCH_RETRY_DURATION_MS` | `86400000`（24小时） | `open-sse/services/batchProcessor.ts` | 单个批次项的最大重试窗口（毫秒）。超过此时间的项被标记为失败。 |
| `BATCH_BACKOFF_BASE_MS` | `5000` | `open-sse/services/batchProcessor.ts` | 批次项重试时指数退避的基础延迟（毫秒）。 |
| `BATCH_BACKOFF_MAX_MS` | `3600000`（1小时） | `open-sse/services/batchProcessor.ts` | 批次项重试时指数退避的上限（毫秒）。 |
| `BATCH_MAX_CONCURRENT` | `1` | `open-sse/services/batchProcessor.ts` | 并发处理的批次最大数量。提高以增加吞吐量；保持低值以避免速率限制风暴。 |
### 场景
@@ -250,41 +250,37 @@ OmniRoute 提供两层防护：请求侧的注入扫描和响应侧的 PII 脱
## 7. URL 与云同步
| 变量 | 默认值 | 源文件 | 说明 |
| ----------------------------------------- | ----------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BASE_URL` | `http://localhost:20128` | `src/lib/cloudSync.ts` | 内部同步任务调用 `/api/sync/cloud` 的服务器端 URL。即使应用被公共代理，也保持为 loopback/容器 URL。 |
| `CLOUD_URL` | _(空)_ | `src/lib/cloudSync.ts` | 云中继端点 URL（高级功能）。 |
| `CLOUD_SYNC_TIMEOUT_MS` | `12000` | `src/lib/cloudSync.ts` | 云同步请求的 HTTP 超时。 |
| `OMNIROUTE_BUILD_PROFILE` | `full` | Webpack 构建配置 | 构建时配置文件（设为 `minimal` 可物理排除特权模块不打包）。 |
| `OMNIROUTE_CLOUD_SYNC_SECRET` | _(空)_ | `src/lib/cloudSync.ts` | 用于校验云同步响应 HMAC-SHA256 签名的共享密钥。 |
| `OMNIROUTE_CLOUD_SYNC_SECRETS` | `false` | `src/lib/cloudSync.ts` | 设为 `true` 允许云同步端点覆盖本地凭证。默认 `false`。 |
| `OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP` | `false` | `src/app/api/providers/zed/import/route.ts` | 设为 `true` 可回退到 v3.8.5 的一步式"导入全部"行为，无需用户确认。 |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | OAuth、Dashboard、同步 | 面向公共的 URL，用于 OAuth redirect_uri、Dashboard 链接、生成的公共 URL 以及同源浏览器变更检查。**在反向代理背后时，必须匹配你的公共 URL。** |
| `NEXT_PUBLIC_CLOUD_URL` | _(空)_ | 客户端侧 | `CLOUD_URL` 的客户端镜像。 |
| `NEXT_PUBLIC_APP_URL` | _(未设置)_ | `src/shared/services/cloudSyncScheduler.ts` | `NEXT_PUBLIC_BASE_URL` 的旧版回退。 |
| `OMNIROUTE_PUBLIC_BASE_URL` | _(未设置)_ | 公共源解析器、图片 URL | 最高优先级的浏览器侧 OmniRoute 源，用于公共 URL 生成和源校验（例如 `/v1/chatgpt-web/image/<id>`）。当 OpenWebUI 或其他中继通过内部 URL 访问 OmniRoute，但用户浏览器必须从 LAN、隧道或公共源获取图片时设置。**不要**包含 `/v1`。 |
| `OMNIROUTE_TRUST_PROXY` | _(未设置)_ | `src/server/origin/publicOrigin.ts` | 可选的转发公共源头信任模式。未设置 = 出于安全考虑不信任 `Forwarded` / `X-Forwarded-*`。`true` / `loopback` 仅信任来自经过 Token 戳记的 loopback 代理的转发 host/proto。`private` / `lan` 还信任私有 LAN 代理对端。生产环境中推荐显式设置 `NEXT_PUBLIC_BASE_URL`。 |
| `OMNIROUTE_CGPT_WEB_IMAGE_TIMEOUT_MS` | `180000`（3 分钟） | `open-sse/executors/chatgpt-web.ts` | 等待异步 chatgpt-web 图片通过 Celsius WebSocket 到达的最大时间。在上游排队窗口较长时提高此值。 |
| `OMNIROUTE_CGPT_WEB_IMAGE_CACHE_MAX_MB` | `256` | `open-sse/services/chatgptImageCache.ts` | 为 `/v1/chatgpt-web/image/<id>` 提供服务的 chatgpt-web 图片缓存的内存预算总额（MB）。在内存受限的主机上降低；图片生成量大且客户端争抢 30 分钟 TTL 时提高。 |
| `OMNIROUTE_CGPT_WEB_PRO_TIMEOUT_MS` | `1200000`（20 分钟） | `open-sse/executors/chatgpt-web.ts` | chatgpt-web GPT-5.5 Pro 后台轮询交接的总体等待预算。Pro 推理在带外完成，OmniRoute 轮询直到结果到达或预算耗尽。如果 Pro 请求完成前超时，请提高此值。 |
| `OMNIROUTE_CGPT_WEB_PRO_POLL_INTERVAL_MS` | `4000`（4 秒） | `open-sse/executors/chatgpt-web.ts` | chatgpt-web GPT-5.5 Pro 后台轮询尝试的间隔。降低可更快完成但增加上游轮询；提高可减少请求量。 |
| `THEOLDLLM_NAV_TIMEOUT_MS` | `30000`（30 秒） | `open-sse/executors/theoldllm.ts` | 浏览器端 Token 捕获（The Old LLM (theoldllm) 免费服务商使用）的 Playwright 导航超时（毫秒）。如果中继页面加载慢，可在慢速网络上提高。 |
| `KIE_CALLBACK_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | 异步 kie.ai 任务的公共回调 URL。优先级高于 `OMNIROUTE_KIE_CALLBACK_URL` 和 `OMNIROUTE_PUBLIC_URL`。 |
| `OMNIROUTE_KIE_CALLBACK_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | `KIE_CALLBACK_URL` 的替代写法。主变量未设置时的回退。 |
| `OMNIROUTE_PUBLIC_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | 用于组合异步回调 URL 的公共源。kie.ai 回调的最低优先级回退；也用作其他中继的通用公共 URL。 |
| `OMNIROUTE_CROF_USAGE_URL` | `https://crof.ai/usage_api/` | `open-sse/services/usage.ts` | Usage 页面使用的 CrofAI 配额查询端点。可覆盖为中继/测试固定件。 |
| `OMNIROUTE_OPENCODE_QUOTA_URL` | `https://opencode.ai/zen/go/v1/quota` | `open-sse/services/opencodeQuotaFetcher.ts` | Usage 页面使用的 OpenCode (zen/go) 配额查询端点。可覆盖为中继/测试固定件。 |
| `OMNIROUTE_OPENCODE_GO_QUOTA_URL` | _(未设置)_ | `open-sse/services/opencodeOllamaUsage.ts` | Usage 页面使用的 OpenCode Go 配额查询端点。OpenCode Go 没有公开的配额 API，因此没有默认值；除非运维人员显式设置该变量选择接入自建/镜像端点，否则不会发起网络请求。 |
| `OMNIROUTE_OPENCODE_GO_DASHBOARD_URL` | `https://opencode.ai/workspace` | `open-sse/services/usage.ts` | 配置了 workspace ID 和 auth Cookie 时用于配额抓取的 OpenCode Go Dashboard 基础 URL。可覆盖为中继/测试固定件。 |
| `OPENCODE_GO_WORKSPACE_ID` | _(未设置)_ | `open-sse/services/usage.ts` | 用于 Dashboard 配额抓取的 OpenCode Go workspace ID。配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OPENCODE_GO_WORKSPACE_ID` | _(未设置)_ | `open-sse/services/usage.ts` | OpenCode Go workspace ID 环境变量的备选名，在较短的别名之前使用。配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OPENCODE_GO_AUTH_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | 用于 Dashboard 配额抓取的 OpenCode Go `auth` Cookie。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OPENCODE_GO_AUTH_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | OpenCode Go `auth` Cookie 环境变量的备选名，在较短的别名之前使用。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OLLAMA_CLOUD_USAGE_URL` | `https://ollama.com/settings` | `open-sse/services/usage.ts` | 用于配额抓取的 Ollama Cloud settings URL。可覆盖为中继/测试固定件。 |
| `OLLAMA_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | 用于设置页面配额抓取的 Ollama Cloud `__Secure-session` Cookie。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OLLAMA_CLOUD_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | Ollama Cloud `__Secure-session` Cookie 环境变量的备选名。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OLLAMA_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | Ollama Cloud `__Secure-session` Cookie 环境变量的备选名，在较短的别名之前使用。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_CODEWHISPERER_BASE_URL` | `https://codewhisperer.us-east-1.amazonaws.com` | `open-sse/services/usage.ts` | CodeWhisperer (AWS Kiro) 用量限制端点。可覆盖为中继/测试固定件。 |
| 变量 | 默认值 | 源文件 | 说明 |
| -------------------------------------- | ----------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BASE_URL` | `http://localhost:20128` | `src/lib/cloudSync.ts` | 内部同步任务调用 `/api/sync/cloud` 的服务器端 URL。即使应用被公共代理，也保持为 loopback/容器 URL。 |
| `CLOUD_URL` | _(空)_ | `src/lib/cloudSync.ts` | 云中继端点 URL（高级功能）。 |
| `CLOUD_SYNC_TIMEOUT_MS` | `12000` | `src/lib/cloudSync.ts` | 云同步请求的 HTTP 超时。 |
| `OMNIROUTE_BUILD_PROFILE` | `full` | Webpack 构建配置 | 构建时配置文件（设为 `minimal` 可物理排除特权模块不打包）。 |
| `OMNIROUTE_CLOUD_SYNC_SECRET` | _(空)_ | `src/lib/cloudSync.ts` | 用于校验云同步响应 HMAC-SHA256 签名的共享密钥。 |
| `OMNIROUTE_CLOUD_SYNC_SECRETS` | `false` | `src/lib/cloudSync.ts` | 设为 `true` 允许云同步端点覆盖本地凭证。默认 `false`。 |
| `OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP` | `false` | `src/app/api/providers/zed/import/route.ts` | 设为 `true` 可回退到 v3.8.5 的一步式"导入全部"行为，无需用户确认。 |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | OAuth、Dashboard、同步 | 面向公共的 URL，用于 OAuth redirect_uri、Dashboard 链接、生成的公共 URL 以及同源浏览器变更检查。**在反向代理背后时，必须匹配你的公共 URL。** |
| `NEXT_PUBLIC_CLOUD_URL` | _(空)_ | 客户端侧 | `CLOUD_URL` 的客户端镜像。 |
| `NEXT_PUBLIC_APP_URL` | _(未设置)_ | `src/shared/services/cloudSyncScheduler.ts` | `NEXT_PUBLIC_BASE_URL` 的旧版回退。 |
| `OMNIROUTE_PUBLIC_BASE_URL` | _(未设置)_ | 公共源解析器、图片 URL | 最高优先级的浏览器侧 OmniRoute 源，用于公共 URL 生成和非 Dashboard 浏览器源校验。当 OpenWebUI 或其他中继通过内部 URL 访问 OmniRoute，但用户浏览器必须从 LAN、隧道或公共源获取生成媒体时设置。**不要**包含 `/v1`。 |
| `OMNIROUTE_TRUST_PROXY` | _(未设置)_ | `src/server/origin/publicOrigin.ts` | 可选的转发公共源头信任模式。未设置 = 出于安全考虑不信任 `Forwarded` / `X-Forwarded-*`。`true` / `loopback` 仅信任来自经过 Token 戳记的 loopback 代理的转发 host/proto。`private` / `lan` 还信任私有 LAN 代理对端。生产环境中推荐显式设置 `NEXT_PUBLIC_BASE_URL`。 |
| `THEOLDLLM_NAV_TIMEOUT_MS` | `30000`（30 秒） | `open-sse/executors/theoldllm.ts` | 浏览器端 Token 捕获（The Old LLM (theoldllm) 免费服务商使用）的 Playwright 导航超时（毫秒）。如果中继页面加载慢，可在慢速网络上提高。 |
| `KIE_CALLBACK_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | 异步 kie.ai 任务的公共回调 URL。优先级高于 `OMNIROUTE_KIE_CALLBACK_URL` 和 `OMNIROUTE_PUBLIC_URL`。 |
| `OMNIROUTE_KIE_CALLBACK_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | `KIE_CALLBACK_URL` 的替代写法。主变量未设置时的回退。 |
| `OMNIROUTE_PUBLIC_URL` | _(未设置)_ | `open-sse/utils/kieTask.ts` | 用于组合异步回调 URL 的公共源。kie.ai 回调的最低优先级回退；也用作其他中继的通用公共 URL。 |
| `OMNIROUTE_CROF_USAGE_URL` | `https://crof.ai/usage_api/` | `open-sse/services/usage.ts` | Usage 页面使用的 CrofAI 配额查询端点。可覆盖为中继/测试固定件。 |
| `OMNIROUTE_OPENCODE_QUOTA_URL` | `https://opencode.ai/zen/go/v1/quota` | `open-sse/services/opencodeQuotaFetcher.ts` | Usage 页面使用的 OpenCode (zen/go) 配额查询端点。可覆盖为中继/测试固定件。 |
| `OMNIROUTE_OPENCODE_GO_QUOTA_URL` | _(未设置)_ | `open-sse/services/opencodeOllamaUsage.ts` | Usage 页面使用的 OpenCode Go 配额查询端点。OpenCode Go 没有公开的配额 API，因此没有默认值；除非运维人员显式设置该变量选择接入自建/镜像端点，否则不会发起网络请求。 |
| `OMNIROUTE_OPENCODE_GO_DASHBOARD_URL` | `https://opencode.ai/workspace` | `open-sse/services/usage.ts` | 配置了 workspace ID 和 auth Cookie 时用于配额抓取的 OpenCode Go Dashboard 基础 URL。可覆盖为中继/测试固定件。 |
| `OPENCODE_GO_WORKSPACE_ID` | _(未设置)_ | `open-sse/services/usage.ts` | 用于 Dashboard 配额抓取的 OpenCode Go workspace ID。配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OPENCODE_GO_WORKSPACE_ID` | _(未设置)_ | `open-sse/services/usage.ts` | OpenCode Go workspace ID 环境变量的备选名，在较短的别名之前使用。配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OPENCODE_GO_AUTH_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | 用于 Dashboard 配额抓取的 OpenCode Go `auth` Cookie。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OPENCODE_GO_AUTH_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | OpenCode Go `auth` Cookie 环境变量的备选名，在较短的别名之前使用。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OLLAMA_CLOUD_USAGE_URL` | `https://ollama.com/settings` | `open-sse/services/usage.ts` | 用于配额抓取的 Ollama Cloud settings URL。可覆盖为中继/测试固定件。 |
| `OLLAMA_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | 用于设置页面配额抓取的 Ollama Cloud `__Secure-session` Cookie。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OLLAMA_CLOUD_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | Ollama Cloud `__Secure-session` Cookie 环境变量的备选名。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_OLLAMA_USAGE_COOKIE` | _(未设置)_ | `open-sse/services/usage.ts` | Ollama Cloud `__Secure-session` Cookie 环境变量的备选名，在较短的别名之前使用。敏感信息；配置多个账户时，推荐使用每个连接的 Dashboard 字段。 |
| `OMNIROUTE_CODEWHISPERER_BASE_URL` | `https://codewhisperer.us-east-1.amazonaws.com` | `open-sse/services/usage.ts` | CodeWhisperer (AWS Kiro) 用量限制端点。可覆盖为中继/测试固定件。 |
> [!IMPORTANT]
> 当部署在反向代理（nginx、Caddy）之后时，**必须**将 `NEXT_PUBLIC_BASE_URL` 设置为你的公共 URL（例如 `https://omniroute.example.com`）。否则 OAuth 回调可能因 redirect_uri 不匹配而失败，生成的公共链接可能指向内部容器源，同源 Dashboard 变更可能被浏览器源检查拒绝。
@@ -581,36 +577,33 @@ REQUEST_TIMEOUT_MS (全局覆盖)
└── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (默认值: 0 = 禁用)
```
| 变量 | 默认值 | 说明 |
| ------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `REQUEST_TIMEOUT_MS` | _(未设置)_ | 全局快捷方式 — 覆盖 `FETCH_TIMEOUT_MS` 和 `STREAM_IDLE_TIMEOUT_MS` 两者的默认值。 |
| `FETCH_TIMEOUT_MS` | `600000` | 上游服务商调用的 HTTP 请求总超时。 |
| `STREAM_IDLE_TIMEOUT_MS` | `600000` | SSE 块之间的最长静默时间，超时则中止。扩展推理模型很少暂停超过 90 秒。 |
| `STREAM_READINESS_TIMEOUT_MS` | `80000` | 接收第一个非 ping SSE 事件的超时时间。设置时继承 `REQUEST_TIMEOUT_MS`。 |
| `OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS` | _(关闭)_ | 剥离会导致 OpenAI SDK 的 `responses.stream()` 以 502 报错的非标准 `codex.*` SSE 事件（如 `codex.rate_limits`）。设为 `true`/`1`/`yes` 可启用。 |
| `FETCH_HEADERS_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | 接收响应头的超时时间。 |
| `FETCH_BODY_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | 接收完整响应体的超时时间。 |
| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | TCP 连接建立超时。 |
| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Keep-alive 套接字空闲超时。 |
| `TLS_CLIENT_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | TLS 指纹代理（wreq-js）超时。 |
| `API_BRIDGE_PROXY_TIMEOUT_MS` | `30000` | `/v1` 桥接请求的代理跳超时。 |
| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `300000` | 桥接的服务器请求总超时。 |
| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | 通过桥接发送响应头的超时时间。 |
| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | 桥接 keep-alive 空闲超时。 |
| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | 原始套接字超时（0 = 禁用）。 |
| `SHUTDOWN_TIMEOUT_MS` | `30000` | SIGTERM/SIGINT 后强制退出前的宽限期。 |
| `OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS` | `120000` | `FETCH_TIMEOUT_MS` 未设置时 `src/shared/utils/fetchTimeout.ts` 使用的回退值。 |
| `OMNIROUTE_CHATGPT_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`chatgptTlsClient.ts`）。 |
| `OMNIROUTE_CHATGPT_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 |
| `OMNIROUTE_CHATGPT_STREAM_FIRST_BYTE_TIMEOUT_MS` | `30000`（30 秒） | ChatGPT TLS sidecar（`chatgptTlsClient.ts`）在中止死流前等待第一个流式字节的最大时间。如果上游冷启动超过窗口则提高。 |
| `OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`claudeTlsClient.ts`）。 |
| `OMNIROUTE_CLAUDE_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 |
| `OMNIROUTE_PPLX_TLS_TIMEOUT_MS` | `30000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`perplexityTlsClient.ts`）。 |
| `OMNIROUTE_PPLX_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 |
| `OMNIROUTE_GROK_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`grokTlsClient.ts`）。 |
| `OMNIROUTE_GROK_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 |
| `OMNIROUTE_BROWSER_POOL` | `on` | 用于浏览器端 Web Cookie 聊天的共享 Playwright 浏览器池（`browserPool.ts`）；设为 `off` 可禁用。 |
| `WEB_COOKIE_USE_BROWSER` | `0` | 将 Web Cookie 聊天请求选择进入浏览器端路径（`browserBackedChat.ts`）；`1` 启用。 |
| 变量 | 默认值 | 说明 |
| ----------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `REQUEST_TIMEOUT_MS` | _(未设置)_ | 全局快捷方式 — 覆盖 `FETCH_TIMEOUT_MS` 和 `STREAM_IDLE_TIMEOUT_MS` 两者的默认值。 |
| `FETCH_TIMEOUT_MS` | `600000` | 上游服务商调用的 HTTP 请求总超时。 |
| `STREAM_IDLE_TIMEOUT_MS` | `600000` | SSE 块之间的最长静默时间，超时则中止。扩展推理模型很少暂停超过 90 秒。 |
| `STREAM_READINESS_TIMEOUT_MS` | `80000` | 接收第一个非 ping SSE 事件的超时时间。设置时继承 `REQUEST_TIMEOUT_MS`。 |
| `OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS` | _(关闭)_ | 剥离会导致 OpenAI SDK 的 `responses.stream()` 以 502 报错的非标准 `codex.*` SSE 事件（如 `codex.rate_limits`）。设为 `true`/`1`/`yes` 可启用。 |
| `FETCH_HEADERS_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | 接收响应头的超时时间。 |
| `FETCH_BODY_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | 接收完整响应体的超时时间。 |
| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | TCP 连接建立超时。 |
| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Keep-alive 套接字空闲超时。 |
| `TLS_CLIENT_TIMEOUT_MS` | = `FETCH_TIMEOUT_MS` | TLS 指纹代理（wreq-js）超时。 |
| `API_BRIDGE_PROXY_TIMEOUT_MS` | `30000` | `/v1` 桥接请求的代理跳超时。 |
| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `300000` | 桥接的服务器请求总超时。 |
| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | 通过桥接发送响应头的超时时间。 |
| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | 桥接 keep-alive 空闲超时。 |
| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | 原始套接字超时（0 = 禁用）。 |
| `SHUTDOWN_TIMEOUT_MS` | `30000` | SIGTERM/SIGINT 后强制退出前的宽限期。 |
| `OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS` | `120000` | `FETCH_TIMEOUT_MS` 未设置时 `src/shared/utils/fetchTimeout.ts` 使用的回退值。 |
| `OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`claudeTlsClient.ts`）。 |
| `OMNIROUTE_CLAUDE_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 |
| `OMNIROUTE_PPLX_TLS_TIMEOUT_MS` | `30000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`perplexityTlsClient.ts`）。 |
| `OMNIROUTE_PPLX_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 |
| `OMNIROUTE_GROK_TLS_TIMEOUT_MS` | `60000` | bogdanfinn/tls-client koffi 绑定的线路级超时（`grokTlsClient.ts`）。 |
| `OMNIROUTE_GROK_TLS_GRACE_MS` | `10000` | 原生绑定卡住时在线路超时之上添加的 JS 侧宽恕时间。 |
| `OMNIROUTE_BROWSER_POOL` | `on` | 用于浏览器端 Web Cookie 聊天的共享 Playwright 浏览器池（`browserPool.ts`）；设为 `off` 可禁用。 |
| `WEB_COOKIE_USE_BROWSER` | `0` | 将 Web Cookie 聊天请求选择进入浏览器端路径（`browserBackedChat.ts`）；`1` 启用。 |
Combo 目标尝试继承已解析的上游请求超时（`FETCH_TIMEOUT_MS`，或当它提供 fetch 默认值时的 `REQUEST_TIMEOUT_MS`）。仅在 Combo 中设置 `targetTimeoutMs`、Combo 默认值或服务商覆盖值以加快 Combo 回退；超过当前上游超时的值会被截断到上游超时。
@@ -979,8 +972,7 @@ CLI_COMPAT_ALL=1
| `NGROK_AUTHTOKEN` | _(未设置)_ | `src/lib/ngrokTunnel.ts` | 认证出口 ngrok 隧道。 |
| `DB_BACKUP_MAX_FILES` | `20` | `src/lib/db/backup.ts` | 磁盘上保留的最大 SQLite 备份文件数。覆盖从 Settings → Database backup retention 保存的值。 |
| `DB_BACKUP_RETENTION_DAYS` | `0` | `src/lib/db/backup.ts` | 保留备份的最大天数。`0` 禁用基于时间的清理。覆盖从 Settings → Database backup retention 保存的值。 |
| `OMNIROUTE_TLS_PROXY_URL` | _(未设置)_ | `open-sse/services/chatgptTlsClient.ts` | 覆盖测试用的 TLS sidecar URL。生产环境应保持未设置。 |
| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | 入口点权限检查的容器运行时提示。任何 Podman 拓扑都应设为 `podman`。由于容器无法判断引擎位于本地还是通过 Podman Machine 访问，警告会保持拓扑中立并指向 `contrib/podman/README.md`。 |
| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | 入口点权限检查的容器运行时提示。任何 Podman 拓扑都应设为 `podman`。由于容器无法判断引擎位于本地还是通过 Podman Machine 访问，警告会保持拓扑中立并指向 `contrib/podman/README.md`。 |
| `QUOTA_STORE_DRIVER` | `sqlite` | `src/lib/quota/storeFactory.ts` | 配额共享消费存储后端：`sqlite`（默认）或 `redis`。 |
| `QUOTA_STORE_REDIS_URL` | _(未设置)_ | `src/lib/quota/storeFactory.ts` | `QUOTA_STORE_DRIVER=redis` 时使用的 Redis 连接字符串（如 `redis://localhost:6379`）。 |
| `QUOTA_SATURATION_THRESHOLD` | `0.5` | `src/lib/quota/enforce.ts` | 池饱和比率（0..1）；达到或超过该值时池进入严格模式（不允许借用）。 |

178
docs/i18n/zh-TW/docs/architecture/ARCHITECTURE.md
View File

@@ -466,8 +466,6 @@ FSM 轉換結果饋入自動組合的評分，對背景/自動化任務偏向較
- Claude Code CCH（相容性通道握手）：`open-sse/services/claudeCodeCCH.ts`，加上 `claudeCodeCompatible.ts`、`claudeCodeConstraints.ts`、`claudeCodeExtraRemap.ts`、`claudeCodeToolRemapper.ts`
- Claude Code 指紋塑造：`open-sse/services/claudeCodeFingerprint.ts`
- Claude Code 混淆：`open-sse/services/claudeCodeObfuscation.ts`
- ChatGPT TLS 客戶端：`open-sse/services/chatgptTlsClient.ts`（curl-impersonate 風格的 ChatGPT-Web 工作階段）
- ChatGPT 圖片快取：`open-sse/services/chatgptImageCache.ts`
完整的隱匿手冊與操作指南，請參閱
[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md)。
@@ -873,103 +871,103 @@ flowchart LR
每個提供者都有一個專門的執行器，繼承自 `BaseExecutor`（位於 `open-sse/executors/base.ts`），提供 URL 建置、標頭建構、指數退避重試、憑證刷新鉤子與 `execute()` 協調方法。
| 執行器 | 提供者 | 特殊處理 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `DefaultExecutor` | OpenAI、Claude、Gemini、Qwen、OpenRouter、GLM、Kimi、MiniMax、DeepSeek、Groq、xAI、Mistral、Perplexity、Together、Fireworks、Cerebras、Cohere、NVIDIA 等 | 每個提供者的動態 URL/標頭設定 |
| `AntigravityExecutor` | Google Antigravity | 自訂專案/工作階段 ID、Retry-After 解析、429 混淆 |
| `AzureOpenAIExecutor` | Azure OpenAI | 基於部署的路由、api-version 查詢強制 |
| `BlackboxWebExecutor` | Blackbox AI（網頁模式） | 含 TLS 指紋模擬的網頁工作階段反向 |
| `ChatGPTWebExecutor` | ChatGPT 網頁 | TLS 客戶端 + 工作階段 Cookie 管理（`chatgptTlsClient.ts`） |
| `ClaudeIdentityExecutor` | Claude.ai（CCH 路徑） | 約束 + 工具重新對應管線、指紋塑造 |
| `CliProxyApiExecutor` | CLIProxyAPI 相容提供者 | 自訂驗證與協定處理 |
| `CloudflareAiExecutor` | Cloudflare Workers AI | 帳戶 ID 注入、基於 Neurons 的用量追蹤 |
| `CodexExecutor` | OpenAI Codex | 注入系統指令、強制推理努力 |
| `CommandCodeExecutor` | Command Code | OAuth + 每個工作階段的標頭輪換 |
| `CursorExecutor` | Cursor IDE | ConnectRPC 協定、Protobuf 編碼、透過 checksum 的請求簽署 |
| `DevinCliExecutor` | Devin CLI | 透過雲端代理模組的 Devin 任務生命週期橋接 |
| `GithubExecutor` | GitHub Copilot | Copilot 令牌刷新、模擬 VSCode 標頭 |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth + 專案範圍路由 |
| `GlmExecutor` | Z.AI GLM（含 `glmt` 預設） | 思考預算感知、GLMT 預設常數 |
| `GrokWebExecutor` | xAI Grok 網頁 | 網頁工作階段反向、模式選擇（think/standard） |
| `KieExecutor` | KIE | 自訂令牌簽發，含輪換的工作階段錨點 |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream 二進位格式 → SSE 轉換 |
| `MuseSparkWebExecutor` | Muse Spark（網頁） | 含圖片訊息橋接的網頁工作階段反向 |
| `NlpCloudExecutor` | NLP Cloud | 提供者特定的請求主體形式 |
| `OpenCodeExecutor` | OpenCode | AI SDK 相容提供者設定 |
| `PerplexityWebExecutor` | Perplexity 網頁 | 用於聊天延續的網頁工作階段反向 |
| `PetalsExecutor` | Petals 分散式推理 | 去中心化群組路由 |
| `PollinationsExecutor` | Pollinations AI | 無需 API 金鑰、速率限制請求 |
| `QoderExecutor` | Qoder AI | PAT 與 OAuth 支援、多模型免費方案 |
| `VertexExecutor` | Google Vertex AI | 服務帳戶驗證、基於區域的端點 |
| `DevinDesktopExecutor` | Devin Desktop | 匯入的 API 金鑰 + Connect-protobuf 聊天串流 |
| 執行器 | 提供者 | 特殊處理 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `DefaultExecutor` | OpenAI、Claude、Gemini、Qwen、OpenRouter、GLM、Kimi、MiniMax、DeepSeek、Groq、xAI、Mistral、Perplexity、Together、Fireworks、Cerebras、Cohere、NVIDIA 等 | 每個提供者的動態 URL/標頭設定 |
| `AntigravityExecutor` | Google Antigravity | 自訂專案/工作階段 ID、Retry-After 解析、429 混淆 |
| `AzureOpenAIExecutor` | Azure OpenAI | 基於部署的路由、api-version 查詢強制 |
| `BlackboxWebExecutor` | Blackbox AI（網頁模式） | 含 TLS 指紋模擬的網頁工作階段反向 |
| `ClaudeIdentityExecutor` | Claude.ai（CCH 路徑） | 約束 + 工具重新對應管線、指紋塑造 |
| `CliProxyApiExecutor` | CLIProxyAPI 相容提供者 | 自訂驗證與協定處理 |
| `CloudflareAiExecutor` | Cloudflare Workers AI | 帳戶 ID 注入、基於 Neurons 的用量追蹤 |
| `CodexExecutor` | OpenAI Codex | 注入系統指令、強制推理努力 |
| `ChatGptWebCodexExecutor` | ChatGPT Web (Codex) | 瀏覽器工作階段 Responses API 橋接與執行緒/輪次固定 |
| `CommandCodeExecutor` | Command Code | OAuth + 每個工作階段的標頭輪換 |
| `CursorExecutor` | Cursor IDE | ConnectRPC 協定、Protobuf 編碼、透過 checksum 的請求簽署 |
| `DevinCliExecutor` | Devin CLI | 透過雲端代理模組的 Devin 任務生命週期橋接 |
| `GithubExecutor` | GitHub Copilot | Copilot 令牌刷新、模擬 VSCode 標頭 |
| `GitlabExecutor` | GitLab Duo | GitLab OAuth + 專案範圍路由 |
| `GlmExecutor` | Z.AI GLM（含 `glmt` 預設） | 思考預算感知、GLMT 預設常數 |
| `GrokWebExecutor` | xAI Grok 網頁 | 網頁工作階段反向、模式選擇（think/standard） |
| `KieExecutor` | KIE | 自訂令牌簽發，含輪換的工作階段錨點 |
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream 二進位格式 → SSE 轉換 |
| `MuseSparkWebExecutor` | Muse Spark（網頁） | 含圖片訊息橋接的網頁工作階段反向 |
| `NlpCloudExecutor` | NLP Cloud | 提供者特定的請求主體形式 |
| `OpenCodeExecutor` | OpenCode | AI SDK 相容提供者設定 |
| `PerplexityWebExecutor` | Perplexity 網頁 | 用於聊天延續的網頁工作階段反向 |
| `PetalsExecutor` | Petals 分散式推理 | 去中心化群組路由 |
| `PollinationsExecutor` | Pollinations AI | 無需 API 金鑰、速率限制請求 |
| `QoderExecutor` | Qoder AI | PAT 與 OAuth 支援、多模型免費方案 |
| `VertexExecutor` | Google Vertex AI | 服務帳戶驗證、基於區域的端點 |
| `DevinDesktopExecutor` | Devin Desktop | 匯入的 API 金鑰 + Connect-protobuf 聊天串流 |
所有其他提供者（包括自訂相容節點）使用 `DefaultExecutor`。
## 提供者相容性矩陣
> **注意：** 以下矩陣為 OmniRoute v3.8.0 中 237 個已註冊提供者的代表性樣本。
> **注意：** 以下矩陣為 OmniRoute v3.8.0 中 351 個已註冊提供者的代表性樣本。
> 完整且持續更新的清單，請參閱
> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md)（自動產生）或
> `src/shared/constants/providers.ts`（載入時經 Zod 驗證）中的權威來源。
| 提供者 | 格式 | 驗證 | 串流 | 非串流 | 令牌刷新 | 用量 API |
| ------------------ | ---------------- | --------------------- | ---------------- | ------ | -------- | ---------------- |
| Claude | claude | API 金鑰 / OAuth | ✅ | ✅ | ✅ | ⚠️ 僅管理員 |
| Gemini | gemini | API 金鑰 / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ 完整配額 API |
| OpenAI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ 強制 | ❌ | ✅ | ✅ 速率限制 |
| GitHub Copilot | openai | OAuth + Copilot 令牌 | ✅ | ✅ | ✅ | ✅ 配額快照 |
| Cursor | cursor | 自訂 checksum | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ 用量限制 |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每次請求 |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| xAI（Grok） | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API 令牌 + 帳戶 ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | 無（無需金鑰） | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API 金鑰（選用） | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | 服務帳戶 | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每次請求 |
| Z.AI / GLM | openai | API 金鑰 / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT（預設） | claude | API 金鑰 | ✅ | ✅ | ❌ | ⚠️ 每次請求 |
| Kimi Coding | openai | OAuth / API 金鑰 | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | 匯入的 API 金鑰 | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ 每次請求 |
| GitLab Duo | openai | OAuth（GitLab） | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | 本機 CLI 登入 | ✅ | ✅ | ❌ | ✅ 任務 API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ 速率限制 |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ 任務 API |
| AgentRouter | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| ChatGPT-Web | openai | 工作階段 Cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | 工作階段 Cookie | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | 工作階段 Cookie | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | 工作階段 Cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | 工作階段 Cookie | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API 金鑰 | ✅ | ✅ | ❌ | ⚠️ 配額政策 |
| BazaarLink | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | 無 | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每次請求 |
| OpenCode（Go/Zen） | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | 自訂 | ✅ | ✅ | ❌ | ❌ |
| 提供者 | 格式 | 驗證 | 串流 | 非串流 | 令牌刷新 | 用量 API |
| ------------------- | ---------------- | --------------------- | ---------------- | ------ | -------- | ---------------- |
| Claude | claude | API 金鑰 / OAuth | ✅ | ✅ | ✅ | ⚠️ 僅管理員 |
| Gemini | gemini | API 金鑰 / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ 完整配額 API |
| OpenAI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Codex | openai-responses | OAuth | ✅ 強制 | ❌ | ✅ | ✅ 速率限制 |
| ChatGPT Web (Codex) | openai-responses | 瀏覽器工作階段 | ✅ 強制 | ❌ | ❌ | ❌ |
| GitHub Copilot | openai | OAuth + Copilot 令牌 | ✅ | ✅ | ✅ | ✅ 配額快照 |
| Cursor | cursor | 自訂 checksum | ✅ | ✅ | ❌ | ❌ |
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ 用量限制 |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每次請求 |
| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| OpenRouter | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| GLM/Kimi/MiniMax | claude | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| DeepSeek | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Groq | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| xAI（Grok） | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Mistral | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Perplexity | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Together AI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Fireworks AI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Cerebras | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Cohere | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| NVIDIA NIM | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Cloudflare AI | openai | API 令牌 + 帳戶 ID | ✅ | ✅ | ❌ | ❌ |
| Pollinations | openai | 無（無需金鑰） | ✅ | ✅ | ❌ | ❌ |
| Scaleway AI | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| LongCat | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Ollama Cloud | openai | API 金鑰（選用） | ✅ | ✅ | ❌ | ❌ |
| HuggingFace | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Nebius | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| SiliconFlow | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Hyperbolic | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Vertex AI | gemini | 服務帳戶 | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ 每次請求 |
| Z.AI / GLM | openai | API 金鑰 / OAuth | ✅ | ✅ | ❌ | ❌ |
| GLMT（預設） | claude | API 金鑰 | ✅ | ✅ | ❌ | ⚠️ 每次請求 |
| Kimi Coding | openai | OAuth / API 金鑰 | ✅ | ✅ | ✅ | ❌ |
| KIE | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Devin Desktop | openai | 匯入的 API 金鑰 | ✅ (Connect→SSE) | ✅ | ❌ | ⚠️ 每次請求 |
| GitLab Duo | openai | OAuth（GitLab） | ✅ | ✅ | ✅ | ❌ |
| Devin CLI | openai | 本機 CLI 登入 | ✅ | ✅ | ❌ | ✅ 任務 API |
| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ 速率限制 |
| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ 任務 API |
| AgentRouter | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Grok-Web | openai | 工作階段 Cookie | ✅ | ✅ | ❌ | ❌ |
| Perplexity-Web | openai | 工作階段 Cookie | ✅ | ✅ | ❌ | ❌ |
| BlackBox-Web | openai | 工作階段 Cookie + TLS | ✅ | ✅ | ❌ | ❌ |
| Muse-Spark-Web | openai | 工作階段 Cookie | ✅ | ✅ | ❌ | ❌ |
| ModelScope | openai | API 金鑰 | ✅ | ✅ | ❌ | ⚠️ 配額政策 |
| BazaarLink | openai | API 金鑰 | ✅ | ✅ | ❌ | ❌ |
| Petals | openai | 無 | ✅ | ✅ | ❌ | ❌ |
| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ 每次請求 |
| OpenCode（Go/Zen） | openai | OAuth | ✅ | ✅ | ✅ | ❌ |
| CLIProxyAPI | openai | 自訂 | ✅ | ✅ | ❌ | ❌ |
## 格式轉換覆蓋範圍

9
docs/i18n/zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md
View File

@@ -229,7 +229,6 @@ v1/
├── audio/{speech, transcriptions}/ TTS + STT
├── batches/[id]/{cancel}、batches/ OpenAI Batches API
├── chat/completions/ 聊天補全（主要端點）
├── chatgpt-web/ ChatGPT-Web 相容層
├── completions/ 舊版文字補全
├── embeddings/ 嵌入向量
├── files/[id]/、files/ 檔案 API
@@ -476,16 +475,16 @@ open-sse/
### 4.2 `open-sse/executors/`
84 個提供者執行器，每個都繼承 `BaseExecutor`（`base.ts`）：
107 個提供者執行器，每個都繼承 `BaseExecutor`（`base.ts`）：
`antigravity`、`azure-openai`、`blackbox-web`、`chatgpt-web`、`cliproxyapi`、
`cloudflare-ai`、`codex`、`commandCode`、`cursor`、`default`、`devin-cli`、
`antigravity`、`azure-openai`、`blackbox-web`、`cliproxyapi`、
`chatgpt-web-codex`、`cloudflare-ai`、`codex`、`commandCode`、`cursor`、`default`、`devin-cli`、
`muse-spark-web`、`nlpcloud`、`opencode`、`perplexity-web`、`petals`、
`pollinations`、`qoder`、`vertex`、`windsurf`，加上 `claudeIdentity.ts`
（共用身分識別輔助程式）和 `index.ts`（註冊表）。
> 注意：未列在此處的提供者由 `default.ts` 使用通用的
> 與 OpenAI 相容的執行器處理。完整的 329 項提供者目錄位於
> 與 OpenAI 相容的執行器處理。完整的 351 項提供者目錄位於
> `src/shared/constants/providers.ts`。
### 4.3 `open-sse/translator/`

272
docs/providers/CHATGPT_WEB.md
View File

@@ -1,166 +1,61 @@
---
title: "Providers — ChatGPT Web (session credentials via Cookie Editor)"
title: "Providers — ChatGPT Web (Codex)"
version: 3.8.50
lastUpdated: 2026-08-08
lastUpdated: 2026-08-26
---
# Providers — ChatGPT Web (Plus/Pro session credentials)
# Providers — ChatGPT Web (Codex)
`chatgpt-web` (alias `cgpt-web`, display name **ChatGPT Web (Plus/Pro)**) sends OpenAI-format chat requests through an authenticated `chatgpt.com` browser session. It authenticates with the `__Secure-next-auth.session-token` cookie — **no API key required**.
`chatgpt-web-codex` (alias `cgpt-codex`) bridges Codex Responses turns through an
authenticated ChatGPT browser session. It is independent from the retired common
`chatgpt-web` provider and uses the MIT-noticed implementation under
`open-sse/vendor/codex-chatgpt-web/`.
> **New to Web Cookie providers?**
>
> Read **`docs/getting-started/WEB-COOKIE-GUIDE.md`** for the general setup process, limitations, and troubleshooting before following this provider-specific guide.
## Common provider retirement
---
The former common provider IDs `chatgpt-web` and `cgpt-web` no longer ship because the
provenance of their pre-key/proof-of-work implementation could not be cleared. Explicit
requests to either ID, including slash-prefixed model IDs and persisted aliases, fail
closed with HTTP `410` and code **PROVIDER_RETIRED** before any upstream request.
## 1. What credential does OmniRoute need?
Migration `163_retire_chatgpt_web.sql` tombstones matching provider connections and
invalidates their active session leases. It preserves connection history and API-key
allowlists; it does not add replacement access to an allowlist. The Codex provider and
its connections are not matched by this retirement.
Defined in `src/shared/constants/providers/web-cookie.ts` + `src/shared/providers/webSessionCredentials.ts`:
| Field | Value |
| -------------------------- | ----------------------------------------------------------------------------- |
| Provider id | `chatgpt-web` |
| Credential name | `__Secure-next-auth.session-token` |
| Accepts full Cookie header | ✅ yes |
| Accepted storage keys | `cookie`, `sessionToken`, `session-token`, `__Secure-next-auth.session-token` |
Two paste formats both work:
- **Bare value** — just the token contents: `eyJhbGciOi...`
- **Full Cookie header** — `__Secure-next-auth.session-token=eyJhbGciOi...; cf_clearance=...` (preferred — carries rotation/anti-bot cookies the executor needs)
---
## 2. Copy the cookie header with Cookie Editor
Cookie Editor can copy the cookies for the active `chatgpt.com` tab as an HTTP header string.
Always compare the exported value with a live authenticated request as described in section 3.
### 2.1 Install and pin
1. Install **[Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)** (Moustachauve) in Chrome/Edge, or the Firefox equivalent.
2. Pin it to the toolbar if you use it regularly.
### 2.2 Copy the credential
1. Go to **https://chatgpt.com** and make sure you're **signed in with the Plus/Pro account** you want OmniRoute to use.
2. Open a conversation and send at least one message (forces the session token to be live/refreshed).
3. Click the **Cookie Editor** icon to open its side panel for the active tab.
4. Find `__Secure-next-auth.session-token`. If it's split into chunks (`__Secure-next-auth.session-token.0`, `.1`, …), select **all** of them — OmniRoute's `nextAuthCookie.ts` merges rotated chunk families.
5. Click **Copy**, choose **Header string**, and copy the resulting `name=value; name=value` text.
> **If the token is missing:** confirm that you are signed in, send a message to refresh the session, and inspect the live request in section 3.
---
## 3. Verify the required data (before pasting)
The repo's `WEB-COOKIE-GUIDE.md` mandates a live-request check. Do it once per session:
1. With chatgpt.com open, press **F12** → **Network** tab.
2. Refresh the page, then send a chat message.
3. Click the conversation request (e.g. `/backend-api/conversation` or the SSE stream) → **Headers** → **Request Headers** → **Cookie**.
4. Confirm it contains `__Secure-next-auth.session-token=...` — **not** just `cf_clearance` or `__cf_bm`.
The value you copied in step 2.3 must match what the live request sends. If they differ, re-copy from Cookie Editor.
---
## 4. Add / update the credential in OmniRoute
### Dashboard (typical user path)
1. Open the OmniRoute dashboard → **Providers** → **Add Provider**.
2. Search **ChatGPT Web (Plus/Pro)** (id `chatgpt-web`).
3. Paste the copied cookie header into the credential field.
4. Click **Test Connection**.
5. Save.
If requests later return 401 or 403, re-copy the header from a fresh live session. The executor merges `Set-Cookie` rotations while the connection is active, but it cannot recover a credential that is no longer accepted upstream.
### Bulk / session pools (many accounts)
For multiple ChatGPT sessions, use the bulk web-session import or session-pool endpoints:
- `POST /api/providers/bulk-web-session` — import many cookie credentials at once
- `GET /api/session-pools` + `/api/session-pools/[provider]` — pool rotation across accounts
Each credential blob must carry the `__Secure-next-auth.session-token` value under one of the accepted storage keys (`cookie`, `sessionToken`, `session-token`, or the cookie's exact name).
### Renewing when the session expires
Web sessions can stop working after sign-out or server-side rotation. Re-run steps 2.2 through 4 whenever requests start failing with 401/403.
---
## 5. Contributing updates
If you changed the credential contract (new storage key, new cookie name, changed hint) or are filling the docs gap, contribute it:
1. Update `src/shared/providers/webSessionCredentials.ts` (credential name / placeholder / storage keys) or `src/shared/constants/providers/web-cookie.ts` (`authHint`).
2. Update this guide (`docs/providers/CHATGPT_WEB.md`) and the provider table in `docs/getting-started/WEB-COOKIE-GUIDE.md`.
3. Update `.env.example` + `docs/reference/ENVIRONMENT.md` if you touched env vars, then run:
```bash
node scripts/check/check-env-doc-sync.mjs # must pass
```
4. Run the provider/unit tests:
```bash
npm run test:unit
# targeted: tests/unit/chatgpt-web.test.ts (stealth path)
```
5. Follow `CONTRIBUTING.md`, branch from the current active release tip, use a Conventional Commit message, and open the PR against that active release branch.
> ⚠️ **Never commit a real cookie value.** All examples above are placeholders. If a test fixture needs a token, use a fake `eyJhbGciOi...` string.
---
## Troubleshooting
| Symptom | Likely cause | Fix |
| -------------------------------- | -------------------------------------------- | --------------------------------------------------------- |
| Cookie not in Cookie Editor | Signed out / not HttpOnly-visible | Sign in; enable HttpOnly display in options |
| Token missing from live request | Request is not authenticated | Sign in and send a chat message first |
| 401 after Test Connection passed | Expired or rotated session | Re-copy from a fresh live request |
| Chunked token fails | Only one chunk pasted | Select all `__Secure-next-auth.session-token.*` chunks |
---
## ChatGPT Web (Codex)
`ChatGPT Web (Codex)` is an additional provider. The existing
`ChatGPT Web (Plus/Pro)` provider described above stays unchanged for regular
chats, images, and its existing tool emulation.
### Prerequisites
## Prerequisites
- a full Cookie header from a signed-in ChatGPT session;
- Chrome or Chromium for npm, systemd, and PM2 installs;
- with the Docker `web` profile, the internal Chromium service from `docker-compose.yml`;
- with the Docker `web` profile, the internal Chromium service from
`docker-compose.yml`;
- an OpenAI tunnel and a ChatGPT custom connector for local Codex tools.
The tunnel is only needed for tool turns. `pro` is read-only and does not need a
local tool connector.
The tunnel is only needed for tool turns. The `pro` model is read-only and does not need
a local tool connector.
### Dashboard setup
## Dashboard setup
1. Open the **ChatGPT Web (Codex)** provider and add a connection.
2. Paste the full ChatGPT cookie, the tunnel ID, the runtime key, and the name of
the custom connector.
3. Start the check. OmniRoute opens a headless Temporary Chat and also detects
2. Paste the full ChatGPT Cookie header, tunnel ID, runtime key, and custom connector
name.
3. Run the connection check. OmniRoute opens a headless Temporary Chat and detects
whether `pro` is available for the account.
4. Save the connection. OmniRoute replaces the pasted cookie with the verified
Playwright storage state and stores it together with the runtime key through
the encrypted credential abstraction.
Playwright storage state and stores it with the runtime key through the encrypted
credential abstraction.
The raw cookie is not retained after a successful save. When the session expires,
open the connection, paste a fresh full cookie, and re-run the check. The doctor
status in the edit dialog reports browser, storage state, sign-in, Temporary
Chat, tunnel, connector, and tool round-trip separately.
The raw cookie is not retained after a successful save. When the session expires, open
the connection, paste a fresh full Cookie header, and rerun the check. The doctor status
in the edit dialog reports browser, storage state, sign-in, Temporary Chat, tunnel,
connector, and tool round-trip separately.
### Models and combos
> Never commit a real cookie, runtime key, storage state, or capability token. Test and
> documentation values must always be placeholders.
The fixed models are:
## Models and combos
The fixed model routes are:
- `chatgpt-web-codex/instant`
- `chatgpt-web-codex/medium`
@@ -168,54 +63,71 @@ The fixed models are:
- `chatgpt-web-codex/extra-high`
- `chatgpt-web-codex/pro`
Add one of them to a combo like any other model. The Codex app sends only the
combo name as `model` to the regular Responses endpoint `/v1/responses`. There is
no special endpoint and no Codex-mode switch.
Add one of them to a combo like any other model. The Codex app sends the combo name as
`model` to the regular Responses endpoint, `/v1/responses`; there is no separate Codex
endpoint or mode switch.
`pro` does not run local tools. A forced tool makes that combo target
incompatible; with optional tools the turn runs read-only and reports that
limitation as commentary.
`pro` does not run local tools. A forced tool makes that combo target incompatible. With
optional tools, the turn runs read-only and reports the limitation as commentary.
### Security model
## Security model
- The native path requires a Responses request, a recognized Codex client, and
matching thread and turn identities.
- Workspace, sandbox, approval policy, and the tool catalog come from the native
Codex shell. Free-form prompt text is not an authority for them.
- ChatGPT receives only a short-lived capability per turn. The MCP broker accepts
only tools that Codex offered in exactly that turn.
- Auto-confirming "Allow once" only returns the tool request to Codex. Codex
alone decides on approval and execution.
- Before the first output, the combo may fall back to another compatible target.
After that, provider, model, connection, and browser turn stay pinned until the
- The native path requires a Responses request, a recognized Codex client, and matching
thread and turn identities.
- Workspace, sandbox, approval policy, and tool catalog come from the native Codex shell;
free-form prompt text is not authority for them.
- ChatGPT receives only a short-lived capability per turn. The MCP broker accepts only
tools Codex offered in that exact turn.
- Auto-confirming **Allow once** only returns the tool request to Codex. Codex alone
decides on approval and execution.
- Before the first output, a combo may fall back to another compatible target. After
output begins, provider, model, connection, and browser turn remain pinned until the
turn completes.
- Cookies, runtime keys, storage state, and capability tokens do not appear in
provider responses or request logs.
- Cookies, runtime keys, storage state, and capability tokens do not appear in provider
responses or request logs.
### Headless VPS and Docker
## Headless VPS and Docker
For npm, systemd, and PM2 installs, OmniRoute detects common Chrome and Chromium
paths. Alternatively, set `CHATGPT_WEB_CODEX_CHROME_PATH`.
For npm, systemd, and PM2 installs, OmniRoute detects common Chrome and Chromium paths.
Alternatively, set `CHATGPT_WEB_CODEX_CHROME_PATH`.
The Docker `web` profile starts `chatgpt-web-codex-browser` on the internal
Compose network. Its CDP port is not published on the host. The protected profile
volume stays separate from the OmniRoute data volume, and the browser gets enough
shared memory. The internal CDP proxy listens only on the Compose network on port
`9223`; Chrome itself stays bound to loopback inside the sidecar.
The Docker `web` profile starts `chatgpt-web-codex-browser` on the internal Compose
network. Its CDP port is not published on the host. The protected browser profile volume
is separate from the OmniRoute data volume, and the browser receives enough shared
memory. The internal CDP proxy listens only on port `9223` inside the Compose network;
Chrome remains bound to loopback in the sidecar.
A supervisor lease under `DATA_DIR` prevents multiple OmniRoute processes from
owning the same tunnel and broker state. A conflict shows up in the doctor.
A supervisor lease under `DATA_DIR` prevents multiple OmniRoute processes from owning
the same tunnel and broker state. A conflict is reported by the doctor.
### Interactive recovery
## Interactive recovery
The normal path is fully headless. When ChatGPT demands an interactive sign-in or
challenge, the existing VNC browser infrastructure can be used as a recovery
path. Browser UI and CDP must then only be reachable over loopback, an
authenticated management connection, or an SSH tunnel; noVNC stays disabled in
normal operation.
The normal path is headless. When ChatGPT requires an interactive sign-in or challenge,
the existing VNC browser infrastructure can be used for recovery. Browser UI and CDP
must remain reachable only over loopback, an authenticated management connection, or an
SSH tunnel; noVNC stays disabled during normal operation.
### WebSocket fallback
## WebSocket fallback
When a combo contains `ChatGPT Web (Codex)`, the Responses WebSocket bridge
requests the HTTP/SSE fallback before connecting upstream. The actual transfer
then goes through `/v1/responses`.
When a combo contains ChatGPT Web (Codex), the Responses WebSocket bridge requests the
HTTP/SSE fallback before connecting upstream. The transfer then goes through
`/v1/responses`.
## Verification
Run the provider controls without invoking the retired provider:
```bash
node --import tsx/esm --test \\
tests/unit/chatgpt-web-codex.test.ts \\
tests/unit/chatgpt-web-codex-turn-pin.test.ts \\
tests/unit/chatgpt-web-environment-double-unescape.test.ts
```
Retirement regression guards live in:
- `tests/unit/chatgpt-web-retirement.test.ts`
- `tests/unit/chatgpt-web-runtime-block.test.ts`
- `tests/unit/chatgpt-web-image-handler-retirement.test.ts`
- `tests/unit/chatgpt-web-source-retirement.test.ts`
- `tests/unit/migration-163-retire-chatgpt-web.test.ts`

10
docs/reference/ENVIRONMENT.md
View File

@@ -305,14 +305,10 @@ OmniRoute provides a two-layer defense: request-side injection scanning and resp
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | OAuth, Dashboard, sync | Public-facing URL for OAuth redirect_uri, Dashboard links, and generated public URLs. Set this to the stable public URL when OAuth callbacks or generated browser links must use a canonical reverse-proxy host. |
| `NEXT_PUBLIC_CLOUD_URL` | _(empty)_ | Client-side | Client-side mirror of `CLOUD_URL`. |
| `NEXT_PUBLIC_APP_URL` | _(unset)_ | `src/shared/services/cloudSyncScheduler.ts` | Legacy fallback for `NEXT_PUBLIC_BASE_URL`. |
| `OMNIROUTE_PUBLIC_BASE_URL` | _(unset)_ | Public-origin resolver, image URLs | Highest-priority browser-facing OmniRoute origin used for public URL generation and non-dashboard browser-origin validation (for example `/v1/chatgpt-web/image/<id>`). Set this when OpenWebUI or another relay reaches OmniRoute by an internal URL but the user's browser must fetch images from a LAN, tunnel, or public origin. Do **not** include `/v1`. |
| `OMNIROUTE_PUBLIC_BASE_URL` | _(unset)_ | Public-origin resolver, image URLs | Highest-priority browser-facing OmniRoute origin used for public URL generation and non-dashboard browser-origin validation. Set this when OpenWebUI or another relay reaches OmniRoute by an internal URL but the user's browser must fetch generated media from a LAN, tunnel, or public origin. Do **not** include `/v1`. |
| `OMNIROUTE_PROVIDER_MANIFEST_URL` | _(unset)_ | `open-sse/config/providerPluginManifestUrl.ts` | Absolute provider plugin manifest URL advertised to sidecar clients. When unset, OmniRoute derives `/api/v1/provider-plugin-manifest` from request origin or HOST/PORT. |
| `OMNIROUTE_PUBLIC_PROTOCOL` | `http` | `open-sse/config/providerPluginManifestUrl.ts` | Protocol used when deriving the provider plugin manifest URL from HOST/PORT without a request origin. Set to `https` behind a TLS-terminating public proxy when no explicit `OMNIROUTE_PROVIDER_MANIFEST_URL` is set. |
| `OMNIROUTE_TRUST_PROXY` | _(unset)_ | `src/server/origin/publicOrigin.ts` | Optional trust mode for forwarded public-origin headers. Unset = do not trust `Forwarded` / `X-Forwarded-*` for security decisions. `true` / `loopback` trusts forwarded host/proto only from a token-stamped loopback proxy. `private` / `lan` also trusts private-LAN proxy peers. Prefer explicit `NEXT_PUBLIC_BASE_URL` in production. |
| `OMNIROUTE_CGPT_WEB_IMAGE_TIMEOUT_MS` | `180000` (3 min) | `open-sse/executors/chatgpt-web.ts` | Max wait time for an async chatgpt-web image to land via the celsius WebSocket. Increase during upstream queue-deep windows. |
| `OMNIROUTE_CGPT_WEB_IMAGE_CACHE_MAX_MB` | `256` | `open-sse/services/chatgptImageCache.ts` | Total in-memory byte budget (MB) for the chatgpt-web image cache serving `/v1/chatgpt-web/image/<id>`. Lower on memory-constrained hosts; raise if image generation is heavy and clients race the 30-minute TTL. |
| `OMNIROUTE_CGPT_WEB_PRO_TIMEOUT_MS` | `1200000` (20 min) | `open-sse/executors/chatgpt-web.ts` | Overall wait budget for a chatgpt-web GPT-5.5 Pro background-poll handoff. Pro reasoning runs complete out-of-band, so OmniRoute polls until the answer lands or this budget elapses. Raise if Pro requests time out before finishing. |
| `OMNIROUTE_CGPT_WEB_PRO_POLL_INTERVAL_MS` | `4000` (4s) | `open-sse/executors/chatgpt-web.ts` | Interval between chatgpt-web GPT-5.5 Pro background-poll attempts. Lower for snappier completion at the cost of more upstream polling; raise to reduce request volume. |
| `THEOLDLLM_NAV_TIMEOUT_MS` | `30000` (30s) | `open-sse/executors/theoldllm.ts` | Playwright navigation timeout (ms) for the browser-backed token capture used by the The Old LLM (theoldllm) free provider. Raise on slow networks if the relay page is slow to settle. |
| `KIE_CALLBACK_URL` | _(unset)_ | `open-sse/utils/kieTask.ts` | Public callback URL for asynchronous kie.ai jobs. Highest-priority override before `OMNIROUTE_KIE_CALLBACK_URL` and `OMNIROUTE_PUBLIC_URL`. |
| `OMNIROUTE_KIE_CALLBACK_URL` | _(unset)_ | `open-sse/utils/kieTask.ts` | Alternate spelling of `KIE_CALLBACK_URL`. Falls back when the primary variable is unset. |
@@ -768,9 +764,6 @@ REQUEST_TIMEOUT_MS (global override)
| `OMNIROUTE_PROVIDER_PROBE_TIMEOUT_MS` | `8000` | Timeout (ms) for the `validationRead` and `modelsProbe` presets in `src/shared/network/safeOutboundFetch.ts`. Raise for slow endpoints (Cerebras, Cloudflare AI, Groq) to prevent flapping between active/error in the dashboard. Falls back to 8000ms for invalid (<1000) or non-numeric values. |
| `OMNIROUTE_RELAY_FETCH_TIMEOUT_MS` | `25000` | Relay-specific fetch timeout in `open-sse/utils/proxyFetch.ts` (#9158). A hung relay must fail before the client/agent timeout (~30s) so callers see a relay-specific failure instead of a generic upstream timeout. Capped at `29000` so it always fires first. |
| `OMNIROUTE_RETRY_BACKOFF_MS` | `10` | Shared retry backoff for the direct/relay/proxy retry-once paths in `open-sse/utils/proxyFetch.ts` (#9158). `0` = retry immediately. |
| `OMNIROUTE_CHATGPT_TLS_TIMEOUT_MS` | `60000` | Wire-level timeout for the bogdanfinn/tls-client koffi binding (`chatgptTlsClient.ts`). |
| `OMNIROUTE_CHATGPT_TLS_GRACE_MS` | `10000` | JS-side grace added on top of the wire timeout when the native binding is wedged. |
| `OMNIROUTE_CHATGPT_STREAM_FIRST_BYTE_TIMEOUT_MS` | `30000` (30s) | Max wait for the first streamed byte from the ChatGPT TLS sidecar (`chatgptTlsClient.ts`) before aborting a dead stream. Raise if upstream cold-starts exceed the window. |
| `OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS` | `60000` | Wire-level timeout for the bogdanfinn/tls-client koffi binding (`claudeTlsClient.ts`). |
| `OMNIROUTE_CLAUDE_TLS_GRACE_MS` | `10000` | JS-side grace added on top of the wire timeout when the native binding is wedged. |
| `OMNIROUTE_PPLX_TLS_TIMEOUT_MS` | `30000` | Wire-level timeout for the bogdanfinn/tls-client koffi binding (`perplexityTlsClient.ts`). |
@@ -1316,7 +1309,6 @@ Provider quota endpoints, network tunnels (Tailscale, Ngrok, MITM debug proxy),
| `DB_BACKUP_MAX_FILES` | `20` | `src/lib/db/backup.ts`, `src/lib/db/migrationRunner.ts` | Maximum SQLite backup files retained on disk. Applies to manual/scheduled backups and to pre-migration snapshots. Overrides the value saved from Settings → Database backup retention. |
| `DB_BACKUP_RETENTION_DAYS` | `0` | `src/lib/db/backup.ts`, `src/lib/db/migrationRunner.ts` | Maximum age (days) of retained backups. `0` disables age-based pruning. Applies to manual/scheduled backups and to pre-migration snapshots. Overrides the value saved from Settings → Database backup retention. |
| `OMNIROUTE_BACKUP_SCHEDULE_JOB_INTERVAL_MS` | `30000` | `src/lib/jobs/backupScheduleJob.ts` | Tick interval (ms) of the server-side job that executes `backup-schedule.json`. Must stay well under the 1-minute cron granularity; values below `5000` or unparseable fall back to `30000`. |
| `OMNIROUTE_TLS_PROXY_URL` | _(unset)_ | `open-sse/services/chatgptTlsClient.ts` | Override the TLS sidecar URL for tests. Production should leave unset. |
| `CONTAINER_HOST` | `docker` | `scripts/check-permissions.sh` | Container runtime hint for the entrypoint permission check. Set to `podman` for any Podman topology. Because the container cannot determine whether the engine is local or reached through Podman Machine, the warning stays topology-neutral and points to `contrib/podman/README.md`. |
| `QUOTA_STORE_DRIVER` | `sqlite` | `src/lib/quota/storeFactory.ts` | Quota-share consumption store backend: `sqlite` (default) or `redis`. |
| `QUOTA_STORE_REDIS_URL` | _(unset)_ | `src/lib/quota/storeFactory.ts` | Redis connection string used when `QUOTA_STORE_DRIVER=redis` (e.g. `redis://localhost:6379`). |

3
docs/reference/PROVIDER_REFERENCE.md
View File

@@ -82,14 +82,13 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each
| `zed` | `zd` | Zed IDE | OAuth | [link](https://zed.dev) | Zed stores LLM provider credentials (OpenAI, Anthropic, Google, Mistral, xAI) in the OS keychain. Use the Import button below to discover and import them automatically. |
| `zed-hosted` | — | Zed Hosted Models | OAuth | [link](https://zed.dev) | Sign in with your Zed account (native-app sign-in). OmniRoute generates a one-time RSA keypair and opens zed.dev to authorize it — on a remote/headless install, copy the resulting 127.0.0.1 callback URL from your browser's address bar and paste it back here. Distinct from the 'Zed IDE' credential-import entry above: this proxies chat completions through Zed's own hosted model aggregator (cloud.zed.dev), fronting Anthropic/OpenAI/Google/xAI models under your Zed plan. |
## Web Cookie Providers (35)
## Web Cookie Providers (34)
| ID | Alias | Name | Tags | Website | Notes | Tool calling |
|----|-------|------|------|---------|-------|--------------|
| `adapta-web` | `adp-web` | Adapta.org (Adapta One Web) | Web cookie | [link](https://agent.adapta.one) | Paste your __client cookie value from .clerk.agent.adapta.one (DevTools → Application → Cookies) | emulated |
| `adobe-firefly` | `firefly` | Adobe Firefly (Image/Video) | Web cookie | [link](https://firefly.adobe.com) | RECOMMENDED: firefly.adobe.com signed-in → F12 → Network → click firefly-3p.ff.adobe.io (generate-async or models/discovery) → Request Headers → Authorization → copy the token AFTER 'Bearer ' (starts with eyJ…). Cookie-only from firefly.adobe.com mints a GUEST token → 401/403; only multi-domain IMS cookies (adobelogin.com) or that Bearer JWT work. Unofficial/experimental media + Limits. | — |
| `blackbox-web` | `bb-web` | Blackbox Web (Subscription) | Web cookie | [link](https://app.blackbox.ai) | Paste your __Secure-authjs.session-token value or full cookie header from app.blackbox.ai | emulated |
| `chatgpt-web` | `cgpt-web` | ChatGPT Web (Plus/Pro) | Web cookie | [link](https://chatgpt.com) | Paste your __Secure-next-auth.session-token cookie value from chatgpt.com | emulated |
| `chatgpt-web-codex` | `cgpt-codex` | ChatGPT Web (Codex) | Web cookie | [link](https://chatgpt.com) | Paste the full ChatGPT Cookie header. OmniRoute verifies it in an isolated headless browser profile. | native |
| `claude-web` | `cw` | Claude Web | Web cookie | [link](https://claude.ai) | Paste your session cookie from claude.ai | none |
| `conol-web` | `cnl` | Conol (Unofficial/Experimental) | Web cookie | [link](https://conol.ai) | Use browser sign-in, or paste the full Cookie header from conol.ai. The __Secure-better-auth.session_token cookie is required. | — |

8
docs/screenshots/free-tier-budget-card.svg
View File

@@ -1,10 +1,10 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 566" role="img" aria-label="OmniRoute free-tier dashboard preview: about 1.51 billion documented recurring tokens per month and about 2.13 billion in the first month. The audited catalog has 40 recurring pool keys and 455 entries, 448 active and 7 discontinued; the chart represents the 20 pools with a published positive monthly token budget. One-time signup credits total about 626 million and include a 10 million LongCat grant that requires KYC. Uncapped providers remain subject to rate, concurrency, account, regional, and policy limits." font-family="-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 566" role="img" aria-label="OmniRoute free-tier dashboard preview: about 1.51 billion documented recurring tokens per month and about 2.13 billion in the first month. The audited catalog has 40 recurring pool keys and 454 entries, 447 active and 7 discontinued; the chart represents the 20 pools with a published positive monthly token budget. One-time signup credits total about 626 million and include a 10 million LongCat grant that requires KYC. Uncapped providers remain subject to rate, concurrency, account, regional, and policy limits." font-family="-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif">
<desc>Static dashboard preview of recurring token pools, first-month signup grants, and uncapped but rate-limited free-access providers.</desc>
<rect width="900" height="566" rx="16" fill="#0d1117"/>
<rect x="16" y="16" width="868" height="550" rx="13" fill="#161b22" stroke="#30363d"/>
<text x="868" y="558" fill="#484f58" font-size="10.5" text-anchor="end">OmniRoute · /dashboard/free-tiers · preview mockup</text>
<text x="32" y="50" fill="#e6edf3" font-size="18" font-weight="700">Monthly free-token budget</text>
<text x="868" y="50" fill="#7d8590" font-size="13" text-anchor="end">40 recurring pools · 455 catalog entries · one endpoint</text>
<text x="868" y="50" fill="#7d8590" font-size="13" text-anchor="end">40 recurring pools · 454 catalog entries · one endpoint</text>
<text x="32" y="84" fill="#7d8590" font-size="11.5">Steady / month</text>
<text x="32" y="114" fill="#e6edf3" font-size="27" font-weight="800">~1.51B</text>
<text x="330" y="84" fill="#7d8590" font-size="11.5">First month (+ signup credits)</text>
@@ -34,7 +34,7 @@
<rect x="855.7" y="132" width="5.7" height="16" fill="#fdcb6e"/>
<rect x="862.3" y="132" width="5.7" height="16" fill="#e84393"/>
</g>
<text x="32" y="172" fill="#7d8590" font-size="12">Each segment = one of 20 quantified recurring pools · 40 pools / 455 entries in the audited catalog.</text>
<text x="32" y="172" fill="#7d8590" font-size="12">Each segment = one of 20 quantified recurring pools · 40 pools / 454 entries in the audited catalog.</text>
<circle cx="37" cy="196" r="5" fill="#6c5ce7"/>
<text x="48" y="200" fill="#c9d1d9" font-size="12.5">Mistral <tspan fill="#7d8590">1.00B</tspan></text>
<circle cx="250" cy="196" r="5" fill="#00b894"/>
@@ -101,5 +101,5 @@
<text x="299" y="466" fill="#7ee787" font-size="11.5" text-anchor="middle">nscale 5M</text>
<rect x="32" y="492" width="836" height="34" rx="8" fill="#1c2230" stroke="#30363d"/>
<text x="46" y="506" fill="#7d8590" font-size="12">Pool-deduped, honest counting — no inflated rate-limit ceilings. Some terms suggest personal-use only; we flag them so you decide.</text>
<text x="46" y="520" fill="#7d8590" font-size="11.5">+ 14 recurring uncapped* providers (rate/concurrency-limited) · OpenRouter $10 → +24M/mo.</text>
<text x="46" y="520" fill="#7d8590" font-size="11.5">+ 13 recurring uncapped* providers (rate/concurrency-limited) · OpenRouter $10 → +24M/mo.</text>
</svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.9 KiB

After

Width:  |  Height:  |  Size: 8.9 KiB

2
docs/security/BAN_DETECTION.md
View File

@@ -87,7 +87,7 @@ OAuth/subscription scrapers. The resulting terminal state is per **connection**,
not per provider.
That said, the built-in _strings_ are oriented toward subscription/OAuth
providers with real ban risk (ChatGPT Web, Claude Web, Codex, Muse Spark,
providers with real ban risk (ChatGPT Web Codex, Claude Web, Codex, Muse Spark,
Antigravity). An API-key provider will only trip the detector if its error body
literally contains one of the substrings.

26
docs/security/STEALTH_GUIDE.md
View File

@@ -6,7 +6,7 @@ lastUpdated: 2026-06-28
# Stealth Guide
> **Source of truth:** `open-sse/utils/tlsClient.ts`, `open-sse/services/{chatgptTlsClient,claudeCodeCCH,claudeCodeFingerprint,claudeCodeObfuscation,claudeCodeCompatible}.ts`, `open-sse/config/cliFingerprints.ts`, `src/mitm/`
> **Source of truth:** `open-sse/utils/tlsClient.ts`, `open-sse/services/{claudeCodeCCH,claudeCodeFingerprint,claudeCodeObfuscation,claudeCodeCompatible}.ts`, `open-sse/config/cliFingerprints.ts`, `src/mitm/`
> **Last updated:** 2026-06-28 — v3.8.40
> **Audience:** Engineers maintaining provider-specific stealth integrations.
@@ -14,7 +14,7 @@ OmniRoute integrates with providers whose edges actively fingerprint non-officia
## Legal and Ethical Notice
Stealth features exist so OmniRoute can act as a compatibility layer between user-owned official accounts (Claude Code CLI, ChatGPT Desktop/Web, Antigravity, Cursor, etc.) and OmniRoute's unified API. They are **not** for evading fraud detection, sharing credentials, or violating provider Terms of Service. The maintainers expect operators to comply with the upstream ToS they signed when creating accounts.
Stealth features exist so OmniRoute can act as a compatibility layer between user-owned official accounts (Claude Code CLI, Codex, Antigravity, Cursor, etc.) and OmniRoute's unified API. They are **not** for evading fraud detection, sharing credentials, or violating provider Terms of Service. The maintainers expect operators to comply with the upstream ToS they signed when creating accounts.
---
@@ -29,20 +29,6 @@ Lazy-loaded `wreq-js` session that impersonates **Chrome 124 on macOS**. Used as
- Timeout: `TLS_CLIENT_TIMEOUT_MS` (inherits from `FETCH_TIMEOUT_MS`, default 600000)
- `wreq-js` Response is fetch-compatible (`headers`, `text()`, `json()`, `clone()`, `body`).
### `open-sse/services/chatgptTlsClient.ts` — tls-client-node (Firefox 148)
Dedicated TLS impersonator for `chatgpt.com`. ChatGPT's Cloudflare config pins `cf_clearance` to JA3/JA4 + HTTP/2 SETTINGS frame ordering — undici's handshake gets `cf-mitigated: challenge` even with valid cookies.
- Profile: `firefox_148` (must match the Firefox 148 `User-Agent` sent)
- Mode: `runtimeMode: "native"` (koffi-loaded shared library; avoids managed sidecar HTTP)
- `withRandomTLSExtensionOrder: true`
- `tlsFetchChatGpt(url, options)` supports streaming (writes body to temp file, tailed as `ReadableStream`)
- Hang detection: `raceWithTimeout` + `TlsClientHangError` triggers `resetClientCache()` so the next call respawns the binding
- Proxy resolution (priority): per-call `proxyUrl` → `OMNIROUTE_TLS_PROXY_URL` → `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` (the native binding does **not** read these envs itself; it must be threaded through)
- Errors: `TlsClientUnavailableError` (binary missing), `TlsClientHangError` (binding deadlocked)
---
## Claude Code Stealth Bundle
When `cliCompatMode` is on, OmniRoute reshapes outgoing Claude requests so they are indistinguishable from `claude-cli` traffic. Three modules collaborate:
@@ -253,17 +239,17 @@ OmniRoute scrubs inbound client headers before forwarding so a request that arri
2. Extract JA3/JA4 and the literal header order
3. Update the relevant `CLI_FINGERPRINTS[...]` entry
4. Bump matching `*_USER_AGENT` default in `.env.example`
5. If TLS handshake itself changed: update `chatgptTlsClient.ts::CHATGPT_PROFILE` or wreq-js `browser:` option
6. Run `chatgptTlsClient.test.ts` and a manual canary against the live provider
5. If the TLS handshake itself changed, update the relevant provider wrapper or the wreq-js `browser:` option
6. Run the provider-specific TLS tests and a manual canary against the live provider
7. Ship in a patch release; document in `CHANGELOG.md`
---
## Tests
- `open-sse/services/__tests__/chatgptTlsClient.test.ts` — proxy resolution priority, abort handling, hang recovery
- `open-sse/services/__tests__/claudeTlsClient.test.ts` — shared TLS wrapper behavior
- `tests/unit/anthropic-cache-fingerprint.test.ts` — fingerprint determinism
- `tests/unit/chatgpt-web.test.ts` — end-to-end stealth path for ChatGPT
- `tests/unit/chatgpt-web-source-retirement.test.ts` — common ChatGPT Web stealth source remains absent while Codex Web stays present
---