Configuração de API personalizada do IronClaw: provedores, chaves e limites de privacidade

O IronClaw aceita uma API personalizada em um único bloco de quatro campos: um bloco [llm.default] em ~/.ironclaw/reborn/config.toml contendo provider_id, base_url, model e api_key_env — ou, quando não existe um bloco, as variáveis de ambiente LLM_BACKEND / LLM_BASE_URL / LLM_API_KEY às quais ele recorre. Ambas as formas são atuais e documentadas. O que as páginas de configuração não reúnem em um único lugar é a lista do que um endpoint personalizado deixa de receber — streaming nativo, descoberta de modelos, pontos de interrupção Anthropic cache_control e exibição precisa de custos, entre outros — e essa é a parte que vale ler antes de escolher um provedor.

Primeiro, uma desambiguação, porque os resultados de busca são dominados por outros produtos. Esta página trata de github.com/nearai/ironclaw, descrito pelos metadados do próprio repositório como "IronClaw is an Agent OS focused on privacy, security and extensibility": Rust, não arquivado e não um fork, 12,626 estrelas, criado em 3 de fevereiro de 2026 e atualizado pela última vez em 21 de setembro de 2026 (API do GitHub, no mesmo dia). Não é o mouse gamer Corsair com esse nome, o RPG de mesa da Sanguine Productions, o token de criptomoeda IRONCLAW nem o repositório não relacionado JoasASantos/ironclaw — nenhum dos preços ou configurações deles pertence a esta página. A documentação canônica é docs.ironclaw.com e a própria árvore docs/ do repositório; um espelho de terceiros no Mintlify aparece para os mesmos títulos e pode estar desatualizado.

Vale citar a atribuição em vez de parafraseá-la, porque as próprias superfícies do fornecedor diferem: ironclaw.com coloca "Built by" ao lado de um logotipo da NEAR e das palavras "Near Foundation" no corpo, e "— by NEAR AI" no rodapé, enquanto a organização no GitHub é nearai.

A configuração mínima de provedor personalizado do IronClaw

A estrutura do bloco em ironclaw_config aceita exatamente quatro campos opcionais, e os próprios comentários da documentação os descrevem como substituições da entrada do catálogo: model substitui o default_model do provedor, api_key_env substitui o api_key_env e base_url substitui o default_base_url. A documentação de provedores acrescenta que base_url "também funciona em qualquer outro provedor quando você precisa roteá-lo por um proxy ou endpoint regional" — portanto, isso não é apenas um recurso do adaptador genérico.

[llm.default]
provider_id = "openai_compatible"
base_url    = "https://api.kunavo.com/v1"
model       = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"

Três regras que causam problemas. Omitir base_url é fatal, não assume um padrão: a documentação diz que isso "deixa o bloco apontando para lugar nenhum e a resolução do modelo falha", e a entrada de catálogo openai_compatible contém base_url_required: true. api_key_env recebe um nome de variável, nunca uma chave — um segredo colado é "rejeitado no momento da análise, não aceito silenciosamente", e ironclaw config set <provider>.api_key solicita a entrada com o valor oculto. Nada é aplicado até uma reinicialização: config set "nunca reinicia nada"; ele exibe a etapa ironclaw service restart que você ainda precisa executar. E não espere que config set grave o bloco por você — a página de configuração lista [llm.default] entre as seções "editadas diretamente em config.toml", e config set "rejeita uma chave não compatível em vez de não fazer nada silenciosamente".

O formato de ambiente é o fallback documentado quando [llm.default] está ausente, e a documentação resolve a escolha claramente: "Ambos funcionam … Prefira o bloco TOML para uma instalação permanente e o formato de ambiente para execuções pontuais e contêineres."

export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6

# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120

