nanobot OpenCode Go 缺少工作階段標頭：版本與路由檢查

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 顆星、未封存，且在本次檢查當日仍有最新推送（GitHub API，2026 年 9 月 21 日）——不是 obot-platform 上同名的 Go 專案。

錯誤，以及哪些 nanobot 版本會發生此錯誤

最初引發此事的通知是以供應商通知的形式傳達給訂閱者，而不是透過文件。使用者在 anomalyco/opencode#47438 中逐字引用了該通知；該議題於 2026 年 9 月 5 日針對 OpenCode 自己的用戶端建立，並描述這是模型供應商透過電子郵件寄來的通知：「您傳送至 OpenCode Go 的部分請求缺少 x-opencode-session 標頭。如果沒有這個標頭，我們就無法妥善最佳化服務。自 09/06 起，缺少此標頭的請求可能會發生錯誤。」我們能找到的 OpenCode 文件中都沒有出現這段措辭。 於 2026 年 9 月 21 日查閱的 OpenCode 變更記錄，在 v1.18.31 時涵蓋 2026 年 8 月 4 日至 9 月 14 日，完全沒有提及 x-opencode-session 的項目。Go 文件將其表述為請求，而不是拒絕：「請在每段對話的 x-opencode-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 或其子網域時也會如此。有對話內容時，標頭值是工作階段 ID 的 SHA-256 十六進位摘要，使其對非 ASCII ID 保持不透明且適合 ASCII 傳輸。沒有對話內容時，供應商執行個體會退回使用一個在其生命週期內固定的隨機 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 的原始碼可見，提供 opencode、opencode_zen 與 opencode_go 規格的 OpenAI 相容供應商模組完全沒有設定 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 每 1M 個詞元的輸入費率為 $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與AI 代理 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 在 X 上於 2026 年 9 月 3 日發布的貼文；nanobot 的 issue 和 PR 引用了該貼文，但本頁未取得。引用的訂閱者通知與 400 錯誤契約均由使用者回報，OpenCode 的文件或變更日誌中都沒有出現。本文團隊中無人曾讓 nanobot 連接 OpenCode Go 或 Kunavo，也無人重現該失敗情況；Kunavo 詞元費率來自即時目錄，而每個美元數字都是在所述假設下的說明性算術。