nanobot OpenCode Go: falta la cabecera de sesión; comprobaciones de versión y ruta

nanobot comenzó a enviar el encabezado x-opencode-session en v0.3.5, publicada el 15 de septiembre de 2026; las versiones hasta v0.3.0 solo enviaban un id genérico x-session-affinity, que es la diferencia de versión detrás del fallo por ausencia del encabezado de sesión frente a OpenCode Go. Ejecuta nanobot --version antes de cambiar cualquier otra cosa: si informa v0.3.0 o anterior, la actualización es toda la solución para ese encabezado concreto. Lo que la actualización no resuelve es el resto del contrato de cliente de OpenCode Go, y esa es la parte que conviene leer antes de concluir que la ruta funciona correctamente.

Primero, una aclaración, porque los nombres se solapan. Aquí OpenCode Go es la suscripción activa de modelos de $10/mes documentada en opencode.ai/docs/go, no el agente de terminal OpenCode escrito en Go y archivado, cuyo propio README indica que el proyecto continuó bajo el nombre Crush con el autor original y el equipo de Charm. Esto no es una nota de migración sobre un producto retirado; es una página de resolución de problemas sobre un servicio que se vende actualmente y que endureció un requisito del cliente. Y aquí nanobot es HKUDS/nanobot, el framework de agente personal en Python con licencia MIT — 48,459 estrellas, no archivado, con el último push realizado el día de esta comprobación (API de GitHub, 21 de septiembre de 2026) —, no el proyecto de Go del mismo nombre en obot-platform.

El error y las versiones de nanobot que lo presentan

El aviso que inició todo esto llegó a los suscriptores como una notificación del proveedor, no como documentación. Un usuario lo citó textualmente en anomalyco/opencode#47438, abierto el 5 de septiembre de 2026 contra el propio cliente de OpenCode y descrito como una notificación del proveedor de modelos recibida por correo electrónico: "Some of your requests to OpenCode Go are missing an x-opencode-session header. If we don't have this we cannot properly optimize our service. Starting 09/06 requests missing this header may error." Ese texto no aparece en ninguna documentación de OpenCode que pudiéramos encontrar. El registro de cambios de OpenCode, consultado el 21 de septiembre de 2026, cubre del 4 de agosto al 14 de septiembre de 2026 en v1.18.31 y no contiene ninguna entrada que mencione x-opencode-session. La documentación de Go lo formula como una solicitud, no como un rechazo: «Enviar un ID de sesión estable en x-opencode-session para cada conversación para que podamos optimizar el enrutamiento y el almacenamiento en caché de prompts.»

La fecha 09/06 sí tiene una fuente pública oficial, aunque no documental: el issue #5661 y el PR #5662 de nanobot citan ambos una publicación de @opencode en X fechada el 3 de septiembre de 2026, que según su cita dice que las herramientas que no incluyan el encabezado perderán la optimización de la caché de prompts y que "Starting 09/06 requests missing this header may error." Esa publicación es el anuncio contra el que se escribió la corrección de nanobot; esta página no la ha recuperado de forma independiente.

El fallo grave solo está respaldado por terceros. vastsa/PI-Desktop#48, abierto y cerrado el 7 de septiembre de 2026, registra HTTP 400 con "type": "MissingSessionID" y un mensaje que indica que a la solicitud le falta x-opencode-session y no puede enrutarse de forma eficiente, apuntando al ancla de la documentación de Go. La documentación de OpenCode Go no contiene ninguna referencia de errores que enumere ese código de estado o esa cadena de tipo, así que interpreta la obligación documentada y el rechazo informado como dos niveles de afirmación diferentes del mismo proveedor.

No existe v0.3.1 a v0.3.4 en el historial de etiquetas, por lo que "v0.3.0 y anteriores" es todo el rango afectado. Dos comprobaciones confirmaron la correspondencia de la versión el 21 de septiembre de 2026 en lugar de inferirla: el cuerpo de la versión enumera el PR #5662 por número, y una llamada de comparación de GitHub informa que v0.3.5 está 84 commits por delante de 20f115bf y ninguno por detrás, lo que sitúa el commit dentro de la etiqueta. Ten en cuenta que la documentación de nanobot v0.3.5 no menciona nunca el encabezado; los únicos registros del cambio son las notas de la versión, el PR y el issue.

