Erste Schritte

Ziel: von Null → erster funktionierender Chat (mit sinnvollen Standardeinstellungen) so schnell wie möglich.

Schnellster Chat: öffne die Control UI (kein Channel-Setup nötig). Führe openclaw dashboard aus und chatte im Browser, oder öffne http://127.0.0.1:18789/ auf dem Gateway-Host. Docs: Dashboard und Control UI.

Empfohlener Weg: nutze den CLI Onboarding Wizard (openclaw onboard). Er richtet ein:

  • Modell/Auth (OAuth empfohlen)
  • Gateway-Einstellungen
  • Channels (WhatsApp/Telegram/Discord/Mattermost (Plugin)/…)
  • Pairing-Standardeinstellungen (sichere DMs)
  • Workspace Bootstrap + Skills
  • optionaler Hintergrunddienst

Wenn du die ausführlichen Referenzseiten willst, spring zu: Wizard, Setup, Pairing, Security.

Sandboxing-Hinweis: agents.defaults.sandbox.mode: "non-main" nutzt session.mainKey (Standard "main"), sodass Gruppen-/Channel-Sessions in der Sandbox laufen. Wenn der Main-Agent immer auf dem Host laufen soll, setze ein explizites Per-Agent-Override:

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) Voraussetzungen

  • Node >=22
  • pnpm (optional; empfohlen wenn du aus dem Quellcode baust)
  • Empfohlen: Brave Search API Key für Websuche. Einfachster Weg: openclaw configure --section web (speichert tools.web.search.apiKey). Siehe Web Tools.

macOS: wenn du die Apps bauen willst, installiere Xcode / CLT. Für CLI + Gateway allein reicht Node. Windows: nutze WSL2 (Ubuntu empfohlen). WSL2 wird dringend empfohlen; natives Windows ist ungetestet, problematischer und hat schlechtere Tool-Kompatibilität. Installiere zuerst WSL2, dann führe die Linux-Schritte in WSL aus. Siehe Windows (WSL2).

1) CLI installieren (empfohlen)

curl -fsSL https://openclaw.ai/install.sh | bash

Installer-Optionen (Installationsmethode, nicht-interaktiv, von GitHub): Install.

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

Alternative (globale Installation):

npm install -g openclaw@latest
pnpm add -g openclaw@latest

2) Onboarding Wizard ausführen (und Service installieren)

openclaw onboard --install-daemon

Was du auswählen wirst:

  • Local vs Remote Gateway
  • Auth: OpenAI Code (Codex) Subscription (OAuth) oder API Keys. Für Anthropic empfehlen wir einen API Key; claude setup-token wird auch unterstützt.
  • Providers: WhatsApp QR-Login, Telegram/Discord Bot-Tokens, Mattermost Plugin-Tokens, etc.
  • Daemon: Hintergrundinstallation (launchd/systemd; WSL2 nutzt systemd)
    • Runtime: Node (empfohlen; erforderlich für WhatsApp/Telegram). Bun ist nicht empfohlen.
  • Gateway Token: der Wizard generiert standardmäßig einen (auch bei Loopback) und speichert ihn in gateway.auth.token.

Wizard-Doku: Wizard

Auth: wo sie gespeichert wird (wichtig)

  • Empfohlener Anthropic-Weg: setze einen API Key (der Wizard kann ihn für die Service-Nutzung speichern). claude setup-token wird auch unterstützt, wenn du Claude Code Credentials wiederverwenden willst.

  • OAuth Credentials (Legacy-Import): ~/.openclaw/credentials/oauth.json

  • Auth Profiles (OAuth + API Keys): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Headless/Server-Tipp: mach OAuth zuerst auf einem normalen Rechner, dann kopiere oauth.json zum Gateway-Host.

3) Gateway starten

Wenn du den Service während des Onboardings installiert hast, sollte das Gateway bereits laufen:

openclaw gateway status

Manueller Start (Vordergrund):

openclaw gateway --port 18789 --verbose

Dashboard (lokaler Loopback): http://127.0.0.1:18789/ Wenn ein Token konfiguriert ist, füge es in die Control UI Einstellungen ein (gespeichert als connect.params.auth.token).

⚠️ Bun-Warnung (WhatsApp + Telegram): Bun hat bekannte Probleme mit diesen Channels. Wenn du WhatsApp oder Telegram nutzt, führe das Gateway mit Node aus.

3.5) Schnelle Überprüfung (2 Min)

openclaw status
openclaw health
openclaw security audit --deep

4) Pairing + erste Chat-Oberfläche verbinden

WhatsApp (QR-Login)

openclaw channels login

Scanne via WhatsApp → Einstellungen → Verknüpfte Geräte.

WhatsApp-Doku: WhatsApp

Telegram / Discord / andere

Der Wizard kann Tokens/Config für dich schreiben. Wenn du manuelle Konfiguration bevorzugst, starte mit:

Telegram DM-Tipp: deine erste DM gibt einen Pairing-Code zurück. Genehmige ihn (siehe nächster Schritt), sonst antwortet der Bot nicht.

5) DM-Sicherheit (Pairing-Genehmigungen)

Standard-Verhalten: unbekannte DMs bekommen einen kurzen Code und Nachrichten werden nicht verarbeitet, bis sie genehmigt sind. Wenn deine erste DM keine Antwort bekommt, genehmige das Pairing:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

Pairing-Doku: Pairing

Aus dem Quellcode (Entwicklung)

Wenn du an OpenClaw selbst arbeitest, führe es aus dem Quellcode aus:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # installiert UI-Abhängigkeiten beim ersten Durchlauf automatisch
pnpm build
openclaw onboard --install-daemon

Wenn du noch keine globale Installation hast, führe den Onboarding-Schritt via pnpm openclaw ... aus dem Repo aus. pnpm build bündelt auch A2UI-Assets; wenn du nur diesen Schritt ausführen musst, nutze pnpm canvas:a2ui:bundle.

Gateway (aus diesem Repo):

node openclaw.mjs gateway --port 18789 --verbose

7) End-to-End-Überprüfung

In einem neuen Terminal, sende eine Testnachricht:

openclaw message send --target +15555550123 --message "Hello from OpenClaw"

Wenn openclaw health “no auth configured” zeigt, geh zurück zum Wizard und setze OAuth/Key-Auth — der Agent kann ohne sie nicht antworten.

Tipp: openclaw status --all ist der beste einfügbare, read-only Debug-Report. Health Probes: openclaw health (oder openclaw status --deep) fragt das laufende Gateway nach einem Health-Snapshot.

Nächste Schritte (optional, aber super)