nanobot OpenCode Go thiếu session header: kiểm tra phiên bản và tuyến

nanobot bắt đầu gửi header x-opencode-session trong v0.3.5, phát hành ngày 15 tháng 9 năm 2026; các bản phát hành đến v0.3.0 chỉ gửi id x-session-affinity chung, đây là khoảng cách phiên bản đứng sau lỗi thiếu header phiên khi dùng OpenCode Go. Hãy chạy nanobot --version trước khi thay đổi bất kỳ điều gì khác: nếu lệnh báo v0.3.0 hoặc cũ hơn, nâng cấp là toàn bộ cách sửa cho riêng header đó. Điều mà bản nâng cấp không giải quyết là phần còn lại trong hợp đồng client của OpenCode Go, và đó là phần đáng đọc trước khi kết luận route đang hoạt động bình thường.

Trước hết cần làm rõ một điểm, vì các tên này dễ bị nhầm lẫn. OpenCode Go ở đây là gói đăng ký mô hình hiện đang được cung cấp với giá $10/tháng được mô tả tại opencode.ai/docs/go — không phải tác nhân terminal OpenCode bằng ngôn ngữ Go đã được lưu trữ, mà README riêng của nó nói rằng dự án tiếp tục dưới tên Crush cùng tác giả ban đầu và nhóm Charm. Đây không phải ghi chú di chuyển về một sản phẩm đã ngừng hoạt động; đây là trang khắc phục sự cố cho một dịch vụ đang được bán và đã siết chặt yêu cầu đối với client. Còn nanobot ở đây là HKUDS/nanobot, framework tác nhân cá nhân bằng Python được cấp phép MIT — 48.459 sao, chưa được lưu trữ, lần push cuối vào đúng ngày kiểm tra này (GitHub API, ngày 21 tháng 9 năm 2026) — không phải dự án Go cùng tên tại obot-platform.

Lỗi và các phiên bản nanobot gặp lỗi này

Thông báo khởi đầu cho sự việc này đã được gửi đến người đăng ký dưới dạng thông báo từ nhà cung cấp, không phải tài liệu. Một người dùng đã trích dẫn nguyên văn thông báo đó trong anomalyco/opencode#47438, được mở ngày 5 tháng 9 năm 2026 đối với chính ứng dụng khách của OpenCode và mô tả đây là thông báo từ nhà cung cấp mô hình được gửi qua email: "Một số yêu cầu của bạn đến OpenCode Go đang thiếu tiêu đề x-opencode-session. Nếu không có tiêu đề này, chúng tôi không thể tối ưu hóa dịch vụ đúng cách. Bắt đầu từ 09/06, các yêu cầu thiếu tiêu đề này có thể gặp lỗi." Chúng tôi không tìm thấy cách diễn đạt này trong bất kỳ tài liệu OpenCode nào. Nhật ký thay đổi của OpenCode, được đọc ngày 21 tháng 9 năm 2026, bao quát giai đoạn từ ngày 4 tháng 8 đến ngày 14 tháng 9 năm 2026 ở v1.18.31 và hoàn toàn không có mục nào đề cập đến x-opencode-session. Tài liệu Go diễn đạt đây là một yêu cầu, không phải sự từ chối: "Gửi một ID phiên ổn định trong x-opencode-session cho mỗi cuộc trò chuyện để chúng tôi có thể tối ưu hóa định tuyến và bộ nhớ đệm lời nhắc."

Bản thân ngày 09/06 có nguồn công khai chính thức, chỉ là không phải nguồn tài liệu: nanobot issue #5661 và PR #5662 đều dẫn đến một bài đăng của @opencode trên X ngày 3 tháng 9 năm 2026, được họ trích dẫn là nói rằng các công cụ thiếu tiêu đề sẽ mất khả năng tối ưu hóa bộ nhớ đệm lời nhắc và rằng "Bắt đầu từ 09/06, các yêu cầu thiếu tiêu đề này có thể gặp lỗi." Bài đăng đó là thông báo mà bản sửa lỗi của nanobot được viết dựa trên; trang này chưa tự truy xuất bài đăng đó.

