Provedores de modelos

Referência para provedores de LLM/modelos (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 fica em Plugins de provedor (registerProvider(...)), enquanto o OpenClaw mantém o loop genérico de inferência. Plugins controlam onboarding, catálogos de modelo, mapeamento de variáveis de ambiente de autenticação, normalização de transporte/configuração, limpeza de esquema de ferramenta, classificação de failover, atualização de OAuth, relatório de uso, perfis de pensamento/raciocínio e mais.

A lista completa de hooks de 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 é fornecido com o catálogo pi-ai. Estes provedores não exigem nenhuma configuração models.providers; basta definir autenticação + 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; o OpenClaw passa a escolha de transporte para pi-ai.
• Substitua por modelo via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" ou "auto")
• O processamento prioritário da OpenAI pode ser ativado 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 uma camada explícita em vez do alternador compartilhado /fast
• Cabeçalhos ocultos de atribuição 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 modelagem de payload de compatibilidade de raciocínio da OpenAI; rotas de proxy não
• openai/gpt-5.3-codex-spark é intencionalmente suprimido no OpenClaw porque requisições live da API OpenAI o rejeitam e o catálogo Codex atual 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 oferecem 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 preferencial da Claude CLI mantém a referência de modelo canônica e seleciona o backend de CLI separadamente: anthropic/claude-opus-4-7 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" } } },}

OpenAI Codex OAuth

• Provedor: openai-codex
• Autenticação: OAuth (ChatGPT)
• Referência de modelo PI legada: openai-codex/gpt-5.5
• Referência do harness nativo do servidor de aplicativo Codex: openai/gpt-5.5
• Documentação do harness nativo do servidor de aplicativo Codex: harness Codex
• Referências de modelo legadas: codex/gpt-*
• Limite de Plugin: openai-codex/* carrega o Plugin OpenAI; o Plugin nativo do servidor de aplicativo Codex é selecionado somente pelo runtime do harness Codex ou por referências 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 SSE)
• Substitua por modelo 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 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-codex/gpt-5.5 usa o contextWindow = 400000 nativo do catálogo Codex e o runtime padrão contextTokens = 272000; substitua o limite de runtime com models.providers.openai-codex.models[].contextTokens
• Observação de política: OpenAI Codex OAuth é explicitamente compatível com ferramentas/fluxos de trabalho externos como o OpenClaw.
• Para a rota comum de assinatura mais runtime nativo Codex, entre com autenticação openai-codex, mas configure openai/gpt-5.5; turnos de agente OpenAI selecionam Codex por padrão.
• Use agentRuntime.id: "pi" de provedor/modelo somente quando quiser uma rota de compatibilidade por meio do PI; caso contrário, mantenha openai/gpt-5.5 no harness Codex padrão.
• Referências antigas openai-codex/gpt-5.1*, openai-codex/gpt-5.2* e openai-codex/gpt-5.3* são suprimidas porque contas ChatGPT/Codex OAuth as rejeitam; use openai-codex/gpt-5.5 ou a rota nativa de runtime Codex em vez disso.

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

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

Outras opções hospedadas em estilo de assinatura

OpenCode

• Autenticação: OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY)
• Provedor de runtime Zen: opencode
• Provedor de 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: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, fallback 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
• Apelido: google/gemini-3.1-pro é aceito e normalizado para o id da API Gemini ativa 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 de 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

OAuth do Gemini CLI é enviado 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

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

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
  • Apelidos: 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 runtime.
• O roteamento upstream exato por trás de kilocode/kilo/auto é propriedade do Kilo Gateway, não codificado diretamente no OpenClaw.

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

Outros Plugins de provedor incluídos

Particularidades úteis de saber

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 provedor incluídos abaixo já publicam um catálogo padrão. Use entradas explícitas models.providers.<id> apenas 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 aceitar imagens, defina input: ["text", "image"] nesse modelo para que o WebChat e os caminhos de anexos originados em nós passem imagens como entradas nativas do modelo, em vez de referências de mídia apenas de 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 provedor personalizados, adicione também models.providers.<provider>.models[] com pelo menos o id correspondente.

Moonshot AI (Kimi)

Moonshot é distribuído como um plugin de provedor incluído. Use o provedor integrado por padrão e adicione uma entrada explícita models.providers.moonshot apenas 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" }],      },    },  },}

Kimi coding

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 legados kimi/kimi-code e kimi/k2p5 continuam aceitos como ids de modelo de compatibilidade e são normalizados para o id de modelo estável da API 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 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 tanto as linhas volcengine/* quanto 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 com escopo de 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 tanto as linhas byteplus/* quanto 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 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
• MiniMax API key (Global): --auth-choice minimax-global-api
• MiniMax API key (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 de propriedade do 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 é de propriedade do 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 é 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 + carregamento automático, com /v1/chat/completions para inferência por padrão. Se você 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 configuração e solução de problemas.

Ollama

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)
• 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 incluído adiciona Ollama diretamente ao openclaw onboard e ao seletor de modelos. Consulte /providers/ollama para integração inicial, modo em nuvem/local e configuração personalizada.

vLLM

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 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 é fornecido 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 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.

Relacionado

• 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 e aliases de modelo
• Provedores - guias de configuração por provedor