Referenz zur CLI-Einrichtung

Diese Seite behandelt Schritt für Schritt das Onboarding-Verhalten, die Ausgaben und die internen Abläufe. Eine Anleitung finden Sie unter Onboarding (CLI). Die vollständige Referenz der CLI-Flags (alle --flag, nicht interaktive Beispiele, providerspezifische Befehle) finden Sie unter openclaw onboard.

Funktionsweise des Assistenten

Der lokale Modus (Standard) führt Sie durch:

• Modell- und Authentifizierungseinrichtung (Anthropic, OAuth für das OpenAI-Code-Abonnement, xAI, OpenCode, benutzerdefinierte Endpunkte und weitere providerseitige Authentifizierungsabläufe)
• Arbeitsbereichsspeicherort und Bootstrap-Dateien
• Gateway-Einstellungen (Port, Bindung, Authentifizierung, Tailscale)
• Kanäle und Provider (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp und weitere gebündelte oder Plugin-Kanäle)
• Provider für die Websuche (optional)
• Daemon-Installation (LaunchAgent, systemd-Benutzereinheit oder native geplante Windows-Aufgabe mit Ausweichlösung über den Autostartordner)
• Integritätsprüfung
• Einrichtung der Skills

Der Remote-Modus konfiguriert diesen Rechner für die Verbindung mit einem Gateway an einem anderen Ort. Er installiert oder ändert nichts auf dem Remote-Host.

Details zum lokalen Ablauf

Details zum Remote-Modus

Der Remote-Modus konfiguriert diesen Rechner für die Verbindung mit einem Gateway an einem anderen Ort. Er installiert oder ändert nichts auf dem Remote-Host.

Ihre Einstellungen:

