nanobot OpenCode Go 세션 헤더 누락: 버전 및 경로 확인

nanobot은 2026년 9월 15일에 출시된 v0.3.5부터 x-opencode-session 헤더를 전송하기 시작했습니다. v0.3.0까지의 릴리스는 일반적인 x-session-affinity ID만 전송했으며, 이러한 버전 차이가 OpenCode Go를 사용할 때 세션 헤더 누락으로 인한 오류가 발생하는 원인입니다. 다른 사항을 변경하기 전에 nanobot --version를 실행하세요. v0.3.0 이하로 표시된다면, 해당 헤더 문제는 업그레이드만으로 완전히 해결됩니다. 하지만 업그레이드로 해결되지 않는 것은 OpenCode Go의 나머지 클라이언트 계약 요건이며, 해당 경로가 정상적으로 작동한다고 결론 내리기 전에 이 부분을 읽어볼 필요가 있습니다.

먼저 이름이 겹치므로 구분해야 합니다. 여기서 OpenCode Go는 현재 판매 중인 월 $10 모델 구독 서비스입니다. 이는 opencode.ai/docs/go에 문서화되어 있으며, 자체 README에서 원저자와 Charm 팀이 프로젝트를 Crush라는 이름으로 계속 진행한다고 밝힌 보관된 Go 언어 OpenCode 터미널 에이전트가 아닙니다. 이는 단종된 제품에 대한 마이그레이션 안내가 아니라, 클라이언트 요구사항이 강화된 현재 판매 서비스에 대한 문제 해결 페이지입니다. 또한 여기서 nanobot은 MIT 라이선스의 Python 개인 에이전트 프레임워크인 HKUDS/nanobot을 뜻합니다. 2026년 9월 21일 GitHub API 확인 기준 별표 48,459개를 보유하고 보관되지 않았으며 당일 마지막 푸시가 이루어졌습니다. 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의 이슈 #5661과 PR #5662는 모두 2026년 9월 3일자 @opencode의 X 게시물을 인용하며, 해당 게시물은 헤더가 없는 도구는 프롬프트 캐시 최적화를 잃고 "09/06부터 이 헤더가 누락된 요청은 오류가 발생할 수 있습니다"라고 전했다고 설명합니다. 이 게시물은 nanobot 수정이 작성된 근거가 된 공지이며, 이 페이지에서 독립적으로 가져온 내용은 아닙니다.

심각한 오류는 타사 자료로만 입증됩니다. 2026년 9월 7일에 열리고 종료된 vastsa/PI-Desktop#48은 "type": "MissingSessionID"과 함께 HTTP 400을 기록하며, 요청에 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 및 이슈뿐입니다.

수정 사항의 실제 동작과 이를 트리거하는 조건

nanobot/providers/openai_compat_provider.py의 v0.3.5 태그에서 확인한 로직은 간단하지만 정확히 알아둘 가치가 있습니다. nanobot은 공급자 사양 이름이 opencode, opencode_zen 또는 opencode_go인 경우, 또는 기본 URL의 호스트 이름이 opencode.ai 또는 그 하위 도메인인 경우 대상을 OpenCode 대상으로 판단합니다. 대화 컨텍스트가 있으면 헤더 값은 세션 ID의 SHA-256 16진수 다이제스트이며, 이를 통해 원래 ID를 드러내지 않고 비ASCII ID도 ASCII로 안전하게 표현할 수 있습니다. 대화 컨텍스트가 없으면 공급자 인스턴스는 자체 수명 동안 고정되는 무작위 UUID를 헤더 값으로 사용합니다. 즉, 해당 인스턴스에서 일정하게 유지되는 값이지 대화별 값은 아닙니다. 직접 구성한 헤더는 이름을 대소문자 구분 없이 비교하여 적용되며, 앞서 설명한 두 값보다 우선합니다.

기억해야 할 문장은 호스트 이름 조건입니다. 헤더는 어떤 공급자 블록을 작성했는지가 아니라 요청이 향하는 위치에 따라 추가됩니다. providers.custom 블록을 opencode.ai 기본 URL로 지정해도 헤더가 추가됩니다. 다른 호스트로 보내는 요청에는 헤더가 추가되지 않으며, 대신 해당 호스트가 요구하는 사항은 그 공급자의 문제이고 여기서는 답하지 않습니다.

업그레이드는 일반적인 절차입니다. 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일 확인한 자체 문서에서 가져왔습니다.

사용자 에이전트 행에는 주의가 필요합니다. PR #5662는 세션 헤더만 변경했습니다. nanobot v0.3.5 소스를 확인하면 opencode, opencode_zen 및 opencode_go 사양을 제공하는 OpenAI 호환 공급자 모듈 어디에도 User-Agent가 설정되어 있지 않지만, GitHub Copilot, xAI Grok 및 OpenAI Codex 공급자 모듈에는 각각 nanobot 브랜드의 User-Agent가 설정되어 있습니다. 따라서 해당 경로의 요청에는 기반 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에는 nanobot이 전송 전에 제거하는 opencode-go/ 접두사가 포함됩니다. 마지막으로 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}'

이렇게 하면 두 오류를 명확히 구분할 수 있습니다. MissingSessionID을 명시하는 400 오류는 헤더 문제이며, 그 외의 오류는 헤더 문제가 아닙니다. 오류가 사라지게 하려고 요청마다 새로운 무작위 ID를 사용하지 말고, 다른 클라이언트의 이름을 빌리지도 마세요. 문서에서 대화마다 안정적인 ID를 요구하는 이유는 라우팅과 프롬프트 캐싱이 해당 ID를 키로 사용하기 때문입니다. 따라서 요청마다 ID를 바꾸면 비용을 지불하는 캐싱이 무효화될 뿐 아니라 해결책처럼 보일 수 있습니다. 정당한 답은 업그레이드하거나, 해당 요구사항이 없는 경로로 워크로드를 이동하는 두 가지입니다.

비용과 더 적합한 경로

소프트웨어와 토큰을 분리해서 생각하세요. 2026년 9월 21일 확인한 저장소 기록에 따르면 nanobot 자체는 $0입니다. MIT 라이선스이며 자체 호스팅되므로, 아래 내용은 모두 모델 이용 요금과 nanobot을 실행하는 머신에 관한 것입니다.

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개를 사용한다고 가정하고, 토큰 100만 개당 적용되는 실시간 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 문서와 변경 로그, HKUDS/nanobot 릴리스·태그·PR #5662·이슈 #5661 및 커밋이 v0.3.5 태그에 포함됨을 입증하는 compare 호출에 대한 GitHub API, 인용된 공지와 보고된 400 오류에 대한 anomalyco/opencode#47438 및 vastsa/PI-Desktop#48, 그리고 nanobot이 전송하는 내용에 관한 모든 주장에 대한 v0.3.5 소스 tarball을 확인했습니다. 09/06 날짜는 nanobot의 이슈와 PR에서 인용한 2026년 9월 3일자 X의 @opencode 게시물에서 유래하지만, 이 페이지에서는 해당 게시물을 가져오지 못했습니다. 인용된 구독자 공지와 400 오류 계약은 사용자 제보이며, OpenCode의 문서나 변경 로그에는 어느 것도 나타나지 않습니다. 여기서는 nanobot을 OpenCode Go 또는 Kunavo에 연결해 실행하거나 오류를 재현하지 않았습니다. Kunavo 토큰 요금은 실시간 카탈로그에서 가져왔으며 모든 달러 금액은 명시된 가정에 따른 예시 계산입니다.