nanobot OpenCode Go 缺少 session header：版本与路由检查

nanobot 在 v0.3.5 中开始发送 x-opencode-session 标头，该版本于 2026 年 9 月 15 日发布；截至 v0.3.0 的发布版本只发送通用的 x-session-affinity id，这就是针对 OpenCode Go 发生缺少会话标头故障的版本差距。 在进行其他更改前运行 nanobot --version：如果它报告 v0.3.0 或更早版本，那么升级就是解决该标头问题的全部修复。升级没有解决的是 OpenCode Go 客户端契约的其余部分；在你断定该路由运行正常前，值得阅读的正是这一部分。

先澄清一下，以免名称冲突造成混淆。这里的 OpenCode Go 是目前在售的 $10/月模型订阅服务，文档位于 opencode.ai/docs/go——不是已归档的 Go 语言 OpenCode 终端代理；后者自己的 README 说明，项目由原作者和 Charm 团队以 Crush 的名称继续开发。这不是关于已退役产品的迁移说明，而是关于一项目前在售、收紧了客户端要求的服务的故障排查页面。这里的 nanobot 是 HKUDS/nanobot，采用 MIT 许可证的 Python 个人代理框架——48,459 个 star，未归档，最近一次推送发生在本次检查当天（GitHub API，2026 年 9 月 21 日）——不是 obot-platform 上同名的 Go 项目。

错误，以及哪些 nanobot 版本会出现该错误

最初的通知是以提供商通知的形式发送给订阅者的，而不是文档。用户在 anomalyco/opencode#47438 中逐字引用了该通知；该 issue 于 2026 年 9 月 5 日创建，针对 OpenCode 自己的客户端，并将其描述为模型提供商通过电子邮件发送的通知："你的部分 OpenCode Go 请求缺少 x-opencode-session 标头。如果没有该标头，我们无法正确优化服务。从 09/06 开始，缺少该标头的请求可能会报错。" 我们找到的 OpenCode 文档中没有出现这段措辞。 OpenCode 的变更日志于 2026 年 9 月 21 日读取，涵盖 2026 年 8 月 4 日至 9 月 14 日的 v1.18.31 内容，完全没有提到 x-opencode-session 的条目。Go 文档将其表述为请求，而不是拒绝："请为每个会话在 x-opencode-session 中发送稳定的 session ID，以便我们优化路由和提示缓存。"

09/06 这一日期本身确实有官方公开来源，只是不是文档来源：nanobot 的issue #5661和PR #5662都引用了 @opencode 于 2026 年 9 月 3 日在 X 上发布的帖子，并引用其内容称，缺少该标头的工具会失去提示缓存优化，且"从 09/06 开始，缺少该标头的请求可能会报错"。该帖子是 nanobot 修复所依据的公告；本页面没有独立获取该帖子。

硬性失败仅有第三方证据。vastsa/PI-Desktop#48于 2026 年 9 月 7 日创建并关闭，记录了 HTTP 400、"type": "MissingSessionID"，以及一条说明请求缺少 x-opencode-session 且无法高效路由的消息，并指向 Go 文档锚点。OpenCode 的 Go 文档没有列出包含该状态码或类型字符串的错误参考，因此应将已记录的义务与报告的拒绝视为来自同一供应商、但证据强度不同的两种说法。

标签历史中不存在 v0.3.1 至 v0.3.4，因此“v0.3.0 及更早版本”就是完整的受影响范围。2026 年 9 月 21 日，两个检查确认了发布版本映射，而不是进行推断：发布说明正文按编号列出了 PR #5662，GitHub 比较调用报告 v0.3.5 比 20f115bf 领先 84 个提交、落后 0 个提交，因此该提交位于该标签之内。请注意，nanobot 的 v0.3.5 文档从未提到该标头——该变更的唯一记录是发行说明、PR 和 issue。

修复实际做了什么，以及什么会触发它

在 nanobot/providers/openai_compat_provider.py 的 v0.3.5 标签中读取时，其逻辑很小，但值得准确了解。当提供商规范名为 opencode、opencode_zen 或 opencode_go 时，nanobot 将目标视为 OpenCode 目标；或者当基础 URL 的主机名为 opencode.ai 或其子域名时也如此。当存在会话上下文时，标头值是 session id 的 SHA-256 十六进制摘要，这使其对非 ASCII id 保持不透明且安全。不存在会话上下文时，提供商实例会退回到一个在其自身生命周期内固定的随机 UUID——对该实例稳定，但不是每个会话稳定。你自行配置的标头优先于上述两种情况，名称匹配不区分大小写。