• Remote-Gateway-URL (ws://... oder wss://...)
• Token, Passwort oder keine Authentifizierung, entsprechend der Konfiguration des Remote-Gateways

Authentifizierungs- und Modelloptionen

Wenn ein Schritt zur Provider-Einrichtung beim interaktiven Onboarding fehlschlägt (beispielsweise eine Option zur Wiederverwendung der CLI ohne lokale Anmeldung), zeigt der Assistent den Fehler an und kehrt zur Provider-Auswahl zurück, anstatt sich zu beenden. Explizite --auth-choice-Ausführungen schlagen für die Automatisierung weiterhin sofort fehl.

Modellverhalten:

• Wählen Sie das Standardmodell aus den erkannten Optionen aus oder geben Sie Provider und Modell manuell ein.
• Wenn das Onboarding mit der Auswahl einer Provider-Authentifizierung beginnt, bevorzugt die Modellauswahl diesen Provider automatisch. Bei Volcengine und BytePlus berücksichtigt dieselbe Präferenz auch deren Coding-Plan-Varianten (volcengine-plan/*, byteplus-plan/*).
• Wenn dieser Filter für den bevorzugten Provider leer wäre, greift die Auswahl auf den vollständigen Katalog zurück, statt keine Modelle anzuzeigen.
• Der Assistent führt eine Modellprüfung aus und warnt, wenn das konfigurierte Modell unbekannt ist oder die Authentifizierung fehlt.

Pfade für Anmeldedaten und Profile:

• Authentifizierungsprofile (API-Schlüssel + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Import von Legacy-OAuth: ~/.openclaw/credentials/oauth.json

Speichermodus für Anmeldedaten:

• Standardmäßig speichert das Onboarding API-Schlüssel als Klartextwerte in Authentifizierungsprofilen.
• --secret-input-mode ref aktiviert anstelle der Klartextspeicherung von Schlüsseln den Referenzmodus. Bei der interaktiven Einrichtung können Sie zwischen folgenden Optionen wählen:
  • Umgebungsvariablen-Referenz (zum Beispiel keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • konfigurierte Provider-Referenz (file oder exec) mit Provider-Alias und ID
• Der interaktive Referenzmodus führt vor dem Speichern eine schnelle Vorabvalidierung aus.
  • Umgebungsvariablen-Referenzen: Validiert den Variablennamen und einen nicht leeren Wert in der aktuellen Onboarding-Umgebung.
  • Provider-Referenzen: Validiert die Provider-Konfiguration und löst die angeforderte ID auf.
  • Wenn die Vorabvalidierung fehlschlägt, zeigt das Onboarding den Fehler an und ermöglicht einen erneuten Versuch.
• Im nicht interaktiven Modus wird --secret-input-mode ref ausschließlich durch Umgebungsvariablen gestützt.
  • Setzen Sie die Umgebungsvariable des Providers in der Prozessumgebung des Onboardings.
  • Inline-Schlüssel-Flags (zum Beispiel --openai-api-key) setzen voraus, dass diese Umgebungsvariable gesetzt ist; andernfalls schlägt das Onboarding sofort fehl.
  • Bei benutzerdefinierten Providern speichert der nicht interaktive Modus ref den Wert models.providers.<id>.apiKey als { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • In diesem Fall eines benutzerdefinierten Providers setzt --custom-api-key voraus, dass CUSTOM_API_KEY gesetzt ist; andernfalls schlägt das Onboarding sofort fehl.
• Gateway-Authentifizierungsdaten unterstützen bei der interaktiven Einrichtung Klartext- und SecretRef-Optionen:
  • Token-Modus: Klartext-Token generieren/speichern (Standard) oder SecretRef verwenden.
  • Passwortmodus: Klartext oder SecretRef.
• Nicht interaktiver Token-SecretRef-Pfad: --gateway-token-ref-env <ENV_VAR>.
• Bestehende Klartext-Einrichtungen funktionieren unverändert weiter.

Ausgaben und Interna

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 (lokales Onboarding verwendet bei nicht gesetztem Wert standardmäßig "coding"; vorhandene explizite Werte bleiben erhalten)
• gateway.* (Modus, Bindung, Authentifizierung, Tailscale)
• session.dmScope (das Onboarding behält explizite Werte bei und lässt den Wert andernfalls ungesetzt, sodass der Standardwert main alle Direktnachrichten kanalübergreifend in der fortlaufenden Hauptsitzung des Agenten hält – der Standard für persönliche Agenten. Verwenden Sie für gemeinsam genutzte Posteingänge oder Posteingänge mit mehreren Benutzern per-channel-peer; openclaw security audit empfiehlt eine Isolierung, wenn Direktnachrichtenverkehr von mehreren Benutzern erkannt wird)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Kanal-Zulassungslisten (Discord, iMessage, Signal, Slack, Telegram, WhatsApp), wenn Sie sich während der Abfragen dafür entscheiden; Discord und Slack lösen eingegebene Namen außerdem in IDs auf
• skills.install.nodeManager
  • Das Flag setup --node-manager akzeptiert npm, pnpm oder bun.
  • In der manuellen Konfiguration kann skills.install.nodeManager: "yarn" weiterhin später festgelegt werden.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

openclaw agents add schreibt agents.entries.* 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 Legacy-Migration sowie für Archiv- und Supportartefakte verwendet.

Empfehlungen für installierte Apps

Nachdem die Prüfung des Modellzugriffs erfolgreich war, durchsucht das klassische interaktive Onboarding unter macOS Anwendungsnamen und Bundle-IDs, ohne macOS-Datenschutzberechtigungen anzufordern. Es durchsucht die offiziellen Plugin-Kataloge und ClawHub und bittet anschließend das konfigurierte Modell, falsche Namensübereinstimmungen zu verwerfen und relevante Plugins oder Skills zu empfehlen. Empfohlene Treffer sind standardmäßig ausgewählt; optionale Treffer erfordern eine explizite Auswahl.

Der Ergebnisbildschirm führt die erkannten Anwendungen auf und zeigt Folgendes an: „App-Namen wurden mithilfe Ihres konfigurierten Modells und der ClawHub-Suche abgeglichen.“ Setzen Sie wizard.appRecommendations auf false, um sowohl diesen Onboarding-Schritt als auch den Gateway-Zugriff auf App-Inventare von Nodes zu deaktivieren. Der Scan wird weder im Schnellstart noch beim Onboarding außerhalb von macOS verwendet.

Nicht interaktive Einrichtung

--non-interactive erfordert --accept-risk (bestätigt, dass Agenten leistungsfähig sind und vollständiger Systemzugriff riskant ist):

openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

Vollständige Flag-Referenz und providerspezifische Beispiele: openclaw onboard, CLI-Automatisierung.

RPC des Gateway-Assistenten

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Clients (macOS-App und Control UI) können Schritte darstellen, ohne die Onboarding-Logik erneut zu implementieren.

Verhalten bei der Signal-Einrichtung

• Lädt das passende Release-Artefakt aus den offiziellen GitHub-Releases von signal-cli herunter (nativer Build, nur Linux x86-64)
• Installiert auf anderen Plattformen (macOS, Linux ohne x64) stattdessen über Homebrew
• Speichert die Installation des Release-Artefakts unter ~/.openclaw/tools/signal-cli/<version>/
• Schreibt channels.signal.transport.cliPath mit kind: "managed-native" in die Konfiguration
• Natives Windows wird noch nicht unterstützt; führen Sie das Onboarding in WSL2 aus, um den Linux-Installationspfad zu erhalten

Zugehörige Dokumentation

• Onboarding-Übersicht: Onboarding (CLI)
• Automatisierung und Skripte: CLI-Automatisierung
• Befehlsreferenz: openclaw onboard