Lỗi nghiêm trọng chỉ được bên thứ ba ghi nhận. vastsa/PI-Desktop#48, được mở và đóng ngày 7 tháng 9 năm 2026, ghi nhận HTTP 400 với "type": "MissingSessionID" cùng thông báo cho biết yêu cầu thiếu x-opencode-session và không thể được định tuyến hiệu quả, đồng thời trỏ đến anchor trong tài liệu Go. Tài liệu Go của OpenCode không có tham chiếu lỗi nào liệt kê mã trạng thái hoặc chuỗi kiểu đó, vì vậy hãy xem nghĩa vụ được tài liệu hóa và sự từ chối được báo cáo là hai mức độ khẳng định khác nhau từ cùng một nhà cung cấp.

Không có v0.3.1 đến v0.3.4 trong lịch sử tag, vì vậy "v0.3.0 và các phiên bản cũ hơn" là toàn bộ phạm vi bị ảnh hưởng. Hai kiểm tra đã xác nhận ánh xạ bản phát hành vào ngày 21 tháng 9 năm 2026 thay vì suy đoán: nội dung bản phát hành liệt kê PR #5662 theo số, và một lệnh gọi compare của GitHub cho biết v0.3.5 đi trước 20f115bf 84 commit và không tụt lại commit nào, xác nhận commit này nằm trong tag. Lưu ý rằng tài liệu nanobot v0.3.5 không bao giờ đề cập đến tiêu đề — các bản ghi duy nhất về thay đổi này là ghi chú phát hành, PR và issue.

Bản sửa lỗi thực sự làm gì và điều gì kích hoạt nó

Đọc tại tag v0.3.5 trong nanobot/providers/openai_compat_provider.py, logic này ngắn gọn nhưng đáng để nắm chính xác. nanobot xem một đích đến là đích OpenCode khi đặc tả nhà cung cấp có tên opencode, opencode_zen hoặc opencode_go, hoặc khi hostname của URL cơ sở là opencode.ai hoặc một tên miền con của nó. Khi có ngữ cảnh cuộc trò chuyện, giá trị tiêu đề là digest SHA-256 dạng hex của ID phiên, giúp giá trị này trở nên không thể đọc trực tiếp và an toàn với ASCII đối với các ID không phải ASCII. Khi không có ngữ cảnh cuộc trò chuyện, phiên bản nhà cung cấp sẽ dùng UUID ngẫu nhiên cố định trong suốt vòng đời của chính nó — ổn định cho phiên bản đó, không phải cho từng cuộc trò chuyện. Tiêu đề bạn tự cấu hình sẽ được ưu tiên hơn cả hai, với tên được so khớp không phân biệt chữ hoa chữ thường.

Mệnh đề về hostname là điều cần ghi nhớ: tiêu đề được đính kèm vì nơi yêu cầu được gửi đến, không phải vì bạn đã viết khối nhà cung cấp nào. Một khối providers.custom chung trỏ đến URL cơ sở opencode.ai vẫn sẽ nhận tiêu đề này. Yêu cầu đến bất kỳ máy chủ nào khác sẽ không nhận tiêu đề — máy chủ đó yêu cầu điều gì thay vào đó là vấn đề riêng của nhà cung cấp tương ứng, và nội dung này không trả lời vấn đề đó.

Việc nâng cấp rất thông thường: gói PyPI là nanobot-ai, ở phiên bản 0.3.5 trong pyproject.toml của tag đó, và README v0.3.5 ghi lại uv tool install nanobot-ai cùng python -m pip install nanobot-ai. Xác nhận bằng nanobot --version, hoặc python -m nanobot --version nếu điểm vào không nằm trên PATH, sau đó chạy nanobot status, lệnh mà tài liệu CLI mô tả là kiểm tra mức sẵn sàng của nhà cung cấp và mô hình mà không gọi mô hình.

