PicoClaw model not found 404: IDs de modelo e protocolos Anthropic

No PicoClaw, "model not found" e um 404 são quatro falhas diferentes, e somente uma delas acontece fora da sua máquina. Três são locais — um alias que não é resolvido, o backend web próprio do PicoClaw respondendo 404 e uma string de protocolo desconhecida — e a quarta é um 404 upstream cujo corpo informa se a rota ou o id do modelo estava errado. Ler primeiro o texto do erro é o que impede trocar protocolos para corrigir um erro de digitação.

Esta página pressupõe que você já tem uma entrada model_list funcional e uma chave; a configuração em si e o custo do PicoClaw são abordados em preços e configuração da API do PicoClaw. Tudo abaixo foi lido na tag lançada v0.3.1, que a API de lançamentos confirmou como a mais recente em 21 de setembro de 2026, publicada em 3 de julho de 2026. O repositório recebeu o último push em 17 de setembro de 2026, portanto main está à frente da tag — quando isso importa, é indicado. Em 1º de outubro de 2026, v0.3.1 ainda era o lançamento mais recente, e seu binário de lançamento foi executado contra um endpoint local de gravação e, com uma chave deliberadamente inválida, contra a Kunavo; o que isso mostrou está registrado abaixo.

Quatro falhas, uma frase

Saber se a solicitação saiu da sua máquina é, portanto, a primeira coisa a estabelecer, e a própria string resolve isso. Uma incompatibilidade de alias é um caso registrado, não uma hipótese: o issue #958 do PicoClaw relata error creating provider: model "llama3.2" not found in model_list enquanto picoclaw status mostrava o endpoint do Ollama acessível e o modelo presente como llama3.2:latest. Ele foi encerrado em 25 de março de 2026 pelo bot de issues obsoletos do repositório. Observe que, neste repositório, um issue encerrado marcado como completed não significa corrigido — o mesmo bot encerrou #1624 com a mesma redação.

O texto envolvente nomeia o protocolo que realmente foi executado

Como anthropic com uma chave de API e anthropic-messages criam provedores diferentes, seus envoltórios de 404 diferem — o que torna a string de erro um diagnóstico gratuito.

Por que a própria orientação de 404 do PicoClaw pode levar você ao caminho errado

O guia de provedores do PicoClaw orienta você a mudar para anthropic-messages quando "The existing anthropic protocol returns 404 errors (indicating the endpoint doesn't support OpenAI-compatible format)", e acrescenta a observação que resolve a nomenclatura: "The anthropic protocol uses OpenAI-compatible format (/v1/chat/completions), while anthropic-messages uses Anthropic's native format (/v1/messages)." As duas citações foram relidas na v0.3.1 em 21 de setembro de 2026.

Essa orientação está correta para um 404 de rota e errada para um 404 de modelo. Ela também aparece 294 linhas abaixo de uma tabela no mesmo arquivo, cuja coluna Protocol contém Anthropic para a linha anthropic, dizendo o oposto. O código resolve a contradição de uma maneira pouco evidente: anthropic são dois protocolos dependendo de auth_method. Com oauth ou token, ele cria o provedor SDK nativo da Anthropic e a tabela está correta; com uma chave de API, ele recai no mesmo provedor compatível com OpenAI usado por openai e toda a sua família, e a observação está correta.

Duas consequências seguem diretamente. Na família openai, escrever https://api.kunavo.com em vez de https://api.kunavo.com/v1 monta https://api.kunavo.com/chat/completions — um 404 de rota causado pela sua própria configuração, e o mais comum. Nos dois protocolos Anthropic, esse erro é impossível, porque o /v1 é forçado de qualquer maneira; mas essa mesma imposição significa que um gateway cujo caminho não pode terminar em /v1 não pode ser expresso por eles de forma alguma e precisa usar o protocolo openai. A própria documentação do PicoClaw usa essa alternativa para um fornecedor cujo base termina em um segmento de versão diferente.

Uma afirmação a tratar como não resolvida. O único comentário no issue #269 do PicoClaw afirma que enviar para /v1/chat/completions retorna 404 na Anthropic porque o endpoint correto é /v1/messages. A própria documentação da Anthropic contradiz isso: ela publica uma camada de compatibilidade com o SDK da OpenAI com base_url https://api.anthropic.com/v1/ e marca o cabeçalho authorization como "Fully supported" (verificado em 21 de setembro de 2026), embora alerte na mesma página que a camada "is not considered a long-term or production-ready solution for most use cases". O issue #269 foi encerrado em 13 de março de 2026 sem comentário de encerramento — a API de issues mostra um comentário nele, a análise acima, de uma conta sem associação ao repositório — portanto não se sabe o que realmente o resolveu. Confie no próprio corpo do seu 404, não em nenhuma das duas contas.

