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

# nullclaw onboard

> Interactive setup wizard for first-time configuration

The `nullclaw onboard` command guides you through initial configuration, creating `~/.nullclaw/config.json` with your provider, channels, and security settings.

## Usage

```bash theme={null}
# Quick setup with API key
nullclaw onboard --api-key sk-or-... --provider openrouter

# Interactive wizard
nullclaw onboard --interactive

# Reconfigure channels only
nullclaw onboard --channels-only
```

## Options

<ParamField path="--api-key" type="string">
  API key for the provider (quick mode)
</ParamField>

<ParamField path="--provider" type="string">
  Provider name: openrouter, openai, anthropic, groq, ollama, etc.
</ParamField>

<ParamField path="--interactive" type="boolean">
  Run full interactive wizard (recommended for first-time setup)
</ParamField>

<ParamField path="--channels-only" type="boolean">
  Reconfigure channels and allowlists only (preserve existing provider config)
</ParamField>

## Quick Mode

Fastest way to get started:

```bash theme={null}
nullclaw onboard --api-key sk-or-v1-abc123 --provider openrouter
```

This creates a minimal config:

```json theme={null}
{
  "models": {
    "providers": {
      "openrouter": {
        "api_key": "sk-or-v1-abc123"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    }
  }
}
```

## Interactive Wizard

The full wizard walks through:

<Steps>
  <Step title="Provider selection">
    Choose from 22+ AI providers:

    * OpenRouter (recommended - aggregates 100+ models)
    * Anthropic (Claude)
    * OpenAI (GPT-4, o1)
    * Groq (fast inference)
    * Ollama (local models)
    * And more...
  </Step>

  <Step title="API key setup">
    Enter your API key. The wizard will:

    * Validate the key format
    * Test connectivity
    * Encrypt the key with ChaCha20-Poly1305
  </Step>

  <Step title="Default model selection">
    Pick your primary model:

    * OpenRouter: `openrouter/anthropic/claude-sonnet-4`
    * Anthropic: `claude-4`
    * OpenAI: `gpt-4o`, `o1`
    * Ollama: `llama3.2`, `qwen2.5`
  </Step>

  <Step title="Channel configuration">
    Enable and configure messaging channels:

    * Telegram bot (token + allowlist)
    * Discord bot (token + guild)
    * Signal (phone number)
    * Nostr (keypair generation)
    * IRC, Slack, Matrix, etc.
  </Step>

  <Step title="Memory backend">
    Choose memory storage:

    * **SQLite** (recommended - hybrid vector + FTS5)
    * **Markdown** (simple file-based)
    * **PostgreSQL** (for production)
    * **Redis** (caching layer)
  </Step>

  <Step title="Security settings">
    Configure autonomy level:

    * **Supervised** (requires approval for risky commands)
    * **Autonomous** (full automation)
    * **Restricted** (read-only)

    Set workspace restrictions:

    * `workspace_only: true` (recommended)
    * Command allowlist
    * Resource limits
  </Step>

  <Step title="Nostr setup (optional)">
    If enabling Nostr:

    * Generate new keypair or import existing
    * Configure relays (wss\://relay.damus.io, etc.)
    * Set owner pubkey for DM allowlist
    * Install `nak` CLI tool
  </Step>
</Steps>

## Channels-Only Mode

Reconfigure channels without touching provider settings:

```bash theme={null}
nullclaw onboard --channels-only
```

Use this to:

* Add new channels
* Update allowlists
* Change channel credentials
* Enable/disable channels

## Examples

### OpenRouter + Telegram

```bash theme={null}
nullclaw onboard --interactive

# Wizard prompts:
# 1. Provider: openrouter
# 2. API key: sk-or-v1-...
# 3. Model: openrouter/anthropic/claude-sonnet-4
# 4. Enable Telegram? yes
# 5. Bot token: 123456:ABC-DEF...
# 6. Allowed users: your_telegram_username
```

Result:

```json theme={null}
{
  "models": {
    "providers": {
      "openrouter": {"api_key": "enc2:..."}
    }
  },
  "agents": {
    "defaults": {
      "model": {"primary": "openrouter/anthropic/claude-sonnet-4"}
    }
  },
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "enc2:...",
          "allow_from": ["your_telegram_username"]
        }
      }
    }
  }
}
```

### Local Ollama

```bash theme={null}
nullclaw onboard --api-key none --provider ollama

# Model: llama3.2
# Base URL: http://localhost:11434 (default)
```

## Configuration Output

Onboarding creates `~/.nullclaw/config.json` with:

* Encrypted API keys (ChaCha20-Poly1305)
* Provider and model selection
* Channel credentials and allowlists
* Memory backend configuration
* Security policies
* Gateway settings

<Info>
  You can manually edit `~/.nullclaw/config.json` after onboarding. See [Configuration](/configuration/overview) for full reference.
</Info>

## Validation

After onboarding, verify your setup:

```bash theme={null}
# Check configuration
nullclaw status

# Run diagnostics
nullclaw doctor

# Test agent
nullclaw agent -m "Hello!"
```

## See Also

* [Configuration Overview](/configuration/overview) - Full config reference
* [Providers](/guides/providers) - Provider setup guides
* [Channels](/configuration/channels) - Channel configuration
* [Doctor](/cli/doctor) - System diagnostics