Konfiguration

Für den Plattformbetrieb. Diese Aufgaben betreffen die ganze Installation. Du brauchst je nach Aufgabe Serverzugriff oder Plattformrechte. Beginne mit dem Administrationshandbuch.

OpenBot kann als viele Instanzen laufen. Eine Instanz ist ein laufender Prozess des OpenBot-Servers. Alle Instanzen einer Installation nutzen dieselbe Datenbank. Diese Seite listet die wenigen Werte, die jede Instanz beim Start liest. Sie zeigt auch, wo alle anderen Einstellungen liegen.

---

Die Regel

Es gibt zwei Arten von Einstellungen:

• Instanz-Einstellungen gehören zu einer Instanz. Keine andere Instanz braucht denselben Wert. Sie kommen aus Umgebungsvariablen oder aus Dateien in /run/secrets.
• Geteilte Einstellungen müssen auf jeder Instanz gleich sein. Sie liegen in PostgreSQL. Du änderst sie über die API, und jede Instanz nutzt die Änderung sofort.

Es gibt zwei Ausnahmen: OPENBOT_SECRET_KEYS und OPENBOT_CLUSTER_SECRET. Alle Knoten brauchen dieselben Werte. Sie schützen gespeicherte Daten und private Nachrichten zwischen Knoten. Jeder Knoten liest sie aus seiner Umgebung oder aus Dateien mit Geheimnissen.

Wenn ein nötiger Wert fehlt oder falsch ist, startet OpenBot nicht. Es schreibt einen Fehler zur Konfiguration ins Log.

---

Instanz-Einstellungen

Das ist die vollständige Liste der Umgebungsvariablen, die der Server liest.

Variable	Pflicht	Standard	Bedeutung
OPENBOT_HOST	Nein	127.0.0.1	Die Netzwerk-Adresse, auf der der Server lauscht.
OPENBOT_PORT	Nein	3000	Der Port, auf dem der Server lauscht.
OPENBOT_CLUSTER_SECRET	Ja		Das gemeinsame Geheimnis für private RPC. Mindestens 32 Zeichen.
OPENBOT_CLUSTER_HOST	Nein	Gebundene Adresse	Der Host, den andere Knoten am Server-Port erreichen.
OPENBOT_DATABASE_URL	Ja		Eine URL für die Verbindung zu PostgreSQL.
OPENBOT_SECRET_KEYS	Ja		Die Schlüssel, die Geheimnisse in der Datenbank verschlüsseln. Siehe unten.
OPENBOT_OUTBOUND_ALLOW	Nein		Private Hosts und IP-Bereiche, mit denen OpenBot sich verbinden darf. Siehe unten.

Das Docker-Image setzt OPENBOT_HOST=0.0.0.0 und OPENBOT_PORT=3000. So kann der Server Verkehr von außerhalb des Containers annehmen.

Private Aufrufe zwischen Knoten nutzen /internal/executions/rpc. Halte diesen Pfad im privaten Netzwerk. Alle Knoten nutzen dasselbe zufällige Geheimnis. Gib bei mehreren Knoten jedem Knoten einen eigenen erreichbaren Host. Der private RPC-Client ist vom Schutz des App-Netzwerks getrennt.

Datenbank

OPENBOT_DATABASE_URL sieht so aus: postgres://openbot:secret@db.example.com:5432/openbot. Der Server, das Migrations-Programm und das Setup-Programm lesen sie alle.

Wenn der Server startet, prüft er, ob alle Tabellen da sind. Wenn sie fehlen, hört er auf. Führe zuerst das Migrations-Programm aus. Siehe Deploy.

TLS

OpenBot liefert nur einfaches HTTP. Es hat kein eigenes HTTPS. Um HTTPS anzubieten, setze einen Reverse Proxy davor, zum Beispiel Caddy oder nginx. Der Proxy hat das Zertifikat und schickt den Verkehr an OpenBot. Siehe Deploy.

Ausgehende Verbindungen

OpenBot verbindet sich mit Adressen, die Menschen ihm geben. Beispiele sind Endpunkte von Model Providern, SSO-Aussteller, eigene Channels und Apps. Ein Angreifer könnte so dein eigenes Netzwerk erreichen. Dieser Angriff heißt Server-Side Request Forgery (SSRF).

