Wie das Docs-System funktioniert

Hinter den Kulissen

Diese Seite erklärt, wie das OpenClaw-Dokumentationssystem intern funktioniert. Sie richtet sich an Mitwirkende, die Dokumentation hinzufügen oder aktualisieren möchten, und an alle, die an der technischen Umsetzung interessiert sind.

Markdown-Dateien

Alle Dokumentation wird als Markdown-Dateien geschrieben, die im Repository unter folgendem Pfad gespeichert sind:

content/openclaw/docs/
├── en/              # Englische Dokumentation
│   ├── getting-started/
│   ├── channels/
│   ├── billing/
│   ├── advanced/
│   ├── security/
│   ├── troubleshooting/
│   └── meta/
└── de/              # Deutsche Dokumentation
    ├── getting-started/
    ├── channels/
    ├── billing/
    ├── advanced/
    ├── security/
    ├── troubleshooting/
    └── meta/

Jede Dokumentationsseite existiert als zwei Dateien: eine in en/ und eine in de/. Beide Versionen müssen denselben Slug und dieselbe Kategorie haben.

YAML-Frontmatter

Jede Markdown-Datei beginnt mit einem YAML-Frontmatter-Block, der Metadaten definiert:

---
title: Seitentitel
slug: seiten-slug
category: getting-started
section: Erste Schritte
position: 3
---

Kategorie- und Sektions-Zuordnung

Dokument-Sync-Prozess

Dokumentationsdateien werden über den DocumentSyncService mit der Datenbank synchronisiert. Dieser Service:

1. Durchsucht das Verzeichnis content/openclaw/docs/ nach Markdown-Dateien
2. Parst YAML-Frontmatter aus jeder Datei
3. Konvertiert den Markdown-Inhalt zu HTML
4. Berechnet eine geschätzte Lesezeit
5. Generiert ein Vektor-Embedding für die semantische Suche
6. Speichert alles in der Tabelle oc_document_embeddings

Der Sync-Ablauf

Markdown-Datei auf der Festplatte
  → DocumentSyncService liest die Datei
  → YAML-Frontmatter wird für Metadaten geparst
  → Markdown-Body wird zu HTML konvertiert
  → Lesezeit wird aus der Wortanzahl berechnet
  → Text wird an die Embedding-API gesendet (4096 Dimensionen)
  → Datensatz wird in oc_document_embeddings upserted

Datenbank-Felder

Jedes synchronisierte Dokument erzeugt einen Datensatz mit:

Semantische Suche mit pgvector

Das Dokumentationssystem nutzt die pgvector-Erweiterung von PostgreSQL für semantische Suche. Wenn ein Nutzer eine Frage stellt, macht das System Folgendes:

1. Konvertiert die Frage in ein Vektor-Embedding mit demselben Embedding-Modell
2. Fragt die Tabelle oc_document_embeddings mittels Vektor-Ähnlichkeitssuche ab
3. Gibt die relevantesten Dokumentationsseiten zurück, sortiert nach Ähnlichkeit

Das bedeutet, dass Nutzer Dokumentation finden können, indem sie in natürlicher Sprache beschreiben, wonach sie suchen -- anstatt exakte Schlüsselwörter oder Seitentitel kennen zu müssen.

Wie sich Vektorsuche von Textsuche unterscheidet

Textsuche findet exakte oder unscharfe Wortübereinstimmungen. Eine Suche nach "Server startet nicht" würde nur Seiten finden, die genau diese Wörter enthalten.

Vektorsuche versteht Bedeutung. Eine Suche nach "Server startet nicht" würde auch Seiten über "Instanz läuft nicht" oder "Deployment fehlgeschlagen" finden, weil die Konzepte semantisch ähnlich sind.

Verlinkung zwischen Seiten

Dokumentationsseiten verlinken aufeinander im /docs/slug-Format:

Siehe die [Architekturübersicht](/docs/architecture) für weitere Details.

Der Slug in der URL muss mit dem slug-Feld im Frontmatter der Zielseite übereinstimmen. Links funktionieren sprachübergreifend -- das System löst die korrekte lokalisierte Version basierend auf der Spracheinstellung des Lesers auf.

Neue Dokumentation hinzufügen

Um eine neue Dokumentationsseite hinzuzufügen:

1. Erstelle die englische Datei im entsprechenden Kategorie-Verzeichnis
2. Erstelle die deutsche Datei im passenden DE-Kategorie-Verzeichnis
3. Setze übereinstimmende Slugs -- Beide Dateien müssen denselben slug-Wert haben
4. Wähle eine Position -- Wähle eine Nummer, die die Seite in der richtigen Sortierreihenfolge innerhalb ihrer Kategorie platziert
5. Schreibe den Inhalt -- Verwende Standard-Markdown mit Überschriften, Tabellen, Codeblöcken und Listen
6. Füge einen Abschnitt "Verwandte Dokumentation" hinzu -- Verlinke am Ende auf andere relevante Seiten

Dateibenennungs-Konvention

Verwende den Slug als Dateinamen mit der Endung .md:

content/openclaw/docs/en/advanced/meine-neue-seite.md
content/openclaw/docs/de/advanced/meine-neue-seite.md

Beide Dateien hätten slug: meine-neue-seite in ihrem Frontmatter.

Inhaltsrichtlinien

• Schreibe in klarer, direkter Sprache
• Verwende Überschriften zur Gliederung des Inhalts (beginne mit ##, nicht mit #)
• Füge Codebeispiele ein, wo sie hilfreich sind
• Nutze Tabellen zum Vergleichen von Optionen oder Auflisten von Konfigurationen
• Beende jede Seite mit einem Abschnitt "Verwandte Dokumentation", der auf verwandte Seiten verlinkt
• Verwende keine unüberprüfbaren Behauptungen oder erfundenen Statistiken

Hinweise zur deutschen Übersetzung

Die deutsche Version sollte eine natürliche deutsche Übersetzung sein, keine wörtliche Übertragung:

• Verwende korrekte deutsche Umlaute (ä, ö, ü, ß), niemals ae, oe, ue, ss als Ersatz
• Lokalisiere die Felder title und section
• Behalte technische Begriffe (Docker, API, SSH) unverändert
• Übersetze Code-Kommentare, wenn sie nutzersichtbaren Text enthalten
• Verwende "du" (informell) für die Ansprache des Lesers

Dokumentation testen

Jede Dokumentationsseite hat einen zugehörigen RSpec-Test, der überprüft:

1. Die Markdown-Datei existiert am erwarteten Pfad
2. Das Frontmatter enthält alle erforderlichen Felder mit korrekten Werten
3. Die Datei synchronisiert erfolgreich über den DocumentSyncService
4. Der Datenbank-Datensatz hat das korrekte Locale, den Slug, die Kategorie und den Inhalt

Tests befinden sich in spec/services/openclaw/docs_content/ und folgen einem einheitlichen Muster für alle Dokumentationsseiten.

Verwandte Dokumentation

• Architekturübersicht -- Technische Architektur der Plattform
• Best Practices -- Empfehlungen für die effektive Nutzung von OpenClaw