En-tête de session manquant dans nanobot OpenCode Go : vérifications de version et de route

nanobot a commencé à envoyer l’en-tête x-opencode-session dans v0.3.5, publiée le 15 septembre 2026 ; les versions jusqu’à v0.3.0 n’envoyaient qu’un identifiant x-session-affinity générique, ce qui explique l’écart de version à l’origine de l’échec lié à l’en-tête de session manquant avec OpenCode Go. Exécutez nanobot --version avant toute autre modification : s’il indique v0.3.0 ou une version antérieure, la mise à niveau constitue toute la correction pour cet en-tête précis. Ce que la mise à niveau ne règle pas, c’est le reste du contrat client d’OpenCode Go ; c’est cette partie qu’il vaut la peine de lire avant de conclure que la route fonctionne correctement.

Commençons par une clarification, car les noms se ressemblent. OpenCode Go désigne ici l’abonnement de modèles à 10 $/mois actuellement proposé, documenté sur opencode.ai/docs/go — et non l’agent terminal OpenCode archivé écrit en Go, dont le README indique que le projet a continué sous le nom Crush avec l’auteur d’origine et l’équipe Charm. Il ne s’agit pas d’une note de migration concernant un produit retiré ; c’est une page de dépannage consacrée à un service actuellement vendu qui a renforcé une exigence client. Ici, nanobot désigne HKUDS/nanobot, le framework Python d’agent personnel sous licence MIT — 48,459 étoiles, non archivé, dernière contribution le jour de cette vérification (API GitHub, 21 septembre 2026) — et non le projet Go du même nom chez obot-platform.

L’erreur et les versions de nanobot concernées

L’avis à l’origine de cette situation est parvenu aux abonnés sous la forme d’une notification du fournisseur, et non d’une documentation. Un utilisateur l’a cité intégralement dans anomalyco/opencode#47438, ouverte le 5 septembre 2026 contre le client d’OpenCode lui-même, en la décrivant comme une notification du fournisseur de modèles reçue par e-mail : « Certaines de vos requêtes vers OpenCode Go ne contiennent pas d’en-tête x-opencode-session. Sans celui-ci, nous ne pouvons pas optimiser correctement notre service. À partir du 09/06, les requêtes dépourvues de cet en-tête pourront générer une erreur. » Nous n’avons trouvé cette formulation dans aucune documentation d’OpenCode. Le journal des modifications d’OpenCode, consulté le 21 septembre 2026, couvre la période du 4 août au 14 septembre 2026 dans v1.18.31 et ne contient aucune entrée mentionnant x-opencode-session. La documentation Go le formule comme une demande, et non comme un rejet : « Envoyez un identifiant de session stable dans x-opencode-session pour chaque conversation afin que nous puissions optimiser le routage et la mise en cache des prompts. »

La date du 09/06 dispose bien d’une source publique officielle, mais pas documentaire : l’issue #5661 et la PR #5662 de nanobot citent toutes deux une publication de @opencode sur X datée du 3 septembre 2026, qu’elles reproduisent comme indiquant que les outils dépourvus de l’en-tête perdent l’optimisation du cache de prompts et que « À partir du 09/06, les requêtes dépourvues de cet en-tête pourront générer une erreur. » Cette publication est l’annonce sur laquelle la correction de nanobot a été fondée ; cette page ne l’a pas récupérée indépendamment.

L’échec bloquant n’est étayé que par des tiers. vastsa/PI-Desktop#48, ouverte et fermée le 7 septembre 2026, consigne HTTP 400 avec "type": "MissingSessionID" et un message indiquant que la requête ne contient pas x-opencode-session et ne peut pas être acheminée efficacement, en renvoyant vers l’ancre de la documentation Go. La documentation Go d’OpenCode ne contient aucune référence d’erreur répertoriant ce code d’état ou cette chaîne de type ; lisez donc l’obligation documentée et le rejet rapporté comme deux degrés de preuve différents provenant du même fournisseur.