Darum verbindet sich OpenBot nur mit öffentlichen Adressen. Es sperrt diese Ziele:

• Loopback-Adressen, zum Beispiel 127.0.0.1, ::1 und localhost,
• private Netzwerke, zum Beispiel 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 und fc00::/7,
• Link-Local-Adressen und Metadaten-Dienste von Clouds, zum Beispiel 169.254.169.254,
• andere besondere Bereiche, zum Beispiel geteilte, Test-, Multicast- und reservierte Bereiche.

OpenBot prüft die echte Adresse jeder neuen Verbindung, nach der DNS-Abfrage. Es prüft auch jede Weiterleitung. Ein Host-Name, der auf eine private Adresse zeigt, ist auch gesperrt.

Um ein privates Ziel bewusst zu öffnen, schreibe es in OPENBOT_OUTBOUND_ALLOW. Trenne die Einträge mit Kommas. Jeder Eintrag ist eines davon:

Eintrag	Beispiel	Was er öffnet
Eine IP-Adresse	127.0.0.1, ::1	Genau diese eine Adresse.
Ein IP-Bereich	10.20.0.0/16, fd00::/8	Jede Adresse im Bereich, für jeden Host-Namen.
Ein Host-Name	localhost, ollama.internal	Genau diesen Namen, egal auf welche Adresse er zeigt. Keinen anderen Namen.

Es gibt keine Platzhalter und keine Ports. Wenn ein Eintrag falsch ist, startet OpenBot nicht.

# Ein Model-Server auf derselben Maschine und ein internes Netzwerk.
OPENBOT_OUTBOUND_ALLOW=localhost,10.20.0.0/16

Hinweis

Die Liste öffnet ein Ziel für jede ausgehende Verbindung, auch für die Apps, die Mitglieder hinzufügen. Schreibe nur die Hosts hinein, die du brauchst. Schreibe nie eine Metadaten-Adresse einer Cloud hinein. Gib jeder Instanz dieselbe Liste.

Wenn OpenBot eine Verbindung sperrt, nennen der Fehler und das Log den Host und OPENBOT_OUTBOUND_ALLOW.

---

Geheime Schlüssel

OpenBot speichert manche Geheimnisse in der Datenbank. Es verschlüsselt sie mit den Schlüsseln in OPENBOT_SECRET_KEYS. Diese Geheimnisse sind:

• die privaten Daten von App-Connections, zum Beispiel Zugangsdaten von Apps, private Einstellungen und der Zustand der Anmeldung,
• die API-Schlüssel von Model Providers,
• die Client-Secrets von SSO-Verbindungen,
• das Anmelde-Geheimnis der Platform, das die Anmelde-Cookies signiert,
• das Client-Secret des OpenID-Connect-Anbieters der Platform.

OPENBOT_SECRET_KEYS ist eine Liste von Schlüsseln, getrennt durch Kommas:

OPENBOT_SECRET_KEYS=k2:<64 hexadecimal characters>,k1:<64 hexadecimal characters>

• Jeder Eintrag ist <id>:<key>.
• Der Schlüssel hat genau 64 hexadezimale Zeichen (32 Bytes).
• Die ID hat 1 bis 32 Zeichen. Sie kann Kleinbuchstaben, Ziffern, _ und - enthalten.
• Der erste Schlüssel verschlüsselt neue Geheimnisse.
• Jeder Schlüssel in der Liste kann entschlüsseln. OpenBot speichert die ID des Schlüssels neben jedem Geheimnis. So weiß es, welchen Schlüssel es nutzen muss.

Erstelle einmal einen Schlüssel:

echo "k1:$(openssl rand -hex 32)"

Gib jeder Instanz dieselbe Liste. Bewahre die Schlüssel zusammen mit deinen Backups der Datenbank auf. Wenn du sie verlierst, kann OpenBot die Geheimnisse in der Datenbank nicht lesen.

Die Schlüssel wechseln

Du kannst einen neuen Schlüssel hinzufügen, ohne die alten Geheimnisse zu verlieren:

1. Erstelle einen neuen Schlüssel, zum Beispiel k2.
2. Setze ihn an den Anfang der Liste und behalte den alten Schlüssel dahinter: k2:<new>,k1:<old>.
3. Gib die neue Liste jeder Instanz und starte sie neu.

