openclaw onboard

Interactive onboarding wizard for gateway, workspace, and skills

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

Quick Start

# 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 [phone]
   

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.

Related Commands

• setup - Initialize config without interactive wizard
• configure - Interactive config wizard for existing setups
• doctor - Validate and repair configuration
• gateway - Manage the gateway after onboarding