Provedores de modelo

Referência para provedores de LLM/modelo (não canais de chat como WhatsApp/Telegram). Para regras de seleção de modelo, 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 de inferência genérico. Plugins são responsáveis por onboarding, catálogos de modelos, mapeamento de variáveis de ambiente de autenticação, normalização de transporte/configuração, limpeza de esquema de ferramentas, classificação de failover, atualização de OAuth, relatório de uso, perfis de pensamento/raciocínio e mais.

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

Rotação de chaves de API

Plugins de provedor oficiais

Plugins de provedor oficiais publicam suas próprias linhas de catálogo de modelos. Estes provedores não exigem entradas de modelo em models.providers; habilite o Plugin de provedor, configure a autenticação e escolha um modelo. Use models.providers apenas para provedores customizados explícitos ou configurações de requisição restritas, como timeouts.

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 de conta/modelo com openclaw models list --provider openai se uma instalação específica ou chave de API se comportar de forma diferente.
• CLI: openclaw onboard --auth-choice openai-api-key
• O transporte padrão é auto; o OpenClaw passa a escolha de transporte para o runtime de modelo compartilhado.
• Substitua por modelo via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" ou "auto")
• O processamento prioritário da OpenAI pode ser habilitado via agents.defaults.models["openai/<model>"].params.serviceTier
• /fast e params.fastMode mapeiam requisições Responses diretas openai/* para service_tier=priority em api.openai.com
• Use params.serviceTier quando quiser um nível explícito em vez do alternador compartilhado /fast
• Cabeçalhos de atribuição ocultos do OpenClaw (originator, version, User-Agent) se aplicam somente 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 está disponível por autenticação de assinatura OAuth ChatGPT/Codex quando sua conta conectada o expõe; o OpenClaw ainda suprime rotas diretas de chave de API da OpenAI e de chave de API do Azure para este modelo porque esses transportes o rejeitam

{  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 dão suporte ao alternador compartilhado /fast e a params.fastMode, incluindo tráfego autenticado por chave de API e OAuth enviado para api.anthropic.com; o OpenClaw mapeia isso para service_tier da Anthropic (auto vs standard_only)
• A configuração preferida da CLI Claude mantém a ref de modelo canônica e seleciona o backend da CLI separadamente: anthropic/claude-opus-4-8 com agentRuntime.id: "claude-cli" com escopo de modelo. Refs legadas claude-cli/claude-opus-4-7 ainda funcionam para compatibilidade.

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

OAuth do OpenAI ChatGPT/Codex

• Provedor: openai
• Autenticação: OAuth (ChatGPT)
• Ref de modelo legada OpenAI Codex: openai/gpt-5.5
• Ref do harness app-server nativo do Codex: openai/gpt-5.5
• Documentação do harness app-server nativo do Codex: Harness do Codex
• Refs de modelo legadas: codex/gpt-*
• Fronteira de Plugin: openai/* carrega o Plugin OpenAI; o Plugin app-server nativo do Codex é selecionado pelo runtime do harness Codex.
• CLI: openclaw onboard --auth-choice openai ou openclaw models auth login --provider openai
• O transporte padrão é auto (WebSocket primeiro, SSE como fallback)
• Substitua por modelo OpenAI Codex via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" ou "auto")
• params.serviceTier também é encaminhado em requisições Responses nativas do Codex (chatgpt.com/backend-api)
• Cabeçalhos de atribuição ocultos do OpenClaw (originator, version, User-Agent) são anexados somente ao tráfego nativo do Codex para chatgpt.com/backend-api, não a proxies genéricos compatíveis com OpenAI
• Compartilha o mesmo alternador /fast e a configuração params.fastMode que openai/* direto; o OpenClaw mapeia isso para service_tier=priority
• openai/gpt-5.5 usa contextWindow = 400000 nativo do catálogo Codex e runtime padrão contextTokens = 272000; substitua o limite do runtime com models.providers.openai.models[].contextTokens
• Nota de política: o 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 e configure openai/gpt-5.5; turnos de agente OpenAI selecionam Codex por padrão.
• Use agentRuntime.id: "openclaw" de provedor/modelo somente quando quiser a rota integrada do OpenClaw; caso contrário, mantenha openai/gpt-5.5 no harness Codex padrão.
• refs GPT legadas do Codex são estado legado, não uma rota de provedor live. Use openai/gpt-5.5 no runtime nativo do Codex para novas configurações de agente e execute openclaw doctor --fix para migrar refs de modelo Codex legadas antigas para refs canônicas openai/*.

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

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

Outras opções hospedadas no estilo 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 da API Gemini ao vivo 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 aparecem como cacheRead do OpenClaw

Google Vertex e Gemini CLI

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

O OAuth do Gemini CLI é enviado como parte do Plugin google integrado.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

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

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

Z.AI (GLM)

• Provedor: zai
• Autenticação: ZAI_API_KEY
• Modelo de exemplo: zai/glm-5.2
• CLI: openclaw onboard --auth-choice zai-api-key
  • Referências de modelo usam o ID de provedor canônico 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

Outros Plugins de provedor integrados

Peculiaridades 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 de provedores 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 metadados explícitos de models.providers.<id>.models[]. Se um modelo personalizado ou proxy aceita imagens, defina input: ["text", "image"] nesse modelo para que os caminhos de anexos originados no WebChat e em nós passem imagens como entradas nativas do modelo, em vez de referências de mídia somente texto.

agents.defaults.models["provider/model"] controla apenas a visibilidade do modelo, aliases e metadados por modelo para agentes. Ele não registra um novo modelo de runtime por si só. 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
• 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.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" }],      },    },  },}

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-for-coding

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

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

Volcano Engine (Doubao)

Volcano Engine (火山引擎) fornece acesso ao Doubao e a 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 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/configuração, a opção de autenticação 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 mostrar um seletor vazio com escopo de provedor.

BytePlus (Internacional)

BytePlus ARK fornece acesso aos mesmos modelos que o 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 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/configuração, a opção de autenticação 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 mostrar um seletor vazio com escopo de 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 snippets de configuração.

Divisão de capacidades de propriedade do 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 é MiniMax-VL-01, de propriedade do Plugin, em ambos os caminhos de autenticação MiniMax
• A pesquisa na Web permanece no ID de provedor minimax

LM Studio

LM Studio é distribuído como um Plugin de provedor integrado 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 /api/v1/models e /api/v1/models/load nativos 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 sejam responsáveis pelo 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 integrado 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" } },  },}

Ollama é detectado localmente em http://127.0.0.1:11434 quando você opta por usá-lo com OLLAMA_API_KEY, e o Plugin de provedor integrado adiciona Ollama diretamente ao openclaw onboard e ao seletor de modelos. Consulte /providers/ollama para integração, modo em nuvem/local e configuração personalizada.

vLLM

vLLM é distribuído como um Plugin de provedor integrado 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 optar pela descoberta automática localmente (qualquer valor funciona se o seu servidor não impuser 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 integrado 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 optar pela descoberta automática localmente (qualquer valor funciona se o seu servidor não impuser 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-zenopenclaw models set opencode/claude-opus-4-6openclaw 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 nova tentativa
• Modelos - configuração e aliases de modelos
• Provedores - guias de configuração por provedor