Vì sao OpenCode Go không phải là một endpoint tương thích OpenAI thông thường

Đây là phần khiến một bản sửa tiêu đề có vẻ chưa đầy đủ. OpenCode Go nêu ra một số điều kiện phía ứng dụng khách mà một URL cơ sở tương thích OpenAI thông thường không có, và tiêu đề phiên chỉ là một trong số đó. Tất cả các hàng bên dưới đều lấy từ tài liệu của chính sản phẩm, được kiểm tra ngày 21 tháng 9 năm 2026.

Hàng user-agent cần được lưu ý. PR #5662 chỉ thay đổi tiêu đề phiên. Khi đọc mã nguồn nanobot v0.3.5, mô-đun nhà cung cấp tương thích OpenAI — mô-đun phục vụ các đặc tả opencode, opencode_zen và opencode_go — không thiết lập User-Agent ở bất kỳ đâu, trong khi các mô-đun nhà cung cấp GitHub Copilot, xAI Grok và OpenAI Codex đều thiết lập một user-agent mang thương hiệu nanobot. Vì vậy, trên đường đi đó, yêu cầu sẽ mang bất kỳ giá trị nào mà SDK bên dưới gửi theo mặc định. Tại đây không có yêu cầu nào được gửi qua mạng để quan sát giá trị, và OpenCode chưa công bố cơ chế thực thi nào cho dòng đó, vì vậy đây là kết luận từ việc đọc mã nguồn chứ không phải lỗi được tái hiện. Biện pháp được tài liệu hóa là một tiêu đề do bạn tự thiết lập — tài liệu tham chiếu của nanobot mô tả providers.<name>.extraHeaders là các tiêu đề được hợp nhất vào yêu cầu của nhà cung cấp:

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

Hãy trung thực khi đặt tên ứng dụng khách của bạn ở đó. Đưa một trong các tên ứng dụng khách đã được OpenCode xác thực vào trường đó sẽ là giả mạo danh tính, không phải nhận diện, và đó không phải điều tài liệu yêu cầu.

Hàng endpoint có một hệ quả riêng của nanobot mà không tiêu đề nào có thể khắc phục. Tài liệu tham chiếu nhà cung cấp v0.3.5 của nanobot cho biết hãy sử dụng các ID mô hình mà OpenCode liệt kê dưới endpoint chat/completions, vì các mô hình chỉ được liệt kê dưới responses, messages hoặc các endpoint dành riêng cho nhà cung cấp sẽ không được xử lý bởi đường dẫn tương thích OpenAI đó. Trong cấu hình, OpenCode Go là providers.opencodeGo với một preset có provider là opencode_go, và các ID mô hình mang tiền tố opencode-go/ mà nanobot sẽ loại bỏ trước khi gửi. Cuối cùng, trang Go của OpenCode công bố danh sách các ứng dụng khách đã được xác thực (Hermes, Claude Code, Codex, ZCode, Pi, jcode và Kilo Code CLI) cùng danh sách các ứng dụng khách thiếu hoặc hỗ trợ phiên chưa hoàn chỉnh (DeepSeek Harness, GitHub Copilot Chat, Kimi Code và MiMo Code). nanobot không nằm trong danh sách nào tính đến ngày 21 tháng 9 năm 2026 — đây là sự vắng mặt của kết luận được công bố, không phải sự chứng thực và cũng không phải lệnh chặn. Trang đó cũng lưu ý các yêu cầu phiên bản riêng cho từng ứng dụng khách nhưng nội dung này không ghi lại chúng, vì vậy đừng suy ra phiên bản tối thiểu cho bất kỳ ứng dụng khách nào từ trang này.

Xác minh bằng một yêu cầu đã ẩn dữ liệu

Tài liệu nanobot v0.3.5 không mô tả cách in các tiêu đề gửi đi, vì vậy hãy xác nhận trực tiếp hợp đồng với gói đăng ký của chính bạn trước khi kết luận bất kỳ điều gì về ứng dụng khách. Chỉ đọc dòng trạng thái.

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

