convez.ai
AgenteDevOps & InfraestruturaAvançado
dengmengmian

AgentGate — Gateway Local para Agentes de IA

dengmengmian/agentgate-ai

Gateway inteligente local para agentes de código com failover e rastreamento de custos

Ver no GitHub
BomPluginScore · de 0 a 100

Gateway local em Rust que redireciona requisições de agentes de código (Codex, Claude Code, Gemini CLI) para 25 provedores diferentes, automatizando failover, conversão de protocolos e rastreamento de custos em tempo real. Permite rodar agentes em modelos mais baratos sem quebrar funcionalidades, com dashboard de despesas integrado.

Instalação

$npx convez-ai dengmengmian/agentgate-ai

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
36
Forks
3
Acompanhando
2
Saúde
71%
Último commit
há 5 dias
Versão
v2.0.12
Issues abertas
6
Contribuidores
1

Casos de uso

  • Reduzir custos ao rodar Codex e Claude Code em modelos alternativos baratos (DeepSeek, MiMo)
  • Centralizar roteamento inteligente entre 25 provedores com conversão automática de protocolos
  • Monitorar e rastrear despesas de IA por modelo, cliente e rota em dashboard em tempo real

Veredito

Solução robusta e bem pensada para um problema real: compatibilizar agentes proprietários com múltiplos provedores de API. A implementação em Rust garante performance, mas exige familiaridade com configuração de gateways e integração com agentes como Codex. Recomendado para times que buscam otimização de custos em larga escala.

README

A tradução para o português deste README ainda está na fila.


AgentGate is a local model gateway for AI coding agents. It gives Codex, Claude Code, Gemini CLI, OpenCode, and AtomCode one local endpoint, then routes requests to 25 providers including Xiaomi MiMo, DeepSeek, OpenAI, Anthropic, Kimi, GLM, DashScope, SiliconFlow, Volcengine, and more.

Run your coding agents on cheaper models — and watch the spend drop in real time. Point Codex / Claude Code / Gemini CLI at DeepSeek, MiMo, GLM, or Kimi, and the cost dashboard shows exactly what you spend, broken down by model, client, and route.

Cost dashboard

AgentGate is more than a proxy — it's an intelligent gateway built on three pillars:

🧠 Smart Routing🔁 Self-Healing💰 Cost Dashboard
Pick the right model per request — by capability (vision / tools / reasoning), by price, or by latencyAutomatic failover, circuit breaker, and cooldown keep requests flowing when a provider rate-limits or diesPer-request cost tracking, with breakdowns by model, client, and route over a time range

It is built for real integration problems:

  • Codex speaks the Responses API, while many providers only expose Chat Completions or Anthropic-compatible Messages.
  • Codex Desktop plugin and account features expect the official OpenAI-authenticated provider path; many third-party API proxies break that shape.
  • Claude Code can directly use DeepSeek / MiMo Anthropic-compatible endpoints, but base URLs, model names, and mapping rules are easy to misconfigure.
  • Different models from the same provider have different capabilities; sending images, tools, or web_search to the wrong model often causes 400 errors.
  • Multiple providers and multiple API keys should fail over automatically, with request logs, token stats, and cost tracking.
  • Switching models should not mean hand-editing ~/.codex/config.toml or ~/.claude/settings.json.

AgentGate's job is: one local gateway + protocol conversion + native pass-through + smart routing + GUI configuration — and ⚡ zero hand-editing: one-click apply / restore for your coding agents, no more poking at config.toml / settings.json.

How It Compares

There are great LLM proxies out there. AgentGate's niche is coding agents on the desktop — it's the only one focused on keeping Codex / Claude Code / Gemini CLI happy with a GUI, not a server you operate.

ToolWhat it's best atHow AgentGate differs
Plain proxySwapping a base URLKeeps Codex / ChatGPT login + plugins working, converts protocols, and routes by capability
claude-code-routerRouting Claude Code (CLI) to other modelsAlso covers Codex Responses API, Gemini CLI, OpenCode — plus a GUI and cost dashboard
one-api / new-apiMulti-user API reselling & billing on a serverLocal-first, single-user, no account system; one-click client config built in
LiteLLMA Python SDK / proxy for 100+ LLMs in your own appA desktop gateway for coding agents, not a library — zero code, GUI-driven

Positioning is approximate and these tools evolve fast — pick what fits your workflow. If you operate a shared API server, one-api / LiteLLM may suit you better; if you live in Codex / Claude Code, this is built for you.

Common Use Cases

Guides: Use Codex Desktop with third-party APIs and plugins · Use Codex with DeepSeek · Use Codex with Xiaomi MiMo

GoalWhat AgentGate does
Use Codex with DeepSeekConverts Codex's OpenAI Responses API requests to DeepSeek-compatible Chat Completions or Anthropic-compatible endpoints.
Use Codex with Xiaomi MiMoRoutes Codex through a local gateway to MiMo models with model mapping, reasoning support, and capability checks.
Use Codex Desktop plugins with third-party APIsKeeps Codex Desktop on its official OpenAI-authenticated provider path so plugin and account features can keep working while model requests route through AgentGate.
Use Claude Code with DeepSeek / MiMoUses Anthropic-compatible pass-through plus model mapping for DeepSeek and MiMo endpoints.
Switch Codex between providersOne local endpoint lets Codex switch between DeepSeek, MiMo, OpenAI, Kimi, GLM, DashScope, and more without hand-editing config files.