OpenBot verschließt neue Geheimnisse jetzt mit k2. Geheimnisse, die k1 verschlossen hat, lassen sich weiter öffnen. Behalte den alten Schlüssel in der Liste, solange die Datenbank Geheimnisse enthält, die er verschlossen hat.

Achtung

Halte OPENBOT_SECRET_KEYS aus der Versionsverwaltung heraus. Jeder mit den Schlüsseln und einer Kopie der Datenbank kann jedes gespeicherte Geheimnis lesen.

---

Geheimnisse als Dateien

Wenn eine Umgebungsvariable nicht gesetzt ist, liest OpenBot stattdessen die Datei /run/secrets/<NAME>. Zum Beispiel liest es OPENBOT_SECRET_KEYS aus /run/secrets/OPENBOT_SECRET_KEYS. Docker und Compose legen Geheimnisse in diesen Ordner.

• Eine Umgebungsvariable kommt immer zuerst, auch wenn die Datei da ist.
• OpenBot entfernt Leerzeichen und Zeilenumbrüche am Anfang und Ende der Datei.
• Eine leere Datei zählt als nicht gesetzt. Eine fehlende Datei oder ein fehlender Ordner zählt auch als nicht gesetzt.

Das funktioniert für jede Variable auf dieser Seite. Am nützlichsten ist es für Geheimnisse. Denn Umgebungsvariablen erscheinen in docker inspect, Dateien nicht.

---

Erstes Setup

Eine neue Datenbank hat keine geteilten Einstellungen. Bevor Menschen OpenBot nutzen können, führst du einmal das Setup-Programm aus. Es schreibt die ersten Einstellungen der Platform und die ersten Admins der Platform.

Bis dahin startet der Server, aber jede Route außer /health antwortet mit 503 und diesem Body:

{ "_tag": "SetupRequired" }

Das Log sagt dir auch, dass du das Setup ausführen sollst. Alle Flags findest du unter Platform, die Befehle unter Deploy.

---

Wo alle anderen Einstellungen liegen

Jede andere Einstellung ist eine geteilte Einstellung in der Datenbank. Zwei Dokumente enthalten die meisten davon:

• Die Einstellungen der Platform unter /v1/platform/settings. Nur Admins der Platform können sie ändern. Siehe Platform.
• Die Einstellungen der Organization unter /v1/organization/settings. Jede Organization hat ihre eigenen. Siehe Organization.

Ältere Versionen von OpenBot haben mehr Umgebungsvariablen gelesen. OpenBot ignoriert sie jetzt. Diese Tabelle zeigt, wohin jeder Wert gewandert ist:

Alte Variable	Neuer Ort
OPENBOT_PUBLIC_ORIGIN	publicOrigin in den Einstellungen der Platform. Das Setup schreibt ihn mit --public-origin.
OPENBOT_OIDC_ISSUER	identityProvider.issuer in den Einstellungen der Platform. Das Setup schreibt ihn mit --oidc-issuer.
OPENBOT_OIDC_CLIENT_ID	identityProvider.clientId in den Einstellungen der Platform. Das Setup schreibt ihn mit --oidc-client-id.
OPENBOT_OIDC_CLIENT_SECRET	identityProvider.clientSecret in den Einstellungen der Platform, verschlüsselt. Das Setup schreibt ihn mit --oidc-client-secret.
BETTER_AUTH_SECRET	Das Anmelde-Geheimnis. Das Setup erstellt ein zufälliges und speichert es verschlüsselt. Du setzt es nie.
OPENBOT_APP_ENCRYPTION_KEY	OPENBOT_SECRET_KEYS.
OPENBOT_OWNER_EMAILS	Admins der Platform. Das Setup fügt sie mit --admin-email hinzu. Ändere sie mit /v1/platform/admins.
OPENBOT_ALLOWED_EMAIL_DOMAINS	Bestätigte Domains jeder Organization, mit joinByDomain in ihren Einstellungen. Siehe SSO.
OPENBOT_MODEL_ENDPOINT	Model Providers einer Organization oder der Platform. Siehe Models.
OPENBOT_MODEL_API_KEY	Model Providers, verschlüsselt.
OPENBOT_MODEL_ID	Ein Model, das ein Model Provider verknüpft, und das model jedes Bots.
OPENBOT_DEV_MODE	Der Einstiegspunkt für die Entwicklung entscheidet. Siehe Entwicklung.

