nullclaw doctor

Run system diagnostics and health checks

The nullclaw doctor command runs comprehensive diagnostics to verify your installation, configuration, and system health.

Usage

nullclaw doctor

What It Checks

The doctor command performs these diagnostic checks:

1. Installation

• ✓ Zig version (requires 0.15.2)
• ✓ Binary location and permissions
• ✓ Config directory exists (~/.nullclaw)
• ✓ Config file exists and is valid JSON

2. Configuration

• ✓ Valid JSON syntax
• ✓ Required fields present
• ✓ Provider configuration (API keys, base URLs)
• ✓ Model selection (primary model exists)
• ✓ Channel credentials (encrypted secrets)

3. Connectivity

• ✓ Provider API reachable
• ✓ Test API call with configured model
• ✓ Channel services reachable (Telegram, Discord, etc.)
• ✓ Tunnel connectivity (if configured)

4. Dependencies

• ✓ Required CLI tools installed:
  • signal-cli (for Signal channel)
  • nak (for Nostr channel)
  • cloudflared / ngrok / tailscale (for tunnels)

5. Memory Backend

• ✓ SQLite database accessible
• ✓ FTS5 extension available
• ✓ Embedding provider configured (if using vector search)
• ✓ Database integrity

6. Security

• ✓ Sandbox backend available (landlock, firejail, bubblewrap, docker)
• ✓ Workspace directory exists
• ✓ File permissions correct
• ✓ Secrets encryption working

7. Gateway

• ✓ Port available (default 3000)
• ✓ Pairing system functional
• ✓ Webhook endpoints responding

Example Output

$ nullclaw doctor
Running diagnostics...

✓ Installation
  Zig version: 0.15.2
  Binary: /usr/local/bin/nullclaw (678 KB)
  Config dir: /Users/alice/.nullclaw

✓ Configuration
  Config file: valid JSON
  Provider: openrouter (configured)
  Model: openrouter/anthropic/claude-sonnet-4
  Channels: telegram, discord (2 active)

✓ Connectivity
  OpenRouter API: reachable
  Test request: success (claude-sonnet-4)
  Telegram API: reachable
  Discord Gateway: connected

✓ Dependencies
  signal-cli: not installed (optional)
  nak: /usr/local/bin/nak
  cloudflared: /opt/homebrew/bin/cloudflared

✓ Memory
  Backend: sqlite
  Database: /Users/alice/.nullclaw/memory.db (12 MB)
  FTS5: available
  Embeddings: openai (text-embedding-3-small)

✓ Security
  Sandbox: landlock (kernel 5.13+)
  Workspace: /Users/alice/.nullclaw/workspace
  Secrets: encrypted (ChaCha20-Poly1305)

✓ Gateway
  Port 3000: available
  Pairing: functional
  Health endpoint: http://127.0.0.1:3000/health

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
All checks passed! ✓

Error Example

$ nullclaw doctor
Running diagnostics...

✗ Configuration
  Config file: syntax error at line 42
  Error: unexpected token '}'

✗ Connectivity
  OpenRouter API: unreachable
  Error: Connection timeout

⚠ Dependencies
  signal-cli: not installed
  Note: Required for Signal channel

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found 2 errors, 1 warning
See above for details

Common Issues and Fixes

Invalid Config

✗ Configuration
  Config file: syntax error at line 42

Fix: Edit ~/.nullclaw/config.json and fix JSON syntax:

# Validate JSON
jq . ~/.nullclaw/config.json

# Or use an editor with JSON validation

Provider Unreachable

✗ Connectivity
  OpenRouter API: unreachable

Fix: Check network and API key:

# Test API manually
curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer sk-or-..."

# Verify API key in config
cat ~/.nullclaw/config.json | jq .models.providers.openrouter

Missing Dependencies

⚠ Dependencies
  nak: not installed

Fix: Install missing tools:

# nak (for Nostr)
go install github.com/fiatjaf/nak@latest

# signal-cli (for Signal)
brew install signal-cli  # macOS

# cloudflared (for Cloudflare Tunnel)
brew install cloudflared  # macOS

Port Already in Use

✗ Gateway
  Port 3000: in use by another process

Fix: Change port or kill process:

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port in config
{
  "gateway": { "port": 8080 }
}

Sandbox Not Available

⚠ Security
  Sandbox: none available
  Note: Install firejail or bubblewrap

Fix: Install sandbox backend:

# Linux
sudo apt install firejail       # Debian/Ubuntu
sudo pacman -S bubblewrap       # Arch

# Or use Docker
sudo apt install docker.io

Exit Codes

• 0 - All checks passed
• 1 - Warnings only
• 2 - Errors found

Use in Scripts

#!/bin/bash

if nullclaw doctor; then
  echo "Health check passed"
  nullclaw gateway
else
  echo "Health check failed"
  exit 1
fi

Verbose Mode

For detailed output:

NULLCLAW_LOG=debug nullclaw doctor

See Also

• Status - Quick status overview
• Onboard - Initial configuration
• Configuration - Config reference