5-Minute Quick Start

  1. Download AgentGate from Releases and install it.
  2. Open the app, go to Quick Setup or Providers, and paste your provider API key.
  3. AgentGate detects known key prefixes and fills base URL, protocols, default model, and capability matrix. If the prefix is ambiguous, select the provider type manually.
  4. On Overview or Gateway, click Start Gateway. The default address is 127.0.0.1:9090. Note: 1420 is the development UI port, not the client API gateway.
  5. On Clients, click Apply Config for Codex / Claude Code / OpenCode / Gemini CLI / AtomCode.
  6. Send a test message in the client. Click Switch to Official whenever you want to restore the original client config.

Most users only need these steps. Model mapping, protocol endpoints, and capability matrices can be left alone at first; AgentGate fills the common defaults for you.

Three Modes

ModeWhen it happensModel handlingTypical case
Protocol ConversionClient protocol differs from upstream protocolModel Mapping wins; otherwise provider default model is used as a compatibility fallbackCodex Responses → DeepSeek / MiMo Chat
Native Pass-throughClient protocol matches a native upstream endpointRequest model is preserved unless a Model Mapping matches; the virtual agentgate model resolves to the model selected by routingOpenCode / curl → Chat Completions
Pass-through + Model MappingProtocol matches, but client model names differ from upstream namesModel Mapping rewrites modelClaude Code claude-* → DeepSeek / MiMo model

Rule of thumb: protocol match decides pass-through vs conversion; Model Mapping only renames models. For one-click client integrations, agentgate is a virtual model name that means "let AgentGate pick the provider model for this request."

Features

Protocol Conversion — 4 formats, bidirectional

  • OpenAI Responses API (/v1/responses) → Chat Completions / Claude Messages / Gemini API, for Codex
  • Anthropic Messages API (/v1/messages) → Chat Completions conversion / Anthropic pass-through, for Claude Code
  • Google Gemini API (/v1beta/models/:model:generateContent) → Chat Completions conversion, for Gemini CLI
  • Chat Completions (/v1/chat/completions) pass-through forwarding
  • Native Anthropic Claude API: tool_use/tool_result, input_schema, thinking.budget_tokens
  • Native Gemini API: contents/functionCall/functionResponse, generationConfig
  • Full DeepSeek reasoning_content (thinking mode) support without degradation
  • Automatic request retry (429/5xx, exponential backoff, Retry-After)

Cost Tracking & Multi-Key Pooling

  • 22+ built-in model prices, auto-calculate cost per request
  • Dashboard: total/today/average cost cards, plus cost breakdown by model, by client, and by route, scoped to a time range (7/30 days)
  • Settings: inline price editing, custom price overrides
  • Multi-API-key per provider: round-robin rotation, auto-switch on 429

Smart Routing

  • Task-level routing conditions: route by input size, images, tools, system keywords
  • Failover selection strategy per route: priority (default) / cheapest (by model unit price) / fastest (by recent gateway latency)
  • Preset scenes: Image Requests / Reasoning / Background / Long Text / Tool-Heavy
  • Prompt cache injection for Anthropic (auto cache_control, ~90% input cost savings)
  • Cache support auto-detection on provider test

Gateway Refiner Layer (opt-in, off by default)

  • By default the gateway forwards requests/responses byte-for-byte; nothing is rewritten until you opt in
  • Three independent refiners, each behind a global master switch in Settings, with a per-provider override that can force-off (never force-on):
    • Request field filter — strips request fields a provider rejects, based on its quirks, to avoid 400s
    • Reasoning param correction — normalizes thinking.budget_tokens / reasoning.effort to the provider's accepted shape and range
    • Error response normalization — rewrites upstream error bodies into the shape the client (Codex / Claude Code / Gemini CLI) expects
  • Provider quirks come from built-in defaults, overridable per provider; every refiner action is recorded in the request log's trace_json

Multimodal Support & Per-Model Capability Matrix

  • Image content is fully preserved during protocol conversion (input_image/image_url → Chat Completions image_url, Anthropic image source format)
  • Per-model capability matrix tracks 8 dimensions per model: text / vision / audio_in / tts / video_in / reasoning / tools / web_search
  • Capability-aware promotion: when a request includes images, the gateway auto-swaps to a sibling model that supports vision (e.g. routes image requests to mimo-v2.5 instead of mimo-v2.5-pro on the same provider)
  • Promotion ranking prefers the substitute that preserves the most of the original model's other capabilities, with supported_models order as tiebreak
  • The capability matrix also drives tool emission: unchecking web_search for a model stops the gateway from sending the builtin to that model
  • Matrix auto-seeded from model-name patterns: built-in rules for MiMo / DeepSeek / Kimi / Moonshot, with a generic fallback for others
  • Provider test button now combines connectivity check + non-destructive matrix autofill (preserves manual edits)
  • In failover mode, requests with images skip providers whose matrix declares no vision-capable model
  • Providers that don't support images at the chosen model strip the image content at the provider-specific layer, avoiding upstream 400/404

