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

# 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

--api-key · string

API key for the provider (quick mode)

--provider · string

Provider name: openrouter, openai, anthropic, groq, ollama, etc.

--interactive · boolean

Run full interactive wizard (recommended for first-time setup)

--channels-only · boolean

Reconfigure channels and allowlists only (preserve existing provider config)

Quick Mode

Fastest way to get started:

nullclaw onboard --api-key sk-or-v1-abc123 --provider openrouter

This creates a minimal config:

{
  "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:

1. 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…
2. API key setup

   Enter your API key. The wizard will:

   • Validate the key format
   • Test connectivity
   • Encrypt the key with ChaCha20-Poly1305
3. 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
4. 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.
5. Memory backend

   Choose memory storage:

   • SQLite (recommended - hybrid vector + FTS5)
   • Markdown (simple file-based)
   • PostgreSQL (for production)
   • Redis (caching layer)
6. 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
7. 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

Channels-Only Mode

Reconfigure channels without touching provider settings:

nullclaw onboard --channels-only

Use this to:

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

Examples

OpenRouter + Telegram

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:

{
  "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

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

You can manually edit ~/.nullclaw/config.json after onboarding. See Configuration for full reference.

Validation

After onboarding, verify your setup:

# Check configuration
nullclaw status

# Run diagnostics
nullclaw doctor

# Test agent
nullclaw agent -m "Hello!"

See Also

• Configuration Overview - Full config reference
• Providers - Provider setup guides
• Channels - Channel configuration
• Doctor - System diagnostics