Il n’existe aucune version v0.3.1 à v0.3.4 dans l’historique des tags ; « v0.3.0 et les versions antérieures » constitue donc toute la plage concernée. Deux vérifications ont confirmé la correspondance avec la version publiée le 21 septembre 2026, plutôt que de l’inférer : le contenu de la version répertorie la PR #5662 par son numéro, et un appel de comparaison GitHub indique que v0.3.5 a 84 commits d’avance et aucun commit de retard sur 20f115bf, ce qui place le commit dans le tag. Notez que la documentation de nanobot v0.3.5 ne mentionne jamais l’en-tête — les seuls enregistrements de la modification sont les notes de version, la PR et l’issue.

Ce que fait réellement la correction et ce qui la déclenche

Lue dans le tag v0.3.5 de nanobot/providers/openai_compat_provider.py, la logique est courte et mérite d’être connue avec précision. nanobot considère une cible comme une cible OpenCode lorsque la spécification du fournisseur est nommée opencode, opencode_zen ou opencode_go, ou lorsque le nom d’hôte de l’URL de base est opencode.ai ou un sous-domaine de celui-ci. Lorsqu’un contexte de conversation existe, la valeur de l’en-tête est le condensat hexadécimal SHA-256 de l’identifiant de session, ce qui le garde opaque et compatible ASCII pour les identifiants non ASCII. Lorsqu’il n’existe aucun contexte de conversation, l’instance du fournisseur utilise un UUID aléatoire, fixe pendant sa propre durée de vie — stable pour cette instance, et non par conversation. Un en-tête que vous avez configuré vous-même est prioritaire dans les deux cas, avec une correspondance insensible à la casse sur le nom.

La clause relative au nom d’hôte est la phrase à retenir : l’en-tête est ajouté en raison de la destination de la requête, et non du bloc fournisseur que vous avez écrit. Un bloc providers.custom générique dirigé vers une URL de base opencode.ai le reçoit également. Une requête vers tout autre hôte ne le reçoit pas — ce que cet hôte exige à la place relève de son propre fournisseur, et rien ici ne permet d’y répondre.

La mise à niveau est classique : le paquet PyPI est nanobot-ai, en version 0.3.5 dans le pyproject.toml de ce tag, et le README de v0.3.5 documente uv tool install nanobot-ai et python -m pip install nanobot-ai. Confirmez avec nanobot --version, ou avec python -m nanobot --version si le point d’entrée ne se trouve pas dans PATH, puis avec nanobot status, que la référence CLI décrit comme une vérification de l’état de préparation du fournisseur et du modèle sans appeler de modèle.

Pourquoi OpenCode Go n’est pas un simple endpoint compatible avec OpenAI

C’est ce qui donne l’impression qu’une correction de l’en-tête est incomplète. OpenCode Go énonce plusieurs conditions côté client qu’une URL de base ordinaire compatible avec OpenAI n’énonce pas, et l’en-tête de session n’en est qu’une. Toutes les lignes ci-dessous proviennent de sa propre documentation, vérifiée le 21 septembre 2026.

La ligne concernant le user agent appelle à la prudence. La PR #5662 a uniquement modifié l’en-tête de session. À la lecture du code source de nanobot v0.3.5, le module du fournisseur compatible avec OpenAI — celui qui sert les spécifications opencode, opencode_zen et opencode_go — ne définit User-Agent nulle part, tandis que les modules des fournisseurs GitHub Copilot, xAI Grok et OpenAI Codex en définissent chacun un aux couleurs de nanobot. Sur cette route, la requête transporte donc ce que le SDK sous-jacent envoie par défaut. Aucune requête n’a été envoyée ici pour observer la valeur, et OpenCode n’a publié aucune mesure d’application concernant cette ligne ; il s’agit donc d’une lecture du code source, et non d’un échec reproduit. La solution documentée consiste à définir soi-même un en-tête — la référence de nanobot décrit providers.<name>.extraHeaders comme des en-têtes fusionnés dans les requêtes du fournisseur :

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

Nommez-y honnêtement votre propre client. Inscrire dans ce champ le nom de l’un des clients validés par OpenCode constituerait une usurpation d’identité, et non une identification ; ce n’est pas ce que demande la documentation.