Multi-Provider Management

  • 25 built-in presets (auto-fill base URL / protocols / Anthropic endpoint / default model):
    • Domestic: Xiaomi MiMo, DeepSeek, Kimi/Moonshot, MiniMax, GLM (Zhipu BigModel), DashScope (Aliyun Qwen), SiliconFlow, Volcengine (Doubao), Baichuan, StepFun, SenseNova, ModelScope, Yi (01.AI)
    • International: OpenAI, Anthropic (Claude), Google Gemini, xAI (Grok), Mistral, Groq, Together, Fireworks, Cerebras, Perplexity, Cohere
    • Aggregator: OpenRouter
    • Custom: any OpenAI-compatible endpoint (vLLM / Ollama / LiteLLM / local proxies)
  • MiMo first-class support: 5 chat models (mimo-v2.5-pro / mimo-v2-pro / mimo-v2.5 / mimo-v2-omni / mimo-v2-flash), multi-turn reasoning_content round-trip, sk-* / tp-* keys auto-route to the correct Open API or Token Plan host, region-aware Token Plan URLs (cn / sgp / ams), and automatic web_search degradation when the paid plugin is unavailable
  • Claude Code passthrough for MiMo / DeepSeek uses ordinary provider model IDs by default; AgentGate no longer auto-configures [1m] suffixed models.
  • Route Profiles with multi-provider priority chains, auto-matched by protocol
  • Manual switching or automatic failover
  • Provider cooldown and runtime status tracking
  • Per-request failover: Provider A fails → automatically tries Provider B
  • Capability-aware routing: requests with images / audio / etc. auto-route to capable models within a provider, fall back to capable providers across the chain
  • New providers are automatically added to all route chains
  • Automatic model list fetching from providers
  • Connection stability: HTTP client tuned with pool_idle_timeout and tcp_keepalive, plus app-layer retry on transient connect/timeout errors (avoids stale keep-alive failures after a pause)

Client Configuration

  • Codex: one-click config + toggle between official and AgentGate (preserves conversations)
  • Codex Desktop compatibility: routes model requests to third-party APIs while preserving the official OpenAI provider path, signed-in account state, and plugin/account feature compatibility
  • Claude Code: one-click config + toggle between official and AgentGate
  • OpenCode: one-click config
  • Claude Desktop (macOS): point its third-party inference gateway at AgentGate; one-click apply with history rollback
  • Global instruction files: edit ~/.claude/CLAUDE.md / ~/.codex/AGENTS.md from inside AgentGate with 6 built-in templates grouped by purpose (general / coding / review / debug / security / docs); overwrite or append, with auto-snapshot, one-click rollback, and JSON backup/restore
  • MCP servers: read, add, edit, delete, and sync MCP server configs across Codex and Claude Code from one panel; env values are never shown in the list; JSON import/export with keys excluded by default
  • Local skills: list, enable/disable, and delete skills under ~/.claude/skills and ~/.codex/skills; install from a local .zip (zip-slip guarded, no network download) and JSON backup/restore
  • Local gateway access token (ag_local_*) authentication

Desktop Experience

  • System tray background operation when the window is closed
  • Auto-start on system boot, in-app updates, bilingual UI, 8 built-in themes
  • Optional desktop pet for gateway status, request stats, and error bubbles; it can be disabled in Settings

Quick Setup & Diagnostics

  • First-run onboarding: paste API key → auto-detect provider → select tools → one-click setup
  • Quick-add provider: paste an API key; known prefixes are detected automatically, ambiguous prefixes can be selected manually
  • Connection test: 3-step status bar (Config → Gateway → Provider) on the Clients page
  • Quick Setup page in sidebar (auto-hidden after providers configured, re-enable in Settings)

Diagnostics & Observability

  • Request logs, token stats, cost estimates, and provider runtime status
  • Provider failure state visible on cards: cooldown / consecutive failures / quota exhausted, with one-click reset
  • Active health probing (optional, off by default): periodic 1-token probe per provider, shown on the card — display-only, never affects routing
  • Self-check and redacted diagnostic bundle export
  • Capability degradation events: image stripping, web_search downgrade, MCP advisory, and omitted tool-output images

Screenshots

OverviewProviders
OverviewProviders
RoutesGateway
RoutesGateway
ClientsLogs
ClientsLogs
DiagnosticsSettings
DiagnosticsSettings
Global InstructionsMCP Servers
Global InstructionsMCP Servers
SkillsQuick Setup
SkillsQuick Setup
Pet SettingsDesktop Pet
Pet SettingsPet

Tech Stack

LayerTechnology
Desktop FrameworkTauri v2
FrontendReact 19 + TypeScript + Tailwind CSS v4
BackendRust + Tokio + Axum
DatabaseSQLite (rusqlite, WAL mode)
HTTP Clientreqwest

