> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/openclaw/openclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# openclaw onboard

> Interactive onboarding wizard for gateway, workspace, and skills

# openclaw onboard

Guided setup wizard for first-time OpenClaw configuration.

## Usage

```bash theme={null}
openclaw onboard [options]
```

## Options

<ParamField path="--non-interactive" type="boolean">
  Run in non-interactive mode (requires --accept-risk)
</ParamField>

<ParamField path="--accept-risk" type="boolean">
  Acknowledge security risks (required for --non-interactive)
</ParamField>

<ParamField path="--flow <type>" type="string">
  Onboarding flow: `quick`, `advanced`, or `manual`

  * `quick`: Guided setup with defaults
  * `advanced`: Full configuration options
  * `manual`: Expert mode with minimal guidance
</ParamField>

<ParamField path="--auth-choice <choice>" type="string">
  Authentication choice: `token` or `openai-codex`

  * `token`: Anthropic setup-token flow
  * `openai-codex`: OpenAI Codex OAuth
</ParamField>

<ParamField path="--workspace <path>" type="string">
  Workspace directory path (default: \~/openclaw-workspace)
</ParamField>

<ParamField path="--reset" type="boolean">
  Reset existing configuration before onboarding
</ParamField>

<ParamField path="--install-daemon" type="boolean">
  Install gateway as a system service (launchd/systemd/schtasks)
</ParamField>

## 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

```bash theme={null}
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

```bash theme={null}
openclaw onboard --flow advanced
```

### Manual Flow

Expert mode with minimal guidance:

```bash theme={null}
openclaw onboard --flow manual
```

## Authentication

The onboarding wizard supports multiple authentication methods:

### Anthropic Setup Token

Recommended for Claude models:

```bash theme={null}
openclaw onboard --auth-choice token
```

You'll receive a setup token from Anthropic's developer console.

### OpenAI Codex OAuth

For OpenAI models:

```bash theme={null}
openclaw onboard --auth-choice openai-codex
```

Uses OAuth flow to authenticate with OpenAI.

## Non-Interactive Mode

For automated setups and CI/CD:

```bash theme={null}
openclaw onboard --non-interactive --accept-risk --auth-choice token
```

<Warning>
  Non-interactive mode requires `--accept-risk` to acknowledge security implications. Read the [security documentation](https://docs.openclaw.ai/security) before using automated setup.
</Warning>

## Examples

<CodeGroup>
  ```bash Quick Start theme={null}
  # Interactive onboarding (recommended)
  openclaw onboard

  # Quick flow with defaults
  openclaw onboard --flow quick

  # Advanced configuration
  openclaw onboard --flow advanced
  ```

  ```bash Custom Workspace theme={null}
  # Use custom workspace directory
  openclaw onboard --workspace ~/my-openclaw-workspace

  # Reset and reconfigure
  openclaw onboard --reset
  ```

  ```bash Authentication theme={null}
  # Anthropic setup token
  openclaw onboard --auth-choice token

  # OpenAI Codex OAuth
  openclaw onboard --auth-choice openai-codex
  ```

  ```bash Automated theme={null}
  # Non-interactive setup
  openclaw onboard --non-interactive --accept-risk \
    --auth-choice token \
    --workspace ~/openclaw-workspace

  # With daemon installation
  openclaw onboard --non-interactive --accept-risk \
    --install-daemon \
    --auth-choice token
  ```
</CodeGroup>

## 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:

```json5 theme={null}
{
  // 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**:
   ```bash theme={null}
   openclaw gateway start
   ```

2. **Check status**:
   ```bash theme={null}
   openclaw status
   ```

3. **Test agent**:
   ```bash theme={null}
   openclaw agent --message "Hello" --to +1234567890
   ```

4. **Add channels** (if not done during onboarding):
   ```bash theme={null}
   openclaw channels add
   ```

## Troubleshooting

If onboarding fails:

1. **Check requirements**:
   ```bash theme={null}
   node --version  # Should be 22+
   ```

2. **Reset and retry**:
   ```bash theme={null}
   openclaw onboard --reset
   ```

3. **Run diagnostics**:
   ```bash theme={null}
   openclaw doctor
   ```

4. **Check logs**:
   ```bash theme={null}
   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

<Tip>
  Run `openclaw onboard` again at any time to reconfigure settings. Use `--reset` to start fresh.
</Tip>

## Related Commands

* [setup](/cli/setup) - Initialize config without interactive wizard
* [configure](/cli/configure) - Interactive config wizard for existing setups
* [doctor](/cli/doctor) - Validate and repair configuration
* [gateway](/cli/gateway) - Manage the gateway after onboarding