Gute Standardwerte
GoModel folgt dem Prinzip guter Standardwerte. Die Standardeinstellungen sollen also ausreichen, um GoModel zu nutzen.Wie überschreibe ich die Standardeinstellungen?
Wir verwenden eine dreistufige Konfigurations-Pipeline. Jede Einstellung hat einen sinnvollen Standardwert, sodass Sie den Server ganz ohne Konfiguration starten können. GoModel erkennt Provider automatisch anhand bekannter Umgebungsvariablen.Konfigurationsmethoden
1. Umgebungsvariablen
Der gängigste Weg, GoModel zu konfigurieren. Setzen Sie eine der folgenden Variablen, um Standardwerte zu überschreiben.Server
Request-Bodys dürfen mit
Content-Encoding: gzip (oder x-gzip) oder zstd
komprimiert sein; die TypeSafe-SDKs komprimieren Bodys ab 1 KiB standardmäßig
mit zstd. Das Gateway dekodiert sie vor dem Routing, sodass Guardrails, Audit
und Provider den unkomprimierten Body sehen, und BODY_SIZE_LIMIT gilt sowohl
für die komprimierte als auch für die dekodierte Größe (413, wenn eine davon
überschritten wird). Andere Kodierungen liefern 415. Ein Body wird erst
gelesen und dekodiert, nachdem der Request authentifiziert ist. Vom Body eines
Requests ohne gültige Zugangsdaten wird daher nichts gelesen, und sein
Audit-Eintrag enthält keinen Request-Body. Ein solcher Request erhält 401,
auch wenn sein Body dekodiert über dem Limit läge; nur eine angegebene Größe über
dem Limit liefert weiterhin 413.
STREAM_STALL_TIMEOUT (server.stream_stall_timeout in YAML) schützt das
Gateway vor Clients, die eine Streaming-Response öffnen und dann aufhören, sie
zu lesen. Jeder Schreibvorgang zum Client erhält eine neue Frist. Der Timeout
greift daher nur, wenn der Socket des Clients so lange voll bleibt, niemals
während ein langsames Modell nichts zu senden hat. Greift er, wird die
Verbindung geschlossen, der Upstream-Request an den Provider abgebrochen und
der Audit-Eintrag vermerkt client_stalled, auch wenn der Stream aus dem
Response-Cache bedient wurde. Erhöhen Sie den Wert für Clients, die das Lesen
eines Streams berechtigterweise länger als eine Minute pausieren; setzen Sie
0, um ihn zu deaktivieren.
Client-Adressen hinter einem Proxy
Jede Client-Adresse, die GoModel meldet – in Audit-Einträgen, Rate-Limit-Keys, Logs –, ist die Adresse der Verbindung, die das Gateway erreicht hat. Hinter einem Reverse Proxy zeigen daher alle den Proxy. Setzen SieSERVER_TRUSTED_PROXIES auf die Netzwerke, in denen Ihre eigenen Proxys
stehen, dann liest GoModel stattdessen den weitergeleiteten Client. Nichts gilt
als vertrauenswürdig, bevor Sie es auflisten, nicht einmal Loopback, und
Änderungen an diesen Einstellungen erfordern einen Neustart.
Verwenden Sie bevorzugt genau das Subnetz, in dem Ihr Proxy steht.
private
erlaubt jedem privaten Client, seine eigene weitergeleitete Adresse zu setzen.
Das ist die falsche Wahl, wenn auch Ihre Clients private Adressen haben – ein
Homelab, dessen Clients in 192.168.1.0/24 liegen und dessen Cluster in
10.42.0.0/16 läuft, sollte nur 10.42.0.0/16 auflisten.
Standardmäßig liest GoModel X-Forwarded-For, an das jeder Hop die von ihm
gesehene Adresse anhängt, und erfasst den nächstgelegenen Hop, der nicht zu
Ihren vertrauenswürdigen Netzwerken gehört: die letzte Adresse, die Ihre eigene
Infrastruktur geschrieben hat, und zugleich die am weitesten entfernte, die ein
Client nicht überschreiben kann. Ein Request von außerhalb der aufgelisteten
Netzwerke, eine nicht parsebare Kette und eine Kette, die ausschließlich aus
vertrauenswürdigen Netzwerken besteht, behalten jeweils die
Verbindungsadresse – im letzten Fall ist jeder Eintrag eine Angabe, die ein
interner Client erfunden haben könnte.
Zwei Einstellungen ändern, wie der Header gelesen wird:
SERVER_CLIENT_IP_HEADERbenennt einen anderen Header. Alles außerX-Forwarded-Forenthält eine einzelne Adresse und wird unverändert übernommen. Das ist die korrekte Lesart hinter einem Edge, der den Client selbst ermittelt:SERVER_CLIENT_IP_HEADER=CF-Connecting-IPhinter Cloudflare oderX-Real-IPhinter einem nginx, der ihn setzt. DerForwarded-Header nach RFC 7239 wird nicht unterstützt.SERVER_TRUSTED_HOPSnimmt denX-Forwarded-For-Eintrag in einer festen Tiefe, statt die Kette zu durchsuchen –1ist der Eintrag ganz rechts,2der davor. Verwenden Sie diese Einstellung, wenn Ihr Edge in einer bekannten Tiefe sitzt, aber wechselnde Adressen nutzt, die Sie nicht aufzählen können. Die Verbindung muss weiterhin aus einem vertrauenswürdigen Netzwerk kommen, und eine Kette, die kürzer als die konfigurierte Tiefe ist, fällt auf die Verbindungsadresse zurück.
SERVER_TRUSTED_PROXIES voraus; allein gesetzt führen sie zu
einem Fehler beim Start, statt stillschweigend wirkungslos zu bleiben.
Setzen Sie GOMODEL_DEMO_MODE=true für eine öffentliche oder gemeinsam
genutzte Demo-Instanz. GoModel protokolliert dann beim Start und alle fünf
Minuten eine Warnung, zeigt oben im Dashboard eine dauerhafte Warnung an und
gibt DEMO_MODE=on über die freigegebene /admin/runtime/config-Response aus.
Der Demo-Modus setzt den Speicher nicht zurück; planen Sie das separat im
Deployment ein.
Der Demo-Modus umgeht auch nicht die Authentifizierung. Ein Log-Modus
managed_keys beim Start bedeutet, dass der konfigurierte Speicher noch
mindestens einen verwalteten Gateway-API-Key enthält, sodass Requests ein
Bearer-Token erfordern, selbst wenn GOMODEL_MASTER_KEY leer ist. Deaktivierte
oder abgelaufene verwaltete Keys lassen die Authentifizierung als
Fail-Closed-Sicherheitsmaßnahme aktiv. Löschen Sie alle verwalteten Keys, um in
den nicht authentifizierten Modus zurückzukehren, oder konfigurieren Sie einen
Master-Key für die Wiederherstellung.
Master-Key deaktivieren
Der Master-Key ist eine einzige globale Berechtigung: Wer ihn besitzt, ist gleichzeitig jeder Benutzer des Gateways. Sobald verwaltete Gateway-API-Keys ausgegeben sind, setzen SieMASTER_KEY_DISABLED=true
(server.master_key_disabled in YAML), um ihn stillzulegen. Dann bleiben diese
Keys – zusammen mit einer eventuell betriebenen Authentifizierungserweiterung
wie SSO – der einzige Zugang. User Paths, Budgets, Rate-Limits und
Audit-Trails pro Key gelten dann für jeden Request, einschließlich der Admin
API.
GET /v1/auth/verify und an
/admin. Ein in der Umgebung oder in config.yaml verbliebener Key ist
wirkungslos statt ein Fehler. Deshalb können Sie den Schalter gefahrlos
umlegen, bevor Sie den Key entfernen.
Deaktivieren ist nicht dasselbe, wie GOMODEL_MASTER_KEY leer zu lassen. Ein
leerer Wert betreibt das Gateway ohne Authentifizierung und öffnet /admin/*,
damit das Dashboard seinen ersten verwalteten Key anlegen kann. Sofern keine
Authentifizierungserweiterung konfiguriert ist, bleibt /admin/* auch dann
offen, wenn bereits verwaltete Keys existieren, und GoModel protokolliert
währenddessen beim Start eine Sicherheitswarnung. Setzen Sie daher einen
Master-Key oder deaktivieren Sie ihn, sobald der erste Key mit
Dashboard-Zugriff ausgegeben ist. Ein deaktivierter Master-Key schlägt
dagegen geschlossen fehl (Fail-Closed): Jeder Request benötigt Zugangsdaten,
und die Admin API bleibt hinter Zugangsdaten mit Dashboard-Zugriff. Geben Sie
diese Zugangsdaten aus, bevor Sie den Schalter umlegen – ohne Master-Key, ohne
verwalteten Key und ohne Authentifizierungserweiterung lehnt das Gateway jeden
Request ab und protokolliert beim Start eine entsprechende Warnung.
HTTPS ausliefern
Lassen Sie dieSERVER_TLS_*-Einstellungen leer, um hinter einem Proxy, der TLS
terminiert, einfaches HTTP auszuliefern. Setzen Sie Zertifikat und Schlüssel
(server.tls_cert_file und server.tls_key_file in YAML), wenn Clients sich
direkt mit dem Gateway verbinden:
${env:...}-Referenzen; ${file:...} liefert den Inhalt einer Datei, nutzen Sie
es also nur für eine Datei, die einen Pfad enthält. Diese Einstellungen betreffen
nur eingehende Verbindungen; das Vertrauen für ausgehendes
TLS wird separat konfiguriert. Ein Beispiel mit
cert-manager finden Sie im Produktionsleitfaden.
MCP Gateway
Den vollständigen Leitfaden finden Sie unter MCP Gateway.Logging
Ausgabe des Laufzeit-Loggers. Für den persistierten API-Audit-Trail (Request-/Response-Bodys, Header) siehe Audit-Logging weiter unten.Cache
CACHE_REFRESH_INTERVAL legt außerdem fest, wie oft das Dashboard den
Zustand der Provider erneut prüft („Last checked“), und
PROVIDER_RECHECK_INTERVAL, wie schnell ein ausgefallener Provider erneut
auf Wiederherstellung geprüft wird. Siehe
Ausfallsicherheit.Speicher
Der Speicher wird gemeinsam von Audit-Logging, Nutzungserfassung und künftigen Features wie IAM verwendet.Medienspeicher
Mediendateien – die Audio- und Bilddaten, die für das Audit-Log erfasst werden, wennLOGGING_LOG_AUDIO_BODIES oder LOGGING_LOG_IMAGE_BODIES aktiv ist –
werden außerhalb der Datenbank abgelegt. Ihre Metadaten liegen im oben
beschriebenen Speicher-Backend; nur die Bytes landen hier. So sind sie in der
Größe nie begrenzt, und die Datenbank bleibt klein. Siehe
ADR-0013.
Der Standardpfad folgt der SQLite-Regel:
./data/media, wenn neben dem Prozess
ein ./data-Verzeichnis existiert, andernfalls das benutzerspezifische
Datenverzeichnis des Betriebssystems. Binden Sie in Containern dort ein Volume
ein; bei mehreren Replikas verwenden Sie einen gemeinsamen Mount (EFS, einen
S3-FUSE-Mount), damit jede Instanz jede Datei ausliefern kann. Dateien werden so
lange aufbewahrt wie die Audit-Einträge, die auf sie verweisen
(LOGGING_RETENTION_DAYS), und durch einen stündlichen Bereinigungslauf
entfernt.
Audit-Logging
Audit-Einträge enthalten die Client-Adresse, die das Gateway ermittelt hat.
Hinter einem Reverse Proxy ist das der Proxy, bis Sie dessen Netzwerk in
SERVER_TRUSTED_PROXIES eintragen – siehe Client-Adressen hinter einem
Proxy.
Echtzeit-Vorschauen im Dashboard und persistierte Audit-Logs sind getrennte
Features. Mit DASHBOARD_LIVE_LOGS_ENABLED=true und LOGGING_ENABLED=false
können Requests live erscheinen, werden aber nicht gespeichert und
verschwinden nach dem Neuladen der Seite. Ist das Audit-Logging aktiviert,
erfolgen die Schreibvorgänge asynchron, und es kann bis zu
LOGGING_FLUSH_INTERVAL Sekunden dauern, bis Einträge über die API für
gespeicherte Logs sichtbar sind.
Unter PostgreSQL nutzt die Volltextsuche des Audit-Logs einen Trigramm-Index
aus der mitgelieferten Erweiterung
pg_trgm. GoModel installiert die
Erweiterung und baut den Index beim Start auf, sofern seine Datenbankrolle das
darf. Andernfalls funktioniert die Suche weiterhin, durchsucht aber jeden
Eintrag im gewählten Datumsbereich. Um sie für eine eingeschränkte Rolle zu
aktivieren, führen Sie einmalig CREATE EXTENSION pg_trgm; als Superuser aus
und starten Sie GoModel neu.LOGGING_LOG_REVISION_BODIES verfeinert LOGGING_LOG_BODIES für die
Rewrite-Kette eingehender Requests – ohne aktiviertes Body-Logging hat es
keine Wirkung. Sind beide aktiv, speichern jeder Rewriter, der einen Request
geändert hat (zum Beispiel die Token-Komprimierung von GoModel Pro), und jede
Prompt-Guardrail, die den Prompt bearbeitet hat, den Request in dem Zustand,
in dem sie ihn weitergegeben haben, zusammen mit dem ursprünglichen
Client-Body im Audit-Eintrag. So lässt sich eine Kette von Änderungen Schritt
für Schritt nachvollziehen. LOGGING_LOG_GUARDRAIL_STEPS steuert diese
Erfassung pro Schritt (die Request-Bodys werden außerhalb des Request-Pfads
kodiert): Schalten Sie es ab, um die Änderungen einer Kette als eine einzige
Revision mit dem weitergeleiteten Request zu erfassen, ohne Snapshots pro
Schritt. Wenn Sie LOGGING_LOG_REVISION_BODIES deaktivieren, bleiben die
Revisions-Metadaten (Name des Rewriters, Bytegrößen, eingesparte Tokens,
Details der Änderung) erhalten, die zusätzlichen Body-Kopien entfallen aber.
Das halbiert den Audit-Speicher pro umgeschriebenem Request ungefähr.LOGGING_LOG_AUDIO_BODIES verfeinert LOGGING_LOG_BODIES für
Audio-Endpunkte – ohne aktiviertes Body-Logging hat es keine Wirkung. Sind
beide aktiv, speichert /v1/audio/speech seine Texteingabe und das erzeugte
Audio (Base64, begrenzt auf 8 MB), damit das Dashboard es abspielen kann, und
/v1/audio/transcriptions speichert das hochgeladene Audio (Base64, begrenzt
auf 8 MB, ebenfalls abspielbar) samt Upload-Metadaten. Der Standardwert ist
false, weil Audio-Payloads groß sind und den Audit-Speicher schnell
wachsen lassen. Ist Body-Logging aktiv, diese Option aber nicht, werden
Audio-Bodys (die Speech-Response und der Transkriptions-Upload, der seine
Metadaten behält) als schlanker Platzhalter
{__audio__, content_type, bytes, stored: false} erfasst; ist Body-Logging
deaktiviert, wird überhaupt kein Audio-Body gespeichert.LOGGING_LOG_EMBEDDING_BODIES verfeinert LOGGING_LOG_BODIES für
Embeddings – ohne aktiviertes Body-Logging hat es keine Wirkung. Es gilt für
/v1/embeddings und für Provider-Passthrough-Aufrufe an einen
Embeddings-Endpunkt (/p/{provider}/.../embeddings, llama.cpp
/embedding, Cohere und Ollama
.../embed, Gemini :embedContent und :batchEmbedContents).
Embedding-Eingaben können ganze Dokumente oder Base64-Bilder sein und die
Responses sind Float-Vektoren, sodass Massen-Indexierungsjobs den
Audit-Speicher schnell wachsen lassen. Ist Body-Logging aktiv, diese Option
aber nicht, behalten Embedding-Einträge ihre Metadaten (Modell, Provider,
Status, Timing, User-Pfad, Usage) und verwerfen Request- und Response-Body.
Der Standardwert ist true, was das bisherige Verhalten beibehält.LOGGING_LOG_IMAGE_BODIES verfeinert LOGGING_LOG_BODIES für die
Images API – ohne aktiviertes Body-Logging hat es
keine Wirkung. Sind beide aktiv, werden generierte Bilder
(/v1/images/generations, /v1/images/edits) sowie hochgeladene
Bearbeitungsquellen und Masken als Base64 gespeichert (8 MB pro Eintrag,
Bilder jenseits dieses Budgets werden zu Platzhaltern), damit das Dashboard
sie anzeigen kann. LOGGING_LOG_IMAGE_BODIES_SCOPE schränkt dies auf input
(nur Uploads) oder output (nur Ergebnisse) ein; der Standardwert all
speichert beides. Der Standardwert ist false, weil Bild-Payloads groß sind
und den Audit-Speicher schnell wachsen lassen. Ist Body-Logging aktiv, diese
Option aber nicht, behalten Bildeinträge alles außer den Pixeln: Prompt und
Parameter, die Response-Hülle (usage, size, quality), gehostete URLs
und pro Bild einen Platzhalter mit Größenangabe
{role, content_type, bytes, stored: false}.Erfassung der Token-Nutzung
Budgets
Budgets verwenden die erfassten Nutzungs- und Kostendatensätze. Ist die Nutzungserfassung deaktiviert, startet GoModel mit deaktivierter Budgetverwaltung und protokolliert eine Warnung.SET_BUDGET_<PATH> unterstützt die Standardzeiträume hourly, daily,
weekly und monthly. Das Suffix <PATH> wird in Kleinbuchstaben
umgewandelt; verwenden Sie doppelte Unterstriche (__) zwischen
Pfadsegmenten, während einfache Unterstriche innerhalb eines Segments bleiben.
Zum Beispiel konfiguriert SET_BUDGET_TEAM__ALPHA__SERVICE="daily=10" den Pfad
/team/alpha/service und SET_BUDGET_TEAM_ALPHA="daily=10" den Pfad
/team_alpha. Das unterscheidet sich von den unten beschriebenen
<SUFFIX>-Variablen für Provider, die in Provider-Namen Unterstriche in
Bindestriche umwandeln; SET_PROVIDER_BUDGET_<NAME> folgt der
Provider-Konvention, sodass SET_PROVIDER_BUDGET_OPENAI_PROD den Provider
openai-prod begrenzt.
SET_BUDGET_="monthly=500" bezeichnet eine Umgebungsvariable mit dem
wörtlichen Namen SET_BUDGET_, die den Root-Pfad / konfiguriert. POSIX
erlaubt diesen Namen, manche Shells und Orchestratoren, darunter einige
Kubernetes-Validatoren, lehnen ihn jedoch möglicherweise ab. Verwenden Sie
YAML oder das Dashboard, wenn Ihre Umgebung ihn nicht setzen kann.
Hinweis zur Migration: Die Budgetverwaltung hängt von der Nutzungserfassung
ab. Bei USAGE_ENABLED=false startet GoModel mit deaktivierten Budgets und
protokolliert eine Warnung, selbst wenn BUDGETS_ENABLED=true gesetzt ist.
Setzen Sie sowohl USAGE_ENABLED=true als auch BUDGETS_ENABLED=true, um
Budgets durchzusetzen.
Unter Budgets finden Sie YAML-Beispiele, Zeiträume,
Zuordnungsregeln und die Durchsetzung in Workflows.
Metriken
Die Prometheus-Unterstützung ist experimentell. Details finden Sie im
Leitfaden zu Prometheus-Metriken.
Admin
Live-Logs im Dashboard sind kompakte Vorschauen für die Seiten Audit Logs und
Usage. Sie aktualisieren Zeilen, bevor das asynchrone Schreiben in die
Datenbank abgeschlossen ist. Die gespeicherten Audit- und Nutzungstabellen
bleiben die maßgebliche Quelle; verbindet sich ein Browser mit einem Cursor
außerhalb des Replay-Fensters neu, lädt das Dashboard die Daten über die
regulären REST-APIs neu.
HTTP-Client
Diese Einstellungen steuern die Timeouts für Upstream-API-Requests an LLM-Provider.
Ein Stream, der länger als
HTTP_STREAM_IDLE_TIMEOUT still bleibt, wird mit
einem 504-Provider-Fehler geschlossen, statt bis HTTP_TIMEOUT zu hängen.
Die Wartezeit auf das erste Token zählt nicht mit, langsame Reasoning-Modelle
sind also nicht betroffen. Erhöhen Sie den Wert nur für einen Provider, der
mitten im Stream berechtigterweise minutenlang pausiert.
Die Standardvariablen HTTP_PROXY, HTTPS_PROXY und NO_PROXY gelten für
jede Upstream-Verbindung, sofern ein Provider keinen eigenen
ausgehenden Proxy festlegt.
Vertrauen für ausgehendes TLS
Diese Einstellungen gelten für die ausgehenden HTTPS-Clients des Gateways: Provider, Modellkatalog, Update-Prüfung, MCP-Upstreams, Vector Stores und Embedding-Endpunkte. Standardmäßig wird dem Zertifikatsspeicher des Betriebssystems vertraut. Das passt, solange keine interne CA und kein TLS-abfangender Proxy zwischen Gateway und Upstreams sitzt. Verbindungen anderer Clients betreffen sie nicht; diese haben eigene Einstellungen: Der OpenTelemetry-Export liestOTEL_EXPORTER_OTLP_CERTIFICATE,
PostgreSQL nimmt sslmode und sslrootcert in der URL (empfohlen:
sslmode=verify-full), MongoDB nimmt tls=true und tlsCAFile in der URL,
und Redis über rediss:// vertraut dem Systemspeicher.
Eine fehlende oder nicht lesbare Datei ist ein Startfehler, sodass ein Tippfehler
im Pfad nicht stillschweigend dazu führt, dass nichts zusätzlich vertraut wird.
Bei einem Reload der Konfiguration
werden die Dateien neu gelesen, aber nicht überwacht. Führen Sie nach dem
Rotieren also einen Reload oder Neustart aus. Ein vollständiges Beispiel
finden Sie im Produktionsleitfaden.
API-Keys der Provider
Setzen Sie diese Variablen, um Provider automatisch zu registrieren. Keine YAML-Konfiguration erforderlich.
Die meisten Provider können über
<PROVIDER>_BASE_URL (zum Beispiel OPENAI_BASE_URL) eine eigene Base-URL verwenden. Chutes AI verwendet standardmäßig https://llm.chutes.ai/v1; dies lässt sich mit CHUTES_BASE_URL überschreiben. DeepSeek verwendet standardmäßig https://api.deepseek.com; setzen Sie DEEPSEEK_BASE_URL nur für einen kompatiblen Proxy oder einen alternativen DeepSeek-Endpunkt. OpenRouter verwendet standardmäßig https://openrouter.ai/api/v1; dies lässt sich mit OPENROUTER_BASE_URL überschreiben. Kilo AI verwendet standardmäßig https://api.kilo.ai/api/gateway; dies lässt sich mit KILO_BASE_URL überschreiben. Eden AI verwendet standardmäßig https://api.edenai.run/v3; dies lässt sich mit EDENAI_BASE_URL überschreiben. Z.ai verwendet standardmäßig https://api.z.ai/api/paas/v4; setzen Sie ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4 für den Endpunkt des GLM Coding Plan. SGLang verwendet standardmäßig http://localhost:30000/v1, wenn SGLANG_API_KEY gesetzt ist; Deployments ohne Key sollten SGLANG_BASE_URL jedoch explizit setzen, um den Provider zu registrieren. vLLM folgt demselben Muster mit http://localhost:8000/v1. Für llama.cpp ist LLAMACPP_BASE_URL immer erforderlich (der Standardport von llama-server kollidiert mit GoModels eigenem Port 8080, daher gibt es keinen Standardwert); LLAMACPP_API_KEY ist optional. llm-d hat keinen universellen Endpunkt, daher ist LLMD_BASE_URL immer erforderlich; LLMD_API_KEY ist optional. Azure verwendet AZURE_BASE_URL für die Base-URL seines Deployments und akzeptiert optional AZURE_API_VERSION zum Überschreiben; andernfalls gilt für Deployment-URLs standardmäßig 2024-10-21, für /openai/v1-URLs (Azure AI Foundry) wird keine Version gesendet. Oracle erfordert ORACLE_BASE_URL, weil sein OpenAI-kompatibler Endpunkt regionsspezifisch ist.
Jeder Provider-Typ akzeptiert außerdem über <PROVIDER>_MODELS eine
kommagetrennte Liste konfigurierter Modelle, zum Beispiel
OPENROUTER_MODELS, ORACLE_MODELS, AZURE_MODELS, SGLANG_MODELS,
VLLM_MODELS oder LLMD_MODELS. Wie eine Liste mit dem /models des
Providers kombiniert wird, legt CONFIGURED_PROVIDER_MODELS_MODE fest (Standard
allowlist), für einen einzelnen Provider <PROVIDER>[_SUFFIX]_MODELS_MODE
(YAML: providers.<name>.models_mode), zum Beispiel
OPENROUTER_MODELS_MODE=fallback; siehe Modellmodi. Ein OpenAI-kompatibler
Provider ohne /models-Endpunkt (404 oder 405) wird aus seiner konfigurierten
Liste bedient und als gesund gemeldet. Das passt zu Servern mit nur einer API,
etwa für Speech-to-Text. In YAML liefert
providers.<name>.models dieselbe Modellliste für benannte Provider-Blöcke.
GET /v1/models listet standardmäßig Provider-qualifizierte IDs
(openai/gpt-5). Setzen Sie UNQUALIFIED_MODEL_IDS_AT_MODELS_ENDPOINT=true
(YAML: models.unqualified_model_ids_at_models_endpoint), um stattdessen
reine Modell-IDs (gpt-5) aufzulisten – für Clients, die das angeforderte
Modell gegen die Liste prüfen und nur einfache Namen kennen. Einschränkung:
Wenn zwei Provider dieselbe Modell-ID anbieten, wird nur der Provider
aufgelistet, an den ein nicht qualifizierter Request geroutet wird (der zuerst
registrierte). Binden Sie einen Namen mit einem
virtuellen Modell an einen
bestimmten Provider, zum Beispiel source: gpt-5 mit target: azure/gpt-5.
Jedes Provider-Modell ist standardmäßig verfügbar. Setzen Sie
MODELS_ENABLED_BY_DEFAULT=false (YAML: models.enabled_by_default), um
stattdessen einen expliziten Freigabeeintrag in
virtuellen Modellen
zu verlangen: Requests für andere Modelle schlagen dann mit
400 model_access_denied fehl, und die Modelle erscheinen nicht in
GET /v1/models. Um Provider-Modelle in GET /v1/models auszublenden, sie aber
routbar zu lassen, setzen Sie KEEP_ONLY_ALIASES_AT_MODELS_ENDPOINT=true
(YAML: models.keep_only_aliases_at_models_endpoint); der Endpunkt listet dann
nur aktivierte Redirects virtueller Modelle.
Um das Modellangebot eines Providers einzugrenzen, statt es Modell für Modell
aufzulisten, verwenden Sie <PROVIDER>_MODEL_FILTER_INCLUDE,
<PROVIDER>_MODEL_FILTER_EXCLUDE und
<PROVIDER>_MODEL_FILTER_MAX_PRICE_PER_MTOK (YAML:
providers.<name>.model_filter). Siehe
Modelle eines Providers filtern.
Setzen Sie MODELS_VLLM_DISCOVERY_COMPAT=true (YAML:
models.vllm_discovery_compat), wenn ein Client Modelle nur von einer
vLLM-Runtime erkennt. Der vllm-Provider von OpenCode ist ein Beispiel: Er
fragt /health und /v1/models ab und verwirft jeden Eintrag, dessen
owned_by nicht vllm ist oder dem max_model_len fehlt. Mit dieser
Einstellung meldet GET /v1/models owned_by als vllm und füllt
max_model_len für jeden Eintrag, sodass der Client die Modelle des Gateways
ohne handgeschriebene Liste übernimmt. Die Angabe zum Eigentümer ist damit
falsch, deshalb ist die Einstellung standardmäßig aus und für Gateways gedacht,
deren Clients sie brauchen.
Das Limit hat zwei Quellen, in dieser Reihenfolge:
- Die Angabe des Providers selbst. Eine Runtime, die das Modell selbst
ausliefert (vLLM, SGLang, llm-d und jeder OpenAI-kompatible Server, der
max_model_lenin seiner/models-Liste zurückgibt), kennt das echte Limit ihres Prozesses, daher hat ihr Wert Vorrang. metadata.context_window. Der Katalogwert, nur für ein Modell, dessen Provider kein Limit gemeldet hat. Er macht gehostete Modelle auffindbar.
owned_by: "vllm" und
max_model_len: 0. Null bedeutet, dass das Limit unbekannt ist, nicht dass der
Eintrag unvollständig ist: Das Feld wird nie weggelassen, weil diese Clients die
ganze Liste gegen ein Schema prüfen, in dem es Pflicht ist. Fehlt es bei einem
Eintrag, schlägt die Antwort fehl und alle anderen Modelle verschwinden mit. Ein
Client, der den Wert nur liest, wenn er positiv ist, behält seinen eigenen
Standard. Um das echte Fenster anzugeben, deklarieren Sie es am Modell:
OPENROUTER_SITE_URL und OPENROUTER_APP_NAME.
2. .env-Datei
GoModel lädt beim Start automatisch eine .env-Datei aus dem Arbeitsverzeichnis. Das ist praktisch für die lokale Entwicklung.
.env.template nach .env und kommentieren Sie die benötigten Werte ein:
Echte Umgebungsvariablen haben immer Vorrang vor Werten aus der
.env-Datei.
Die .env-Datei wird nur geladen, wenn sie existiert – fehlt sie, ist das
kein Fehler.3. Konfigurationsdatei (YAML)
Für komplexere Setups können Sie eine optionale YAML-Konfigurationsdatei verwenden. GoModel sucht sie an zwei Orten (in dieser Reihenfolge):config/config.yamlconfig.yaml
${VAR} und ${VAR:-default}:
${file:/run/secrets/openai} oder ${env:OPENAI_API_KEY}.
Provider-Konfiguration
Automatische Erkennung über Umgebungsvariablen
Der einfachste Weg, Provider hinzuzufügen. GoModel prüft bekannte Umgebungsvariablen für API-Keys und registriert Provider automatisch:<PROVIDER>_*) haben Vorrang vor dem Provider in
config.yaml, der nach dem Typ benannt ist (openai). Ein umbenannter
Provider (alpha: {type: openai}) übernimmt nur Felder, die er leer gelassen
hat; sein explizites api_key oder base_url bleibt erhalten, und die
ignorierten Variablen werden beim Start als Warnung protokolliert. Teilen sich
mehrere umbenannte Provider einen Typ, werden die Variablen ohne Suffix mit
derselben Warnung ignoriert.
Verwenden Sie Variablen mit Suffix, um ohne YAML mehr als eine Instanz
desselben Provider-Typs zu registrieren. GoModel wandelt das Suffix in
Kleinbuchstaben um und ersetzt im konfigurierten Provider-Namen Unterstriche
durch Bindestriche:
<PROVIDER>_<SUFFIX>_API_KEY, <PROVIDER>_<SUFFIX>_BASE_URL und
<PROVIDER>_<SUFFIX>_MODELS. Azure unterstützt zusätzlich
<PROVIDER>_<SUFFIX>_API_VERSION. Azure und Oracle erfordern weiterhin ihre
BASE_URL-Werte mit Suffix, weil ihre Endpunkte deployment- bzw.
regionsspezifisch sind.
Google Vertex AI verwendet das Präfix VERTEX_* und folgt derselben Regel zur
Ableitung des Namens aus dem Suffix wie andere Provider:
Provider-Blöcke in YAML
Für mehr Kontrolle (eigene Namen, Ausfallsicherheit pro Provider oder größere strukturierte Einstellungen) verwenden Sie die YAML-Datei:models: funktioniert in jedem Provider-Block; wie es mit Upstream /models
kombiniert wird, hängt vom Modellmodus ab. Für Oracle GenAI finden Sie im
Oracle-GenAI-Leitfaden die erforderliche OCI-Policy und
eine getestete Konfiguration.Ollama (lokale Modelle)
Ollama benötigt keinen API-Key. Setzen Sie die Base-URL, um es zu aktivieren:vLLM
vLLM verwendet seine OpenAI-kompatible/v1-API. Setzen Sie in Docker
VLLM_BASE_URL, um einen vLLM-Server ohne Key zu registrieren:
vllm serve ... --api-key token-abc123
gestartet, setzen Sie zusätzlich:
vllm und vllm-test registriert. Verwenden Sie
YAML nur, wenn die generierten Provider-Namen nicht ausreichen oder Sie einen
größeren strukturierten Block benötigen.
Hinweise zum Provider-Verhalten
Anthropic: Standardwert für max_tokens
Anthropic verlangt max_tokens bei jedem /v1/messages-Request. Lässt ein
Client das Feld weg, setzt GoModel einen Fallback-Wert ein, damit der Request
trotzdem gelingt. OpenAI und Gemini behandeln das Feld als optional, und
GoModel setzt für sie keinen Standardwert ein.
Erhöhen Sie diesen Wert für neuere Modelle, die regelmäßig längere Ausgaben
erzeugen (Sonnet 4.6, Opus 4.7). Ein explizit im Request gesetztes
max_tokens hat immer Vorrang vor dem über die Umgebung gesetzten
Standardwert. Ungültige oder nicht positive Werte fallen auf 4096 zurück.