Header di sessione mancante in nanobot OpenCode Go: controlli di versione e percorso

nanobot ha iniziato a inviare l'header x-opencode-session nella v0.3.5, pubblicata il 15 settembre 2026; le release fino a v0.3.0 inviavano solo un ID x-session-affinity generico, che rappresenta la differenza di versione alla base dell'errore relativo all'header di sessione mancante con OpenCode Go. Esegui nanobot --version prima di modificare qualsiasi altra cosa: se segnala v0.3.0 o precedente, l'aggiornamento è l'unica correzione necessaria per quel singolo header. Ciò che l'aggiornamento non risolve è il resto del contratto client di OpenCode Go, ed è questa la parte che vale la pena leggere prima di concludere che il percorso sia integro.

Prima una precisazione, perché i nomi si sovrappongono. Qui OpenCode Go è l'abbonamento ai modelli attivo da $10/mese documentato in opencode.ai/docs/go — non l'agente terminale OpenCode archiviato e scritto in Go, il cui README afferma che il progetto è proseguito con il nome Crush insieme all'autore originale e al team Charm. Questa non è una nota di migrazione su un prodotto ritirato; è una pagina di risoluzione dei problemi relativa a un servizio attualmente venduto che ha inasprito un requisito del client. E qui nanobot indica HKUDS/nanobot, il framework Python per agenti personali con licenza MIT — 48.459 stelle, non archiviato, con l'ultimo push effettuato il giorno di questa verifica (API GitHub, 21 settembre 2026) — non il progetto Go omonimo di obot-platform.

L'errore e le versioni di nanobot interessate

L'avviso che ha dato origine a tutto questo è arrivato agli abbonati come notifica del provider, non come documentazione. Un utente lo ha citato testualmente in anomalyco/opencode#47438, aperto il 5 settembre 2026 contro il client di OpenCode stesso e descritto come una notifica del provider del modello ricevuta via e-mail: "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." Non abbiamo trovato questa formulazione in alcuna documentazione di OpenCode. Il changelog di OpenCode, consultato il 21 settembre 2026, copre il periodo dal 4 agosto al 14 settembre 2026 alla v1.18.31 e non contiene alcuna voce che menzioni x-opencode-session. La documentazione Go lo formula come una richiesta, non come un rifiuto: «Invia un ID di sessione stabile in x-opencode-session per ogni conversazione, così possiamo ottimizzare l’instradamento e la memorizzazione nella cache dei prompt.»

La data 09/06 ha effettivamente una fonte pubblica ufficiale, anche se non documentale: il problema #5661 e la PR #5662 di nanobot citano entrambi un post di @opencode su X datato 3 settembre 2026, riportato con il testo secondo cui gli strumenti privi dell'header perdono l'ottimizzazione della cache dei prompt e che "Starting 09/06 requests missing this header may error." Quel post è l'annuncio sulla base del quale è stata scritta la correzione di nanobot; questa pagina non lo ha recuperato autonomamente.

Il malfunzionamento definitivo è dimostrato solo da terze parti. vastsa/PI-Desktop#48, aperto e chiuso il 7 settembre 2026, registra HTTP 400 con "type": "MissingSessionID" e un messaggio che indica che nella richiesta manca x-opencode-session e che non può essere instradata in modo efficiente, con riferimento all'ancora della documentazione Go. La documentazione Go di OpenCode non contiene alcun riferimento agli errori che elenchi quel codice di stato o quella stringa del tipo, quindi leggi l'obbligo documentato e il rifiuto segnalato come due livelli diversi di affermazione dello stesso vendor.

Nella cronologia dei tag non esiste v0.3.1 fino a v0.3.4, quindi "v0.3.0 e precedenti" è l'intero intervallo interessato. Due verifiche hanno confermato la corrispondenza della release il 21 settembre 2026, invece di dedurla: il corpo della release elenca la PR #5662 per numero e una chiamata GitHub compare segnala che v0.3.5 è avanti di 84 commit rispetto a 20f115bf e non ne ha nessuno indietro, collocando il commit all'interno del tag. Nota che la documentazione di nanobot v0.3.5 non menziona mai l'header — gli unici record della modifica sono le note della release, la PR e il problema.

Cosa fa realmente la correzione e cosa la attiva

Letta al tag v0.3.5 in nanobot/providers/openai_compat_provider.py, la logica è breve e merita di essere conosciuta con precisione. nanobot tratta una destinazione come destinazione OpenCode quando la specifica del provider si chiama opencode, opencode_zen o opencode_go, oppure quando il nome host dell'URL di base è opencode.ai o un suo sottodominio. Quando esiste un contesto di conversazione, il valore dell'header è il digest esadecimale SHA-256 dell'ID della sessione, che lo mantiene opaco e sicuro in ASCII per gli ID non ASCII. Quando non esiste un contesto di conversazione, l'istanza del provider ricorre a un UUID casuale fissato per tutta la propria durata — stabile per quell'istanza, non per conversazione. Un header configurato autonomamente ha la precedenza su entrambi, con confronto senza distinzione tra maiuscole e minuscole nel nome.

