openclaw-expert

# OpenClaw Expert Skill ## Kernprinzip: Docs-First + Backup-First OpenClaw verwendet CalVer-Versioning (YYYY.M.D-N) und ändert sich häufig. **Vor jeder Änderung** diese Checkliste abarbeiten: 1. **Version prüfen**: `openclaw --version` 2. **Live-Docs holen** — `web_fetch` auf relevante Docs-Seiten (URLs in Referenzdateien) 3. **Community-Tipps suchen** — `web_search` nach aktuellen Workarounds 4. **Backup anlegen** — Niemals Konfig ohne Backup ändern 5. **Änderung durchführen** 6. **Validieren** — `openclaw doctor` vor und nach jeder Änderung 7. **Gateway neu starten** — `systemctl --user restart openclaw-gateway` 8. **Testen** — `openclaw status` + Kanal-Test --- ## Architektur auf einen Blick ``` Messaging-Kanäle (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, Matrix, Google Chat, Zalo, WebChat…) │ ▼ ┌───────────────────────────────┐ │ Gateway │ ← ws://127.0.0.1:18789 │ (Control-Plane, RPC) │ ← Config: ~/.openclaw/openclaw.json (JSON5) │ systemd user service │ ← Dashboard: http://127.0.0.1:18789 └──────────────┬────────────────┘ │ ┌──────┴──────┐ │ Agent(s) │ ← Workspace: ~/.openclaw/workspace/ │ Runtime │ ← Sessions: ~/.openclaw/agents/<id>/sessions/ └──────┬──────┘ │ ┌──────┴──────────────────────────┐ │ Nodes (optional) │ │ iOS / Android / macOS / Pi │ │ + Canvas / A2UI │ └─────────────────────────────────┘ ``` ### Verzeichnisstruktur ``` ~/.openclaw/ ├── openclaw.json # Haupt-Config (JSON5 – Kommentare + trailing commas!) ├── credentials/ # API-Keys (chmod 600!) │ ├── anthropic │ ├── openai │ └── openrouter ├── agents/ │ └── <agentId>/ │ ├── agent/ # Auth-Profile, Model-Registry │ └── sessions/ # Session-Logs (*.jsonl) ├── skills/ # Managed/lokale Skills ├── cron/ # Cron-Jobs (jobs.json, runs/) └── workspace/ # Agent-Workspace (= das "Gehirn") ├── AGENTS.md # Betriebsanweisungen (in JEDER Session geladen) ├── SOUL.md # Persönlichkeit, Ton, Grenzen (jede Session) ├── USER.md # Nutzerprofil (jede Session) ├── TOOLS.md # Tool-Hinweise (jede Session) ├── IDENTITY.md # Name, Emoji, Vibe ├── HEARTBEAT.md # Scheduled-Tasks / Cron-Checkliste ├── MEMORY.md # Langzeit-Gedächtnis (nur private Sessions!) ├── BOOT.md # Startup-Checkliste (bei Gateway-Restart) ├── BOOTSTRAP.md # Einmal-Setup (nach Ausführung gelöscht) ├── memory/ # Tages-Logs (YYYY-MM-DD.md) └── skills/ # Workspace-Skills ``` --- ## ⚡ Quick-Start: Häufige Aufgaben ### Neuinstallation ```bash pnpm add -g openclaw@latest && pnpm approve-builds -g openclaw onboard # Interaktiver Wizard openclaw doctor # Gesundheitscheck ``` ### Channel einrichten (WhatsApp) ```bash openclaw channels login --channel whatsapp --account personal openclaw pairing list whatsapp openclaw pairing approve whatsapp <CODE> ``` ### Multi-Agent Setup ```bash openclaw agents add work # Neuer Agent openclaw agents bind work "whatsapp:biz" # Routing-Regel ``` ### Memory mit Semantic Search ```json5 // In openclaw.json: agents: { defaults: { memorySearch: { provider: "openai", model: "text-embedding-3-small", query: { hybrid: { enabled: true }, mmr: { enabled: true, lambda: 0.7 }, temporalDecay: { enabled: true, halfLifeDays: 30 } } } } } ``` ### Sandbox aktivieren ```json5 agents: { defaults: { sandbox: { mode: "non-main", scope: "agent", workspaceAccess: "ro", docker: { image: "openclaw-sandbox:bookworm-slim" } } } } ``` ### Cron-Job erstellen ```bash openclaw cron add --name "Tageszusammenfassung" \ --cron "0 7 * * *" \ --message "Fasse die wichtigsten Ereignisse zusammen" \ --announce ``` ### Config-Problem debuggen ```bash openclaw config validate openclaw doctor --fix systemctl --user restart openclaw-gateway ``` --- ## Referenzdateien — Wann was lesen Dieses Skill-Paket enthält detaillierte Referenzdateien. **Lies die relevante Datei BEVOR du eine Aktion durchführst.** Die Dateien liegen unter `references/` im Skill-Verzeichnis. | Aufgabe | Referenzdatei | Inhalt | |---|---|---| | **Schnellnachschlage** | `references/quick-reference.md` | Einseitige Referenz: Verzeichnisse, Minimal-Config, CLI-Einzeiler, Troubleshooting-Patterns | | Installation & erste Schritte | `references/installation.md` | npm/pnpm, Docker, VPS-Setup, Onboarding-Wizard | | openclaw.json bearbeiten | `references/config-reference.md` | Vollständige Feld-Referenz (agents, models, channels, session, secrets, bindings, $include…) | | Dashboard (Control UI) | `references/dashboard.md` | Alle Dashboard-Bereiche, Zugriff, Troubleshooting | | Workspace-Dateien schreiben | `references/workspace-files.md` | AGENTS.md, SOUL.md, USER.md, HEARTBEAT.md, MEMORY.md Templates | | Channels einrichten | `references/channels.md` | Telegram (komplett!), WhatsApp, Discord, Slack, Signal + Troubleshooting | | Memory & Compaction tunen | `references/memory-system.md` | memoryFlush, memorySearch, Compaction, Semantic Search, Decay | | Docker-Deployment | `references/docker-setup.md` | docker-compose, Sandbox, alpine/openclaw, Permissions | | Security-Hardening | `references/security-hardening.md` | dmPolicy, SecretRef, Token-Rotation, Allowlists, Sandboxing, CIS-Style | | Skills entwickeln/installieren | `references/skills-guide.md` | SKILL.md-Format, ClawHub, Workspace-Skills, Security-Review | | Multi-Agent-Routing | `references/multi-agent.md` | agents.list, bindings, accountId, agentId, Isolation, Per-Agent Sandbox/Tools | | CLI-Referenz | `references/cli-reference.md` | Alle Befehle mit Syntax und Beispielen (agents, browser, cron, secrets, sandbox…) | | Dashboard / Control UI | `references/dashboard.md` | Sidebar-Navigation, Bereiche, CORS, Config, Troubleshooting | | Nodes & Remote-Zugriff | `references/nodes-and-remote.md` | Node-Typen, Pairing, Headless-Nodes, Bonjour/mDNS, Exec-Approval | | Tailscale-Integration | `references/tailscale-integration.md` | Serve vs Funnel vs Tailnet-Bind, SSH-Tunnel, Auth, Config-Beispiele | | Praxis-Beispiele | `references/examples.md` | 7 vollständige Setup-Szenarien (Einsteiger → Multi-Agent → Kosten-optimiert) | | Troubleshooting | `references/troubleshooting.md` | Häufige Fehler, Logs, Diagnose-Schritte, SecretRef, Sandbox, Skill-Gating | | Tricks & Power-User | `references/tricks-and-hacks.md` | Community-Tipps, Cost-Saving, Obsidian, Surge, Watchdog | > **Companion Skill**: Für Cognee Knowledge-Graph-Memory (Docker-Setup, LLM/Embedding-Config, > Ollama Cloud + OpenAI Hybrid, Plugin-Troubleshooting) → den **`cognee-openclaw-memory` Skill** nutzen. --- ## Schnellreferenz: Wichtigste CLI-Befehle ```bash # Status & Diagnose openclaw --version # CalVer-Version openclaw doctor # Gesundheitscheck (IMMER!) openclaw doctor --fix # Auto-Fix openclaw status # Kurzer Status openclaw dashboard # Browser-UI (Port 18789) # Gateway openclaw gateway start|stop|restart|status openclaw gateway install # systemd user service openclaw gateway log # Logs (= journalctl --user -u openclaw-gateway -f) # Agents (Multi-Agent) openclaw agents list # Agent-Liste openclaw agents add <id> # Neuen Agent erstellen openclaw agents bind <agent> <binding> # Binding hinzufügen openclaw agents unbind <agent> <binding> # Binding entfernen # Channels openclaw channels list|add|remove|restart openclaw channels status --probe # Live-Check openclaw channels login --channel whatsapp --account <id> # WhatsApp Account # Models openclaw models list|set <provider/model> openclaw models auth setup-token # Interaktiver Auth-Setup # Skills openclaw skills list|reload clawhub search|install|update <name> # Secrets (Secure Credential Management) openclaw secrets audit # Plaintext-Scan openclaw secrets configure # Interaktiver Wizard openclaw secrets reload # Runtime-Refresh # Cron Jobs openclaw cron list # Alle Jobs openclaw cron add --name "..." --cron "0 7 * * *" --message "..." --announce openclaw cron runs --id <jobId> # Run-History # Browser Automation openclaw browser start|stop|status # Sandbox openclaw sandbox list|status # Memory & Sessions openclaw sessions list|clean openclaw memory flush # Security openclaw token:rotate --force --length 64 openclaw security audit --deep # Nodes & Devices openclaw nodes status # Verbundene Nodes anzeigen openclaw nodes describe --all # Node-Capabilities auflisten openclaw nodes run --node <id> -- <cmd> # Befehl auf Node ausführen openclaw devices list # Pairing-Requests anzeigen openclaw devices approve <requestId> # Node-Pairing genehmigen # Channel-Pairing openclaw pairing list|approve <channel> <code> # Config openclaw config list|get|set|validate # Hooks openclaw hooks list|test # Webhooks openclaw webhooks list|test # DNS (für Nodes) openclaw dns setup|status # Update pnpm add -g openclaw@latest && pnpm approve-builds -g && openclaw doctor ``` --- ## Sicherheits-Grundregeln (IMMER beachten!) 1. **Gateway bind: `loopback`** — Niemals `lan` oder `0.0.0.0` ohne Tailscale/VPN 2. **dmPolicy: `allowlist` oder `pairing`** — Niemals `open` in Produktion 3. **Token: mindestens 64 Zeichen** — `openclaw token:rotate --force --length 64` 4. **Secrets mit SecretRef** — API-Keys nie im Plaintext in Config, `openclaw secrets configure` 5. **Credentials: `chmod 600`** — `chmod 600 ~/.openclaw/credentials/*` 6. **Skills reviewen** — Vor Installation Quellcode prüfen, ClawHub "Hide Suspicious" nutzen 7. **Kein root** — OpenClaw als eigener User betreiben 8. **Workspace = privat** — Git-Backup in **privates** Repo, MEMORY.md nie in Groups laden 9. **API-Spending-Limits** — Beim Provider setzen, bevor Heartbeat aktiviert wird 10. **Sandbox für Tools** — `agents.defaults.sandbox.mode: "all"` wenn möglich --- ## Workflow: Docs nachschlagen ### Offizielle Docs-URLs (für web_fetch) ``` https://docs.openclaw.ai # Hauptseite https://docs.openclaw.ai/install/docker # Docker https://docs.openclaw.ai/concepts/agent-workspace # Workspace https://docs.openclaw.ai/concepts/memory # Memory https://docs.openclaw.ai/concepts/multi-agent # Multi-Agent https://docs.openclaw.ai/concepts/session # Session Management https://docs.openclaw.ai/automation/cron-jobs # Cron Jobs https://docs.openclaw.ai/gateway/secrets # Secrets Management https://docs.openclaw.ai/gateway/configuration # Config https://docs.openclaw.ai/channels/<name> # Channel-Guides https://docs.openclaw.ai/models # Models https://docs.openclaw.ai/tools/skills # Skills https://docs.openclaw.ai/security # Security ``` Alternative Docs-Mirror: `https://openclaw.im/docs/` ### Community-Suche (für web_search) ``` "openclaw <Thema> 2026 tips" "openclaw <Problem> fix workaround github issue" "openclaw.json <Section> advanced configuration" ``` Quellen-Priorität: 1. `github.com/openclaw/openclaw` (Issues, Discussions, AGENTS.md) 2. `docs.openclaw.ai` / `openclaw.im/docs` 3. Community-Guides (Simon Willison TIL, Substack, Medium) 4. Reddit r/selfhosted, Hacker News --- ## Backup-Strategie (IMMER vor Änderungen) ```bash # Snapshot der Config cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak # Versioniertes Backup tar czf ~/openclaw-backup-$(date +%Y%m%d_%H%M%S).tar.gz ~/.openclaw/ # Git-Backup des Workspace (empfohlen) cd ~/.openclaw/workspace && git add -A && git commit -m "backup: $(date +%Y%m%d_%H%M%S)" ``` --- ## Protokoll: Sichere Config-Änderung 1. `openclaw --version` → Version notieren 2. Relevante Referenzdatei lesen (siehe Tabelle oben) 3. Live-Docs fetchen (URLs oben) 4. `cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak` 5. Änderung durchführen 6. `openclaw doctor` 7. `systemctl --user restart openclaw-gateway` 8. `openclaw status` + Funktionstest im Channel 9. Bei Fehler: `cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json && systemctl --user restart openclaw-gateway` --- ## Wichtige Konzepte (Kurzreferenz) ### Multi-Agent-Routing ```json5 { agents: { list: [ { id: "home", default: true, workspace: "~/.openclaw/workspace-home" }, { id: "work", workspace: "~/.openclaw/workspace-work" }, ], }, bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }, ], } ``` ### Session-DmScope - `main` — Alle DMs teilen eine Session (Single-User) - `per-channel-peer` — DMs pro Channel+Sender isolieren (Multi-User empfohlen) - `per-account-channel-peer` — DMs pro Account+Channel+Sender (Multi-Account) ### Config-Hot-Reload | Modus | Verhalten | |---|---| | `hybrid` | Auto-Applie + Auto-Restart für Kritisches | | `hot` | Nur Hot-Applie, Warnung bei Restart-Bedarf | | `restart` | Immer Restart bei Änderung | | `off` | Kein File-Watching | ### SecretRef ```json5 // Env-Variable { source: "env", provider: "default", id: "OPENAI_API_KEY" } // File { source: "file", provider: "filemain", id: "/providers/openai/apiKey" } // Exec (1Password, Vault, sops) { source: "exec", provider: "vault", id: "providers/openai/apiKey" } ```