Como conectar uma API de modelo de IA a um agente Android na FoneClaw
Configure API Base URL, API Key e model ID na FoneClaw, teste a conexão do modelo e valide uma ação Android governada com permissões e aprovação visível.
- A FoneClaw oferece dois caminhos: usar o modelo padrão gratuito ou configurar um modelo compatível com API Base URL, API Key e model ID dentro do próprio agente.
- API Base URL aponta para o endpoint compatível do provedor, API Key autentica as chamadas, e model ID escolhe qual modelo responderá ao raciocínio do agente.
- Uma resposta de texto bem-sucedida prova apenas a conexão do modelo; ações Android ainda dependem de ferramentas suportadas, permissões do sistema, política de aprovação e resultado visível.
- O teste seguro começa por uma tarefa de baixo risco, depois passa para uma ação Android governada, sem expor credenciais reais nem presumir que todo modelo ou provedor funciona igual.
Use o modelo padrão ou conecte sua própria API
Para conectar uma API de modelo de IA a um agente Android, comece pela escolha certa: você não precisa trazer uma chave própria para usar a FoneClaw. A FoneClaw inclui um modelo padrão gratuito para começar. Quem quer usar um modelo compatível de outro provedor pode configurar esse modelo dentro da FoneClaw usando API Base URL, API Key e model ID.
Esses dois caminhos resolvem necessidades diferentes. O modelo padrão é o caminho mais simples para testar o agente no telefone sem lidar com credenciais externas. A configuração personalizada é útil quando você já tem conta em um provedor, quer comparar latência, prefere um modelo específico ou precisa usar uma API compatível com seu fluxo.
| Caminho | Quando usar | O que continua igual |
|---|---|---|
| Modelo padrão gratuito | Primeiro teste, configuração rápida e uso sem chave externa | A FoneClaw ainda governa ferramentas, permissões, aprovação e resultado |
| Modelo compatível configurado | Quando você tem API Base URL, API Key e model ID de um provedor compatível | O modelo raciocina, mas a FoneClaw executa ações Android suportadas |
Essa separação é essencial. A configuração de modelo acontece dentro da FoneClaw; não é uma cooperação entre dois apps de consumidor. O modelo fornece compreensão, raciocínio e planejamento. A FoneClaw é o runtime de phone agent que decide como transformar esse plano em uma ação Android suportada, com permissões sob demanda e controles visíveis.
O que são API Base URL, API Key e model ID
API Base URL é o endereço base do serviço compatível que receberá chamadas do modelo. Ele precisa vir do provedor ou da documentação do gateway que você usa. Alguns provedores oferecem compatibilidade com clientes no estilo OpenAI por meio de um endereço próprio, como explica a documentação da compatibilidade da Gemini API com bibliotecas OpenAI. Isso não significa que todos os provedores usem o mesmo caminho, os mesmos modelos ou as mesmas opções.
API Key é a credencial que autentica as chamadas. Ela deve ser tratada como segredo. Não publique a chave, não cole em capturas de tela, não envie em chats públicos e não use exemplos reais em tutoriais. A referência de autenticação da API da OpenAI mostra o padrão de autenticação por Bearer token, mas cada provedor pode ter regras próprias de emissão, rotação e escopo.
model ID é o identificador do modelo que você quer usar. Ele não é um apelido livre. Precisa corresponder a um modelo aceito pelo provedor naquele endpoint e naquela conta. Se o model ID estiver errado, a autenticação pode estar correta e ainda assim a chamada falhar. Por isso, copie o nome exatamente da documentação ou do painel do provedor.
Também há erros de formato que parecem pequenos e quebram a conexão: Base URL com caminho incompleto, chave copiada com espaço no começo, model ID de outro provedor, uso de um endpoint que não é compatível com o formato esperado, ou uma conta sem permissão para aquele modelo. Para configurar API Key de LLM no celular com segurança, use apenas valores reais no campo próprio da FoneClaw e mantenha exemplos públicos como placeholders.
Configure um modelo na FoneClaw passo a passo
Antes de abrir a configuração, reúna três informações do provedor: API Base URL, API Key e model ID. Confirme que o endpoint usa HTTPS e que o provedor oferece um formato compatível com o fluxo que você quer testar. Se você ainda não sabe qual modelo usar, mantenha o modelo padrão gratuito da FoneClaw para validar o agente antes de mexer em credenciais externas.
O fluxo prático é simples e deve ser feito sem expor segredos:
- Abra as configurações de agente na FoneClaw.
- Escolha manter o modelo padrão ou adicionar um modelo compatível.
- Preencha a API Base URL exatamente como o provedor orienta.
- Cole a API Key no campo próprio, sem mostrar a chave em capturas ou mensagens.
- Informe o model ID aceito pelo provedor.
- Salve a configuração e selecione o modelo que será usado pelo agente.
- Faça primeiro um teste de texto curto, sem ação no telefone.
- Depois valide uma ação Android de baixo risco com resultado visível.
Não invente rótulos extras se o provedor não exige. Também não misture credenciais de produtos diferentes: uma chave de um app de chat, por exemplo, não é automaticamente uma chave de API compatível. Se você usa um gateway próprio, confirme se ele encaminha autenticação, model ID e payload no formato esperado.
O projeto Android da FoneClaw é a referência pública do produto. Para o usuário final, o ponto central é mais direto: o modelo configurado ajuda a FoneClaw a raciocinar; a ação no Android continua passando pelo runtime, pelas ferramentas governadas e pelas permissões do aparelho.
Teste a conexão antes de controlar o telefone
Um teste de modelo deve acontecer em etapas. Primeiro, faça uma pergunta inofensiva: peça ao modelo para resumir uma frase, explicar uma regra simples ou devolver uma resposta curta. Se essa etapa falhar, o problema provavelmente está em API Base URL, API Key, model ID, rede, conta do provedor ou formato de compatibilidade. Ainda não é hora de testar controle Android.
Quando a resposta textual funcionar, passe para um teste de raciocínio com intenção de agente, mas sem consequência. Por exemplo: peça para explicar quais etapas seriam necessárias para criar um lembrete, sem criar nada. Isso mostra se o modelo entende a tarefa e consegue separar planejamento de execução. Uma resposta boa ainda não prova que a ferramenta Android está disponível.
O terceiro passo é uma ação visível e de baixo risco no telefone, como abrir um app suportado, consultar estado visível ou preparar um rascunho sem enviar. Evite começar por envio de mensagem, exclusão, alteração de configuração sensível, compra ou uso de dados privados. Phone actions ainda dependem de ferramentas suportadas e permissões Android.
Para entender por que um modelo conectado não equivale automaticamente a controle do celular, consulte Controle do celular por agente de IA: como funciona no Android. Esse guia aprofunda a passagem de intenção para ferramenta, permissão, aprovação e resultado.
Corrija erros 401, 404, timeout, modelo e permissão
Quando a conexão falha, separe erro de API de erro de Android. Um erro do modelo aparece antes da ação no telefone: autenticação, endpoint, model ID, limite de conta ou timeout. Um erro Android aparece depois que o modelo já respondeu ou tentou planejar uma ação: permissão ausente, ferramenta desabilitada, app incompatível, alvo ambíguo ou ação que exige aprovação.
| Sintoma | Causa provável | Correção segura |
|---|---|---|
| 401 ou não autorizado | API Key ausente, inválida, vencida ou sem escopo | Gere uma nova chave no provedor, cole no campo próprio e não exponha em prints |
| 404 ou endpoint não encontrado | API Base URL ou caminho compatível incorreto | Confira a documentação do provedor e não presuma que todos usam o mesmo caminho |
| Modelo não encontrado | model ID errado ou indisponível para a conta | Copie o identificador oficial do modelo e teste com uma chamada simples |
| Timeout | Rede instável, provedor lento ou modelo pesado | Teste rede, reduza tarefa inicial e compare com modelo mais leve quando disponível |
| Resposta textual funciona, mas ação Android falha | Ferramenta, permissão ou alvo do telefone não está pronto | Revise ferramentas habilitadas, conceda permissão em contexto e comece por ação simples |
| O agente pede aprovação | A ação tem consequência ou política mais restrita | Revise alvo e conteúdo; não trate aprovação como erro de modelo |
Erros 401 geralmente apontam para autenticação, mas não assuma sem olhar o texto do provedor. Erros 404 muitas vezes indicam Base URL, caminho compatível ou model ID incorreto, mas também podem variar por gateway. Timeouts podem vir de rede móvel, VPN, provedor ocupado ou modelo lento. Já permissões Android são outro mundo: uma API Key válida não concede acesso a câmera, localização, contatos ou notificações do telefone.
Se o objetivo é configurar um modelo específico para phone agent, vale comparar casos de uso. O guia DeepSeek no Android: ele consegue controlar o celular de verdade? mostra como separar capacidade do modelo e execução Android em um exemplo concreto. Para outro recorte de assistente e telefone, veja O Grok pode controlar um celular Android? Chamadas, assistente e FoneClaw.
Escolha um modelo para ações Android
O melhor modelo para um agente de celular não é necessariamente o maior, o mais famoso ou o mais caro. A escolha depende da tarefa. Para comandos simples, um modelo rápido e estável pode ser melhor. Para tarefas com ambiguidade, leitura de contexto ou planejamento de múltiplas etapas, um modelo mais forte pode reduzir erros e retries. Para uso frequente em rede móvel, latência e custo também importam.
Avalie cinco critérios. Primeiro, compatibilidade com o formato de API que você vai usar. Segundo, qualidade de raciocínio para escolher ferramentas e pedir esclarecimento. Terceiro, latência real no seu telefone e na sua rede. Quarto, política de privacidade e retenção do provedor. Quinto, confiabilidade em respostas estruturadas quando a tarefa exige campos, JSON ou escolha de ferramenta.
Mesmo com um bom modelo, a FoneClaw continua sendo a camada que governa ações. O modelo planeja; a FoneClaw executa apenas o que é suportado no Android, com permissões sob demanda, aprovação quando a política exige e resultado visível. Um modelo mais rápido não torna automática uma ação sensível; um modelo mais inteligente não remove permissões do sistema.
Se você quer comparar roteamento entre modelos para phone agent, leia Melhor modelo para agente de telefone: Kimi K3, DeepSeek V4 e GLM-5.2. Aqui, a regra de configuração é pragmática: escolha um modelo compatível, teste pequeno e só aumente o escopo quando o fluxo estiver estável.
Transforme o modelo conectado em uma ação governada
Depois que o modelo responde, o teste final é uma ação governada no Android. A sequência correta é: pedido do usuário, raciocínio do modelo, escolha de ferramenta pela FoneClaw, permissão sob demanda quando necessária, aprovação quando a ação tem consequência e verificação do resultado. Se qualquer etapa falhar, o agente deve explicar o motivo e oferecer recuperação, não improvisar em silêncio.
A base atualmente disponível da FoneClaw adiciona controles por ferramenta, substituições de aprovação, recuperação de permissões e tratamento de falhas mais forte. Essas melhorias ajudam a transformar modelo configurado em uso prático no telefone sem apagar a fronteira entre raciocínio e execução.
As ferramentas da FoneClaw incluem mais de 100 ferramentas integradas para ações Android suportadas. Use isso como mapa de capacidade, não como promessa de controle universal. Comece por ações reversíveis e visíveis: abrir um app, consultar estado, preparar texto, criar lembrete simples. Depois avance para fluxos mais sensíveis somente quando você entende permissões, aprovação e resultado.
Essa é a forma segura de usar modelo personalizado com agente de celular: configure o endpoint, proteja a API Key, valide uma resposta textual, teste uma ação baixa em risco e mantenha a FoneClaw como camada governada de execução Android.