Octop selbst hosten: KI-Assistent für mehrere Benutzer

Was Octop ist und warum Sie es selbst hosten sollten

Octop ist ein selbst gehosteter KI-Assistent für einen Haushalt oder ein kleines Team. Der Grund, Octop statt einer einfachen Chat-Oberfläche selbst zu hosten, besteht in der Trennung der Benutzer voneinander. Open WebUI stellt eine Browser-Oberfläche vor einem Modell bereit. Octop ergänzt Benutzerkonten mit einer Administratorrolle, einem privaten Arbeitsbereich und einem eigenen Satz an Zugangsdaten für jeden Benutzer sowie eine Bibliothek spezialisierter Agenten, zwischen denen jeder Benutzer je nach Aufgabe wechseln kann. Dadurch kann ein VPS fünf Personen statt nur einer bedienen.

Das Projekt befindet sich unter github.com/TencentCloud/Octop. Es handelt sich um einen einzelnen Prozess, der ein Web-Dashboard, eine Befehlszeilenschnittstelle, Chat-Kanäle (Feishu, DingTalk, QQ, Discord, WeCom) und geplante Aufgaben bereitstellt. Alle diese Funktionen verwenden eine gemeinsame SQLite-Datenbank unter ~/.octop/. Die folgenden Schritte beziehen sich auf den Tag v0.9.19, der am 5 August 2026 veröffentlicht wurde. Wenn Sie noch zwischen Plattformen entscheiden, behandelt der Vergleich von Open-WebUI-Alternativen, die Sie auf einem VPS betreiben können die gesamte Auswahl.

Bevor Sie einen Abend dafür einplanen, sollten Sie einen Punkt kennen. Octop ist eine Pre-1.0-Software, die aus der GitHub-Organisation eines Anbieters veröffentlicht wird und im August 2026 etwa 900 Sterne hatte. Die Entwicklung verläuft schnell, wie die Versionsnummern zeigen. Eine stabile Upgrade-Route ist daher nicht zugesichert. Fixieren Sie einen Tag, lesen Sie das Änderungsprotokoll und erstellen Sie Backups.

Voraussetzungen

• Ein VPS mit Ubuntu 24.04, Docker Engine und dem Compose-Plugin. Sie kennen Compose noch nicht? Beginnen Sie mit den Docker-Compose-Grundlagen für einen VPS.
• git, weil Sie ein Release-Tag auschecken und kein Image abrufen.
• Ein Domainname, der auf den VPS zeigt, weil Sie davor TLS (Transport Layer Security) einsetzen möchten.
• Ein Modell-Backend, das die OpenAI-API unterstützt: ein lokales Ollama, ein selbst gehostetes Gateway oder ein kostenpflichtiger API-Schlüssel.

Octop selbst benötigt nur wenige Ressourcen. Es besteht aus einem Python-Prozess und einer SQLite-Datei. Die meiste Leistung benötigt das Modell-Backend. Wenn Sie das Modell auf demselben System ausführen möchten, wählen Sie die Größe des Systems entsprechend dem Modell.

Warum wir das curl-Installationsskript nicht empfehlen

Die README beginnt mit einer einzeiligen Installation:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Wir empfehlen diese Methode nicht auf einem Server, der Ihnen wichtig ist. Der konkrete Grund: Das Skript befindet sich nicht im Repository. Es wird aus einem Tencent Cloud Object Storage-Bucket bereitgestellt. Es ist weder durch einen Git-Tag noch durch einen Commit abgedeckt. Sie können das aktuelle Skript daher nicht mit dem Skript der Vorwoche vergleichen. Außerdem gibt es keine Historie, die eine Änderung erklärt. Der Bucket kann morgen andere Bytes ausliefern, ohne dass dies im Projekt dokumentiert wird. Wenn Sie das Ergebnis direkt an bash weiterleiten, führt der Rechner das Skript außerdem aus, bevor Sie auch nur eine Zeile gelesen haben.

Das Installationsprogramm schreibt außerdem direkt auf den Host und nicht in einen Container. Es verwendet uv, um Python 3.12 abzurufen und eine Umgebung zu erstellen, von der Ihr Paketmanager nichts weiß. Wenn Sie diese Umgebung später entfernen möchten, müssen Sie dies manuell erledigen.

