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

> Run system diagnostics and health checks

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

## Usage

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

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

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

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

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

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

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

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

```bash theme={null}
#!/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:

```bash theme={null}
NULLCLAW_LOG=debug nullclaw doctor
```

## See Also

* [Status](/cli/status) - Quick status overview
* [Onboard](/cli/onboard) - Initial configuration
* [Configuration](/configuration/overview) - Config reference