Why does OpenClaw say "Model not allowed" or "Unknown model"?

Clawpedia · For Humans

Fix model-related errors by verifying your model configuration, API keys, and provider compatibility.

Why Does OpenClaw Say "Model Not Allowed" or "Unknown Model"?

These error messages appear when OpenClaw cannot use the language model you have configured. This guide explains every scenario and how to fix it.

Understanding the Error Messages

Cause 1: Incorrect Model Name

Model identifiers must match exactly, including version suffixes:

# ❌ Common mistakes
models:
  primary:
    model: gpt4              # Missing hyphen
    model: gpt-4-turbo       # Outdated name
    model: claude-3           # Missing variant
    model: llama3             # Missing hyphen and size

# ✅ Correct identifiers
models:
  primary:
    model: gpt-4             # Correct
    model: gpt-4o            # Correct
    model: claude-3-sonnet   # Correct with variant
    model: llama-3-70b       # Correct with size

# List all supported models
openclaw models list

# Output:
# PROVIDER    MODEL               CONTEXT   STATUS
# openai      gpt-4o              128K      ✅ available
# openai      gpt-4o-mini         128K      ✅ available
# anthropic   claude-3-sonnet     200K      ✅ available
# anthropic   claude-3-haiku      200K      ✅ available
# local       llama-3-8b          8K        ✅ available
# local       llama-3-70b         8K        ❌ not downloaded
# google      gemini-1.5-pro      1M        ✅ available

# Search for a specific model
openclaw models search "gpt"

Cause 2: Missing or Invalid API Key

API-based models require valid credentials:

# Check API key status
openclaw auth status

# Output:
# Provider: openai
# API Key:  sk-...7x3Q (configured)
# Status:   ❌ Invalid (expired or revoked)
# Quota:    Unable to check

# Update API key
openclaw auth set openai --key sk-your-new-key

# Verify the key works
openclaw auth verify openai
# Output: ✅ API key valid (org: my-org, tier: pay-as-you-go)

Cause 3: Account Tier Restrictions

Some models are only available on certain subscription tiers:

# Check your account tier
openclaw auth info openai

# Output:
# Organization: my-org
# Tier:         free
# Models allowed:
#   ✅ gpt-4o-mini
#   ❌ gpt-4o (requires pay-as-you-go)
#   ❌ gpt-4 (requires tier 1+)

Solution: Upgrade your API account tier or switch to an allowed model.

Cause 4: Local Model Not Downloaded

Local models must be downloaded before use:

# Check local model status
openclaw models local list

# Output:
# MODEL           SIZE      STATUS
# llama-3-8b      4.7 GB    ✅ ready
# llama-3-70b     40 GB     ❌ not downloaded
# mistral-7b      4.1 GB    ⚠️ outdated (v0.2 → v0.3 available)

# Download a model
openclaw models download llama-3-70b

# Update an outdated model
openclaw models update mistral-7b

Cause 5: Provider Not Configured

The provider for the requested model may not be set up:

# Check configured providers
openclaw providers list

# Output:
# PROVIDER     STATUS
# openai       ✅ configured
# anthropic    ❌ not configured
# local        ✅ configured (ollama)
# google       ❌ not configured

# Configure a new provider
openclaw providers add anthropic --key sk-ant-your-key

Cause 6: Model Deprecated or Renamed

AI providers regularly deprecate and rename models:

# Check for deprecated model warnings
openclaw doctor --check models

# Output:
# ⚠️ Model "gpt-4-turbo-preview" is deprecated
#    Suggested replacement: "gpt-4o"
#    Deprecation date: 2024-06-01
#    Auto-migrate: openclaw models migrate

# Auto-migrate to recommended replacements
openclaw models migrate --dry-run    # Preview changes
openclaw models migrate              # Apply changes

Cause 7: Ollama Not Running (Local Models)

If using local models via Ollama:

# Check if Ollama is running
openclaw providers status local

# Output:
# Backend:    Ollama
# Status:     ❌ Not running
# Expected:   http://localhost:11434

# Start Ollama
ollama serve &

# Verify connection
openclaw providers status local
# Output: ✅ Connected to Ollama (3 models available)

Quick Fix Flowchart

• Run openclaw models list — is your model in the list?
• No → Check spelling, run openclaw models search
• Yes but ❌ → Check if it needs download, API key, or tier upgrade
• Yes and ✅ → Run openclaw auth verify <provider> to check credentials
• Still failing → Run openclaw diagnose --include-model-check for a full report

Configuration Example

A robust model configuration with fallbacks:

models:
  primary:
    provider: openai
    model: gpt-4o
  fallback:
    provider: local
    model: llama-3-8b
    enabled: true
  validation:
    check_on_startup: true
    warn_deprecated: true
    auto_migrate: false