AI Sonar Provider Setup

This guide is for self-hosted OpenClaw users who want to connect AI Sonar as their AI provider.

Recommended: install the plugin

For standard OpenClaw agent execution, install the AI Sonar provider plugin:

openclaw plugins install @aisonarai/openclaw-provider
openclaw onboard --aisonar-api-key "$API_KEY"

The plugin discovers AI Sonar’s live chat-model catalog and keeps 18 fallback models for offline discovery. Models use the aisonar/<model-id> format. npm package · ClawHub listing · Source code

Manual provider configuration

Use manual models.providers entries when you explicitly need separate Responses API, Claude native, Gemini native, or MiniMax native routes. If you choose manual configuration, configuring aisonar alone is enough. Add the other providers only when you explicitly need Responses API, Claude native, Gemini native, or MiniMax native behavior.

Provider	OpenClaw `api`	Best for	baseUrl
`aisonar`	`openai-completions`	GPT, DeepSeek, Qwen, and most OpenAI-compatible calls	`https://api.aisonar.dev/v1`
`aisonar-responses`	`openai-responses`	OpenAI Responses workflows that expect `/v1/responses` semantics	`https://api.aisonar.dev/v1`
`aisonar-claude`	`anthropic-messages`	Native Claude Messages API	`https://api.aisonar.dev`
`aisonar-gemini`	`google-generative-ai`	Native Gemini API format	`https://api.aisonar.dev`
`aisonar-minimax`	`anthropic-messages`	Native MiniMax routing	`https://api.aisonar.dev`

Use the /v1 suffix only for openai-completions and openai-responses.Native providers such as anthropic-messages and google-generative-ai should use https://api.aisonar.dev without /v1, otherwise OpenClaw may construct the wrong provider path.

Prerequisites

A self-hosted OpenClaw instance
An API key — Get one here

Configuration

Edit your OpenClaw config:

Self-hosted: ~/.openclaw/openclaw.json

Add AI Sonar providers under models.providers:

{
  agents: {
    defaults: {
      model: {
        primary: "aisonar-claude/claude-sonnet-4-6"
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      aisonar: {
        api: "openai-completions",
        baseUrl: "https://api.aisonar.dev/v1",
        apiKey: "sk-your-api-key",
        models: [
          { id: "gpt-4o", name: "GPT-4o" },
          { id: "deepseek-r1", name: "DeepSeek R1" },
          { id: "qwen3-coder-flash", name: "Qwen 3 Coder Flash" }
        ]
      },
      "aisonar-responses": {
        api: "openai-responses",
        baseUrl: "https://api.aisonar.dev/v1",
        apiKey: "sk-your-api-key",
        models: [
          { id: "gpt-4o", name: "GPT-4o (Responses)" },
          { id: "gpt-5.2", name: "GPT-5.2 (Responses)" }
        ]
      },
      "aisonar-claude": {
        api: "anthropic-messages",
        baseUrl: "https://api.aisonar.dev",
        apiKey: "sk-your-api-key",
        models: [
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
          { id: "claude-opus-4-6", name: "Claude Opus 4.6" }
        ]
      },
      "aisonar-gemini": {
        api: "google-generative-ai",
        baseUrl: "https://api.aisonar.dev",
        apiKey: "sk-your-api-key",
        models: [
          { id: "gemini-3.5-flash", name: "Gemini 3.5 Flash" },
          { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" }
        ]
      },
      "aisonar-minimax": {
        api: "anthropic-messages",
        baseUrl: "https://api.aisonar.dev",
        apiKey: "sk-your-api-key",
        models: [
          { id: "minimax-m3", name: "MiniMax M3" }
        ]
      }
    }
  }
}

All 5 providers use the same API Key. You only need one AI Sonar account.

The models arrays above only show common examples. Add more model IDs to each provider as needed.

Using Models

OpenClaw still references models with the provider/model format:

{
  agents: {
    defaults: {
      model: {
        primary: "aisonar-gemini/gemini-3.5-flash"
      }
    }
  }
}

Model Examples

Provider	Model reference	Description
`aisonar`	`aisonar/gpt-4o`	OpenAI-compatible route
`aisonar`	`aisonar/deepseek-r1`	DeepSeek reasoning model
`aisonar-responses`	`aisonar-responses/gpt-4o`	Responses API route
`aisonar-claude`	`aisonar-claude/claude-sonnet-4-6`	Native Claude Messages route
`aisonar-gemini`	`aisonar-gemini/gemini-3.5-flash`	Native Gemini route
`aisonar-minimax`	`aisonar-minimax/minimax-m3`	Native MiniMax route

Browse all available models at aisonar.dev/models.

When to Use Which Provider

aisonar: default choice for most general-purpose agent and chat use cases.
aisonar-responses: use when your OpenClaw workflow explicitly depends on OpenAI Responses semantics.
aisonar-claude: use when you want Claude’s native Messages behavior.
aisonar-gemini: use when you want Gemini-native request/response formatting or existing Gemini-style integrations.
aisonar-minimax: use when you want MiniMax on its native route.

If you do not need Gemini-native behavior, you can still call Gemini models through aisonar/gemini-* on the OpenAI-compatible route.

Common Mistakes

Still using the old top-level providers array

Current OpenClaw docs use models.providers. If you keep the older top-level providers array format, OpenClaw may ignore the config or fail to resolve the provider prefixes as expected.

Forgetting /v1 on aisonar-responses

openai-responses maps to AI Sonar’s /v1/responses path, so aisonar-responses must use https://api.aisonar.dev/v1.

Adding /v1 to aisonar-claude, aisonar-gemini, or aisonar-minimax

anthropic-messages and google-generative-ai should use https://api.aisonar.dev without /v1. Adding /v1 can produce incorrect request paths.

Does OpenClaw still support native Gemini?

Yes. Current OpenClaw documentation still includes the built-in google provider and also supports custom providers using api: "google-generative-ai". So aisonar-gemini remains a valid native Gemini route for OpenClaw users.

Verify Setup

After saving the config, restart your OpenClaw instance and test with a simple message. If you see a response, the provider is configured correctly.

# Self-hosted: restart the service
systemctl --user restart openclaw    # Linux
# macOS: restart the OpenClaw app or its configured launch service

Next Steps

Once OpenClaw is connected, these guides help you use AI Sonar more effectively:

API Formats — understand the differences between OpenAI, Responses, Anthropic, and Gemini routes
IDE / SDK Compatibility — see when /v1/responses is the better fit
Error Handling — learn common failure modes and recovery patterns
Models Overview — browse model IDs before wiring them into agents

Compatibility Matrix

Coding Tools

Native SDKs

Frameworks & Platforms

Chat Apps

AI Sonar Provider Setup

Recommended: install the plugin

Manual provider configuration

Prerequisites

Configuration

Using Models

Model Examples

When to Use Which Provider

Common Mistakes

Verify Setup

Next Steps

​Recommended: install the plugin

​Manual provider configuration

​Prerequisites

​Configuration

​Using Models

​Model Examples

​When to Use Which Provider

​Common Mistakes

​Verify Setup

​Next Steps

Recommended: install the plugin

Manual provider configuration

Prerequisites

Configuration

Using Models

Model Examples

When to Use Which Provider

Common Mistakes

Verify Setup

Next Steps