Installation & Build

Download

Download the installer for your platform from the Releases page.

PlatformFormat
macOS (Apple Silicon).dmg (aarch64)
macOS (Intel).dmg (x86_64)
Windows.exe
Linux.AppImage / .deb

If macOS Gatekeeper blocks the app, use one of these options:

Option 1: System Settings (recommended)

  1. Double-click AgentGate, click Cancel on the prompt
  2. Open System Settings → Privacy & Security
  3. Scroll down, find "AgentGate" was blocked → click Open Anyway
  4. Open AgentGate again, click Open

Option 2: Right-click open

  1. Find AgentGate.app in Finder
  2. Hold Control and click (or right-click) → select Open
  3. Click Open on the prompt

Option 3: Terminal

xattr -d com.apple.quarantine /Applications/AgentGate.app

Only needed once.

On first run, SmartScreen may show a warning:

  1. Click More info
  2. Click Run anyway

Only needed once.

Build from Source

Prerequisites

  • Node.js >= 20
  • pnpm >= 10
  • Rust >= 1.75
  • macOS / Windows / Linux

Install Dependencies

pnpm install

Development Mode

pnpm tauri dev

Build

pnpm tauri build

Headless / Server Mode

Run AgentGate without GUI — for servers, CI, Docker, and team deployments.

# Add a provider
agentgate-serve provider-add -t deepseek -k sk-xxx

# Start the gateway
agentgate-serve serve --host 0.0.0.0 --port 9090

# Other commands
agentgate-serve provider-list          # list all providers
agentgate-serve provider-remove NAME   # remove provider
agentgate-serve token                  # show access token
agentgate-serve status                 # show config summary

Provider presets auto-fill base URL and model for: deepseek, openai, anthropic, kimi, minimax, groq, together, google_gemini, xai, mistral.

Docker:

docker compose up
# or
docker build -t agentgate . && docker run -p 9090:9090 \
  -e AGENTGATE_PROVIDER=deepseek -e AGENTGATE_API_KEY=sk-xxx agentgate

Environment variables: AGENTGATE_HOST, AGENTGATE_PORT, AGENTGATE_DB_PATH, AGENTGATE_PROVIDER, AGENTGATE_API_KEY.

Usage Guide

Most users only need the 5-Minute Quick Start above. Expand for the full reference.

1. Add a Provider

Launch AgentGate → Providers → Add Provider

Fast path (recommended) — paste API key:

  1. Paste your provider API key into the top input
  2. AgentGate detects known key prefixes (sk-ant- / deepseek- / gsk_ / …). If the prefix is ambiguous, select the provider type manually
  3. Click Create — name, base URL, protocols, default/reasoning model, capabilities are all filled in for you. Done.

Manual mode — 3 sections, only Section A is required:

SectionFieldsNotes
BasicType · Name · API Key (+ Base URL only if custom type)Picking a type auto-fills everything else from the preset
Models & CapabilitiesDefault model · Reasoning model · Fetch & detect button · capability matrix toggleOn a freshly created provider, this is auto-run in the background — you get newest non-mini model as default + newest reasoning model + per-model capability matrix without clicking anything
Advanced (collapsed, "usually no need to touch")Protocols + their endpoints (Chat / Responses / Anthropic) · Extra Headers · Timeout · Auto cache control · Model MappingEach protocol you tick shows its own URL — one place to read "which native endpoints this upstream supports"

Model Mapping is at the bottom of Advanced for a reason: usually not needed. AgentGate auto-fills recommended MiMo / DeepSeek mappings when you create the provider, fetch models, test the provider, or apply Codex / Claude Code config. Existing mappings are preserved. Native pass-through keeps model unchanged unless a mapping matches or the client sends the virtual agentgate model; protocol conversion uses mapping first, then falls back to default_model for compatibility with clients like Codex, Claude Code, and Gemini CLI.

Provider configuration examples:

FieldValue
NameDeepSeek
Typedeepseek
Base URLhttps://api.deepseek.com
Default Modeldeepseek-v4-flash
Reasoning Modeldeepseek-v4-pro
Model Mappinggpt-5.5 → deepseek-v4-flash, o3 → deepseek-v4-pro
Anthropic Endpointhttps://api.deepseek.com/anthropic (supports Claude Code pass-through)
FieldValue
NameKimiCoding
Typekimi
Base URLhttps://api.moonshot.cn
Default Modelkimi-k2
Extra Headers{"User-Agent":"KimiCLI/1.40.0"}
Model Mappinggpt-5.5 → kimi-k2

KimiCoding supports Vision and can serve as a failover target for image requests.

FieldValue
NameOpenAI
Typeopenai
Base URLhttps://api.openai.com
Default Modelgpt-4o
Responses API Endpointhttps://api.openai.com (OpenAI natively supports Responses API, uses pass-through)
Model MappingUsually not needed (client model names used directly)
FieldValue
NameAnthropic
Typeanthropic
Base URLhttps://api.anthropic.com
Default Modelclaude-sonnet-4-6
Model Mappinggpt-5.5 → claude-sonnet-4-6