Quando o 404 é o id do modelo

O issue #1624 do PicoClaw — aberto em 16 de março de 2026 e encerrado em 31 de março de 2026 — registra o corpo exato para um id Claude com pontos configurado como "model": "anthropic/claude-sonnet-4.6": Status: 404 com {"error":{"code":"not_found_error","message":"model: claude-sonnet-4.6 was not found. Did you mean claude-sonnet-4-6?"…. O título e o único comentário foram relidos na API de issues em 21 de setembro de 2026: o comentário é do bot de issues obsoletos, portanto o issue está encerrado, mas não há evidência de uma correção.

Uma sugestão "did you mean" é o sinal decisivo. Ela só retorna de um endpoint que interpretou a solicitação, portanto a rota funcionou e nenhuma alteração de protocolo ajudará. O motivo pelo qual o PicoClaw não corrige a grafia por você é específico e verificável: strings.ReplaceAll(model, ".", "-") ocorre uma vez no repositório, em pkg/providers/anthropic/provider.go linha 219 — o provedor SDK usado nos caminhos OAuth e token. Nem anthropic_messages/provider.go nem openai_compat/provider.go a contém. As duas afirmações foram verificadas novamente na v0.3.1 em 21 de setembro de 2026, e a pesquisa que precedeu esta página buscou novamente os mesmos arquivos em main no mesmo dia, com o mesmo resultado. A execução do binário v0.3.1 em 1º de outubro de 2026 confirmou isso nos dois caminhos de chave de API: o id com pontos chegou ao endpoint exatamente como escrito e voltou como o próprio 404 do endpoint (consulte o que a execução da v0.3.1 mostrou). O caminho OAuth e token, o único com a reescrita, não foi executado.

Os próprios arquivos do PicoClaw também divergem sobre a grafia: provider_metadata.go lista ids com hífens para as duas entradas Anthropic, o exemplo de anthropic no guia de provedores usa um id com pontos, e anthropic-messages retorna um padrão com pontos de GetDefaultModel — a mesma grafia que o #1624 mostra sendo rejeitada. Todos os ids de API Claude impressos na visão geral de modelos da Anthropic usam hífens, e essa página lista Claude Sonnet 4.6 e Claude Opus 4.6 em "Legacy models (still available)" — portanto aposentadoria não é o motivo pelo qual um id 4.6 estaria recebendo 404 na Anthropic atualmente. Isso elimina uma causa, não todas: um id com hífens ainda pode ser rejeitado por um gateway que não disponha do modelo. Copie o id do endpoint que você está chamando, não de um README.

Escreva explicitamente as duas entradas e mantenha o id com hífens. As chaves não pertencem a este arquivo — o PicoClaw as lê de ~/.picoclaw/.security.yml, abordado no guia de configuração.

{
  "agents": {
    "defaults": {
      "model_name": "kunavo-sonnet"
    }
  },
  "model_list": [
    {
      "model_name": "kunavo-sonnet",
      "provider": "openai",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com/v1"
    },
    {
      "model_name": "kunavo-sonnet-native",
      "provider": "anthropic-messages",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com"
    }
  ]
}

A primeira entrada fornece /v1 por conta própria porque a família compatível com OpenAI concatena /chat/completions a api_base literalmente. A segunda o omite deliberadamente, para mostrar que em anthropic-messages as duas grafias são normalizadas para a mesma base. O URL base publicado pela Kunavo é https://api.kunavo.com/v1 para compleções de chat e https://api.kunavo.com/v1/messages para a rota Messages. O fato de os dois conjuntos de aritmética de URL coincidirem é uma aritmética baseada em dois conjuntos de documentação — e, em 1º de outubro de 2026, ambas as entradas foram executadas da v0.3.1 contra a Kunavo com uma chave deliberadamente inválida: a entrada openai chegou a /v1/chat/completions e a entrada anthropic-messages chegou a /v1/messages, e cada uma recebeu o 401 da Kunavo. Isso prova os URLs, não uma solicitação concluída: nada nesta página afirma uma integração testada. Para a forma geral da questão sobre URL base, consulte o documento sobre URL base da Anthropic.

