Uso e custos da API

Mapa dos recursos do OpenClaw que podem chamar APIs pagas de provedores, de onde cada um lê suas credenciais e onde o custo resultante é exibido.

Onde os custos são exibidos

/status (instantâneo por sessão)

• Mostra o modelo da sessão atual, o uso do contexto e os tokens da última resposta.
• Adiciona um custo estimado para a última resposta quando o OpenClaw tem metadados de uso e preços locais para o modelo ativo, incluindo provedores sem chave de API com preços definidos explicitamente, como os modelos aws-sdk do Bedrock.
• Se o instantâneo da sessão ativa tiver poucos dados, /status recupera os contadores de tokens/cache e o rótulo do modelo ativo da entrada de uso mais recente da transcrição. Valores ativos existentes diferentes de zero prevalecem sobre os dados da transcrição; um total da transcrição equivalente ao tamanho do prompt ainda pode prevalecer quando o total armazenado está ausente ou é menor.

/usage (rodapé por mensagem)

• /usage full acrescenta um rodapé de uso a cada resposta, incluindo o custo estimado quando os preços locais estão configurados e os metadados de uso estão disponíveis.
• /usage tokens mostra apenas os tokens. Runtimes de OAuth/token e CLI no estilo de assinatura mostram apenas os tokens, a menos que forneçam metadados de uso compatíveis e um preço local explícito.
• /usage cost exibe um resumo local dos custos; /usage off desativa o rodapé.
• Observação sobre a Gemini CLI: tanto a saída stream-json quanto a saída legada json incluem o uso em stats. O OpenClaw normaliza stats.cached como cacheRead e, quando necessário, deriva os tokens de entrada de stats.input_tokens - stats.cached.

Interface de controle → Uso (análise entre sessões)

• Mostra os totais de tokens e custos estimados derivados das transcrições para o intervalo de datas selecionado, com detalhamentos por provedor, modelo, agente, canal e tipo de token.
• Compara janelas de calendário mais curtas que terminam na data final do intervalo selecionado. Datas ausentes contam como dias do calendário com uso zero; elas não são ignoradas para criar uma janela mais densa.
• Identifica diretamente a escala do gráfico diário. Um selo √ significa que a compressão por raiz quadrada está mantendo visíveis os dias de baixo uso.
• Esses totais descrevem o histórico de sessões local disponível, não uma fatura do provedor nem um registro de cobrança de toda a duração. A interface avisa quando faltam preços para algumas entradas.

Janelas de uso da CLI (cotas do provedor, não custo por mensagem)

• openclaw status --usage e openclaw channels list mostram as janelas de uso dos provedores como X% left.
• Provedores atuais de janelas de uso: Anthropic, ClawRouter, DeepSeek, GitHub Copilot, Gemini CLI, MiniMax, OpenAI (abrange autenticação por OAuth/token do ChatGPT/Codex), Xiaomi e z.ai. Consulte CLI de modelos e CLI de canais para ver a lista completa de provedores/opções.
• Os campos brutos usage_percent / usagePercent da MiniMax informam a cota restante, portanto o OpenClaw os inverte; campos baseados em contagem prevalecem quando presentes. Se a resposta incluir uma matriz model_remains, o OpenClaw seleciona a entrada do modelo de chat, deriva o rótulo da janela dos carimbos de data e hora quando necessário e inclui o nome do modelo no rótulo do plano.
• A autenticação de uso vem de hooks específicos do provedor quando disponíveis; caso contrário, o OpenClaw recorre às credenciais OAuth/chave de API correspondentes nos perfis de autenticação, no ambiente ou na configuração.

Consulte Uso e custos de tokens para ver exemplos detalhados.

Como as chaves são descobertas

• 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, agents.defaults.memorySearch.*, talk.providers.*.apiKey.
• Skills: skills.entries.<name>.apiKey, que pode exportar a chave para o ambiente do processo da Skills.

Recursos que podem consumir chaves

Respostas do modelo principal (chat + ferramentas)

Cada resposta ou chamada de ferramenta é executada no provedor do modelo atual. Essa é a principal fonte de uso e custo, incluindo planos hospedados no estilo de assinatura cuja cobrança ocorre fora da interface local do OpenClaw: OpenAI Codex, Alibaba Cloud Model Studio Coding Plan, MiniMax Coding Plan, Z.AI/GLM Coding Plan e o fluxo de login do Claude da Anthropic com Extra Usage ativado.

