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:

# Quick setup with API key
nullclaw onboard --api-key sk-... --provider openrouter

# Interactive wizard
nullclaw onboard --interactive

Supported Providers

OpenRouter

Access to 200+ models via single API

Anthropic

Claude models (Opus, Sonnet, Haiku)

OpenAI

GPT-4, GPT-3.5, and embeddings

Groq

Fast inference for Llama, Mixtral

Ollama

Local models (no API key needed)

Google Gemini

Gemini Pro and Flash models

Configuration

OpenRouter (Recommended)

Access 200+ models through a single API:

config.json

{
  "models": {
    "providers": {
      "openrouter": {
        "api_key": "sk-or-v1-..."
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    }
  }
}

1. Get API Key

   Sign up at openrouter.ai and create an API key

2. Add to Config

   Place your key in ~/.nullclaw/config.json under models.providers.openrouter.api_key

3. Select Model

   Use format openrouter/<provider>/<model> (e.g., openrouter/anthropic/claude-sonnet-4)

Anthropic Claude

Direct access to Claude models:

config.json

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

config.json

{
  "models": {
    "providers": {
      "openai": {
        "api_key": "sk-..."
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "gpt-4"
      }
    }
  }
}

Groq

Fast inference for open models:

config.json

{
  "models": {
    "providers": {
      "groq": {
        "api_key": "gsk_..."
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "llama-3.1-70b"
      }
    }
  }
}

Ollama (Local)

Run models locally without API keys:

config.json

{
  "models": {
    "providers": {
      "ollama": {
        "base_url": "http://localhost:11434"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "llama3.1:8b"
      }
    }
  }
}

Ollama doesn’t require an API key. Install models with ollama pull llama3.1:8b

Model Selection

Primary Model

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

OpenRouter

"agents": {
  "defaults": {
    "model": {
      "primary": "openrouter/anthropic/claude-sonnet-4"
    }
  }
}

"agents": {
  "defaults": {
    "model": {
      "primary": "claude-sonnet-4"
    }
  }
}

"agents": {
  "defaults": {
    "model": {
      "primary": "llama3.1:8b"
    }
  }
}

Per-Agent Models

Different agents can use different models:

config.json

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

config.json

{
  "models": {
    "providers": {
      "custom": {
        "api_key": "your-key",
        "base_url": "https://your-api.com/v1"
      }
    }
  }
}

Temperature Control

Control response randomness globally or per-model:

config.json

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

config.json

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

# Check your config
cat ~/.nullclaw/config.json | grep api_key

# Re-run onboarding
nullclaw onboard --interactive

Provider Not Working

# 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

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

{
  "secrets": {
    "encrypt": true
  }
}

Next Steps

Configure Channels

Connect Telegram, Discord, or other channels

Memory Setup

Configure vector search and embeddings