When type is set to Anthropic (Claude), Codex requests are automatically converted using Claude Messages API native format (tool_use/tool_result/input_schema), rather than being converted to Chat Completions.

FieldValue
NameMiniMax
Typeminimax
Base URLhttps://api.minimax.chat
Default ModelMiniMax-M1
Model Mappinggpt-5.5 → MiniMax-M1
FieldValue
NameOpenRouter
Typeopenrouter
Base URLhttps://openrouter.ai/api
Default Modeldeepseek/deepseek-v4-flash
Model Mappinggpt-5.5 → deepseek/deepseek-v4-flash
FieldValue
NameYour custom name
Typecustom_openai_compatible
Base URLYour server URL, e.g., http://localhost:8000
Default ModelYour model name

Works with any OpenAI Chat Completions API-compatible service (e.g., vLLM, Ollama, LiteLLM).

After saving:

  • Fetch + capability detection runs automatically in the background — no manual action needed
  • Click Test Connection to verify the config — it opens a single dialog with 3 live steps: Connectivity & auth → Capability autofill → Prompt cache detection (auto-skipped for non-Anthropic providers)

2. Start the Gateway

Overview or Gateway page → Start Gateway

Listens on 127.0.0.1:9090 by default.

3. Configure Codex

Clients → Codex → Apply Config

AgentGate will automatically:

  • Save original ~/.codex/config.toml and auth.json
  • Write AgentGate provider settings and local token

Click Switch to Official to restore the original config at any time — conversations are preserved.

4. Configure Claude Code

Clients → Claude Code → Apply Config

AgentGate writes to ~/.claude/settings.json, setting ANTHROPIC_BASE_URL to the local gateway and ANTHROPIC_API_KEY to the AgentGate local token.

Click Switch to Official to restore the original settings.json.

5. Configure OpenCode

Clients → OpenCode → Apply Config

AgentGate writes to ~/.config/opencode/opencode.json, configuring an OpenAI-compatible provider pointing to the local gateway. It uses openai/agentgate as a virtual model so switching providers in AgentGate does not require editing OpenCode again.

6. Configure Gemini CLI

Clients → Gemini CLI → Apply Config

AgentGate writes Gemini CLI's config to point at the local gateway's /v1beta/... route (Gemini-compatible). One-click toggle back to official.

7. Configure AtomCode

Clients → AtomCode → Apply Config

AtomCode integration writes its config to use AgentGate as the upstream — same toggle pattern as the others. It uses agentgate as a virtual model so the gateway can resolve DeepSeek / MiMo / other provider model names at request time.

8. Direct API Calls

All endpoints (except /health) require a local access token.

Getting the token:

  • Copy from UI: AgentGate → Settings → Gateway Auth → click the copy button next to the token
  • Read from terminal:
    TOKEN=$(cat ~/.agentgate/token)
    
  • Regenerate: Settings → Regenerate Token (old token is immediately invalidated)

The token format is ag_local_*. It is only used for local gateway auth and is never forwarded to upstream providers.

Chat Completions (Pass-through)

curl -X POST http://127.0.0.1:9090/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Hello"}]}'

Responses API (Codex Protocol)

curl -X POST http://127.0.0.1:9090/v1/responses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","input":"Hello","stream":true}'

Messages API (Claude Code Protocol)

curl -X POST http://127.0.0.1:9090/v1/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'

Model List

curl http://127.0.0.1:9090/v1/models -H "Authorization: Bearer $TOKEN"

Health Check (No Auth Required)

curl http://127.0.0.1:9090/health

Client says “network connection failed”?

First check whether the gateway port is actually running:

curl http://127.0.0.1:9090/health
  • If the connection fails: go back to AgentGate Overview / Gateway / Clients and click Start Gateway.
  • If health works: use the Clients page connection test to narrow it down: Config → Gateway → Provider.
  • http://localhost:1420 is only the development UI; Codex / Claude Code / OpenCode / Gemini CLI / AtomCode call http://127.0.0.1:9090.

9. Multi-Provider & Failover

Configure Route Profiles on the Routes page:

  1. Default routes are auto-created per protocol (Codex / Claude Code / OpenCode)
  2. Add multiple providers to the provider chain, adjust priorities
  3. Switch mode: manual / failover
  4. In failover mode, 429/402/5xx/timeout errors automatically try the next provider

10. Capability-Aware Routing (Multimodal & Reasoning)

AgentGate tracks per-model capabilities across 8 dimensions and uses them for routing — when your request contains images / audio / tools, the gateway picks a model that actually supports it.

Capability matrix per model:

text · vision · audio_in · tts · video_in · reasoning · tools · web_search

Setup:

  1. Add a provider — model list, capabilities, and best default/reasoning model are detected automatically right after creation
  2. On the Providers page, the card shows capability icons + native pass-through chips (Native Chat, Native Anthropic, …)
  3. To re-detect manually: open Edit → click Fetch & detect capabilities
  4. On the Routes page, switch mode to failover