Consulte Modelos para ver a configuração de preços e Uso e custos de tokens para saber como são exibidos.

Compreensão de mídia (áudio/imagem/vídeo)

A mídia recebida pode ser resumida ou transcrita por uma API de provedor antes da execução do pipeline de resposta. O suporte a provedores é registrado por Plugin e muda à medida que Plugins são adicionados; consulte Compreensão de mídia para ver a lista e a configuração atuais.

Geração de imagens e vídeos

image_generate e video_generate encaminham para qualquer provedor configurado que esteja disponível. A geração de imagens pode inferir um provedor padrão baseado em autenticação quando agents.defaults.imageGenerationModel não está definido; a geração de vídeos exige um agents.defaults.videoGenerationModel explícito (por exemplo, qwen/wan2.6-t2v).

Consulte Geração de imagens e Geração de vídeos para ver a lista atual de provedores.

Embeddings de memória e pesquisa semântica

A pesquisa semântica na memória usa APIs de embeddings quando agents.defaults.memorySearch.provider indica um adaptador remoto (por exemplo, openai, gemini, voyage, mistral, deepinfra, github-copilot, amazon-bedrock). memorySearch.provider = "lmstudio" ou "ollama" é executado em um servidor local/auto-hospedado e normalmente não gera cobrança de hospedagem. memorySearch.provider = "local" mantém tudo no dispositivo, sem uso de API. Um provedor opcional em memorySearch.fallback pode cobrir falhas nos embeddings locais.

Consulte Memória.

Ferramenta de pesquisa na web

web_search pode gerar cobranças de uso dependendo do provedor selecionado. Cada provedor lê sua chave primeiro de uma variável de ambiente e depois de plugins.entries.<id>.config.webSearch.apiKey:

Os caminhos legados de configuração tools.web.search.* ainda são carregados por uma camada de compatibilidade, mas deixaram de ser a opção recomendada.

Crédito gratuito do Brave Search: cada plano inclui US$ 5/mês em crédito gratuito renovável. O plano Search custa US$ 5 por 1.000 solicitações, portanto o crédito cobre 1.000 solicitações/mês sem cobrança. Defina um limite de uso no painel do Brave para evitar cobranças inesperadas.

Consulte Ferramentas da web.

Ferramenta de busca de conteúdo da web (Firecrawl)

web_fetch pode chamar o Firecrawl com acesso inicial sem chave; adicione FIRECRAWL_API_KEY (ou plugins.entries.firecrawl.config.webFetch.apiKey) para obter limites maiores. Se o Firecrawl não estiver configurado, a ferramenta recorre à busca direta mais o Plugin web-readability incluído (sem API paga). Desative plugins.entries.web-readability.enabled para ignorar a extração local de legibilidade.

Consulte Ferramentas da web.

Instantâneos de uso dos provedores (status/integridade)

openclaw status --usage e openclaw models status --json chamam endpoints de uso dos provedores para mostrar janelas de cota ou a integridade da autenticação. As chamadas têm baixo volume, mas ainda acessam as APIs dos provedores.

Consulte CLI de modelos.

Resumo de proteção da Compaction

A proteção da Compaction pode resumir o histórico da sessão usando o modelo atual, o que invoca APIs do provedor quando executada.

Consulte Gerenciamento de sessões e Compaction.

Varredura/sondagem de modelos

openclaw models scan pode sondar modelos do OpenRouter e usa OPENROUTER_API_KEY quando a sondagem está ativada.

Consulte CLI de modelos.

Conversa (fala)

O modo de conversa pode invocar o ElevenLabs quando configurado: ELEVENLABS_API_KEY ou talk.providers.elevenlabs.apiKey.

Consulte Modo de conversa.

Skills (APIs de terceiros)

Skills pode armazenar apiKey em skills.entries.<name>.apiKey. Se uma Skills usar essa chave em uma API externa, o custo seguirá o provedor da Skills.

Consulte Skills.

Relacionado

• Uso e custos de tokens
• Cache de prompts
• Rastreamento de uso