Zielgruppe: Das Gateway läuft, aber MCP-Tools erscheinen nicht, Aufrufe laufen in Timeouts oder Skills verschwinden nach Neustarts. Ergebnis: Bootstrap bleibt im Installationsleitfaden und im Docker-Produktions-Runbook; Persistenz im Artikel zu Volumes & Skills-Berechtigungen. Dieses Runbook behandelt Deklarieren → Prozesssichtbarkeit → Gateway-Registrierung → Triage von Modell, Tool und Kanal. Aufbau: sechs Fallen, zwei Matrizen, Konfig-Skizze, Warnhinweis, sechs Schritte, drei KPIs, abschließende Hinweise.
MCP ist eine JSON-RPC-Sitzung zwischen Gateway und Kindprozess oder Remote-Endpunkt. Konfigurationseinträge existieren ≠ Kind startet; Kind startet ≠ Schemas kommen zurück. Sechs häufige Fehldeutungen folgen.
PATH noch API-Schlüssel aus ~/.zshrc.AGENTS.md-/Bootstrap-Texte: doppelte Anweisungen über MCP und Skills blähen den Kontext auf; Grenzen wie im Skills-Tuning-Checklist-Artikel trennen.openclaw doctor in der Reihenfolge des Doctor-Leitfadens nach der Installation ausführen; dieser Text ergänzt die Beweiskette zur Tool-Registrierung, kein weiteres Installations-Tutorial.
Pro MCP-Server eine einseitige „Minimum-Repro-Karte“: eine Leseabfrage, ein negativer Test, der verweigert werden muss, drei erwartete Log-Tokens—On-Call kann Karten vergleichen, ohne riesige Prompts zu lesen. Auf der Karte erlaubten Egress und Datenklassifikation festhalten, damit Vorfälle Token-Scopes nicht ohne Nachweis erweitern.
Feldnamen variieren je nach OpenClaw-Version; diese Tabelle fixiert die Reihenfolge der Arbeitsschritte.
| Symptom | Zuerst sammeln | Wahrscheinliche Ursache | Auditierbare Maßnahme |
|---|---|---|---|
| Leere/teilweise Toolliste | Gateway-Logs, Exit-Codes des Kindes | Fehlendes Binary, cwd, permission denied | Absolute command/args/cwd; Kind als derselbe Benutzer wie das Gateway ausführen |
| Erster Aufruf langsam, dann ok | Kaltstart-Timing, Paket-Fetch-Logs | npx -y oder Laufzeit-JIT | Prewarm; Versionen in Images pinnen; Timeout für ersten Aufruf lockern |
| Stetige Timeouts | Kind lebt, CPU, FD-Nutzung | Deadlock, blockierendes IO | Stichproben/Traces wo erlaubt; A/B mit nur-Lese-Tool |
| „Tool nicht registriert“ | Schema-Logs, Protokollversion | Implementierungs-Mismatch | MCP-Versionen angleichen; Minors pinnen; Upstream-Changelog lesen |
Eine Fähigkeitsmatrix veröffentlichen, damit ein Workflow nicht dreifach beschrieben wird.
| Quelle | Am besten für | Versionierung | Risiko |
|---|---|---|---|
| ClawHub / Marktplatz | Schnelle Experimente | Commit oder Semver-Range pinnen; wöchentlicher Diff | Upstream-Drift—Regressionstests nötig |
Repo-SKILL.md / private Packs | Compliance-lastige Abläufe | Mit Mainline per PR ausliefern | Wartungslast; an MCP-Scope angleichen |
| MCP (System of Record) | DBs, Tickets, interne HTTP-APIs | Eigenes Release-Tempo | Zu breite Token—Allowlists pflegen |
# Nur Strukturskizze—echte Schlüssel, Verschachtelung und Hot Reload folgen der aktuellen OpenClaw-Doku.
# Ziel: Gateway startet einen MCP-Server über stdio als festen Benutzer.
#
# mcpServers:
# internal-readonly-lookup:
# command: /usr/local/bin/node
# args: ["/opt/mcp-servers/lookup/dist/index.js"]
# env:
# LOOKUP_API_TOKEN: "${LOOKUP_TOKEN_READONLY}"
#
# ClawHub-Skill: ins Team-Skills-Verzeichnis entpacken/klonen, dann Skill-Index
# aktualisieren oder den dokumentierten Reload-Befehl Ihrer Version ausführen.
Warnung: MCP verbindet Assistenten mit Produktionsdaten. Datenschutz durch Technikgestaltung und nachvollziehbare Berechtigungen schlagen „einfach zum Laufen bringen“. Lese- und Schreib-Server trennen, Token trennen, Allowlist-Auszüge am Change-Ticket anhängen. Unternehmen sollten prüfen, ob über MCP erreichbare Daten personenbezogen sind und ob Zweckbindung, Speicherbegrenzung, Zugriffskontrollen sowie Verzeichnis von Verarbeitungstätigkeiten nach DSGVO die jeweiligen MCP-Endpunkte und Logs abdecken.
PATH, cwd und Bind-Mounts dokumentieren.memory_search oder Doku-Tools verschieben, um Kontextwachstum zu begrenzen.AGENTS.md—alles >1 braucht eine schriftlich freigegebene Ausnahme.Auf Remote-Macs oder Cloud-Hosts beeinflussen Plattenplatz und Log-Rotation MCP-Kinder, die Temporäres auf kleine Systemvolumes schreiben—Timeouts wirken zufällig, obwohl die Modellkonfiguration gleich bleibt. Host-Betrieb parallel zur Tool-Konfiguration prüfen.
Bei HTTP-/SSE-MCP-Frontends Reverse-Proxy-Idle-Timeouts, Upgrade-Behandlung und TLS-Terminierung einbeziehen: Das Gateway kann einen erfolgreichen Handshake loggen, während der Edge-Proxy 499/504 liefert. Vor reiner Erhöhung der OpenClaw-Timeouts den Nginx/Caddy-Reverse-Proxy-Leitfaden abgleichen.
Richtungscommunity-Hinweis (kein Benchmark): drei schwere MCP-Server plus breite Retrieval erzeugen oft jitter in Minutenlänge—Fähigkeitsmatrizen und Allowlists schlagen unbegrenzte Plugins für SLAs.
Sleep, VPN-Aussetzer und Pfad-Drift machen Kindprozesse und Skill-Indizes unvorhersehbar. Echte Geschäftsdaten verlangen 24/7-Verfügbarkeit, persistente Pfade und auditierbare Berechtigungen.
Selbstverwaltete Maschinen ohne Multi-Region-Wahl oder flexible Konditionen fördern geteilte Hosts, auf denen Kaltstarts und Log-IO konkurrieren. Das Gateway auf dediziertem Apple Silicon mit planbaren Platten und Egress zu betreiben—typisch für professionelle Mac-Clouds—macht MCP- und Skills-Policies oft vertraglich durchsetzbar. MACCOME bietet mehrregionale Mac Mini M4 / M4 Pro mit flexiblen Mietmodellen als stabile Basis für Gateway und Build-Farmen; öffentliche Preise und Hilfe-Center-SLAs vor Bestellung prüfen.
Die drei Checks aus diesem Runbook auf einem Remote-Mac pilotieren, bevor eine Image-Flotte global ausgerollt wird—Schleifen „lokal ok, in Prod Timeout“ vermeiden. Ist das Gateway internetseitig erreichbar, TLS, Ratenlimits und IP-Allowlists in derselben Änderung ausliefern, nicht als späteren Patch.
FAQ
Wie passt das zur Kanal-Onboarding-Dokumentation?
Kanal-Leitfäden behandeln Slack/Discord/Telegram-OAuth; dieser Artikel Tool-Discovery. Wenn Nachrichten das Gateway erreichen, Tools aber scheitern, zuerst Evidenz aus Tabelle 1 sammeln, bevor „verbunden aber still“-Fälle erneut geöffnet werden.
Was soll ein Rollback enthalten?
MCP-Einträge entfernen, Neustart-Reihenfolge dokumentieren, eine nur-Lese-Verifikationsabfrage ausführen und auf Dashboards prüfen, dass Tool-Zähler zur Baseline zurückkehren. Abrechnung mit Mietpreisen abstimmen.
Container- vs. Bare-Metal-Pfade weichen ab—was nun?
Eine Absolute-Pfad-Matrix pro Runtime pflegen; das Modell soll Pfade im Chat nicht raten. Hilfe-Center mit dem Docker-Volume-Artikel abgleichen.