Um gateway também pode responder 404 de propósito, e isso não é um bug do PicoClaw. A Kunavo retorna 404 para um modelo temporariamente pausado, com um corpo que nomeia o modelo e a substituição a ser usada, e omite modelos pausados de /v1/models; corresponda ao formato dessa mensagem, não a um nome específico, porque quais modelos estão pausados muda. A Kunavo também não oferece nenhum modelo de embeddings, texto para fala ou fala para texto, portanto uma entrada model_list que nomeie um deles resultará em 404 independentemente do protocolo escolhido — aponte essas entradas para outro provedor e mantenha apenas entradas de chat em uma chave da Kunavo.

O que a execução da v0.3.1 mostrou

Em 1º de outubro de 2026, o binário da versão v0.3.1, com checksum verificado em relação ao próprio arquivo de checksums da versão, foi executado em um contêiner descartável com uma entrada model_list por vez e picoclaw agent -m. O endpoint era um servidor de gravação local que se comportava como o roteamento da Kunavo na época — /v1/* é a API, qualquer outro caminho retornava uma página HTML 404 (a Kunavo agora responde a esses caminhos com um 404 JSON que indica a correção; consulte as linhas da Kunavo) — e conhecia claude-sonnet-5 e claude-sonnet-4-6, mas não o id com ponto; as três últimas linhas usaram o api.kunavo.com real com uma chave deliberadamente inválida, portanto nada foi cobrado.

Duas coisas que esta execução confirma, mas que a leitura do código-fonte só poderia prever. O wrapper de erro realmente identifica o provedor que foi executado, portanto é seguro deduzir o protocolo a partir dele; e um id com ponto é enviado sem alteração nos dois caminhos de chave de API, portanto um "modelo não encontrado" que cita um id com ponto é corrigido reescrevendo o id, não trocando de protocolo. O que isto não cobre: os caminhos de OAuth e token, a interface web do launcher, streaming e qualquer solicitação concluída pela Kunavo — as linhas da Kunavo usaram uma chave inválida de propósito.

A ordem mais curta de verificação

1. Algo saiu da máquina? Um erro de terminal contendo not found in model_list sem status HTTP é local. Faça agents.defaults.model_name ser igual a uma entrada de model_name e pare aí.
2. Veio do localhost? Um 404 no navegador ao escolher um modelo padrão na interface web do PicoClaw é a mesma incompatibilidade, servida pelo próprio backend do PicoClaw. Nenhuma API de modelo foi envolvida.
3. Qual provedor foi executado? Compare o texto do wrapper com a tabela acima. Se o wrapper não corresponder ao protocolo que você acha que configurou, o campo provider ou o prefixo do modelo não é o que você imagina.
4. 404 de rota ou 404 de modelo? Um corpo que identifica seu modelo — especialmente com uma sugestão did you mean — é um 404 de modelo: corrija o id. Uma página HTML, um corpo vazio ou um não encontrado genérico é um 404 de rota: derive novamente a URL montada a partir da tabela antes de fazer qualquer outra coisa.
5. Peça ao endpoint que informe o que ele oferece. O PicoClaw não consegue fazer isso em nenhum dos protocolos Anthropic, porque nenhuma das duas entradas de catálogo define o sinalizador de busca. Use curl no próprio /v1/models do gateway ou aponte temporariamente o mesmo gateway para o protocolo openai. Modelo não encontrado entre os provedores aborda esse método, e Modelo Anthropic não encontrado em 404 aborda os casos em que o próprio id é o problema.
6. Só agora troque de protocolo, e apenas se a etapa 4 tiver indicado 404 de rota. Se o bloqueio for o cabeçalho de autenticação, e não o formato da rede, token de autenticação versus chave de API explica a diferença.
7. Verifique novamente com uma rodada de ferramenta, não com uma simples mensagem de chat. Uma configuração que responde a uma mensagem simples ainda pode falhar na primeira chamada de ferramenta, portanto a tarefa limitada usada para confirmar a correção deve incluir uma.

Quanto a escolha do protocolo custa

A maior consequência de custo é o cache de prompts, e ela é estrutural, não uma configuração. No PicoClaw v0.3.1, o único código que emite um ponto de interrupção de cache está em pkg/providers/anthropic/provider.go, alcançado apenas nos caminhos de OAuth e token. Com uma chave de API — o caso comum de usar sua própria chave — nenhum dos protocolos Anthropic envia cache_control. Contra a própria camada de compatibilidade da Anthropic, isso se acumula, porque a documentação afirma claramente que "Prompt caching is not supported, but it is supported in the Anthropic SDKs". Contra um gateway que insere pontos de interrupção para clientes no formato OpenAI, a economia é recuperada no próprio gateway; a documentação de cache da Kunavo diz que ele faz isso e delimita precisamente: modelos Claude alcançados por /v1/chat/completions ou /v1/responses. A mesma página diz que cache_control passa sem tradução pela rota Messages nativa — portanto a entrada anthropic-messages não recebe pontos de interrupção de nenhum dos lados, e a segunda coluna abaixo descreve apenas a entrada do protocolo openai. Não foi verificado se outros gateways inserem pontos de interrupção, e nada disso foi observado de dentro do PicoClaw.

O valor disso é uma aritmética ilustrativa de tokens, não um custo de tarefa medido nem um limite de cobrança. Suponha uma rodada de agente de 10 rodadas de ferramenta, em que cada rodada reenvia o mesmo prefixo de 20,000 tokens (prompt do sistema, esquemas de ferramentas, transcrição até o momento), adiciona 1,000 novos tokens de entrada e retorna 600 tokens de saída. Essas proporções são suposições para fins ilustrativos. A primeira coluna cobra a entrada de cada rodada à tarifa integral; a segunda cobra o prefixo repetido à tarifa de leitura do cache a partir da segunda rodada. As tarifas são preços atuais do catálogo da Kunavo por milhão de tokens.

Com essas suposições, Claude Sonnet 4.6 passa de $0.504 para $0.164 pelo mesmo trabalho. Leia a segunda coluna como otimista: as gravações no cache são cobradas à própria tarifa e não são modeladas em nenhuma das direções, e um prefixo que muda a cada rodada nunca se torna um acerto de cache. Multiplique pelas rodadas por dia antes de tratar qualquer valor como orçamento.

Separe as duas cobranças enquanto faz isso. O PicoClaw em si é gratuito — o repositório tem licença MIT, e nenhum protocolo, incluindo os dois da Anthropic, exige algo para comprar. O custo recorrente são os tokens do modelo à tarifa do seu provedor. 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. O recarregamento mínimo é $10 em crédito pré-pago, um mínimo de financiamento, não uma taxa de tarefa ou assinatura — consulte detalhes de cobrança.

Fornecedor direto, gateway, assinatura ou local

Escolhendo o runtime em vez da rota? PicoClaw versus OpenClaw compara os dois quanto ao formato de implantação. Se você optar por um gateway e quiser financiar uma chave, crie uma conta na Kunavo e envie uma tarefa limitada com uma chamada de ferramenta, depois leia a cobrança que sua conta realmente registrou.

Perguntas frequentes

Verificado em 21 de setembro de 2026. Reverificado nesta tarefa na tag v0.3.1: a observação de protocolo do guia de provedores e a linha do fornecedor Anthropic, o ramo anthropic e o caminho padrão de factory_provider.go, NormalizeBaseURL, a URL de anthropic-messages, os cabeçalhos e a string 404, a concatenação de URL e o cabeçalho Bearer de openai_compat, as três strings "not found in model_list" anteriores ao HTTP, o 404 do backend web, a única ocorrência da substituição de ponto por hífen, a coluna SupportsFetch da tabela de opções de provedores e o exemplo do OpenRouter em docs/operations/troubleshooting.md; além da API de releases (v0.3.1, publicada em 3 de julho de 2026) e dos títulos, estados, datas e comentários das issues #1624, #958 e #269. A página de compatibilidade do SDK OpenAI da Anthropic foi lida no mesmo dia. Executado em 1º de outubro de 2026: o binário da versão v0.3.1 em um contêiner contra um endpoint de gravação local e, com uma chave inválida, contra a Kunavo — todas as linhas da tabela acima. Não verificado: qualquer coisa em main além dos arquivos cujas diferenças foram comparadas pela pesquisa, o que encerrou a issue #269, os caminhos de OAuth e token e qualquer solicitação concluída pela Kunavo. As tarifas de tokens da Kunavo vêm do catálogo atual, e todo valor em dólar aqui é uma aritmética ilustrativa de tokens.