Referenz zur Konfiguration von tokios-connector.json

Der Tokios Connector bezieht seine Einstellungen aus einer JSON-Konfigurationsdatei. Sie geben die Datei mittels --config an; zudem lässt sich jede Einstellung beim Start mit einem Befehlszeilen-Parameter überschreiben. Der Connector liest niemals Umgebungsvariablen aus und leitet Anfragen ausschließlich an die hier definierten Upstreams weiter – niemals an URLs, die vom Gateway bereitgestellt werden.

Ihre ConnectorId- sowie Token-Daten werden von der Tokios-Konsole bei der Erstellung eines Connectors ausgegeben. Der API-Schlüssel wird nur ein einziges Mal angezeigt – kopieren Sie ihn in Ihre Konfigurationsdatei und bewahren Sie ihn an einem sicheren Ort auf.

Precedence:CLI flags›TOKIOS_* env vars›tokios-connector.json›defaults

Die Konfigurationsdatei

Eine minimale Konfiguration enthält einen Connector-Abschnitt mit Ihren Zugangsdaten sowie einen lokalen Upstream.

tokios-connector.json

{
  "Connector": {
    "ConnectorId": "con_your_connector_id",
    "Token": "ct-your-connector-token",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

Starten Sie den Connector, indem Sie auf diese Datei verweisen:

tokios-connector --config tokios-connector.json

`Connector`-Felder

string

erforderlich

managed by pairingrestart requiredDie ID des Connectors, wie sie in der Konsole angegeben ist (z. B. con_...). Sie dient der eindeutigen Identifizierung des Connectors gegenüber dem Tokios Gateway.

string

erforderlich

managed by pairingsecret — redacted in logsDer API-Schlüssel, der beim Erstellen des Connectors generiert wird (z. B. ct-...); er ist an Ihren Mandanten gebunden. Dieser Schlüssel wird in der Konsole nur ein einziges Mal angezeigt.

string

Der wss://-Gateway-Endpunkt, den der Connector kontaktiert. Standardmäßig wird der gehostete Tokios Gateway-Endpunkt verwendet; normalerweise müssen Sie diesen Wert nicht ändern. Bei selbstgehosteten Deployments wird stattdessen der eigene Server angegeben – etwa wss://your-server/connector/connect.

integer

Standard:"8"

Die maximale Anzahl an gleichzeitig weitergeleiteten Anfragen, die der Connector verarbeiten kann. Überschreitet die Anzahl dieses Limits, werden zusätzliche Anfragen mit dem Status 503 connector_busy abgelehnt, bis wieder Kapazitäten frei werden.

Hier wird festgelegt, welche Dienste der Connector bereitstellt.

Wählen Sie eine der beiden Optionen aus – die Angabe beider ist nicht zulässig. Einzelner Upstream: Ein lokaler Server, der ein oder mehrere Upstream-Modell-IDs bedient.

tokios-connector.json

"Connector": {
  "ConnectorId": "con_...",
  "Token": "ct-...",
  "Models": ["gemma4:e4b"],
  "Upstream": { "BaseUrl": "http://127.0.0.1:11434/v1" }
}

Mehrere Upstreams: Unterschiedliche Modell-IDs werden an verschiedene lokale Server weitergeleitet.

tokios-connector.json

"Connector": {
  "ConnectorId": "con_...",
  "Token": "ct-...",
  "Routes": [
    { "Model": "gemma4:e4b",    "UpstreamId": "ollama" },
    { "Model": "qwen2.5-coder", "UpstreamId": "lmstudio" }
  ],
  "Upstreams": {
    "ollama":   { "BaseUrl": "http://127.0.0.1:11434/v1" },
    "lmstudio": { "BaseUrl": "http://127.0.0.1:1234/v1" }
  }
}

Die IDs in Models bzw. Routes[].Model entsprechen den Modell-IDs, die Ihr lokaler Server verwendet – also den Werten, die Sie direkt an ihn senden würden (z. B. gemma4:e4b bei Ollama). Unter einem öffentlichen API-Namen (z. B. gemma-tunnel) stellen Sie ein Modell über eine Deployment-Registrierung im Dashboard bereit; dieser öffentliche Name wird von Clients im Feld "model" angegeben, und das Gateway wandelt ihn vor der Weiterleitung in die jeweilige Upstream-ID um. Weitere Informationen finden Sie unter Model Routing.

Felder für die Konfiguration der Upstreams

Jeder Upstream – sei es der einzelne Eintrag in Upstream oder alle Einträge unter Upstreams – akzeptiert folgende Angaben:

string

erforderlich

requiredDie Basis-URL Ihres Modell-Servers, inklusive des /v1-Segments – beispielsweise http://127.0.0.1:11434/v1. Der Connector hängt anschließend den Anfragepfad (/chat/completions) an diese URL an. Ihr Server muss eine OpenAI-kompatible Chat Completions API bereitstellen. Weitere Details finden Sie unter Backends.

string[]

Optional: eine Einschränkung hinsichtlich des Hosts. Ist dieses Feld leer (Standard), vertraut der Connector der im Feld BaseUrl angegebenen Host-Adresse – für lokale sowie entfernte Upstreams sind keine weiteren Einstellungen nötig. Ist der Wert nicht leer, muss der Host aus BaseUrl in der Liste enthalten sein; andernfalls schlägt ein späterer Versuch, den Host in BaseUrl zu ändern, beim Start fehl – statt Daten unbemerkt an den neuen Host (und dessen ApiKey) zu senden.

string[]

Anfragepfade, die der Connector weiterleiten darf. Standardwert ist ["/chat/completions"].

Um auf ein Modell auf einem anderen Rechner Ihres Netzwerks zuzugreifen, geben Sie in BaseUrl dessen Adresse an – etwa http://192.168.1.50:11434/v1. Eine explizite Freigabe ist nicht erforderlich: Der Connector leitet Anfragen nur an Hosts weiter, die in seiner Konfiguration vermerkt sind, niemals an URLs, die vom Gateway übermittelt werden. Ältere Konfigurationen enthalten eventuell noch AllowLan; dieser Wert wird vom Connector ignoriert.

Authentifizierung bei einem entfernten Upstream-Server

Um anstelle eines lokalen Servers Daten an einen gehosteten, OpenAI-kompatiblen Anbieter weiterzuleiten, richten Sie BaseUrl auf diesen Anbieter aus und geben Sie die erforderlichen Zugangsdaten für das Upstream-Modell an.

string

Der Schlüssel, der in die Anfrage an den Upstream-Server eingefügt wird.

string

Standard:"Authorization"

Der Header, in dem der Schlüssel übermittelt wird. Verwenden Sie x-api-key für Anbieter im Stil von Anthropic sowie api-key für Azure OpenAI.

string

Standard:"Bearer "

Ein Präfix, das dem Schlüssel vorangestellt wird. Bei Verfahren, bei denen der Schlüssel unverändert verwendet wird, setzen Sie diesen Wert auf eine leere Zeichenfolge (z. B. x-api-key, api-key).

object

Statische Header, die zu jeder Anfrage an den Upstream-Server hinzugefügt werden.

object

Statische Abfrageparameter, die an die Upstream-URL angehängt werden (z. B. der Parameter api-version bei Azure OpenAI).

Befehlszeilen-Parameter

Parameter	Beschreibung
`--config <path>`	Pfad zur Konfigurationsdatei. Ein relativer Pfad wird zunächst vom aktuellen Verzeichnis aus gesucht; anschließend wird das Verzeichnis neben der ausführbaren Datei durchsucht. Falls kein Pfad angegeben ist, sucht der Connector nach `appsettings.json`. Fehlt die Datei trotz Angabe, tritt ein Fehler auf.
`--version`	Gibt die Version des Connectors aus und beendet das Programm. Aliase: `--ver`, `-v`.

Jeder Konfigurationswert lässt sich ebenfalls über die Kommandozeile durch Angabe des vollständigen Schlüsselpfads überschreiben.

tokios-connector --config tokios-connector.json --Logging:LogLevel:Default=Debug

Es existiert kein --log-level-Schalter. Die Ausführlichkeit der Ausgabe lässt sich über den Abschnitt Logging (unten) oder den oben beschriebenen --Logging:LogLevel:Default=...-Überschreibungsmechanismus einstellen.

Protokollierung

Der Connector protokolliert stets in die Konsole. Zur Steuerung der Ausführlichkeit sowie zum Aktivieren optionaler täglicher Protokolldateien dient ein oberster Logging-Abschnitt, der neben Connector steht.

tokios-connector.json

{
  "Logging": {
    "LogLevel": { "Default": "Information" },
    "Directory": "logs",
    "RetainedDays": 7
  },
  "Connector": {
    "ConnectorId": "con_...",
    "Token": "ct-...",
    "Models": ["gemma4:e4b"],
    "Upstream": { "BaseUrl": "http://127.0.0.1:11434/v1" }
  }
}

string

Standard:"Information"

Verfügbare Ausführlichkeitsstufen: Trace, Debug, Information, Warning sowie Error. Bei Fehlerbehebungen empfiehlt sich die Einstellung Debug, um Details zum Routing, zum cid sowie zum Upstream-Modell zu erfassen.

string

Hier lassen sich tägliche Protokolldateien aktivieren; der angegebene Ordner wird bei Bedarf angelegt. Bleibt das Feld leer (Standard), erfolgt ausschließlich die Protokollierung in die Konsole. Ein relativer Pfad bezieht sich auf den Speicherort der Connector-Datei – nicht auf das aktuelle Arbeitsverzeichnis – wodurch die Protokolle stets an derselben Stelle gespeichert werden, selbst wenn der Connector per Doppelklick gestartet wird.

integer

Standard:"14"

Anzahl der zu speichernden täglichen Protokolldateien.

Mit dieser Einstellung wird logs/tokios-connector-YYYYMMDD.log geschrieben.

Vollständiges Beispiel

macOS
Linux
Windows

Konfigurationspfad: ~/Library/Application Support/tokios/tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

Konfigurationspfad: /etc/tokios/tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

Konfigurationspfad: %APPDATA%\tokios\tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

Ausführung als Hintergrunddienst

Zur Entwicklung genügt die Ausführung in einem Terminalfenster. Für einen dauerhaften Betrieb sollte der Connector als Systemdienst laufen, damit er nach einem Neustart automatisch erneut gestartet wird.

macOS (launchd)
Linux (systemd)
Windows (Dienst)

Erstellen Sie eine plist-Datei unter ~/Library/LaunchAgents/com.tokios.connector.plist:

~/Library/LaunchAgents/com.tokios.connector.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.tokios.connector</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/tokios-connector</string>
    <string>--config</string>
    <string>/etc/tokios/tokios-connector.json</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/var/log/tokios-connector.log</string>
  <key>StandardErrorPath</key>
  <string>/var/log/tokios-connector.log</string>
</dict>
</plist>

Laden und starten Sie den Dienst:

launchctl load ~/Library/LaunchAgents/com.tokios.connector.plist
launchctl start com.tokios.connector

Erstellen Sie eine Unit-Datei unter /etc/systemd/system/tokios-connector.service:

/etc/systemd/system/tokios-connector.service

[Unit]
Description=Tokios Connector
After=network.target

[Service]
ExecStart=/usr/local/bin/tokios-connector --config /etc/tokios/tokios-connector.json
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Aktivieren und starten Sie den Dienst:

sudo systemctl daemon-reload
sudo systemctl enable tokios-connector
sudo systemctl start tokios-connector

On Windows, use NSSM (Non-Sucking Service Manager) or Task Scheduler to run the connector as a background service.Verwendung von NSSM:

nssm install TokiosConnector "C:\Program Files\Tokios\tokios-connector.exe"
nssm set TokiosConnector AppParameters "--config C:\ProgramData\Tokios\tokios-connector.json"
nssm set TokiosConnector Start SERVICE_AUTO_START
nssm start TokiosConnector

Verwendung des Aufgabenplaners:Erstellen Sie eine neue Aufgabe, legen Sie den Auslöser auf At startup fest und verweisen Sie die Aktion auf tokios-connector.exe, wobei --config <path> als Argument dient. Aktivieren Sie anschließend Run whether user is logged on or not, damit der Dienst im Hintergrund weiterläuft.

Code	Bedeutung
E1401	Ungültiges oder widerrufenes Connector-Token
E1404	Die Route verweist auf ein unbekanntes Upstream-Modell
E1502	Upstream unreachable — check `BaseUrl` includes `/v1`

Erste Schritte

Modelle

Konzepte

Referenz

Referenz zur Konfiguration von tokios-connector.json

Die Konfigurationsdatei

`Connector`-Felder

Hier wird festgelegt, welche Dienste der Connector bereitstellt.

Felder für die Konfiguration der Upstreams

Authentifizierung bei einem entfernten Upstream-Server

Befehlszeilen-Parameter

Protokollierung

Vollständiges Beispiel

Ausführung als Hintergrunddienst

Verwandte Fehler

​Die Konfigurationsdatei

​Connector-Felder

​Hier wird festgelegt, welche Dienste der Connector bereitstellt.

​Felder für die Konfiguration der Upstreams

​Authentifizierung bei einem entfernten Upstream-Server

​Befehlszeilen-Parameter

​Protokollierung

​Vollständiges Beispiel

​Ausführung als Hintergrunddienst

​Verwandte Fehler

Die Konfigurationsdatei

`Connector`-Felder

Hier wird festgelegt, welche Dienste der Connector bereitstellt.

Felder für die Konfiguration der Upstreams

Authentifizierung bei einem entfernten Upstream-Server

Befehlszeilen-Parameter

Protokollierung

Vollständiges Beispiel

Ausführung als Hintergrunddienst

Verwandte Fehler