Điều đó phân tách rõ hai lỗi: lỗi 400 có tên MissingSessionID là lỗi tiêu đề, còn mọi lỗi khác không phải lỗi tiêu đề. Đừng thay một ID ngẫu nhiên mới cho mỗi yêu cầu để làm lỗi biến mất, và đừng mượn tên của ứng dụng khách khác. Tài liệu yêu cầu một ID ổn định cho mỗi cuộc trò chuyện chính xác vì định tuyến và bộ nhớ đệm lời nhắc sử dụng ID đó làm khóa, vì vậy ID riêng cho từng yêu cầu sẽ vô hiệu hóa bộ nhớ đệm mà bạn đang trả tiền, dù trông có vẻ như một bản sửa. Hai câu trả lời hợp lệ là nâng cấp hoặc chuyển khối lượng công việc đó sang một route không có yêu cầu này.

Chi phí là bao nhiêu và route nào phù hợp hơn

Hãy tách phần mềm khỏi token. Bản thân nanobot là $0 — được cấp phép MIT và tự lưu trữ, theo bản ghi kho lưu trữ được đọc ngày 21 tháng 9 năm 2026 — vì vậy mọi nội dung bên dưới là hóa đơn mô hình và máy chạy nó.

Hàng Zen lấy từ tài liệu riêng của Zen, được đọc ngày 21 tháng 9 năm 2026; Zen và Go là các sản phẩm được tính phí riêng, vì vậy mức giá của Zen không phải là mức mà người đăng ký Go trả, và danh sách riêng của Zen đánh dấu một số mô hình là tạm thời miễn phí trong khi các nhà cung cấp thu thập phản hồi. Giá OpenCode bao quát phần chi phí riêng của ứng dụng khách.

Gói đăng ký không thể được quy đổi thành bảng bên dưới, và giả vờ rằng có thể là sai lầm dễ mắc nhất ở đây. Hạn mức của Go được tính bằng đô la theo đơn giá riêng của Go cho từng mô hình, và mỗi mô hình có hạn mức riêng: ví dụ minh họa trong tài liệu là một mô hình $60 mỗi tháng cho phép sử dụng $12 mỗi 5 giờ và $30 mỗi tuần, trong khi các hàng mô hình được đọc ngày 21 tháng 9 năm 2026 cho thấy GLM-5.3-Flash có giá $0,15 cho đầu vào và $0,50 cho đầu ra trên mỗi 1M token, với giới hạn hàng tháng $60 và ước tính 31.580 yêu cầu mỗi tháng. Đó là các ước tính của OpenCode cho danh mục riêng của họ, không phải bảo đảm, và một hàng có chương trình khuyến mãi với ngày hết hạn cụ thể, không lâu sau thời điểm nội dung này được viết. Đối với khối lượng công việc phù hợp với danh sách mô hình và các khoảng thời gian của Go, $10 mua được khá nhiều mức sử dụng tính theo đơn vị; so sánh thực sự là liệu mô hình và các đợt tăng tải của bạn có nằm trong các giới hạn đó hay không.

Một gateway tính phí theo mức sử dụng sẽ định giá cùng khối lượng công việc theo cách khác. Đây là phép tính token mang tính minh họa, không phải chi phí tác vụ đo được và không phải trần hóa đơn: giả sử một trợ lý nanobot sử dụng 3.000.000 token đầu vào không được bộ nhớ đệm và 300.000 token đầu ra mỗi tháng, theo mức giá hiện hành trong danh mục Kunavo trên mỗi triệu token.

