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

# Configuring AI Providers

> Set up OpenAI, Anthropic, OpenRouter, and other AI model providers in NullClaw

NullClaw supports 22+ AI providers through a unified vtable interface. Configure providers in `~/.nullclaw/config.json` under `models.providers`.

## Quick Setup

Use the onboarding wizard for fastest setup:

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

# Interactive wizard
nullclaw onboard --interactive
```

## Supported Providers

<CardGroup cols={3}>
  <Card title="OpenRouter" icon="route">
    Access to 200+ models via single API
  </Card>

  <Card title="Anthropic" icon="brain">
    Claude models (Opus, Sonnet, Haiku)
  </Card>

  <Card title="OpenAI" icon="sparkles">
    GPT-4, GPT-3.5, and embeddings
  </Card>

  <Card title="Groq" icon="bolt">
    Fast inference for Llama, Mixtral
  </Card>

  <Card title="Ollama" icon="server">
    Local models (no API key needed)
  </Card>

  <Card title="Google Gemini" icon="google">
    Gemini Pro and Flash models
  </Card>
</CardGroup>

## Configuration

### OpenRouter (Recommended)

Access 200+ models through a single API:

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

<Steps>
  <Step title="Get API Key">
    Sign up at [openrouter.ai](https://openrouter.ai) and create an API key
  </Step>

  <Step title="Add to Config">
    Place your key in `~/.nullclaw/config.json` under `models.providers.openrouter.api_key`
  </Step>

  <Step title="Select Model">
    Use format `openrouter/<provider>/<model>` (e.g., `openrouter/anthropic/claude-sonnet-4`)
  </Step>
</Steps>

### Anthropic Claude

Direct access to Claude models:

```json config.json theme={null}
{
  "models": {
    "providers": {
      "anthropic": {
        "api_key": "sk-ant-...",
        "base_url": "https://api.anthropic.com"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4"
      }
    }
  }
}
```

**Features:**

* Supports both standard API keys (`sk-ant-...`) and OAuth tokens (`sk-ant-oat01-...`)
* Custom `base_url` for proxies or self-hosted endpoints
* Default max tokens: 4096 (configurable)

### OpenAI

GPT models and embeddings:

```json config.json theme={null}
{
  "models": {
    "providers": {
      "openai": {
        "api_key": "sk-..."
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "gpt-4"
      }
    }
  }
}
```

### Groq

Fast inference for open models:

```json config.json theme={null}
{
  "models": {
    "providers": {
      "groq": {
        "api_key": "gsk_..."
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "llama-3.1-70b"
      }
    }
  }
}
```

### Ollama (Local)

Run models locally without API keys:

```json config.json theme={null}
{
  "models": {
    "providers": {
      "ollama": {
        "base_url": "http://localhost:11434"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "llama3.1:8b"
      }
    }
  }
}
```

<Note>
  Ollama doesn't require an API key. Install models with `ollama pull llama3.1:8b`
</Note>

## Model Selection

### Primary Model

Set your default model in `agents.defaults.model.primary`:

<CodeGroup>
  ```json OpenRouter theme={null}
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    }
  }
  ```

  ```json Direct Provider theme={null}
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4"
      }
    }
  }
  ```

  ```json Local Ollama theme={null}
  "agents": {
    "defaults": {
      "model": {
        "primary": "llama3.1:8b"
      }
    }
  }
  ```
</CodeGroup>

### Per-Agent Models

Different agents can use different models:

```json config.json theme={null}
{
  "agents": {
    "list": [
      {
        "id": "researcher",
        "model": { "primary": "openrouter/anthropic/claude-opus-4" },
        "system_prompt": "You are a research assistant..."
      },
      {
        "id": "coder",
        "model": { "primary": "gpt-4" },
        "system_prompt": "You are a coding assistant..."
      }
    ]
  }
}
```

## Custom Providers

Any OpenAI-compatible API can be used:

```json config.json theme={null}
{
  "models": {
    "providers": {
      "custom": {
        "api_key": "your-key",
        "base_url": "https://your-api.com/v1"
      }
    }
  }
}
```

## Temperature Control

Control response randomness globally or per-model:

```json config.json theme={null}
{
  "default_temperature": 0.7,
  "agents": {
    "defaults": {
      "temperature": 0.9
    }
  }
}
```

* **0.0**: Deterministic, focused responses
* **0.7**: Balanced (default)
* **1.0+**: Creative, varied responses

## Reliability & Fallbacks

Configure retries and fallback providers:

```json config.json theme={null}
{
  "reliability": {
    "provider_retries": 2,
    "provider_backoff_ms": 500,
    "fallback_providers": ["groq", "openai"],
    "model_fallbacks": [
      "openrouter/anthropic/claude-sonnet-4",
      "gpt-4"
    ]
  }
}
```

## Troubleshooting

### Missing API Key

```bash theme={null}
# Check your config
cat ~/.nullclaw/config.json | grep api_key

# Re-run onboarding
nullclaw onboard --interactive
```

### Provider Not Working

```bash theme={null}
# Check system diagnostics
nullclaw doctor

# Test with a simple message
nullclaw agent -m "Hello"
```

### Custom Base URL

Ensure your custom URL:

* Uses HTTPS (HTTP rejected for security)
* Ends without trailing slash
* Implements OpenAI-compatible `/v1/chat/completions` endpoint

<Warning>
  API keys are stored in plaintext by default. Enable encryption in production:

  ```json theme={null}
  {
    "secrets": {
      "encrypt": true
    }
  }
  ```
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Channels" href="/guides/telegram" icon="message">
    Connect Telegram, Discord, or other channels
  </Card>

  <Card title="Memory Setup" href="/guides/memory-backends" icon="database">
    Configure vector search and embeddings
  </Card>
</CardGroup>