A ordem de resolução é compiled defaults < config.toml < environment variables < CLI flags, portanto uma variável exportada silenciosamente tem precedência sobre o arquivo que você acabou de editar. A rota da CLI evita a edição manual por completo: ironclaw models list, depois ironclaw models set-provider <id> --model <model>, depois ironclaw models status. Confirme seus caminhos com ironclaw config path em vez de confiar em qualquer uma das localizações documentadas — a página de início rápido diz que tudo fica em ~/.ironclaw, enquanto as páginas de configuração e onboarding dizem ~/.ironclaw/reborn. Uma armadilha operacional para usuários hospedados: a página de configuração afirma que os comandos ironclaw service "não funcionam em uma instância hospedada da NEAR AI — não há um gerenciador de serviços de usuário com o qual possam falar", portanto conecte-se por SSH para executar ironclaw config e reinicie pelo Agent Dashboard. Todas as citações foram lidas na branch main em 21 de setembro de 2026.

O que um endpoint personalizado não alcança

Estas são as próprias declarações do IronClaw sobre seu comportamento de execução pretendido, lidas nos arquivos de código-fonte e de contrato em main. Elas não são execuções observadas, e main estava à frente da tag de lançamento 1.4.0 — publicada em 28 de agosto de 2026, segundo a API de releases do GitHub — quando foram lidas.

O catálogo do IronClaw é um catálogo de chat, e a Kunavo não oferece nenhum modelo de embeddings, conversão de texto em fala ou conversão de fala em texto, portanto qualquer parte da sua configuração que precise de um deles terá de apontar para outro lugar completamente diferente.

A exibição de custos do IronClaw não é a sua fatura

Dois caminhos separados calculam valores monetários dentro do IronClaw, discordam entre si e nenhum consulta o seu provedor. price_usage() em ironclaw_common calcula preços a partir de uma tabela de tarifas por token fixada no código e recorre a default_cost() — 0.0000025 de entrada e 0.00001 por token, um valor de $2.50 / $10.00 por milhão no formato do GPT-4o — com a justificativa declarada de que "um novo modelo pago nunca recebe silenciosamente preço zero". Enquanto isso, o StaticModelCostTable do loop host faz o oposto para as reservas de orçamento: um perfil ausente da tabela "recorre a None, que o contador trata como custo zero". E no caminho llm_costs, o desconto de leitura do cache é estimado a partir do nome do modelo por substring — claude divide por dez, gpt ou um prefixo o1/o3/o4 divide por dois, e todo o restante divide por um.

A consequência prática é que budget.user_daily_usd, budget.pause_at e o restante das chaves [budget] do IronClaw controlam uma estimativa, não uma cobrança. Ainda vale a pena defini-las em um agente sempre ativo — interromper cedo um loop descontrolado é justamente o objetivo —, mas faça a conciliação com o uso registrado pelo seu provedor, não com o número exibido na tela.

Uma estimativa calculada para um dia de agente

Isto é aritmética de tokens, não um custo de tarefa medido nem um limite máximo de cobrança. Suponha um dia de atividade do agente totalizando 1,000,000 tokens de entrada sem cache e 40,000 tokens de saída — uma suposição para ilustração, escolhida porque um ambiente de execução sempre ativo acumula entrada por meio de pulsações de heartbeat e rotinas, em vez de respostas longas. As tarifas são os preços atuais do catálogo da Kunavo por milhão de tokens.

A última coluna é a surpresa útil, e é uma propriedade da string do ID, não do modelo. vision_models.rs faz correspondência por substring com uma lista fixa que inclui claude-opus-, claude-sonnet-, claude-haiku- e claude-fable-, portanto esses IDs encaminham anexos de imagem; os outros IDs da tabela acima não correspondem a nenhum de gpt-4o, gemini-1.5, gemini-2 ou ao restante da lista e seriam classificados como somente texto. Quando não há correspondência, o gateway do loop host envia o texto da mensagem sem as partes de imagem e não gera erro — a transcrição persistente mantém um ponteiro <attachments>, mas o modelo nunca vê a imagem. Consulte a lista de padrões comparando-a com o ID exato que pretende digitar antes de presumir que a entrada de imagem funciona. Multiplique os valores em dólares pelos seus próprios dias antes de tratá-los como orçamento. O valor do catálogo da Kunavo é um piso de cobrança, não um teto: quando o upstream informa sua cobrança, a fatura é o maior valor entre o custo do catálogo e o custo do upstream multiplicado pela margem aplicável. As cobranças de cache e as ferramentas externas ficam fora deste exemplo, e o recarregamento mínimo é de $10 em crédito pré-pago — um mínimo de financiamento, não uma tarifa de tarefa nem uma assinatura. Consulte os detalhes de cobrança.

