PicoClaw: modelo no encontrado 404: IDs de modelo y protocolos de Anthropic

En PicoClaw, «model not found» y un 404 corresponden a cuatro fallos distintos, y solo uno de ellos ocurre fuera de tu máquina. Tres son locales: un alias que no se resuelve, el backend web propio de PicoClaw que responde 404 y una cadena de protocolo desconocida; el cuarto es un 404 upstream cuyo cuerpo indica si la ruta era incorrecta o lo era el id del modelo. Leer primero el texto del error evita cambiar de protocolo para corregir un error tipográfico.

Esta página presupone que ya tienes una entrada model_list funcional y una clave; la configuración en sí y el coste de PicoClaw se explican en PicoClaw pricing and API setup. Todo lo siguiente se leyó en la etiqueta publicada v0.3.1, que la API de versiones confirmó como la más reciente el 21 de septiembre de 2026, publicada el 3 de julio de 2026. El último push al repositorio fue el 17 de septiembre de 2026, por lo que main está por delante de la etiqueta; cuando es relevante, se indica. El 1 de octubre de 2026 v0.3.1 seguía siendo la versión más reciente, y su binario de lanzamiento se ejecutó contra un endpoint local de grabación y, con una clave deliberadamente no válida, contra Kunavo; lo que mostró se registra a continuación.

Cuatro fallos, una frase

Por tanto, lo primero que hay que establecer es si la solicitud salió de tu máquina, y la cadena por sí sola lo resuelve. Un desajuste de alias es un caso documentado, no hipotético: el problema de PicoClaw #958 informa de error creating provider: model "llama3.2" not found in model_list, mientras que picoclaw status mostró que el endpoint de Ollama era accesible y que el modelo estaba presente como llama3.2:latest. El bot de problemas obsoletos del repositorio lo cerró el 25 de marzo de 2026. Ten en cuenta que en este repositorio un problema cerrado marcado como completed no significa que esté solucionado: el mismo bot cerró #1624 con la misma redacción.

El texto envolvente nombra el protocolo que realmente se ejecutó

Como anthropic con una clave de API y anthropic-messages construyen proveedores distintos, sus envoltorios 404 difieren, lo que convierte la cadena de error en un diagnóstico gratuito.

Por qué el consejo 404 de PicoClaw puede llevarte por el camino equivocado

La guía de proveedores de PicoClaw te indica cambiar a anthropic-messages cuando «El protocolo anthropic existente devuelve errores 404 (lo que indica que el endpoint no admite el formato compatible con OpenAI)», y añade la nota que aclara la nomenclatura: «El protocolo anthropic utiliza un formato compatible con OpenAI (/v1/chat/completions), mientras que anthropic-messages utiliza el formato nativo de Anthropic (/v1/messages).» Ambas citas se volvieron a leer en v0.3.1 el 21 de septiembre de 2026.

Ese consejo es correcto para un 404 de ruta y erróneo para un 404 de modelo. Además, aparece 294 líneas por debajo de una tabla del mismo archivo cuya columna Protocol muestra Anthropic para la fila anthropic, lo que afirma lo contrario. El código resuelve la contradicción de una forma poco evidente: anthropic son dos protocolos según auth_method. Con oauth o token construye el proveedor SDK nativo de Anthropic y la tabla es correcta; con una clave de API recurre al mismo proveedor compatible con OpenAI que utiliza openai y toda su familia, y la nota es correcta.

De aquí se derivan dos consecuencias directas. En la familia openai, escribir https://api.kunavo.com en lugar de https://api.kunavo.com/v1 construye https://api.kunavo.com/chat/completions: un 404 de ruta causado por tu propia configuración, y el más común. En ambos protocolos de Anthropic ese error es imposible, porque /v1 se fuerza en cualquier caso; pero ese mismo forzado significa que una puerta de enlace cuya ruta no deba terminar en /v1 no puede expresarse mediante ellos y debe pasar por el protocolo openai. La propia documentación de PicoClaw utiliza esta vía de escape para un proveedor cuya base termina en un segmento de versión diferente.