Manche Werte waren früher Optionen im Code. Sie sind jetzt auch Einstellungen:

Alte Option	Neuer Ort
appRestrictions	appRestrictions in den Einstellungen der Platform.
appReadRules	appReadRules in den Einstellungen der Organization.
bots.helperModel	rulesModel und botMemoryModel in den Einstellungen der Organization.
bots.requestTimeout	requestTimeoutMs in den Einstellungen der Organization.
bots.memory	botMemory in den Einstellungen der Organization.
sessions.memory.defaults	Nichts. Das gelernte Memory jeder Session gibt es nicht mehr.
allowedEmailDomains, defaultRoles (API)	Bestätigte Domains, und defaultRoles in den Einstellungen der Organization.

Wie eine Änderung jede Instanz erreicht

Jeder Lesezugriff nutzt die gespeicherte Datenbankzeile. Eine Änderung läuft so ab:

1. Die API schreibt die neuen Einstellungen in einer Transaktion.
2. Beim Commit sendet PostgreSQL NOTIFY auf openbot_settings.
3. Abonnenten reagieren auf die Nachricht. Auch ohne Nachricht sieht der nächste Lesezugriff die gespeicherte Zeile.

Kein lokaler Cache hält alte Zugriffsrechte fest. Wenn das Lesen scheitert, scheitert auch die Aktion. App-Beschränkungen werden bei einem Datenbankfehler nicht leer. Eine Liste liest einen Stand der Regeln für alle ihre Einträge.

Wenn die Verbindung zum Zuhören abbricht, wird der Fehler protokolliert. Nach einer Sekunde startet das Zuhören erneut. Lesezugriffe nutzen weiter die Datenbank.

Eine Änderung an publicOrigin, am Identitäts-Anbieter der Platform oder am Anmelde-Geheimnis ändert, wie die Anmeldung funktioniert. Jede Instanz liest diese Werte, wenn sie sie braucht. So nutzt schon der nächste Request die neuen Werte. Die Anmeldung bekommt dafür einen neuen Aufbau, und der alte schließt einige Minuten nach seinem letzten Request. Nichts startet neu: laufende Requests und Turns gehen weiter.

---

Compose für den Betrieb

Die Compose-Datei deploy/docker/compose.production.yaml liest diese Variablen. Nur OPENBOT_DATABASE_URL, OPENBOT_SECRET_KEYS und OPENBOT_OUTBOUND_ALLOW kommen bei OpenBot an.

Variable	Pflicht	Standard	Bedeutung
POSTGRES_PASSWORD	Ja		Das Passwort des PostgreSQL-Nutzers openbot. Nutze Zeichen, die in URLs sicher sind.
OPENBOT_DATABASE_URL	Ja		Die Vorlage füllt sie aus POSTGRES_PASSWORD aus.
OPENBOT_SECRET_KEYS	Ja		Die geheimen Schlüssel. Siehe Geheime Schlüssel.
OPENBOT_OUTBOUND_ALLOW	Nein		Private Ziele, die offen sein sollen. Siehe Ausgehende Verbindungen.
OPENBOT_RELEASE	Ja		Das Tag des Image, das laufen soll.
OPENBOT_PUBLISHED_PORT	Nein	8080	Der Port auf 127.0.0.1, an dem dein Reverse Proxy OpenBot findet.
PROTOCOL_TEST_PUBLIC_ORIGIN	Ja		Der öffentliche HTTPS-Ursprung des Test-Dienstes für das Protokoll.
PROTOCOL_TEST_ALLOWED_ORIGINS	Nein	PROTOCOL_TEST_PUBLIC_ORIGIN	Browser-Ursprünge, die der Test-Dienst für das Protokoll annimmt.

Die Compose-Datei gibt OPENBOT_DATABASE_URL und OPENBOT_SECRET_KEYS als Dateien in /run/secrets an OpenBot. OPENBOT_OUTBOUND_ALLOW gibt sie als Umgebungsvariable. Der Dienst openbot hat keine anderen Umgebungsvariablen. Siehe Deploy. Eine vollständige Vorlage liegt in deploy/docker/production.env.example.

