Was macht Claw Doctor — OpenClaw Selbstreparatur-Skill?

Dieser Skill diagnostiziert und behebt häufige OpenClaw / NanoClaw Probleme. Wenn etwas kaputt geht, führe die folgende Checkliste durch, bevor du aufgibst.

Wann aktivieren

Aktiviere diesen Skill, wenn der Benutzer eines der folgenden Probleme meldet:

"skill not found" / Skill wird nicht ausgelöst
"No such file or directory" beim Ausführen eines Skill-Skripts
API-Key-Fehler von einem Skill
Skill produziert keine Ausgabe oder falsche Ausgabe
"SKILL.md is invalid" / YAML-Parse-Fehler
Ein Skill funktioniert global, aber nicht im Workspace (oder umgekehrt)
Skills haben funktioniert, aber nach einem Update aufgehört

Skill-Ladereihenfolge & Pfade

OpenClaw lädt Skills von zwei Speicherorten. Workspace-Skills haben Priorität.

Priorität 1 (hoch): <workspace>/skills/<skill-name>/SKILL.md
Priorität 2 (niedrig):  ~/.openclaw/skills/<skill-name>/SKILL.md

Diagnose: Alle geladenen Skills auflisten

# Zeige, was global installiert ist
ls ~/.openclaw/skills/ 2>/dev/null || echo "Kein globales Skills-Verzeichnis"

# Zeige, was im aktuellen Workspace installiert ist
ls ./skills/ 2>/dev/null || echo "Kein Workspace-Skills-Verzeichnis"

Wenn ein Skill in beiden Verzeichnissen existiert, gewinnt die Workspace-Version — überprüfe auf Versionskonflikte.

Problem 1 — Skill wird nicht ausgelöst

Symptom: Benutzer ruft einen Skill auf, aber Claude ignoriert ihn oder folgt nicht der Skill-Prozedur.

Diagnose-Checkliste:

Ist die SKILL.md tatsächlich vorhanden und lesbar?

cat ./skills/<skill-name>/SKILL.md | head -20

Parst das YAML-Frontmatter korrekt?

python3 -c "
import re, sys
txt = open('skills/<skill-name>/SKILL.md').read()
fm = re.search(r'^---\n(.*?)\n---', txt, re.DOTALL)
print('Frontmatter gefunden:', bool(fm))
if fm:
    import yaml; d = yaml.safe_load(fm.group(1)); print('Keys:', list(d.keys()))
"

Stimmen die keywords in der SKILL.md mit dem überein, was der Benutzer gesagt hat?
- Füge bei Bedarf mehr Keyword-Varianten hinzu (Synonyme, Abkürzungen).
Ist die description klar genug, damit das Modell den Skill identifizieren kann?
- Kurze, spezifische Beschreibungen sind besser als vage.

Fix: Stelle sicher, dass das Frontmatter gültiges YAML ist (keine Tabs, korrekte Anführungszeichen, korrekte Einrückung).

Problem 2 — Skript nicht gefunden (Pfadauflösung)

Symptom: bash: scripts/run: No such file or directory

Dies ist der häufigste Skill-Fehler. Skripte, die in der SKILL.md als scripts/foo referenziert werden, sind relativ zum Installationsverzeichnis des Skills im OpenClaw-Plugin-Cache, nicht zum aktuellen Arbeitsverzeichnis.

Kanonischer Fix — Löse den Skript-Pfad dynamisch vor jeder Verwendung auf:

# Für einen Skill namens "my-skill" mit einem Skript namens "run"
MY_SCRIPT=$(find ~/.openclaw -name "run" -path "*/my-skill/*/scripts/*" -type f 2>/dev/null | head -1)
# Fallback: Überprüfe Workspace-Skills
[ -z "$MY_SCRIPT" ] && MY_SCRIPT=$(find ./skills -name "run" -path "*/my-skill/scripts/*" -type f 2>/dev/null | head -1)

if [ -z "$MY_SCRIPT" ]; then
  echo "FEHLER: Skript nicht gefunden. Ist der Skill installiert?"
  exit 1
fi

$MY_SCRIPT <args>

Überprüfe auch: Ist das Skript ausführbar?

