OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Technical reference

Onboarding-Referenz

Dies ist die vollständige Referenz für openclaw onboard. Eine allgemeine Übersicht finden Sie unter Onboarding (CLI). Informationen zum schrittweisen Verhalten und zu den Ausgaben finden Sie in der Referenz zur CLI-Einrichtung.

Ablaufdetails (lokaler Modus)

  • Zurücksetzen (optional)

    • --reset setzt den Zustand zurück, bevor die Einrichtung ausgeführt wird; ohne diese Option behält eine erneute Ausführung des Onboardings die vorhandene Konfiguration bei und verwendet sie erneut als Standardwerte.
    • --reset-scope steuert, was --reset entfernt: config (nur die Konfigurationsdatei), config+creds+sessions (Standard) oder full (entfernt außerdem den Workspace).
    • Wenn die Konfigurationsdatei ungültig ist, wird das Onboarding beendet und Sie werden aufgefordert, zuerst openclaw doctor auszuführen und anschließend die Einrichtung erneut zu starten.
    • Beim Zurücksetzen wird der Zustand in den Papierkorb verschoben (niemals direkt gelöscht).

  • Risikobestätigung

    • Bei der ersten Ausführung (oder jeder Ausführung, bevor wizard.securityAcknowledgedAt festgelegt ist) werden Sie aufgefordert zu bestätigen, dass Sie verstehen, dass Agenten leistungsfähig sind und ein vollständiger Systemzugriff riskant ist.
    • --non-interactive erfordert ausdrücklich --accept-risk; ohne diese Option wird das Onboarding mit einem Fehler beendet, statt eine Eingabeaufforderung anzuzeigen.
    • Bei interaktiven Ausführungen erscheint statt der Option eine Bestätigungsaufforderung; eine Ablehnung bricht die Einrichtung ab.

  • Modell/Authentifizierung

    • Anthropic-API-Schlüssel: Verwendet ANTHROPIC_API_KEY, falls vorhanden, oder fordert zur Eingabe eines Schlüssels auf und speichert ihn anschließend für die Verwendung durch den Daemon.
    • Anthropic Claude CLI: Bevorzugter lokaler Pfad, wenn bereits eine Claude-CLI-Anmeldung vorhanden ist; OpenClaw unterstützt alternativ weiterhin die Authentifizierung mit einem Anthropic-Einrichtungstoken.
    • OpenAI-Code-(Codex-)Abonnement (OAuth): Browserablauf; fügen Sie code#state ein.
      • Bei einer neuen Einrichtung ohne primäres Modell wird agents.defaults.model über die Codex-Laufzeit auf openai/gpt-5.6-sol gesetzt.
    • OpenAI-Code-(Codex-)Abonnement (Gerätekopplung): Browserbasierter Kopplungsablauf mit einem kurzlebigen Gerätecode.
      • Bei einer neuen Einrichtung ohne primäres Modell wird agents.defaults.model über die Codex-Laufzeit auf openai/gpt-5.6-sol gesetzt.
    • OpenAI-API-Schlüssel: Verwendet OPENAI_API_KEY, falls vorhanden, oder fordert zur Eingabe eines Schlüssels auf und speichert ihn anschließend in Authentifizierungsprofilen.
      • Bei einer neuen Einrichtung ohne primäres Modell wird agents.defaults.model auf openai/gpt-5.6 gesetzt; die reine Modell-ID der direkten API wird der Sol-Stufe zugeordnet.
    • Beim Hinzufügen oder erneuten Authentifizieren von OpenAI bleibt ein vorhandenes, explizit festgelegtes primäres Modell einschließlich openai/gpt-5.5 erhalten. Wenn das Konto GPT-5.6 nicht bereitstellt, wählen Sie ausdrücklich openai/gpt-5.5; OpenClaw stuft das Modell nicht stillschweigend herab.
    • xAI OAuth: Browseranmeldung per Gerätecode ohne erforderlichen localhost-Callback, sodass sie auch über SSH/Docker/VPS funktioniert (--auth-choice xai-oauth).
    • xAI-API-Schlüssel: Fordert zur Eingabe von XAI_API_KEY auf (--auth-choice xai-api-key).
    • --auth-choice xai-device-code funktioniert weiterhin als ausschließlich manuell verwendbarer Kompatibilitätsalias für denselben xAI-OAuth-Gerätecodeablauf; verwenden Sie für neue Skripte xai-oauth.
    • OpenCode: Fordert zur Eingabe von OPENCODE_API_KEY auf (oder OPENCODE_ZEN_API_KEY, erhältlich unter https://opencode.ai/auth) und ermöglicht Ihnen die Auswahl des Zen- oder Go-Katalogs.
    • Ollama: Bietet zunächst Cloud + lokal, Nur Cloud oder Nur lokal an. Cloud only fordert zur Eingabe von OLLAMA_API_KEY auf und verwendet https://ollama.com; die hostgestützten Modi fordern zur Eingabe der Ollama-Basis-URL auf (Standard http://127.0.0.1:11434), ermitteln verfügbare Modelle und laden das ausgewählte lokale Modell bei Bedarf automatisch herunter; Cloud + Local prüft außerdem, ob dieser Ollama-Host für den Cloud-Zugriff angemeldet ist.
    • Weitere Einzelheiten: Ollama
    • API-Schlüssel: Speichert den Schlüssel für Sie.
    • Vercel AI Gateway (Proxy für mehrere Modelle): Fordert zur Eingabe von AI_GATEWAY_API_KEY auf.
    • Weitere Einzelheiten: Vercel AI Gateway
    • Cloudflare AI Gateway: Fordert zur Eingabe von Konto-ID, Gateway-ID und CLOUDFLARE_AI_GATEWAY_API_KEY auf.
    • Weitere Einzelheiten: Cloudflare AI Gateway
    • MiniMax: Die Konfiguration wird automatisch geschrieben; der gehostete Standard ist MiniMax-M3. Die Einrichtung per API-Schlüssel verwendet minimax/..., die OAuth-Einrichtung verwendet minimax-portal/....
    • Weitere Einzelheiten: MiniMax
    • StepFun: Die Konfiguration wird für StepFun Standard oder Step Plan auf chinesischen oder globalen Endpunkten automatisch geschrieben.
    • Standard verwendet derzeit standardmäßig step-3.5-flash; Step Plan umfasst außerdem step-3.5-flash-2603.
    • Weitere Einzelheiten: StepFun
    • Synthetic (Anthropic-kompatibel): Fordert zur Eingabe von SYNTHETIC_API_KEY auf.
    • Weitere Einzelheiten: Synthetic
    • Moonshot (Kimi K2): Die Konfiguration wird automatisch geschrieben.
    • Kimi Coding: Die Konfiguration wird automatisch geschrieben.
    • Weitere Einzelheiten: Moonshot AI (Kimi + Kimi Coding)
    • Benutzerdefinierter Provider: Funktioniert mit OpenAI-kompatiblen, OpenAI-Responses-kompatiblen oder Anthropic-kompatiblen Endpunkten. Optionen für den nicht interaktiven Modus: --auth-choice custom-api-key, --custom-base-url, --custom-model-id, --custom-api-key (optional; verwendet ersatzweise CUSTOM_API_KEY), --custom-provider-id (optional; wird automatisch aus der Basis-URL abgeleitet), --custom-compatibility openai|openai-responses|anthropic (Standard openai), --custom-image-input / --custom-text-input (überschreibt die abgeleitete Erkennung von Vision-Modellen).
    • Überspringen: Es ist noch keine Authentifizierung konfiguriert.
    • Wählen Sie aus den erkannten Optionen ein Standardmodell aus (oder geben Sie Provider/Modell manuell ein). Wählen Sie für die beste Qualität und ein geringeres Risiko durch Prompt-Injection das leistungsfähigste verfügbare Modell der neuesten Generation in Ihrem Provider-Stack.
    • Das Onboarding führt eine Modellprüfung aus und warnt, wenn das konfigurierte Modell unbekannt ist oder die Authentifizierung fehlt.
    • Der Speichermodus für API-Schlüssel verwendet standardmäßig Klartextwerte in Authentifizierungsprofilen. Verwenden Sie --secret-input-mode ref, um stattdessen umgebungsvariablengestützte Referenzen zu speichern (zum Beispiel keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }); die referenzierte Umgebungsvariable muss bereits festgelegt sein, andernfalls schlägt das Onboarding sofort fehl.
    • Authentifizierungsprofile befinden sich in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (API-Schlüssel + OAuth). ~/.openclaw/credentials/oauth.json dient nur dem Import aus Altsystemen.
    • Weitere Einzelheiten: OAuth

  • Workspace

    • Standardmäßig ~/.openclaw/workspace (konfigurierbar).
    • Legt die Workspace-Dateien an, die für das Bootstrap-Ritual des Agenten erforderlich sind.
    • Vollständiges Workspace-Layout und Sicherungsleitfaden: Agenten-Workspace

  • Gateway

    • Port (Standard 18789), Bindung, Authentifizierungsmodus, Tailscale-Freigabe.
    • Authentifizierungsempfehlung: Behalten Sie Token auch für Loopback bei, damit sich lokale WS-Clients authentifizieren müssen.
    • Im Token-Modus bietet die interaktive Einrichtung Folgendes an:
      • Klartexttoken generieren/speichern (Standard)
      • SecretRef verwenden (Opt-in)
      • Der Schnellstart verwendet vorhandene gateway.auth.token-SecretRefs für die Provider env, file und exec erneut, um die Onboarding-Prüfung und das Dashboard-Bootstrap durchzuführen.
      • Wenn diese SecretRef konfiguriert ist, aber nicht aufgelöst werden kann, schlägt das Onboarding frühzeitig mit einer klaren Korrekturmeldung fehl, statt die Laufzeitauthentifizierung stillschweigend abzuschwächen.
    • Im Passwortmodus unterstützt die interaktive Einrichtung ebenfalls die Speicherung als Klartext oder SecretRef.
    • Nicht interaktiver Token-SecretRef-Pfad: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • Erfordert eine nicht leere Umgebungsvariable in der Prozessumgebung des Onboardings.
      • Kann nicht mit --gateway-token kombiniert werden.
    • Deaktivieren Sie die Authentifizierung nur, wenn Sie jedem lokalen Prozess vollständig vertrauen.
    • Bindungen außerhalb von Loopback erfordern weiterhin eine Authentifizierung.

  • Kanäle

    • WhatsApp: Optionale QR-Anmeldung.
    • Telegram: Bot-Token.
    • Discord: Bot-Token.
    • Google Chat: Dienstkonto-JSON + Webhook-Zielgruppe.
    • Mattermost (Plugin): Bot-Token + Basis-URL.
    • Signal (Plugin): Optionale Installation von signal-cli + Kontokonfiguration.
    • iMessage: Pfad zur imsg-CLI + Zugriff auf die Messages-Datenbank; verwenden Sie einen SSH-Wrapper, wenn der Gateway nicht auf einem Mac ausgeführt wird.
    • Discord, Feishu, Microsoft Teams, QQ Bot, Slack und weitere Kanäle werden als Plugins ausgeliefert, die das Onboarding für Sie installieren kann. Vollständiger Katalog: Kanäle.
    • DM-Sicherheit: Standardmäßig wird eine Kopplung verwendet. Die erste DM sendet einen Code; genehmigen Sie ihn mit openclaw pairing approve <channel> <code> oder verwenden Sie Zulassungslisten.

  • Websuche

    • Wählen Sie einen unterstützten Provider wie Brave, Codex (gehostete Suche), DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Parallel, Perplexity, SearXNG oder Tavily aus (oder überspringen Sie diesen Schritt).
    • API-gestützte Provider können für die Schnelleinrichtung Umgebungsvariablen oder eine vorhandene Konfiguration verwenden; Provider ohne Schlüssel verwenden stattdessen ihre providerspezifischen Voraussetzungen.
    • Überspringen Sie den Schritt mit --skip-search.
    • Später konfigurieren: openclaw configure --section web.

  • Daemon-Installation

    • macOS: LaunchAgent
      • Erfordert eine angemeldete Benutzersitzung; verwenden Sie für Headless-Systeme einen benutzerdefinierten LaunchDaemon (nicht enthalten).
    • Linux (und Windows über WSL2): systemd-Benutzereinheit
      • Das Onboarding versucht, den dauerhaften Betrieb mit loginctl enable-linger <user> zu aktivieren, damit der Gateway nach der Abmeldung weiter ausgeführt wird.
      • Möglicherweise wird sudo angefordert (schreibt nach /var/lib/systemd/linger); zunächst wird es ohne sudo versucht.
    • Natives Windows: Zunächst eine geplante Aufgabe; wenn das Erstellen der Aufgabe verweigert wird, verwendet OpenClaw ersatzweise ein benutzerspezifisches Anmeldeelement im Autostartordner und startet den Gateway sofort.
    • Laufzeitauswahl: Node (empfohlen; für WhatsApp/Telegram erforderlich – Bun kann beim erneuten Verbinden den Speicher beschädigen). Interaktiv wird nur Node angeboten; --daemon-runtime bun ist ausschließlich über die CLI verfügbar.
    • Wenn die Token-Authentifizierung ein Token erfordert und gateway.auth.token über SecretRef verwaltet wird, validiert die Daemon-Installation dieses, speichert den aufgelösten Klartextwert des Tokens jedoch nicht dauerhaft in den Umgebungsmetadaten des Supervisor-Dienstes.
    • Wenn die Token-Authentifizierung ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst werden kann, wird die Daemon-Installation mit konkreten Hinweisen zur Behebung blockiert.
    • Wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind und gateway.auth.mode nicht festgelegt ist, wird die Daemon-Installation blockiert, bis der Modus ausdrücklich festgelegt wurde.

  • Integritätsprüfung

    • Startet den Gateway (falls erforderlich) und führt openclaw health aus.
    • Tipp: openclaw status --deep ergänzt die Statusausgabe um die Live-Integritätsprüfung des Gateways, einschließlich Kanalprüfungen, sofern unterstützt (erfordert einen erreichbaren Gateway).

  • Skills (empfohlen)

    • Liest die verfügbaren Skills und prüft die Anforderungen.
    • Ermöglicht Ihnen die Auswahl eines Node-Managers: npm / pnpm / bun.
    • Installiert optionale Abhängigkeiten für vertrauenswürdige, mitgelieferte Skills automatisch (einige verwenden Homebrew unter macOS).
    • Überspringt Skills, deren Voraussetzung für die Installation über Homebrew, uv oder Go nicht verfügbar ist, gruppiert sie mit Anleitungen zur manuellen Einrichtung und verweist Sie auf openclaw doctor, sobald die Voraussetzung installiert wurde.

  • Abschluss

    • Zusammenfassung und nächste Schritte, einschließlich der Aufforderung Wie möchten Sie Ihren Agenten schlüpfen lassen? mit den Optionen Terminal, Browser oder später.

    • Nicht interaktiver Modus

    Verwenden Sie --non-interactive --accept-risk, um das Onboarding zu automatisieren oder per Skript auszuführen (die Option stellt die erforderliche Risikobestätigung dar; ohne sie wird das Onboarding mit einem Fehler beendet):

    bash
    openclaw onboard --non-interactive --accept-risk \  --mode local \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY" \  --gateway-port 18789 \  --gateway-bind loopback \  --install-daemon \  --daemon-runtime node \  --skip-skills

    Fügen Sie --json hinzu, um eine maschinenlesbare Zusammenfassung zu erhalten.

    Gateway-Token-SecretRef im nicht interaktiven Modus:

    bash
    export OPENCLAW_GATEWAY_TOKEN="your-token"openclaw onboard --non-interactive --accept-risk \  --mode local \  --auth-choice skip \  --gateway-auth token \  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

    --gateway-token und --gateway-token-ref-env schließen sich gegenseitig aus.

    Providerspezifische Befehlsbeispiele finden Sie unter CLI-Automatisierung. Auf dieser Referenzseite finden Sie die Bedeutung der Flags und die Reihenfolge der Schritte.

    Agent hinzufügen (nicht interaktiv)

    bash
    openclaw agents add work \  --workspace ~/.openclaw/workspace-work \  --model openai/gpt-5.6-sol \  --bind whatsapp:biz \  --non-interactive \  --json

    main ist eine reservierte Agent-ID und kann nicht für openclaw agents add verwendet werden.

    Gateway-Assistenten-RPC

    Das Gateway stellt den Onboarding-Ablauf über RPC bereit (wizard.start, wizard.next, wizard.cancel, wizard.status). Clients (macOS-App, Control UI) können die Schritte darstellen, ohne die Onboarding-Logik neu zu implementieren.

    Signal-Einrichtung (signal-cli)

    Beim Onboarding wird erkannt, ob sich signal-cli im PATH befindet. Falls es fehlt, wird dessen Installation angeboten:

    • Linux x86-64: Lädt den offiziellen nativen GraalVM-Build aus den GitHub-Releases von signal-cli herunter und speichert ihn unter ~/.openclaw/tools/signal-cli/<version>/.
    • macOS und andere Architekturen: Installiert es stattdessen über Homebrew.
    • Natives Windows: Wird noch nicht unterstützt; führen Sie das Onboarding innerhalb von WSL2 aus, um den Linux-Installationspfad zu erhalten.
    • Schreibt in jedem Fall channels.signal.cliPath in Ihre Konfiguration.

    Was der Assistent schreibt

    Typische Felder in ~/.openclaw/openclaw.json:

    • agents.defaults.workspace
    • agents.defaults.skipBootstrap, wenn --skip-bootstrap übergeben wird
    • agents.defaults.model / models.providers (wenn Minimax ausgewählt wurde)
    • tools.profile (beim lokalen Onboarding standardmäßig "coding", wenn nicht festgelegt; vorhandene explizite Werte bleiben erhalten)
    • gateway.* (Modus, Bindung, Authentifizierung, Tailscale)
    • session.dmScope (beim lokalen Onboarding standardmäßig "per-channel-peer", wenn nicht festgelegt; vorhandene explizite Werte bleiben erhalten. Details: Referenz zur CLI-Einrichtung)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • Zulassungslisten für Direktnachrichten der Kanäle, wenn Sie diese während der Kanalabfragen aktivieren. Discord, Matrix, Microsoft Teams und Slack lösen Namen nach Möglichkeit in IDs auf; andere Kanäle übernehmen IDs direkt (beispielsweise numerische Telegram-Absender-IDs oder WhatsApp-Telefonnummern).
    • skills.install.nodeManager
      • setup --node-manager akzeptiert npm, pnpm oder bun.
      • Bei manueller Konfiguration kann weiterhin yarn verwendet werden, indem skills.install.nodeManager direkt festgelegt wird.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode
    • wizard.securityAcknowledgedAt

    openclaw agents add schreibt agents.list[] und optional bindings.

    WhatsApp-Anmeldedaten werden unter ~/.openclaw/credentials/whatsapp/<accountId>/ gespeichert. Aktive Sitzungen und Transkripte werden in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite gespeichert. Das Verzeichnis ~/.openclaw/agents/<agentId>/sessions/ wird für Eingaben zur Migration älterer Daten sowie für Archiv- und Support-Artefakte verwendet.

    Einige Kanäle werden als Plugins bereitgestellt. Wenn Sie während der Einrichtung einen davon auswählen, fordert das Onboarding Sie auf, ihn zu installieren (über npm oder einen lokalen Pfad), bevor er konfiguriert werden kann.

    Zugehörige Dokumentation

    Was this useful?
    On this page

    On this page