How it works:

  • After provider creation: gateway calls upstream /models, runs name-pattern seeding for capabilities, picks newest non-mini model as default and newest reasoning-style model as reasoning_model
  • When a request includes images, the gateway:
    • First tries to swap to a sibling model on the same provider that supports vision (e.g., mimo-v2.5-pro → mimo-v2.5 for images)
    • If no sibling on the current provider, failover to next provider in the chain whose matrix declares a vision-capable model
  • Capability matrix also gates tool emission — unchecking web_search for a model stops the gateway from sending the web_search builtin to that model
  • Promotion picker prefers the candidate that preserves the most of the original model's other capabilities; supported_models order is the tiebreak
  • Providers without any vision-capable model strip image content at the provider transform layer, avoiding upstream 400/404 on text-only fallback

Example scenario:

Codex sends a request with images
  → Gateway sees request has images
  → MiMo's matrix: mimo-v2.5-pro = text, mimo-v2.5 = text + vision
  → Promote mimo-v2.5-pro → mimo-v2.5 (same provider, capability match)
  → Request goes through, full image + text preserved

11. Diagnostics

On the Diagnostics page:

  • Run Self-Check — checks gateway, provider, config, and database status
  • Export Diagnostic Bundle — generates a redacted diagnostic report for troubleshooting
  • Request log trace_json includes degradation_events when AgentGate strips unsupported capabilities such as images, native web search, MCP connectors, or tool-output images.

Supported Providers

Providers marked Provider-specific handling have dedicated transform code in src-tauri/src/transform/providers/. The rest go through the generic Chat Completions / Anthropic pass-through path and work out-of-the-box.

ProviderTypeNative ProtocolsProvider-Specific Handling
Xiaomi MiMomimoChat + AnthropicMulti-turn reasoning_content round-trip, region-aware tp-* host auto-routing, temperature strip in thinking mode, tool_choice non-auto strip, omni web_search strip, web_search builtin gated by matrix, Web Search Plugin auto-degrade / retry
DeepSeekdeepseekChat + AnthropicImage stripping with explicit notice, DeepSeek V4 thinking history reasoning backfill, schema cleaning, message reordering
Anthropic (Claude)anthropicAnthropictool_use/tool_result, input_schema, thinking budget, native cache_control
OpenAIopenaiChat + ResponsesNone (Responses passthrough or Chat conversion)
Google Geminigoogle_geminiChatNone
Kimi / MoonshotkimiChatweb_search → builtin_function/$web_search, thinking control
MiniMaxminimaxChatStrip reasoning_effort / response_format, <think> extraction
GLM (Zhipu)glmChatGeneric
DashScope (Qwen)dashscopeChatGeneric
SiliconFlowsiliconflowChatGeneric
Volcengine (Doubao)volcengineChatGeneric
BaichuanbaichuanChatGeneric
StepFunstepfunChatGeneric
SenseNovasensenovaChatDrops null strict / response_format / non-function tools, merges system messages
Yi (01.AI)yiChatGeneric
ModelScopemodelscopeChatGeneric
xAI (Grok)xaiChatGeneric
MistralmistralChatGeneric
GroqgroqChatGeneric
TogethertogetherChatGeneric
FireworksfireworksChatGeneric
CerebrascerebrasChatGeneric
PerplexityperplexityChatGeneric
CoherecohereChatGeneric
OpenRouteropenrouterChatNone
Customcustom_openai_compatibleChatNone (set Base URL yourself)

Vision / reasoning / tools / web_search capability is tracked per-model in the capability matrix, not at the provider level. See Capability-Aware Routing below.

Architecture & Internals

Data Flow

AgentGate separates protocol handling from model naming. There are three common request modes:

How to tell? First check whether the client protocol matches a native provider endpoint. If it matches, the request is forwarded without protocol conversion. Model names are a separate concern: a matching Model Mapping can still rename model.

ClientSendsDownstream ProviderAgentGate ModeTrigger
CodexResponses APIChat CompletionsProtocol ConversionDefault (no special URL)
CodexResponses APIClaude Messages APIProtocol Conversionprovider_type is anthropic
CodexResponses APIResponses APINative Passthroughresponses_base_url is configured
Claude CodeMessages APIChat CompletionsProtocol ConversionNo anthropic_base_url
Claude CodeMessages APIAnthropic-compatible endpointNative Passthrough + Model Mappinganthropic_base_url is configured and claude-* maps to provider model
OpenCodeChat CompletionsChat CompletionsNative PassthroughSame protocol and upstream model name
curl / New API etc.Chat CompletionsChat CompletionsNative PassthroughSame protocol and upstream model name

Protocol Conversion

When the client protocol differs from the downstream provider, AgentGate converts the format. This is the most complex path, including vision-aware routing and provider-specific processing.

┌──────────────────┐    ┌──────────────────┐
│      Codex       │    │    Claude Code    │
│  (Responses API) │    │  (Messages API)   │
└────────┬─────────┘    └────────┬─────────┘
         │                       │
         ▼                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    AgentGate (127.0.0.1:9090)                           │