需要记住的就是主机名条件：标头是否附加取决于请求发往哪里，而不是取决于你写了哪个提供商块。 指向 opencode.ai 基础 URL 的通用 providers.custom 块仍会获得该标头。发往任何其他主机的请求都不会获得该标头——该主机要求什么是其供应商自己的问题，本文不作回答。

升级过程很普通：PyPI 包是 nanobot-ai，该标签的 pyproject.toml 中版本为 0.3.5，而 v0.3.5 README 记录了 uv tool install nanobot-ai 和 python -m pip install nanobot-ai。使用 nanobot --version 确认；如果入口点不在 PATH 上，则使用 python -m nanobot --version；然后运行 nanobot status，CLI 参考将其描述为检查提供商和模型是否就绪，而不调用模型。

为什么 OpenCode Go 不是普通的兼容 OpenAI 端点

这正是标头修复看起来不完整的原因。OpenCode Go 规定了普通兼容 OpenAI 基础 URL 没有的多项客户端条件，会话标头只是其中一项。以下所有行都来自其自身的文档，并于 2026 年 9 月 21 日核查。

user-agent 这一行需要特别谨慎。 PR #5662 只更改了会话标头。阅读 nanobot v0.3.5 的源代码可见，兼容 OpenAI 的提供商模块——也就是服务于 opencode、opencode_zen 和 opencode_go 规范的模块——在任何地方都没有设置 User-Agent，而 GitHub Copilot、xAI Grok 和 OpenAI Codex 提供商模块各自设置了带 nanobot 品牌的值。因此在该路径上，请求会携带底层 SDK 默认发送的任何值。这里没有实际发送请求来观察该值，且 OpenCode 没有发布针对该项的强制执行规则，因此这是对源代码的解读，而不是重现出的失败。文档记录的补救方式是由你自行设置标头——nanobot 的参考文档将 providers.<name>.extraHeaders 描述为会合并到提供商请求中的标头：

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

在那里如实填写你自己的客户端名称。在该字段中填写 OpenCode 已验证客户端的名称会构成冒充，而不是身份标识，也不是文档所要求的做法。

端点这一行带来了任何标头都无法解决的 nanobot 特定后果。其 v0.3.5 提供商参考文档要求使用 OpenCode 在 chat/completions 端点下列出的模型 ID，因为仅列在 responses、messages 或提供商专用端点下的模型无法由该兼容 OpenAI 路径处理。在配置中，OpenCode Go 是 providers.opencodeGo，其预设的 provider 为 opencode_go，模型 id 带有 opencode-go/ 前缀，nanobot 会在发送前将其去除。最后，OpenCode 的 Go 页面发布了已验证客户端列表（Hermes、Claude Code、Codex、ZCode、Pi、jcode 和 Kilo Code CLI）以及会话支持缺失或不完整的列表（DeepSeek Harness、GitHub Copilot Chat、Kimi Code 和 MiMo Code）。截至 2026 年 9 月 21 日，nanobot 不在任何一份名单中——这表示没有公开发布的结论，不是认可，也不是禁止。该页面还指出每个客户端有版本要求，但本文未记录这些要求，因此不要从本页面推断上述任何客户端的最低版本。

使用一次经过脱敏的请求进行验证

nanobot 的 v0.3.5 文档没有说明如何打印其发出的标头，因此在对客户端下任何结论前，请直接针对你自己的订阅确认该契约。只读取状态行。

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

这清晰地区分了两种失败：400 错误中命名 MissingSessionID 的是标头，其他任何内容都不是标头。不要为每个请求轮换一个全新的随机 ID 来让错误消失，也不要借用其他客户端的名称。文档之所以要求每个会话使用稳定 ID，正是因为路由和提示缓存都以它为键；因此，每请求一个 ID 会抵消你付费获得的缓存收益，却看起来像是修复。两种合理的做法是升级，或将该工作负载迁移到不携带此要求的路由。

这需要多少费用，以及哪条路由更胜一筹

将软件成本与令牌成本分开。根据 2026 年 9 月 21 日读取的仓库记录，nanobot 本身为 $0——采用 MIT 许可证并自行托管；因此，下面的所有内容都是模型账单及其运行所需机器的成本。