Una afirmación que debe considerarse no resuelta. El único comentario sobre el problema de PicoClaw #269 afirma que publicar en /v1/chat/completions devuelve 404 en Anthropic porque el endpoint correcto es /v1/messages. La propia documentación de Anthropic lo contradice: publica una capa de compatibilidad con el SDK de OpenAI con base_url https://api.anthropic.com/v1/ y marca el encabezado authorization como «Fully supported» (comprobado el 21 de septiembre de 2026), aunque advierte en la misma página que la capa «no se considera una solución a largo plazo ni preparada para producción para la mayoría de los casos de uso». El problema #269 se cerró el 13 de marzo de 2026 sin comentario de cierre; la API de problemas muestra un comentario, el análisis anterior, procedente de una cuenta sin asociación con el repositorio, por lo que se desconoce qué lo resolvió realmente. Confía en tu propio cuerpo 404 por encima de cualquiera de las dos cuentas.

Cuando el 404 corresponde al id del modelo

El problema de PicoClaw #1624 —abierto el 16 de marzo de 2026 y cerrado el 31 de marzo de 2026— registra el cuerpo exacto para un id de Claude con puntos configurado como "model": "anthropic/claude-sonnet-4.6": Status: 404 con {"error":{"code":"not_found_error","message":"model: claude-sonnet-4.6 was not found. Did you mean claude-sonnet-4-6?"…. Su título y su único comentario se volvieron a leer en la API de problemas el 21 de septiembre de 2026: el comentario procede del bot de problemas obsoletos, por lo que el problema está cerrado, pero no hay pruebas de una corrección.

Una sugerencia «did you mean» es la señal inequívoca. Solo procede de un endpoint que analizó la solicitud, por lo que la ruta funcionó y ningún cambio de protocolo ayudará. La razón por la que PicoClaw no corrige la escritura por ti es concreta y comprobable: strings.ReplaceAll(model, ".", "-") aparece una vez en el repositorio, en pkg/providers/anthropic/provider.go línea 219, el proveedor SDK utilizado en las rutas OAuth y token. Ni anthropic_messages/provider.go ni openai_compat/provider.go la contienen. Ambas afirmaciones se volvieron a comprobar en v0.3.1 el 21 de septiembre de 2026, y la investigación previa a esta página volvió a obtener los mismos archivos desde main ese mismo día, con el mismo resultado. Ejecutar el binario v0.3.1 el 1 de octubre de 2026 lo confirmó en ambas rutas de clave de API: el id con puntos llegó al endpoint exactamente como estaba escrito y volvió como el propio 404 del endpoint (consulta lo que mostró la ejecución de v0.3.1). La ruta OAuth y token, la única con la reescritura, no se ejecutó.

Los propios archivos de PicoClaw también discrepan sobre la escritura: provider_metadata.go enumera ids con guiones para ambas entradas de Anthropic, el ejemplo anthropic de la guía de proveedores utiliza uno con puntos y anthropic-messages devuelve un valor predeterminado con puntos desde GetDefaultModel, la misma escritura que #1624 muestra como rechazada. Todos los ids de API de Claude impresos en la descripción general de modelos de Anthropic utilizan guiones, y esa página enumera Claude Sonnet 4.6 y Claude Opus 4.6 bajo «Legacy models (still available)»; por tanto, la retirada no es la razón por la que un id 4.6 produciría un 404 hoy en Anthropic. Esto descarta una causa, no todas: una puerta de enlace que no tenga el modelo aún puede rechazar un id con guiones. Copia el id del endpoint al que llamas, no de un README.

Escribe ambas entradas explícitamente y conserva el id con guiones. Las claves no pertenecen a este archivo: PicoClaw las lee de ~/.picoclaw/.security.yml, como se explica en la guía de configuración.

{
  "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"
    }
  ]
}

La primera entrada proporciona /v1 por sí misma porque la familia compatible con OpenAI concatena /chat/completions a api_base literalmente. La segunda lo omite deliberadamente para mostrar que, en anthropic-messages, ambas escrituras se normalizan a la misma base. La URL base publicada de Kunavo es https://api.kunavo.com/v1 para completions de chat y https://api.kunavo.com/v1/messages para la ruta Messages. Que los dos conjuntos de aritmética de URL coincidan es aritmética sobre dos conjuntos de documentación; el 1 de octubre de 2026 ambas entradas se ejecutaron desde v0.3.1 contra Kunavo con una clave deliberadamente no válida: la entrada openai llegó a /v1/chat/completions y la entrada anthropic-messages llegó a /v1/messages, y cada una recibió el 401 de Kunavo. Eso demuestra las URL, no una solicitud completada: nada de esta página afirma que se haya probado una integración. Para la forma general de la cuestión de la URL base, consulta la documentación de URL base de Anthropic.