---

Entwicklung

devenv shell -- pnpm dev:setup erstellt die Datei .env.development aus .env.development.example. Es füllt OPENBOT_SECRET_KEYS mit einem neuen zufälligen Schlüssel namens dev.

Variable	Standard	Bedeutung
OPENBOT_SECRET_KEYS		dev:<random key>. dev:setup füllt ihn aus.
OPENBOT_DEV_DATABASE_NAME	openbot	Der Name der Datenbank für die Entwicklung.

Hinweis

Wenn deine .env.development aus einer älteren Version stammt, lösche sie und führe devenv shell -- pnpm dev:setup noch einmal aus. Du kannst auch die Datenbank für die Entwicklung zurücksetzen. Siehe Mitwirken.

devenv setzt dann diese Werte für dich. devenv wählt jeden Port selbst: Es beginnt beim Basis-Port und nimmt den nächsten freien Port. Die Werte mit einem Port gibt es nur dem OpenBot-Prozess, nicht devenv shell.

Variable	Wert
OPENBOT_DEV_PUBLIC_ORIGIN	http://localhost
OPENBOT_HOST	127.0.0.1
OPENBOT_PORT	ein freier Port, ab 3000
OPENBOT_DATABASE_URL	postgres://openbot_dev:openbot_dev@127.0.0.1:<port>/openbot, mit einem freien Port ab 5433
OPENBOT_DEV_S3_ENDPOINT	http://127.0.0.1:<port>, mit einem freien Port ab 9000
OPENBOT_DEV_S3_BUCKET	openbot

Der Proxy von devenv liefert OpenBot unter http://localhost, auf Port 80. Die Entwicklung braucht kein HTTPS. Browser und curl behalten das sichere Anmelde-Cookie auf localhost, auch ohne HTTPS.

Der Proxy lauscht auf Port 80. Wenn ein anderes Programm ihn nutzt, gib dem Proxy in deiner Shell einen anderen Port, zum Beispiel DEVENV_PROXY_LISTEN=127.0.0.1:8080. Setze dann OPENBOT_DEV_PUBLIC_ORIGIN=http://localhost:8080 in .env.development. Mit einem Port über 1023 braucht der Proxy kein sudo.

Nur der Einstiegspunkt für die Entwicklung liest OPENBOT_DEV_PUBLIC_ORIGIN. Er braucht keinen Setup-Schritt. Bei jedem Start schreibt er die Einstellungen der Platform für diesen Ursprung selbst. Er macht das lokale Konto developer@localhost.test zum Admin der Platform und schaltet die lokale Test-Anmeldung ein. Siehe Authentifizierung.

Das Programm für den Betrieb nutzt nie das lokale Test-Konto. Es gibt keinen Schalter dafür.

Der Entwicklungs-Server sperrt private Ziele auch. Um einen Model-Server auf deiner Maschine zu nutzen, zum Beispiel Ollama, setze OPENBOT_OUTBOUND_ALLOW=localhost in .env.development. Siehe Ausgehende Verbindungen.

devenv startet auch RustFS, einen kleinen Objektspeicher, für Dateien. Es läuft in Docker. Seine Daten liegen im Docker-Volume openbot-dev-rustfs. Bei jedem Start macht der Einstiegspunkt für die Entwicklung den Bucket openbot und schreibt den Speicher in die Einstellungen der Platform. RustFS ist auf 127.0.0.1, einer privaten Adresse. Darum öffnet der Einstiegspunkt für die Entwicklung diesen einen Host für sich selbst. Du musst ihn nicht zu OPENBOT_OUTBOUND_ALLOW hinzufügen.

Um eine andere Datenbank zu nutzen, setze OPENBOT_DATABASE_URL in .env.development. Siehe Mitmachen.

---

Beispiel

Das ist eine vollständige Umgebungsdatei für den Betrieb einer Instanz:

OPENBOT_DATABASE_URL=postgres://openbot:secret@db.example.com:5432/openbot
OPENBOT_SECRET_KEYS=k1:<output of openssl rand -hex 32>

Jede andere Einstellung kommt aus dem Setup-Programm und der API.