La clausola sul nome host è la frase da ricordare: l'header viene aggiunto in base alla destinazione della richiesta, non al blocco del provider che hai scritto. Anche un blocco providers.custom generico indirizzato a un URL di base opencode.ai riceve l'header. Una richiesta verso qualsiasi altro host non lo riceve — ciò che quell'host richiede invece è una questione del proprio vendor, e qui non viene fornita alcuna risposta.

L'aggiornamento è ordinario: il pacchetto PyPI è nanobot-ai, alla versione 0.3.5 nel suo pyproject.toml, e il README v0.3.5 documenta uv tool install nanobot-ai e python -m pip install nanobot-ai. Conferma con nanobot --version, oppure con python -m nanobot --version se il punto di ingresso non si trova in PATH, quindi esegui nanobot status, che il riferimento CLI descrive come un controllo della disponibilità del provider e del modello senza chiamare un modello.

Perché OpenCode Go non è un semplice endpoint compatibile con OpenAI

Questa è la parte che fa sembrare incompleta una correzione dell'header. OpenCode Go specifica diverse condizioni lato client che un normale URL di base compatibile con OpenAI non specifica, e l'header di sessione è solo una di queste. Tutte le righe qui sotto provengono dalla sua documentazione, verificata il 21 settembre 2026.

La riga relativa allo user agent richiede cautela. La PR #5662 ha modificato solo l'header di sessione. Dalla lettura del codice sorgente di nanobot v0.3.5, il modulo del provider compatibile con OpenAI — quello che serve le specifiche opencode, opencode_zen e opencode_go — non imposta User-Agent in alcun punto, mentre i moduli dei provider GitHub Copilot, xAI Grok e OpenAI Codex ne impostano ciascuno uno con il marchio nanobot. Pertanto, su quel percorso, la richiesta include qualunque valore l'SDK sottostante invii per impostazione predefinita. Qui non è stata inviata alcuna richiesta sulla rete per osservare il valore e OpenCode non ha pubblicato alcun meccanismo di applicazione per quella riga, quindi si tratta della lettura del codice sorgente, non di un errore riprodotto. La soluzione documentata è un header impostato autonomamente — il riferimento di nanobot descrive providers.<name>.extraHeaders come header aggiunti alle richieste del provider:

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

Indica lì il tuo client in modo veritiero. Inserire in quel campo uno dei nomi dei client verificati da OpenCode sarebbe impersonificazione, non identificazione, e non è ciò che richiede la documentazione.

La riga relativa all'endpoint ha una conseguenza specifica per nanobot che nessun header può correggere. Il riferimento al provider di v0.3.5 indica di usare gli ID dei modelli che OpenCode elenca sotto l'endpoint chat/completions, perché i modelli elencati solo sotto responses, messages o endpoint specifici del provider non sono gestiti da quel percorso compatibile con OpenAI. Nella configurazione, OpenCode Go è providers.opencodeGo con un preset il cui provider è opencode_go, e gli ID dei modelli hanno il prefisso opencode-go/ che nanobot rimuove prima dell'invio. Infine, la pagina Go di OpenCode pubblica un elenco di client verificati (Hermes, Claude Code, Codex, ZCode, Pi, jcode e Kilo Code CLI) e un elenco con supporto alla sessione mancante o incompleto (DeepSeek Harness, GitHub Copilot Chat, Kimi Code e MiMo Code). Al 21 settembre 2026 nanobot non figura in nessuno dei due elenchi — un'assenza di valutazione pubblicata, non un'approvazione né un blocco. Quella pagina segnala inoltre requisiti di versione per singolo client che qui non sono stati acquisiti, quindi non dedurre da questa pagina una versione minima per nessuno di quei client.

Verifica con una richiesta dai dati oscurati

La documentazione di nanobot v0.3.5 non descrive alcun modo per stampare gli header in uscita, quindi conferma direttamente il contratto sul tuo abbonamento prima di trarre conclusioni sul client. Leggi solo la riga di stato.

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

Questo separa nettamente due errori: un 400 che nomina MissingSessionID riguarda l'header, mentre qualsiasi altra cosa non riguarda l'header. Non ruotare un nuovo ID casuale per ogni richiesta per far sparire l'errore e non prendere in prestito il nome di un altro client. La documentazione richiede un ID stabile per conversazione proprio perché il routing e la cache dei prompt si basano su di esso; pertanto un ID per richiesta annulla la cache per cui stai pagando, pur sembrando una correzione. Le due risposte legittime sono eseguire l'upgrade oppure spostare quel carico di lavoro su un percorso che non preveda il requisito.

Quanto costa e quale percorso conviene

Tieni separato il software dai token. nanobot stesso costa $0 — ha licenza MIT ed è self-hosted, secondo il record del repository consultato il 21 settembre 2026 — quindi tutto ciò che segue riguarda il costo del modello e della macchina su cui viene eseguito.

