CLI Onboarding-referentie

Deze pagina is de volledige referentie voor openclaw onboard. Voor de korte gids, zie Onboarding Wizard (CLI).

Wat de wizard doet

Lokale modus (standaard) leidt je door:

• Model- en auth-setup (OpenAI Code subscription OAuth, Anthropic API key of setup token, plus MiniMax, GLM, Ollama, Moonshot en AI Gateway-opties)
• Workspace-locatie en bootstrap-bestanden
• Gateway-instellingen (poort, bind, auth, tailscale)
• Kanalen en providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
• Daemon-installatie (LaunchAgent of systemd user unit)
• Health check
• Skills-setup

Remote modus configureert deze machine om te verbinden met een gateway elders. Het installeert of wijzigt niets op de remote host.

Lokale flow-details

Stap 1: Bestaande config-detectie

- Als `~/.openclaw/openclaw.json` bestaat, kies Behouden, Wijzigen of Resetten.
- De wizard opnieuw draaien wist niets tenzij je expliciet Reset kiest (of `--reset` meegeeft).
- CLI `--reset` staat standaard op `config+creds+sessions`; gebruik `--reset-scope full` om ook de workspace te verwijderen.
- Als de config ongeldig is of legacy keys bevat, stopt de wizard en vraagt je om eerst `openclaw doctor` te draaien.
- Reset gebruikt `trash` en biedt scopes:
  - Alleen config
  - Config + credentials + sessions
  - Volledige reset (verwijdert ook workspace)

Stap 2: Model en auth