chmod +x ~/.openclaw/skills/my-skill/scripts/*
chmod +x ./skills/my-skill/scripts/*

Problem 3 — API-Key nicht konfiguriert

Symptom: Skill gibt {"success": false, "setup_required": true} oder 401/403-Fehler zurück.

Standard-API-Key-Einrichtungsablauf:

Die SKILL.md des Skills sollte dokumentieren, wo der Key gespeichert ist (normalerweise ~/.openclaw/secrets/<skill-name>.key oder eine Umgebungsvariable).

Überprüfe, ob die Key-Datei existiert:

ls ~/.openclaw/secrets/ 2>/dev/null || echo "Kein Secrets-Verzeichnis"

Führe den Setup-Befehl des Skills aus (normalerweise scripts/run setup <api-key>).

Überprüfe, ob der Key gespeichert wurde:

cat ~/.openclaw/secrets/<skill-name>.key 2>/dev/null | head -c 20

Wenn kein Setup-Befehl existiert, bitte den Benutzer, die Umgebungsvariable direkt zu setzen:

export SKILL_API_KEY="ihr-key-hier"
# Füge zu ~/.zshrc oder ~/.bashrc hinzu für Persistenz

Problem 4 — Fehlende Abhängigkeit (Node.js / Python / Tool)

Symptom: node: command not found, python3: No such file or directory, jq: command not found

Schnelle Abhängigkeitsprüfung:

echo "=== Kern-Abhängigkeiten ===" && \
node --version 2>/dev/null || echo "FEHLT: node" && \
python3 --version 2>/dev/null || echo "FEHLT: python3" && \
jq --version 2>/dev/null || echo "FEHLT: jq" && \
curl --version 2>/dev/null | head -1 || echo "FEHLT: curl"

Fix nach Plattform:

Tool	macOS	Ubuntu/Debian
Node.js	`brew install node`	`apt install nodejs npm`
Python 3	`brew install python3`	`apt install python3`
jq	`brew install jq`	`apt install jq`

Für Python-Skill-Abhängigkeiten:

pip3 install -r skills/<skill-name>/requirements.txt 2>/dev/null \
  || echo "Keine requirements.txt gefunden"

Für Node-Skill-Abhängigkeiten:

cd skills/<skill-name> && npm install 2>/dev/null \
  || echo "Keine package.json gefunden"

Problem 5 — YAML-Frontmatter-Fehler

Symptom: Skill wird geladen, aber Metadaten sind falsch / Keywords nicht indiziert.

Gültige Frontmatter-Vorlage:

---
name: my-skill-name         # Kleinbuchstaben, nur Bindestriche
description: Ein klarer Satz, der beschreibt, was dieser Skill tut.
keywords:
  - keyword-one
  - keyword-two
license: MIT
---

Häufige Fehler:

Fehler	Fix
Tabs statt Leerzeichen	Ersetze mit 2-Leerzeichen-Einrückung
Unquotetes `:` in der Beschreibung	Setze den Wert in Anführungszeichen
Fehlendes `name`-Feld	Füge es hinzu — es ist erforderlich
`keywords` als Inline-Liste `[a, b]`	Verwende Block-Liste `- a\n- b`

Validieren:

python3 -c "
import yaml, sys
txt = open('skills/<skill-name>/SKILL.md').read().split('---')[1]
try:
    d = yaml.safe_load(txt)
    print('OK:', d)
except yaml.YAMLError as e:
    print('YAML-FEHLER:', e)
    sys.exit(1)
"

Problem 6 — Skill hat vorher funktioniert, nach Update kaputt

Symptom: OpenClaw wurde aktualisiert und ein Skill funktioniert nicht mehr.

Checkliste:

Überprüfe, ob der OpenClaw-Plugin-Cache geleert wurde:

ls ~/.openclaw/plugins/cache/ 2>/dev/null | head -10

Installiere den Skill aus der Quelle neu:

# Aus einem geklonten Skills-Repo
cp -r /path/to/skills-repo/skills/<skill-name> ~/.openclaw/skills/

Überprüfe auf Breaking Changes in der OpenClaw-Skill-API — siehe das OpenClaw-Changelog für SKILL.md-Format-Updates.

Teste das Skript direkt (unter Umgehung von OpenClaw):

bash skills/<skill-name>/scripts/<main-script> --help

Vollständiger Gesundheitscheck

Führe dies aus, um eine vollständige Momentaufnahme der OpenClaw-Umgebung zu erhalten:

echo "=== OpenClaw Gesundheitscheck ===" && \
echo "--- Globale Skills ---" && ls ~/.openclaw/skills/ 2>/dev/null || echo "(keine)" && \
echo "--- Workspace-Skills ---" && ls ./skills/ 2>/dev/null || echo "(keine)" && \
echo "--- Secrets ---" && ls ~/.openclaw/secrets/ 2>/dev/null || echo "(keine)" && \
echo "--- Plugin-Cache ---" && ls ~/.openclaw/plugins/cache/ 2>/dev/null | head -5 || echo "(leer)" && \
echo "--- Abhängigkeiten ---" && \
  node --version 2>/dev/null && \
  python3 --version 2>/dev/null && \
  jq --version 2>/dev/null && \
echo "=== Fertig ==="

Für Claude Code Benutzer

Dieser Skill funktioniert auch als benutzeraufrufbarer Skill für Claude Code. Füge Folgendes zu ~/.claude/CLAUDE.md unter ## Benutzeraufrufbare Skills hinzu:

### claw-doctor

Diagnostiziere und behebe OpenClaw / NanoClaw Probleme.

**Auslöser**: Benutzer erwähnt, dass Skill nicht lädt, Skript nicht gefunden, API-Key-Fehler, SKILL.md kaputt, OpenClaw funktioniert nicht

**Vorgehen**: Folge der Checkliste in claw-doctor SKILL.md:
1. Symptomkategorie identifizieren (Trigger / Skript-Pfad / API-Key / Abhängigkeit / YAML / nach Update)
2. Die relevanten Diagnosebefehle ausführen
3. Den Fix anwenden und mit dem Vollständigen Gesundheitscheck verifizieren

Problem 7 — Feishu Bot verwendet falsches Modell

Symptom: Das Modell, das in Feishu antwortet, stimmt nicht mit der Konfiguration in openclaw.json überein, oder nach /new wird immer noch das alte Modell verwendet.

Grundursache 1 — Session-basierter model override überschreibt die Agent-Konfiguration

Session-Dateien speichern dauerhaft das zuletzt manuell gewählte Modell und werden auch nach einem Neustart nicht gelöscht.

# Finde heraus, welche Session einen model override hat
python3 -c "
import json
for agent in ['main', 'sii']:
    path = f'/Users/tianyiliang/.openclaw/agents/{agent}/sessions/sessions.json'  # An tatsächlichen Pfad anpassen
    try:
        data = json.load(open(path))
        for k, v in data.items():
            if v.get('model'):
                print(f'[{agent}] {k}: model={v[\"model\"]}')
    except: pass
"

Fix: Lösche das model/modelProvider-Feld in der entsprechenden Session oder lösche den gesamten Session-Eintrag und starte das Gateway neu:

openclaw gateway restart

Grundursache 2 — main Agent nicht in agents.list, Binding wird ignoriert

In bindings steht "agentId": "main", aber es wird nicht wirksam — da main ein eingebauter Agent ist, kann er nicht als Routing-Ziel dienen, wenn er nicht in agents.list steht.

Diagnose:

openclaw agents list --bindings   # Prüfen, ob main erscheint

Fix: Füge main explizit zu agents.list hinzu:

python3 -c "
import json
path = '~/.openclaw/openclaw.json'  # An tatsächlichen Pfad anpassen
cfg = json.load(open(path))
if not any(a['id'] == 'main' for a in cfg['agents']['list']):
    cfg['agents']['list'].insert(0, {
        'id': 'main',
        'name': 'main',
        'workspace': cfg['agents']['defaults']['workspace'],
        'model': {'primary': 'custom-local/gemini-3-pro-preview', 'fallbacks': []}
    })
    json.dump(cfg, open(path,'w'), indent=2, ensure_ascii=False)
    print('main zu agents.list hinzugefügt')
"

Grundursache 3 — Model-ID passt nicht zum lokalen Proxy, was zu Fallback führt

Die in openclaw.json konfigurierte Model-ID existiert auf dem localhost-Proxy nicht, sodass stillschweigend auf das nächste Modell zurückgegriffen wird.

# Tatsächlich verfügbare Modelle abfragen
curl -s http://localhost:8317/v1/models -H "Authorization: Bearer your-api-key-1" \
  | python3 -c "import json,sys; [print(m['id']) for m in json.load(sys.stdin)['data']]" | sort

Vergleiche mit der Model-ID in openclaw.json und stelle sicher, dass sie exakt übereinstimmt.

Problem 8 — Cron Jobs laufen über OpenRouter

Symptom: In openclaw status zeigt die Cron-Session model=openrouter/auto an, sollte aber nicht in die Cloud gehen.

Grundursache: Die Session enthält authProfileOverride: openrouter:*, das dauerhaft gespeichert wurde (ein Überbleibsel einer automatischen Auth-Umschaltung).

Diagnose:

python3 -c "
import json
for agent in ['main', 'sii']:
    path = f'~/.openclaw/agents/{agent}/sessions/sessions.json'
    try:
        data = json.load(open(path))
        for k, v in data.items():
            if 'cron' in k and 'openrouter' in v.get('authProfileOverride',''):
                print(f'[{agent}] {k}: auth={v[\"authProfileOverride\"]} model={v.get(\"model\")}')
    except: pass
"

Fix: Lösche alle OpenRouter-Überschreibungen aus allen Cron-Sessions:

python3 -c "
import json, glob
for path in glob.glob('~/.openclaw/agents/*/sessions/sessions.json'):
    data = json.load(open(path))
    changed = False
    for k, v in data.items():
        if 'cron' in k and 'openrouter' in v.get('authProfileOverride',''):
            for field in ['model','modelProvider','authProfileOverride','authProfileOverrideSource','authProfileOverrideCompactionCount']:
                v.pop(field, None)
            changed = True
            print(f'Repariert: {k}')
    if changed:
        json.dump(data, open(path,'w'), ensure_ascii=False)