La ligne concernant l’endpoint a une conséquence propre à nanobot qu’aucun en-tête ne peut corriger. La référence du fournisseur de v0.3.5 indique d’utiliser les identifiants de modèle qu’OpenCode répertorie sous l’endpoint chat/completions, car les modèles répertoriés uniquement sous responses, messages ou des endpoints propres au fournisseur ne sont pas pris en charge par cette route compatible avec OpenAI. Dans la configuration, OpenCode Go correspond à providers.opencodeGo avec un preset dont le provider est opencode_go, et les identifiants de modèle portent le préfixe opencode-go/ que nanobot retire avant l’envoi. Enfin, la page Go d’OpenCode publie une liste de clients validés (Hermes, Claude Code, Codex, ZCode, Pi, jcode et Kilo Code CLI) et une liste de clients dont la prise en charge des sessions est absente ou incomplète (DeepSeek Harness, GitHub Copilot Chat, Kimi Code et MiMo Code). nanobot ne figure sur aucune des deux listes au 21 septembre 2026 — une absence de verdict publié, ni une approbation ni un blocage. Cette page mentionne également des exigences de version propres à chaque client, qui n’ont pas été reprises ici ; n’en déduisez donc aucune version minimale pour ces clients à partir de cette page.

Vérifier avec une requête expurgée

La documentation de nanobot v0.3.5 ne décrit aucun moyen d’afficher ses en-têtes sortants ; vérifiez donc directement le contrat avec votre propre abonnement avant de tirer une conclusion sur le client. Ne lisez que la ligne d’état.

# 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}'

Cela distingue clairement deux échecs : une erreur 400 mentionnant MissingSessionID concerne l’en-tête, et toute autre erreur ne le concerne pas. Ne faites pas tourner un nouvel identifiant aléatoire à chaque requête pour faire disparaître l’erreur, et n’empruntez pas le nom d’un autre client. La documentation demande précisément un identifiant stable par conversation parce que le routage et la mise en cache des prompts l’utilisent comme clé ; un identifiant par requête neutralise donc la mise en cache que vous payez tout en donnant l’apparence d’une correction. Les deux réponses légitimes consistent à mettre à niveau ou à déplacer cette charge de travail vers une route qui n’impose pas cette exigence.

Ce que cela coûte et quelle route l’emporte

Gardez le logiciel séparé des tokens. nanobot lui-même coûte 0 $ — sous licence MIT et auto-hébergé, selon la fiche du dépôt consultée le 21 septembre 2026 — ; tout ce qui suit correspond donc à la facture des modèles et à la machine sur laquelle il s’exécute.

La ligne Zen provient de sa propre documentation, consultée le 21 septembre 2026 ; Zen et Go sont des produits facturés séparément, donc un tarif Zen n’est pas celui que paie un abonné Go, et la propre liste de Zen indique que plusieurs modèles sont temporairement gratuits pendant que les fournisseurs recueillent des retours. Les tarifs d’OpenCode couvrent les coûts propres au client.

L’abonnement ne peut pas être converti dans le tableau ci-dessous, et prétendre le contraire est l’erreur la plus facile à commettre ici. L’allocation de Go est libellée en dollars aux propres tarifs par modèle de Go, et chaque modèle possède son propre plafond : l’exemple développé dans la documentation est un modèle avec un plafond mensuel de 60 $ autorisant 12 $ d’utilisation par période de 5 heures et 30 $ par semaine, tandis que les lignes de modèles consultées le 21 septembre 2026 indiquent GLM-5.3-Flash à 0,15 $ en entrée et 0,50 $ en sortie par million de tokens, avec une limite mensuelle de 60 $ et environ 31 580 requêtes par mois. Il s’agit des estimations d’OpenCode pour son propre catalogue, et non de garanties ; une ligne comportait une promotion datée qui expire peu après la rédaction de ce texte. Pour une charge de travail compatible avec la liste de modèles et les fenêtres de Go, 10 $ permettent beaucoup d’utilisation facturée à l’usage ; la comparaison porte réellement sur l’adéquation de vos modèles et de vos pics d’activité à ces limites.

