Setup

Hinweis: Wenn du zum ersten Mal einrichtest, starte mit Erste Schritte. Fur Wizard-Details siehe Onboarding-Wizard.

Zuletzt aktualisiert: 2026-01-01

TL;DR

Anpassungen leben ausserhalb des Repos: ~/.openclaw/workspace (Workspace) + ~/.openclaw/openclaw.json (Config).
Stabiler Workflow: macOS-App installieren; sie betreibt das gebundelte Gateway.
Bleeding-Edge-Workflow: Gateway selbst via pnpm gateway:watch starten, dann die macOS-App im Local-Modus anbinden.

Voraussetzungen (From Source)

Node >=22
pnpm
Docker (optional; nur fur containerisiertes Setup/E2E — siehe Docker)

Anpassungsstrategie (damit Updates nicht wehtun)

Wenn du “100 % auf mich zugeschnitten” und einfache Updates willst, halte deine Anpassungen in:

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

Einmalig bootstrappen:

openclaw setup

Innerhalb dieses Repos nutze den lokalen CLI-Entry:

openclaw setup

Falls du noch keine globale Installation hast, fuhre es via pnpm openclaw setup aus.

Gateway aus diesem Repo starten

Nach pnpm build kannst du die gepackte CLI direkt ausfuhren:

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

Stabiler Workflow (macOS-App zuerst)

OpenClaw.app installieren und starten (Menuleiste).
Onboarding-/Berechtigungs-Checkliste durchlaufen (TCC-Prompts).
Sicherstellen, dass das Gateway auf Lokal steht und lauft (die App verwaltet es).
Oberflachen verbinden (Beispiel: WhatsApp):

openclaw channels login

Sanity Check:

openclaw health

Falls Onboarding in deinem Build nicht verfugbar ist:

Fuhre openclaw setup aus, dann openclaw channels login, dann starte das Gateway manuell (openclaw gateway).

Bleeding-Edge-Workflow (Gateway im Terminal)

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

0) (Optional) macOS-App ebenfalls from Source starten

Wenn du auch die macOS-App auf dem Bleeding Edge willst:

./scripts/restart-mac.sh

1) Dev-Gateway starten

pnpm install
pnpm gateway:watch

gateway:watch startet das Gateway im Watch-Modus und ladt bei TypeScript-Anderungen neu.

2) macOS-App auf dein laufendes Gateway zeigen

In OpenClaw.app:

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

3) Verifizieren

Der In-App-Gateway-Status sollte “Using existing gateway …” anzeigen.
Oder via CLI:

openclaw health

Haufige Stolperfallen

Falscher Port: Gateway-WS ist standardmassig ws://127.0.0.1:18789; App und CLI mussen denselben Port verwenden.
Wo State gespeichert wird:
- Credentials: ~/.openclaw/credentials/
- Sessions: ~/.openclaw/agents/<agentId>/sessions/
- Logs: /tmp/openclaw/

Credential-Storage-Ubersicht

Praktisch 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 (nur regulare Datei; Symlinks werden abgelehnt)
Discord-Bot-Token: Config/Env oder SecretRef (Env/File/Exec Provider)
Slack-Tokens: Config/Env (channels.slack.*)
Pairing-Allowlists:
- ~/.openclaw/credentials/<channel>-allowFrom.json (Standard-Account)
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (Nicht-Standard-Accounts)
Model-Auth-Profile: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Dateibasierter Secrets-Payload (optional): ~/.openclaw/secrets.json
Legacy-OAuth-Import: ~/.openclaw/credentials/oauth.json Mehr Details: Sicherheit.

Updaten (ohne dein Setup zu ruinieren)

Halte ~/.openclaw/workspace und ~/.openclaw/ als “dein Kram”; packe keine personlichen Prompts/Configs ins openclaw-Repo.
Source updaten: git pull + pnpm install (wenn sich die Lockfile geandert hat) + weiterhin pnpm gateway:watch verwenden.

Linux (systemd User Service)

Linux-Installationen nutzen einen systemd-User-Service. Standardmassig beendet systemd User-Services bei Logout/Idle, was das Gateway killt. Das Onboarding versucht, Lingering fur dich zu aktivieren (erfordert moglicherweise sudo). Falls es noch deaktiviert ist:

sudo loginctl enable-linger $USER

Fur Always-on- oder Multi-User-Server ziehe einen System-Service statt eines User-Services in Betracht (kein Lingering notig). Siehe Gateway-Runbook fur systemd-Hinweise.