Qué hace realmente la corrección y qué la activa

Leída en la etiqueta v0.3.5 en nanobot/providers/openai_compat_provider.py, la lógica es pequeña y merece conocerse con precisión. nanobot trata un destino como destino de OpenCode cuando la especificación del proveedor se llama opencode, opencode_zen o opencode_go, o cuando el hostname de la URL base es opencode.ai o un subdominio suyo. Cuando existe contexto de conversación, el valor del encabezado es el resumen hexadecimal SHA-256 del ID de sesión, lo que lo mantiene opaco y seguro para ASCII en el caso de IDs que no sean ASCII. Cuando no existe contexto de conversación, la instancia del proveedor recurre a un UUID aleatorio fijo durante su propia vida útil: estable para esa instancia, no por conversación. Un encabezado que hayas configurado tú mismo prevalece sobre ambos, comparando el nombre sin distinguir mayúsculas y minúsculas.

La cláusula del hostname es la frase que debes recordar: el encabezado se adjunta por el destino de la solicitud, no por el bloque de proveedor que escribiste. Un bloque genérico providers.custom dirigido a una URL base opencode.ai sigue recibiéndolo. Una solicitud a cualquier otro host no lo recibe; lo que ese host requiera en su lugar es asunto de su propio proveedor, y nada de lo que aparece aquí lo responde.

Actualizar es sencillo: el paquete de PyPI es nanobot-ai, está en 0.3.5 en el pyproject.toml de esa etiqueta, y el README de v0.3.5 documenta uv tool install nanobot-ai y python -m pip install nanobot-ai. Confirma con nanobot --version, o con python -m nanobot --version si el punto de entrada no está en PATH, y después nanobot status, que la referencia de la CLI describe como una comprobación de la preparación del proveedor y del modelo sin llamar a ningún modelo.

Por qué OpenCode Go no es un endpoint OpenAI-compatible corriente

Esta es la parte que hace que una corrección del encabezado parezca incompleta. OpenCode Go establece varias condiciones del lado del cliente que una URL base OpenAI-compatible ordinaria no establece, y el encabezado de sesión es solo una de ellas. Todas las filas siguientes proceden de su propia documentación, comprobada el 21 de septiembre de 2026.

La fila del agente de usuario requiere una advertencia. El PR #5662 cambió únicamente el encabezado de sesión. Al leer el código fuente de nanobot v0.3.5, el módulo de proveedor compatible con OpenAI — el que sirve las especificaciones opencode, opencode_zen y opencode_go — no establece User-Agent en ningún lugar, mientras que los módulos de proveedor de GitHub Copilot, xAI Grok y OpenAI Codex establecen cada uno uno con la marca nanobot. Por tanto, en esa ruta la solicitud lleva lo que el SDK subyacente envíe de forma predeterminada. Aquí no se envió ninguna solicitud para observar el valor, y OpenCode no ha publicado ninguna medida de aplicación para esa línea, así que esto es una lectura del código fuente y no un fallo reproducido. La solución documentada es un encabezado que establezcas tú mismo; la referencia de nanobot describe providers.<name>.extraHeaders como encabezados que se combinan con las solicitudes del proveedor:

{
  "providers": {
    "opencodeGo": {
      "apiKey": "${OPENCODE_API_KEY}",
      "extraHeaders": { "User-Agent": "nanobot/0.3.5" }
    }
  },
  "modelPresets": {
    "primary": {
      "provider": "opencode_go",
      "model": "opencode-go/<a model OpenCode lists under chat/completions>",
      "maxTokens": 8192,
      "contextWindowTokens": 65536
    }
  }
}

Nombra allí tu propio cliente con veracidad. Incluir en ese campo uno de los nombres de cliente validados por OpenCode sería suplantación, no identificación, y no es lo que solicita la documentación.

