> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel.enterpilot.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret-Referenzen

> Lesen Sie API-Keys, DSNs und andere Zugangsdaten mit ${env:...}- und ${file:...}-Referenzen aus Umgebungsvariablen oder eingehängten Dateien.

Eine Secret-Referenz teilt GoModel mit, wo ein Wert gelesen werden soll, statt den
Wert selbst zu enthalten:

```yaml theme={null}
server:
  master_key: ${file:/run/secrets/gomodel-master-key}

providers:
  openai:
    type: openai
    api_key: ${env:OPENAI_KEY}
```

Referenzen funktionieren in jeder String-Einstellung der `config.yaml`, in den
Umgebungsvariablen, die diese Einstellungen setzen, und in Provider-Umgebungsvariablen:

```bash theme={null}
OPENAI_API_KEY='${file:/run/secrets/openai}'
POSTGRES_URL='${file:/run/secrets/postgres-url}'
```

Setzen Sie den Wert in einer Shell in einfache Anführungszeichen, damit die Shell ihn
nicht expandiert; `.env`-Dateien benötigen keine Anführungszeichen. Docker Compose
interpoliert `${...}` in seinen eigenen Dateien, schreiben Sie dort also
`$${file:...}`; Compose gibt `${file:...}` dann an GoModel weiter.

## Syntax

Eine Referenz hat die Form `${<scheme>:<reference>}`. Sie kann Teil eines größeren
Werts sein, und ein Wert kann mehrere Referenzen enthalten:

```yaml theme={null}
providers:
  openai:
    type: openai
    api_key: ${env:OPENAI_KEY}
    proxy_url: http://gomodel:${file:/run/secrets/proxy-pass}@proxy:3128

mcp:
  servers:
    github:
      url: https://mcp.example.com/mcp
      headers:
        Authorization: Bearer ${env:GITHUB_TOKEN}
```

Der aufgelöste Wert wird unverändert verwendet. Er darf Zeilenumbrüche,
Anführungszeichen oder beliebige andere Bytes enthalten – eine
Service-Account-JSON-Datei funktioniert also –, und er wird nie nach weiteren
Referenzen durchsucht.

## Schemas

| Schema | Referenz | Wert |
| - | - | - |
| `env` | Variablenname | der Wert der Variablen; nicht gesetzt oder leer bricht den Start ab |
| `file` | absoluter Pfad | der Dateiinhalt ohne einen abschließenden Zeilenumbruch; höchstens 1 MiB; fehlend oder leer bricht den Start ab |

`file` liest Secret-Mounts von Docker und Kubernetes direkt, sodass kein
Entrypoint-Skript nötig ist, um sie in Umgebungsvariablen zu kopieren. Der Pfad muss
eine reguläre Datei oder ein Symlink auf eine solche sein, wie es bei diesen Mounts
der Fall ist; ein FIFO oder Gerät wird abgelehnt, weil GoModel die Datei bei jedem
Reload erneut liest.

`env` unterscheidet sich in zwei Punkten von der einfachen Form `${NAME}`: Es ist
strikt, und es funktioniert in Umgebungsvariablen, nicht nur in der `config.yaml`. Die
einfache Form bleibt unverändert: `${NAME}` und `${NAME:-default}` werden in der
`config.yaml` expandiert, und ein nicht gesetztes `${NAME}` bleibt stehen, wodurch ein
Provider, dessen Key es ist, entfällt.