" && openclaw gateway restart

Problem 9 — Gateway reagiert nicht / `device signature invalid`

Symptom: openclaw status meldet RPC probe: failed, Fehler gateway closed (1008): device signature invalid. Feishu-Bot antwortet nicht, Gateway scheint zu laufen, aber CLI kann sich nicht verbinden.

Grundursache: Nach einem Update der OpenClaw-Version wurde der alte LaunchAgent (com.clawdbot.gateway, lädt openclaw-cn) nicht bereinigt und registriert sich gemeinsam mit der neuen Version ai.openclaw.gateway für den Autostart. Der alte Prozess belegt zuerst Port 18789, und das neue CLI wird aufgrund eines inkompatiblen device-signature-Formats abgewiesen.

Diagnose:

launchctl list | grep -i claw
# Wenn sowohl com.clawdbot.gateway als auch ai.openclaw.gateway erscheinen, liegt das Problem vor

openclaw gateway status 2>&1 | grep -E "RPC|device|pid"

Fix:

# 1. Sichern und deaktivieren des alten LaunchAgents
cp ~/Library/LaunchAgents/com.clawdbot.gateway.plist \
   ~/Library/LaunchAgents/com.clawdbot.gateway.plist.bak
launchctl bootout gui/$UID/com.clawdbot.gateway
mv ~/Library/LaunchAgents/com.clawdbot.gateway.plist \
   ~/Library/LaunchAgents/com.clawdbot.gateway.plist.disabled

