Can I use OpenClaw with local models through Ollama?

Yes, OpenClaw works with Ollama out of the box. Install Ollama, pull a model (e.g., ollama pull deepseek-coder-v2), and configure OpenClaw to point to http://localhost:11434/v1 as the base URL. Local models are free to run but require significant GPU memory for good performance.

How do I configure fallback models in OpenClaw?

In your models.yaml file, define a primary model, a fallback model, and optionally an economy model. OpenClaw automatically uses the fallback when the primary model is unavailable or returns errors. The economy model is used for simple tasks like file summaries to save costs.

Why is OpenClaw ignoring my configuration changes?

The most common causes are: YAML syntax errors (check indentation with a YAML linter), editing the wrong config file (OpenClaw checks ~/.openclaw/config.yaml, not the project-level config), or environment variables overriding your config (OPENCLAW_MODEL and OPENCLAW_API_KEY take precedence over config files).

What models work best with OpenClaw?

For coding tasks, Claude Sonnet 4.6 and GPT-4o offer the best balance of quality, speed, and cost. For complex architectural decisions, Claude Opus 4.6 or GPT-5.4 are worth the higher cost. For quick edits and simple questions, Claude Haiku 3.5 or GPT-4o-mini perform well at a fraction of the cost.

How do I troubleshoot connection errors in OpenClaw?

Run openclaw doctor to check your configuration. Common fixes: verify your API key is valid (not expired or revoked), check that the base_url matches your provider (do not mix OpenAI keys with Anthropic endpoints), ensure your network allows HTTPS connections to the provider, and check that you have not exceeded your billing quota.

OpenClaw API Setup & Model Configuration Guide (2026)

TL;DR

OpenClaw is an open-source AI agent framework that runs in your terminal. This guide walks you through every aspect of configuring it: from the initial openclaw onboard setup to advanced multi-model routing with fallback chains. You will learn how to connect OpenClaw to any API provider — direct (OpenAI, Anthropic, Google), aggregation platforms (Ofox, OpenRouter, Together AI), or local (Ollama) — and optimize your configuration for cost, speed, and reliability.

What Is OpenClaw and Why API Configuration Matters

OpenClaw is an open-source command-line AI agent designed for software developers. Think of it as an AI pair programmer that lives in your terminal — it can read your codebase, write and edit files, run commands, and reason about complex engineering problems. It launched in early 2026 and has quickly gained traction among developers who want the power of AI coding assistants without vendor lock-in.

Unlike hosted AI coding tools that bundle their own models, OpenClaw is a framework. It provides the agent logic — tool use, context management, multi-step reasoning, code editing — but relies on external LLM APIs for the underlying intelligence. This architecture means that your choice of API provider and model directly determines OpenClaw’s capability, speed, and cost.

A poorly configured OpenClaw setup leads to slow responses, unnecessary expense, or outright failures when your provider has issues. A well-configured setup gives you fast, reliable AI assistance that automatically adapts to provider outages, uses cheap models for simple tasks, and reserves expensive models for complex reasoning.

This guide covers everything you need to get OpenClaw’s API configuration right.

Quick Start: The `openclaw onboard` Walkthrough

If you are installing OpenClaw for the first time, the onboarding wizard handles the basic setup:

# Install OpenClaw
npm install -g @openclaw/cli

# Run the onboarding wizard
openclaw onboard

The wizard walks you through four steps:

Step 1: Choose a provider. You will see a list of supported providers. The simplest path is to choose your primary provider here (OpenAI or Anthropic are the most common starting points).

? Select your AI provider:
  ❯ Anthropic (Claude)
    OpenAI (GPT)
    Google (Gemini)
    Custom OpenAI-compatible endpoint
    Local model (Ollama)

Step 2: Enter your API key. Paste your API key. OpenClaw validates it immediately by making a test request.

? Enter your Anthropic API key: sk-ant-••••••••••••••••
✓ API key validated successfully

Step 3: Select your default model. OpenClaw suggests a default model based on your provider. You can change this later.

? Select your default model:
  ❯ claude-sonnet-4.6 (recommended — best quality/cost balance)
    claude-opus-4.6 (highest quality, higher cost)
    claude-haiku-3-5 (fastest, lowest cost)

Step 4: Configuration saved. OpenClaw writes your configuration to ~/.openclaw/config.yaml.

✓ Configuration saved to ~/.openclaw/config.yaml
✓ OpenClaw is ready! Run 'openclaw' in any project directory to start.

This gets you a working setup, but there is much more to configure for a production-grade experience.

Configuration File Structure

OpenClaw uses two main configuration files, both in YAML format:

~/.openclaw/
├── config.yaml      # Global settings, default provider, preferences
├── models.yaml      # Model definitions, fallback chains, routing rules
├── search.yaml      # Search provider configuration
└── usage/           # Local usage tracking data
    └── 2026-03.json

Project-level overrides can be placed in .openclaw/config.yaml within any project directory. Project configs are merged on top of the global config.

config.yaml: Global Settings

# ~/.openclaw/config.yaml

# Default provider and model
provider: anthropic
model: claude-sonnet-4.6

# API credentials (can also use environment variables)
providers:
  anthropic:
    api_key: sk-ant-your-key-here
    base_url: https://api.anthropic.com/v1

  openai:
    api_key: sk-your-openai-key-here
    base_url: https://api.openai.com/v1

# Agent behavior
agent:
  # Maximum tokens per response
  max_tokens: 4096

  # Temperature for generation (0.0 = deterministic, 1.0 = creative)
  temperature: 0.3

  # Maximum context window usage (percentage)
  max_context_usage: 0.8

  # Auto-approve file edits without confirmation
  auto_approve: false

  # Number of retries on API failure
  max_retries: 3

# Output preferences
output:
  # Show token usage after each response
  show_usage: true

  # Show cost estimate after each response
  show_cost: true

  # Theme: dark, light, or auto
  theme: auto

# Logging
logging:
  level: info  # debug, info, warn, error
  file: ~/.openclaw/logs/openclaw.log

models.yaml: Model Definitions and Routing

This file defines which models are available and how OpenClaw selects between them:

# ~/.openclaw/models.yaml

# Model tiers — OpenClaw selects the appropriate tier based on task complexity
tiers:
  # Primary: used for most tasks (code generation, complex reasoning)
  primary:
    provider: anthropic
    model: claude-sonnet-4.6
    max_tokens: 8192
    temperature: 0.3

  # Fallback: used when primary is unavailable
  fallback:
    provider: openai
    model: gpt-4o
    max_tokens: 4096
    temperature: 0.3

  # Economy: used for simple tasks (file summaries, quick lookups)
  economy:
    provider: anthropic
    model: claude-haiku-3-5
    max_tokens: 2048
    temperature: 0.2

# Task-to-tier routing
routing:
  # Tasks that should use the primary model
  primary_tasks:
    - code_generation
    - architecture_review
    - bug_analysis
    - complex_refactor

  # Tasks that can use the economy model
  economy_tasks:
    - file_summary
    - simple_question
    - format_check
    - git_message

  # Fallback is automatic — used when the active tier's provider fails

API Provider Options: Choosing the Right Setup

OpenClaw supports any endpoint that implements the OpenAI chat completions API format. This gives you a wide range of options.

Direct Provider APIs

The most straightforward approach is connecting directly to model providers.

Anthropic (Claude)

providers:
  anthropic:
    api_key: sk-ant-your-key-here
    base_url: https://api.anthropic.com/v1