Zen 这一行来自其自己的文档，读取于 2026 年 9 月 21 日；Zen 和 Go 是分别计费的产品，因此 Zen 的费率并不是 Go 订阅者支付的费用，而 Zen 自己的列表将若干模型标记为临时免费，以便供应商收集反馈。OpenCode 定价涵盖客户端自身的成本侧。

订阅费用无法转换为下表，假装可以是这里最容易犯的错误。Go 的额度以按 Go 自身模型费率计算的美元计价，每个模型都有自己的上限：文档中的示例是一个每月 $60 的模型，每 5 小时允许使用 $12，每周允许使用 $30；而 2026 年 9 月 21 日读取的模型行显示，GLM-5.3-Flash 的输入价格为每 100 万个令牌 $0.15，输出价格为 $0.50，每月上限为 $60，预计每月可处理 31,580 个请求。这些是 OpenCode 对其自身目录的估算，并非保证值，其中一行还带有一项在本文撰写后不久到期的限时促销。对于符合 Go 模型列表及其时间窗口的工作负载，$10 可以购买大量按量计费的使用量；真正的比较在于你的模型和突发流量是否能纳入其中。

按量计费的网关会以不同方式为同一工作负载定价。以下是用于说明的令牌算术，不是实测任务成本，也不是账单上限：假设一个 nanobot 助手每月消耗3,000,000 个未缓存输入令牌和 300,000 个输出令牌，并使用实时的每百万令牌 Kunavo 目录费率。

在将这些数字视为预算之前，请根据你自己的流量进行缩放，并注意后台计划可能比模型选择更大幅度地改变输入列——nanobot API 成本与设置通过 nanobot 默认启用的运行节奏发挥作用。Kunavo 的目录金额是计费下限而非上限：上游报告费用时，账单取目录成本与上游成本乘以适用加价两者中的较高者。缓存费用、工具和托管不包含在此示例中，最低充值额为预付额度 $10——这是资金充值下限，不是任务费用或订阅费用。请参阅计费详情。

Kunavo 能帮什么，以及不能帮什么

坦率说明这一点比进行转换更重要。Kunavo 不转售 OpenCode Go 或 Zen，将 nanobot 指向 https://api.kunavo.com/v1 也不会修复 OpenCode Go 订阅。相反，它避开了这一要求，因为 x-opencode-session 属于 opencode.ai 主机；而根据 v0.3.5 源码中的主机名规则，nanobot 也不会在任何其他基础 URL 上添加该标头。本文未测试 Kunavo 端点会如何处理此类标头，也未测试 nanobot 是否适用于 Kunavo：没有 nanobot 集成页面，上述每项配置说明都来自对供应商文档和已发布源代码的解读，而非兼容性测试结果。

因此，应将这些路由视为具有不同权衡的替代方案，而不是修复方案和临时方案。如果按量计费的 OpenAI 兼容路由适合该工作负载，快速入门涵盖端点约定，而创建 Kunavo 账户是为密钥充值前的步骤——尝试时保留一条可用路由，运行一个有界任务，然后查看账户记录的结果。如果你来这里寻找的是已归档的 Go 终端代理，而不是订阅，Crush 集成文档介绍了它的后继者，OpenCode 集成文档介绍了当前的 TypeScript 客户端。如需更广泛的比较，请参阅 OpenAI 兼容 API和代理 API 目录；如遇另一种 OpenCode 故障，未找到供应商或模型提供诊断信息。

常见问题

核查于 2026 年 9 月 21 日：opencode.ai 的 Go 和 Zen 文档及其变更日志；GitHub API 中 HKUDS/nanobot 的发布版本、标签、PR #5662、issue #5661，以及证明该提交位于 v0.3.5 标签内的 compare 调用；anomalyco/opencode#47438 和 vastsa/PI-Desktop#48，用于所引用的通知和报告的 400 错误；以及 v0.3.5 源代码压缩包，用于 nanobot 发送内容的全部相关声明。09/06 日期追溯至 @opencode 于 2026 年 9 月 3 日在 X 上发布的帖子，nanobot 的 issue 和 PR 引用了该帖子，但本页面未获取到；所引用的订阅者通知和 400 错误契约来自用户报告，OpenCode 的文档或变更日志中均未出现。本文没有人运行 nanobot 连接 OpenCode Go 或 Kunavo，也没有复现该故障；Kunavo 的令牌费率来自实时目录，每个美元数字都是在所述假设下进行的说明性算术。