La fila del endpoint tiene una consecuencia específica para nanobot que ningún encabezado puede solucionar. La referencia de proveedores de v0.3.5 indica que se deben usar IDs de modelo que OpenCode enumere bajo el endpoint chat/completions, porque los modelos enumerados únicamente bajo responses, messages o endpoints específicos del proveedor no son gestionados por esa ruta compatible con OpenAI. En la configuración, OpenCode Go es providers.opencodeGo con un preset cuyo provider es opencode_go, y los IDs de modelo llevan el prefijo opencode-go/ que nanobot elimina antes de enviarlos. Por último, la página de OpenCode Go publica una lista de clientes validados (Hermes, Claude Code, Codex, ZCode, Pi, jcode y Kilo Code CLI) y otra con compatibilidad de sesión ausente o incompleta (DeepSeek Harness, GitHub Copilot Chat, Kimi Code y MiMo Code). nanobot no aparece en ninguna de las dos listas a fecha del 21 de septiembre de 2026: es la ausencia de un veredicto publicado, no una aprobación ni un bloqueo. Esa página también señala requisitos de versión por cliente que no se recogieron aquí, así que no deduzcas de esta página una versión mínima para ninguno de esos clientes.

Verifica con una solicitud con datos ocultos

La documentación de nanobot v0.3.5 no describe ninguna forma de mostrar sus encabezados salientes, así que confirma el contrato directamente frente a tu propia suscripción antes de concluir nada sobre el cliente. Lee únicamente la línea de estado.

# Read the status line only. Key redacted; session id is your own, stable per conversation.
curl -sS -o /dev/null -D - https://opencode.ai/zen/go/v1/chat/completions \
  -H "authorization: Bearer $OPENCODE_API_KEY" \
  -H "x-opencode-session: $(printf 'my-conversation-1' | shasum -a 256 | cut -d' ' -f1)" \
  -H "user-agent: nanobot/0.3.5" \
  -H "content-type: application/json" \
  -d '{"model":"<model-id>","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

Eso separa claramente dos fallos: un 400 que mencione MissingSessionID se refiere al encabezado, y cualquier otra cosa no se refiere al encabezado. No hagas rotar un ID aleatorio nuevo por solicitud para que desaparezca el error, ni tomes prestado el nombre de otro cliente. La documentación solicita un ID estable por conversación precisamente porque el enrutamiento y la caché de prompts se basan en él, así que un ID por solicitud anula la caché por la que estás pagando mientras aparenta ser una solución. Las dos respuestas legítimas son actualizar o trasladar esa carga de trabajo a una ruta que no tenga este requisito.

Cuánto cuesta y qué ruta gana

Mantén el software separado de los tokens. nanobot en sí cuesta $0: tiene licencia MIT y se autoaloja, según el registro del repositorio consultado el 21 de septiembre de 2026; por tanto, todo lo que aparece a continuación es la factura del modelo y la máquina en la que se ejecuta.

La fila de Zen procede de su propia documentación, consultada el 21 de septiembre de 2026; Zen y Go son productos facturados por separado, por lo que una tarifa de Zen no es lo que paga un suscriptor de Go, y la propia lista de Zen marca varios modelos como temporalmente gratuitos mientras los proveedores recopilan comentarios. Los precios de OpenCode cubren el coste propio del cliente.

La suscripción no puede convertirse en la tabla siguiente, y fingir lo contrario es el error más fácil aquí. La asignación de Go se denomina en dólares a las tarifas propias de Go por modelo, y cada modelo tiene su propio límite: el ejemplo trabajado de la documentación es un modelo de $60 al mes que permite $12 de uso por cada 5 horas y $30 por semana, mientras que las filas de modelos consultadas el 21 de septiembre de 2026 muestran GLM-5.3-Flash a $0.15 de entrada y $0.50 de salida por 1M, con un límite mensual de $60 y unos 31,580 requests mensuales estimados. Esas son estimaciones de OpenCode para su propio catálogo, no garantías, y una fila incluía una promoción fechada que caduca poco después de la redacción de este texto. Para una carga de trabajo que encaje con la lista de modelos y las ventanas de Go, $10 compra mucho uso medido; la comparación trata realmente de si tus modelos y tus ráfagas caben dentro de esos límites.