Hãy điều chỉnh các con số đó theo lưu lượng của riêng bạn trước khi xem chúng là ngân sách, đồng thời lưu ý rằng một lịch chạy nền có thể làm cột đầu vào thay đổi nhiều hơn lựa chọn mô hình — chi phí và thiết lập API nanobot hoạt động thông qua tần suất mà nanobot mặc định kích hoạt. Số tiền trong danh mục của Kunavo là mức sàn thanh toán chứ không phải giới hạn: khi upstream báo chi phí, hóa đơn sẽ là mức lớn hơn giữa chi phí trong danh mục và chi phí upstream nhân với mức markup áp dụng. Phí bộ nhớ đệm, công cụ và lưu trữ nằm ngoài ví dụ này, còn khoản nạp tối thiểu là $10 tín dụng trả trước — đây là mức tối thiểu để nạp tiền, không phải phí cho mỗi tác vụ hay gói đăng ký. Xem chi tiết thanh toán.

Kunavo giúp và không giúp ở đâu

Nói thẳng về điều này quan trọng hơn việc chuyển đổi. Kunavo không bán lại OpenCode Go hoặc Zen, và trỏ nanobot đến https://api.kunavo.com/v1 không sửa được gói đăng ký OpenCode Go. Thay vào đó, nó tránh yêu cầu này, vì x-opencode-session thuộc về các máy chủ opencode.ai — và theo quy tắc hostname trong mã nguồn v0.3.5, nanobot cũng sẽ không thêm tiêu đề đó tại bất kỳ URL cơ sở nào khác. Việc endpoint của Kunavo sẽ xử lý một tiêu đề như vậy ra sao chưa được kiểm tra ở đây, và nanobot cũng chưa được kiểm thử với Kunavo: không có trang tích hợp nanobot, và mọi phát biểu cấu hình ở trên đều là kết quả đọc tài liệu của nhà cung cấp và mã nguồn đã phát hành chứ không phải kết quả tương thích.

Vì vậy, hãy xem các route là những lựa chọn thay thế với các đánh đổi khác nhau, không phải một bản sửa và một giải pháp tạm thời. Nếu một route tương thích OpenAI tính phí theo mức sử dụng phù hợp với khối lượng công việc, hướng dẫn bắt đầu nhanh bao quát quy ước endpoint và tạo tài khoản Kunavo là bước trước khi nạp tiền cho khóa — hãy giữ một route đang hoạt động trong khi thử, chạy một tác vụ có giới hạn, rồi đọc thông tin mà tài khoản của bạn đã ghi nhận cho tác vụ đó. Nếu bạn đến đây để tìm tác nhân terminal Go đã lưu trữ thay vì gói đăng ký, tài liệu tích hợp Crush trình bày sản phẩm kế nhiệm, còn tài liệu tích hợp OpenCode trình bày ứng dụng khách TypeScript hiện tại. Để so sánh rộng hơn, xem API tương thích OpenAI và thư mục API tác nhân; đối với một lỗi OpenCode khác, không tìm thấy nhà cung cấp hoặc mô hình là tài liệu chẩn đoán.

Câu hỏi thường gặp

Đã kiểm tra ngày 21 tháng 9 năm 2026: tài liệu Go và Zen cùng nhật ký thay đổi của opencode.ai; API GitHub đối với các bản phát hành, tag, PR #5662, issue #5661 của HKUDS/nanobot và một lệnh gọi compare chứng minh commit nằm trong tag v0.3.5; anomalyco/opencode#47438 và vastsa/PI-Desktop#48 về thông báo được trích dẫn và lỗi 400 được báo cáo; cùng tarball mã nguồn v0.3.5 cho mọi khẳng định về nội dung nanobot gửi đi. Ngày 09/06 bắt nguồn từ một bài đăng của @opencode trên X ngày 3 tháng 9 năm 2026 mà issue và PR của nanobot trích dẫn nhưng trang này chưa truy xuất; thông báo người đăng ký được trích dẫn và hợp đồng lỗi 400 do người dùng báo cáo, và cả hai đều không xuất hiện trong tài liệu hoặc nhật ký thay đổi của OpenCode. Không ai ở đây đã chạy nanobot với OpenCode Go hoặc Kunavo, hay tái hiện lỗi; đơn giá token của Kunavo lấy từ danh mục trực tiếp và mọi con số đô la đều là phép tính minh họa theo các giả định đã nêu.