Gateway

Fehlerbehebung

Diese Seite ist das ausführliche Runbook. Beginnen Sie bei /help/troubleshooting, wenn Sie zuerst den schnellen Triage-Ablauf möchten.

Befehlsabfolge

Führen Sie diese zuerst in dieser Reihenfolge aus:

bash

OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw channels status --probe

Erwartete fehlerfreie Signale:

OmeniaClaw gateway status zeigt Runtime: running, Connectivity probe: ok und eine Zeile Capability: ....
OmeniaClaw doctor meldet keine blockierenden Konfigurations- oder Dienstprobleme.
OmeniaClaw channels status --probe zeigt den Live-Transportstatus pro Konto und, sofern unterstützt, Probe-/Audit-Ergebnisse wie works oder audit ok.

Split-Brain-Installationen und Schutz vor neuerer Konfiguration

Verwenden Sie dies, wenn ein Gateway-Dienst nach einem Update unerwartet stoppt oder Logs zeigen, dass eine OmeniaClaw-Binärdatei älter ist als die Version, die zuletzt OmeniaClaw.json geschrieben hat.

OmeniaClaw versieht Konfigurationsschreibvorgänge mit meta.lastTouchedVersion. Schreibgeschützte Befehle können weiterhin eine von einer neueren OmeniaClaw-Version geschriebene Konfiguration prüfen, aber Prozess- und Dienständerungen verweigern mit einer älteren Binärdatei die Fortsetzung. Blockierte Aktionen umfassen Start, Stopp, Neustart und Deinstallation des Gateway-Dienstes, erzwungene Dienst-Neuinstallation, Gateway-Start im Dienstmodus und gateway --force-Portbereinigung.

bash

which OmeniaClawOmeniaClaw --versionOmeniaClaw gateway status --deepOmeniaClaw config get meta.lastTouchedVersion

PATH korrigieren

Korrigieren Sie PATH, sodass OmeniaClaw auf die neuere Installation verweist, und führen Sie die Aktion dann erneut aus.

Gateway-Dienst neu installieren

Installieren Sie den vorgesehenen Gateway-Dienst aus der neueren Installation neu:

bash

OmeniaClaw gateway install --forceOmeniaClaw gateway restart

Veraltete Wrapper entfernen

Entfernen Sie veraltete Systempaket- oder alte Wrapper-Einträge, die weiterhin auf eine alte OmeniaClaw-Binärdatei zeigen.

Skill-Symlink wegen Pfad-Ausbruch übersprungen

Verwenden Sie dies, wenn Logs Folgendes enthalten:

text

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

OmeniaClaw behandelt jeden Skill-Root als Begrenzung. Ein Symlink unter ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills oder ~/.OmeniaClaw/skills wird übersprungen, wenn sein tatsächliches Ziel außerhalb dieses Roots aufgelöst wird, sofern das Ziel nicht ausdrücklich als vertrauenswürdig eingestuft ist.

Prüfen Sie den Link:

bash

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>OmeniaClaw config get skills.load

Wenn das Ziel beabsichtigt ist, konfigurieren Sie sowohl den direkten Skill-Root als auch das zugelassene Symlink-Ziel:

json5

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Starten Sie anschließend eine neue Sitzung oder warten Sie, bis der Skills-Watcher aktualisiert wurde. Starten Sie das Gateway neu, wenn der laufende Prozess vor der Konfigurationsänderung gestartet wurde.

Verwenden Sie keine breiten Ziele wie ~, / oder einen ganzen synchronisierten Projektordner. Beschränken Sie allowSymlinkTargets auf den tatsächlichen Skill-Root, der vertrauenswürdige SKILL.md-Verzeichnisse enthält.

Verwandt:

Anthropic 429: zusätzliche Nutzung für langen Kontext erforderlich

Verwenden Sie dies, wenn Logs/Fehler Folgendes enthalten: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

bash

OmeniaClaw logs --followOmeniaClaw models statusOmeniaClaw config get agents.defaults.models

Achten Sie auf Folgendes:

Für das ausgewählte Anthropic Opus-/Sonnet-Modell ist params.context1m: true gesetzt.
Die aktuelle Anthropic-Anmeldedatenberechtigung ist nicht für die Nutzung von langem Kontext berechtigt.
Anfragen schlagen nur bei langen Sitzungen/Modellläufen fehl, die den 1M-Beta-Pfad benötigen.

Behebungsoptionen:

context1m deaktivieren

Deaktivieren Sie context1m für dieses Modell, um auf das normale Kontextfenster zurückzufallen.