Una puerta de enlace también puede responder 404 deliberadamente, y eso no es un error de PicoClaw. Kunavo devuelve 404 para un modelo pausado temporalmente, con un cuerpo que nombra el modelo y el reemplazo que debe utilizarse, y omite los modelos pausados de /v1/models; compara la estructura de ese mensaje, no un nombre concreto, porque los modelos pausados cambian. Kunavo tampoco ofrece modelos de embeddings, texto a voz ni voz a texto, por lo que una entrada de model_list que nombre uno de ellos devolverá 404 independientemente del protocolo que elijas; apunta esas entradas a otro proveedor y conserva solo entradas de chat en una clave de Kunavo.

Lo que mostró la ejecución de v0.3.1

El 1 de octubre de 2026, el binario de lanzamiento v0.3.1, verificado mediante la suma de comprobación frente al propio archivo de sumas de comprobación de la versión, se ejecutó en un contenedor desechable con una entrada de model_list cada vez y picoclaw agent -m. El endpoint era un servidor local de grabación que se comportaba como el enrutamiento de Kunavo en ese momento —/v1/* es la API; cualquier otra ruta devolvía una página HTML 404 (Kunavo ahora responde a esas rutas con un 404 JSON que indica la corrección; consulta las filas de Kunavo)— y conocía claude-sonnet-5 y claude-sonnet-4-6, pero no el id con puntos; las tres últimas filas utilizaron el api.kunavo.com real con una clave deliberadamente no válida, por lo que nada de ello se facturó.

Esta ejecución resuelve dos cuestiones que la lectura del código solo podía predecir. El envoltorio de error realmente nombra al proveedor que se ejecutó, por lo que es seguro deducir el protocolo a partir de él; y un id con puntos se envía sin cambios en ambas rutas de clave de API, por lo que un «model not found» que cite un id con puntos se corrige volviendo a escribir el id, no cambiando de protocolo. Lo que no cubre: las rutas OAuth y token, la interfaz web del iniciador, el streaming y cualquier solicitud completada a través de Kunavo; las filas de Kunavo utilizaron deliberadamente una clave no válida.

El orden de comprobación más breve

1. ¿Salió algo de la máquina? Un error de terminal que contenga not found in model_list sin estado HTTP es local. Haz que agents.defaults.model_name sea igual a una entrada de model_name y detente ahí.
2. ¿Procedía de localhost? Un 404 en el navegador al elegir un modelo predeterminado en la interfaz web de PicoClaw es el mismo desajuste, servido por el propio backend de PicoClaw. No intervino ninguna API de modelos.
3. ¿Qué proveedor se ejecutó? Compara el texto del envoltorio con la tabla anterior. Si el envoltorio no coincide con el protocolo que crees haber configurado, el campo provider o el prefijo del modelo no son lo que crees.
4. ¿404 de ruta o 404 de modelo? Un cuerpo que nombre tu modelo, especialmente con una sugerencia did you mean, es un 404 de modelo: corrige el id. Una página HTML, un cuerpo vacío o un not-found genérico es un 404 de ruta: vuelve a derivar la URL ensamblada a partir de la tabla antes de tocar cualquier otra cosa.
5. Pregunta al endpoint qué ofrece. PicoClaw no puede hacerlo con ninguno de los dos protocolos de Anthropic, porque ninguna de las dos entradas del catálogo establece el indicador de consulta. Usa curl contra el propio /v1/models de la puerta de enlace o apunta temporalmente la misma puerta de enlace al protocolo openai. Model not found across providers cubre ese método, y Anthropic 404 model not found cubre los casos en los que el propio id es el problema.
6. Cambia de protocolo solo ahora, y solo si el paso 4 indicó un 404 de ruta. Si el bloqueo es el encabezado de autenticación y no el formato de la transmisión, auth token versus api key explica la diferencia.
7. Vuelve a verificar con una ronda de herramientas, no con un turno de chat simple. Una configuración que responde a un mensaje sencillo aún puede fallar en la primera llamada a una herramienta, por lo que la tarea acotada que utilices para confirmar la corrección debe incluir una.

El coste que te impone la elección del protocolo

La consecuencia de mayor coste es la caché de prompts, y es estructural, no una configuración. En PicoClaw v0.3.1, el único código que emite un punto de interrupción de caché está en pkg/providers/anthropic/provider.go, al que solo se llega por las rutas OAuth y token. Con una clave de API —el caso normal de aportar tu propia clave—, ninguno de los dos protocolos de Anthropic envía cache_control. Frente a la propia capa de compatibilidad de Anthropic, esto se acumula porque su documentación afirma claramente que «Prompt caching is not supported, but it is supported in the Anthropic SDKs». Frente a una puerta de enlace que inserta puntos de interrupción para clientes con formato OpenAI, el ahorro se recupera en la propia puerta de enlace; la documentación de caché de Kunavo dice que lo hace y delimita exactamente su alcance: modelos Claude a los que se llega mediante /v1/chat/completions o /v1/responses. La misma página dice que cache_control se transmite sin traducir en la ruta nativa Messages, por lo que la entrada anthropic-messages no obtiene puntos de interrupción de ninguno de los dos lados y la segunda columna siguiente describe únicamente la entrada del protocolo openai. No se comprobó si otras puertas de enlace insertan puntos de interrupción, y nada de esto se observó desde dentro de PicoClaw.

Lo que eso vale es aritmética ilustrativa de tokens, no el coste medido de una tarea ni un límite máximo de facturación. Supongamos un turno del agente de 10 rondas de herramientas, donde cada ronda reenvía el mismo prefijo de 20,000 tokens (prompt del sistema, esquemas de herramientas y transcripción hasta ese momento), añade 1,000 tokens de entrada nuevos y devuelve 600 tokens de salida. Esas proporciones son supuestos ilustrativos. La primera columna factura la entrada de cada ronda a la tarifa completa; la segunda factura el prefijo repetido a la tarifa de lectura de caché desde la segunda ronda. Las tarifas son precios actuales del catálogo de Kunavo por millón de tokens.

Con estos supuestos, Claude Sonnet 4.6 pasa de $0.504 a $0.164 para el mismo trabajo. Lee la segunda columna como optimista: las escrituras en caché se facturan a su propia tarifa y no se modelan en ninguna de las dos direcciones, y un prefijo que cambia en cada ronda nunca se convierte en un acierto de caché. Multiplica por los turnos diarios antes de considerar cualquiera de estas cifras como un presupuesto.

Mientras tanto, separa las dos facturas. PicoClaw es gratuito: el repositorio tiene licencia MIT y ningún protocolo, incluidos los dos de Anthropic, está bloqueado detrás de algo que haya que comprar. El coste recurrente son los tokens del modelo, según la tarifa de tu proveedor. El importe del catálogo de Kunavo es un mínimo de facturación, no un límite máximo: cuando el upstream informa de su cargo, la factura es el mayor valor entre el coste del catálogo y el coste del upstream multiplicado por el margen aplicable. La recarga mínima es de $10 en crédito prepago, un mínimo de financiación, no una tarifa por tarea ni una suscripción; consulta los detalles de facturación.

Proveedor directo, gateway, suscripción o servicio local

¿Estás eligiendo el runtime en lugar de la ruta? PicoClaw frente a OpenClaw compara ambos por su estructura de despliegue. Si terminas usando un gateway y quieres financiar una clave, crea una cuenta de Kunavo y después envía una tarea acotada que incluya una llamada a una herramienta; luego consulta el cargo que tu cuenta registró realmente.

Preguntas frecuentes

Comprobado el 21 de septiembre de 2026. Verificado de nuevo en esta tarea con la etiqueta v0.3.1: la nota sobre protocolos y la fila del proveedor Anthropic de la guía de proveedores; la rama anthropic y el brazo predeterminado de factory_provider.go, NormalizeBaseURL; la URL, las cabeceras y la cadena 404 de anthropic-messages; la concatenación de URL y la cabecera Bearer de openai_compat; las tres cadenas «not found in model_list» previas a HTTP; el 404 del backend web; la única aparición del reemplazo de punto por guion; la columna SupportsFetch de la tabla de opciones de proveedores; y el ejemplo de OpenRouter en docs/operations/troubleshooting.md; además de la API de versiones (v0.3.1, publicada el 3 de julio de 2026) y los títulos, estados, fechas y comentarios de las incidencias #1624, #958 y #269. La página de compatibilidad del SDK de OpenAI de Anthropic se consultó el mismo día. Ejecutado el 1 de octubre de 2026: el binario de la versión v0.3.1 en un contenedor contra un endpoint de grabación local y, con una clave inválida, contra Kunavo; todas las filas de la tabla anterior. No se verificó nada de main más allá de los archivos comparados por la investigación; tampoco qué cerró la incidencia #269, las rutas de OAuth y tokens, ni ninguna solicitud completada mediante Kunavo. Las tarifas de tokens de Kunavo proceden del catálogo actual, y todas las cifras en dólares aquí son aritmética ilustrativa de tokens.