- Volledige optiematrix staat in [Auth- en modelopties](#auth--en-modelopties).

Stap 3: Workspace

- Standaard `~/.openclaw/workspace` (configureerbaar).
- Zaait workspace-bestanden nodig voor het eerste-keer bootstrap-ritueel.
- Workspace-indeling: [Agent workspace](/docs/concepts/agent-workspace).

Stap 4: Gateway

- Vraagt om poort, bind, auth-modus en tailscale-blootstelling.
- Aanbevolen: houd token-auth ingeschakeld zelfs voor loopback zodat lokale WS-clients moeten authenticeren.
- In token-modus biedt interactieve onboarding:
  - **Plaintext token genereren/opslaan** (standaard)
  - **SecretRef gebruiken** (opt-in)
- In password-modus ondersteunt interactieve onboarding ook plaintext of SecretRef-opslag.
- Niet-interactief token SecretRef-pad: `--gateway-token-ref-env <ENV_VAR>`.
  - Vereist een niet-lege env var in de onboarding-procesomgeving.
  - Kan niet gecombineerd worden met `--gateway-token`.
- Schakel auth alleen uit als je elk lokaal proces volledig vertrouwt.
- Niet-loopback binds vereisen nog steeds auth.

Stap 5: Kanalen

- [WhatsApp](/docs/channels/whatsapp): optionele QR-login
- [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): optionele `signal-cli`-installatie + accountconfiguratie
- [BlueBubbles](/docs/channels/bluebubbles): aanbevolen voor iMessage; server URL + wachtwoord + webhook
- [iMessage](/docs/channels/imessage): legacy `imsg` CLI-pad + DB-toegang
- DM-beveiliging: standaard is pairing. Eerste DM stuurt een code; goedkeuren via
  `openclaw pairing approve <channel> <code>` of gebruik allowlists.

Stap 6: Daemon-installatie

- macOS: LaunchAgent
  - Vereist een ingelogde gebruikerssessie; gebruik voor headless een custom LaunchDaemon (niet meegeleverd).
- Linux en Windows via WSL2: systemd user unit
  - De wizard probeert `loginctl enable-linger <user>` zodat de gateway na uitloggen blijft draaien.
  - Kan om sudo vragen (schrijft naar `/var/lib/systemd/linger`); probeert eerst zonder sudo.
- Runtime-selectie: Node (aanbevolen; vereist voor WhatsApp en Telegram). Bun wordt niet aanbevolen.

Stap 7: Health check

- Start gateway (indien nodig) en draait `openclaw health`.
- `openclaw status --deep` voegt gateway health probes toe aan status-output.

Stap 8: Skills

- Leest beschikbare skills en controleert vereisten.
- Laat je kiezen tussen node manager: npm of pnpm (bun niet aanbevolen).
- Installeert optionele afhankelijkheden (sommige gebruiken Homebrew op macOS).

Stap 9: Afronden

- Samenvatting en volgende stappen, inclusief iOS-, Android- en macOS-app opties.

Opmerking: Als er geen GUI wordt gedetecteerd, print de wizard SSH port-forward instructies voor de Control UI in plaats van een browser te openen. Als Control UI-assets ontbreken, probeert de wizard ze te bouwen; fallback is pnpm ui:build (installeert automatisch UI-afhankelijkheden).

Remote modus-details

Remote modus configureert deze machine om te verbinden met een gateway elders.

Info: Remote modus installeert of wijzigt niets op de remote host.

Wat je instelt:

• Remote gateway-URL (ws://...)
• Token als remote gateway-auth vereist is (aanbevolen)

Opmerking:

• Als de gateway loopback-only is, gebruik SSH-tunneling of een tailnet.
• Discovery-hints:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Auth- en modelopties

Gebruikt `ANTHROPIC_API_KEY` als die aanwezig is of vraagt om een key, slaat die vervolgens op voor daemon-gebruik.

- macOS: controleert Keychain-item "Claude Code-credentials"
- Linux en Windows: hergebruikt `~/.claude/.credentials.json` als die aanwezig is

Kies op macOS "Altijd toestaan" zodat launchd-starts niet blokkeren.

Draai `claude setup-token` op een willekeurige machine, plak dan het token.
Je kunt het een naam geven; leeg laten gebruikt de standaard.

Als `~/.codex/auth.json` bestaat, kan de wizard het hergebruiken.

Browserflow; plak `code#state`.

Stelt `agents.defaults.model` in op `openai-codex/gpt-5.4` wanneer model niet is ingesteld of `openai/*` is.

Gebruikt `OPENAI_API_KEY` als die aanwezig is of vraagt om een key, slaat de credential dan op in auth-profielen.

Stelt `agents.defaults.model` in op `openai/gpt-5.1-codex` wanneer model niet is ingesteld, `openai/*` of `openai-codex/*` is.

Vraagt om `XAI_API_KEY` en configureert xAI als modelprovider.

Vraagt om `OPENCODE_API_KEY` (of `OPENCODE_ZEN_API_KEY`) en laat je kiezen tussen de Zen- of Go-catalogus.
Setup-URL: [opencode.ai/auth](https://opencode.ai/auth).

Slaat de key voor je op.

Vraagt om `AI_GATEWAY_API_KEY`.
Meer detail: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Vraagt om account ID, gateway ID en `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Meer detail: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

Config wordt automatisch geschreven.
Meer detail: [MiniMax](/docs/providers/minimax).

Vraagt om `SYNTHETIC_API_KEY`.
Meer detail: [Synthetic](/docs/providers/synthetic).

Vraagt om base URL (standaard `http://127.0.0.1:11434`), biedt vervolgens Cloud + Local of Local-modus.
Ontdekt beschikbare modellen en stelt standaarden voor.
Meer detail: [Ollama](/docs/providers/ollama).

Moonshot (Kimi K2) en Kimi Coding configs worden automatisch geschreven.
Meer detail: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Werkt met OpenAI-compatible en Anthropic-compatible endpoints.

Interactieve onboarding ondersteunt dezelfde API key-opslagkeuzes als andere provider API key-flows:
- **API key nu plakken** (plaintext)
- **Secret reference gebruiken** (env ref of geconfigureerde provider ref, met preflight-validatie)

Niet-interactieve flags:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (optioneel; valt terug op `CUSTOM_API_KEY`)
- `--custom-provider-id` (optioneel)
- `--custom-compatibility <openai|anthropic>` (optioneel; standaard `openai`)

Laat auth ongeconfigureerd.

Modelgedrag:

• Kies standaardmodel uit gedetecteerde opties, of voer provider en model handmatig in.
• De wizard draait een modelcontrole en waarschuwt als het geconfigureerde model onbekend is of auth mist.

Credential- en profielpaden:

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

Credential-opslagmodus:

• Standaard onboarding-gedrag persisteert API keys als plaintext-waarden in auth-profielen.
• --secret-input-mode ref schakelt referentiemodus in in plaats van plaintext key-opslag. In interactieve onboarding kun je kiezen:
  • omgevingsvariabele ref (bijvoorbeeld keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • geconfigureerde provider ref (file of exec) met provider alias + id
• Interactieve referentiemodus draait een snelle preflight-validatie voor het opslaan.
  • Env refs: valideert variabelenaam + niet-lege waarde in de huidige onboarding-omgeving.
  • Provider refs: valideert provider-config en resolvet het gevraagde id.
  • Als preflight faalt, toont onboarding de fout en laat je opnieuw proberen.
• In niet-interactieve modus is --secret-input-mode ref alleen env-backed.
  • Stel de provider env var in de onboarding-procesomgeving in.
  • Inline key-flags (bijvoorbeeld --openai-api-key) vereisen dat die env var is ingesteld; anders faalt onboarding direct.
  • Voor custom providers slaat niet-interactieve ref-modus models.providers.<id>.apiKey op als { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • In dat custom-provider geval vereist --custom-api-key dat CUSTOM_API_KEY is ingesteld; anders faalt onboarding direct.
• Gateway auth-credentials ondersteunen plaintext en SecretRef-keuzes in interactieve onboarding:
  • Token-modus: Plaintext token genereren/opslaan (standaard) of SecretRef gebruiken.
  • Password-modus: plaintext of SecretRef.
• Niet-interactief token SecretRef-pad: --gateway-token-ref-env <ENV_VAR>.
• Bestaande plaintext-setups blijven ongewijzigd werken.

Opmerking: Tip voor headless en servers: voltooi OAuth op een machine met een browser, kopieer dan ~/.openclaw/credentials/oauth.json (of $OPENCLAW_STATE_DIR/credentials/oauth.json) naar de gateway-host.

Outputs en internals

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

• agents.defaults.workspace
• agents.defaults.model / models.providers (als Minimax is gekozen)
• tools.profile (lokale onboarding standaardiseert naar "coding" wanneer niet ingesteld; bestaande expliciete waarden worden behouden)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (lokale onboarding standaardiseert naar per-channel-peer wanneer niet ingesteld; bestaande expliciete waarden worden behouden)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Kanaal-allowlists (Slack, Discord, Matrix, Microsoft Teams) wanneer je opt-in kiest tijdens prompts (namen worden waar mogelijk geresolved naar ID’s)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add schrijft agents.list[] en optionele bindings.

WhatsApp-credentials staan onder ~/.openclaw/credentials/whatsapp/<accountId>/. Sessions worden opgeslagen onder ~/.openclaw/agents/<agentId>/sessions/.

Opmerking: Sommige kanalen worden geleverd als plugins. Wanneer ze geselecteerd worden tijdens onboarding, vraagt de wizard om de plugin te installeren (npm of lokaal pad) voordat de kanaalconfiguratie plaatsvindt.

Gateway wizard-RPC:

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

Clients (macOS-app en Control UI) kunnen stappen renderen zonder onboarding-logica opnieuw te implementeren.

Signal setup-gedrag:

• Downloadt het juiste release-asset
• Slaat het op onder ~/.openclaw/tools/signal-cli/<version>/
• Schrijft channels.signal.cliPath in config
• JVM-builds vereisen Java 21
• Native builds worden gebruikt wanneer beschikbaar
• Windows gebruikt WSL2 en volgt de Linux signal-cli flow binnen WSL

Gerelateerde docs

• Onboarding-hub: Onboarding Wizard (CLI)
• Automatisering en scripts: CLI Automation
• Commandoreferentie: openclaw onboard