Provedores de modelos

Referência para provedores de LLM/modelo (não canais de chat como WhatsApp/Telegram). Para regras de seleção de modelos, consulte Modelos.

# Regras rápidas

# Comportamento de provedor pertencente ao Plugin

A maior parte da lógica específica de provedor vive em Plugins de provedor (registerProvider(...)), enquanto o OpenClaw mantém o loop genérico de inferência. Plugins são donos de onboarding, catálogos de modelos, mapeamento de variáveis de ambiente de autenticação, normalização de transporte/configuração, limpeza de schema de ferramentas, classificação de failover, refresh de OAuth, relatórios de uso, perfis de pensamento/raciocínio e mais.

A lista completa de hooks do SDK de provedor e exemplos de Plugins incluídos fica em Plugins de provedor. Um provedor que precisa de um executor de requisição totalmente personalizado é uma superfície de extensão separada e mais profunda.

# Rotação de chaves de API

# Provedores integrados (catálogo pi-ai)

O OpenClaw é distribuído com o catálogo pi-ai. Estes provedores não exigem configuração de models.providers; basta definir a autenticação e escolher um modelo.

# OpenAI

• Provedor: openai
• Autenticação: OPENAI_API_KEY
• Rotação opcional: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, mais OPENCLAW_LIVE_OPENAI_KEY (substituição única)
• Modelos de exemplo: openai/gpt-5.5, openai/gpt-5.4-mini
• Verifique a disponibilidade da conta/modelo com openclaw models list --provider openai se uma instalação ou chave de API específica se comportar de forma diferente.
• CLI: openclaw onboard --auth-choice openai-api-key
• O transporte padrão é auto (WebSocket primeiro, fallback para SSE)
• Substitua por modelo via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" ou "auto")
• O aquecimento de WebSocket de Responses da OpenAI vem habilitado por padrão via params.openaiWsWarmup (true/false)
• O processamento prioritário da OpenAI pode ser habilitado via agents.defaults.models["openai/<model>"].params.serviceTier
• /fast e params.fastMode mapeiam requisições diretas de Responses openai/* para service_tier=priority em api.openai.com
• Use params.serviceTier quando quiser um tier explícito em vez do toggle compartilhado /fast
• Cabeçalhos ocultos de atribuição do OpenClaw (originator, version, User-Agent) se aplicam apenas ao tráfego nativo da OpenAI para api.openai.com, não a proxies genéricos compatíveis com OpenAI
• Rotas nativas da OpenAI também mantêm store de Responses, dicas de cache de prompt e formatação de payload compatível com raciocínio da OpenAI; rotas de proxy não
• openai/gpt-5.3-codex-spark é suprimido intencionalmente no OpenClaw porque requisições live da API da OpenAI o rejeitam e o catálogo atual do Codex não o expõe

{
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

# Anthropic

• Provedor: anthropic
• Autenticação: ANTHROPIC_API_KEY
• Rotação opcional: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, mais OPENCLAW_LIVE_ANTHROPIC_KEY (substituição única)
• Modelo de exemplo: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Requisições públicas diretas da Anthropic aceitam o toggle compartilhado /fast e params.fastMode, incluindo tráfego por chave de API e autenticado por OAuth enviado para api.anthropic.com; o OpenClaw mapeia isso para service_tier da Anthropic (auto vs standard_only)
• A configuração preferida da Claude CLI mantém a ref de modelo canônica e seleciona o backend de CLI separadamente: anthropic/claude-opus-4-7 com agents.defaults.agentRuntime.id: "claude-cli". Refs legadas claude-cli/claude-opus-4-7 ainda funcionam por compatibilidade.

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

# OAuth do OpenAI Codex

• Provedor: openai-codex
• Autenticação: OAuth (ChatGPT)
• Ref de modelo do PI: openai-codex/gpt-5.5
• Ref do harness nativo do servidor de aplicativo Codex: openai/gpt-5.5 com agents.defaults.agentRuntime.id: "codex"
• Documentação do harness nativo do servidor de aplicativo Codex: Harness do Codex
• Refs de modelo legadas: codex/gpt-*
• Limite do Plugin: openai-codex/* carrega o Plugin da OpenAI; o Plugin nativo do servidor de aplicativo Codex é selecionado apenas pelo runtime do harness do Codex ou por refs legadas codex/*.
• CLI: openclaw onboard --auth-choice openai-codex ou openclaw models auth login --provider openai-codex
• O transporte padrão é auto (WebSocket primeiro, fallback para SSE)
• Substitua por modelo do PI via agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket" ou "auto")
• params.serviceTier também é encaminhado em requisições nativas de Responses do Codex (chatgpt.com/backend-api)
• Cabeçalhos ocultos de atribuição do OpenClaw (originator, version, User-Agent) são anexados apenas ao tráfego nativo do Codex para chatgpt.com/backend-api, não a proxies genéricos compatíveis com OpenAI
• Compartilha o mesmo toggle /fast e a configuração params.fastMode que openai/* direto; o OpenClaw mapeia isso para service_tier=priority
• openai-codex/gpt-5.5 usa contextWindow = 400000 nativo do catálogo do Codex e o runtime padrão contextTokens = 272000; substitua o limite de runtime com models.providers.openai-codex.models[].contextTokens
• Nota de política: OAuth do OpenAI Codex é explicitamente compatível com ferramentas/fluxos de trabalho externos como o OpenClaw.
• Para a rota comum de assinatura mais runtime nativo do Codex, entre com autenticação openai-codex, mas configure openai/gpt-5.5 mais agents.defaults.agentRuntime.id: "codex".
• Use openai-codex/gpt-5.5 apenas quando quiser a rota OAuth/assinatura do Codex pelo PI; use openai/gpt-5.5 sem a substituição de runtime do Codex quando sua configuração por chave de API e catálogo local expuserem a rota de API pública.
• Refs mais antigas openai-codex/gpt-5.1*, openai-codex/gpt-5.2* e openai-codex/gpt-5.3* são suprimidas porque contas OAuth do ChatGPT/Codex as rejeitam; use openai-codex/gpt-5.5 ou a rota de runtime nativo do Codex em vez disso.

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      agentRuntime: { id: "codex" },
    },
  },
}

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

# Outras opções hospedadas no estilo de assinatura

# OpenCode

• Autenticação: OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY)
• Provedor do runtime Zen: opencode
• Provedor do runtime Go: opencode-go
• Modelos de exemplo: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen ou openclaw onboard --auth-choice opencode-go

{
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

# Google Gemini (chave de API)

• Provedor: google
• Autenticação: GEMINI_API_KEY
• Rotação opcional: fallback de GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, GOOGLE_API_KEY e OPENCLAW_LIVE_GEMINI_KEY (substituição única)
• Modelos de exemplo: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Compatibilidade: a configuração legada do OpenClaw usando google/gemini-3.1-flash-preview é normalizada para google/gemini-3-flash-preview
• Alias: google/gemini-3.1-pro é aceito e normalizado para o id ativo da API Gemini do Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Pensamento: /think adaptive usa o pensamento dinâmico do Google. Gemini 3/3.1 omite um thinkingLevel fixo; Gemini 2.5 envia thinkingBudget: -1.
• Execuções diretas do Gemini também aceitam agents.defaults.models["google/<model>"].params.cachedContent (ou o legado cached_content) para encaminhar um identificador nativo do provedor cachedContents/...; acertos de cache do Gemini aparecem como OpenClaw cacheRead

# Google Vertex e Gemini CLI

• Provedores: google-vertex, google-gemini-cli
• Autenticação: Vertex usa gcloud ADC; Gemini CLI usa seu fluxo OAuth

O OAuth do Gemini CLI é distribuído como parte do plugin google incluído no pacote.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

As respostas JSON do Gemini CLI são analisadas a partir de response; o uso recorre a stats, com stats.cached normalizado para OpenClaw cacheRead.

# Z.AI (GLM)

• Provedor: zai
• Autenticação: ZAI_API_KEY
• Modelo de exemplo: zai/glm-5.1
• CLI: openclaw onboard --auth-choice zai-api-key
  • Aliases: z.ai/* e z-ai/* são normalizados para zai/*
  • zai-api-key detecta automaticamente o endpoint Z.AI correspondente; zai-coding-global, zai-coding-cn, zai-global e zai-cn forçam uma superfície específica

# Vercel AI Gateway

• Provedor: vercel-ai-gateway
• Autenticação: AI_GATEWAY_API_KEY
• Modelos de exemplo: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

# Kilo Gateway

• Provedor: kilocode
• Autenticação: KILOCODE_API_KEY
• Modelo de exemplo: kilocode/kilo/auto
• CLI: openclaw onboard --auth-choice kilocode-api-key
• URL base: https://api.kilo.ai/api/gateway/
• O catálogo de fallback estático inclui kilocode/kilo/auto; a descoberta ativa em https://api.kilo.ai/api/gateway/models pode expandir ainda mais o catálogo em tempo de execução.
• O roteamento upstream exato por trás de kilocode/kilo/auto é de responsabilidade do Kilo Gateway, não codificado diretamente no OpenClaw.

Consulte /providers/kilocode para detalhes de configuração.

# Outros plugins de provedores incluídos no pacote

# Particularidades que vale conhecer

# Provedores via models.providers (URL personalizada/base)

Use models.providers (ou models.json) para adicionar provedores personalizados ou proxies compatíveis com OpenAI/Anthropic.

Muitos dos Plugins provedores incluídos abaixo já publicam um catálogo padrão. Use entradas explícitas models.providers.<id> somente quando quiser substituir a URL base, os cabeçalhos ou a lista de modelos padrão.

As verificações de capacidade de modelo do Gateway também leem metadados explícitos de models.providers.<id>.models[]. Se um modelo personalizado ou de proxy aceita imagens, defina input: ["text", "image"] nesse modelo para que o WebChat e os caminhos de anexo originados em nó passem imagens como entradas nativas do modelo em vez de referências de mídia somente texto.

# Moonshot AI (Kimi)

Moonshot é distribuído como um Plugin provedor incluído. Use o provedor integrado por padrão e adicione uma entrada explícita models.providers.moonshot somente quando precisar substituir a URL base ou os metadados do modelo:

• Provedor: moonshot
• Autenticação: MOONSHOT_API_KEY
• Modelo de exemplo: moonshot/kimi-k2.6
• CLI: openclaw onboard --auth-choice moonshot-api-key ou openclaw onboard --auth-choice moonshot-api-key-cn

IDs de modelo Kimi K2:

• moonshot/kimi-k2.6
• moonshot/kimi-k2.5
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo
• moonshot/kimi-k2-turbo

{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.6" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],
      },
    },
  },
}

# Codificação com Kimi

Kimi Coding usa o endpoint compatível com Anthropic da Moonshot AI:

• Provedor: kimi
• Autenticação: KIMI_API_KEY
• Modelo de exemplo: kimi/kimi-code

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi/kimi-code" } },
  },
}

O kimi/k2p5 legado continua aceito como um ID de modelo de compatibilidade.

# Volcano Engine (Doubao)

Volcano Engine (火山引擎) fornece acesso ao Doubao e outros modelos na China.

• Provedor: volcengine (codificação: volcengine-plan)
• Autenticação: VOLCANO_ENGINE_API_KEY
• Modelo de exemplo: volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}

A integração inicial usa a superfície de codificação por padrão, mas o catálogo geral volcengine/* é registrado ao mesmo tempo.

Nos seletores de modelo de integração inicial/configuração, a opção de autenticação Volcengine prefere linhas volcengine/* e volcengine-plan/*. Se esses modelos ainda não tiverem sido carregados, o OpenClaw recorre ao catálogo sem filtro em vez de mostrar um seletor vazio limitado ao provedor.

# BytePlus (Internacional)

BytePlus ARK fornece acesso aos mesmos modelos do Volcano Engine para usuários internacionais.

• Provedor: byteplus (codificação: byteplus-plan)
• Autenticação: BYTEPLUS_API_KEY
• Modelo de exemplo: byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

A integração inicial usa a superfície de codificação por padrão, mas o catálogo geral byteplus/* é registrado ao mesmo tempo.

Nos seletores de modelo de integração inicial/configuração, a opção de autenticação BytePlus prefere linhas byteplus/* e byteplus-plan/*. Se esses modelos ainda não tiverem sido carregados, o OpenClaw recorre ao catálogo sem filtro em vez de mostrar um seletor vazio limitado ao provedor.

# Synthetic

Synthetic fornece modelos compatíveis com Anthropic por trás do provedor synthetic:

• Provedor: synthetic
• Autenticação: SYNTHETIC_API_KEY
• Modelo de exemplo: synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI: openclaw onboard --auth-choice synthetic-api-key

{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" }],
      },
    },
  },
}

# MiniMax

MiniMax é configurado via models.providers porque usa endpoints personalizados:

• MiniMax OAuth (global): --auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• Chave de API MiniMax (global): --auth-choice minimax-global-api
• Chave de API MiniMax (CN): --auth-choice minimax-cn-api
• Autenticação: MINIMAX_API_KEY para minimax; MINIMAX_OAUTH_TOKEN ou MINIMAX_API_KEY para minimax-portal

Consulte /providers/minimax para detalhes de configuração, opções de modelo e trechos de configuração.

Divisão de capacidades pertencente ao Plugin:

• Os padrões de texto/chat permanecem em minimax/MiniMax-M2.7
• A geração de imagens é minimax/image-01 ou minimax-portal/image-01
• A compreensão de imagens pertence ao Plugin MiniMax-VL-01 em ambos os caminhos de autenticação MiniMax
• A busca na Web permanece no ID de provedor minimax

# LM Studio

LM Studio é distribuído como um Plugin de provedor incluído que usa a API nativa:

• Provedor: lmstudio
• Autenticação: LM_API_TOKEN
• URL base de inferência padrão: http://localhost:1234/v1

Em seguida, defina um modelo (substitua por um dos IDs retornados por http://localhost:1234/api/v1/models):

{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}

O OpenClaw usa os endpoints nativos /api/v1/models e /api/v1/models/load do LM Studio para descoberta + carregamento automático, com /v1/chat/completions para inferência por padrão. Se você quiser que o carregamento JIT, TTL e despejo automático do LM Studio controlem o ciclo de vida do modelo, defina models.providers.lmstudio.params.preload: false. Consulte /providers/lmstudio para configuração e solução de problemas.

# Ollama

Ollama é distribuído como um Plugin de provedor incluído e usa a API nativa do Ollama:

• Provedor: ollama
• Autenticação: nenhuma necessária (servidor local)
• Modelo de exemplo: ollama/llama3.3
• Instalação: https://ollama.com/download

# Install Ollama, then pull a model:
ollama pull llama3.3

{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

O Ollama é detectado localmente em http://127.0.0.1:11434 quando você aceita usar OLLAMA_API_KEY, e o Plugin de provedor incluído adiciona o Ollama diretamente ao openclaw onboard e ao seletor de modelo. Consulte /providers/ollama para integração inicial, modo em nuvem/local e configuração personalizada.

# vLLM

vLLM é distribuído como um Plugin de provedor incluído para servidores locais/auto-hospedados compatíveis com OpenAI:

• Provedor: vllm
• Autenticação: opcional (depende do seu servidor)
• URL base padrão: http://127.0.0.1:8000/v1

Para aceitar a descoberta automática localmente (qualquer valor funciona se o servidor não exigir autenticação):

export VLLM_API_KEY="vllm-local"

Em seguida, defina um modelo (substitua por um dos IDs retornados por /v1/models):

{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

Consulte /providers/vllm para detalhes.

# SGLang

SGLang é distribuído como um Plugin de provedor incluído para servidores rápidos auto-hospedados compatíveis com OpenAI:

• Provedor: sglang
• Autenticação: opcional (depende do seu servidor)
• URL base padrão: http://127.0.0.1:30000/v1

Para aceitar a descoberta automática localmente (qualquer valor funciona se o servidor não exigir autenticação):

export SGLANG_API_KEY="sglang-local"

Em seguida, defina um modelo (substitua por um dos IDs retornados por /v1/models):

{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

Consulte /providers/sglang para detalhes.

# Proxies locais (LM Studio, vLLM, LiteLLM etc.)

Exemplo (compatível com OpenAI):

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

# Exemplos de CLI

openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

Veja também: Configuração para exemplos completos de configuração.

# Relacionados

• Referência de configuração - chaves de configuração de modelo
• Failover de modelo - cadeias de fallback e comportamento de repetição
• Modelos - configuração de modelo e aliases
• Provedores - guias de configuração por provedor