CLI setup reference

​

What the wizard does

• Workspace location and bootstrap files
• Model and auth setup (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and more provider-owned auth flows)
• Gateway settings (port, bind, auth, Tailscale)
• Channels and providers (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and other bundled or plugin channels)
• Web search provider (optional)
• Skills setup
• Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
• Health check

​

Local flow details

​

Remote mode details

• Remote gateway URL (ws://... or wss://...)
• Token, password, or no auth, matching the remote Gateway’s configuration

​

Auth and model options

• Pick default model from detected options, or enter provider and model manually.
• When onboarding starts from a provider auth choice, the model picker prefers that provider automatically. For Volcengine and BytePlus, the same preference also matches their coding-plan variants (volcengine-plan/*, byteplus-plan/*).
• If that preferred-provider filter would be empty, the picker falls back to the full catalog instead of showing no models.
• Wizard runs a model check and warns if the configured model is unknown or missing auth.

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

• Default onboarding behavior persists API keys as plaintext values in auth profiles.
• --secret-input-mode ref enables reference mode instead of plaintext key storage. In interactive setup, you can choose either:
  • environment variable ref (for example keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • configured provider ref (file or exec) with provider alias + id
• Interactive reference mode runs a fast preflight validation before saving.
  • Env refs: validates variable name + non-empty value in the current onboarding environment.
  • Provider refs: validates provider config and resolves the requested id.
  • If preflight fails, onboarding shows the error and lets you retry.
• In non-interactive mode, --secret-input-mode ref creates only env-backed references for new credentials.
  • Set the provider env var in the onboarding process environment when adding a new credential.
  • Inline key flags (for example --openai-api-key) require that env var to be set; otherwise onboarding fails fast.
  • Existing resolvable named auth profiles are reused unchanged, including existing env, file, exec, and store references; no new apiKey or keyRef is written and no additional provider env var is required.
  • For new custom-provider credentials, non-interactive ref mode stores models.providers.<id>.apiKey as { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • In that custom-provider case, --custom-api-key requires CUSTOM_API_KEY to be set; otherwise onboarding fails fast.
  • Existing plaintext profile credentials remain unchanged; reference mode does not migrate them. Run openclaw secrets configure --apply, then openclaw secrets audit --check. See Secrets management.
• Gateway auth credentials support plaintext and SecretRef choices in interactive setup:
  • Token mode: Generate/store plaintext token (default) or Use SecretRef.
  • Password mode: plaintext or SecretRef.
• Non-interactive token SecretRef path: --gateway-token-ref-env <ENV_VAR>.
• The named environment variable must be non-empty in the onboarding process. --gateway-token and --gateway-token-ref-env are mutually exclusive.
• Existing plaintext setups continue to work unchanged.

​

Outputs and internals

• agents.defaults.workspace
• agents.defaults.skipBootstrap when --skip-bootstrap is passed
• agents.defaults.model and provider config when the selected provider needs it
• tools.profile (local onboarding defaults to "coding" when unset; existing explicit values are preserved)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (onboarding preserves explicit values and otherwise leaves it unset, so the main default keeps all direct messages across channels in the agent’s rolling main session—the personal-agent default. For shared or multi-user inboxes, use per-channel-peer; openclaw security audit recommends isolation when it detects multi-user DM traffic)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Channel allowlists when you opt in during prompts. Discord, Matrix, Microsoft Teams, and Slack resolve names to IDs when possible; other channels accept their native IDs directly.
• skills.install.nodeManager
  • The setup --node-manager flag accepts npm, pnpm, or bun.
  • Manual config can still set skills.install.nodeManager: "yarn" later.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

​

Installed app recommendations

​

Non-interactive setup

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

​

Gateway wizard RPC

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

​

Signal setup behavior

• Downloads the appropriate release asset from the official signal-cli GitHub releases (native build, Linux x86-64 only)
• On other platforms (macOS, non-x64 Linux), installs via Homebrew instead
• Stores the release-asset install under ~/.openclaw/tools/signal-cli/<version>/
• Writes channels.signal.transport.cliPath with kind: "managed-native" in config
• Native Windows is not supported yet; run onboarding inside WSL2 to get the Linux install path

​

Related docs

• Onboarding hub: Onboarding (CLI)
• Automation and scripts: CLI Automation
• Command reference: openclaw onboard