Une passerelle facturée à l’usage tarifie différemment la même charge de travail. Il s’agit d’un calcul illustratif de tokens, et non de coûts mesurés par tâche ni d’un plafond de facture : supposons qu’un assistant nanobot consomme 3,000,000 tokens d’entrée non mis en cache et 300,000 tokens de sortie sur un mois, aux tarifs actuels du catalogue Kunavo par million de tokens.

Multipliez ces montants par votre propre trafic avant de les considérer comme un budget, et notez qu’une planification en arrière-plan peut faire varier la colonne d’entrée bien davantage que le choix du modèle — le coût et la configuration de l’API nanobot analysent la cadence que nanobot active par défaut. Le montant du catalogue Kunavo constitue un plancher de facturation plutôt qu’un plafond : lorsque l’amont communique son tarif, la facture correspond au montant le plus élevé entre le coût du catalogue et le coût amont multiplié par la majoration applicable. Les frais de cache, les outils et l’hébergement sont exclus de cet exemple, et le rechargement minimal est de $10 en crédit prépayé — un minimum de financement, et non des frais de tâche ou un abonnement. Consultez les détails de facturation.

Dans quels cas Kunavo aide ou n'aide pas

Il est plus important d'être direct à ce sujet que de favoriser une conversion. Kunavo ne revend pas OpenCode Go ni Zen, et diriger nanobot vers https://api.kunavo.com/v1 ne rétablit pas un abonnement OpenCode Go. Cela évite plutôt cette exigence, car x-opencode-session appartient aux hôtes opencode.ai — et, selon la règle de nom d'hôte du code source de v0.3.5, nanobot n'ajoutera cet en-tête à aucune autre URL de base. Ce que le point de terminaison de Kunavo ferait avec un tel en-tête n'a pas été testé ici, pas plus que nanobot avec Kunavo : il n'existe aucune page d'intégration nanobot, et toutes les affirmations de configuration ci-dessus sont une lecture de la documentation des fournisseurs et du code source distribué, et non un résultat de compatibilité.

Considérez donc ces routes comme des solutions de remplacement présentant des compromis différents, et non comme un correctif et un contournement. Si une route compatible avec OpenAI et facturée à l'usage convient à votre charge de travail, le démarrage rapide présente la convention du point de terminaison, et la création d'un compte Kunavo est l'étape préalable à l'approvisionnement d'une clé — gardez une route fonctionnelle à disposition pendant vos essais, exécutez une tâche limitée, puis consultez ce que votre compte a enregistré à ce sujet. Si vous cherchiez l'agent de terminal Go archivé plutôt que l'abonnement, la documentation d'intégration de Crush présente son successeur, et la documentation d'intégration d'OpenCode présente le client TypeScript actuel. Pour une comparaison plus large, consultez l'API compatible avec OpenAI et l'annuaire des API d'agents ; pour un autre problème OpenCode, fournisseur ou modèle introuvable constitue le diagnostic.

Questions fréquentes

Vérifié le 21 septembre 2026 : la documentation et le journal des modifications de opencode.ai concernant Go et Zen ; l'API GitHub pour les versions, tags, PR #5662, issue #5661 de HKUDS/nanobot ainsi qu'un appel compare prouvant que le commit se trouve dans le tag v0.3.5 ; anomalyco/opencode#47438 et vastsa/PI-Desktop#48 pour l'avis cité et l'erreur 400 signalée ; et l'archive tar du code source de v0.3.5 pour chaque affirmation concernant ce que nanobot envoie. La date du 09/06 provient d'une publication de @opencode sur X datée du 3 septembre 2026, que l'issue et la PR de nanobot citent mais que cette page n'a pas récupérée ; l'avis cité destiné aux abonnés et le contrat d'erreur 400 sont rapportés par des utilisateurs, et aucun des deux n'apparaît dans la documentation ou le journal des modifications d'OpenCode. Personne ici n'a exécuté nanobot avec OpenCode Go ou avec Kunavo, ni reproduit l'échec ; les tarifs des tokens Kunavo proviennent du catalogue en ligne et chaque montant en dollars est un calcul illustratif fondé sur les hypothèses indiquées.