Das Problem

Du hast clawdbot auf deinem Server laufen, die clawdbot.json sieht gut aus, Matrix-Credentials stimmen — und der Bot ignoriert dich trotzdem komplett. Kein Fehler im Log. Kein Crash. Einfach Stille.

Die Meldung Matrix: not configured ist dabei eine der frustrierendsten überhaupt, weil sie exakt nichts darüber verrät, was nicht konfiguriert ist. Die Config existiert. Die Felder sind da. Trotzdem: nichts.

Hier sind die drei Probleme, die nacheinander auftraten — und wie du sie vermeidest.

TL;DR

  1. Plugin-Installation schlägt fehl wegen workspace:* in devDependencies → devDependencies aus package.json entfernen, dann npm install
  2. Drei falsche Feldnamen in der Config → homeserver statt homeserverUrl, dm.policy statt dmPolicy, identityLinks gehört in session nicht in channels.matrix
  3. Bot antwortet mit API-Fehler → korrupte Session-History löschen

Problem 1: npm install schlägt fehl

Nach dem Hinzufügen des Matrix-Plugins in der Config:

clawdbot plugins install @clawdbot/matrix

Fehlermeldung:

npm error code EUNSUPPORTEDPROTOCOL
npm error Unsupported URL Type "workspace:": workspace:*

Ursache

Die package.json enthält devDependencies mit workspace:* Referenzen — ein Monorepo-Feature, das nur innerhalb des Entwicklungs-Workspaces funktioniert. Auf einem Produktivsystem hat npm damit nichts anfangen können.

Fix

cd /opt/clawdbot  # oder wo dein clawdbot liegt

# devDependencies entfernen (braucht kein Produktivsystem)
node -e "
  const pkg = require('./package.json');
  delete pkg.devDependencies;
  require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2));
"

# Dann normal installieren
npm install
clawdbot plugins install @clawdbot/matrix

Problem 2: Die drei falschen Feldnamen

Das ist der eigentliche Showstopper. Der Bot startet sauber, meldet keine Fehler — aber die Matrix-Verbindung wird einfach ignoriert. Der Grund: drei Feldnamen in der clawdbot.json die fast richtig aussehen, aber vom Plugin nicht erkannt werden.

Fehler 1: homeserverUrl → homeserver

// FALSCH
"channels": {
  "matrix": {
    "homeserverUrl": "https://matrix.deathstar.lan"
  }
}

// RICHTIG
"channels": {
  "matrix": {
    "homeserver": "https://matrix.deathstar.lan"
  }
}

Kein Fehler, kein Warning. Das Feld wird einfach ignoriert, und ohne homeserver gilt der Channel als “not configured”.

Fehler 2: dmPolicy → dm.policy

// FALSCH
"channels": {
  "matrix": {
    "dmPolicy": "pairing"
  }
}

// RICHTIG
"channels": {
  "matrix": {
    "dm": {
      "policy": "pairing"
    }
  }
}

dmPolicy als flacher Key wird nicht gelesen. Es muss ein verschachteltes Objekt dm mit dem Key policy sein.

// FALSCH — identityLinks im Channel-Block
"channels": {
  "matrix": {
    "identityLinks": {
      "@c3po:deathstar.lan": "c3po"
    }
  }
}

// RICHTIG — identityLinks im session-Block (Top-Level)
"session": {
  "identityLinks": {
    "@c3po:deathstar.lan": "c3po"
  }
}

identityLinks mappt Matrix-User auf interne Identitäten (für Pairing, Permissions, etc.). Das gehört in die session-Konfiguration, nicht in den Channel.

Korrekte Minimal-Config

{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.deathstar.lan",
      "userId": "@clawdbot:deathstar.lan",
      "accessToken": "<DEIN-ACCESS-TOKEN>",
      "dm": {
        "policy": "pairing"
      }
    }
  },
  "session": {
    "identityLinks": {
      "@c3po:deathstar.lan": "c3po"
    }
  }
}

Problem 3: Korrupte Session History

Nach dem Config-Fix startet der Bot, verbindet sich mit Matrix — und antwortet auf jede Nachricht mit einem API-Fehler statt einer sinnvollen Antwort.

Ursache

Die Session-Datei enthielt eine korrupte Conversation History. Konkret: ein tool_use-Block ohne passendes tool_result. Die LLM-API (Claude) erwartet, dass auf jeden tool_use ein tool_result folgt. Fehlt der, schlägt der API-Call fehl.

Das passiert, wenn der Bot während einer Tool-Ausführung abrupt beendet wird (Crash, Kill, Restart).

Fix

# Session-Dateien finden
ls -la /opt/clawdbot/data/sessions/

# Korrupte Session löschen
rm /opt/clawdbot/data/sessions/<session-id>.json

# Bot neustarten
systemctl restart clawdbot

Der Bot erstellt beim nächsten Gespräch automatisch eine neue, saubere Session.

Pairing nicht vergessen

Wenn du dm.policy: "pairing" nutzt, muss jeder User einmalig gepairt werden. Der Ablauf:

  1. User schreibt dem Bot in Matrix — der Bot antwortet mit einem Pairing-Code
  2. Admin führt auf dem Server aus:
clawdbot pairing approve matrix <CODE>

Danach antwortet der Bot normal. Ohne Pairing: Stille.

Verifikation

Nach allen Fixes prüfen:

# Gesundheitscheck
clawdbot health

# Installierte Plugins
clawdbot plugins list
# Erwartete Ausgabe: @clawdbot/matrix

# Matrix-Status im Health-Output
# Erwartete Ausgabe: Matrix: connected

Fazit

Drei Lektionen aus dieser Konfiguration:

  1. Feldnamen sind nicht geraten — wenn die Doku homeserver sagt und du homeserverUrl schreibst, bekommst du keine Fehlermeldung. Du bekommst Stille. Immer die exakten Feldnamen aus der Plugin-Dokumentation nehmen.

  2. Verschachtelte vs. flache Keys — dmPolicy: "pairing" und dm: { policy: "pairing" } sehen für Menschen ähnlich aus. Für JSON-Parser sind das komplett verschiedene Strukturen.

  3. Session-Dateien können korrupt werden — wenn der Bot nach einem Crash seltsame API-Fehler wirft, ist die Session-History der erste Verdächtige. Löschen und neu anfangen.

Die gute Nachricht: Wenn die Config einmal stimmt, läuft das Matrix-Plugin stabil. Man muss nur erstmal durch das Tal der stillen Fehlkonfigurationen.