│                                                                         │
│  ① Auth: validate local token (ag_local_*)                              │
│                         ▼                                               │
│  ② Route Matching: match Route Profile by protocol                      │
│     /v1/responses → Codex Default                                       │
│     /v1/messages  → Claude Code Default                                 │
│                         ▼                                               │
│  ③ Protocol Conversion (shared layer)                                   │
│     Responses API → Chat Completions (input_image → image_url)          │
│     Messages API  → Chat Completions (image → image_url)                │
│                         ▼                                               │
│  ④ Capability-Aware Routing (failover mode)                             │
│     Has images → promote to vision sibling on same provider, or         │
│                  failover to next provider with a vision-capable model  │
│     No images  → select by priority as normal                           │
│                         ▼                                               │
│  ⑤ Provider-Specific Transform                                          │
│     DeepSeek   → strip images + reasoning_content + schema fix          │
│     KimiCoding → web_search conversion + thinking control               │
│     Anthropic  → convert to Claude Messages (image→source.base64)       │
│     Others     → send directly                                          │
│                         ▼                                               │
│  ⑥ Failover: 429/402/5xx/timeout → cooldown → try next provider        │
│                         ▼                                               │
│  ⑦ Logging → SQLite                                                    │
│                         ▼                                               │
│  ⑧ Response reverse-conversion: back to original protocol for client    │
└─────────┬───────────────────────────────┬───────────────────────────────┘
          │                               │
          ▼                               ▼
   ┌──────────────┐               ┌──────────────┐
   │   DeepSeek   │               │  KimiCoding  │  ...
   │  (text only) │               │ (text+image) │
   └──────────────┘               └──────────────┘

Native Passthrough

When the client protocol matches the downstream provider, AgentGate does not convert the request format. It replaces the URL and credentials. Model handling follows one rule: Model Mapping wins; otherwise the request model is preserved. If the request model is agentgate or openai/agentgate, AgentGate resolves it to the model selected by routing for that request. If the client omits model, AgentGate uses the provider default.

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│    Claude Code   │  │     OpenCode     │  │  curl / New API  │
│  (Messages API)  │  │(Chat Completions)│  │(Chat Completions)│
└────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘
         │                     │                      │
         ▼                     ▼                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    AgentGate (127.0.0.1:9090)                           │
│                                                                         │
│  ① Auth: validate local token (ag_local_*)                              │
│                         ▼                                               │
│  ② Route Matching: match Route Profile by protocol                      │
│     /v1/messages          → Claude Code Default                         │
│     /v1/chat/completions  → OpenCode Default                            │
│                         ▼                                               │
│  ③ Native Passthrough                                                   │
│     Replace target URL (base_url or anthropic_base_url)                 │
│     Inject provider API key                                             │
│     Optional model mapping (claude-* → mimo/deepseek model)             │
│     Forward request body as-is ──→ Proxy response stream as-is         │
│                         ▼                                               │
│  ④ Logging → SQLite                                                    │
└─────────┬───────────────┬───────────────────┬───────────────────────────┘
          │               │                   │
          ▼               ▼                   ▼
  ┌──────────────┐ ┌──────────────┐   ┌──────────────┐
  │  DeepSeek    │ │   OpenAI     │   │  New API     │  ...
  │  /anthropic  │ │              │   │  / aggregator│
  └──────────────┘ └──────────────┘   └──────────────┘

Trigger conditions:
  • /v1/messages    + Provider has anthropic_base_url → Messages API native passthrough
  • /v1/chat/completions → Chat Completions native passthrough (all providers)

Flow Examples

Codex with images (protocol conversion + vision-aware routing):

Codex sends input_image
  → /v1/responses (Responses API)
  → ① Auth passes
  → ② Matches Codex Default Route Profile
  → ③ Protocol conversion: input_image → image_url (image preserved)
  → ④ Vision routing: image detected → skip DeepSeek (No Vision) → select KimiCoding (Vision)
  → ⑤ KimiCoding transform: no image stripping, send directly
  → ⑥ KimiCoding returns success → mark healthy
  → ⑦ Log request
  → ⑧ Reverse-convert to Responses API format → return to Codex

Claude Code → DeepSeek (native passthrough + model mapping):

Claude Code sends Messages API request
  → /v1/messages
  → ① Auth passes
  → ② Matches Claude Code Default Route Profile
  → ③ DeepSeek has anthropic_base_url → native passthrough
  → Model Mapping: claude-sonnet-4-6 → deepseek-v4-pro
  → Replace URL with api.deepseek.com/anthropic + inject API key
  → Request body proxied as-is → SSE response stream proxied as-is
  → ④ Log request

OpenCode / curl / New API (native passthrough):

Client sends Chat Completions request
  → /v1/chat/completions
  → ① Auth passes
  → ② Matches Route Profile
  → ③ Native passthrough: replace URL + API key; model unchanged unless mapping matches
  → Request body forwarded as-is → SSE response stream proxied as-is
  → ④ Log request

Gateway Routes