Externe Secret-Manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager,
Azure Key Vault) lassen sich mit [GoModel Pro](https://gomodel.enterpilot.io/docs/de/pro/overview.md) als weitere Schemas
einbinden.

## Fehler brechen den Start ab

Eine Referenz, die nicht aufgelöst werden kann, beendet das Gateway mit einem Fehler,
der die Einstellung und das Schema nennt, aber niemals den Wert:

```text theme={null}
failed to resolve secret references: providers.openai.api_key: secret reference ${file:...}: open /run/secrets/openai: no such file or directory
```

Ein über eine Umgebungsvariable gesetzter Provider-API-Key wird unter dem Namen der
Variablen gemeldet, zum Beispiel `OPENAI_API_KEY_2: secret reference ${file:...}`.
Ein Schema, das GoModel nicht kennt, wird im Fehler nicht wiederholt, weil es sich um
Text aus dem Wert handelt; prüfen Sie die genannte Einstellung auf Tippfehler.

Ein fehlgeschlagener [Reload](https://gomodel.enterpilot.io/docs/de/advanced/cli.md#konfiguration-neu-laden) behält die
laufende Konfiguration bei. GoModel startet niemals mit einer nicht aufgelösten
Referenz und sendet sie auch nie upstream.

Jede Referenz hat 30 Sekunden Zeit zur Auflösung. Eine, die länger braucht – etwa eine
Datei auf einem hängenden Netzwerk-Mount –, schlägt mit `context deadline exceeded`
fehl, statt den Start, einen Reload oder ein Speichern im Dashboard aufzuhalten.

Nur tatsächlich verwendete Werte werden aufgelöst: Ein Provider-Wert in der
`config.yaml`, den eine Umgebungsvariable überschreibt, eine Provider-Umgebungsvariable,
die GoModel ignoriert (zum Beispiel `OPENAI_MODELS`, wenn mehrere `openai`-Provider
existieren und keiner `openai` heißt), oder ein Provider, der wegen fehlender
Zugangsdaten übersprungen wird, wird nicht nachgeschlagen.

## Rotation

GoModel fragt `env`- oder `file`-Referenzen nicht periodisch ab. Führen Sie nach dem
Rotieren einer Referenz einen Reload aus: `gomodel --reload` oder `SIGHUP`.

Erweiterungen, die einen Secret-Manager beobachten, etwa die Vaults von GoModel Pro,
benachrichtigen GoModel, wenn sich ein Wert ändert. GoModel löst dann jede Referenz
erneut auf und:

* tauscht Provider-API-Keys im laufenden Betrieb aus, wenn sich nur diese geändert
  haben. Laufende Requests werden mit dem Key abgeschlossen, mit dem sie begonnen
  haben. Sessions, die an einen entfernten Key gebunden sind, wechseln zu einem
  anderen; die meisten anderen Sessions behalten ihren Key.
* lädt die Konfiguration neu, wie bei `SIGHUP`, wenn sich irgendetwas anderes in der
  `config.yaml` oder der Umgebung geändert hat (eine DSN, der Master-Key, eine
  Proxy-URL, ein Service-Account-JSON). Ein fehlgeschlagener Reload behält die
  laufende Konfiguration bei und wird bei der nächsten Änderung erneut versucht. Im
  Dashboard gespeicherte Referenzen lösen nie einen Reload der Konfiguration aus;
  siehe [Im Dashboard verwaltete Zugangsdaten](https://gomodel.enterpilot.io/docs/de/advanced/secret-references.md#im-dashboard-verwaltete-zugangsdaten).
* behält jeden aktuellen Wert bei, wenn eine Referenz nicht erneut aufgelöst werden
  kann, und protokolliert eine Warnung, die die Einstellung nennt.

Die Log-Zeile nennt die geänderten Einstellungen, niemals ihre Werte:

```text theme={null}
rotated provider API keys in place providers=[openai] fields=[providers.openai.api_keys[1]]
```

Eine Änderung am Key des Providers, den der Embedder des semantischen Caches
verwendet, löst ebenfalls einen Reload aus, weil der Embedder eine eigene Kopie der
Keys hält.

## Im Dashboard verwaltete Zugangsdaten

Provider-Zugangsdaten, Header von MCP-Servern und geheime Felder von Guardrails, die
über das Dashboard oder die Admin API gespeichert werden, akzeptieren ebenfalls
Referenzen in derselben Syntax:

| Entität | Felder |
| - | - |
| Provider-Zugangsdaten | API-Keys, Service-Account-JSON und Base64-JSON, Proxy-URL |
| MCP-Server | Header-Werte |
| Guardrails | die geheimen Felder des Plugins |

* Die Referenz wird so gespeichert, wie sie eingegeben wurde; GoModel löst sie auf,
  wenn es den Provider, die MCP-Verbindung oder die Guardrail aufbaut.
* Eine Referenz ist kein Secret; daher zeigen das Dashboard und die Admin API einen
  Wert, der nur aus Referenzen besteht, unmaskiert an. Ein MCP-Header darf zusätzlich
  mit einem Auth-Schema beginnen (`Bearer ${env:TOKEN}`), und eine Proxy-URL wird
  angezeigt, wenn ihr Passwort eine Referenz ist. Literale Secrets und Werte, die
  literalen Text mit einer Referenz mischen, bleiben maskiert, und das Zurücksenden
  der Maske behält den gespeicherten Wert bei.
* Eine Referenz, die nicht aufgelöst werden kann, wird beim Speichern mit einem `400`
  abgelehnt, der das Feld und das Schema nennt.
* Nur der Master-Key kann eine Referenz hinzufügen oder ändern. Eine Referenz wird auf
  dem Gateway-Host aufgelöst und kann daher jede Umgebungsvariable und jede Datei
  lesen, die das Gateway lesen kann, einschließlich des Master-Keys. Alle anderen
  Zugangsdaten, etwa ein verwalteter Key mit Dashboard-Zugriff, erhalten einen `403`
  (`secret_reference_requires_master_key`), der das Feld nennt. Sie können weiterhin
  literale Secrets speichern, die Maske zurücksenden und eine Entität erneut
  speichern, deren Referenzen unverändert sind. Ohne Master-Key speichern
  Dashboard-Zugangsdaten Referenzen wie bisher.
* Aus demselben Grund kann nur der Master-Key ändern, wohin eine Entität, die eine
  Referenz enthält, diese sendet: die `url` eines MCP-Servers, `type`, `base_url`,
  `backend` oder `proxy_url` eines Providers oder den Typ bzw. die Service-URL einer
  Guardrail (etwa `analyzer_url` von Presidio). Andere Zugangsdaten erhalten denselben
  `403` mit dem Feldnamen und können alle anderen Felder weiterhin bearbeiten.
* Jeder Resolver-Aufruf trägt für Audit-Zwecke einen Feldpfad, etwa
  `provider_credentials.openai.api_keys[0]`,
  `mcp_servers.github.headers.Authorization` oder
  `guardrail_definitions.pii.config.api_key`.
* Wenn ein referenzierter Wert [rotiert](https://gomodel.enterpilot.io/docs/de/advanced/secret-references.md#rotation) wird, wird nur die betroffene
  Entität neu eingerichtet: Die Keys eines Providers werden im laufenden Betrieb
  ausgetauscht, jede andere Provider-Änderung baut diesen Provider neu auf, ein
  MCP-Server wird neu verbunden und eine Guardrail neu aufgebaut. Kann die Referenz
  nicht aufgelöst werden, behält die Entität ihren aktuellen Wert.

In der `config.yaml` deklarierte Guardrail-Regeln werden auf dieselbe Weise
gespeichert: Eine Referenz im geheimen Feld eines Plugins wird so gespeichert, wie sie
geschrieben ist, und beim Aufbau der Guardrail aufgelöst, sodass die Datenbank das
Secret nie enthält.

Kann eine gespeicherte Referenz beim Start nicht aufgelöst werden, werden die
Provider-Zugangsdaten bzw. der MCP-Server protokolliert und übersprungen, und der Rest
des Gateways startet. Bei einem Reload werden Provider-Zugangsdaten oder ein
MCP-Server, die gerade in Betrieb sind, weder auf diese Weise noch deshalb verworfen,
weil ein Key jetzt zu einem leeren Wert aufgelöst wird: Der Reload schlägt fehl, nennt
Entität und Feld, und die laufende Konfiguration – einschließlich dieser Entität –
bleibt in Betrieb. Korrigieren oder löschen Sie die Entität und führen Sie dann
erneut einen Reload aus. Eine bereits übersprungene Entität wird erneut übersprungen
und blockiert den Reload nicht.
Guardrails werden als Gesamtheit geladen und schlagen geschlossen fehl (fail closed):
Der Start schlägt fehl, ein Reload behält die laufende Konfiguration bei, und eine
periodische Aktualisierung behält die vorhandenen Guardrails bei.

Werte, die gespeichert wurden, bevor es Referenzen gab, werden auf dieselbe Weise
gelesen; ein gespeichertes Literal, das `${scheme:...}` enthält, wird also jetzt als
Referenz behandelt. Speichern Sie es mit `$${` erneut, damit es literal bleibt.

Eine Erweiterung kann einen Secret-Writer registrieren. Ein im Dashboard eingegebenes
Literal wird dann im Secret-Manager abgelegt, und nur die Referenz wird gespeichert;
die Secrets des Writers werden gelöscht, wenn ihre Entität oder ihr Feld gelöscht
wird. Ein Speichervorgang, der noch eine geschriebene Referenz enthält, die ihre
Entität nicht mehr speichert – etwa ein Formular, das geöffnet wurde, bevor jemand
anderes dieses Secret ersetzt hat –, wird abgelehnt: Laden Sie neu und speichern Sie
erneut. Das Core-GoModel liefert keinen Writer mit.

## Literales `${`

Schreiben Sie `$${` für ein literales `${`. Aus `pa$${x}` wird `pa${x}`.

## Einschränkungen

* `env`- und `file`-Referenzen werden aufgelöst, wenn die Konfiguration geladen oder
  neu geladen wird; siehe [Rotation](https://gomodel.enterpilot.io/docs/de/advanced/secret-references.md#rotation).
* Sie gelten für String-Einstellungen. Eine boolesche oder numerische Einstellung kann
  keine Referenz sein, und eine Umgebungsvariable, die GoModel als Zahl, booleschen
  Wert, Dauer oder Liste parst (`LOGGING_ENABLED`, `HTTP_TIMEOUT`,
  `ENABLED_PASSTHROUGH_PROVIDERS`, ...), bricht den Start ab, wenn sie eine Referenz
  enthält. JSON-Variablen akzeptieren Referenzen innerhalb ihrer String-Werte.
* Provider-Umgebungsvariablen sind die Ausnahme: `OPENAI_MODELS`,
  `OPENAI_MODEL_FILTER_*` und `OPENAI_SESSION_STICKY_KEYS` werden vor dem Parsen
  aufgelöst.
* Bei im Dashboard verwalteten Entitäten akzeptieren nur die unter
  [Im Dashboard verwaltete Zugangsdaten](https://gomodel.enterpilot.io/docs/de/advanced/secret-references.md#im-dashboard-verwaltete-zugangsdaten) aufgeführten
  Felder Referenzen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.