Referencja CLI onboardingu

Ta strona to pełna referencja dla openclaw onboard. Po krótki przewodnik, zobacz Kreator onboardingu (CLI).

Co robi kreator

Tryb lokalny (domyślny) prowadzi cię przez:

• Konfigurację modelu i auth (OpenAI Code subscription OAuth, Anthropic API key lub setup token, plus opcje MiniMax, GLM, Ollama, Moonshot i AI Gateway)
• Lokalizację workspace i pliki bootstrap
• Ustawienia Gateway (port, bind, auth, tailscale)
• Kanały i providerów (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
• Instalację daemona (LaunchAgent lub systemd user unit)
• Health check
• Konfigurację skills

Tryb zdalny konfiguruje tę maszynę do połączenia z gateway gdzie indziej. Nie instaluje ani nie modyfikuje niczego na zdalnym hoście.

Szczegóły przepływu lokalnego

Krok 1: Wykrywanie istniejącej konfiguracji

- Jeśli `~/.openclaw/openclaw.json` istnieje, wybierz Zachowaj, Modyfikuj lub Resetuj.
- Ponowne uruchomienie kreatora nie kasuje niczego, chyba że jawnie wybierzesz Reset (lub podasz `--reset`).
- CLI `--reset` domyślnie do `config+creds+sessions`; użyj `--reset-scope full`, żeby usunąć też workspace.
- Jeśli konfiguracja jest nieprawidłowa lub zawiera legacy keys, kreator zatrzymuje się i prosi o uruchomienie `openclaw doctor` przed kontynuacją.
- Reset używa `trash` i oferuje zakresy:
  - Tylko konfiguracja
  - Konfiguracja + dane logowania + sesje
  - Pełny reset (usuwa też workspace)

Krok 2: Model i auth

- Pełna macierz opcji w [Opcje auth i modeli](#opcje-auth-i-modeli).

Krok 3: Workspace

- Domyślnie `~/.openclaw/workspace` (konfigurowalny).
- Tworzy pliki workspace potrzebne do rytuału bootstrap pierwszego uruchomienia.
- Układ workspace: [Workspace agenta](/docs/concepts/agent-workspace).

Krok 4: Gateway

- Pyta o port, bind, tryb auth i ekspozycję tailscale.
- Zalecane: utrzymuj auth tokenem włączone nawet dla loopback, żeby lokalne klienty WS musiały się uwierzytelniać.
- W trybie tokena, interaktywny onboarding oferuje:
  - **Generuj/przechowuj plaintext token** (domyślnie)
  - **Użyj SecretRef** (opt-in)
- W trybie hasła, interaktywny onboarding też wspiera plaintext lub SecretRef.
- Nieinteraktywna ścieżka token SecretRef: `--gateway-token-ref-env <ENV_VAR>`.
  - Wymaga niepustej zmiennej env w środowisku procesu onboardingu.
  - Nie może być łączone z `--gateway-token`.
- Wyłącz auth tylko jeśli w pełni ufasz każdemu lokalnemu procesowi.
- Bindy non-loopback nadal wymagają auth.

Krok 5: Kanały

- [WhatsApp](/docs/channels/whatsapp): opcjonalny login QR
- [Telegram](/docs/channels/telegram): bot token
- [Discord](/docs/channels/discord): bot token
- [Google Chat](/docs/channels/googlechat): service account JSON + webhook audience
- [Mattermost](/docs/channels/mattermost) plugin: bot token + base URL
- [Signal](/docs/channels/signal): opcjonalna instalacja `signal-cli` + konfiguracja konta
- [BlueBubbles](/docs/channels/bluebubbles): zalecane dla iMessage; server URL + hasło + webhook
- [iMessage](/docs/channels/imessage): legacy ścieżka CLI `imsg` + dostęp DB
- Bezpieczeństwo DM: domyślnie parowanie. Pierwszy DM wysyła kod; zatwierdź przez
  `openclaw pairing approve <channel> <code>` lub użyj allowlist.

Krok 6: Instalacja daemona

- macOS: LaunchAgent
  - Wymaga zalogowanej sesji użytkownika; dla headless użyj niestandardowego LaunchDaemona (niedołączany).
- Linux i Windows przez WSL2: systemd user unit
  - Kreator próbuje `loginctl enable-linger <user>`, żeby gateway działał po wylogowaniu.
  - Może poprosić o sudo (zapisuje do `/var/lib/systemd/linger`); najpierw próbuje bez sudo.
- Wybór runtime: Node (zalecany; wymagany dla WhatsApp i Telegram). Bun niezalecany.

Krok 7: Health check

- Uruchamia gateway (jeśli potrzeba) i wykonuje `openclaw health`.
- `openclaw status --deep` dodaje sondy health gateway do wyjścia statusu.

Krok 8: Skills

- Odczytuje dostępne skills i sprawdza wymagania.
- Pozwala wybrać menedżer node: npm lub pnpm (bun niezalecany).
- Instaluje opcjonalne zależności (niektóre używają Homebrew na macOS).

Krok 9: Zakończenie

- Podsumowanie i następne kroki, w tym opcje iOS, Android i macOS app.

Uwaga: Jeśli GUI nie zostanie wykryty, kreator wypisuje instrukcje SSH port-forward dla Control UI zamiast otwierać przeglądarkę. Jeśli assety Control UI brakują, kreator próbuje je zbudować; fallback to pnpm ui:build (automatycznie instaluje zależności UI).

Szczegóły trybu zdalnego

Tryb zdalny konfiguruje tę maszynę do połączenia z gateway gdzie indziej.

Info: Tryb zdalny nie instaluje ani nie modyfikuje niczego na zdalnym hoście.

Co ustawiasz:

• URL zdalnego gateway (ws://...)
• Token jeśli auth zdalnego gateway jest wymagane (zalecane)

Uwaga:

• Jeśli gateway jest loopback-only, użyj SSH tunnelingu lub tailnet.
• Wskazówki discovery:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Opcje auth i modeli

Używa `ANTHROPIC_API_KEY` jeśli jest obecny lub pyta o key, następnie zapisuje go do użycia przez daemona.

- macOS: sprawdza element Keychain "Claude Code-credentials"
- Linux i Windows: reużywa `~/.claude/.credentials.json` jeśli istnieje

Na macOS wybierz „Zawsze zezwalaj", żeby starty launchd nie blokowały.

Uruchom `claude setup-token` na dowolnej maszynie, potem wklej token.
Możesz mu nadać nazwę; puste używa domyślnej.

Jeśli `~/.codex/auth.json` istnieje, kreator może go reużyć.

Przepływ przeglądarki; wklej `code#state`.

Ustawia `agents.defaults.model` na `openai-codex/gpt-5.4` gdy model nie jest ustawiony lub jest `openai/*`.

Używa `OPENAI_API_KEY` jeśli jest obecny lub pyta o key, następnie przechowuje credential w profilach auth.

Ustawia `agents.defaults.model` na `openai/gpt-5.1-codex` gdy model nie jest ustawiony, jest `openai/*` lub `openai-codex/*`.

Pyta o `XAI_API_KEY` i konfiguruje xAI jako providera modeli.

Pyta o `OPENCODE_API_KEY` (lub `OPENCODE_ZEN_API_KEY`) i pozwala wybrać katalog Zen lub Go.
URL konfiguracji: [opencode.ai/auth](https://opencode.ai/auth).

Przechowuje key za ciebie.

Pyta o `AI_GATEWAY_API_KEY`.
Więcej szczegółów: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Pyta o account ID, gateway ID i `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Więcej szczegółów: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

Konfiguracja zapisywana automatycznie.
Więcej szczegółów: [MiniMax](/docs/providers/minimax).

Pyta o `SYNTHETIC_API_KEY`.
Więcej szczegółów: [Synthetic](/docs/providers/synthetic).

Pyta o base URL (domyślnie `http://127.0.0.1:11434`), następnie oferuje tryb Cloud + Local lub Local.
Odkrywa dostępne modele i sugeruje domyślne.
Więcej szczegółów: [Ollama](/docs/providers/ollama).

Konfiguracje Moonshot (Kimi K2) i Kimi Coding zapisywane automatycznie.
Więcej szczegółów: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Działa z endpointami OpenAI-compatible i Anthropic-compatible.

Interaktywny onboarding wspiera te same opcje przechowywania API key co inne przepływy API key providerów:
- **Wklej API key teraz** (plaintext)
- **Użyj secret reference** (ref env lub skonfigurowany ref providera, z walidacją preflight)

Flagi nieinteraktywne:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (opcjonalny; fallback do `CUSTOM_API_KEY`)
- `--custom-provider-id` (opcjonalny)
- `--custom-compatibility <openai|anthropic>` (opcjonalny; domyślnie `openai`)

Auth pozostaje nieskonfigurowane.

Zachowanie modeli:

• Wybierz domyślny model z wykrytych opcji, lub wpisz providera i model ręcznie.
• Kreator uruchamia sprawdzenie modelu i ostrzega, jeśli skonfigurowany model jest nieznany lub brakuje auth.

Ścieżki credentiali i profili:

• Credentiale OAuth: ~/.openclaw/credentials/oauth.json
• Profile auth (API keys + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Tryb przechowywania credentiali:

• Domyślne zachowanie onboardingu utrwala API keys jako wartości plaintext w profilach auth.
• --secret-input-mode ref włącza tryb referencji zamiast przechowywania key plaintext. W interaktywnym onboardingu możesz wybrać:
  • ref zmiennej środowiskowej (np. keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • skonfigurowany ref providera (file lub exec) z aliasem providera + id
• Interaktywny tryb referencji uruchamia szybką walidację preflight przed zapisem.
  • Refy env: waliduje nazwę zmiennej + niepustą wartość w bieżącym środowisku onboardingu.
  • Refy providera: waliduje konfigurację providera i rozwiązuje żądane id.
  • Jeśli preflight nie powiedzie się, onboarding pokazuje błąd i pozwala spróbować ponownie.
• W trybie nieinteraktywnym, --secret-input-mode ref jest tylko env-backed.
  • Ustaw zmienną env providera w środowisku procesu onboardingu.
  • Inline flagi key (np. --openai-api-key) wymagają ustawienia tej zmiennej env; w przeciwnym razie onboarding natychmiast kończy się błędem.
  • Dla custom providerów, nieinteraktywny tryb ref przechowuje models.providers.<id>.apiKey jako { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • W tym przypadku custom providera, --custom-api-key wymaga ustawienia CUSTOM_API_KEY; w przeciwnym razie onboarding natychmiast kończy się błędem.
• Credentiale auth Gateway wspierają wybór plaintext i SecretRef w interaktywnym onboardingu:
  • Tryb tokena: Generuj/przechowuj plaintext token (domyślnie) lub Użyj SecretRef.
  • Tryb hasła: plaintext lub SecretRef.
• Nieinteraktywna ścieżka token SecretRef: --gateway-token-ref-env <ENV_VAR>.
• Istniejące konfiguracje plaintext nadal działają bez zmian.

Uwaga: Wskazówka dla headless i serwerów: wykonaj OAuth na maszynie z przeglądarką, potem skopiuj ~/.openclaw/credentials/oauth.json (lub $OPENCLAW_STATE_DIR/credentials/oauth.json) na host gateway.

Wyjścia i mechanizmy wewnętrzne

Typowe pola w ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.model / models.providers (jeśli wybrano Minimax)
• tools.profile (lokalny onboarding domyślnie ustawia na "coding" gdy nieustawione; istniejące jawne wartości są zachowywane)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (lokalny onboarding domyślnie ustawia na per-channel-peer gdy nieustawione; istniejące jawne wartości są zachowywane)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Allowlisty kanałów (Slack, Discord, Matrix, Microsoft Teams) gdy wybierzesz opt-in podczas monitów (nazwy rozwiązywane do ID gdzie to możliwe)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add zapisuje agents.list[] i opcjonalne bindings.

Credentiale WhatsApp znajdują się w ~/.openclaw/credentials/whatsapp/<accountId>/. Sesje przechowywane w ~/.openclaw/agents/<agentId>/sessions/.

Uwaga: Niektóre kanały są dostarczane jako wtyczki. Gdy zostaną wybrane podczas onboardingu, kreator pyta o instalację wtyczki (npm lub lokalna ścieżka) przed konfiguracją kanału.

Gateway wizard RPC:

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

Klienci (aplikacja macOS i Control UI) mogą renderować kroki bez reimplementacji logiki onboardingu.

Zachowanie konfiguracji Signal:

• Pobiera odpowiedni asset release
• Przechowuje go w ~/.openclaw/tools/signal-cli/<version>/
• Zapisuje channels.signal.cliPath w konfiguracji
• Buildy JVM wymagają Java 21
• Natywne buildy używane gdy dostępne
• Windows używa WSL2 i podąża za przepływem Linux signal-cli wewnątrz WSL

Powiązane dokumenty

• Hub onboardingu: Kreator onboardingu (CLI)
• Automatyzacja i skrypty: CLI Automation
• Referencja komend: openclaw onboard