CLI setup reference

Remote mode details

Remote mode configures this machine to connect to a gateway elsewhere.

What you set:

• Remote gateway URL (ws://...)
• Token if remote gateway auth is required (recommended)

Auth and model options

Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.

Sets `agents.defaults.model` to `openai/gpt-5.5` through the Codex runtime when model is unset or already OpenAI-family.

Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset, `openai/*`, or `openai-codex/*`.

Interactive onboarding supports the same API key storage choices as other provider API key flows:
- **Paste API key now** (plaintext)
- **Use secret reference** (env ref or configured provider ref, with preflight validation)

Non-interactive flags:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
- `--custom-provider-id` (optional)
- `--custom-compatibility <openai|anthropic>` (optional; default `openai`)
- `--custom-image-input` / `--custom-text-input` (optional; override inferred model input capability)

Model behavior:

• Pick default model from detected options, or enter provider and model manually.
• Custom-provider onboarding infers image support for common model IDs and asks only when the model name is unknown.
• 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.

Credential and profile paths:

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

Credential storage mode:

• 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 is env-backed only.
  • Set the provider env var in the onboarding process environment.
  • Inline key flags (for example --openai-api-key) require that env var to be set; otherwise onboarding fails fast.
  • For custom providers, 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.
• 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>.
• Existing plaintext setups continue to work unchanged.

Outputs and internals

Typical fields in ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.skipBootstrap when --skip-bootstrap is passed
• agents.defaults.model / models.providers (if Minimax chosen)
• tools.profile (local onboarding defaults to "coding" when unset; existing explicit values are preserved)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (local onboarding defaults this to per-channel-peer when unset; existing explicit values are preserved)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
• 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

openclaw agents add writes agents.list[] and optional bindings.

WhatsApp credentials go under ~/.openclaw/credentials/whatsapp/<accountId>/. Sessions are stored under ~/.openclaw/agents/<agentId>/sessions/.

Gateway wizard RPC:

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

Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.

Signal setup behavior:

• Downloads the appropriate release asset
• Stores it under ~/.openclaw/tools/signal-cli/<version>/
• Writes channels.signal.cliPath in config
• JVM builds require Java 21
• Native builds are used when available
• Windows uses WSL2 and follows Linux signal-cli flow inside WSL

Related docs

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