La riga relativa a Zen proviene dalla sua documentazione, consultata il 21 settembre 2026; Zen e Go sono prodotti fatturati separatamente, quindi una tariffa Zen non è ciò che paga un abbonato Go, e l'elenco proprietario di Zen indica diversi modelli come temporaneamente gratuiti mentre i provider raccolgono feedback. OpenCode pricing copre il lato dei costi propri del client.

L'abbonamento non può essere convertito nella tabella seguente, e fingere il contrario è l'errore più facile da commettere qui. L'indennità di Go è denominata in dollari alle tariffe per modello proprie di Go, e ogni modello ha il proprio limite: l'esempio sviluppato nella documentazione è un modello da $60 al mese che consente $12 di utilizzo ogni 5 ore e $30 a settimana, mentre le righe dei modelli lette il 21 settembre 2026 mostrano GLM-5.3-Flash a $0,15 di input e $0,50 di output per 1M, con un limite mensile di $60 e una stima di 31.580 richieste al mese. Queste sono stime di OpenCode per il proprio catalogo, non garanzie, e una riga riportava una promozione datata che scade poco dopo la stesura del testo. Per un carico di lavoro compatibile con l'elenco dei modelli di Go e con le relative finestre, $10 acquistano molto utilizzo a consumo; il confronto riguarda davvero il fatto che i tuoi modelli e i tuoi picchi rientrino o meno in quei limiti.

Un gateway a consumo applica un prezzo diverso allo stesso carico di lavoro. Si tratta di calcoli illustrativi dei token, non di costi misurati delle attività né di un tetto alla fattura: supponiamo un assistente nanobot che consumi 3.000.000 di token di input non memorizzati nella cache e 300.000 token di output al mese, alle tariffe attive del catalogo Kunavo per milione di token.

Scala questi valori in base al tuo traffico prima di considerarli un budget e nota che una pianificazione in background può spostare la colonna dell'input molto più della scelta del modello — nanobot API cost and setup analizza la cadenza che nanobot abilita per impostazione predefinita. L'importo del catalogo Kunavo è un valore minimo di fatturazione, non un limite massimo: quando l'upstream comunica il proprio addebito, la fattura è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per il markup applicabile. I costi della cache, degli strumenti e dell'hosting sono esclusi da questo esempio, e la ricarica minima è di $10 in credito prepagato — un minimo di finanziamento, non un costo per attività né un abbonamento. Consulta i dettagli sulla fatturazione.

Dove Kunavo è utile e dove non lo è

Essere franchi su questo aspetto è più importante di una conversione. Kunavo non rivende OpenCode Go o Zen e indirizzare nanobot verso https://api.kunavo.com/v1 non risolve un abbonamento OpenCode Go. Evita invece il requisito, perché x-opencode-session appartiene agli host opencode.ai — e, secondo la regola del nome host nel codice sorgente della v0.3.5, nanobot non aggiungerà quell'header nemmeno a qualsiasi altro URL di base. Qui non è stato verificato cosa farebbe l'endpoint di Kunavo con un header di questo tipo, né nanobot è stato testato con Kunavo: non esiste una pagina di integrazione di nanobot e ogni affermazione sulla configurazione riportata sopra è una lettura della documentazione dei fornitori e del codice sorgente distribuito, non un risultato di compatibilità.

Considera quindi i percorsi come alternative con compromessi diversi, non come una soluzione e un workaround. Se per il carico di lavoro è adatto un percorso compatibile con OpenAI a consumo, la guida rapida illustra la convenzione dell'endpoint e creare un account Kunavo è il passaggio precedente al finanziamento di una chiave — mantieni disponibile un percorso funzionante mentre lo provi, esegui un'attività circoscritta, poi leggi ciò che il tuo account ha registrato per essa. Se sei arrivato cercando l'agente terminale Go archiviato anziché l'abbonamento, la documentazione dell'integrazione Crush illustra il suo successore e la documentazione dell'integrazione OpenCode illustra l'attuale client TypeScript. Per un confronto più ampio, consulta API compatibile con OpenAI e la directory delle API per agenti; per un errore OpenCode diverso, provider o modello non trovato è la guida diagnostica.

Domande frequenti

Verificato il 21 settembre 2026: la documentazione e il changelog di opencode.ai relativi a Go e Zen; l'API GitHub per le release, i tag, la PR #5662, la issue #5661 e una chiamata compare che dimostra che il commit è incluso nel tag v0.3.5; anomalyco/opencode#47438 e vastsa/PI-Desktop#48 per l'avviso citato e il 400 segnalato; e l'archivio tar del codice sorgente della v0.3.5 per ogni affermazione su ciò che invia nanobot. La data 09/06 risale a un post di @opencode su X del 3 settembre 2026, citato dalla issue e dalla PR di nanobot ma non recuperato da questa pagina; l'avviso citato per gli abbonati e il contratto dell'errore 400 sono segnalati dagli utenti e nessuno dei due compare nella documentazione o nel changelog di OpenCode. Nessuno ha eseguito qui nanobot con OpenCode Go o con Kunavo, né ha riprodotto il problema; le tariffe dei token Kunavo provengono dal catalogo attivo e ogni cifra in dollari è un calcolo illustrativo basato sulle ipotesi dichiarate.