diff --git a/docs/pt-BR/concepts/model-providers.md b/docs/pt-BR/concepts/model-providers.md index 5f0dc5da2..290a8d31a 100644 --- a/docs/pt-BR/concepts/model-providers.md +++ b/docs/pt-BR/concepts/model-providers.md @@ -1,41 +1,40 @@ --- read_when: - Você precisa de uma referência de configuração de modelos por provedor - - Você quer configurações de exemplo ou comandos de integração da CLI para provedores de modelo -summary: Visão geral dos provedores de modelo com configurações de exemplo + fluxos da CLI -title: Provedores de modelo + - Você quer exemplos de configuração ou comandos de onboarding da CLI para provedores de modelos +summary: Visão geral dos provedores de modelos com exemplos de configuração + fluxos de CLI +title: Provedores de modelos x-i18n: - generated_at: "2026-04-11T02:44:18Z" + generated_at: "2026-04-13T08:50:35Z" model: gpt-5.4 provider: openai - source_hash: 910ea7895e74c03910757d9d3e02825754b779b204eca7275b28422647ed0151 + source_hash: 66ba688c4b4366eec07667571e835d4cfeee684896e2ffae11d601b5fa0a4b98 source_path: concepts/model-providers.md workflow: 15 --- -# Provedores de modelo +# Provedores de modelos -Esta página cobre **provedores de LLM/modelo** (não canais de chat como WhatsApp/Telegram). +Esta página cobre **provedores de LLM/modelos** (não canais de chat como WhatsApp/Telegram). Para regras de seleção de modelos, consulte [/concepts/models](/pt-BR/concepts/models). ## Regras rápidas - As referências de modelo usam `provider/model` (exemplo: `opencode/claude-opus-4-6`). -- Se você definir `agents.defaults.models`, isso se torna a lista de permissões. -- Auxiliares da CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Regras de fallback em runtime, sondagens de resfriamento e persistência de substituição de sessão são - documentadas em [/concepts/model-failover](/pt-BR/concepts/model-failover). +- Se você definir `agents.defaults.models`, isso se tornará a lista de permissão. +- Auxiliares de CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. +- As regras de runtime de fallback, sondas de cooldown e persistência de sobrescrita de sessão estão documentadas em [/concepts/model-failover](/pt-BR/concepts/model-failover). - `models.providers.*.models[].contextWindow` são metadados nativos do modelo; - `models.providers.*.models[].contextTokens` é o limite efetivo em runtime. + `models.providers.*.models[].contextTokens` é o limite efetivo de runtime. - Plugins de provedor podem injetar catálogos de modelos via `registerProvider({ catalog })`; o OpenClaw mescla essa saída em `models.providers` antes de gravar `models.json`. - Manifestos de provedor podem declarar `providerAuthEnvVars` e - `providerAuthAliases` para que sondagens genéricas de autenticação baseadas em variáveis de ambiente e variantes de provedor - não precisem carregar o runtime do plugin. O mapa restante de variáveis de ambiente do núcleo agora - é apenas para provedores não baseados em plugin/do núcleo e alguns casos de precedência genérica, - como integração com prioridade para chave de API da Anthropic. -- Plugins de provedor também podem ser donos do comportamento de runtime do provedor por meio de + `providerAuthAliases` para que sondas genéricas de autenticação baseadas em variáveis de ambiente e variantes de provedor + não precisem carregar o runtime do plugin. O mapeamento restante de variáveis de ambiente do core agora existe + apenas para provedores não baseados em plugin/do core e alguns casos genéricos de precedência, como + onboarding com chave de API Anthropic primeiro. +- Plugins de provedor também podem controlar o comportamento de runtime do provedor por meio de `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -53,79 +52,82 @@ Para regras de seleção de modelos, consulte [/concepts/models](/pt-BR/concepts `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, e `onModelSelected`. -- Observação: `capabilities` do runtime do provedor são metadados compartilhados do executor (família do provedor, peculiaridades de transcrição/ferramentas, dicas de transporte/cache). Não é o +- Observação: `capabilities` do runtime do provedor são metadados compartilhados do runner (família do provedor, + particularidades de transcrição/ferramentas, dicas de transporte/cache). Isso não é o mesmo que o [modelo de capacidade pública](/pt-BR/plugins/architecture#public-capability-model), que descreve o que um plugin registra (inferência de texto, fala etc.). -- O provedor `codex` incluído é emparelhado com o harness do agente Codex incluído. - Use referências `codex/gpt-*` quando você quiser login gerenciado pelo Codex, descoberta de modelos, - retomada nativa de thread e execução em servidor de aplicativo. Referências simples `openai/gpt-*` continuam +- O provedor `codex` incluído vem emparelhado com o harness de agente Codex incluído. + Use `codex/gpt-*` quando quiser login controlado pelo Codex, descoberta de modelos, + retomada nativa de thread e execução no servidor do app. Referências simples `openai/gpt-*` continuam usando o provedor OpenAI e o transporte normal de provedor do OpenClaw. - Implantações somente com Codex podem desativar o fallback automático de PI com + Implantações somente com Codex podem desativar o fallback automático para PI com `agents.defaults.embeddedHarness.fallback: "none"`; consulte [Codex Harness](/pt-BR/plugins/codex-harness). -## Comportamento de provedor sob posse do plugin +## Comportamento de provedor controlado por plugin -Plugins de provedor agora podem ser donos da maior parte da lógica específica do provedor, enquanto o OpenClaw mantém +Os plugins de provedor agora podem controlar a maior parte da lógica específica de provedor, enquanto o OpenClaw mantém o loop genérico de inferência. Divisão típica: -- `auth[].run` / `auth[].runNonInteractive`: o provedor é dono dos fluxos de integração/login +- `auth[].run` / `auth[].runNonInteractive`: o provedor controla os fluxos de onboarding/login para `openclaw onboard`, `openclaw models auth` e configuração sem interface -- `wizard.setup` / `wizard.modelPicker`: o provedor é dono dos rótulos de escolha de autenticação, - aliases legados, dicas de lista de permissões na integração e entradas de configuração nos seletores de integração/modelo +- `wizard.setup` / `wizard.modelPicker`: o provedor controla os rótulos de escolha de autenticação, + aliases legados, dicas de lista de permissão no onboarding e entradas de configuração nos seletores de onboarding/modelo - `catalog`: o provedor aparece em `models.providers` -- `normalizeModelId`: o provedor normaliza IDs de modelo legados/prévia antes - da busca ou da canonização +- `normalizeModelId`: o provedor normaliza IDs de modelo legados/preview antes + da busca ou canonicalização - `normalizeTransport`: o provedor normaliza `api` / `baseUrl` da família de transporte antes da montagem genérica do modelo; o OpenClaw verifica primeiro o provedor correspondente, - depois outros plugins de provedor com suporte a hooks até que um realmente altere o - transporte + depois outros plugins de provedor com suporte a hook até que um realmente altere + o transporte - `normalizeConfig`: o provedor normaliza a configuração `models.providers.` antes de o runtime usá-la; o OpenClaw verifica primeiro o provedor correspondente, depois outros - plugins de provedor com suporte a hooks até que um realmente altere a configuração. Se nenhum + plugins de provedor com suporte a hook até que um realmente altere a configuração. Se nenhum hook de provedor reescrever a configuração, os auxiliares incluídos da família Google ainda normalizam entradas compatíveis de provedor Google. -- `applyNativeStreamingUsageCompat`: o provedor aplica regravações de compatibilidade de uso de streaming nativo orientadas por endpoint para provedores de configuração -- `resolveConfigApiKey`: o provedor resolve autenticação com marcador de variável de ambiente para provedores de configuração +- `applyNativeStreamingUsageCompat`: o provedor aplica reescritas de compatibilidade de uso de streaming nativo orientadas por endpoint para provedores de configuração +- `resolveConfigApiKey`: o provedor resolve autenticação por marcador de ambiente para provedores de configuração sem forçar o carregamento completo da autenticação de runtime. `amazon-bedrock` também tem um - resolvedor interno de marcador de variável de ambiente da AWS aqui, embora a autenticação de runtime do Bedrock use + resolvedor embutido de marcador de ambiente AWS aqui, embora a autenticação de runtime do Bedrock use a cadeia padrão do SDK da AWS. - `resolveSyntheticAuth`: o provedor pode expor disponibilidade de autenticação - local/self-hosted ou outra baseada em configuração sem persistir segredos em texto simples + local/self-hosted ou outra autenticação baseada em configuração sem persistir segredos em texto puro - `shouldDeferSyntheticProfileAuth`: o provedor pode marcar placeholders sintéticos de perfil armazenados - como de menor precedência do que autenticação baseada em variável de ambiente/configuração -- `resolveDynamicModel`: o provedor aceita IDs de modelo ainda não presentes no catálogo estático local + como de precedência inferior à autenticação baseada em ambiente/configuração +- `resolveDynamicModel`: o provedor aceita IDs de modelo que ainda não estão presentes no + catálogo estático local - `prepareDynamicModel`: o provedor precisa de uma atualização de metadados antes de tentar novamente a resolução dinâmica -- `normalizeResolvedModel`: o provedor precisa de regravações de transporte ou URL base +- `normalizeResolvedModel`: o provedor precisa de reescritas de transporte ou base URL - `contributeResolvedModelCompat`: o provedor contribui com sinalizadores de compatibilidade para seus - modelos do fornecedor, mesmo quando eles chegam por outro transporte compatível -- `capabilities`: o provedor publica peculiaridades de transcrição/ferramentas/família do provedor -- `normalizeToolSchemas`: o provedor limpa esquemas de ferramenta antes que o executor embutido os veja + modelos do fornecedor mesmo quando eles chegam por outro transporte compatível +- `capabilities`: o provedor publica particularidades de transcrição/ferramentas/família de provedor +- `normalizeToolSchemas`: o provedor limpa esquemas de ferramentas antes que o + runner embutido os veja - `inspectToolSchemas`: o provedor expõe avisos de esquema específicos de transporte após a normalização -- `resolveReasoningOutputMode`: o provedor escolhe contratos nativos versus marcados - para saída de raciocínio -- `prepareExtraParams`: o provedor define padrões ou normaliza parâmetros de solicitação por modelo -- `createStreamFn`: o provedor substitui o caminho normal de stream por um transporte totalmente - personalizado -- `wrapStreamFn`: o provedor aplica wrappers de compatibilidade de cabeçalhos/corpo/modelo da solicitação +- `resolveReasoningOutputMode`: o provedor escolhe contratos de saída de raciocínio + nativos vs marcados +- `prepareExtraParams`: o provedor define padrões ou normaliza parâmetros de requisição por modelo +- `createStreamFn`: o provedor substitui o caminho normal de stream por um transporte + totalmente personalizado +- `wrapStreamFn`: o provedor aplica wrappers de compatibilidade de cabeçalhos/corpo/modelo da requisição - `resolveTransportTurnState`: o provedor fornece cabeçalhos ou metadados nativos de transporte por turno - `resolveWebSocketSessionPolicy`: o provedor fornece cabeçalhos nativos de sessão WebSocket - ou política de resfriamento de sessão -- `createEmbeddingProvider`: o provedor é dono do comportamento de embeddings de memória quando isso - pertence ao plugin do provedor em vez do comutador central de embeddings do núcleo -- `formatApiKey`: o provedor formata perfis de autenticação armazenados na - string `apiKey` de runtime esperada pelo transporte -- `refreshOAuth`: o provedor é dono da atualização de OAuth quando os atualizadores compartilhados - de `pi-ai` não são suficientes -- `buildAuthDoctorHint`: o provedor anexa orientações de reparo quando a atualização de OAuth + ou política de cooldown da sessão +- `createEmbeddingProvider`: o provedor controla o comportamento de embeddings de memória quando isso + pertence ao plugin do provedor em vez do comutador central de embeddings do core +- `formatApiKey`: o provedor formata perfis de autenticação armazenados na string + `apiKey` de runtime esperada pelo transporte +- `refreshOAuth`: o provedor controla a atualização de OAuth quando os atualizadores compartilhados de `pi-ai` + não são suficientes +- `buildAuthDoctorHint`: o provedor acrescenta orientação de correção quando a atualização de OAuth falha - `matchesContextOverflowError`: o provedor reconhece erros de estouro de janela de contexto - específicos do provedor que as heurísticas genéricas não detectariam + específicos do provedor que heurísticas genéricas não detectariam - `classifyFailoverReason`: o provedor mapeia erros brutos específicos do provedor, de transporte/API, para motivos de failover, como limite de taxa ou sobrecarga - `isCacheTtlEligible`: o provedor decide quais IDs de modelo upstream oferecem suporte a TTL de cache de prompt @@ -133,98 +135,98 @@ Divisão típica: por uma dica de recuperação específica do provedor - `suppressBuiltInModel`: o provedor oculta linhas upstream desatualizadas e pode retornar um erro controlado pelo fornecedor para falhas de resolução direta -- `augmentModelCatalog`: o provedor adiciona linhas sintéticas/finais ao catálogo após +- `augmentModelCatalog`: o provedor acrescenta linhas sintéticas/finais ao catálogo após descoberta e mesclagem de configuração -- `isBinaryThinking`: o provedor é dono da UX binária de pensamento ligado/desligado -- `supportsXHighThinking`: o provedor habilita `xhigh` para modelos selecionados -- `resolveDefaultThinkingLevel`: o provedor é dono da política padrão de `/think` para uma +- `isBinaryThinking`: o provedor controla a UX binária de pensamento ligado/desligado +- `supportsXHighThinking`: o provedor habilita `xhigh` em modelos selecionados +- `resolveDefaultThinkingLevel`: o provedor controla a política padrão de `/think` para uma família de modelos - `applyConfigDefaults`: o provedor aplica padrões globais específicos do provedor - durante a materialização da configuração com base no modo de autenticação, ambiente ou família do modelo -- `isModernModelRef`: o provedor é dono da correspondência de modelo preferido em live/smoke + durante a materialização da configuração com base no modo de autenticação, ambiente ou família de modelos +- `isModernModelRef`: o provedor controla a correspondência de modelo preferido em live/smoke - `prepareRuntimeAuth`: o provedor transforma uma credencial configurada em um token de runtime de curta duração - `resolveUsageAuth`: o provedor resolve credenciais de uso/cota para `/usage` e superfícies relacionadas de status/relatórios -- `fetchUsageSnapshot`: o provedor é dono da busca/análise do endpoint de uso, enquanto - o núcleo ainda é dono da estrutura de resumo e da formatação -- `onModelSelected`: o provedor executa efeitos colaterais pós-seleção, como - telemetria ou controle de sessão sob posse do provedor +- `fetchUsageSnapshot`: o provedor controla a busca/análise do endpoint de uso enquanto o + core ainda controla o shell de resumo e a formatação +- `onModelSelected`: o provedor executa efeitos colaterais após a seleção do modelo, como + telemetria ou bookkeeping de sessão controlado pelo provedor -Exemplos incluídos atualmente: +Exemplos atuais incluídos: -- `anthropic`: fallback de compatibilidade futura para Claude 4.6, dicas de reparo de autenticação, busca do endpoint de uso, metadados de TTL de cache/família de provedor e padrões globais de configuração conscientes de autenticação -- `amazon-bedrock`: correspondência de estouro de contexto sob posse do provedor e classificação de motivo de failover para erros específicos do Bedrock de limitação/não pronto, além da família compartilhada de replay `anthropic-by-model` para proteções de política de replay somente para Claude em tráfego Anthropic -- `anthropic-vertex`: proteções de política de replay somente para Claude em tráfego `anthropic-message` -- `openrouter`: IDs de modelo em passagem direta, wrappers de solicitação, dicas de capacidade do provedor, saneamento de assinatura de pensamento do Gemini em tráfego Gemini por proxy, injeção de raciocínio por proxy por meio da família de stream `openrouter-thinking`, encaminhamento de metadados de roteamento e política de TTL de cache -- `github-copilot`: integração/login de dispositivo, fallback de modelo com compatibilidade futura, dicas de transcrição para pensamento do Claude, troca de token em runtime e busca do endpoint de uso -- `openai`: fallback de compatibilidade futura para GPT-5.4, normalização direta de transporte OpenAI, dicas de autenticação ausente com reconhecimento de Codex, supressão do Spark, linhas sintéticas de catálogo OpenAI/Codex, política de thinking/live-model, normalização de aliases de token de uso (`input` / `output` e famílias `prompt` / `completion`), a família compartilhada de stream `openai-responses-defaults` para wrappers nativos OpenAI/Codex, metadados de família de provedor, registro incluído de provedor de geração de imagem para `gpt-image-1` e registro incluído de provedor de geração de vídeo para `sora-2` -- `google` e `google-gemini-cli`: fallback de compatibilidade futura para Gemini 3.1, validação nativa de replay do Gemini, saneamento de replay de bootstrap, modo de saída de raciocínio com tags, correspondência de modelo moderno, registro incluído de provedor de geração de imagem para modelos Gemini image-preview e registro incluído de provedor de geração de vídeo para modelos Veo; o OAuth do Gemini CLI também é dono da formatação de token do perfil de autenticação, análise de token de uso e busca de endpoint de cota para superfícies de uso -- `moonshot`: transporte compartilhado, normalização de payload de thinking sob posse do plugin -- `kilocode`: transporte compartilhado, cabeçalhos de solicitação sob posse do plugin, normalização de payload de raciocínio, saneamento de assinatura de pensamento do Gemini por proxy e política de TTL de cache -- `zai`: fallback de compatibilidade futura para GLM-5, padrões `tool_stream`, política de TTL de cache, política de binary-thinking/live-model e autenticação de uso + busca de cota; IDs desconhecidos `glm-5*` são sintetizados a partir do modelo `glm-4.7` incluído -- `xai`: normalização nativa de transporte Responses, regravações de alias `/fast` para variantes rápidas do Grok, `tool_stream` padrão, limpeza específica do xAI para esquema de ferramenta / payload de raciocínio e registro incluído de provedor de geração de vídeo para `grok-imagine-video` -- `mistral`: metadados de capacidade sob posse do plugin -- `opencode` e `opencode-go`: metadados de capacidade sob posse do plugin mais saneamento de assinatura de pensamento do Gemini por proxy -- `alibaba`: catálogo de geração de vídeo sob posse do plugin para referências diretas de modelo Wan, como `alibaba/wan2.6-t2v` -- `byteplus`: catálogos sob posse do plugin mais registro incluído de provedor de geração de vídeo para modelos Seedance de texto para vídeo/imagem para vídeo -- `fal`: registro incluído de provedor de geração de vídeo para geração de imagem de terceiros hospedada para modelos de imagem FLUX, mais registro incluído de provedor de geração de vídeo para modelos de vídeo de terceiros hospedados +- `anthropic`: fallback de compatibilidade futura para Claude 4.6, dicas de reparo de autenticação, busca de endpoint de uso, metadados de TTL de cache/família de provedor e padrões globais de configuração com reconhecimento de autenticação +- `amazon-bedrock`: correspondência de overflow de contexto controlada pelo provedor e classificação de motivo de failover para erros específicos do Bedrock de throttle/não pronto, além da família compartilhada de replay `anthropic-by-model` para proteções de política de replay apenas para Claude em tráfego Anthropic +- `anthropic-vertex`: proteções de política de replay apenas para Claude em tráfego de mensagens Anthropic +- `openrouter`: IDs de modelo pass-through, wrappers de requisição, dicas de capacidade do provedor, sanitização de assinatura de pensamento Gemini em tráfego Gemini por proxy, injeção de raciocínio por proxy por meio da família de stream `openrouter-thinking`, encaminhamento de metadados de roteamento e política de TTL de cache +- `github-copilot`: onboarding/login por dispositivo, fallback de modelo com compatibilidade futura, dicas de transcrição de pensamento Claude, troca de token de runtime e busca de endpoint de uso +- `openai`: fallback de compatibilidade futura para GPT-5.4, normalização direta de transporte OpenAI, dicas de autenticação ausente com reconhecimento de Codex, supressão de Spark, linhas sintéticas de catálogo OpenAI/Codex, política de thinking/modelo live, normalização de aliases de token de uso (`input` / `output` e famílias `prompt` / `completion`), a família compartilhada de stream `openai-responses-defaults` para wrappers nativos OpenAI/Codex, metadados de família de provedor, registro incluído de provedor de geração de imagem para `gpt-image-1` e registro incluído de provedor de geração de vídeo para `sora-2` +- `google` e `google-gemini-cli`: fallback de compatibilidade futura para Gemini 3.1, validação nativa de replay Gemini, sanitização de replay de bootstrap, modo de saída de raciocínio com tags, correspondência de modelos modernos, registro incluído de provedor de geração de imagem para modelos Gemini image-preview e registro incluído de provedor de geração de vídeo para modelos Veo; o OAuth do Gemini CLI também controla a formatação de token de perfil de autenticação, a análise de token de uso e a busca de endpoint de cota para superfícies de uso +- `moonshot`: transporte compartilhado, normalização de payload de thinking controlada por plugin +- `kilocode`: transporte compartilhado, cabeçalhos de requisição controlados por plugin, normalização de payload de raciocínio, sanitização de assinatura de pensamento Gemini por proxy e política de TTL de cache +- `zai`: fallback de compatibilidade futura para GLM-5, padrões de `tool_stream`, política de TTL de cache, política binária de thinking/modelo live e autenticação de uso + busca de cota; IDs desconhecidos `glm-5*` são sintetizados a partir do modelo incluído `glm-4.7` +- `xai`: normalização nativa de transporte Responses, reescritas de alias `/fast` para variantes rápidas do Grok, `tool_stream` padrão, limpeza específica do xAI de esquema de ferramenta / payload de raciocínio e registro incluído de provedor de geração de vídeo para `grok-imagine-video` +- `mistral`: metadados de capacidade controlados por plugin +- `opencode` e `opencode-go`: metadados de capacidade controlados por plugin, além de sanitização de assinatura de pensamento Gemini por proxy +- `alibaba`: catálogo de geração de vídeo controlado por plugin para referências diretas de modelo Wan, como `alibaba/wan2.6-t2v` +- `byteplus`: catálogos controlados por plugin, além de registro incluído de provedor de geração de vídeo para modelos Seedance de texto para vídeo/imagem para vídeo +- `fal`: registro incluído de provedor de geração de vídeo para modelos de terceiros hospedados, registro de provedor de geração de imagem para modelos de imagem FLUX, além de registro incluído de provedor de geração de vídeo para modelos de vídeo de terceiros hospedados - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` e `volcengine`: - apenas catálogos sob posse do plugin -- `qwen`: catálogos sob posse do plugin para modelos de texto mais registros compartilhados de provedores de compreensão de mídia e geração de vídeo para suas superfícies multimodais; a geração de vídeo Qwen usa os endpoints de vídeo DashScope Standard com modelos Wan incluídos, como `wan2.6-t2v` e `wan2.7-r2v` -- `runway`: registro de provedor de geração de vídeo sob posse do plugin para modelos nativos baseados em tarefa do Runway, como `gen4.5` -- `minimax`: catálogos sob posse do plugin, registro incluído de provedor de geração de vídeo para modelos de vídeo Hailuo, registro incluído de provedor de geração de imagem para `image-01`, seleção híbrida de política de replay Anthropic/OpenAI e lógica de autenticação/snapshot de uso -- `together`: catálogos sob posse do plugin mais registro incluído de provedor de geração de vídeo para modelos de vídeo Wan -- `xiaomi`: catálogos sob posse do plugin mais lógica de autenticação/snapshot de uso + apenas catálogos controlados por plugin +- `qwen`: catálogos controlados por plugin para modelos de texto, além de registros compartilhados de provedores de media-understanding e geração de vídeo para suas superfícies multimodais; a geração de vídeo do Qwen usa os endpoints padrão de vídeo do DashScope com modelos Wan incluídos, como `wan2.6-t2v` e `wan2.7-r2v` +- `runway`: registro de provedor de geração de vídeo controlado por plugin para modelos nativos do Runway baseados em tarefas, como `gen4.5` +- `minimax`: catálogos controlados por plugin, registro incluído de provedor de geração de vídeo para modelos de vídeo Hailuo, registro incluído de provedor de geração de imagem para `image-01`, seleção híbrida de política de replay Anthropic/OpenAI e lógica de autenticação/snapshot de uso +- `together`: catálogos controlados por plugin, além de registro incluído de provedor de geração de vídeo para modelos de vídeo Wan +- `xiaomi`: catálogos controlados por plugin, além de lógica de autenticação/snapshot de uso -O plugin `openai` incluído agora é dono de ambos os IDs de provedor: `openai` e +O plugin `openai` incluído agora controla ambos os IDs de provedor: `openai` e `openai-codex`. -Isso cobre provedores que ainda se encaixam nos transportes normais do OpenClaw. Um provedor -que precisa de um executor de solicitação totalmente personalizado pertence a uma superfície de extensão separada e mais profunda. +Isso cobre os provedores que ainda se encaixam nos transportes normais do OpenClaw. 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 chave de API +## Rotação de chaves de API -- Suporta rotação genérica de provedor para provedores selecionados. +- Oferece suporte à rotação genérica de provedor para provedores selecionados. - Configure várias chaves por meio de: - - `OPENCLAW_LIVE__KEY` (substituição única de uso ao vivo, prioridade mais alta) + - `OPENCLAW_LIVE__KEY` (sobrescrita live única, maior prioridade) - `_API_KEYS` (lista separada por vírgula ou ponto e vírgula) - - `_API_KEY` (chave principal) + - `_API_KEY` (chave primária) - `_API_KEY_*` (lista numerada, por exemplo `_API_KEY_1`) - Para provedores Google, `GOOGLE_API_KEY` também é incluída como fallback. - A ordem de seleção de chaves preserva a prioridade e remove valores duplicados. -- As solicitações são repetidas com a próxima chave apenas em respostas de limite de taxa (por +- As requisições são repetidas com a próxima chave apenas em respostas de limite de taxa (por exemplo `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` ou mensagens periódicas de limite de uso). - Falhas que não sejam de limite de taxa falham imediatamente; nenhuma rotação de chave é tentada. -- Quando todas as chaves candidatas falham, o erro final retornado é o da última tentativa. +- Quando todas as chaves candidatas falham, o erro final da última tentativa é retornado. -## Provedores incluídos (catálogo pi-ai) +## Provedores integrados (catálogo pi-ai) -O OpenClaw é fornecido com o catálogo pi‑ai. Esses provedores não exigem -configuração em `models.providers`; basta definir a autenticação + escolher um modelo. +O OpenClaw é fornecido com o catálogo pi-ai. Esses provedores não exigem +configuração em `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) +- Rotação opcional: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, além de `OPENCLAW_LIVE_OPENAI_KEY` (sobrescrita única) - Modelos de exemplo: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - 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/"].params.transport` (`"sse"`, `"websocket"` ou `"auto"`) -- O pré-aquecimento do OpenAI Responses WebSocket vem habilitado por padrão via `params.openaiWsWarmup` (`true`/`false`) -- O processamento prioritário da OpenAI pode ser habilitado por meio de `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` e `params.fastMode` mapeiam solicitações diretas `openai/*` Responses para `service_tier=priority` em `api.openai.com` +- O warm-up de WebSocket do OpenAI Responses vem habilitado por padrão via `params.openaiWsWarmup` (`true`/`false`) +- O processamento prioritário da OpenAI pode ser habilitado via `agents.defaults.models["openai/"].params.serviceTier` +- `/fast` e `params.fastMode` mapeiam requisições diretas `openai/*` de Responses 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 apenas ao tráfego OpenAI nativo para `api.openai.com`, não a - proxies genéricos compatíveis com OpenAI +- Os cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, + `User-Agent`) se aplicam apenas ao tráfego OpenAI nativo para `api.openai.com`, não + a proxies genéricos compatíveis com OpenAI - Rotas OpenAI nativas também mantêm `store` do Responses, dicas de cache de prompt e - modelagem de payload de compatibilidade de raciocínio da OpenAI; rotas por proxy não -- `openai/gpt-5.3-codex-spark` é intencionalmente suprimido no OpenClaw porque a API OpenAI ao vivo o rejeita; Spark é tratado como exclusivo do Codex + 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 a API live da OpenAI o rejeita; Spark é tratado como exclusivo do Codex ```json5 { @@ -236,12 +238,12 @@ configuração em `models.providers`; basta definir a autenticação + escolher - 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) +- Rotação opcional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, além de `OPENCLAW_LIVE_ANTHROPIC_KEY` (sobrescrita única) - Modelo de exemplo: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Solicitações públicas diretas para a Anthropic também 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` versus `standard_only`) -- Observação sobre a Anthropic: a equipe da Anthropic nos informou que o uso do Claude CLI no estilo do OpenClaw é permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como autorizados para esta integração, a menos que a Anthropic publique uma nova política. -- O token de configuração da Anthropic continua disponível como um caminho de token compatível do OpenClaw, mas o OpenClaw agora prefere reutilização do Claude CLI e `claude -p` quando disponíveis. +- Requisições públicas diretas da Anthropic também oferecem suporte ao alternador compartilhado `/fast` e `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`) +- Observação sobre Anthropic: a equipe da Anthropic nos informou que o uso no estilo Claude CLI do OpenClaw é permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como autorizados para esta integração, a menos que a Anthropic publique uma nova política. +- O token de configuração da Anthropic continua disponível como um caminho de token compatível no OpenClaw, mas o OpenClaw agora prefere reutilização do Claude CLI e `claude -p` quando disponíveis. ```json5 { @@ -257,14 +259,14 @@ configuração em `models.providers`; basta definir a autenticação + escolher - 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 via `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` ou `"auto"`) -- `params.serviceTier` também é encaminhado em solicitações nativas Codex Responses (`chatgpt.com/backend-api`) -- Cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, - `User-Agent`) são anexados apenas no tráfego Codex nativo para - `chatgpt.com/backend-api`, não em proxies genéricos compatíveis com OpenAI +- `params.serviceTier` também é encaminhado em requisições nativas Codex Responses (`chatgpt.com/backend-api`) +- Os cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, + `User-Agent`) são anexados apenas ao tráfego Codex nativo para + `chatgpt.com/backend-api`, não a proxies genéricos compatíveis com OpenAI - Compartilha o mesmo alternador `/fast` e a mesma configuração `params.fastMode` de `openai/*` direto; o OpenClaw mapeia isso para `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` continua disponível quando o catálogo OAuth do Codex o expõe; dependente de direito de acesso +- `openai-codex/gpt-5.3-codex-spark` continua disponível quando o catálogo OAuth do Codex o expõe; depende do entitlement - `openai-codex/gpt-5.4` mantém `contextWindow = 1050000` nativo e um `contextTokens = 272000` padrão em runtime; substitua o limite de runtime com `models.providers.openai-codex.models[].contextTokens` -- Observação de política: o OAuth do OpenAI Codex é explicitamente compatível com ferramentas/fluxos de trabalho externos como o OpenClaw. +- Observação de política: o OAuth do OpenAI Codex é explicitamente compatível para ferramentas/fluxos de trabalho externos como o OpenClaw. ```json5 { @@ -286,9 +288,9 @@ configuração em `models.providers`; basta definir a autenticação + escolher ### Outras opções hospedadas no estilo assinatura -- [Qwen Cloud](/pt-BR/providers/qwen): superfície de provedor do Qwen Cloud mais mapeamento de endpoint Alibaba DashScope e Coding Plan +- [Qwen Cloud](/pt-BR/providers/qwen): superfície de provedor do Qwen Cloud, além de mapeamento de endpoint do Alibaba DashScope e Coding Plan - [MiniMax](/pt-BR/providers/minimax): acesso ao OAuth ou chave de API do MiniMax Coding Plan -- [GLM Models](/pt-BR/providers/glm): endpoints do Z.AI Coding Plan ou da API geral +- [GLM Models](/pt-BR/providers/glm): Z.AI Coding Plan ou endpoints gerais de API ### OpenCode @@ -308,7 +310,7 @@ configuração em `models.providers`; basta definir a autenticação + escolher - 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) +- Rotação opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback para `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (sobrescrita única) - Modelos de exemplo: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Compatibilidade: configuração legada do OpenClaw usando `google/gemini-3.1-flash-preview` é normalizada para `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` @@ -319,19 +321,19 @@ configuração em `models.providers`; basta definir a autenticação + escolher ### Google Vertex e Gemini CLI - Provedores: `google-vertex`, `google-gemini-cli` -- Autenticação: o Vertex usa gcloud ADC; o Gemini CLI usa seu fluxo OAuth -- Cuidado: o OAuth do Gemini CLI no OpenClaw é uma integração não oficial. Alguns usuários relataram restrições na conta Google após usar clientes de terceiros. Revise os termos do Google e use uma conta não crítica se optar por prosseguir. +- Autenticação: Vertex usa gcloud ADC; Gemini CLI usa seu fluxo OAuth +- Cuidado: o OAuth do Gemini CLI no OpenClaw é uma integração não oficial. Alguns usuários relataram restrições em contas Google após usar clientes de terceiros. Revise os termos do Google e use uma conta não crítica se optar por continuar. - O OAuth do Gemini CLI é distribuído como parte do plugin `google` incluído. - Instale primeiro o Gemini CLI: - `brew install gemini-cli` - ou `npm install -g @google/gemini-cli` - Habilite: `openclaw plugins enable google` - - Faça login: `openclaw models auth login --provider google-gemini-cli --set-default` + - Login: `openclaw models auth login --provider google-gemini-cli --set-default` - Modelo padrão: `google-gemini-cli/gemini-3-flash-preview` - Observação: você **não** cola um client id nem um secret em `openclaw.json`. O fluxo de login da CLI armazena tokens em perfis de autenticação no host do gateway. - - Se as solicitações falharem após o login, defina `GOOGLE_CLOUD_PROJECT` ou `GOOGLE_CLOUD_PROJECT_ID` no host do gateway. - - As respostas JSON do Gemini CLI são analisadas a partir de `response`; o uso recorre a + - Se as requisições falharem após o login, defina `GOOGLE_CLOUD_PROJECT` ou `GOOGLE_CLOUD_PROJECT_ID` no host do gateway. + - Respostas JSON do Gemini CLI são analisadas a partir de `response`; o uso recorre a `stats`, com `stats.cached` normalizado para `cacheRead` no OpenClaw. ### Z.AI (GLM) @@ -341,7 +343,7 @@ configuração em `models.providers`; basta definir a autenticação + escolher - 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 correspondente do Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` e `zai-cn` forçam uma superfície específica + - `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 superfície específica ### Vercel AI Gateway @@ -356,12 +358,12 @@ configuração em `models.providers`; basta definir a autenticação + escolher - 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 estático de fallback inclui `kilocode/kilo/auto`; a descoberta ao vivo em +- Base URL: `https://api.kilo.ai/api/gateway/` +- O catálogo estático de fallback inclui `kilocode/kilo/auto`; a descoberta live 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` pertence ao Kilo Gateway, - não é codificado diretamente no OpenClaw. + de runtime. +- O roteamento upstream exato por trás de `kilocode/kilo/auto` é controlado pelo Kilo Gateway, + não codificado estaticamente no OpenClaw. Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de configuração. @@ -369,26 +371,25 @@ Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de confi - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Modelo de exemplo: `openrouter/auto` -- O OpenClaw aplica os cabeçalhos documentados de atribuição de aplicativo do OpenRouter apenas quando - a solicitação realmente é direcionada para `openrouter.ai` -- Os marcadores `cache_control` específicos do Anthropic no OpenRouter também são restritos a - rotas OpenRouter verificadas, não a URLs arbitrárias de proxy -- O OpenRouter continua no caminho compatível com OpenAI em estilo proxy, então a - modelagem nativa de solicitação exclusiva do OpenAI (`serviceTier`, `store` do Responses, - dicas de cache de prompt, payloads de compatibilidade de raciocínio do OpenAI) não é encaminhada -- Referências OpenRouter baseadas em Gemini mantêm apenas o saneamento de assinatura de pensamento do Gemini por proxy; - a validação nativa de replay do Gemini e as regravações de bootstrap permanecem desativadas +- O OpenClaw aplica os cabeçalhos documentados de atribuição de app do OpenRouter apenas quando + a requisição realmente tem `openrouter.ai` como destino +- Os marcadores `cache_control` específicos do OpenRouter para Anthropic também são restritos a + rotas OpenRouter verificadas, não a URLs de proxy arbitrárias +- O OpenRouter permanece no caminho no estilo proxy compatível com OpenAI, portanto + a modelagem de requisição exclusiva do OpenAI nativo (`serviceTier`, `store` do Responses, + dicas de cache de prompt, payloads de compatibilidade de raciocínio da OpenAI) não é encaminhada +- Referências OpenRouter baseadas em Gemini mantêm apenas a sanitização de assinatura de pensamento Gemini por proxy; + a validação nativa de replay Gemini e reescritas de bootstrap continuam desativadas - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Modelo de exemplo: `kilocode/kilo/auto` -- Referências Kilo baseadas em Gemini mantêm o mesmo caminho de saneamento de assinatura - de pensamento do Gemini por proxy; `kilocode/kilo/auto` e outras dicas de proxy sem suporte a raciocínio - pulam a injeção de raciocínio por proxy +- Referências Kilo baseadas em Gemini mantêm o mesmo caminho de sanitização de assinatura de pensamento Gemini por proxy; + `kilocode/kilo/auto` e outras dicas em que o raciocínio por proxy não é compatível ignoram a injeção de raciocínio por proxy - MiniMax: `minimax` (chave de API) e `minimax-portal` (OAuth) - Autenticação: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` ou `MINIMAX_API_KEY` para `minimax-portal` - Modelo de exemplo: `minimax/MiniMax-M2.7` ou `minimax-portal/MiniMax-M2.7` -- A integração/configuração com chave de API do MiniMax grava definições explícitas do modelo M2.7 com +- A configuração por onboarding/chave de API do MiniMax grava definições explícitas de modelo M2.7 com `input: ["text", "image"]`; o catálogo do provedor incluído mantém as referências de chat - apenas como texto até que essa configuração do provedor seja materializada + apenas como texto até que a configuração desse provedor seja materializada - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Modelo de exemplo: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` ou `KIMICODE_API_KEY`) @@ -414,8 +415,8 @@ Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de confi - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) - Modelo de exemplo: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - - Solicitações xAI nativas incluídas usam o caminho xAI Responses - - `/fast` ou `params.fastMode: true` reescreve `grok-3`, `grok-3-mini`, + - Requisições xAI nativas incluídas usam o caminho xAI Responses + - `/fast` ou `params.fastMode: true` reescrevem `grok-3`, `grok-3-mini`, `grok-4` e `grok-4-0709` para suas variantes `*-fast` - `tool_stream` vem ativado por padrão; defina `agents.defaults.models["xai/"].params.tool_stream` como `false` para @@ -425,25 +426,25 @@ Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de confi - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Modelos GLM no Cerebras usam IDs `zai-glm-4.7` e `zai-glm-4.6`. - - URL base compatível com OpenAI: `https://api.cerebras.ai/v1`. + - Modelos GLM no Cerebras usam os IDs `zai-glm-4.7` e `zai-glm-4.6`. + - Base URL compatível com OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Modelo de exemplo do Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Consulte [Hugging Face (Inference)](/pt-BR/providers/huggingface). -## Provedores via `models.providers` (personalizado/URL base) +## Provedores via `models.providers` (base URL/personalizado) 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.` somente quando quiser substituir a -URL base, os cabeçalhos ou a lista de modelos padrão. +Use entradas explícitas em `models.providers.` apenas quando quiser substituir +a base URL, os cabeçalhos ou a lista de modelos padrão. ### Moonshot AI (Kimi) -O Moonshot é distribuído como um plugin de provedor incluído. Use o provedor incluído por -padrão e adicione uma entrada explícita `models.providers.moonshot` somente quando -precisar substituir a URL base ou os metadados do modelo: +O 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 base URL ou os metadados do modelo: - Provedor: `moonshot` - Autenticação: `MOONSHOT_API_KEY` @@ -482,7 +483,7 @@ IDs de modelo Kimi K2: ### Kimi Coding -O Kimi Coding usa o endpoint compatível com Anthropic do Moonshot AI: +O Kimi Coding usa o endpoint compatível com Anthropic da Moonshot AI: - Provedor: `kimi` - Autenticação: `KIMI_API_KEY` @@ -501,7 +502,7 @@ O legado `kimi/k2p5` continua aceito como ID de modelo de compatibilidade. ### Volcano Engine (Doubao) -O Volcano Engine (火山引擎) fornece acesso ao Doubao e a outros modelos na China. +O Volcano Engine (火山引擎) fornece acesso ao Doubao e outros modelos na China. - Provedor: `volcengine` (coding: `volcengine-plan`) - Autenticação: `VOLCANO_ENGINE_API_KEY` @@ -516,10 +517,10 @@ O Volcano Engine (火山引擎) fornece acesso ao Doubao e a outros modelos na C } ``` -A integração usa por padrão a superfície de coding, mas o catálogo geral `volcengine/*` +O onboarding usa por padrão a superfície de coding, mas o catálogo geral `volcengine/*` é registrado ao mesmo tempo. -Nos seletores de modelo de integração/configuração, a escolha de autenticação do Volcengine prioriza linhas +Nos seletores de onboarding/configuração de modelo, a escolha de autenticação do 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 com escopo de provedor. @@ -540,9 +541,9 @@ Modelos de coding (`volcengine-plan`): - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (Internacional) +### BytePlus (internacional) -O BytePlus ARK fornece acesso aos mesmos modelos que o Volcano Engine para usuários internacionais. +O BytePlus ARK fornece acesso aos mesmos modelos do Volcano Engine para usuários internacionais. - Provedor: `byteplus` (coding: `byteplus-plan`) - Autenticação: `BYTEPLUS_API_KEY` @@ -557,10 +558,10 @@ O BytePlus ARK fornece acesso aos mesmos modelos que o Volcano Engine para usuá } ``` -A integração usa por padrão a superfície de coding, mas o catálogo geral `byteplus/*` +O onboarding usa por padrão a superfície de coding, mas o catálogo geral `byteplus/*` é registrado ao mesmo tempo. -Nos seletores de modelo de integração/configuração, a escolha de autenticação do BytePlus prioriza linhas +Nos seletores de onboarding/configuração de modelo, a escolha de autenticação do 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 com escopo de provedor. @@ -618,30 +619,52 @@ O MiniMax é configurado via `models.providers` porque usa endpoints personaliza - Autenticação: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` ou `MINIMAX_API_KEY` para `minimax-portal` -Consulte [/providers/minimax](/pt-BR/providers/minimax) para detalhes de configuração, opções de modelo e trechos de configuração. +Consulte [/providers/minimax](/pt-BR/providers/minimax) para detalhes de configuração, opções de modelo e snippets de configuração. -No caminho de streaming compatível com Anthropic do MiniMax, o OpenClaw desativa o thinking por +No caminho de streaming compatível com Anthropic do MiniMax, o OpenClaw desativa thinking por padrão, a menos que você o defina explicitamente, e `/fast on` reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`. -Divisão de capacidades sob posse do plugin: +Divisão de capacidade controlada por plugin: - Os padrões de texto/chat permanecem em `minimax/MiniMax-M2.7` - A geração de imagem é `minimax/image-01` ou `minimax-portal/image-01` -- A compreensão de imagem é `MiniMax-VL-01`, sob posse do plugin, em ambos os caminhos de autenticação MiniMax -- A busca na web permanece no ID de provedor `minimax` +- O entendimento de imagem é `MiniMax-VL-01`, controlado por plugin, em ambos os caminhos de autenticação MiniMax +- A pesquisa na web permanece no ID de provedor `minimax` + +### LM Studio + +O LM Studio é distribuído como um plugin de provedor incluído que usa a API nativa: + +- Provedor: `lmstudio` +- Autenticação: `LM_API_TOKEN` +- Base URL padrão de inferência: `http://localhost:1234/v1` + +Em seguida, defina um modelo (substitua por um dos IDs retornados por `http://localhost:1234/api/v1/models`): + +```json5 +{ + agents: { + defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } }, + }, +} +``` + +O OpenClaw usa os endpoints nativos do LM Studio `/api/v1/models` e `/api/v1/models/load` +para descoberta + carregamento automático, com `/v1/chat/completions` para inferência por padrão. +Consulte [/providers/lmstudio](/pt-BR/providers/lmstudio) para configuração e solução de problemas. ### Ollama O Ollama é distribuído como um plugin de provedor incluído e usa a API nativa do Ollama: - Provedor: `ollama` -- Autenticação: não obrigatória (servidor local) +- Autenticação: nenhuma necessária (servidor local) - Modelo de exemplo: `ollama/llama3.3` - Instalação: [https://ollama.com/download](https://ollama.com/download) ```bash -# Instale o Ollama e depois baixe um modelo: +# Instale o Ollama e, em seguida, baixe um modelo: ollama pull llama3.3 ``` @@ -653,19 +676,19 @@ ollama pull llama3.3 } ``` -O Ollama é detectado localmente em `http://127.0.0.1:11434` quando você ativa com +O Ollama é detectado localmente em `http://127.0.0.1:11434` quando você ativa o uso com `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](/pt-BR/providers/ollama) -para integração, modo em nuvem/local e configuração personalizada. +`openclaw onboard` e ao seletor de modelo. Consulte [/providers/ollama](/pt-BR/providers/ollama) +para onboarding, modo cloud/local e configuração personalizada. ### vLLM -O vLLM é distribuído como um plugin de provedor incluído para servidores -locais/self-hosted compatíveis com OpenAI: +O vLLM é distribuído como um plugin de provedor incluído para servidores locais/self-hosted +compatíveis com OpenAI: - Provedor: `vllm` - Autenticação: opcional (depende do seu servidor) -- URL base padrão: `http://127.0.0.1:8000/v1` +- Base URL padrão: `http://127.0.0.1:8000/v1` Para ativar a descoberta automática localmente (qualquer valor funciona se o seu servidor não exigir autenticação): @@ -673,7 +696,7 @@ Para ativar a descoberta automática localmente (qualquer valor funciona se o se export VLLM_API_KEY="vllm-local" ``` -Depois defina um modelo (substitua por um dos IDs retornados por `/v1/models`): +Em seguida, defina um modelo (substitua por um dos IDs retornados por `/v1/models`): ```json5 { @@ -683,25 +706,25 @@ Depois defina um modelo (substitua por um dos IDs retornados por `/v1/models`): } ``` -Consulte [/providers/vllm](/pt-BR/providers/vllm) para detalhes. +Consulte [/providers/vllm](/pt-BR/providers/vllm) para mais detalhes. ### SGLang -O SGLang é distribuído como um plugin de provedor incluído para servidores -self-hosted rápidos compatíveis com OpenAI: +O SGLang é distribuído como um plugin de provedor incluído para servidores self-hosted +rápidos compatíveis com OpenAI: - Provedor: `sglang` - Autenticação: opcional (depende do seu servidor) -- URL base padrão: `http://127.0.0.1:30000/v1` +- Base URL padrão: `http://127.0.0.1:30000/v1` -Para ativar a descoberta automática localmente (qualquer valor funciona se o seu servidor não -exigir autenticação): +Para ativar a descoberta automática localmente (qualquer valor funciona se o seu servidor não exigir +autenticação): ```bash export SGLANG_API_KEY="sglang-local" ``` -Depois defina um modelo (substitua por um dos IDs retornados por `/v1/models`): +Em seguida, defina um modelo (substitua por um dos IDs retornados por `/v1/models`): ```json5 { @@ -711,7 +734,7 @@ Depois defina um modelo (substitua por um dos IDs retornados por `/v1/models`): } ``` -Consulte [/providers/sglang](/pt-BR/providers/sglang) para detalhes. +Consulte [/providers/sglang](/pt-BR/providers/sglang) para mais detalhes. ### Proxies locais (LM Studio, vLLM, LiteLLM etc.) @@ -729,7 +752,7 @@ Exemplo (compatível com OpenAI): providers: { lmstudio: { baseUrl: "http://localhost:1234/v1", - apiKey: "LMSTUDIO_KEY", + apiKey: "${LM_API_TOKEN}", api: "openai-completions", models: [ { @@ -751,17 +774,17 @@ Exemplo (compatível com OpenAI): Observações: - Para provedores personalizados, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` são opcionais. - Quando omitidos, o OpenClaw usa por padrão: + Quando omitidos, o OpenClaw usa os seguintes padrões: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` - Recomendado: defina valores explícitos que correspondam aos limites do seu proxy/modelo. -- Para `api: "openai-completions"` em endpoints não nativos (qualquer `baseUrl` não vazio cujo host não seja `api.openai.com`), o OpenClaw força `compat.supportsDeveloperRole: false` para evitar erros 400 do provedor por funções `developer` não compatíveis. -- Rotas compatíveis com OpenAI em estilo proxy também pulam a modelagem nativa de solicitação exclusiva do OpenAI: sem `service_tier`, sem `store` do Responses, sem dicas de cache de prompt, sem modelagem de payload de compatibilidade de raciocínio do OpenAI e sem cabeçalhos ocultos de atribuição do OpenClaw. +- Para `api: "openai-completions"` em endpoints não nativos (qualquer `baseUrl` não vazio cujo host não seja `api.openai.com`), o OpenClaw força `compat.supportsDeveloperRole: false` para evitar erros 400 do provedor por papéis `developer` não compatíveis. +- Rotas compatíveis com OpenAI no estilo proxy também ignoram a modelagem de requisição exclusiva do OpenAI nativo: sem `service_tier`, sem `store` do Responses, sem dicas de cache de prompt, sem modelagem de payload de compatibilidade de raciocínio da OpenAI e sem cabeçalhos ocultos de atribuição do OpenClaw. - Se `baseUrl` estiver vazio/omitido, o OpenClaw mantém o comportamento padrão da OpenAI (que resolve para `api.openai.com`). -- Por segurança, um `compat.supportsDeveloperRole: true` explícito ainda é substituído em endpoints não nativos `openai-completions`. +- Por segurança, um `compat.supportsDeveloperRole: true` explícito ainda é sobrescrito em endpoints `openai-completions` não nativos. ## Exemplos de CLI diff --git a/docs/pt-BR/gateway/local-models.md b/docs/pt-BR/gateway/local-models.md index b43524633..3d8561811 100644 --- a/docs/pt-BR/gateway/local-models.md +++ b/docs/pt-BR/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - - Você quer servir modelos a partir da sua própria máquina com GPU - - Você está configurando o LM Studio ou um proxy compatível com OpenAI - - Você precisa da orientação mais segura para modelos locais + - Você quer servir modelos a partir da sua própria máquina com GPU. + - Você está configurando o LM Studio ou um proxy compatível com OpenAI. + - Você precisa das orientações mais seguras para modelos locais. summary: Execute o OpenClaw em LLMs locais (LM Studio, vLLM, LiteLLM, endpoints OpenAI personalizados) title: Modelos locais x-i18n: - generated_at: "2026-04-08T02:14:58Z" + generated_at: "2026-04-13T08:50:40Z" model: gpt-5.4 provider: openai - source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8 + source_hash: 3ecb61b3e6e34d3666f9b688cd694d92c5fb211cf8c420fa876f7ccf5789154a source_path: gateway/local-models.md workflow: 15 --- # Modelos locais -Executar localmente é viável, mas o OpenClaw espera contexto grande + defesas fortes contra injeção de prompt. Placas pequenas truncam o contexto e enfraquecem a segurança. Mire alto: **≥2 Mac Studios no máximo ou rig de GPU equivalente (~US$30 mil+)**. Uma única GPU de **24 GB** funciona apenas para prompts mais leves, com maior latência. Use a **maior variante / variante completa do modelo que você conseguir executar**; checkpoints agressivamente quantizados ou “pequenos” aumentam o risco de injeção de prompt (consulte [Security](/pt-BR/gateway/security)). +Local é viável, mas o OpenClaw espera contexto grande + defesas robustas contra injeção de prompt. Placas menores truncam o contexto e enfraquecem a segurança. Mire alto: **≥2 Mac Studios no máximo ou rig de GPU equivalente (~US$ 30 mil+)**. Uma única GPU de **24 GB** funciona apenas para prompts mais leves, com latência mais alta. Use a **maior / variante de tamanho completo do modelo que você conseguir executar**; checkpoints agressivamente quantizados ou “small” aumentam o risco de injeção de prompt (veja [Segurança](/pt-BR/gateway/security)). -Se você quiser a configuração local com menos atrito, comece com [Ollama](/pt-BR/providers/ollama) e `openclaw onboard`. Esta página é o guia opinativo para stacks locais mais avançadas e servidores locais personalizados compatíveis com OpenAI. +Se você quiser a configuração local com menos atrito, comece com [LM Studio](/pt-BR/providers/lmstudio) ou [Ollama](/pt-BR/providers/ollama) e `openclaw onboard`. Esta página é o guia opinativo para stacks locais mais avançadas e servidores locais personalizados compatíveis com OpenAI. ## Recomendado: LM Studio + modelo local grande (API Responses) -A melhor stack local atual. Carregue um modelo grande no LM Studio (por exemplo, uma build completa de Qwen, DeepSeek ou Llama), habilite o servidor local (padrão `http://127.0.0.1:1234`) e use a API Responses para manter o raciocínio separado do texto final. +Melhor stack local no momento. Carregue um modelo grande no LM Studio (por exemplo, uma build completa de Qwen, DeepSeek ou Llama), ative o servidor local (padrão `http://127.0.0.1:1234`) e use a API Responses para manter o raciocínio separado do texto final. ```json5 { @@ -45,7 +45,7 @@ A melhor stack local atual. Carregue um modelo grande no LM Studio (por exemplo, models: [ { id: “my-local-model”, - name: “Local Model”, + name: “Modelo Local”, reasoning: false, input: [“text”], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -62,11 +62,11 @@ A melhor stack local atual. Carregue um modelo grande no LM Studio (por exemplo, **Checklist de configuração** - Instale o LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- No LM Studio, baixe a **maior build de modelo disponível** (evite variantes “small”/fortemente quantizadas), inicie o servidor e confirme que `http://127.0.0.1:1234/v1/models` a lista. +- No LM Studio, baixe a **maior build de modelo disponível** (evite variantes “small”/fortemente quantizadas), inicie o servidor e confirme que `http://127.0.0.1:1234/v1/models` o lista. - Substitua `my-local-model` pelo ID real do modelo mostrado no LM Studio. -- Mantenha o modelo carregado; carregamento a frio adiciona latência de inicialização. +- Mantenha o modelo carregado; o carregamento a frio adiciona latência de inicialização. - Ajuste `contextWindow`/`maxTokens` se a sua build do LM Studio for diferente. -- Para o WhatsApp, use a API Responses para que apenas o texto final seja enviado. +- Para WhatsApp, mantenha a API Responses para que apenas o texto final seja enviado. Mantenha modelos hospedados configurados mesmo ao executar localmente; use `models.mode: "merge"` para que os fallbacks continuem disponíveis. @@ -97,7 +97,7 @@ Mantenha modelos hospedados configurados mesmo ao executar localmente; use `mode models: [ { id: "my-local-model", - name: "Local Model", + name: "Modelo Local", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -113,16 +113,16 @@ Mantenha modelos hospedados configurados mesmo ao executar localmente; use `mode ### Local primeiro com rede de segurança hospedada -Inverta a ordem do primário e dos fallbacks; mantenha o mesmo bloco `providers` e `models.mode: "merge"` para poder recorrer ao Sonnet ou ao Opus quando a máquina local estiver indisponível. +Troque a ordem do primário e dos fallbacks; mantenha o mesmo bloco de providers e `models.mode: "merge"` para poder recorrer a Sonnet ou Opus quando a máquina local estiver fora do ar. ### Hospedagem regional / roteamento de dados -- Variantes hospedadas de MiniMax/Kimi/GLM também existem no OpenRouter com endpoints fixados por região (por exemplo, hospedados nos EUA). Escolha ali a variante regional para manter o tráfego na jurisdição desejada, ainda usando `models.mode: "merge"` para fallbacks de Anthropic/OpenAI. -- Local-only continua sendo o caminho mais forte em privacidade; o roteamento regional hospedado é o meio-termo quando você precisa de recursos do provider, mas quer controle sobre o fluxo de dados. +- Variantes hospedadas de MiniMax/Kimi/GLM também existem no OpenRouter com endpoints fixados por região (por exemplo, hospedados nos EUA). Escolha a variante regional lá para manter o tráfego na jurisdição desejada enquanto ainda usa `models.mode: "merge"` para fallbacks de Anthropic/OpenAI. +- Somente local continua sendo o caminho mais forte em privacidade; roteamento regional hospedado é o meio-termo quando você precisa de recursos do provider, mas quer controlar o fluxo de dados. ## Outros proxies locais compatíveis com OpenAI -vLLM, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um endpoint `/v1` no estilo OpenAI. Substitua o bloco do provider acima pelo seu endpoint e ID de modelo: +vLLM, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um endpoint `/v1` no estilo OpenAI. Substitua o bloco do provider acima pelo seu endpoint e ID do modelo: ```json5 { @@ -136,7 +136,7 @@ vLLM, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um en models: [ { id: "my-local-model", - name: "Local Model", + name: "Modelo Local", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -155,36 +155,21 @@ Mantenha `models.mode: "merge"` para que os modelos hospedados continuem dispon Observação de comportamento para backends `/v1` locais/com proxy: - O OpenClaw trata esses backends como rotas compatíveis com OpenAI no estilo proxy, não como endpoints OpenAI nativos -- a formatação de requisição exclusiva do OpenAI nativo não se aplica aqui: sem - `service_tier`, sem `store` do Responses, sem formatação de payload de - compatibilidade de raciocínio do OpenAI e sem dicas de cache de prompt -- cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, `User-Agent`) - não são injetados nessas URLs de proxy personalizadas +- a formatação de requisição exclusiva do OpenAI nativo não se aplica aqui: sem `service_tier`, sem `store` da Responses, sem formatação de payload de compatibilidade de raciocínio do OpenAI e sem dicas de cache de prompt +- cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, `User-Agent`) não são injetados nessas URLs de proxy personalizadas -Observações de compatibilidade para backends compatíveis com OpenAI mais restritos: +Notas de compatibilidade para backends compatíveis com OpenAI mais rígidos: -- Alguns servidores aceitam apenas `messages[].content` em formato string no Chat Completions, e não - arrays estruturados de partes de conteúdo. Defina - `models.providers..models[].compat.requiresStringContent: true` para - esses endpoints. -- Alguns backends locais menores ou mais restritos são instáveis com o formato completo de prompt - do runtime de agente do OpenClaw, especialmente quando esquemas de ferramentas são incluídos. Se o - backend funciona para chamadas diretas pequenas em `/v1/chat/completions`, mas falha em turnos normais - de agente do OpenClaw, tente primeiro - `models.providers..models[].compat.supportsTools: false`. -- Se o backend ainda falhar apenas em execuções maiores do OpenClaw, o problema restante - normalmente está na capacidade do modelo/servidor upstream ou em um bug do backend, e não na camada - de transporte do OpenClaw. +- Alguns servidores aceitam apenas `messages[].content` como string em Chat Completions, e não arrays estruturados de partes de conteúdo. Defina `models.providers..models[].compat.requiresStringContent: true` para esses endpoints. +- Alguns backends locais menores ou mais rígidos são instáveis com o formato completo de prompt do runtime de agentes do OpenClaw, especialmente quando esquemas de ferramentas estão incluídos. Se o backend funcionar para chamadas diretas pequenas de `/v1/chat/completions`, mas falhar em turnos normais de agentes do OpenClaw, tente primeiro `models.providers..models[].compat.supportsTools: false`. +- Se o backend ainda falhar apenas em execuções maiores do OpenClaw, o problema restante normalmente é capacidade do modelo/servidor upstream ou um bug do backend, não da camada de transporte do OpenClaw. ## Solução de problemas -- O gateway consegue alcançar o proxy? `curl http://127.0.0.1:1234/v1/models`. -- Modelo descarregado no LM Studio? Recarregue; inicialização a frio é uma causa comum de “travamento”. +- O Gateway consegue alcançar o proxy? `curl http://127.0.0.1:1234/v1/models`. +- Modelo do LM Studio descarregado? Recarregue; inicialização a frio é uma causa comum de “travamento”. - Erros de contexto? Reduza `contextWindow` ou aumente o limite do seu servidor. - O servidor compatível com OpenAI retorna `messages[].content ... expected a string`? Adicione `compat.requiresStringContent: true` nessa entrada de modelo. -- Chamadas diretas pequenas em `/v1/chat/completions` funcionam, mas `openclaw infer model run` - falha no Gemma ou em outro modelo local? Primeiro desative esquemas de ferramentas com - `compat.supportsTools: false` e teste novamente. Se o servidor ainda falhar apenas - em prompts maiores do OpenClaw, trate isso como uma limitação do modelo/servidor upstream. -- Segurança: modelos locais ignoram filtros do provider; mantenha os agentes estreitos e a compactação ativada para limitar o raio de impacto de injeção de prompt. +- Chamadas diretas pequenas de `/v1/chat/completions` funcionam, mas `openclaw infer model run` falha em Gemma ou outro modelo local? Desative primeiro os esquemas de ferramentas com `compat.supportsTools: false` e teste novamente. Se o servidor ainda travar apenas em prompts maiores do OpenClaw, trate isso como uma limitação do servidor/modelo upstream. +- Segurança: modelos locais ignoram filtros do provider; mantenha os agentes restritos e a Compaction ativada para limitar o raio de impacto da injeção de prompt. diff --git a/docs/pt-BR/providers/index.md b/docs/pt-BR/providers/index.md index 104b894d6..d682974bc 100644 --- a/docs/pt-BR/providers/index.md +++ b/docs/pt-BR/providers/index.md @@ -3,22 +3,22 @@ read_when: - Você quer escolher um provedor de modelo - Você precisa de uma visão geral rápida dos backends de LLM compatíveis summary: Provedores de modelo (LLMs) compatíveis com o OpenClaw -title: Diretório de Provedores +title: Diretório de provedores x-i18n: - generated_at: "2026-04-08T02:17:27Z" + generated_at: "2026-04-13T08:50:33Z" model: gpt-5.4 provider: openai - source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70 + source_hash: 3bc682d008119719826f71f74959ab32bedf14214459f5e6ac9cb70371d3c540 source_path: providers/index.md workflow: 15 --- -# Provedores de Modelo +# Provedores de modelo O OpenClaw pode usar muitos provedores de LLM. Escolha um provedor, autentique-se e depois defina o modelo padrão como `provider/model`. -Procurando a documentação de canais de chat (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/etc.)? Veja [Channels](/pt-BR/channels). +Está procurando a documentação dos canais de chat (WhatsApp/Telegram/Discord/Slack/Mattermost (Plugin)/etc.)? Veja [Channels](/pt-BR/channels). ## Início rápido @@ -45,13 +45,14 @@ Procurando a documentação de canais de chat (WhatsApp/Telegram/Discord/Slack/M - [fal](/pt-BR/providers/fal) - [Fireworks](/pt-BR/providers/fireworks) - [GitHub Copilot](/pt-BR/providers/github-copilot) -- [modelos GLM](/pt-BR/providers/glm) +- [Modelos GLM](/pt-BR/providers/glm) - [Google (Gemini)](/pt-BR/providers/google) - [Groq (inferência LPU)](/pt-BR/providers/groq) - [Hugging Face (Inference)](/pt-BR/providers/huggingface) - [inferrs (modelos locais)](/pt-BR/providers/inferrs) - [Kilocode](/pt-BR/providers/kilocode) -- [LiteLLM (gateway unificado)](/pt-BR/providers/litellm) +- [LiteLLM (Gateway unificado)](/pt-BR/providers/litellm) +- [LM Studio (modelos locais)](/pt-BR/providers/lmstudio) - [MiniMax](/pt-BR/providers/minimax) - [Mistral](/pt-BR/providers/mistral) - [Moonshot AI (Kimi + Kimi Coding)](/pt-BR/providers/moonshot) @@ -61,7 +62,7 @@ Procurando a documentação de canais de chat (WhatsApp/Telegram/Discord/Slack/M - [OpenCode](/pt-BR/providers/opencode) - [OpenCode Go](/pt-BR/providers/opencode-go) - [OpenRouter](/pt-BR/providers/openrouter) -- [Perplexity (busca na web)](/pt-BR/providers/perplexity-provider) +- [Perplexity (pesquisa na web)](/pt-BR/providers/perplexity-provider) - [Qianfan](/pt-BR/providers/qianfan) - [Qwen Cloud](/pt-BR/providers/qwen) - [Runway](/pt-BR/providers/runway) @@ -78,12 +79,12 @@ Procurando a documentação de canais de chat (WhatsApp/Telegram/Discord/Slack/M - [Xiaomi](/pt-BR/providers/xiaomi) - [Z.AI](/pt-BR/providers/zai) -## Páginas gerais compartilhadas +## Páginas de visão geral compartilhadas -- [Variantes incluídas adicionais](/pt-BR/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy e Gemini CLI OAuth -- [Geração de Imagens](/pt-BR/tools/image-generation) - ferramenta compartilhada `image_generate`, seleção de provedor e failover -- [Geração de Música](/pt-BR/tools/music-generation) - ferramenta compartilhada `music_generate`, seleção de provedor e failover -- [Geração de Vídeo](/pt-BR/tools/video-generation) - ferramenta compartilhada `video_generate`, seleção de provedor e failover +- [Variantes adicionais incluídas](/pt-BR/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy e Gemini CLI OAuth +- [Geração de imagens](/pt-BR/tools/image-generation) - Ferramenta compartilhada `image_generate`, seleção de provedor e failover +- [Geração de música](/pt-BR/tools/music-generation) - Ferramenta compartilhada `music_generate`, seleção de provedor e failover +- [Geração de vídeo](/pt-BR/tools/video-generation) - Ferramenta compartilhada `video_generate`, seleção de provedor e failover ## Provedores de transcrição @@ -91,7 +92,7 @@ Procurando a documentação de canais de chat (WhatsApp/Telegram/Discord/Slack/M ## Ferramentas da comunidade -- [Claude Max API Proxy](/pt-BR/providers/claude-max-api-proxy) - Proxy da comunidade para credenciais de assinatura do Claude (verifique a política/termos da Anthropic antes de usar) +- [Claude Max API Proxy](/pt-BR/providers/claude-max-api-proxy) - Proxy da comunidade para credenciais de assinatura do Claude (verifique a política/os termos da Anthropic antes de usar) -Para o catálogo completo de provedores (xAI, Groq, Mistral etc.) e configuração avançada, -veja [provedores de modelo](/pt-BR/concepts/model-providers). +Para o catálogo completo de provedores (xAI, Groq, Mistral etc.) e a configuração avançada, +veja [Provedores de modelo](/pt-BR/concepts/model-providers). diff --git a/docs/pt-BR/providers/lmstudio.md b/docs/pt-BR/providers/lmstudio.md new file mode 100644 index 000000000..5cd2fabaf --- /dev/null +++ b/docs/pt-BR/providers/lmstudio.md @@ -0,0 +1,163 @@ +--- +read_when: + - Você quer executar o OpenClaw com modelos de código aberto via LM Studio + - Você quer configurar o LM Studio +summary: Execute o OpenClaw com o LM Studio +title: LM Studio +x-i18n: + generated_at: "2026-04-13T08:50:33Z" + model: gpt-5.4 + provider: openai + source_hash: 11264584e8277260d4215feb7c751329ce04f59e9228da1c58e147c21cd9ac2c + source_path: providers/lmstudio.md + workflow: 15 +--- + +# LM Studio + +O LM Studio é um aplicativo amigável, porém poderoso, para executar modelos com pesos abertos no seu próprio hardware. Ele permite executar modelos llama.cpp (GGUF) ou MLX (Apple Silicon). Está disponível em um pacote com GUI ou como daemon headless (`llmster`). Para documentação do produto e de configuração, consulte [lmstudio.ai](https://lmstudio.ai/). + +## Início rápido + +1. Instale o LM Studio (desktop) ou o `llmster` (headless) e, em seguida, inicie o servidor local: + +```bash +curl -fsSL https://lmstudio.ai/install.sh | bash +``` + +2. Inicie o servidor + +Certifique-se de iniciar o aplicativo desktop ou executar o daemon usando o seguinte comando: + +```bash +lms daemon up +``` + +```bash +lms server start --port 1234 +``` + +Se você estiver usando o aplicativo, certifique-se de ter o JIT habilitado para uma experiência fluida. Saiba mais no [guia de JIT e TTL do LM Studio](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict). + +3. O OpenClaw requer um valor de token do LM Studio. Defina `LM_API_TOKEN`: + +```bash +export LM_API_TOKEN="your-lm-studio-api-token" +``` + +Se a autenticação do LM Studio estiver desativada, use qualquer valor de token não vazio: + +```bash +export LM_API_TOKEN="placeholder-key" +``` + +Para detalhes de configuração da autenticação do LM Studio, consulte [Autenticação do LM Studio](https://lmstudio.ai/docs/developer/core/authentication). + +4. Execute o onboarding e escolha `LM Studio`: + +```bash +openclaw onboard +``` + +5. No onboarding, use o prompt `Default model` para escolher seu modelo do LM Studio. + +Você também pode defini-lo ou alterá-lo depois: + +```bash +openclaw models set lmstudio/qwen/qwen3.5-9b +``` + +As chaves de modelo do LM Studio seguem o formato `author/model-name` (por exemplo, `qwen/qwen3.5-9b`). As referências de modelo do OpenClaw adicionam o nome do provedor antes: `lmstudio/qwen/qwen3.5-9b`. Você pode encontrar a chave exata de um modelo executando `curl http://localhost:1234/api/v1/models` e procurando o campo `key`. + +## Onboarding não interativo + +Use o onboarding não interativo quando quiser automatizar a configuração (CI, provisionamento, bootstrap remoto): + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio +``` + +Ou especifique a URL base ou o modelo com chave de API: + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio \ + --custom-base-url http://localhost:1234/v1 \ + --lmstudio-api-key "$LM_API_TOKEN" \ + --custom-model-id qwen/qwen3.5-9b +``` + +`--custom-model-id` recebe a chave do modelo retornada pelo LM Studio (por exemplo, `qwen/qwen3.5-9b`), sem o prefixo de provedor `lmstudio/`. + +O onboarding não interativo exige `--lmstudio-api-key` (ou `LM_API_TOKEN` no ambiente). +Para servidores LM Studio sem autenticação, qualquer valor de token não vazio funciona. + +`--custom-api-key` continua compatível por razões de compatibilidade, mas `--lmstudio-api-key` é o preferido para o LM Studio. + +Isso grava `models.providers.lmstudio`, define o modelo padrão como +`lmstudio/` e grava o perfil de autenticação `lmstudio:default`. + +A configuração interativa pode solicitar um comprimento de contexto de carregamento preferido opcional e aplicá-lo aos modelos do LM Studio descobertos que ela salva na configuração. + +## Configuração + +### Configuração explícita + +```json5 +{ + models: { + providers: { + lmstudio: { + baseUrl: "http://localhost:1234/v1", + apiKey: "${LM_API_TOKEN}", + api: "openai-completions", + models: [ + { + id: "qwen/qwen3-coder-next", + name: "Qwen 3 Coder Next", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 128000, + maxTokens: 8192, + }, + ], + }, + }, + }, +} +``` + +## Solução de problemas + +### LM Studio não detectado + +Certifique-se de que o LM Studio está em execução e de que você definiu `LM_API_TOKEN` (para servidores sem autenticação, qualquer valor de token não vazio funciona): + +```bash +# Inicie pelo aplicativo desktop ou em modo headless: +lms server start --port 1234 +``` + +Verifique se a API está acessível: + +```bash +curl http://localhost:1234/api/v1/models +``` + +### Erros de autenticação (HTTP 401) + +Se a configuração relatar HTTP 401, verifique sua chave de API: + +- Verifique se `LM_API_TOKEN` corresponde à chave configurada no LM Studio. +- Para detalhes de configuração da autenticação do LM Studio, consulte [Autenticação do LM Studio](https://lmstudio.ai/docs/developer/core/authentication). +- Se o seu servidor não exigir autenticação, use qualquer valor de token não vazio para `LM_API_TOKEN`. + +### Carregamento de modelo just-in-time + +O LM Studio oferece suporte ao carregamento de modelo just-in-time (JIT), em que os modelos são carregados na primeira solicitação. Certifique-se de que isso esteja habilitado para evitar erros de "Model not loaded". diff --git a/docs/pt-BR/reference/api-usage-costs.md b/docs/pt-BR/reference/api-usage-costs.md index 4d23a77c7..afdb9cdf5 100644 --- a/docs/pt-BR/reference/api-usage-costs.md +++ b/docs/pt-BR/reference/api-usage-costs.md @@ -1,95 +1,94 @@ --- read_when: - Você quer entender quais recursos podem chamar APIs pagas - - Você precisa auditar chaves, custos e visibilidade de uso - - Você está explicando relatórios de custo de /status ou /usage + - Você precisa auditar chaves, custos e a visibilidade de uso + - Você está explicando o relatório de custos de /status ou /usage summary: Audite o que pode gerar custos, quais chaves são usadas e como visualizar o uso -title: Uso e custos de API +title: Uso e custos da API x-i18n: - generated_at: "2026-04-07T05:31:13Z" + generated_at: "2026-04-13T08:50:33Z" model: gpt-5.4 provider: openai - source_hash: ab6eefcde9ac014df6cdda7aaa77ef48f16936ab12eaa883d9fe69425a31a2dd + source_hash: f5077e74d38ef781ac7a72603e9f9e3829a628b95c5a9967915ab0f321565429 source_path: reference/api-usage-costs.md workflow: 15 --- -# Uso e custos de API +# Uso e custos da API Este documento lista **recursos que podem invocar chaves de API** e onde seus custos aparecem. Ele se concentra em -recursos do OpenClaw que podem gerar uso de provedor ou chamadas pagas de API. +recursos do OpenClaw que podem gerar uso de provedores ou chamadas pagas de API. ## Onde os custos aparecem (chat + CLI) -**Snapshot de custo por sessão** +**Instantâneo de custo por sessão** - `/status` mostra o modelo atual da sessão, o uso de contexto e os tokens da última resposta. -- Se o modelo usar **auth por chave de API**, `/status` também mostra o **custo estimado** da última resposta. -- Se os metadados live da sessão forem escassos, `/status` pode recuperar contadores - de tokens/cache e o rótulo do modelo de runtime ativo da entrada de uso mais recente - do transcript. Valores live existentes e diferentes de zero ainda têm precedência, e - totais do transcript no tamanho do prompt podem prevalecer quando os totais armazenados estiverem ausentes ou menores. +- Se o modelo usa **autenticação por chave de API**, `/status` também mostra o **custo estimado** da última resposta. +- Se os metadados da sessão em tempo real forem escassos, `/status` pode recuperar + contadores de tokens/cache e o rótulo do modelo de runtime ativo a partir da entrada + de uso mais recente da transcrição. Valores em tempo real não nulos existentes ainda têm prioridade, e totais da transcrição no tamanho do prompt podem prevalecer quando os totais armazenados estiverem ausentes ou forem menores. **Rodapé de custo por mensagem** - `/usage full` acrescenta um rodapé de uso a cada resposta, incluindo **custo estimado** (somente chave de API). -- `/usage tokens` mostra apenas tokens; fluxos de OAuth/token e CLI no estilo assinatura ocultam o custo em dólar. -- Observação sobre Gemini CLI: quando a CLI retorna saída JSON, o OpenClaw lê o uso de - `stats`, normaliza `stats.cached` em `cacheRead` e deriva tokens de entrada +- `/usage tokens` mostra apenas tokens; fluxos de OAuth/token no estilo assinatura e da CLI ocultam o custo em dólares. +- Observação sobre o Gemini CLI: quando a CLI retorna saída JSON, o OpenClaw lê o uso de + `stats`, normaliza `stats.cached` em `cacheRead` e deriva os tokens de entrada de `stats.input_tokens - stats.cached` quando necessário. -Observação sobre Anthropic: a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw é -permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como -permitidos para esta integração, a menos que a Anthropic publique uma nova política. +Observação sobre Anthropic: a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw está +novamente permitido, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como +autorizados para esta integração, a menos que a Anthropic publique uma nova política. A Anthropic ainda não expõe uma estimativa em dólares por mensagem que o OpenClaw possa mostrar em `/usage full`. **Janelas de uso da CLI (cotas do provedor)** -- `openclaw status --usage` e `openclaw channels list` mostram **janelas de uso** - do provedor (snapshots de cota, não custos por mensagem). -- A saída humana é normalizada para `X% left` entre provedores. +- `openclaw status --usage` e `openclaw channels list` mostram **janelas de uso** do provedor + (instantâneos de cota, não custos por mensagem). +- A saída legível por humanos é normalizada para `X% left` entre os provedores. - Provedores atuais de janela de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi e z.ai. -- Observação sobre MiniMax: os campos brutos `usage_percent` / `usagePercent` significam +- Observação sobre MiniMax: seus campos brutos `usage_percent` / `usagePercent` significam cota restante, então o OpenClaw os inverte antes da exibição. Campos baseados em contagem ainda têm prioridade - quando presentes. Se o provedor retornar `model_remains`, o OpenClaw prefere a entrada do modelo de chat, - deriva o rótulo da janela a partir de timestamps quando necessário e + quando presentes. Se o provedor retornar `model_remains`, o OpenClaw prefere a entrada + do modelo de chat, deriva o rótulo da janela a partir de timestamps quando necessário e inclui o nome do modelo no rótulo do plano. -- A auth de uso para essas janelas de cota vem de hooks específicos do provedor quando - disponíveis; caso contrário, o OpenClaw usa como fallback credenciais OAuth/chave de API - correspondentes de perfis auth, env ou config. +- A autenticação de uso para essas janelas de cota vem de hooks específicos do provedor quando + disponíveis; caso contrário, o OpenClaw recorre à correspondência de credenciais + OAuth/chave de API a partir de perfis de autenticação, ambiente ou configuração. -Consulte [Uso de tokens e custos](/pt-BR/reference/token-use) para detalhes e exemplos. +Consulte [Uso e custos de tokens](/pt-BR/reference/token-use) para detalhes e exemplos. ## Como as chaves são descobertas O OpenClaw pode obter credenciais de: -- **Perfis auth** (por agente, armazenados em `auth-profiles.json`). +- **Perfis de autenticação** (por agente, armazenados em `auth-profiles.json`). - **Variáveis de ambiente** (por exemplo, `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`). - **Configuração** (`models.providers.*.apiKey`, `plugins.entries.*.config.webSearch.apiKey`, `plugins.entries.firecrawl.config.webFetch.apiKey`, `memorySearch.*`, `talk.providers.*.apiKey`). -- **Skills** (`skills.entries..apiKey`) que podem exportar chaves para o env do processo da skill. +- **Skills** (`skills.entries..apiKey`), que podem exportar chaves para o ambiente do processo da skill. ## Recursos que podem consumir chaves ### 1) Respostas do modelo principal (chat + ferramentas) -Toda resposta ou chamada de ferramenta usa o **provedor de modelo atual** (OpenAI, Anthropic etc.). Esta é a +Cada resposta ou chamada de ferramenta usa o **provedor de modelo atual** (OpenAI, Anthropic etc.). Esta é a principal fonte de uso e custo. Isso também inclui provedores hospedados no estilo assinatura que ainda cobram fora da UI local do OpenClaw, como **OpenAI Codex**, **Alibaba Cloud Model Studio Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** e -o caminho de login Claude da Anthropic no OpenClaw com **Extra Usage** ativado. +o caminho Claude-login do OpenClaw da Anthropic com **Extra Usage** habilitado. -Consulte [Modelos](/pt-BR/providers/models) para configuração de preços e [Uso de tokens e custos](/pt-BR/reference/token-use) para exibição. +Consulte [Modelos](/pt-BR/providers/models) para configuração de preços e [Uso e custos de tokens](/pt-BR/reference/token-use) para exibição. ### 2) Entendimento de mídia (áudio/imagem/vídeo) -Mídia de entrada pode ser resumida/transcrita antes da execução da resposta. Isso usa APIs de modelo/provedor. +Mídia recebida pode ser resumida/transcrita antes de a resposta ser executada. Isso usa APIs de modelo/provedor. - Áudio: OpenAI / Groq / Deepgram / Google / Mistral. - Imagem: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI. @@ -99,14 +98,14 @@ Consulte [Entendimento de mídia](/pt-BR/nodes/media-understanding). ### 3) Geração de imagem e vídeo -Capacidades compartilhadas de geração também podem consumir chaves de provedor: +Recursos compartilhados de geração também podem consumir chaves de provedores: - Geração de imagem: OpenAI / Google / fal / MiniMax - Geração de vídeo: Qwen -A geração de imagem pode inferir um padrão de provedor respaldado por auth quando +A geração de imagem pode inferir um provedor padrão com autenticação quando `agents.defaults.imageGenerationModel` não estiver definido. A geração de vídeo atualmente -requer um `agents.defaults.videoGenerationModel` explícito, como +exige um `agents.defaults.videoGenerationModel` explícito, como `qwen/wan2.6-t2v`. Consulte [Geração de imagem](/pt-BR/tools/image-generation), [Qwen Cloud](/pt-BR/providers/qwen) @@ -114,16 +113,17 @@ e [Modelos](/pt-BR/concepts/models). ### 4) Embeddings de memória + busca semântica -A busca de memória semântica usa **APIs de embeddings** quando configurada para provedores remotos: +A busca semântica na memória usa **APIs de embeddings** quando configurada para provedores remotos: - `memorySearch.provider = "openai"` → embeddings da OpenAI - `memorySearch.provider = "gemini"` → embeddings do Gemini -- `memorySearch.provider = "voyage"` → embeddings do Voyage +- `memorySearch.provider = "voyage"` → embeddings da Voyage - `memorySearch.provider = "mistral"` → embeddings da Mistral -- `memorySearch.provider = "ollama"` → embeddings do Ollama (local/self-hosted; normalmente sem cobrança de API hospedada) -- Fallback opcional para um provedor remoto se embeddings locais falharem +- `memorySearch.provider = "lmstudio"` → embeddings do LM Studio (local/autohospedado) +- `memorySearch.provider = "ollama"` → embeddings do Ollama (local/autohospedado; normalmente sem cobrança de API hospedada) +- Fallback opcional para um provedor remoto se os embeddings locais falharem -Você pode mantê-la local com `memorySearch.provider = "local"` (sem uso de API). +Você pode manter isso local com `memorySearch.provider = "local"` (sem uso de API). Consulte [Memória](/pt-BR/concepts/memory). @@ -138,52 +138,52 @@ Consulte [Memória](/pt-BR/concepts/memory). - **Grok (xAI)**: `XAI_API_KEY` ou `plugins.entries.xai.config.webSearch.apiKey` - **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY` ou `plugins.entries.moonshot.config.webSearch.apiKey` - **MiniMax Search**: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_API_KEY` ou `plugins.entries.minimax.config.webSearch.apiKey` -- **Ollama Web Search**: sem chave por padrão, mas requer um host Ollama acessível mais `ollama signin`; também pode reutilizar a auth bearer normal do provedor Ollama quando o host a exigir +- **Ollama Web Search**: sem chave por padrão, mas requer um host Ollama acessível e `ollama signin`; também pode reutilizar a autenticação bearer normal do provedor Ollama quando o host exigir isso - **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY` ou `plugins.entries.perplexity.config.webSearch.apiKey` - **Tavily**: `TAVILY_API_KEY` ou `plugins.entries.tavily.config.webSearch.apiKey` - **DuckDuckGo**: fallback sem chave (sem cobrança de API, mas não oficial e baseado em HTML) -- **SearXNG**: `SEARXNG_BASE_URL` ou `plugins.entries.searxng.config.webSearch.baseUrl` (sem chave/self-hosted; sem cobrança de API hospedada) +- **SearXNG**: `SEARXNG_BASE_URL` ou `plugins.entries.searxng.config.webSearch.baseUrl` (sem chave/autohospedado; sem cobrança de API hospedada) -Caminhos legados de provedor `tools.web.search.*` ainda são carregados pelo shim temporário de compatibilidade, mas já não são a superfície de configuração recomendada. +Caminhos legados de provedor `tools.web.search.*` ainda são carregados por meio do shim temporário de compatibilidade, mas já não são mais a superfície de configuração recomendada. -**Crédito grátis do Brave Search:** cada plano do Brave inclui \$5/mês em -crédito grátis renovável. O plano Search custa \$5 por 1.000 solicitações, então o crédito cobre +**Crédito gratuito do Brave Search:** cada plano do Brave inclui \$5/mês em crédito gratuito renovável. +O plano Search custa \$5 por 1.000 solicitações, então o crédito cobre 1.000 solicitações/mês sem custo. Defina seu limite de uso no painel do Brave para evitar cobranças inesperadas. Consulte [Ferramentas web](/pt-BR/tools/web). -### 5) Ferramenta de busca de páginas web (Firecrawl) +### 5) Ferramenta de busca de página web (Firecrawl) -`web_fetch` pode chamar **Firecrawl** quando uma chave de API estiver presente: +`web_fetch` pode chamar o **Firecrawl** quando uma chave de API está presente: - `FIRECRAWL_API_KEY` ou `plugins.entries.firecrawl.config.webFetch.apiKey` -Se o Firecrawl não estiver configurado, a ferramenta volta para fetch direto + readability (sem API paga). +Se o Firecrawl não estiver configurado, a ferramenta recorre a fetch direto + readability (sem API paga). Consulte [Ferramentas web](/pt-BR/tools/web). -### 6) Snapshots de uso do provedor (status/saúde) +### 6) Instantâneos de uso do provedor (status/saúde) -Alguns comandos de status chamam **endpoints de uso do provedor** para exibir janelas de cota ou saúde da auth. -Essas chamadas normalmente têm baixo volume, mas ainda atingem APIs do provedor: +Alguns comandos de status chamam **endpoints de uso do provedor** para exibir janelas de cota ou saúde de autenticação. +Essas chamadas normalmente têm baixo volume, mas ainda assim atingem APIs de provedores: - `openclaw status --usage` - `openclaw models status --json` Consulte [CLI de modelos](/cli/models). -### 7) Sumarização de proteção de compactação +### 7) Sumarização de proteção de Compaction -A proteção de compactação pode resumir o histórico da sessão usando o **modelo atual**, o que -invoca APIs de provedor quando é executado. +A proteção de Compaction pode resumir o histórico da sessão usando o **modelo atual**, o que +invoca APIs do provedor quando é executado. -Consulte [Gerenciamento de sessão + compactação](/pt-BR/reference/session-management-compaction). +Consulte [Gerenciamento de sessão + compaction](/pt-BR/reference/session-management-compaction). -### 8) Varredura / sonda de modelo +### 8) Varredura / sondagem de modelo -`openclaw models scan` pode sondar modelos OpenRouter e usa `OPENROUTER_API_KEY` quando -a sondagem está ativada. +`openclaw models scan` pode sondar modelos do OpenRouter e usa `OPENROUTER_API_KEY` quando +a sondagem está habilitada. Consulte [CLI de modelos](/cli/models). @@ -197,7 +197,7 @@ Consulte [Modo Talk](/pt-BR/nodes/talk). ### 10) Skills (APIs de terceiros) -Skills podem armazenar `apiKey` em `skills.entries..apiKey`. Se uma skill usar essa chave para -APIs externas, ela pode gerar custos de acordo com o provedor da skill. +As Skills podem armazenar `apiKey` em `skills.entries..apiKey`. Se uma skill usar essa chave para APIs +externas, ela poderá gerar custos de acordo com o provedor da skill. Consulte [Skills](/pt-BR/tools/skills).