Cabeçalho de sessão ausente no nanobot OpenCode Go: verificações de versão e rota

nanobot começou a enviar o cabeçalho x-opencode-session na v0.3.5, publicada em 15 de setembro de 2026; as versões até a v0.3.0 enviavam apenas um id genérico de x-session-affinity, que é a diferença de versão por trás da falha de cabeçalho de sessão ausente contra o OpenCode Go. Execute nanobot --version antes de mudar qualquer outra coisa: se ele informar v0.3.0 ou anterior, a atualização é toda a correção para esse cabeçalho específico. O que a atualização não resolve é o restante do contrato de cliente do OpenCode Go, e essa é a parte que vale a pena ler antes de concluir que a rota está saudável.

Uma desambiguação primeiro, porque os nomes se confundem. OpenCode Go aqui é a assinatura de modelos ativa de US$ 10/mês documentada em opencode.ai/docs/go — não o agente de terminal OpenCode arquivado, escrito em Go, cujo próprio README diz que o projeto continuou sob o nome Crush com o autor original e a equipe Charm. Esta não é uma nota de migração sobre um produto descontinuado; é uma página de solução de problemas sobre um serviço vendido atualmente que tornou mais rígido um requisito do cliente. E nanobot aqui é o HKUDS/nanobot, framework de agente pessoal em Python sob a licença MIT — 48.459 estrelas, não arquivado, com o último push no dia desta verificação (API do GitHub, 21 de setembro de 2026) — não o projeto em Go de mesmo nome em obot-platform.

O erro e quais versões do nanobot o apresentam

O aviso que deu início a isso chegou aos assinantes como uma notificação do provedor, não como documentação. Um usuário o citou literalmente em anomalyco/opencode#47438, aberto em 5 de setembro de 2026 contra o próprio cliente do OpenCode e descrito como uma notificação do provedor de modelos recebida por 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." Não encontramos essa redação em nenhuma documentação do OpenCode. O changelog do OpenCode, consultado em 21 de setembro de 2026, cobre de 4 de agosto a 14 de setembro de 2026 na v1.18.31 e não contém nenhuma entrada mencionando x-opencode-session. A documentação Go formula isso como uma solicitação, não uma rejeição: “Enviar um ID de sessão estável em x-opencode-session para cada conversa para podermos otimizar o roteamento e o cache de prompts.”

A data 09/06 tem, de fato, uma fonte pública oficial, apenas não uma fonte de documentação: o issue #5661 e a PR #5662 do nanobot citam uma publicação de @opencode no X, datada de 3 de setembro de 2026, que eles reproduzem como dizendo que as ferramentas sem o cabeçalho perdem a otimização do cache de prompts e que "Starting 09/06 requests missing this header may error." Essa publicação é o anúncio contra o qual a correção do nanobot foi escrita; esta página não a recuperou de forma independente.

A falha grave só é evidenciada por terceiros. vastsa/PI-Desktop#48, aberto e encerrado em 7 de setembro de 2026, registra HTTP 400 com "type": "MissingSessionID" e uma mensagem dizendo que falta x-opencode-session na solicitação e que ela não pode ser encaminhada com eficiência, apontando para a âncora da documentação Go. A documentação Go do OpenCode não contém nenhuma referência de erro que liste esse código de status ou essa string de tipo; portanto, leia a obrigação documentada e a rejeição relatada como duas afirmações de forças diferentes do mesmo fornecedor.

Não existe v0.3.1 a v0.3.4 no histórico de tags, portanto "v0.3.0 e anteriores" é todo o intervalo afetado. Duas verificações confirmaram o mapeamento da versão em 21 de setembro de 2026, em vez de inferi-lo: o corpo da versão lista a PR #5662 pelo número, e uma chamada de comparação do GitHub informa que a v0.3.5 está 84 commits à frente de 20f115bf e zero atrás dele, o que coloca o commit dentro da tag. Observe que a documentação do nanobot v0.3.5 não menciona o cabeçalho — os únicos registros da alteração são as notas de lançamento, a PR e o issue.

O que a correção realmente faz e o que a aciona

Lida na tag v0.3.5 em nanobot/providers/openai_compat_provider.py, a lógica é pequena e vale a pena conhecê-la com precisão. O nanobot trata um destino como destino OpenCode quando a especificação do provedor se chama opencode, opencode_zen ou opencode_go, ou quando o hostname da URL base é opencode.ai ou um subdomínio dele. Quando há contexto de conversa, o valor do cabeçalho é o digest hexadecimal SHA-256 do ID da sessão, mantendo-o opaco e seguro em ASCII para ids não ASCII. Quando não há contexto de conversa, a instância do provedor usa como fallback um UUID aleatório fixado durante sua própria vida útil — estável para essa instância, não por conversa. Um cabeçalho configurado por você tem precedência sobre ambos, com correspondência sem distinção entre maiúsculas e minúsculas no nome.