MethodPathModeDescription
GET/healthinternalHealth check (no auth)
GET/v1/modelsinternalModel list
POST/v1/responsesautoresponses_base_url set → pass-through; Anthropic type → Claude conversion; otherwise → Chat Completions conversion
POST/v1/chat/completionspass-throughChat Completions direct
POST/v1/messagesautoanthropic_base_url set → pass-through; otherwise → Chat Completions conversion

Project Structure

AgentGate/
├── provider-catalog/             # Provider/model source of truth for generated defaults
├── src/                          # Frontend (React)
│   ├── app/App.tsx               # App entry point
│   ├── pages/                    # Pages (Overview/Quick Setup/Providers/Routes/Gateway/Clients/Logs/Diagnostics/Instructions/MCP/Skills/Settings)
│   ├── components/               # UI components (layout/common/dashboard/providers/logs/tools/onboarding)
│   ├── pet/                      # Desktop pet system (PetApp/Bubble/greetings/9 pet SVG components)
│   ├── lib/                      # API wrapper, i18n, utilities
│   └── types/                    # TypeScript type definitions
├── src-tauri/                    # Backend (Rust)
│   └── src/
│       ├── gateway/              # HTTP gateway (server/routes/SSE/SSE Anthropic/pass-through/failover)
│       ├── protocol/             # Protocol types (Responses/ChatCompletions/Messages/SSE events)
│       ├── transform/            # Protocol conversion (responses→chat/responses→anthropic/schema cleanup/tool_calls/reasoning store/providers)
│       ├── providers/            # Provider adapters
│       ├── storage/              # SQLite storage layer
│       ├── models/               # Data models
│       ├── tools/                # Client config + MCP / skills / global instructions management
│       ├── security/             # Authentication & redaction
│       ├── diagnostics/          # Diagnostics & self-checks
│       ├── app/                  # Tauri commands & app state
│       └── errors/               # Unified error types
├── scripts/                      # Test and generation scripts
└── package.json

Security

  • Gateway uses local token authentication by default
  • Provider API keys are stored only in local SQLite and never sent to clients
  • Client tokens are never forwarded to upstream providers
  • Logs and diagnostic bundles automatically redact sensitive information
  • Gateway binds only to 127.0.0.1 by default; 0.0.0.0 is rejected
  • Token file permissions set to 0600 (Unix)

FAQ

Are my API keys safe? Does AgentGate phone home? Keys live only in a local SQLite file on your machine and are never sent to clients or to any AgentGate server — there is no AgentGate backend. Your keys go only to the upstream provider you configured. The local gateway binds to 127.0.0.1 and rejects 0.0.0.0.

Will it break my Codex / ChatGPT login or Codex Desktop plugins? No. AgentGate keeps Codex on the official OpenAI-authenticated provider path, so your signed-in account, plugins, Browser / Computer-Use / Mobile and quota lookup keep working while chat requests route to third-party models. Switch to Official restores the original config at any time — conversations are preserved.

Can I run it offline / on a server without the GUI? Yes. Headless mode (agentgate-serve) and Docker run without a window — see Headless / Server Mode.

Do I have to edit config.toml / settings.json by hand? No. One-click Apply Config writes them for you and backs up the originals; Switch to Official rolls back.

A client says "network connection failed" — what now? First check the gateway is up: curl http://127.0.0.1:9090/health. If it fails, start the gateway from the app. Note localhost:1420 is only the dev UI — clients call 127.0.0.1:9090.

Which model does a request actually hit? Open Logs — every request shows the client, route, resolved provider, model, status, and cost.

Development

Provider Catalog

Built-in provider/model data is maintained in provider-catalog/providers/*.json. Run this after editing catalog files:

pnpm provider:catalog:generate
pnpm provider:catalog:check
pnpm provider:catalog:sync:check

provider:catalog:sync:check calls provider /models endpoints when the matching API key environment variable is present, and skips providers without credentials. It fails when a catalog model is no longer returned upstream; pass --strict to also fail on newly discovered upstream models. To refresh a provider explicitly, run:

pnpm provider:catalog:sync -- --provider deepseek --update
pnpm provider:catalog:generate

The generated TS/Rust files feed provider presets, endpoint defaults, capability seeds, pricing defaults, supported-model gates, and recommended mapping policy. Provider-specific runtime behavior still lives in code, not in the catalog.

Upstream model sync is intentionally a local maintenance step, not part of the GitHub release workflow. Release CI only checks that generated catalog artifacts are up to date.

Test Scripts

# Health check
./scripts/test-gateway-health.sh

# Auth test
./scripts/check-gateway-auth.sh

# Responses API test
./scripts/test-responses-stream.sh

# Chat Completions test
./scripts/test-chat-completions-pass-through.sh

Community & Support

  • 🐛 Found a bug or want a feature? Open an Issue — include a redacted diagnostic bundle (Diagnostics → Export) when reporting gateway problems.
  • 💡 Questions & ideas: Discussions.
  • ⭐ If AgentGate saves you money or time, a star helps others find it — and helps us prioritize what to build next.

The three pillars — smart routing, self-healing, and the cost dashboard — are shipped. What comes next is driven by Issues and Discussions, so tell us what you need.

Star History

License

MIT

Ver o original no GitHub

Bom para

Relacionados