Skip to main content

​
openclaw onboard

Guided setup wizard for first-time OpenClaw configuration.

​
Usage

openclaw onboard [options]

​
Options

​
--non-interactive
boolean
Run in non-interactive mode (requires —accept-risk)
​
--accept-risk
boolean
Acknowledge security risks (required for —non-interactive)
​
--flow <type>
string
Onboarding flow: quick, advanced, or manual
  • quick: Guided setup with defaults
  • advanced: Full configuration options
  • manual: Expert mode with minimal guidance
​
--auth-choice <choice>
string
Authentication choice: token or openai-codex
  • token: Anthropic setup-token flow
  • openai-codex: OpenAI Codex OAuth
​
--workspace <path>
string
Workspace directory path (default: ~/openclaw-workspace)
​
--reset
boolean
Reset existing configuration before onboarding
​
--install-daemon
boolean
Install gateway as a system service (launchd/systemd/schtasks)

​
Flows

​
Quick Flow

Recommended for first-time users. Guides through:
  1. Model provider authentication
  2. Gateway configuration
  3. Workspace setup
  4. Optional channel connections
  5. Gateway daemon installation
openclaw onboard --flow quick

​
Advanced Flow

For users who want more control:
  1. Choose authentication method
  2. Configure gateway details (port, bind, auth)
  3. Set up workspace and skills
  4. Configure multiple channels
  5. Advanced agent settings
openclaw onboard --flow advanced

​
Manual Flow

Expert mode with minimal guidance: 
openclaw onboard --flow manual

​
Authentication

The onboarding wizard supports multiple authentication methods:

​
Anthropic Setup Token

Recommended for Claude models: 
openclaw onboard --auth-choice token
You’ll receive a setup token from Anthropic’s developer console.

​
OpenAI Codex OAuth

For OpenAI models: 
openclaw onboard --auth-choice openai-codex
Uses OAuth flow to authenticate with OpenAI.

​
Non-Interactive Mode

For automated setups and CI/CD: 
openclaw onboard --non-interactive --accept-risk --auth-choice token
Non-interactive mode requires --accept-risk to acknowledge security implications. Read the security documentation before using automated setup.

​
Examples

# Interactive onboarding (recommended)
openclaw onboard

# Quick flow with defaults
openclaw onboard --flow quick

# Advanced configuration
openclaw onboard --flow advanced

​
What Gets Configured

The onboarding wizard sets up:

​
1. Model Provider Authentication

  • Anthropic API credentials
  • OpenAI API credentials
  • Custom model endpoints
  • Authentication profiles

​
2. Gateway Configuration

  • Gateway mode (local or remote)
  • WebSocket port (default: 18789)
  • Bind address (loopback, lan, tailnet)
  • Authentication (token or password)
  • Tailscale integration (optional)

​
3. Workspace Setup

  • Workspace directory creation
  • Bootstrap files (BOOTSTRAP.md, guides)
  • Skills directory structure
  • Memory system configuration

​
4. Channel Connections

  • Optional channel setup (Telegram, Discord, Slack, etc.)
  • Channel authentication and tokens
  • Default channel configuration

​
5. Agent Defaults

  • Default model selection
  • Thinking level preferences
  • Context token limits
  • Timeout settings

​
6. System Service

  • Gateway daemon installation (optional)
  • LaunchAgent (macOS)
  • systemd user service (Linux)
  • Task Scheduler (Windows)

​
Configuration File

Onboarding creates ~/.openclaw/openclaw.json with your settings: 
{
  // Generated by: openclaw onboard
  // Date: 2026-02-19
  
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "generated-token"
    }
  },
  
  agents: {
    defaults: {
      workspace: "~/openclaw-workspace",
      model: {
        primary: "anthropic:claude-4.5-sonnet"
      },
      thinkingDefault: "medium"
    }
  },
  
  // ... channels and other config
}

​
Workspace Structure

The workspace is created with: 
~/openclaw-workspace/
├── BOOTSTRAP.md          # Getting started guide
├── .gitignore            # Git ignore patterns
├── skills/               # Custom skills directory
│   └── README.md
├── tools/                # Custom tools
└── memory/               # Memory system files

​
Post-Onboarding

After onboarding completes:
  1. Start the gateway: 
    openclaw gateway start
  2. Check status: 
    openclaw status
  3. Test agent: 
    openclaw agent --message "Hello" --to +1234567890
  4. Add channels (if not done during onboarding): 
    openclaw channels add

​
Troubleshooting

If onboarding fails:
  1. Check requirements: 
    node --version  # Should be 22+
  2. Reset and retry: 
    openclaw onboard --reset
  3. Run diagnostics: 
    openclaw doctor
  4. Check logs: 
    openclaw logs

​
Platform-Specific Notes

​
macOS

  • Supports LaunchAgent for automatic gateway startup
  • iMessage integration available
  • Menu bar app available

​
Linux

  • Uses systemd user services
  • May require lingering: loginctl enable-linger $USER
  • Signal CLI integration recommended

​
Windows

  • WSL2 recommended for best experience
  • Native Windows support is experimental
  • Task Scheduler for service management
Run openclaw onboard again at any time to reconfigure settings. Use --reset to start fresh.
  • setup - Initialize config without interactive wizard
  • configure - Interactive config wizard for existing setups
  • doctor - Validate and repair configuration
  • gateway - Manage the gateway after onboarding

Build docs developers (and LLMs) love

Get started for freeTalk to us