A cláusula do hostname é a frase que você deve guardar: o cabeçalho é anexado por causa do destino da solicitação, não por causa do bloco de provedor que você escreveu. Um bloco genérico providers.custom apontado para uma URL base opencode.ai ainda o recebe. Uma solicitação para qualquer outro host não o recebe — o que esse host exigir será uma questão do próprio fornecedor, e nada aqui a responde.

A atualização é comum: o pacote PyPI é nanobot-ai, está na versão 0.3.5 no pyproject.toml dessa tag, e o README da v0.3.5 documenta uv tool install nanobot-ai e python -m pip install nanobot-ai. Confirme com nanobot --version, ou com python -m nanobot --version se o ponto de entrada não estiver em PATH, e então execute nanobot status, que a referência da CLI descreve como uma verificação da prontidão do provedor e do modelo sem chamar um modelo.

Por que o OpenCode Go não é um endpoint simples compatível com OpenAI

Esta é a parte que faz uma correção de cabeçalho parecer incompleta. O OpenCode Go estabelece várias condições do lado do cliente que uma URL base comum compatível com OpenAI não estabelece, e o cabeçalho de sessão é apenas uma delas. Todas as linhas abaixo vêm da própria documentação, verificada em 21 de setembro de 2026.

A linha sobre o user agent merece cautela. A PR #5662 alterou apenas o cabeçalho de sessão. Ao ler o código-fonte do nanobot v0.3.5, o módulo de provedor compatível com OpenAI — aquele que atende às especificações opencode, opencode_zen e opencode_go — não define User-Agent em nenhum lugar, enquanto os módulos de provedor GitHub Copilot, xAI Grok e OpenAI Codex definem cada um um user agent com a marca nanobot. Portanto, nessa rota, a solicitação transporta o que o SDK subjacente enviar por padrão. Nenhuma solicitação foi enviada aqui para observar o valor, e o OpenCode não publicou nenhuma aplicação dessa regra, portanto esta é uma leitura do código-fonte, não uma falha reproduzida. A solução documentada é um cabeçalho definido por você — a referência do nanobot descreve providers.<name>.extraHeaders como cabeçalhos mesclados às solicitações do provedor:

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

Dê um nome verdadeiro ao seu próprio cliente nesse campo. Colocar ali um dos nomes de clientes validados pelo OpenCode seria uma personificação, não uma identificação, e não é isso que a documentação solicita.

A linha do endpoint tem uma consequência específica do nanobot que nenhum cabeçalho resolve. A referência de provedor da v0.3.5 orienta usar ids de modelo que o OpenCode lista no endpoint chat/completions, porque os modelos listados apenas em responses, messages ou endpoints específicos do provedor não são tratados por essa rota compatível com OpenAI. Na configuração, o OpenCode Go é providers.opencodeGo com uma predefinição cujo provider é opencode_go, e os ids dos modelos carregam um prefixo opencode-go/ que o nanobot remove antes de enviar. Por fim, a página Go do OpenCode publica uma lista de clientes validados (Hermes, Claude Code, Codex, ZCode, Pi, jcode e Kilo Code CLI) e uma lista com suporte de sessão ausente ou incompleto (DeepSeek Harness, GitHub Copilot Chat, Kimi Code e MiMo Code). nanobot não está em nenhuma das listas em 21 de setembro de 2026 — uma ausência de veredito publicado, não um endosso nem um bloqueio. Essa página também observa requisitos de versão por cliente que não foram capturados aqui; portanto, não deduza desta página uma versão mínima para nenhum desses clientes.

Verifique com uma solicitação com dados redigidos

A documentação do nanobot v0.3.5 não descreve nenhuma forma de imprimir seus cabeçalhos de saída, portanto confirme o contrato diretamente contra sua própria assinatura antes de concluir qualquer coisa sobre o cliente. Leia apenas a linha de status.

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

Isso separa claramente duas falhas: um 400 que nomeia MissingSessionID é o cabeçalho, e qualquer outra coisa não é o cabeçalho. Não gere um novo id aleatório por solicitação para fazer o erro desaparecer, nem use o nome de outro cliente. A documentação pede um id estável por conversa precisamente porque o roteamento e o cache de prompts usam esse id como chave; portanto, um id por solicitação elimina o cache pelo qual você está pagando, embora pareça uma correção. As duas respostas legítimas são fazer upgrade ou mover essa carga de trabalho para uma rota que não tenha esse requisito.

Quanto custa e qual rota vence

Mantenha o software separado dos tokens. O próprio nanobot custa $0 — é licenciado pelo MIT e auto-hospedado, conforme o registro do repositório consultado em 21 de setembro de 2026 — portanto, tudo abaixo é a cobrança do modelo e da máquina em que ele é executado.