Es gibt zwei bessere Optionen. Rufen Sie das Skript ab, lesen Sie es und führen Sie es anschließend aus. Das dauert dreißig Sekunden: zuerst curl -fsSL <url> -o install.sh, dann less install.sh und anschließend bash install.sh. Oder verwenden Sie Docker. Darum geht es im restlichen Teil dieser Anleitung. Das PyPI-Paket (pip install octop) ist zumindest ein versioniertes Artefakt, das Sie auf eine bestimmte Release-Version festlegen können.

Octop mit Docker Compose bereitstellen, fest auf v0.9.19 gesetzt

Stand August 2026 gibt es kein veröffentlichtes Image zum Abrufen. Die mitgelieferte Compose-Datei erstellt das Image aus dem Repository. Eine Versionsfixierung bedeutet daher, ein git-Tag auszuchecken. Das ist ein zusätzlicher Schritt gegenüber den meisten Self-Hosting-Projekten. Bei einem selbst gehosteten AFFiNE-Arbeitsbereich wird beispielsweise ein veröffentlichtes Image-Tag festgelegt, und auf Ihrem VPS wird nichts erstellt. Die folgende Routine zum Klonen, Auschecken und Erstellen entspricht dem Ablauf im Bereitstellungsleitfaden für openGym. Wenn Sie diesen einmal eingerichtet haben, kennen Sie den grundsätzlichen Ablauf bereits.

git clone https://github.com/TencentCloud/Octop.git
cd Octop
git checkout v0.9.19

Dies ist der vom File definierte Dienst, gekürzt auf die relevanten Teile:

services:
  octop:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    image: octop:latest
    container_name: octop
    restart: unless-stopped
    ports:
      - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
    volumes:
      - ${OCTOP_DATA:-~/.octop}:/data/.octop
    environment:
      - HOME=/data
      - OCTOP_BIND_HOST=0.0.0.0
      - OCTOP_PORT=${OCTOP_PORT:-8088}
      - OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:-octop}
      - OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}

Beachten Sie den Block build:. image: octop:latest ist der Name Ihres selbst erstellten Images und kein Verweis auf eine Registry. latest steht hier daher für die zuletzt kompilierte Version. Legen Sie den Datenpfad explizit fest, statt den Standardwert zu verwenden. Vergeben Sie außerdem vor dem ersten Start ein echtes Passwort für das Administratorkonto. Tragen Sie dies in docker/.env ein:

OCTOP_PORT=8088
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=<a long random password>
OCTOP_DATA=/srv/octop-data

Ein Punkt ist wichtiger als der Rest der Datei. Compose liest docker/.env nur ein, um ${...}-Platzhalter in der YAML-Datei zu ersetzen. Ein Schlüssel, den Sie dort hinzufügen, wird nicht an den Container übergeben, wenn er nicht auch unter environment: in der Compose-Datei aufgeführt ist. Wenn Sie OCTOP_ACCESS_TOKEN_TTL nur zu .env hinzufügen, hat das keinerlei Wirkung. Dies geschieht außerdem ohne Fehlermeldung. Alternativ können Sie dieselben Schlüssel in ~/.octop/env im eingebundenen Datenverzeichnis eintragen. Octop lädt diese Datei beim Start. Der Leitfaden zu Env-Dateien und Secrets in Docker Compose erklärt, warum diese beiden Mechanismen nicht identisch sind.

Erstellen und starten Sie den Dienst:

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml ps
curl http://127.0.0.1:8088/api/health

Eine funktionierende Instanz beantwortet die Health-Prüfung mit {"status":"ok","version":"..."}. Bei jedem anderen Ergebnis lesen Sie docker compose -f docker/docker-compose.yml logs -f octop, bevor Sie den Browser verwenden.

Geben Sie dem soeben erstellten Image nun einen aussagekräftigen Namen. Der nächste --build überschreibt octop:latest. Andernfalls können Sie die beiden Images nicht unterscheiden:

docker image tag octop:latest octop:0.9.19

Beim ersten Start wird octop init ausgeführt und schreibt die Zugangsdaten für den Start in das Daten-Volume:

docker exec -it octop cat /data/.octop/credential.txt

Die Standardwerte sind admin / octop. Sie werden nur bei der ersten Initialisierung angewendet. Das erklärt eine häufig gestellte Frage: Wenn Sie OCTOP_DEFAULT_PASSWORD ändern, nachdem der Container bereits einmal gestartet wurde, hat dies keine Wirkung, weil das Konto bereits existiert. Ändern Sie das Passwort stattdessen im Dashboard.

