Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

Eigene Anbieter und Gateway-Anbieter

Status: Aktiv Umfang: aktueller Stand Zuletzt geprüft: 2026-09-06 Verantwortlich: AX-Code-Laufzeit

AX Code spricht mit Modellen über Standardprotokolle der Anbieter. Jeder Endpunkt, der eine OpenAI-kompatible (/v1/chat/completions) oder Anthropic-kompatible (/v1/messages) API spricht, lässt sich als eigener Anbieter hinzufügen, indem Sie baseURL darauf richten — ohne Codeänderungen und ohne auf eine eingebaute Vorgabe zu warten.

Das umfasst selbst betriebene Aggregatoren und Relay-Gateways wie LiteLLM, one-api, new-api und das Vercel AI Gateway sowie private Unternehmensproxys und jeden anderen kompatiblen Dienst. AX Code behandelt sie einheitlich: Es spricht das Leitungsprotokoll, Sie liefern URL und Schlüssel.

Hinweis zur Verantwortung. Ein Gateway sitzt zwischen AX Code und dem Upstream-Modell, daher laufen Ihre Prompts, Ihr Code und Ihre Zugangsdaten darüber. Wenn Sie AX Code auf ein Relay eines Dritten oder ein kontobündelndes Relay richten, sind Sie dafür verantwortlich, diesem Betreiber Ihre Daten anzuvertrauen und die Nutzungsbedingungen jedes Upstream-Anbieters einzuhalten, an den es weiterleitet. Eingebaute Gateway-Vorgaben wie OpenRouter verwenden denselben Standardprotokollpfad. Eine eigene Gateway-Konfiguration bedeutet keine Empfehlung eines Relay-Betreibers.

Interaktive Einrichtung

Verwenden Sie /connect -> API-Cloud-Anbieter -> Eigener API-Anbieter für ein kompatibles Gateway oder /connect -> AX Trust -> AX Trust verbinden für ein AX-Trust-Gateway. Geben Sie seine Basis-URL (einschließlich /v1 für AX Trust) und den Client-API-Schlüssel ein. Der Editor entdeckt Modell-IDs und Metadaten und speichert Zugangsdaten in verschlüsseltem Auth-Speicher. Er kann auch ausdrückliche Modell-IDs annehmen, wenn die Entdeckung nicht verfügbar ist. Das erneute Verbinden einer gespeicherten URL behält Anbieter-ID und Schlüssel, wenn das Token leer bleibt. AX-Trust-Verbindungen behalten ihre Kategorie nach Bearbeitungen und Modellaktualisierungen. AX Code sendet X-AX-Prompt-Cache-Key mit der Sitzungs-ID auf diesen Verbindungen, damit das Gateway eine Sitzung auf einem geeigneten Konto halten kann. Setzen Sie provider.<id>.options.axTrust auf false, um das abzuschalten. Dieser Header wird nicht upstream weitergeleitet und ist kein Körper prompt_cache_key.

Verbundene AX-Trust-Anbieter aktualisieren ihre Modelllisten beim Start im Hintergrund. AX Code ruft GET /models des konfigurierten Endpunkts mit dem vorhandenen Zugangsdatum auf und aktualisiert Modellnamen, Grenzen für Kontext und Ausgabe, Schlussfolgern, Toolaufrufe, Temperaturunterstützung und Bildunterstützung. Bildfähige Modelle zeigen die Vision-Markierung in /models, einschließlich Gateway-Aliasen, wenn AX Trust ihre Bildunterstützung meldet. Die TUI aktualisiert sich, wenn die Entdeckung endet. Für genaue Modell-IDs von DeepSeek aus erster Hand werden fehlende Metadaten aus dem gebündelten Katalog models.dev gefüllt. Ausdrückliche Fähigkeitsflags und Grenzen des Gateways haben Vorrang. Unbekannte Aliase erben Fähigkeiten nicht über Namensähnlichkeit.

Eine erfolgreiche Aktualisierung ersetzt die Laufzeitliste, entfernt Modelle, die das Gateway nicht mehr meldet, und wendet konfigurierte Zulassungs- und Sperrlisten weiterhin an. Zeitüberschreitungen, Fehler sowie leere oder ungültige Antworten behalten die gespeicherte Liste und protokollieren einen Entdeckungsfehler. Der Start wartet nicht auf das Netzwerk. Diese Aktualisierung schreibt Anbieterkonfiguration oder Zugangsdaten nicht um. Die gespeicherte Konfiguration bleibt der Rückfall beim Start. Gewöhnliche eigene API-Anbieter behalten die manuelle Aktualisierung.

Wie ein Anbieter aufgelöst wird

Für jede Anfrage braucht AX Code drei Dinge aus einem Anbietereintrag:

npm — der Adapter des AI SDK, der das Leitungsprotokoll spricht. Verwenden Sie @ai-sdk/openai-compatible für Endpunkte im OpenAI-Stil und @ai-sdk/anthropic für Endpunkte im Anthropic-Stil. Nur Adapter @ai-sdk/* sind gebündelt oder installierbar.
options.baseURL — die Gateway-URL, die auf das Feld api des Anbieters zurückfällt und danach auf das eigene api.url des Modells. Die Ersetzung ${ENV_VAR} wird unterstützt.
Ein Zugangsdatum — aufgelöst der Reihe nach aus options.apiKey, dann dem dauerhaften Auth-Speicher, dann den Variablen env des Anbieters.

Die manuelle Konfiguration braucht außerdem eine ausdrückliche Zuordnung models. Der interaktive Editor füllt diese Zuordnung aus dem Endpunkt oder aus Modell-IDs, die Sie angeben.

Gewidmete private GPU-Clouds sind Anbieter erster Klasse unter /connect → Private GPU-Cloud. Fügen Sie die OpenAI-kompatible URL und das Token ein (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti oder custom-private-gpu). AX Code ruft GET …/models auf und verwendet die bereitgestellten Modell-IDs automatisch.

Gehostete GPU-Kataloge (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) verwenden einen API-Schlüssel und den gebündelten Modellschnappschuss, dasselbe Muster wie OpenCode.

OpenAI-kompatibles Gateway

Die meisten Aggregatoren (LiteLLM, one-api, new-api, kostenlose oder selbst betriebene Gateways) bieten eine OpenAI-kompatible Oberfläche. Fügen Sie dies zu Ihrem ax-code.json hinzu (global unter ~/.config/ax-code/ax-code.json oder je Projekt im Repository-Wurzelverzeichnis):

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

Der Schlüssel "my-gateway" ist die Anbieter-ID, die Sie in /connect und ax-code models wählen.
Jeder Schlüssel unter models ist die lokale Auswahl-ID. Setzen Sie id des Eintrags auf die genaue Modell-ID, die das Gateway erwartet, wenn sie von diesem Schlüssel abweicht. Andernfalls wird der Schlüssel für manuell erklärte Modelle ohne vorhandene Katalogzuordnung verwendet.
Bevorzugen Sie ${ENV_VAR} gegenüber einem literalen Schlüssel, damit das Geheimnis nicht in einer committeten Konfiguration steht.

Gateway-Modellaliase nach einem Endpunktwechsel

Das Ändern von options.baseURL übersetzt manuell konfigurierte Modell-IDs nicht. Zum Beispiel kann ein AX-Trust-Endpunkt deepseek-flash melden, während eine vorhandene lokale Auswahl ax-trust/deepseek-v4-flash ist. Behalten Sie den lokalen Schlüssel und setzen Sie provider.ax-trust.models.deepseek-v4-flash.id auf deepseek-flash. AX Code sendet dann die Gateway-ID in API-Anfragen.

Siehe das Konfigurationsbeispiel AX Trust DeepSeek Flash. Führen Sie die relevanten Anbieterfelder in Ihre vorhandene Konfiguration zusammen und bewahren Sie andere Modelle und ihre Fähigkeitseinstellungen. Das Beispiel verwendet {env:AX_TRUST_API_KEY}. Setzen Sie diese Umgebungsvariable, bevor Sie AX Code starten, oder behalten Sie Ihre vorhandene Zugangsdatenkonfiguration. Starten Sie AX Code nach der Bearbeitung neu.

Wenn Sie 403 model is not allowed untersuchen, vergleichen Sie die Modell-ID der Anfrage mit der authentifizierten Antwort GET /models des Endpunkts. Eine erfolgreiche Anfrage der Modellliste allein belegt keine Berechtigung, ein Modell auszuführen. Wenn die genaue ID weiterhin fehlschlägt, prüfen Sie die Schlüssel- und Modellberechtigungen des Gateways.

Anthropic-kompatibles Gateway

Relays, die /v1/messages bereitstellen (die Form der Claude-API), verwenden den Anthropic-Adapter:

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

Manche Relays in Anthropic-Form beachten auch die Claude-Umgebungsvariablen direkt. Für einen schnellen Headless-Lauf ohne Bearbeitung der Konfiguration können Sie setzen:

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

Ein Konfigurationseintrag bleibt empfehlenswert, wenn das Gateway als eigener wählbarer Anbieter mit einer gepflegten Modellliste erscheinen soll.

Modellfelder

Modelleinträge verwenden das Registerschema wieder. Für einen eigenen Endpunkt sind diese Felder nützlich:

Feld	Bedeutung
`name`	Anzeigename in der Modellauswahl
`tool_call`	Ob das Modell Tool- oder Funktionsaufrufe unterstützt (nötig für Tools)
`reasoning`	Ob das Modell erweitertes Schlussfolgern ausgibt
`attachment`	Ob das Modell Bild- oder Dateianhänge annimmt
`limit`	Tokengrenzen `{ context, output }` für die Budgetierung
`modalities`	Optionale Arrays `{ input, output }` (`text`, `image`, `pdf`, …)

Setzen Sie Fähigkeitsflags so, dass sie dem entsprechen, was das Upstream-Modell tatsächlich unterstützt. AX Code verwendet sie, um Toolaufrufe, Anhänge und die Kontextbudgetierung zu steuern.

Prüfen

Nach dem Speichern der Konfiguration:

ax-code models listet jedes Modell auf, das Ihr Anbieter bereitstellt.
/connect in der TUI zeigt den Anbieter und lässt Sie authentifizieren, wenn Sie einen Schlüssel env statt options.apiKey verwendet haben.

Wenn ein Modell fehlt, bestätigen Sie die Anbieter-ID, den Modellschlüssel und dass das Gateway unter baseURL erreichbar ist.

Fehlersuche

Authentifizierungsfehler — bestätigen Sie die Auflösungsreihenfolge der Zugangsdaten: options.apiKey gewinnt, andernfalls wird ein Schlüssel aus env oder dem Auth-Speicher verwendet.
Stockende Ströme — Gateways puffern SSE manchmal. Stimmen Sie options.chunkTimeout (je Block) und options.timeout (gesamte Anfrage) am Anbieter ab.
Abgelehnte Toolaufrufe — setzen Sie "tool_call": true am Modell und bestätigen Sie, dass das Upstream-Modell hinter dem Gateway Tools tatsächlich unterstützt.