Berechtigte Anmeldedaten verwenden

Verwenden Sie Anthropic-Anmeldedaten, die für Anfragen mit langem Kontext berechtigt sind, oder wechseln Sie zu einem Anthropic-API-Schlüssel.

Fallback-Modelle konfigurieren

Konfigurieren Sie Fallback-Modelle, damit Läufe fortgesetzt werden, wenn Anthropic-Anfragen mit langem Kontext abgelehnt werden.

Verwandt:

Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Läufe schlagen fehl

Verwenden Sie dies, wenn:

curl ... /v1/models funktioniert
winzige direkte /v1/chat/completions-Aufrufe funktionieren
OmeniaClaw-Modellläufe nur bei normalen Agent-Turns fehlschlagen

bash

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'OmeniaClaw infer model run --model <provider/model> --prompt "hi" --jsonOmeniaClaw logs --follow

Achten Sie auf Folgendes:

direkte winzige Aufrufe sind erfolgreich, aber OmeniaClaw-Läufe schlagen nur bei größeren Prompts fehl
model_not_found- oder 404-Fehler, obwohl direkte /v1/chat/completions mit derselben einfachen Modell-ID funktionieren
Backend-Fehler dazu, dass messages[].content eine Zeichenfolge erwartet
zeitweise Warnungen incomplete turn detected ... stopReason=stop payloads=0 mit einem OpenAI-kompatiblen lokalen Backend
Backend-Abstürze, die nur bei größeren Prompt-Token-Zahlen oder vollständigen Agent-Runtime-Prompts auftreten

Häufige Signaturen

model_not_found mit einem lokalen MLX-/vLLM-artigen Server → prüfen Sie, dass baseUrl /v1 enthält, api für /v1/chat/completions-Backends "openai-completions" ist und models.providers.<provider>.models[].id die einfache provider-lokale ID ist. Wählen Sie sie einmal mit dem Provider-Präfix aus, zum Beispiel mlx/mlx-community/Qwen3-30B-A3B-6bit; behalten Sie den Katalogeintrag als mlx-community/Qwen3-30B-A3B-6bit.
messages[...].content: invalid type: sequence, expected a string → Backend lehnt strukturierte Chat-Completions-Inhaltsteile ab. Behebung: models.providers.<provider>.models[].compat.requiresStringContent: true setzen.
validation.keys oder erlaubte Nachrichtenschlüssel wie ["role","content"] → Backend lehnt OpenAI-artige Replay-Metadaten in Chat-Completions-Nachrichten ab. Behebung: models.providers.<provider>.models[].compat.strictMessageKeys: true setzen.
incomplete turn detected ... stopReason=stop payloads=0 → Das Backend hat die Chat-Completions-Anfrage abgeschlossen, aber für diesen Turn keinen für den Benutzer sichtbaren Assistant-Text zurückgegeben. OmeniaClaw wiederholt replay-sichere leere OpenAI-kompatible Turns einmal; anhaltende Fehler bedeuten in der Regel, dass das Backend leeren/nicht-textuellen Inhalt ausgibt oder finalen Antworttext unterdrückt.
Direkte winzige Anfragen sind erfolgreich, aber OmeniaClaw-Agent-Läufe schlagen mit Backend-/Modellabstürzen fehl (zum Beispiel Gemma auf einigen inferrs-Builds) → Der OmeniaClaw-Transport ist wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Agent-Runtime-Prompt-Form.
Fehler werden nach dem Deaktivieren von Tools kleiner, verschwinden aber nicht → Tool-Schemas waren Teil des Drucks, aber das verbleibende Problem liegt weiterhin bei der Kapazität des Upstream-Modells/-Servers oder einem Backend-Fehler.

Behebungsoptionen

Setzen Sie compat.requiresStringContent: true für reine Zeichenfolgen-Chat-Completions-Backends.
Setzen Sie compat.strictMessageKeys: true für strikte Chat-Completions-Backends, die pro Nachricht nur role und content akzeptieren.
Setzen Sie compat.supportsTools: false für Modelle/Backends, die die Tool-Schema-Oberfläche von OmeniaClaw nicht zuverlässig verarbeiten können.
Verringern Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzerer Sitzungsverlauf, leichteres lokales Modell oder ein Backend mit stärkerer Unterstützung für langen Kontext.
Wenn winzige direkte Anfragen weiterhin bestehen, während OmeniaClaw-Agent-Turns im Backend abstürzen, behandeln Sie dies als Upstream-Server-/Modellbeschränkung und melden Sie dort eine Reproduktion mit der akzeptierten Payload-Form.