Una pasarela de pago por uso tarifica la misma carga de trabajo de otra manera. Estas son cálculos ilustrativos de tokens, no costes medidos de tareas ni un límite máximo de facturación: supón un asistente de nanobot que consuma 3,000,000 de tokens de entrada no almacenados en caché y 300,000 de salida al mes, a las tarifas activas del catálogo de Kunavo por millón de tokens.

Multiplica esas cifras por tu propio tráfico antes de tratarlas como un presupuesto, y ten en cuenta que una programación en segundo plano puede desplazar la columna de entrada mucho más que la elección del modelo: el coste y la configuración de la API de nanobot analizan la cadencia que nanobot habilita de forma predeterminada. El importe del catálogo de Kunavo es un mínimo de facturación, no un límite máximo: cuando el proveedor ascendente informa de su cargo, la factura es el mayor entre el coste del catálogo y el coste ascendente multiplicado por el margen aplicable. Los cargos de caché, las herramientas y el alojamiento quedan fuera de este ejemplo, y 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.

Dónde ayuda Kunavo y dónde no

Ser tajante al respecto importa más que una conversión. Kunavo no revende OpenCode Go ni Zen, y dirigir nanobot a https://api.kunavo.com/v1 no repara una suscripción de OpenCode Go. En su lugar, evita el requisito, porque x-opencode-session pertenece a hosts de opencode.ai; y, según la regla del nombre de host del código fuente de la v0.3.5, nanobot tampoco añadirá esa cabecera en ninguna otra URL base. Aquí no se ha probado qué haría el endpoint de Kunavo con una cabecera de ese tipo, ni tampoco nanobot contra Kunavo: no existe una página de integración de nanobot, y cada afirmación de configuración anterior es una lectura de la documentación del proveedor y del código fuente distribuido, no un resultado de compatibilidad.

Por tanto, trata las rutas como alternativas con diferentes compromisos, no como una solución y un apaño. Si una ruta compatible con OpenAI y con medición por uso se adapta a la carga de trabajo, el inicio rápido explica la convención del endpoint y crear una cuenta de Kunavo es el paso previo a cargar saldo en una clave; mantén disponible una ruta funcional mientras la pruebas, ejecuta una tarea acotada y después comprueba lo que tu cuenta registró para ella. Si llegaste buscando el agente de terminal Go archivado en lugar de la suscripción, la documentación de integración de Crush cubre su sucesor, y la documentación de integración de OpenCode cubre el cliente TypeScript actual. Para una comparación más amplia, consulta API compatible con OpenAI y el directorio de APIs para agentes; para otro fallo de OpenCode, proveedor o modelo no encontrado es el diagnóstico.

Preguntas frecuentes

Comprobado el 21 de septiembre de 2026: la documentación y el registro de cambios de opencode.ai sobre Go y Zen; la API de GitHub para las versiones, etiquetas, la PR #5662, el issue #5661 y una llamada de comparación que demuestra que el commit está incluido en la etiqueta v0.3.5 de HKUDS/nanobot; anomalyco/opencode#47438 y vastsa/PI-Desktop#48 para el aviso citado y el 400 comunicado; y el archivo tar del código fuente de la v0.3.5 para cada afirmación sobre lo que envía nanobot. La fecha 09/06 procede de una publicación de @opencode en X del 3 de septiembre de 2026 que citan el issue y la PR de nanobot, pero que esta página no recuperó; el aviso citado para suscriptores y el contrato de error 400 fueron comunicados por usuarios, y ninguno aparece en la documentación ni en el registro de cambios de OpenCode. Nadie aquí ha ejecutado nanobot contra OpenCode Go ni contra Kunavo, ni ha reproducido el fallo; las tarifas de tokens de Kunavo proceden del catálogo activo y cada cifra en dólares es un cálculo ilustrativo basado en los supuestos indicados.