openclaw onboard

Vollständig geführtes Onboarding für die lokale oder entfernte Gateway-Einrichtung. Verwenden Sie dies, wenn OpenClaw Modell-Authentifizierung, Arbeitsbereich, Gateway, Kanäle, Skills und Integrität in einem Ablauf durchgehen soll.

Zugehörige Leitfäden

Beispiele

openclaw onboardopenclaw onboard --modernopenclaw onboard --flow quickstartopenclaw onboard --flow manualopenclaw onboard --flow importopenclaw onboard --import-from hermes --import-source ~/.hermesopenclaw onboard --skip-bootstrapopenclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow import verwendet Plugin-eigene Migrations-Provider wie Hermes. Es läuft nur gegen eine frische OpenClaw-Einrichtung; wenn vorhandene Konfigurationen, Anmeldedaten, Sitzungen oder Dateien für Arbeitsbereichsspeicher/Identität vorhanden sind, setzen Sie vor dem Import zurück oder wählen Sie eine frische Einrichtung.

--modern startet die Vorschau des dialogbasierten Crestodian-Onboardings. Ohne --modern behält openclaw onboard den klassischen Onboarding-Ablauf bei.

In einem interaktiven Terminal leitet bloßes openclaw (ohne Unterbefehl) nach Konfigurationszustand weiter:

• Wenn die aktive Konfigurationsdatei fehlt oder keine verfassten Einstellungen enthält (leer oder nur Metadaten), startet dieser klassische Onboarding-Ablauf.
• Wenn die Konfigurationsdatei existiert, aber die Validierung fehlschlägt, startet Crestodian zur Reparatur.
• Wenn die Konfigurationsdatei gültig ist, öffnet es die normale Agent-TUI, entweder lokal oder verbunden mit einem erreichbaren konfigurierten Gateway. In einer konfigurierten Installation erreichen Sie Crestodian mit /crestodian innerhalb der TUI oder openclaw crestodian.

Klartext-ws:// wird für loopback, private IP-Literale, .local und Tailnet-*.ts.net-Gateway-URLs akzeptiert. Für andere vertrauenswürdige private DNS-Namen setzen Sie OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 in der Prozessumgebung des Onboardings.

Gebietsschema

Interaktives Onboarding verwendet das CLI-Assistenten-Gebietsschema für feste Einrichtungstexte. Die Auflösungsreihenfolge ist:

1. OPENCLAW_LOCALE
2. LC_ALL
3. LC_MESSAGES
4. LANG
5. Englische Fallback-Sprache

Unterstützte Assistenten-Gebietsschemas sind en, zh-CN und zh-TW. Gebietsschemawerte können Unterstrich- oder POSIX-Suffixformen wie zh_CN.UTF-8 verwenden. Produktnamen, Befehlsnamen, Konfigurationsschlüssel, URLs, Provider-IDs, Modell-IDs und Plugin-/Kanalbezeichnungen bleiben wörtlich.

Beispiel:

OPENCLAW_LOCALE=zh-CN openclaw onboard

Nicht-interaktiver benutzerdefinierter Provider:

openclaw onboard --non-interactive \  --auth-choice custom-api-key \  --custom-base-url "https://llm.example.com/v1" \  --custom-model-id "foo-large" \  --custom-api-key "$CUSTOM_API_KEY" \  --secret-input-mode plaintext \  --custom-compatibility openai \  --custom-image-input

--custom-api-key ist im nicht-interaktiven Modus optional. Wenn es ausgelassen wird, prüft das Onboarding CUSTOM_API_KEY. OpenClaw kennzeichnet gängige Vision-Modell-IDs automatisch als bildfähig. Übergeben Sie --custom-image-input für unbekannte benutzerdefinierte Vision-IDs oder --custom-text-input, um reine Textmetadaten zu erzwingen. Verwenden Sie --custom-compatibility openai-responses für OpenAI-kompatible Endpunkte, die /v1/responses, aber nicht /v1/chat/completions unterstützen.

LM Studio unterstützt im nicht-interaktiven Modus außerdem ein Provider-spezifisches Schlüssel-Flag:

openclaw onboard --non-interactive \  --auth-choice lmstudio \  --custom-base-url "http://localhost:1234/v1" \  --custom-model-id "qwen/qwen3.5-9b" \  --lmstudio-api-key "$LM_API_TOKEN" \  --accept-risk

Nicht-interaktives Ollama:

openclaw onboard --non-interactive \  --auth-choice ollama \  --custom-base-url "http://ollama-host:11434" \  --custom-model-id "qwen3.5:27b" \  --accept-risk

--custom-base-url ist standardmäßig http://127.0.0.1:11434. --custom-model-id ist optional; wenn es ausgelassen wird, verwendet das Onboarding die von Ollama vorgeschlagenen Standardwerte. Cloud-Modell-IDs wie kimi-k2.5:cloud funktionieren hier ebenfalls.

Speichern Sie Provider-Schlüssel als Refs statt als Klartext:

openclaw onboard --non-interactive \  --auth-choice openai-api-key \  --secret-input-mode ref \  --accept-risk

Mit --secret-input-mode ref schreibt das Onboarding umgebungsbasierte Refs statt Klartext-Schlüsselwerte. Für Provider mit Auth-Profil schreibt dies keyRef-Einträge; für benutzerdefinierte Provider schreibt dies models.providers.<id>.apiKey als Umgebungs-Ref (zum Beispiel { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

Vertrag für den nicht-interaktiven ref-Modus:

• Setzen Sie die Provider-Umgebungsvariable in der Prozessumgebung des Onboardings (zum Beispiel OPENAI_API_KEY).
• Übergeben Sie keine Inline-Schlüssel-Flags (zum Beispiel --openai-api-key), es sei denn, diese Umgebungsvariable ist ebenfalls gesetzt.
• Wenn ein Inline-Schlüssel-Flag ohne die erforderliche Umgebungsvariable übergeben wird, schlägt das Onboarding schnell mit Hinweisen fehl.

Gateway-Token-Optionen im nicht-interaktiven Modus:

• --gateway-auth token --gateway-token <token> speichert ein Klartext-Token.
• --gateway-auth token --gateway-token-ref-env <name> speichert gateway.auth.token als Umgebungs-SecretRef.
• --gateway-token und --gateway-token-ref-env schließen sich gegenseitig aus.
• --gateway-token-ref-env erfordert eine nicht leere Umgebungsvariable in der Prozessumgebung des Onboardings.
• Mit --install-daemon werden bei Token-Authentifizierung, die ein Token erfordert, von SecretRef verwaltete Gateway-Token validiert, aber nicht als aufgelöster Klartext in Umgebungsmetadaten des Supervisor-Dienstes persistiert.
• Mit --install-daemon schlägt das Onboarding geschlossen mit Abhilfehinweisen fehl, wenn der Token-Modus ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist.
• Mit --install-daemon blockiert das Onboarding die Installation, bis der Modus explizit gesetzt ist, wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind und gateway.auth.mode nicht gesetzt ist.
• Lokales Onboarding schreibt gateway.mode="local" in die Konfiguration. Wenn einer späteren Konfigurationsdatei gateway.mode fehlt, behandeln Sie dies als Konfigurationsbeschädigung oder unvollständige manuelle Bearbeitung, nicht als gültige Abkürzung für den lokalen Modus.
• Lokales Onboarding installiert ausgewählte herunterladbare Plugins, wenn der gewählte Einrichtungspfad sie erfordert.
• Entferntes Onboarding schreibt nur Verbindungsinformationen für das entfernte Gateway und installiert keine lokalen Plugin-Pakete.
• --allow-unconfigured ist eine separate Gateway-Runtime-Notausnahme. Es bedeutet nicht, dass das Onboarding gateway.mode auslassen darf.

Beispiel:

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 \  --accept-risk

Nicht-interaktive lokale Gateway-Integrität:

• Sofern Sie nicht --skip-health übergeben, wartet das Onboarding auf ein erreichbares lokales Gateway, bevor es erfolgreich beendet wird.
• --install-daemon startet zuerst den verwalteten Gateway-Installationspfad. Ohne dieses Flag muss bereits ein lokales Gateway laufen, zum Beispiel openclaw gateway run.
• Wenn Sie in der Automatisierung nur Konfigurations-/Arbeitsbereichs-/Bootstrap-Schreibvorgänge möchten, verwenden Sie --skip-health.
• Wenn Sie Arbeitsbereichsdateien selbst verwalten, übergeben Sie --skip-bootstrap, um agents.defaults.skipBootstrap: true zu setzen und das Erstellen von AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md und BOOTSTRAP.md zu überspringen.
• Unter nativem Windows versucht --install-daemon zuerst Geplante Aufgaben und fällt auf ein benutzerbezogenes Login-Element im Autostart-Ordner zurück, wenn die Aufgabenerstellung verweigert wird.

Interaktives Onboarding-Verhalten mit Referenzmodus:

• Wählen Sie bei Aufforderung Geheimnisreferenz verwenden.
• Wählen Sie dann entweder:
  • Umgebungsvariable
  • Konfigurierter Secret-Provider (file oder exec)
• Das Onboarding führt vor dem Speichern der Ref eine schnelle Preflight-Validierung durch.
  • Wenn die Validierung fehlschlägt, zeigt das Onboarding den Fehler an und lässt Sie erneut versuchen.

Nicht-interaktive Z.AI-Endpunktauswahl

# Promptless endpoint selectionopenclaw onboard --non-interactive \  --auth-choice zai-coding-global \  --zai-api-key "$ZAI_API_KEY" # Other Z.AI endpoint choices:# --auth-choice zai-coding-cn# --auth-choice zai-global# --auth-choice zai-cn

Nicht-interaktives Mistral-Beispiel:

openclaw onboard --non-interactive \  --auth-choice mistral-api-key \  --mistral-api-key "$MISTRAL_API_KEY"

Zusätzliche nicht-interaktive Flags

Tokenbasierte Modell-Authentifizierung (nicht-interaktiv; verwendet mit --auth-choice token):

• --token-provider <id> — Token-Provider-ID. Identifiziert, welcher Provider das Token ausstellt.
• --token <token> — Token-Wert für die Modell-Authentifizierung.
• --token-profile-id <id> — Auth-Profil-ID. Generische Token-Speicherung ist standardmäßig <provider>:manual; Provider-eigene Einrichtungsabläufe können ihren eigenen Standard verwenden, etwa anthropic:default.
• --token-expires-in <duration> — Optionale Token-Ablaufdauer (z. B. 365d, 12h).

Cloudflare AI Gateway (nicht-interaktiv):

• --cloudflare-ai-gateway-account-id <id> — Cloudflare-Konto-ID für Routing über Cloudflare AI Gateway.
• --cloudflare-ai-gateway-gateway-id <id> — Cloudflare AI Gateway-ID.

Daemon-Installationssteuerung:

• --no-install-daemon — Gateway-Dienstinstallation explizit überspringen.
• --skip-daemon — Alias für --no-install-daemon.

UI- und Hook-Einrichtungssteuerung:

• --skip-ui — Control UI-/TUI-Eingabeaufforderungen während des Onboardings überspringen.
• --skip-hooks — Webhook-/Hook-Eingabeaufforderungen während des Onboardings überspringen.

Ausgabeunterdrückung:

• --suppress-gateway-token-output — Tokenhaltige Gateway-/UI-Ausgabe unterdrücken (Token-Hinweise, Auto-Login-URL mit eingebettetem Token und automatischer Start der Control UI). Nützlich in gemeinsam genutzten Terminal- und CI-Umgebungen.

Hinweise zum Ablauf

Häufige Folge-Befehle

openclaw channels addopenclaw configureopenclaw agents add <name>

Verwenden Sie openclaw setup als denselben geführten Einstiegspunkt für das Onboarding. Verwenden Sie openclaw setup --baseline, wenn Sie nur die Baseline-Konfiguration/den Workspace benötigen, später openclaw configure für gezielte Änderungen und openclaw channels add für die reine Channel-Einrichtung.