Verwandt:

Keine Antworten

Wenn Channels verfügbar sind, aber nichts antwortet, prüfen Sie Routing und Richtlinie, bevor Sie etwas neu verbinden.

bash

OmeniaClaw statusOmeniaClaw channels status --probeOmeniaClaw pairing list --channel <channel> [--account <id>]OmeniaClaw config get channelsOmeniaClaw logs --follow

Achten Sie auf Folgendes:

Pairing für DM-Absender ausstehend.
Gruppen-Erwähnungs-Gating (requireMention, mentionPatterns).
Abweichungen bei Channel-/Gruppen-Allowlists.

Häufige Signaturen:

drop guild message (mention required → Gruppennachricht wird bis zur Erwähnung ignoriert.
pairing request → Absender benötigt Genehmigung.
blocked / allowlist → Absender/Channel wurde durch Richtlinie gefiltert.

Verwandt:

Konnektivität der Dashboard-Steuerungs-UI

Wenn die Dashboard-/Steuerungs-UI keine Verbindung herstellt, validieren Sie URL, Auth-Modus und Annahmen zum sicheren Kontext.

bash

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw gateway status --json

Achten Sie auf Folgendes:

Korrekte Probe-URL und Dashboard-URL.
Abweichung bei Auth-Modus/Token zwischen Client und Gateway.
HTTP-Nutzung, obwohl Geräteidentität erforderlich ist.

Verbindungs-/Auth-Signaturen

device identity required → unsicherer Kontext oder fehlende Geräte-Auth.
origin not allowed → Browser-Origin ist nicht in gateway.controlUi.allowedOrigins enthalten (oder Sie verbinden sich von einem Browser-Origin außerhalb von Loopback ohne ausdrückliche Allowlist).
device nonce required / device nonce mismatch → Client schließt den challenge-basierten Geräte-Auth-Flow nicht ab (connect.challenge + device.nonce).
device signature invalid / device signature expired → Client hat die falsche Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert.
AUTH_TOKEN_MISMATCH mit canRetryWithDeviceToken=true → Client kann einen vertrauenswürdigen Wiederholungsversuch mit zwischengespeichertem Gerätetoken durchführen.
Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet die zwischengespeicherte Scope-Menge, die mit dem gepairten Gerätetoken gespeichert ist. Aufrufer mit explizitem deviceToken / expliziten scopes behalten stattdessen ihre angeforderte Scope-Menge.
AUTH_SCOPE_MISMATCH → Das Gerätetoken wurde erkannt, aber seine genehmigten Scopes decken diese Verbindungsanfrage nicht ab; pairen Sie erneut oder genehmigen Sie den angeforderten Scope-Vertrag, statt ein gemeinsam genutztes Gateway-Token zu rotieren.
Außerhalb dieses Wiederholungspfads lautet die Connect-Auth-Priorität: zuerst explizites gemeinsames Token/Passwort, dann explizites deviceToken, dann gespeichertes Gerätetoken, dann Bootstrap-Token.
Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe {scope, ip} serialisiert, bevor der Limiter den Fehler erfasst. Zwei fehlerhafte gleichzeitige Wiederholungen vom selben Client können daher beim zweiten Versuch retry later statt zweier einfacher Abweichungen anzeigen.
too many failed authentication attempts (retry later) von einem Browser-Origin-Loopback-Client → wiederholte Fehler von demselben normalisierten Origin werden vorübergehend ausgesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
wiederholtes unauthorized nach diesem Wiederholungsversuch → Drift bei gemeinsamem Token/Gerätetoken; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Gerätetoken bei Bedarf erneut.
gateway connect failed: → falsches Host-/Port-/URL-Ziel.

Schnellzuordnung für Auth-Detailcodes

Verwenden Sie error.details.code aus der fehlgeschlagenen connect-Antwort, um die nächste Aktion auszuwählen:

Detailcode	Bedeutung	Empfohlene Aktion
`AUTH_TOKEN_MISSING`	Client hat ein erforderliches gemeinsames Token nicht gesendet.	Token im Client einfügen/festlegen und erneut versuchen. Für Dashboard-Pfade: `OmeniaClaw config get gateway.auth.token` und dann in die Einstellungen der Control UI einfügen.
`AUTH_TOKEN_MISMATCH`	Gemeinsames Token stimmte nicht mit dem Auth-Token des Gateway überein.	Wenn `canRetryWithDeviceToken=true` ist, erlauben Sie einen vertrauenswürdigen erneuten Versuch. Wiederholungen mit zwischengespeichertem Token verwenden gespeicherte genehmigte Scopes erneut; Aufrufer mit explizitem `deviceToken` / `scopes` behalten angeforderte Scopes bei. Wenn der Fehler weiterhin auftritt, führen Sie die Checkliste zur Wiederherstellung bei Token-Drift aus.
`AUTH_DEVICE_TOKEN_MISMATCH`	Zwischengespeichertes gerätespezifisches Token ist veraltet oder widerrufen.	Gerätetoken mit der Geräte-CLI rotieren/erneut genehmigen, dann erneut verbinden.
`AUTH_SCOPE_MISMATCH`	Gerätetoken ist gültig, aber seine genehmigte Rolle/seine genehmigten Scopes decken diese Verbindungsanforderung nicht ab.	Koppeln Sie das Gerät erneut oder genehmigen Sie den angeforderten Scope-Vertrag; behandeln Sie dies nicht als Drift des gemeinsamen Tokens.
`PAIRING_REQUIRED`	Geräteidentität benötigt Genehmigung. Prüfen Sie `error.details.reason` auf `not-paired`, `scope-upgrade`, `role-upgrade` oder `metadata-upgrade`, und verwenden Sie `requestId` / `remediationHint`, wenn vorhanden.	Ausstehende Anforderung genehmigen: `OmeniaClaw devices list`, dann `OmeniaClaw devices approve <requestId>`. Scope-/Rollen-Upgrades verwenden denselben Ablauf, nachdem Sie den angeforderten Zugriff geprüft haben.

Migrationsprüfung für Geräteauthentifizierung v2:

bash

OmeniaClaw --versionOmeniaClaw doctorOmeniaClaw gateway status

Wenn Logs Nonce-/Signaturfehler anzeigen, aktualisieren Sie den verbindenden Client und prüfen Sie ihn:

Auf connect.challenge warten

Client wartet auf das vom Gateway ausgegebene connect.challenge.

Payload signieren

Client signiert die an die Challenge gebundene Payload.

Geräte-Nonce senden

Client sendet connect.params.device.nonce mit derselben Challenge-Nonce.

Wenn OmeniaClaw devices rotate / revoke / remove unerwartet verweigert wird:

Sitzungen mit gekoppeltem Gerätetoken können nur ihr eigenes Gerät verwalten, sofern der Aufrufer nicht auch operator.admin hat
OmeniaClaw devices rotate --scope ... kann nur Operator-Scopes anfordern, die die Aufrufersitzung bereits besitzt

Verwandt:

Gateway-Dienst läuft nicht

Verwenden Sie dies, wenn der Dienst installiert ist, der Prozess aber nicht aktiv bleibt.

bash

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw gateway status --deep   # also scan system-level services

Achten Sie auf:

Runtime: stopped mit Exit-Hinweisen.
Abweichung in der Dienstkonfiguration (Config (cli) gegenüber Config (service)).
Port-/Listener-Konflikte.
Zusätzliche launchd-/systemd-/schtasks-Installationen, wenn --deep verwendet wird.
Bereinigungshinweise zu Other gateway-like services detected (best effort).

Häufige Signaturen

Gateway start blocked: set gateway.mode=local oder existing config is missing gateway.mode → lokaler Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde überschrieben und hat gateway.mode verloren. Behebung: Setzen Sie gateway.mode="local" in Ihrer Konfiguration, oder führen Sie OmeniaClaw onboard --mode local / OmeniaClaw setup erneut aus, um die erwartete lokale Moduskonfiguration neu zu stempeln. Wenn Sie OmeniaClaw über Podman ausführen, ist der Standardkonfigurationspfad ~/.OmeniaClaw/OmeniaClaw.json.
refusing to bind gateway ... without auth → Nicht-loopback-Bindung ohne gültigen Gateway-Auth-Pfad (Token/Passwort oder trusted-proxy, wenn konfiguriert).
another gateway instance is already listening / EADDRINUSE → Portkonflikt.
Other gateway-like services detected (best effort) → veraltete oder parallele launchd-/systemd-/schtasks-Einheiten existieren. Die meisten Setups sollten ein Gateway pro Maschine behalten; wenn Sie mehr als eines benötigen, isolieren Sie Ports + Konfiguration/Zustand/Workspace. Siehe /gateway#multiple-gateways-same-host.
System-level OmeniaClaw gateway service detected von doctor → eine systemd-Systemeinheit existiert, während der Dienst auf Benutzerebene fehlt. Entfernen oder deaktivieren Sie das Duplikat, bevor Sie doctor erlauben, einen Benutzerdienst zu installieren, oder setzen Sie OmeniaClaw_SERVICE_REPAIR_POLICY=external, wenn die Systemeinheit der beabsichtigte Supervisor ist.
Gateway service port does not match current gateway config → der installierte Supervisor pinnt weiterhin den alten --port. Führen Sie OmeniaClaw doctor --fix oder OmeniaClaw gateway install --force aus, und starten Sie dann den Gateway-Dienst neu.

Verwandt:

Gateway hat ungültige Konfiguration abgelehnt

Verwenden Sie dies, wenn der Gateway-Start mit Invalid config fehlschlägt oder Hot-Reload-Logs melden, dass eine ungültige Bearbeitung übersprungen wurde.

bash

OmeniaClaw logs --followOmeniaClaw config fileOmeniaClaw config validateOmeniaClaw doctor

Achten Sie auf:

Invalid config at ...
config reload skipped (invalid config): ...
Config write rejected: ...
Eine mit Zeitstempel versehene Datei OmeniaClaw.json.rejected.* neben der aktiven Konfiguration
Eine mit Zeitstempel versehene Datei OmeniaClaw.json.clobbered.*, wenn doctor --fix eine fehlerhafte direkte Bearbeitung repariert hat

Was passiert ist

Die Konfiguration wurde beim Start, beim Hot Reload oder bei einem OmeniaClaw-eigenen Schreibvorgang nicht validiert.
Gateway-Start schlägt geschlossen fehl, statt OmeniaClaw.json neu zu schreiben.
Hot Reload überspringt ungültige externe Bearbeitungen und hält die aktuelle Laufzeitkonfiguration aktiv.
OmeniaClaw-eigene Schreibvorgänge lehnen ungültige/destruktive Payloads vor dem Commit ab und speichern .rejected.*.
OmeniaClaw doctor --fix besitzt die Reparatur. Es kann Nicht-JSON-Präfixe entfernen oder die letzte als gut bekannte Kopie wiederherstellen, während die abgelehnte Payload als .clobbered.* erhalten bleibt.

Prüfen und reparieren

bash

CONFIG="$(OmeniaClaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"OmeniaClaw config validateOmeniaClaw doctor

Häufige Signaturen

.clobbered.* existiert → doctor hat eine fehlerhafte externe Bearbeitung erhalten, während die aktive Konfiguration repariert wurde.
.rejected.* existiert → ein OmeniaClaw-eigener Konfigurationsschreibvorgang ist vor dem Commit an Schema- oder Clobber-Prüfungen gescheitert.
Config write rejected: → der Schreibvorgang versuchte, erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder ungültige Konfiguration zu persistieren.
config reload skipped (invalid config): → eine direkte Bearbeitung ist an der Validierung gescheitert und wurde vom laufenden Gateway ignoriert.
Invalid config at ... → Start ist fehlgeschlagen, bevor Gateway-Dienste gestartet wurden.
missing-meta-vs-last-good, gateway-mode-missing-vs-last-good oder size-drop-vs-last-good:* → ein OmeniaClaw-eigener Schreibvorgang wurde abgelehnt, weil er Felder oder Größe im Vergleich zum Last-known-good-Backup verloren hat.
Config last-known-good promotion skipped → der Kandidat enthielt redigierte Secret-Platzhalter wie ***.

Behebungsoptionen

Führen Sie OmeniaClaw doctor --fix aus, damit doctor eine Konfiguration mit Präfix/Clobber repariert oder Last-known-good wiederherstellt.
Kopieren Sie nur die beabsichtigten Schlüssel aus .clobbered.* oder .rejected.*, und wenden Sie sie dann mit OmeniaClaw config set oder config.patch an.
Führen Sie OmeniaClaw config validate vor dem Neustart aus.
Wenn Sie von Hand bearbeiten, behalten Sie die vollständige JSON5-Konfiguration bei, nicht nur das Teilobjekt, das Sie ändern wollten.

Verwandt:

Gateway-Probe-Warnungen

Verwenden Sie dies, wenn OmeniaClaw gateway probe etwas erreicht, aber trotzdem einen Warnungsblock ausgibt.

bash

OmeniaClaw gateway probeOmeniaClaw gateway probe --jsonOmeniaClaw gateway probe --ssh user@gateway-host

Achten Sie auf:

warnings[].code und primaryTargetId in der JSON-Ausgabe.
Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Referenzen bezieht.

Häufige Signaturen:

SSH tunnel failed to start; falling back to direct probes. → SSH-Einrichtung ist fehlgeschlagen, aber der Befehl hat weiterhin direkte konfigurierte/loopback-Ziele versucht.
multiple reachable gateways detected → mehr als ein Ziel hat geantwortet. Normalerweise bedeutet dies ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener.
Read-probe diagnostics are limited by gateway scopes (missing operator.read) → Verbindung hat funktioniert, aber Detail-RPC ist durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Zugangsdaten mit operator.read.
Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → Verbindung hat funktioniert, aber der vollständige Diagnose-RPC-Satz ist abgelaufen oder fehlgeschlagen. Behandeln Sie dies als erreichbares Gateway mit eingeschränkter Diagnose; vergleichen Sie connect.ok und connect.rpcOk in der --json-Ausgabe.
Capability: pairing-pending oder gateway closed (1008): pairing required → das Gateway hat geantwortet, aber dieser Client benötigt vor normalem Operator-Zugriff noch Kopplung/Genehmigung.
nicht aufgelöster gateway.auth.* / gateway.remote.* SecretRef-Warnungstext → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.

Verwandt:

Kanal verbunden, Nachrichten fließen nicht

Wenn der Kanalstatus verbunden ist, aber der Nachrichtenfluss nicht funktioniert, konzentrieren Sie sich auf Richtlinien, Berechtigungen und kanalspezifische Zustellregeln.

bash

OmeniaClaw channels status --probeOmeniaClaw pairing list --channel <channel> [--account <id>]OmeniaClaw status --deepOmeniaClaw logs --followOmeniaClaw config get channels

Achten Sie auf:

DM-Richtlinie (pairing, allowlist, open, disabled).
Gruppen-Allowlist und Erwähnungsanforderungen.
Fehlende Kanal-API-Berechtigungen/-Scopes.

Häufige Signaturen:

mention required → Nachricht durch Gruppen-Erwähnungsrichtlinie ignoriert.
pairing / Spuren ausstehender Genehmigung → Absender ist nicht genehmigt.
missing_scope, not_in_channel, Forbidden, 401/403 → Problem mit Kanal-Authentifizierung/-Berechtigungen.

Verwandt:

Cron- und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht ausgeführt oder nicht zugestellt wurde, prüfen Sie zuerst den Scheduler-Status und dann das Zustellziel.

bash

OmeniaClaw cron statusOmeniaClaw cron listOmeniaClaw cron runs --id <jobId> --limit 20OmeniaClaw system heartbeat lastOmeniaClaw logs --follow

Achten Sie auf:

Cron aktiviert und nächste Ausführung vorhanden.
Status des Job-Ausführungsverlaufs (ok, skipped, error).
Heartbeat-Überspringgründe (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Häufige Signaturen

cron: scheduler disabled; jobs will not run automatically → Cron deaktiviert.
cron: timer tick failed → Scheduler-Tick fehlgeschlagen; Datei-/Log-/Laufzeitfehler prüfen.
heartbeat skipped mit reason=quiet-hours → außerhalb des aktiven Zeitfensters.
heartbeat skipped mit reason=empty-heartbeat-file → HEARTBEAT.md existiert, enthält aber nur leere Zeilen / Markdown-Überschriften, daher überspringt OmeniaClaw den Modellaufruf.
heartbeat skipped mit reason=no-tasks-due → HEARTBEAT.md enthält einen tasks:-Block, aber keine der Aufgaben ist bei diesem Tick fällig.
heartbeat: unknown accountId → ungültige Konto-ID für das Heartbeat-Zustellziel.
heartbeat skipped mit reason=dm-blocked → Heartbeat-Ziel wurde als DM-artiges Ziel aufgelöst, während agents.defaults.heartbeat.directPolicy (oder eine agentenspezifische Überschreibung) auf block gesetzt ist.

Verwandt:

Node gekoppelt, Tool schlägt fehl

Wenn eine Node gekoppelt ist, aber Tools fehlschlagen, isolieren Sie Vordergrund-, Berechtigungs- und Genehmigungsstatus.

bash

OmeniaClaw nodes statusOmeniaClaw nodes describe --node <idOrNameOrIp>OmeniaClaw approvals get --node <idOrNameOrIp>OmeniaClaw logs --followOmeniaClaw status

Achten Sie auf:

Node online mit erwarteten Fähigkeiten.
Betriebssystem-Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
Exec-Genehmigungen und Allowlist-Status.

Häufige Signaturen:

NODE_BACKGROUND_UNAVAILABLE → Node-App muss im Vordergrund sein.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → fehlende Betriebssystem-Berechtigung.
SYSTEM_RUN_DENIED: approval required → Exec-Genehmigung ausstehend.
SYSTEM_RUN_DENIED: allowlist miss → Befehl durch Allowlist blockiert.

Verwandt:

Browser-Tool schlägt fehl

Verwenden Sie dies, wenn Browser-Tool-Aktionen fehlschlagen, obwohl der Gateway selbst fehlerfrei ist.

bash

OmeniaClaw browser statusOmeniaClaw browser start --browser-profile OmeniaClawOmeniaClaw browser profilesOmeniaClaw logs --followOmeniaClaw doctor

Achten Sie auf:

Ob plugins.allow gesetzt ist und browser enthält.
Gültigen Pfad zur Browser-Executable.
Erreichbarkeit des CDP-Profils.
Lokale Chrome-Verfügbarkeit für existing-session- / user-Profile.

Plugin- / Executable-Signaturen

unknown command "browser" oder unknown command 'browser' → das gebündelte Browser-Plugin ist durch plugins.allow ausgeschlossen.
Browser-Tool fehlt / nicht verfügbar, obwohl browser.enabled=true → plugins.allow schließt browser aus, daher wurde das Plugin nie geladen.
Failed to start Chrome CDP on port → Browser-Prozess konnte nicht gestartet werden.
browser.executablePath not found → konfigurierter Pfad ist ungültig.
browser.cdpUrl must be http(s) or ws(s) → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema wie file: oder ftp:.
browser.cdpUrl has invalid port → die konfigurierte CDP-URL hat einen ungültigen oder außerhalb des Bereichs liegenden Port.
Playwright is not available in this gateway build; '<feature>' is unsupported. → der aktuellen Gateway-Installation fehlt die zentrale Browser-Laufzeitabhängigkeit; installieren oder aktualisieren Sie OmeniaClaw erneut und starten Sie dann den Gateway neu. ARIA-Snapshots und einfache Seiten-Screenshots können weiterhin funktionieren, aber Navigation, KI-Snapshots, Element-Screenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar.

Chrome-MCP- / Existing-Session-Signaturen

Could not find DevToolsActivePort for chrome → Chrome-MCP-Existing-Session konnte noch nicht an das ausgewählte Browser-Datenverzeichnis anhängen. Öffnen Sie die Browser-Inspektionsseite, aktivieren Sie Remote-Debugging, lassen Sie den Browser geöffnet, genehmigen Sie die erste Anhängeaufforderung und versuchen Sie es erneut. Wenn ein angemeldeter Zustand nicht erforderlich ist, bevorzugen Sie das verwaltete Profil OmeniaClaw.
No Chrome tabs found for profile="user" → das Chrome-MCP-Anhängeprofil hat keine geöffneten lokalen Chrome-Tabs.
Remote CDP for profile "<name>" is not reachable → der konfigurierte Remote-CDP-Endpunkt ist vom Gateway-Host aus nicht erreichbar.
Browser attachOnly is enabled ... not reachable oder Browser attachOnly is enabled and CDP websocket ... is not reachable → Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber der CDP-WebSocket konnte dennoch nicht geöffnet werden.

Element- / Screenshot- / Upload-Signaturen

fullPage is not supported for element screenshots → Screenshot-Anfrage hat --full-page mit --ref oder --element kombiniert.
element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome-MCP- / existing-session-Screenshot-Aufrufe müssen Seitenerfassung oder ein Snapshot---ref verwenden, nicht CSS---element.
existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome-MCP-Upload-Hooks benötigen Snapshot-Refs, keine CSS-Selektoren.
existing-session file uploads currently support one file at a time. → senden Sie bei Chrome-MCP-Profilen einen Upload pro Aufruf.
existing-session dialog handling does not support timeoutMs. → Dialog-Hooks bei Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
existing-session type does not support timeoutMs overrides. → lassen Sie timeoutMs für act:type bei profile="user"- / Chrome-MCP-Existing-Session-Profilen weg, oder verwenden Sie ein verwaltetes/CDP-Browserprofil, wenn ein benutzerdefiniertes Timeout erforderlich ist.
existing-session evaluate does not support timeoutMs overrides. → lassen Sie timeoutMs für act:evaluate bei profile="user"- / Chrome-MCP-Existing-Session-Profilen weg, oder verwenden Sie ein verwaltetes/CDP-Browserprofil, wenn ein benutzerdefiniertes Timeout erforderlich ist.
response body is not supported for existing-session profiles yet. → responsebody erfordert weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil.
veraltete Viewport- / Dark-Mode- / Locale- / Offline-Überschreibungen bei Attach-only- oder Remote-CDP-Profilen → führen Sie OmeniaClaw browser stop --browser-profile <name> aus, um die aktive Steuersitzung zu schließen und den Playwright-/CDP-Emulationsstatus freizugeben, ohne den gesamten Gateway neu zu starten.

Verwandt:

Wenn Sie aktualisiert haben und plötzlich etwas nicht mehr funktioniert

Die meisten Ausfälle nach einem Upgrade sind Konfigurationsdrift oder strengere Defaults, die jetzt durchgesetzt werden.

1. Authentifizierungs- und URL-Override-Verhalten geändert

bash

OmeniaClaw gateway statusOmeniaClaw config get gateway.modeOmeniaClaw config get gateway.remote.urlOmeniaClaw config get gateway.auth.mode

Was zu prüfen ist:

Wenn gateway.mode=remote, zielen CLI-Aufrufe möglicherweise auf remote, während Ihr lokaler Dienst in Ordnung ist.
Explizite --url-Aufrufe fallen nicht auf gespeicherte Zugangsdaten zurück.

Häufige Signaturen:

gateway connect failed: → falsches URL-Ziel.
unauthorized → Endpunkt erreichbar, aber falsche Authentifizierung.

2. Bind- und Authentifizierungs-Schutzmechanismen sind strenger

bash

OmeniaClaw config get gateway.bindOmeniaClaw config get gateway.auth.modeOmeniaClaw config get gateway.auth.tokenOmeniaClaw gateway statusOmeniaClaw logs --follow

Was zu prüfen ist:

Nicht-Loopback-Binds (lan, tailnet, custom) benötigen einen gültigen Gateway-Authentifizierungspfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte Nicht-Loopback-trusted-proxy-Bereitstellung.
Alte Schlüssel wie gateway.token ersetzen gateway.auth.token nicht.

Häufige Signaturen:

refusing to bind gateway ... without auth → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad.
Connectivity probe: failed, während die Laufzeit ausgeführt wird → Gateway läuft, ist aber mit aktueller Authentifizierung/URL nicht zugänglich.

3. Kopplungs- und Geräteidentitätsstatus geändert

bash

OmeniaClaw devices listOmeniaClaw pairing list --channel <channel> [--account <id>]OmeniaClaw logs --followOmeniaClaw doctor

Was zu prüfen ist:

Ausstehende Gerätegenehmigungen für Dashboard/Nodes.
Ausstehende DM-Kopplungsgenehmigungen nach Richtlinien- oder Identitätsänderungen.

Häufige Signaturen:

device identity required → Geräteauthentifizierung nicht erfüllt.
pairing required → Absender/Gerät muss genehmigt werden.

Wenn Dienstkonfiguration und Laufzeit nach den Prüfungen weiterhin voneinander abweichen, installieren Sie die Dienstmetadaten aus demselben Profil-/Statusverzeichnis erneut:

bash

OmeniaClaw gateway install --forceOmeniaClaw gateway restart

Verwandt:

Verwandt

Was this useful?

Fehlerbehebung

Befehlsabfolge

Split-Brain-Installationen und Schutz vor neuerer Konfiguration

PATH korrigieren

Gateway-Dienst neu installieren

Veraltete Wrapper entfernen

Skill-Symlink wegen Pfad-Ausbruch übersprungen

Anthropic 429: zusätzliche Nutzung für langen Kontext erforderlich

context1m deaktivieren

Berechtigte Anmeldedaten verwenden

Fallback-Modelle konfigurieren

Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Läufe schlagen fehl

Keine Antworten

Konnektivität der Dashboard-Steuerungs-UI

Schnellzuordnung für Auth-Detailcodes

Auf connect.challenge warten

Payload signieren

Geräte-Nonce senden

Gateway-Dienst läuft nicht

Gateway hat ungültige Konfiguration abgelehnt

Gateway-Probe-Warnungen

Kanal verbunden, Nachrichten fließen nicht

Cron- und Heartbeat-Zustellung

Node gekoppelt, Tool schlägt fehl

Browser-Tool schlägt fehl

Wenn Sie aktualisiert haben und plötzlich etwas nicht mehr funktioniert

Verwandt

On this page

Molty