A linha do Zen vem da documentação própria, consultada em 21 de setembro de 2026; Zen e Go são produtos cobrados separadamente, portanto uma tarifa do Zen não é o que um assinante do Go paga, e a própria lista do Zen marca vários modelos como temporariamente gratuitos enquanto os provedores coletam feedback. Os preços do OpenCode cobrem o próprio custo do cliente.

A assinatura não pode ser convertida na tabela abaixo, e fingir o contrário é o erro mais fácil de cometer aqui. A franquia do Go é denominada em dólares às próprias tarifas por modelo do Go, e cada modelo tem seu próprio limite: o exemplo trabalhado na documentação é um modelo de US$ 60 mensais que permite US$ 12 de uso a cada 5 horas e US$ 30 por semana, enquanto as linhas de modelos lidas em 21 de setembro de 2026 mostram o GLM-5.3-Flash a US$ 0,15 de entrada e US$ 0,50 de saída por 1 milhão, com limite mensal de US$ 60 e estimativa de 31.580 solicitações por mês. Essas são estimativas do OpenCode para seu próprio catálogo, não garantias, e uma linha tinha uma promoção datada que expira pouco depois da redação deste texto. Para uma carga de trabalho que se encaixe na lista de modelos e nas janelas do Go, US$ 10 compra muito uso medido; a comparação é realmente sobre se seus modelos e seus picos de uso cabem nele.

Um gateway com cobrança por uso precifica a mesma carga de trabalho de outra forma. Estes são cálculos ilustrativos de tokens, não custos medidos de tarefas nem um teto de cobrança: suponha um assistente do nanobot consumindo 3,000,000 tokens de entrada não armazenados em cache e 300,000 tokens de saída em um mês, às tarifas atuais do catálogo da Kunavo por milhão de tokens.

Escale esses valores de acordo com seu próprio tráfego antes de tratá-los como orçamento e observe que uma programação em segundo plano pode aumentar a coluna de entrada muito mais do que a escolha do modelo — custo e configuração da API do nanobot funciona com a cadência que o nanobot habilita por padrão. 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. Cobranças de cache, ferramentas e hospedagem ficam fora deste exemplo, e o carregamento mínimo é $10 em crédito pré-pago — um mínimo de financiamento, não uma tarifa de tarefa nem uma assinatura. Consulte os detalhes de cobrança.

Onde a Kunavo ajuda e onde não ajuda

Ser direto sobre isso importa mais do que uma conversão. A Kunavo não revende o OpenCode Go nem o Zen, e apontar o nanobot para https://api.kunavo.com/v1 não corrige uma assinatura do OpenCode Go. Em vez disso, evita o requisito, porque x-opencode-session pertence a hosts opencode.ai — e, pela regra do hostname no código-fonte da v0.3.5, o nanobot também não adicionará esse cabeçalho em nenhuma outra URL base. O que o endpoint da Kunavo faria com esse cabeçalho não foi testado aqui, nem o nanobot com a Kunavo: não há página de integração do nanobot, e toda afirmação de configuração acima é uma leitura da documentação do fornecedor e do código-fonte distribuído, não um resultado de compatibilidade.

Portanto, trate as rotas como alternativas com diferentes compromissos, não como uma correção e uma solução alternativa. Se uma rota compatível com OpenAI e com cobrança por uso for adequada à carga de trabalho, o início rápido explica a convenção do endpoint, e criar uma conta na Kunavo é a etapa anterior ao financiamento de uma chave — mantenha uma rota funcional disponível enquanto testa, execute uma tarefa delimitada e depois leia o que sua conta registrou para ela. Se você chegou procurando o agente de terminal Go arquivado, e não a assinatura, o documento de integração do Crush aborda seu sucessor, e o documento de integração do OpenCode aborda o cliente TypeScript atual. Para uma comparação mais ampla, consulte API compatível com OpenAI e o diretório de APIs de agentes; para uma falha diferente do OpenCode, provedor ou modelo não encontrado é o diagnóstico.

Perguntas frequentes

Verificado em 21 de setembro de 2026: a documentação do Go e do Zen do opencode.ai e seu changelog; a API do GitHub para lançamentos, tags, PR #5662, issue #5661 e uma chamada de comparação que comprova que o commit está dentro da tag v0.3.5; anomalyco/opencode#47438 e vastsa/PI-Desktop#48 para o aviso citado e o 400 relatado; e o tarball do código-fonte da v0.3.5 para cada afirmação sobre o que o nanobot envia. A data 09/06 remonta a uma publicação de @opencode no X em 3 de setembro de 2026, citada pela issue e pelo PR do nanobot, mas que esta página não recuperou; o aviso citado aos assinantes e o contrato do erro 400 foram relatados por usuários, e nenhum dos dois aparece na documentação ou no changelog do OpenCode. Ninguém aqui executou o nanobot contra o OpenCode Go ou contra a Kunavo, nem reproduziu a falha; as tarifas de tokens da Kunavo vêm do catálogo atual e todos os valores em dólares são cálculos ilustrativos segundo as premissas declaradas.