# 2. Neues Gateway neu starten
openclaw gateway restart

# Überprüfen
openclaw gateway status 2>&1 | grep "RPC probe"
# Erwartete Ausgabe: RPC probe: ok

Hinweis: Die Datei .plist.disabled wird von launchd beim Systemstart nicht geladen (es werden nur .plist-Dateien erkannt), was einer Deaktivierung gleichkommt, während eine Sicherungskopie erhalten bleibt.

Problem 10 — Nicht-Besitzer-Benutzer werden blockiert (OAuth-Autorisierung / Tool-Aufruf)

Symptom: Nachrichten von Feishu-Benutzern, die nicht der App-Besitzer sind, führen zu abgelehnten Autorisierungsversuchen oder Tool-Aufrufen. Im Log erscheinen OwnerAccessDeniedError oder Permission denied: Only the app owner is authorized.

Grundursache: assertOwnerAccessStrict hat standardmäßig ownerOnly=true, sodass alle Nicht-Besitzer-Benutzer abgewiesen werden. Dies ist ein bekanntes Problem im openclaw-lark-Upstream (Issues #5, #12).

Fix A — Konfiguration deaktivieren (empfohlen): Füge im Feishu-Channel in openclaw.json uat.ownerOnly: false hinzu:

# Mit python3 sicher schreiben, um manuelle JSON-Fehler zu vermeiden
python3 - <<'EOF'
import json

path = '/Users/tianyiliang/.openclaw/openclaw.json'  # An tatsächlichen Pfad anpassen
cfg = json.load(open(path))
ch = cfg.setdefault('channels', {}).setdefault('feishu', {})
uat = ch.setdefault('uat', {})
uat['enabled'] = True
uat['ownerOnly'] = False
json.dump(cfg, open(path, 'w'), indent=2, ensure_ascii=False)
print('Fertig. Ausführen: openclaw gateway restart')
EOF

Fix B — Plugin aktualisieren: Wenn du die Workspace-Quellcode-Version des Plugins (openclaw-lark) verwendest, ist dieser Patch in PR #11 enthalten:

src/core/config-schema.ts: UATConfigSchema fügt ownerOnly?: boolean hinzu
src/core/owner-policy.ts: assertOwnerAccessStrict prüft das ownerOnly-Flag

Überprüfung: Nach dem Neustart des Gateways sollten im Log keine OwnerAccessDeniedError-Meldungen mehr erscheinen, wenn Nicht-Besitzer-Benutzer Nachrichten senden.

Mitwirken

Hast du einen neuen OpenClaw-Fehlermodus gefunden? Erstelle einen PR mit:

Dem Symptom (genaue Fehlermeldung oder Verhalten)
Der Grundursache
Dem Diagnosebefehl
Dem Fix

Halte die Einträge kurz und stelle die Befehle an den Anfang. Der Arzt sollte schnell konsultiert werden können.

Claw Doctor — OpenClaw Selbstreparatur-Skill

Was ist Claw Doctor — OpenClaw Selbstreparatur-Skill?

In Ihrer bevorzugten KI fragen

Dokumentation

Was macht Claw Doctor — OpenClaw Selbstreparatur-Skill?

Wann aktivieren

Skill-Ladereihenfolge & Pfade

Diagnose: Alle geladenen Skills auflisten

Problem 1 — Skill wird nicht ausgelöst

Problem 2 — Skript nicht gefunden (Pfadauflösung)

Problem 3 — API-Key nicht konfiguriert

Problem 4 — Fehlende Abhängigkeit (Node.js / Python / Tool)

Problem 5 — YAML-Frontmatter-Fehler

Problem 6 — Skill hat vorher funktioniert, nach Update kaputt

Vollständiger Gesundheitscheck

Für Claude Code Benutzer

Problem 7 — Feishu Bot verwendet falsches Modell

Problem 8 — Cron Jobs laufen über OpenRouter

Problem 9 — Gateway reagiert nicht / `device signature invalid`

Problem 10 — Nicht-Besitzer-Benutzer werden blockiert (OAuth-Autorisierung / Tool-Aufruf)

Mitwirken

Verwandte Skills

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep

In Ihrer bevorzugten KI fragen

Dokumentation

Was macht Claw Doctor — OpenClaw Selbstreparatur-Skill?

Wann aktivieren

Skill-Ladereihenfolge & Pfade

Diagnose: Alle geladenen Skills auflisten

Problem 1 — Skill wird nicht ausgelöst

Problem 2 — Skript nicht gefunden (Pfadauflösung)

Problem 3 — API-Key nicht konfiguriert

Problem 4 — Fehlende Abhängigkeit (Node.js / Python / Tool)

Problem 5 — YAML-Frontmatter-Fehler

Problem 6 — Skill hat vorher funktioniert, nach Update kaputt

Vollständiger Gesundheitscheck

Für Claude Code Benutzer

Problem 7 — Feishu Bot verwendet falsches Modell

Problem 8 — Cron Jobs laufen über OpenRouter

Problem 9 — Gateway reagiert nicht / device signature invalid

Problem 10 — Nicht-Besitzer-Benutzer werden blockiert (OAuth-Autorisierung / Tool-Aufruf)

Mitwirken

Verwandte Skills

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep

Problem 9 — Gateway reagiert nicht / `device signature invalid`