Provedores de modelos

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

Regras rápidas

Comportamento do provedor controlado pelo Plugin

A maior parte da lógica específica de cada provedor fica nos plugins de provedor (registerProvider(...)), enquanto o OpenClaw mantém o loop genérico de inferência. Os plugins controlam a integração inicial, os catálogos de modelos, o mapeamento de variáveis de ambiente de autenticação, a normalização de transporte/configuração, a limpeza de esquemas de ferramentas, a classificação de failover, a atualização de OAuth, os relatórios de uso, os perfis de pensamento/raciocínio e muito mais.

A lista completa de hooks do SDK de provedores e exemplos de plugins integrados está em Plugins de provedor. Um provedor que precise de um executor de solicitações totalmente personalizado constitui uma superfície de extensão separada e mais profunda.

Rotação de chaves de API

Plugins oficiais de provedores

Os plugins oficiais de provedores publicam suas próprias entradas no catálogo de modelos. Esses provedores não exigem entradas de modelo em models.providers; ative o Plugin do provedor, defina a autenticação e escolha um modelo. Use models.providers apenas para provedores personalizados explícitos ou configurações específicas de solicitação, como tempos limite.

OpenAI

• Provedor: openai
• Autenticação: OPENAI_API_KEY
• Rotação opcional: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, além de OPENCLAW_LIVE_OPENAI_KEY (substituição única)
• Padrão da configuração inicial: openai/gpt-5.6; na API direta, o id simples é resolvido como Sol.
• Exemplos de modelos: openai/gpt-5.6, openai/gpt-5.6-terra, openai/gpt-5.6-luna, openai/gpt-5.5
• Verifique a disponibilidade da conta/do modelo com openclaw models list --provider openai caso uma instalação ou chave de API específica se comporte de maneira diferente.
• CLI: openclaw onboard --auth-choice openai-api-key
• O transporte padrão é auto; o OpenClaw repassa a escolha do transporte ao runtime compartilhado de modelos.
• Substitua por modelo por meio de agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" ou "auto")
• O processamento prioritário da OpenAI pode ser ativado por meio de agents.defaults.models["openai/<model>"].params.serviceTier
• /fast e params.fastMode mapeiam solicitações Responses diretas de openai/* para service_tier=priority em api.openai.com
• Use params.serviceTier quando quiser um nível explícito em vez do controle compartilhado /fast
• Cabeçalhos ocultos de atribuição do OpenClaw (originator, version, User-Agent) são aplicados apenas ao tráfego nativo da OpenAI para api.openai.com, não a proxies genéricos compatíveis com a OpenAI
• As rotas nativas da OpenAI também preservam store do Responses, dicas de cache de prompts e a formatação da carga útil para compatibilidade com o raciocínio da OpenAI; rotas de proxy não
• openai/gpt-5.3-codex-spark está disponível apenas pelo OAuth do ChatGPT/Codex; rotas diretas com chave de API da OpenAI e com chave de API do Azure o rejeitam

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

Se a organização da API não disponibilizar o GPT-5.6, defina openai/gpt-5.5 explicitamente. A integração inicial e a reautenticação normais preservam um modelo principal explícito existente; models auth login --set-default e models set são os caminhos para substituição intencional.

Anthropic

• Provedor: anthropic
• Autenticação: ANTHROPIC_API_KEY
• Rotação opcional: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, além de OPENCLAW_LIVE_ANTHROPIC_KEY (substituição única)
• Exemplo de modelo: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Solicitações públicas diretas à Anthropic oferecem suporte ao controle compartilhado /fast e a params.fastMode, incluindo tráfego autenticado por chave de API e OAuth enviado a api.anthropic.com; o OpenClaw mapeia isso para service_tier da Anthropic (auto em comparação com standard_only)
• A configuração preferencial da CLI do Claude mantém a referência do modelo canônica e seleciona o backend da CLI separadamente: anthropic/claude-opus-4-8 com agentRuntime.id: "claude-cli" no escopo do modelo. Referências legadas claude-cli/claude-opus-4-7 ainda funcionam por compatibilidade.

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

OAuth do OpenAI ChatGPT/Codex

• Provedor: openai
• Autenticação: OAuth (ChatGPT)
• Referência inicial do harness nativo do servidor de aplicativo do Codex: openai/gpt-5.6-sol
• Documentação do harness nativo do servidor de aplicativo do Codex: Harness do Codex
• Referências legadas de modelos: codex/gpt-*
• Limite do Plugin: openai/* carrega o Plugin da OpenAI; a política explícita de runtime ou a rota efetiva controlada pelo provedor determina se o Plugin nativo do servidor de aplicativo do Codex é selecionado.
• CLI: openclaw onboard --auth-choice openai ou openclaw models auth login --provider openai
• O transporte integrado de ChatGPT Responses do OpenClaw usa auto como padrão (WebSocket primeiro, SSE como fallback).
• agents.defaults.models["openai/<model>"].params.transport, params.serviceTier e params.fastMode são configurações de solicitação integrada definidas pelo usuário. Elas mantêm a seleção implícita de runtime no OpenClaw; o Codex nativo controla o transporte e o nível de serviço de seu servidor de aplicativo.
• 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 a OpenAI
• O controle compartilhado /fast continua disponível como controle de runtime; ele é diferente dos parâmetros de modelo definidos pelo usuário.
• O catálogo nativo do Codex pode disponibilizar as referências exatas openai/gpt-5.6-sol, openai/gpt-5.6-terra e openai/gpt-5.6-luna de acordo com o acesso da conta. Ele não aplica no cliente o alias simples gpt-5.6 da API direta.
• openai/gpt-5.5 usa o contextWindow = 400000 nativo do catálogo do Codex e o padrão de runtime contextTokens = 272000; substitua o limite do runtime com models.providers.openai.models[].contextTokens
• Entre com a autenticação openai e use openai/gpt-5.6-sol para uma nova configuração baseada em assinatura. Se esse espaço de trabalho do Codex não disponibilizar o GPT-5.6, selecione openai/gpt-5.5 explicitamente.
• Use agentRuntime.id: "openclaw" no provedor/modelo para manter no runtime integrado uma rota que, de outra forma, seria elegível. Quando o runtime não está definido ou é auto, apenas uma rota oficial HTTPS exata compatível com Responses/ChatGPT e sem substituição de solicitação definida pelo usuário pode selecionar o Codex implicitamente.
• Referências legadas do GPT do Codex são estado legado, não uma rota ativa de provedor. Use referências canônicas openai/* para novas configurações de agente e execute openclaw doctor --fix para migrar referências antigas e legadas de modelos do Codex sem atualizar uma seleção explícita existente de openai/gpt-5.5.

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },}

{  models: {    providers: {      openai: {        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
• Exemplos de modelos: 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: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, fallback para GOOGLE_API_KEY e OPENCLAW_LIVE_GEMINI_KEY (substituição única)
• Exemplos de modelos: google/gemini-3.1-pro-preview, google/gemini-3.5-flash
• Compatibilidade: configurações legadas do OpenClaw que usam google/gemini-3.1-flash-preview são normalizadas 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
• Raciocínio: /think adaptive usa o raciocínio dinâmico do Google. Gemini 3/3.1 omitem 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 cachedContents/... nativo do provedor; acertos no cache do Gemini são apresentados como cacheRead do OpenClaw

Google Vertex e Gemini CLI

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

O OAuth do Gemini CLI é fornecido como parte do plugin google incluído.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

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

O Gemini CLI usa stream-json por padrão. O OpenClaw lê as mensagens do fluxo do assistente e normaliza stats.cached para cacheRead; substituições legadas de --output-format json ainda leem o texto da resposta em response.

Z.AI (GLM)

• Provedor: zai
• Autenticação: ZAI_API_KEY
• Exemplo de modelo: zai/glm-5.2
• CLI: openclaw onboard --auth-choice zai-api-key
  • As referências de modelos usam o ID de provedor canônico zai/*.
  • zai-api-key detecta automaticamente o endpoint correspondente da Z.AI; zai-coding-global, zai-coding-cn, zai-global e zai-cn forçam uma interface específica

Vercel AI Gateway

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

Outros plugins de provedores incluídos

Particularidades que vale a pena conhecer

Provedores por meio de 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 de provedor incluídos abaixo já publicam um catálogo padrão. Use entradas explícitas de 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 os metadados explícitos de models.providers.<id>.models[]. Se um modelo personalizado ou via proxy aceitar imagens, defina input: ["text", "image"] nesse modelo para que o WebChat e os caminhos de anexos originados em nodes transmitam imagens como entradas nativas do modelo, em vez de referências de mídia somente de texto.

agents.defaults.models["provider/model"] controla apenas a visibilidade dos modelos, aliases e metadados por modelo para os agentes. Ele não registra sozinho um novo modelo de runtime. Para modelos de provedores personalizados, adicione também models.providers.<provider>.models[] com pelo menos o id correspondente.

Moonshot AI (Kimi)

Instale @openclaw/moonshot-provider antes da integração. Adicione uma entrada explícita de models.providers.moonshot somente quando precisar substituir a URL base ou os metadados do modelo:

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

IDs de modelo do Kimi K2:

• moonshot/kimi-k2.6
• moonshot/kimi-k2.7-code
• 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" }],      },    },  },}

Consulte Moonshot AI (Kimi + Kimi Coding) para obter o guia completo de configuração.

Kimi Coding

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

• Provedor: kimi
• Autenticação: KIMI_API_KEY
• Exemplo de modelo: kimi/kimi-for-coding

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

Os modelos legados kimi/kimi-code e kimi/k2p5 continuam sendo aceitos como IDs de modelo de compatibilidade e são normalizados para o ID de modelo estável da API do Kimi.

Volcano Engine (Doubao)

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

• Provedor: volcengine (programação: volcengine-plan)
• Autenticação: VOLCANO_ENGINE_API_KEY
• Exemplo de modelo: 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 usa por padrão a superfície de programação, mas o catálogo geral volcengine/* é registrado ao mesmo tempo.

Nos seletores de modelo de integração/configuração, a opção de autenticação da Volcengine prioriza tanto as linhas volcengine/* quanto volcengine-plan/*. Se esses modelos ainda não estiverem carregados, o OpenClaw recorre ao catálogo sem filtro, em vez de exibir um seletor vazio com escopo restrito ao provedor.

BytePlus (internacional)

O BytePlus ARK fornece aos usuários internacionais acesso aos mesmos modelos que o Volcano Engine.

• Provedor: byteplus (programação: byteplus-plan)
• Autenticação: BYTEPLUS_API_KEY
• Exemplo de modelo: 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 usa por padrão a superfície de programação, mas o catálogo geral byteplus/* é registrado ao mesmo tempo.

Nos seletores de modelo de integração/configuração, a opção de autenticação da BytePlus prioriza tanto as linhas byteplus/* quanto byteplus-plan/*. Se esses modelos ainda não estiverem carregados, o OpenClaw recorre ao catálogo sem filtro, em vez de exibir um seletor vazio com escopo restrito ao provedor.

Synthetic

A Synthetic fornece modelos compatíveis com Anthropic por meio do provedor synthetic:

• Provedor: synthetic
• Autenticação: SYNTHETIC_API_KEY
• Exemplo de modelo: 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

O MiniMax é configurado por meio de models.providers porque usa endpoints personalizados:

• OAuth do MiniMax (global): --auth-choice minimax-global-oauth
• OAuth do MiniMax (CN): --auth-choice minimax-cn-oauth
• Chave de API do MiniMax (global): --auth-choice minimax-global-api
• Chave de API do 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 obter detalhes de configuração, opções de modelos e trechos de configuração.

Divisão de capacidades pertencentes ao plugin:

• Os padrões de texto/chat permanecem em minimax/MiniMax-M3
• 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 do MiniMax
• A pesquisa na web permanece no ID de provedor minimax

LM Studio

O LM Studio é fornecido 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 e carregamento automático, com /v1/chat/completions para inferência por padrão. Se quiser que o carregamento JIT, o TTL e a remoção automática do LM Studio controlem o ciclo de vida do modelo, defina models.providers.lmstudio.params.preload: false. Consulte /providers/lmstudio para obter instruções de configuração e solução de problemas.

Ollama

O Ollama é fornecido como um plugin de provedor incluído e usa a API nativa do Ollama:

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

# Instale o Ollama e, em seguida, baixe um modelo:ollama pull llama3.3

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

O Ollama é detectado localmente em http://127.0.0.1:11434 quando você adere por meio de OLLAMA_API_KEY, e o plugin de provedor incluído adiciona o Ollama diretamente ao openclaw onboard e ao seletor de modelos. Consulte /providers/ollama para obter informações sobre integração, modo em nuvem/local e configuração personalizada.

vLLM

O vLLM é fornecido 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 aderir à descoberta automática localmente (qualquer valor funciona se o seu 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 obter detalhes.

SGLang

O SGLang é fornecido como um plugin de provedor incluído para servidores rápidos e 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 aderir à descoberta automática localmente (qualquer valor funciona se o seu 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 obter 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-zenopenclaw models set opencode/claude-opus-4-6openclaw models list

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

Relacionados

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