Qual caminho vence e quanto o próprio IronClaw custa

O software é gratuito: a raiz do repositório contém tanto LICENSE-APACHE quanto LICENSE-MIT, e o README declara MIT OR Apache 2.0. Não há uma edição paga do binário nem taxa de licença. O que você paga são tokens, além da hospedagem se optar pela do fornecedor.

Preços dos planos hospedados lidos em ironclaw.com em 21 de setembro de 2026; não há uma página /pricing, os planos ficam na página inicial, e a marcação renderizada mostra os $5 dentro de um span riscado, com $0 como preço vigente. A página inicial também afirma "Inicie até 5 agentes em um Ambiente de Execução Confiável com até 130M de tokens por mês" — essa frase fica acima dos três cartões e não nomeia nenhum plano, portanto não a associe a um deles. Três coisas que este guia não conseguiu estabelecer e não vai presumir: se os planos hospedados permitem uma chave de terceiros, o que os créditos incluídos realmente compram ou o que acontece quando acabam, e a qual plano pertence o valor de 130M. As tarifas de tokens foram lidas em near.ai/pricing no mesmo dia; a página afirma "Não há taxa de plataforma além da tarifa do modelo" e abrange somente seus modelos de texto confidenciais.

Um limite de privacidade deve ser declarado claramente, porque é o motivo pelo qual as pessoas escolhem este ambiente de execução. Os controles descritos pelo próprio README e pela página de segurança do IronClaw — segredos "criptografados em repouso" e injetados no limite do host, o sandbox WASM para ferramentas não confiáveis, lista de permissões de endpoints, detecção de vazamentos — são controles locais sobre a máquina que executa o agente. A atestação de hardware é uma propriedade separada da NEAR AI Cloud: near.ai afirma que a inferência lá "é executada em um enclave de GPU confidencial Intel TDX + NVIDIA" e que "cada resposta carrega uma comprovação de hardware verificável". Apontar o IronClaw para um endpoint de terceiros envia o conteúdo dos prompts a esse endpoint sob os termos dele, e nada de nenhuma das duas listas o acompanha até lá. A tabela "OpenClaw vs IronClaw" produzida pelo fornecedor em ironclaw.com é marketing de uma das partes, não uma comparação neutra — e tenha cuidado com os resultados de pesquisa, pois, em uma amostra da página de resultados coletada em 17 de setembro de 2026, as quatro formas de consulta best api for ironclaw, cheapest api for ironclaw, best model for ironclaw e ironclaw custom provider retornaram, cada uma, oito ou mais resultados de OpenClaw nos dez primeiros, cujas classificações de modelos descrevem um produto diferente.

Configure-o e verifique a primeira cobrança

A Kunavo publica um endpoint no formato da OpenAI em https://api.kunavo.com/v1 e um no formato da Anthropic, que correspondem aos IDs de provedor openai_compatible e anthropic. A Kunavo não testou o IronClaw em execução, portanto trate o bloco acima como um ponto de partida baseado no protocolo documentado, não como uma alegação de compatibilidade: mantenha uma rota funcional disponível, execute uma tarefa limitada e leia a cobrança que sua conta realmente registrou. Se você conduzir o Goose a partir do IronClaw via ACP — .env.example documenta o sandbox do Agent Client Protocol e o comando ironclaw acp add goose —, a integração com o Goose aborda esse lado separadamente, e criar uma conta na Kunavo financia uma chave quando você estiver pronto. Para as opções relacionadas, consulte a referência da API compatível com OpenAI, alternativas ao OpenRouter e otimização de custos de IA.

Perguntas frequentes

Metadados do repositório, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, a árvore docs/, ironclaw.com e near.ai/pricing, todos consultados em 21 de setembro de 2026, a partir do branch main, e não da tag de lançamento 1.4.0. Nenhuma solicitação do IronClaw foi enviada a um endpoint da Kunavo; toda declaração de compatibilidade aqui é uma leitura da documentação de ambos os lados. As tarifas de tokens da Kunavo vêm do catálogo atual, e todo exemplo em dólares é uma aritmética ilustrativa de tokens.