Veröffentlichen Sie Port 8088 nicht

Die obige Zeile ports: bindet an jede Schnittstelle auf dem VPS. Sobald der Container startet, ist das Dashboard unverschlüsselt und mit einem Standardpasswort im öffentlichen Internet erreichbar. Octops eigener Standardwert für OCTOP_BIND_HOST ist 127.0.0.1. Die Compose-Datei überschreibt ihn mit 0.0.0.0, weil der Prozess Datenverkehr von außerhalb seines eigenen Netzwerk-Namespace annehmen muss. Diese Überschreibung ist korrekt. Der veröffentlichte Port ist der Teil, der den Zugriff ermöglicht.

Bearbeiten Sie die Zeile ports: in docker/docker-compose.yml so, dass die Zuordnung nur auf dem Loopback-Interface lauscht:

    ports:
      - "127.0.0.1:${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"

Versuchen Sie nicht, das mit einer einfachen Override-Datei zu beheben. Compose führt die ports-Listen aus mehreren Dateien zusammen, anstatt sie zu ersetzen. Dadurch veröffentlichen Sie beide Zuordnungen, und die zweite kann nicht gebunden werden. Wenn Sie die Upstream-Datei unverändert lassen möchten, verwenden Sie das Tag !override für die Sequenz. Das ist die dokumentierte Methode, um eine Sequenz zu ersetzen, statt sie zu erweitern. Die Erklärung zum Zusammenführen mehrerer Compose-Dateien behandelt die übrigen Regeln für das Zusammenführen.

Das Binden an das Loopback-Interface behebt außerdem ein Problem, das andernfalls mit der Firewall auftreten würde. Docker schreibt seine Regeln für veröffentlichte Ports in die nat-Tabelle, und zwar vor den von ufw verwalteten Ketten. Daher verhindert ufw deny 8088 den Zugriff auf einen veröffentlichten Container-Port nicht. Ein an 127.0.0.1 gebundener Port ist unabhängig von der Konfiguration von ufw von außen nicht erreichbar. Deshalb ist dies die richtige Lösung und kein nachrangiger Workaround.

TLS mit einem Reverse Proxy vorschalten

Caddy ist der kürzeste Weg, weil es das Zertifikat selbst über ACME (automatic certificate management environment) anfordert und WebSockets ohne zusätzliche Konfiguration proxyt:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx erfordert mehr Sorgfalt, weil Octop den Chat über ein WebSocket überträgt:

server {
    listen 443 ssl;
    server_name octop.example.com;

    ssl_certificate     /etc/letsencrypt/live/octop.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/octop.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Jede Zeile erfüllt dort eine bestimmte Aufgabe. Der Chat läuft über WS /agents/{id}/chat/ws. Ohne proxy_http_version 1.1 und die beiden Upgrade-Header beantwortet nginx den Upgrade-Versuch mit 400 Bad Request: Das Dashboard wird normal geladen, aber jede gesendete Nachricht bleibt ohne Fehlermeldung auf der Seite hängen. proxy_buffering off ist erforderlich, weil der Resume-Endpunkt für human-in-the-loop text/event-stream zurückgibt. SSE (server-sent events), die in einem Proxy-Puffer zurückgehalten werden, treffen sonst gesammelt am Ende ein, statt fortlaufend übertragen zu werden. proxy_read_timeout deckt lange Tool-Läufe ab. Der Standardwert von 60 Sekunden beendet einen Agenten sonst mitten in der Aufgabe und schreibt upstream timed out (110: Connection timed out) in die Logs.

Wie sich JWT-Authentifizierung hinter dem Proxy verhält

Octop authentifiziert sich mit einem Bearer-Token, nicht mit einem Cookie. POST /api/auth/login gibt {access_token, role, user, ...} zurück, und bei späteren Anfragen wird Authorization: Bearer <access_token> mitgesendet. Für einen Reverse Proxy ist das eine gute Nachricht: Es gibt keine Cookie-Domain, kein Secure-Flag und keine SameSite-Regel, die falsch konfiguriert werden könnte. Daher verhält sich eine Sitzung, die auf http://127.0.0.1:8088 funktioniert hat, auf https://octop.example.com genauso.

Zwei Folgen sollten Sie kennen, bevor Sie echte Benutzer darauf zugreifen lassen.

Der WebSocket überträgt das Token in der URL. Der Endpunkt lautet WS /agents/{id}/chat/ws?token=<jwt>, weil JavaScript im Browser beim WebSocket-Handshake keinen Authorization-Header setzen kann. TLS schützt dieses Token bei der Übertragung. Es schützt das Token jedoch nicht vor Ihren eigenen Logs: nginx schreibt standardmäßig die vollständige Request-Zeile einschließlich Query-String nach access_log. Dadurch landet ein gültiges Token eines echten Benutzers in einer Klartextdatei auf dem Server. Protokollieren Sie den Pfad ohne die Argumente. $uri ist der normalisierte Pfad, bei dem der Query-String bereits entfernt wurde. Tragen Sie daher Folgendes in den http-Block ein und referenzieren Sie ihn vom Server aus:

log_format octop_noargs '$remote_addr [$time_local] '
                        '"$request_method $uri $server_protocol" '
                        '$status $body_bytes_sent';
access_log /var/log/nginx/octop.log octop_noargs;

Es gibt keine Abmeldung pro Sitzung. OCTOP_ACCESS_TOKEN_TTL ist standardmäßig auf 86400 gesetzt. Daher bleibt ein Token nach der Anmeldung 24 Stunden lang gültig. Die einzige dokumentierte Möglichkeit, ein einzelnes Token ungültig zu machen, ist octop admin rotate-jwt-secret. Dieser Befehl rotiert den unter ~/.octop/secrets/jwt_secret gespeicherten Signaturschlüssel und macht alle noch gültigen Tokens sofort ungültig, für alle Benutzer. Wenn jemand das Team verlässt, lautet die Reihenfolge daher: Löschen Sie den Benutzer, rotieren Sie das Secret und fordern Sie die verbleibenden Benutzer anschließend auf, sich erneut anzumelden. Falls das zu aufwendig ist, verkürzen Sie die Gültigkeitsdauer. Denken Sie daran, die Variable sowohl in die Liste environment: als auch in .env aufzunehmen:

OCTOP_ACCESS_TOKEN_TTL=28800

Brute-Force-Angriffe werden behandelt: OCTOP_LOGIN_MAX_ATTEMPTS steht standardmäßig auf 5 Fehlversuchen und OCTOP_LOGIN_LOCKOUT_SECONDS auf 900. Ein gesperrter Benutzer wartet daher einfach fünfzehn Minuten, statt von einer fehlerhaften Installation auszugehen. Octop hat eine eigene Benutzerverwaltung und bietet in v0.9.19 keine dokumentierte OIDC-Unterstützung. Wenn Sie echtes Single Sign-on benötigen, setzen Sie einen authentifizierenden Proxy davor. Dafür eignet sich ein selbst gehosteter Authentik-Server.

Octop mit einem Modell-Backend verbinden

Provider werden pro Agent im Dashboard konfiguriert. octop provider list zeigt Ihnen die aktuelle Konfiguration. Octop enthält Voreinstellungen für OpenAI-kompatible APIs, DashScope (Qwen) und Ollama. Die Zugangsdaten werden in der Tabelle providers Ihrer eigenen SQLite-Datenbank gespeichert. Die Auswahl bestimmt, welche Kosten entstehen und welche Daten den Server verlassen.

Ein lokales Modell mit Ollama. Der Server verlässt nicht den Rechner. Sie zahlen stattdessen mit RAM statt mit Tokens. Ein wichtiges Detail bei der Verbindung wird häufig übersehen: Ein Container kann Ollama auf dem Host unter 127.0.0.1:11434 nicht erreichen, weil diese Adresse auf die Loopback-Schnittstelle des Containers selbst zeigt. Fügen Sie dem Dienst einen Host-Gateway-Eintrag hinzu:

    extra_hosts:
      - "host.docker.internal:host-gateway"

Setzen Sie anschließend die Basis-URL des Providers auf http://host.docker.internal:11434/v1. Das ist der OpenAI-kompatible Pfad von Ollama. Tragen Sie im API-Key-Feld eine beliebige nicht leere Zeichenfolge ein. Ollama ignoriert diesen Wert, aber OpenAI-Clients verweigern das Senden eines leeren API-Keys. Ollama muss außerdem über die Loopback-Schnittstelle hinaus lauschen. Dazu muss OLLAMA_HOST=0.0.0.0:11434 in der systemd-Unit gesetzt werden. Dieser Teil ist riskant: Ollama bietet keine Authentifizierung. Ein offener Port 11434 auf einer öffentlichen IP-Adresse stellt daher jedem, der ihn zuerst scannt, kostenlos einen Modellserver bereit. Erlauben Sie nur den privaten Docker-Adressbereich sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp und verweigern Sie den übrigen Verkehr. Ollama auf einem VPS betreiben behandelt die Dimensionierung des Modells. Der Vergleich von Ollama und vLLM erklärt, wann Ollama nicht mehr der passende Server ist.

Noch ein Hinweis zu lokalen Modellen, weil das wie ein Fehler in Octop aussieht, aber keiner ist. Agents arbeiten, indem sie Tools aufrufen. System-Prompt, Tool-Definitionen und Verlauf ergeben zusammen einen großen Prompt. Ollama stellt Modelle mit einem relativ kleinen Standard-Kontextfenster bereit. Dadurch fällt der Anfang des Prompts aus dem Fenster, also genau der Bereich mit den Tool-Definitionen. Das Modell ruft dann keine Tools mehr auf oder erfindet nicht vorhandene Tools. Erhöhen Sie num_ctx auf 16k oder 32k und wählen Sie ein Modell, das tatsächlich gut mit Function Calling umgehen kann. Eine Antwort, die mitten im Satz endet, weist auf das Gegenteil und auf eine andere Einstellung hin: num_predict. Wenn Antworten abgeschnitten zurückkommen, sollten Sie prüfen, wo num_predict gesetzt wird und was done_reason anzeigt, bevor Sie den Agent verantwortlich machen. Wenn Sie statt einer Auswahlliste lieber mit einem bestimmten Kandidaten beginnen möchten, ist Nemotron 3.5 Lightning einen Versuch wert. Der zugehörige Beitrag nennt den genauen Tag zum Abrufen, den benötigten RAM und ob die Leistung im reinen CPU-Betrieb ausreicht.

Ein selbst gehostetes Gateway. Schalten Sie ein selbst gehostetes LiteLLM-Gateway zwischen Octop und alle übrigen Komponenten. Dadurch erhalten Sie eine gemeinsame Basis-URL, einen separaten Schlüssel pro Benutzer, Ausgabenlimits und ein zentrales Log. Sie können außerdem das dahinterliegende Modell austauschen, ohne Octop zu bearbeiten.

Eine kostenpflichtige API. Sie erhalten die beste Qualität, müssen aber einen klaren Kompromiss akzeptieren: Der Gesprächsinhalt verlässt Ihren Server und wird an den Provider übertragen. Genau dies ist bei vielen Self-Hosting-Szenarien unerwünscht. Der Schlüssel wird in docker/.env als OPENAI_API_KEY eingetragen. Die Compose-Datei reicht ihn bereits durch.

Unabhängig von Ihrer Wahl enthält die Compose-Datei außerdem OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY und LANGFUSE_BASE_URL. Damit können Sie Traces an Ihre eigene Langfuse-Instanz senden und sehen, was die Agents tatsächlich tun, statt aus dem Chatfenster zu schließen.

Benutzer, Rollen und die gemeinsame Agentenbibliothek

Das Administratorkonto aus dem ersten Start erstellt und verwaltet die übrigen Konten. Jeder Benutzer erhält eigene Agenten, einen eigenen Arbeitsbereich und eigene Zugangsdaten. Diese Trennung wird durch das Token gewährleistet, das der Browser speichert. Daneben gibt es einen gemeinsamen Pool aus Skills und Subagenten, den alle verwenden können. Genau das macht den Betrieb für eine Familie interessant: Eine Person erstellt einmal einen guten Rechercheagenten, und niemand sonst muss ihn neu erstellen.

Gehen Sie bei den Tools vorsichtig vor. Octop bietet die Bestätigung von Tool-Aufrufen und Schutzmechanismen für Shell-Befehle an. Beides funktioniert tatsächlich. Ein Agent, der Shell-Befehle ausführt, führt sie jedoch innerhalb des Octop-Containers aus, in dem Ihr Datenvolume eingebunden ist. Die Schutzmechanismen begrenzen, was ein unvorsichtiger Prompt auslösen kann. Sie bilden keine Sandbox-Grenze. Lassen Sie die Tool-Bestätigung daher für alle aktiviert, denen Sie keinen Shell-Zugriff geben würden. Wenn Sie diese Lösung mit anderen Optionen vergleichen, zeigt der Vergleich selbst gehosteter KI-Agenten, wie die einzelnen Lösungen damit umgehen.

Ein Projekt aktualisieren, das so schnell Releases veröffentlicht

[
  {
    "version": "v0.9.16",
    "days_since_previous_release": 2
  },
  {
    "version": "v0.9.17",
    "days_since_previous_release": 3
  },
  {
    "version": "v0.9.18",
    "days_since_previous_release": 1
  },
  {
    "version": "v0.9.19",
    "days_since_previous_release": 3
  }
]

Das sind die Tag-Daten aus dem Repository, Stand 7. August 2026. 4 getaggte Releases wurden innerhalb von neun Tagen veröffentlicht. Der kürzeste Abstand betrug 1 Tag. v0.9.19 wurde 3 Tage nach dem vorherigen Tag veröffentlicht. Diese Kadenz spricht für das Projekt, ist aber ein schlechter Grund, latest auszuführen. Lesen Sie die Änderungen, bevor Sie sie übernehmen:

cd Octop
git fetch --tags
git tag --sort=-creatordate | head
NEW_TAG=$(git tag --sort=-creatordate | head -1)
git log --oneline "v0.9.19..$NEW_TAG"

Erstellen Sie jedes Mal zuerst ein Backup, weil Datenbankmigrationen beim Start ausgeführt werden. Eine fehlgeschlagene Migration bei einem Projekt vor Version 1.0 müssen Sie selbst beheben:

docker compose -f docker/docker-compose.yml stop
sudo tar czf octop-backup-$(date +%F).tgz -C /srv octop-data
docker compose -f docker/docker-compose.yml start

Wechseln Sie anschließend zum neuen Tag und erstellen Sie den Build mit docker compose -f docker/docker-compose.yml up -d --build neu. Wenn dabei ein Fehler auftritt, stellt das Auschecken des alten Tags mit anschließendem Neubau den Code wieder her. Nur das Tarball stellt die Datenbank wieder her.

Das Tarball enthält octop.db, config.json, das JWT-Signaturgeheimnis und credential.txt. Es ist daher genauso sensibel wie der Server selbst. Setzen Sie den Modus auf 600 und bewahren Sie eine Kopie außerhalb des Servers auf. Für eine größere Installation veröffentlicht das Projekt außerdem docker/docker-compose.postgres.yml. Damit wird PostgreSQL mit pgvector anstelle von SQLite ausgeführt.

Fehlerbilder und die angezeigten Meldungen

Der Health Check antwortet nie. curl http://127.0.0.1:8088/api/health hängt oder verweigert die Verbindung. Lesen Sie docker compose -f docker/docker-compose.yml logs -f octop. Ein Container, der während der ersten Initialisierung beendet wird, kann normalerweise nicht in das Datenverzeichnis schreiben. Prüfen Sie daher die Eigentümerschaft des Verzeichnisses, das Sie für OCTOP_DATA festgelegt haben.

Das Dashboard wird geladen, aber der Chat hängt. Auf der Seite wird kein Fehler angezeigt, und es kommt keine Antwort. Öffnen Sie die Browserkonsole und suchen Sie nach einer fehlgeschlagenen Verbindung zu wss://octop.example.com/agents/.../chat/ws. Der Proxy leitet das Upgrade nicht weiter. Fügen Sie den Header proxy_http_version 1.1 sowie die Header Upgrade und Connection hinzu.

Die gesamte Antwort erscheint mehrere Sekunden verspätet auf einmal. Das Streaming funktioniert, aber das Puffern ist aktiviert. Setzen Sie proxy_buffering off.

bind: address already in use. Port 8088 wird bereits von einem anderen Prozess verwendet. sudo ss -tlnp | grep 8088 ermittelt den betreffenden Prozess. Diese Meldung erhalten Sie auch, wenn Sie in einer Override-Datei einen zweiten Eintrag für ports hinzugefügt haben, statt den ursprünglichen Eintrag zu bearbeiten.

Das korrekte Passwort wird abgelehnt. Fünf falsche Versuche lösen eine Sperre von 900 Sekunden aus. Warten Sie, bis die Sperre abgelaufen ist, statt die Anwendung neu zu installieren.

Das neue Passwort in .env hatte keine Wirkung. Diese Zugangsdaten werden nur bei der ersten Initialisierung verwendet. Ändern Sie das Passwort im Dashboard.

Der Agent antwortet, führt aber nie ein Tool aus. Fast immer liegt das an einem lokalen Modell: Das Kontextfenster ist für die Tool-Definitionen zu klein, oder das Modell unterstützt Function Calling nur unzureichend. Erhöhen Sie num_ctx und verwenden Sie ein Modell, das für die Nutzung von Tools entwickelt wurde.

FAQ

Ist Octop ein Ersatz für Open WebUI?

Nur wenn Sie die zusätzlichen Funktionen benötigen. Open WebUI ist eine Chat-Oberfläche vor einem Modell und erfüllt diese Aufgabe für eine Person oder einen vertrauensvollen Haushalt gut. Octop bietet Konten mit einer Admin-Rolle, benutzerspezifische Arbeitsbereiche und Zugangsdaten sowie eine umschaltbare Bibliothek spezialisierter Agenten. Dadurch können mehrere Personen einen Server gemeinsam nutzen, ohne eine gemeinsame Historie zu verwenden. Wenn ein einzelnes Konto für Sie ausreicht, ist Open WebUI die einfachere und deutlich ausgereiftere Wahl.

Warum sollte ich nicht das Octop-curl-Installationsskript verwenden?

Das Skript wird aus einem Tencent Cloud Object Storage-Bucket und nicht aus dem Repository bereitgestellt. Daher ist es durch kein git-Tag und keinen Commit abgedeckt. Sie können nicht vergleichen, was es heute mit dem, was es letzte Woche getan hat. Wenn Sie es in bash weiterleiten, wird es ausgeführt, bevor Sie es gelesen haben. Außerdem installiert es sich mit einer eigenen Python-3.12-Umgebung direkt auf dem Host und außerhalb Ihres Paketmanagers. Laden Sie es herunter und lesen Sie es zuerst, oder stellen Sie es mit Docker Compose aus einem ausgecheckten Tag bereit.

Kann Octop statt einer kostenpflichtigen API ein lokales Modell verwenden?

Ja. Octop unterstützt OpenAI-kompatible APIs und wird mit einer Ollama-Voreinstellung ausgeliefert. Wenn Sie auf http://host.docker.internal:11434/v1 verweisen, funktioniert dies, sobald Sie extra_hosts: ["host.docker.internal:host-gateway"] in den Container übernehmen und OLLAMA_HOST=0.0.0.0:11434 auf dem Host setzen. Begrenzen Sie den Firewall-Zugriff auf Port 11434 auf den Adressbereich von Docker, da Ollama keine eigene Authentifizierung besitzt. Stellen Sie Ollamas num_ctx auf 16k oder höher ein. Agent-Prompts mit Tool-Definitionen überschreiten sonst das standardmäßige Kontextfenster, woraufhin das Modell keine Tools mehr aufruft.

Benötige ich einen Reverse Proxy, oder kann ich Port 8088 öffnen?

Sie benötigen den Proxy. Die mit Octop ausgelieferte Compose-Datei veröffentlicht 8088 auf allen Schnittstellen ohne TLS. Dadurch würden Passwörter und Bearer-Tokens unverschlüsselt über das Internet übertragen. Ändern Sie den veröffentlichten Port in 127.0.0.1:8088:8088 und schalten Sie Caddy oder nginx mit einem Zertifikat davor. Bei nginx müssen Sie die Header für das WebSocket-Upgrade weiterleiten und proxy_buffering off setzen. Andernfalls wird die Seite geladen, während der Chat ohne sichtbare Fehlermeldung nicht antwortet.

Ist Octop für den Produktionseinsatz bereit?

Octop ist vor Version 1.0 und veröffentlicht seit August 2026 mehrere getaggte Releases pro Woche. Betrachten Sie es daher als vielversprechend, aber noch nicht ausgereift. Für eine Familie oder ein kleines internes Team kann der Einsatz vertretbar sein, wenn Sie ein exaktes Tag festlegen, vor jedem Upgrade das Commit-Log lesen und vor jedem Neuaufbau eine Sicherung des Daten-Volumes erstellen. Betreiben Sie es nicht auf latest und hinterlegen Sie dort vorerst keine Kundendaten.