Setup

Zuletzt aktualisiert: 01.01.2026

TL;DR

  • Anpassungen liegen außerhalb des Repos: ~/.openclaw/workspace (Workspace) + ~/.openclaw/openclaw.json (Config).
  • Stabiler Workflow: Installiere die macOS-App und lass sie den mitgelieferten Gateway starten.
  • Bleeding-Edge-Workflow: Starte den Gateway selbst mit pnpm gateway:watch, dann verbindet sich die macOS-App im Local-Modus.

Voraussetzungen (aus dem Quellcode)

  • Node >=22
  • pnpm
  • Docker (optional; nur für containerisiertes Setup/E2E — siehe Docker)

Anpassungsstrategie (damit Updates nicht wehtun)

Wenn du “100 % auf mich zugeschnitten” und einfache Updates willst, leg deine Anpassungen hier ab:

  • Config: ~/.openclaw/openclaw.json (JSON/JSON5-ähnlich)
  • Workspace: ~/.openclaw/workspace (Skills, Prompts, Memories; mach daraus ein privates Git-Repo)

Einmalig bootstrappen:

openclaw setup

Wenn du im Repo bist, nutze den lokalen CLI-Einstiegspunkt:

openclaw setup

Falls du noch keine globale Installation hast, führe es mit pnpm openclaw setup aus.

Stabiler Workflow (macOS-App zuerst)

  1. Installiere und starte OpenClaw.app (Menüleiste).
  2. Schließe die Onboarding-/Berechtigungs-Checkliste ab (TCC-Prompts).
  3. Stelle sicher, dass der Gateway auf Local steht und läuft (die App verwaltet ihn).
  4. Verbinde Surfaces (Beispiel: WhatsApp):
openclaw channels login
  1. Sanity-Check:
openclaw health

Falls Onboarding in deinem Build nicht verfügbar ist:

  • Führe openclaw setup aus, dann openclaw channels login, dann starte den Gateway manuell (openclaw gateway).

Bleeding-Edge-Workflow (Gateway im Terminal)

Ziel: Am TypeScript-Gateway arbeiten, Hot-Reload nutzen, macOS-App-UI angebunden lassen.

0) (Optional) macOS-App auch aus dem Quellcode starten

Falls du auch die macOS-App auf dem neuesten Stand haben willst:

./scripts/restart-mac.sh

1) Dev-Gateway starten

pnpm install
pnpm gateway:watch

gateway:watch startet den Gateway im Watch-Modus und lädt bei TypeScript-Änderungen neu.

2) macOS-App auf deinen laufenden Gateway zeigen lassen

In OpenClaw.app:

  • Connection Mode: Local Die App verbindet sich mit dem laufenden Gateway auf dem konfigurierten Port.

3) Verifizieren

  • Der Gateway-Status in der App sollte “Using existing gateway …” anzeigen
  • Oder per CLI:
openclaw health

Häufige Stolperfallen

  • Falscher Port: Gateway-WS nutzt standardmäßig ws://127.0.0.1:18789; halte App + CLI auf demselben Port.
  • Wo liegt der State:
    • Credentials: ~/.openclaw/credentials/
    • Sessions: ~/.openclaw/agents/<agentId>/sessions/
    • Logs: /tmp/openclaw/

Credential-Storage-Map

Nutze das beim Debuggen von Auth oder wenn du entscheidest, was du sichern willst:

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram-Bot-Token: config/env oder channels.telegram.tokenFile
  • Discord-Bot-Token: config/env (Token-Datei noch nicht unterstützt)
  • Slack-Tokens: config/env (channels.slack.*)
  • Pairing-Allowlists: ~/.openclaw/credentials/<channel>-allowFrom.json
  • Model-Auth-Profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Legacy-OAuth-Import: ~/.openclaw/credentials/oauth.json Mehr Details: Security.

Updaten (ohne dein Setup zu zerstören)

  • Behandle ~/.openclaw/workspace und ~/.openclaw/ als “dein Zeug”; pack keine persönlichen Prompts/Configs ins openclaw-Repo.
  • Quellcode updaten: git pull + pnpm install (wenn sich die Lockfile geändert hat) + weiter pnpm gateway:watch nutzen.

Linux (systemd-User-Service)

Linux-Installationen nutzen einen systemd-User-Service. Standardmäßig stoppt systemd User-Services beim Logout/Idle, was den Gateway killt. Onboarding versucht, Lingering für dich zu aktivieren (fragt ggf. nach sudo). Falls es noch aus ist, führe aus:

sudo loginctl enable-linger $USER

Für Always-on- oder Multi-User-Server solltest du einen System-Service statt eines User-Service nutzen (kein Lingering nötig). Siehe Gateway-Runbook für die systemd-Hinweise.

Verwandte Docs