English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Technical reference

Onboarding-Referenz

Dies ist die vollständige Referenz für openclaw onboard. Eine allgemeine Übersicht finden Sie unter Onboarding (CLI).

Ablaufdetails (lokaler Modus)

  • Erkennung vorhandener Konfiguration

    • Wenn ~/.openclaw/openclaw.json vorhanden ist, wählen Sie Behalten / Ändern / Zurücksetzen.
    • Das erneute Ausführen des Onboardings löscht nichts, es sei denn, Sie wählen ausdrücklich Zurücksetzen (oder übergeben --reset).
    • CLI --reset verwendet standardmäßig config+creds+sessions; verwenden Sie --reset-scope full, um auch den Arbeitsbereich zu entfernen.
    • Wenn die Konfiguration ungültig ist oder veraltete Schlüssel enthält, stoppt der Assistent und fordert Sie auf, openclaw doctor auszuführen, bevor Sie fortfahren.
    • Zurücksetzen verwendet trash (niemals rm) und bietet Bereiche an:
      • Nur Konfiguration
      • Konfiguration + Zugangsdaten + Sitzungen
      • Vollständiges Zurücksetzen (entfernt auch den Arbeitsbereich)

  • Modell/Auth

    • Anthropic API-Schlüssel: verwendet ANTHROPIC_API_KEY, falls vorhanden, oder fordert einen Schlüssel an und speichert ihn dann für die Daemon-Nutzung.
    • Anthropic API-Schlüssel: bevorzugte Anthropic-Assistentenauswahl in Onboarding/Konfiguration.
    • Anthropic setup-token: weiterhin in Onboarding/Konfiguration verfügbar, obwohl OpenClaw jetzt die Wiederverwendung der Claude CLI bevorzugt, wenn verfügbar.
    • OpenAI Code (Codex)-Abonnement (OAuth): Browser-Ablauf; fügen Sie code#state ein.
      • Setzt agents.defaults.model auf openai-codex/gpt-5.5, wenn kein Modell gesetzt ist oder bereits eine OpenAI-Familie verwendet wird.
    • OpenAI Code (Codex)-Abonnement (Gerätekopplung): Browser-Kopplungsablauf mit einem kurzlebigen Gerätecode.
      • Setzt agents.defaults.model auf openai-codex/gpt-5.5, wenn kein Modell gesetzt ist oder bereits eine OpenAI-Familie verwendet wird.
    • OpenAI API-Schlüssel: verwendet OPENAI_API_KEY, falls vorhanden, oder fordert einen Schlüssel an und speichert ihn dann in Auth-Profilen.
      • Setzt agents.defaults.model auf openai/gpt-5.5, wenn kein Modell gesetzt ist, openai/* oder openai-codex/*.
    • xAI (Grok) API-Schlüssel: fordert XAI_API_KEY an und konfiguriert xAI als Modell-Provider.
    • OpenCode: fordert OPENCODE_API_KEY (oder OPENCODE_ZEN_API_KEY, erhältlich unter https://opencode.ai/auth) an und lässt Sie den Zen- oder Go-Katalog auswählen.
    • Ollama: bietet zuerst Cloud + Lokal, Nur Cloud oder Nur lokal an. Cloud only fordert OLLAMA_API_KEY an und verwendet https://ollama.com; die hostgestützten Modi fordern die Ollama-Basis-URL an, erkennen verfügbare Modelle und ziehen das ausgewählte lokale Modell bei Bedarf automatisch; Cloud + Local prüft außerdem, ob dieser Ollama-Host für Cloud-Zugriff angemeldet ist.
    • Weitere Details: Ollama
    • API-Schlüssel: speichert den Schlüssel für Sie.
    • Vercel AI Gateway (Multi-Modell-Proxy): fordert AI_GATEWAY_API_KEY an.
    • Weitere Details: Vercel AI Gateway
    • Cloudflare AI Gateway: fordert Account-ID, Gateway-ID und CLOUDFLARE_AI_GATEWAY_API_KEY an.
    • Weitere Details: Cloudflare AI Gateway
    • MiniMax: Die Konfiguration wird automatisch geschrieben; der gehostete Standard ist MiniMax-M2.7. Die Einrichtung per API-Schlüssel verwendet minimax/..., und die OAuth-Einrichtung verwendet minimax-portal/....
    • Weitere Details: MiniMax
    • StepFun: Die Konfiguration wird automatisch für StepFun Standard oder Step Plan auf China- oder globalen Endpunkten geschrieben.
    • Standard enthält derzeit step-3.5-flash, und Step Plan enthält außerdem step-3.5-flash-2603.
    • Weitere Details: StepFun
    • Synthetic (Anthropic-kompatibel): fordert SYNTHETIC_API_KEY an.
    • Weitere Details: Synthetic
    • Moonshot (Kimi K2): Die Konfiguration wird automatisch geschrieben.
    • Kimi Coding: Die Konfiguration wird automatisch geschrieben.
    • Weitere Details: Moonshot AI (Kimi + Kimi Coding)
    • Überspringen: Noch keine Auth konfiguriert.
    • Wählen Sie ein Standardmodell aus den erkannten Optionen (oder geben Sie Provider/Modell manuell ein). Für beste Qualität und ein geringeres Risiko durch Prompt Injection wählen Sie das stärkste 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 Auth fehlt.
    • Der Speichermodus für API-Schlüssel verwendet standardmäßig Klartextwerte in Auth-Profilen. Verwenden Sie --secret-input-mode ref, um stattdessen env-gestützte Referenzen zu speichern (zum Beispiel keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
    • Auth-Profile befinden sich in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (API-Schlüssel + OAuth). ~/.openclaw/credentials/oauth.json ist nur ein veralteter Importpfad.
    • Weitere Details: /concepts/oauth

  • Arbeitsbereich

    • Standard ~/.openclaw/workspace (konfigurierbar).
    • Legt die Arbeitsbereichsdateien an, die für das Agent-Bootstrap-Ritual benötigt werden.
    • Vollständiges Arbeitsbereichslayout + Backup-Leitfaden: Agent-Arbeitsbereich

  • Gateway

    • Port, Bind, Auth-Modus, Tailscale-Exposition.
    • Auth-Empfehlung: Behalten Sie Token auch für Loopback bei, damit lokale WS-Clients sich authentifizieren müssen.
    • Im Token-Modus bietet die interaktive Einrichtung:
      • Klartext-Token generieren/speichern (Standard)
      • SecretRef verwenden (Opt-in)
      • Quickstart verwendet vorhandene gateway.auth.token-SecretRefs über env-, file- und exec-Provider für Onboarding-Probe/Dashboard-Bootstrap wieder.
      • Wenn diese SecretRef konfiguriert ist, aber nicht aufgelöst werden kann, schlägt das Onboarding früh mit einer klaren Behebungsmeldung fehl, statt die Laufzeit-Auth stillschweigend abzuschwächen.
    • Im Passwortmodus unterstützt die interaktive Einrichtung ebenfalls Klartext- oder SecretRef-Speicherung.
    • 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 Auth nur, wenn Sie jedem lokalen Prozess vollständig vertrauen.
    • Nicht-Loopback-Binds erfordern weiterhin Auth.

  • Kanäle

    • WhatsApp: optionale QR-Anmeldung.
    • Telegram: Bot-Token.
    • Discord: Bot-Token.
    • Google Chat: Service-Account-JSON + Webhook-Zielgruppe.
    • Mattermost (Plugin): Bot-Token + Basis-URL.
    • Signal: optionale signal-cli-Installation + Account-Konfiguration.
    • BlueBubbles: empfohlen für iMessage; Server-URL + Passwort + Webhook.
    • iMessage: veralteter imsg-CLI-Pfad + DB-Zugriff.
    • DM-Sicherheit: Standard ist Kopplung. Die erste DM sendet einen Code; genehmigen Sie ihn über openclaw pairing approve <channel> <code> oder verwenden Sie Allowlisten.

  • Websuche

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

  • Daemon-Installation

    • macOS: LaunchAgent
      • Erfordert eine angemeldete Benutzersitzung; für Headless-Betrieb verwenden Sie einen benutzerdefinierten LaunchDaemon (nicht mitgeliefert).
    • Linux (und Windows über WSL2): systemd-Benutzereinheit
      • Das Onboarding versucht, Lingering über loginctl enable-linger <user> zu aktivieren, damit der Gateway nach dem Abmelden weiterläuft.
      • Kann nach sudo fragen (schreibt nach /var/lib/systemd/linger); es versucht es zuerst ohne sudo.
    • Laufzeitauswahl: Node (empfohlen; erforderlich für WhatsApp/Telegram). Bun wird nicht empfohlen.
    • Wenn Token-Auth ein Token erfordert und gateway.auth.token per SecretRef verwaltet wird, validiert die Daemon-Installation es, speichert aber keine aufgelösten Klartext-Tokenwerte in Supervisor-Dienstumgebungsmetadaten.
    • Wenn Token-Auth ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist, wird die Daemon-Installation mit umsetzbarer Anleitung blockiert.
    • Wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind und gateway.auth.mode nicht gesetzt ist, wird die Daemon-Installation blockiert, bis der Modus ausdrücklich gesetzt ist.

  • Systemprüfung

    • Startet den Gateway (falls erforderlich) und führt openclaw health aus.
    • Tipp: openclaw status --deep ergänzt die Statusausgabe um die Live-Gateway-Systemprüfung, einschließlich Kanal-Probes, wenn unterstützt (erfordert einen erreichbaren Gateway).

  • Skills (empfohlen)

    • Liest die verfügbaren Skills und prüft Anforderungen.
    • Lässt Sie einen Node-Manager wählen: npm / pnpm (bun nicht empfohlen).
    • Installiert optionale Abhängigkeiten (einige verwenden Homebrew auf macOS).

  • Abschluss

    • Zusammenfassung + nächste Schritte, einschließlich iOS-/Android-/macOS-Apps für zusätzliche Funktionen.

    • Nicht interaktiver Modus

    Verwenden Sie --non-interactive, um Onboarding zu automatisieren oder zu skripten:

    openclaw onboard --non-interactive \
  --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 für eine maschinenlesbare Zusammenfassung hinzu.

    Gateway-Token-SecretRef im nicht interaktiven Modus:

    export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --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. Verwenden Sie diese Referenzseite für Flag-Semantik und Schrittfolge.

    Agent hinzufügen (nicht interaktiv)

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

    Gateway-Assistent-RPC

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

    Signal-Einrichtung (signal-cli)

    Das Onboarding kann signal-cli aus GitHub-Releases installieren:

    • Lädt das passende Release-Asset herunter.
    • Speichert es unter ~/.openclaw/tools/signal-cli/<version>/.
    • Schreibt channels.signal.cliPath in Ihre Konfiguration.

    Hinweise:

    • JVM-Builds erfordern Java 21.
    • Native Builds werden verwendet, wenn verfügbar.
    • Windows verwendet WSL2; die signal-cli-Installation folgt dem Linux-Ablauf innerhalb von WSL.

    Was der Assistent schreibt

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

    • agents.defaults.workspace
    • agents.defaults.model / models.providers (wenn Minimax gewählt wurde)
    • tools.profile (lokales Onboarding verwendet standardmäßig "coding", wenn nicht gesetzt; vorhandene explizite Werte bleiben erhalten)
    • gateway.* (Modus, Bind, Auth, Tailscale)
    • session.dmScope (Verhaltensdetails: CLI-Einrichtungsreferenz)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • Channel-Allowlists (Slack/Discord/Matrix/Microsoft Teams), wenn Sie sich während der Prompts dafür entscheiden (Namen werden nach Möglichkeit zu IDs aufgelöst).
    • skills.install.nodeManager
      • setup --node-manager akzeptiert npm, pnpm oder bun.
      • Die manuelle Konfiguration kann weiterhin yarn verwenden, indem skills.install.nodeManager direkt gesetzt wird.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode

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

    WhatsApp-Anmeldedaten werden unter ~/.openclaw/credentials/whatsapp/<accountId>/ abgelegt. Sitzungen werden unter ~/.openclaw/agents/<agentId>/sessions/ gespeichert.

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

    Zugehörige Dokumentation