PicoClaw model not found 404: 모델 ID와 Anthropic 프로토콜

PicoClaw에서 "model not found"와 404는 서로 다른 네 가지 오류이며, 그중 단 하나만 컴퓨터 외부에서 발생합니다. 세 가지는 로컬 오류입니다. 확인되지 않는 별칭, PicoClaw 자체 웹 백엔드의 404 응답, 알 수 없는 프로토콜 문자열입니다. 네 번째는 업스트림 404이며, 본문을 통해 잘못된 라우트인지 모델 ID인지 알 수 있습니다. 먼저 오류 텍스트를 읽어야 오타를 수정하려고 프로토콜을 바꾸는 일을 막을 수 있습니다.

이 페이지는 이미 작동하는 model_list 항목과 키가 있다고 가정합니다. 설정 자체와 PicoClaw의 비용은 PicoClaw 가격 및 API 설정에서 다룹니다. 아래 내용은 모두 릴리스 태그 v0.3.1에서 확인했습니다. 릴리스 API는 2026년 9월 21일에 이 버전이 최신 릴리스임을 확인했으며, 게시일은 2026년 7월 3일입니다. 저장소는 2026년 9월 17일에 마지막으로 푸시되었으므로 main이 태그보다 앞서 있습니다. 이 차이가 중요한 경우에는 이를 명시합니다. 2026년 10월 1일에도 v0.3.1이 최신 릴리스였으며, 당시 해당 릴리스 바이너리를 로컬 기록 엔드포인트를 대상으로 실행하고, 의도적으로 잘못된 키를 사용해 Kunavo를 대상으로도 실행했습니다. 그 실행으로 확인한 내용은 아래에 기록되어 있습니다.

네 가지 오류, 하나의 표현

따라서 요청이 컴퓨터 외부로 나갔는지를 먼저 확인해야 하며, 문자열만으로도 이를 판단할 수 있습니다. 별칭 불일치는 가상의 사례가 아닙니다. PicoClaw 이슈 #958에는 error creating provider: model "llama3.2" not found in model_list가 보고되어 있고, picoclaw status는 Ollama 엔드포인트에 연결할 수 있으며 모델이 llama3.2:latest로 존재함을 보여 주었습니다. 저장소의 오래된 이슈 봇이 2026년 3월 25일 이슈를 닫았습니다. 이 저장소에서 completed로 표시된 닫힌 이슈는 수정되었다는 뜻이 아닙니다. 같은 봇이 같은 표현으로 #1624도 닫았습니다.

래퍼 텍스트는 실제로 실행된 프로토콜을 표시합니다

API 키를 사용하는 anthropic와 anthropic-messages는 서로 다른 프로바이더를 생성하므로 404 래퍼도 다릅니다. 따라서 오류 문자열만으로도 진단할 수 있습니다.

PicoClaw 자체의 404 조언이 잘못된 방향으로 이끌 수 있는 이유

PicoClaw의 프로바이더 가이드는 "기존 anthropic 프로토콜이 404 오류를 반환하는 경우(엔드포인트가 OpenAI 호환 형식을 지원하지 않음을 의미)" anthropic-messages로 전환하라고 안내하며, 명칭을 확정하는 다음 설명도 덧붙입니다. "anthropic 프로토콜은 OpenAI 호환 형식(/v1/chat/completions)을 사용하고, anthropic-messages는 Anthropic의 네이티브 형식(/v1/messages)을 사용합니다." 두 인용문 모두 2026년 9월 21일 v0.3.1에서 다시 확인했습니다.

이 조언은 라우트 404에는 맞지만 모델 404에는 틀립니다. 또한 같은 파일의 표보다 294줄 아래에 있으며, 해당 표의 Protocol 열은 anthropic 행에서 Anthropic로 되어 있어 정반대의 내용을 말합니다. 코드는 쉽게 드러나지 않는 방식으로 모순을 해결합니다. anthropic는 auth_method에 따라 두 가지 프로토콜입니다. oauth 또는 token을 사용하면 네이티브 Anthropic SDK 프로바이더를 생성하므로 표가 맞습니다. API 키를 사용하면 openai 및 그 전체 계열이 사용하는 동일한 OpenAI 호환 프로바이더로 넘어가므로 설명이 맞습니다.

두 가지 결과가 바로 따라옵니다. openai 계열에서 https://api.kunavo.com/v1 대신 https://api.kunavo.com을 작성하면 https://api.kunavo.com/chat/completions가 조합됩니다. 이는 사용자의 구성으로 인해 발생한 라우트 404이며 가장 흔한 유형입니다. 두 Anthropic 프로토콜에서는 어느 쪽이든 /v1가 강제되므로 이 실수가 불가능합니다. 그러나 같은 강제로 인해 경로가 /v1로 끝나면 안 되는 게이트웨이는 이 프로토콜로 표현할 수 없으며, 대신 openai 프로토콜을 사용해야 합니다. PicoClaw 자체 문서도 기본 경로가 다른 버전 세그먼트로 끝나는 벤더에 이 우회 방법을 사용합니다.

아직 확정되지 않은 주장 하나가 있습니다. PicoClaw 이슈 #269의 유일한 댓글은 /v1/chat/completions에 POST하면 Anthropic에서 404가 반환되며 올바른 엔드포인트는 /v1/messages라고 주장합니다. 그러나 Anthropic 자체 문서는 이와 모순됩니다. Anthropic은 base_url에 https://api.anthropic.com/v1/를 사용하는 OpenAI SDK 호환 계층을 제공하고, authorization 헤더를 "Fully supported"로 표시합니다(2026년 9월 21일 확인). 동시에 같은 페이지에서 이 계층은 "대부분의 사용 사례에서 장기적으로 사용할 수 있거나 프로덕션 환경에 바로 사용할 수 있는 솔루션으로 간주되지 않는다"고 주의를 줍니다. 이슈 #269는 종료 댓글 없이 2026년 3월 13일에 닫혔습니다. 이슈 API에는 저장소와 관련이 없는 계정이 작성한 댓글 하나, 즉 앞서 언급한 분석만 표시되므로 실제로 무엇이 이 문제를 해결했는지는 알 수 없습니다. 어느 쪽 설명보다도 직접 받은 404 응답 본문을 신뢰하세요.

404가 모델 ID인 경우

PicoClaw 이슈 #1624는 2026년 3월 16일에 열리고 2026년 3월 31일에 닫혔으며, "model": "anthropic/claude-sonnet-4.6"로 설정된 점이 포함된 Claude ID에 대한 정확한 응답 본문을 기록합니다. Status: 404와 함께 {"error":{"code":"not_found_error","message":"model: claude-sonnet-4.6 was not found. Did you mean claude-sonnet-4-6?"…가 반환되었습니다. 제목과 유일한 댓글은 2026년 9월 21일 이슈 API에서 다시 확인했습니다. 댓글은 오래된 이슈를 정리하는 봇이 작성한 것이므로, 이슈는 닫혔지만 수정되었다는 증거는 없습니다.

"Did you mean" 힌트가 결정적인 단서입니다. 요청을 파싱한 엔드포인트에서만 반환되므로 라우트는 정상 작동했고 프로토콜을 바꿔도 도움이 되지 않습니다. PicoClaw가 표기를 대신 수정하지 않는 이유는 명확하고 확인 가능합니다. strings.ReplaceAll(model, ".", "-")는 저장소에서 한 번, SDK 프로바이더가 사용되는 OAuth 및 토큰 경로의 pkg/providers/anthropic/provider.go 219행에만 나타납니다. anthropic_messages/provider.go와 openai_compat/provider.go에는 없습니다. 두 내용은 2026년 9월 21일 v0.3.1에서 다시 확인했고, 이 페이지에 앞선 조사에서도 같은 날 main에서 동일한 파일을 다시 가져와 같은 결과를 얻었습니다. 2026년 10월 1일 v0.3.1 바이너리를 실행해 두 API 키 경로에서 이를 확인했습니다. 점이 포함된 ID는 작성된 그대로 엔드포인트에 도달했고 엔드포인트 자체의 404로 반환되었습니다(v0.3.1 실행 결과 참조). 재작성 기능이 있는 유일한 경로인 OAuth 및 토큰 경로는 실행하지 않았습니다.

PicoClaw 자체 파일도 표기에 대해 서로 일치하지 않습니다. provider_metadata.go는 두 Anthropic 항목 모두 하이픈이 포함된 ID를 나열하고, 프로바이더 가이드의 anthropic 예시는 점이 포함된 ID를 사용하며, anthropic-messages는 GetDefaultModel에서 점이 포함된 기본값을 반환합니다. 이는 #1624에서 거부된 것과 같은 표기입니다. Anthropic의 모델 개요에 표시된 모든 Claude API ID는 하이픈을 사용하며, 해당 페이지는 Claude Sonnet 4.6과 Claude Opus 4.6을 "Legacy models (still available)" 아래에 나열합니다. 따라서 현재 Anthropic에서 4.6 ID가 404를 반환하는 이유는 폐기가 아닙니다. 이는 한 가지 원인을 배제할 뿐 모든 원인을 배제하지는 않습니다. 모델을 제공하지 않는 게이트웨이는 하이픈이 포함된 ID도 거부할 수 있습니다. README가 아니라 호출 중인 엔드포인트에서 ID를 복사하세요.

두 항목을 모두 명시적으로 작성하고 ID는 하이픈 표기를 유지하세요. 이 파일에 키를 넣지 마세요. PicoClaw는 키를 ~/.picoclaw/.security.yml에서 읽으며, 자세한 내용은 설정 가이드에 있습니다.

{
  "agents": {
    "defaults": {
      "model_name": "kunavo-sonnet"
    }
  },
  "model_list": [
    {
      "model_name": "kunavo-sonnet",
      "provider": "openai",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com/v1"
    },
    {
      "model_name": "kunavo-sonnet-native",
      "provider": "anthropic-messages",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com"
    }
  ]
}

첫 번째 항목은 OpenAI 호환 계열이 /chat/completions를 api_base 뒤에 그대로 이어 붙이므로 /v1를 직접 제공합니다. 두 번째 항목은 의도적으로 이를 생략해 anthropic-messages에서 두 표기가 동일한 기본 URL로 정규화된다는 점을 보여 줍니다. Kunavo의 공개 기본 URL은 채팅 완성용으로 https://api.kunavo.com/v1, Messages 경로용으로 https://api.kunavo.com/v1/messages입니다. 두 URL 계산이 일치한다는 것은 두 문서 집합을 바탕으로 계산한 결과입니다. 2026년 10월 1일 두 항목을 v0.3.1에서 의도적으로 잘못된 키를 사용해 Kunavo 대상으로 실행했습니다. openai 항목은 /v1/chat/completions에 도달했고 anthropic-messages 항목은 /v1/messages에 도달했으며, 각각 Kunavo의 401 응답을 받았습니다. 이는 URL을 입증하지만 요청이 완료되었음을 입증하지는 않습니다. 이 페이지 어디에도 통합을 테스트했다고 주장하는 내용은 없습니다. 기본 URL에 관한 일반적인 설명은 Anthropic 기본 URL 문서를 참조하세요.

게이트웨이는 의도적으로 404를 반환할 수도 있으며, 이는 PicoClaw 버그가 아닙니다. Kunavo는 일시 중지된 모델에 대해 모델 이름과 대신 사용할 대체 모델을 본문에 명시한 404를 반환하고, /v1/models에서 일시 중지된 모델을 제외합니다. 어떤 모델이 일시 중지되는지는 변경되므로 특정 이름이 아니라 해당 메시지의 형태를 기준으로 판단하세요. Kunavo는 임베딩, 텍스트 음성 변환 또는 음성 텍스트 변환 모델도 제공하지 않습니다. 따라서 그중 하나를 명시하는 model_list 항목은 어떤 프로토콜을 선택해도 404를 반환합니다. 해당 항목은 다른 프로바이더를 가리키고 Kunavo 키에는 채팅 항목만 유지하세요.

v0.3.1 실행 결과

2026년 10월 1일 릴리스 자체의 체크섬 파일과 대조해 체크섬을 검증한 v0.3.1 릴리스 바이너리를 일회성 컨테이너에서 한 번에 하나의 model_list 항목과 picoclaw agent -m로 실행했습니다. 엔드포인트는 당시 Kunavo의 라우팅처럼 동작하는 로컬 기록 서버였습니다. /v1/*는 API이고 다른 경로는 HTML 404 페이지를 반환했습니다(Kunavo는 현재 해당 경로에 수정 방법을 명시한 JSON 404를 반환합니다. Kunavo 행을 참조하세요). 서버는 claude-sonnet-5 및 claude-sonnet-4-6를 알고 있었지만 점이 포함된 ID는 알지 못했습니다. 마지막 세 행은 실제 api.kunavo.com를 사용했으며 키는 의도적으로 잘못된 것이므로 해당 요청에는 비용이 청구되지 않았습니다.

이 실행으로 소스 읽기만으로는 예측할 수 있었던 두 가지가 확정되었습니다. 오류 래퍼는 실제로 실행된 프로바이더를 표시하므로 그 내용을 통해 프로토콜을 확인해도 안전합니다. 또한 두 API 키 경로에서 점이 포함된 ID가 변경되지 않은 채 전송되므로, 점이 포함된 ID를 인용하는 "model not found" 오류는 프로토콜을 바꾸는 것이 아니라 ID 표기를 수정해야 해결됩니다. 확인되지 않은 내용은 OAuth 및 토큰 경로, 런처의 웹 UI, 스트리밍, 그리고 Kunavo를 통해 완료된 모든 요청입니다. Kunavo 행에서는 의도적으로 잘못된 키를 사용했습니다.

가장 짧은 확인 순서

1. 무언가 컴퓨터 외부로 나갔나요? HTTP 상태 없이 not found in model_list가 포함된 터미널 오류라면 로컬 오류입니다. agents.defaults.model_name를 model_name 항목과 동일하게 설정하고 여기서 중단하세요.
2. localhost에서 온 것인가요? PicoClaw의 웹 UI에서 기본 모델을 선택하는 동안 브라우저에 표시되는 404는 PicoClaw 자체 백엔드가 제공하는 동일한 불일치입니다. 모델 API는 관여하지 않았습니다.
3. 어떤 provider가 실행했나요? 래퍼 텍스트를 위 표와 대조하세요. 래퍼가 구성했다고 생각한 프로토콜과 일치하지 않는다면 provider 필드 또는 모델 접두사가 생각한 것과 다릅니다.
4. 라우트 404인가요, 모델 404인가요? 모델 이름이 본문에 포함되어 있고 특히 did you mean 힌트가 있다면 모델 404입니다. ID를 수정하세요. HTML 페이지, 빈 본문 또는 일반적인 not-found라면 라우트 404입니다. 다른 작업을 하기 전에 표에서 조합된 URL을 다시 도출하세요.
5. 엔드포인트에 무엇을 제공하는지 물어보세요. 두 Anthropic 프로토콜 중 어느 쪽에서도 PicoClaw는 이 작업을 수행할 수 없습니다. 두 카탈로그 항목 모두 fetch 플래그를 설정하지 않기 때문입니다. curl을 게이트웨이 자체의 /v1/models에 사용하거나, 동일한 게이트웨이를 일시적으로 openai 프로토콜에 연결하세요. 프로바이더 전반에서 모델을 찾을 수 없음에서는 이 방법을 다루고, Anthropic 404 모델을 찾을 수 없음에서는 ID 자체가 문제인 경우를 다룹니다.
6. 이제 프로토콜을 변경하세요. 단, 4단계에서 라우트 404라고 한 경우에만 변경합니다. 와이어 형식이 아니라 인증 헤더가 차단 요인이라면 auth token과 api key 비교에서 차이를 설명합니다.
7. 일반 채팅 턴이 아니라 도구를 한 번 실행하는 라운드로 다시 확인하세요. 단순한 메시지에 응답하는 구성도 첫 도구 호출에서는 실패할 수 있으므로, 수정 사항을 확인하는 제한된 작업에 도구 호출을 하나 포함해야 합니다.

프로토콜 선택으로 인해 발생하는 비용

가장 큰 비용 영향은 프롬프트 캐싱이며, 설정이 아니라 구조적인 문제입니다. PicoClaw v0.3.1에서 캐시 중단점을 생성하는 유일한 코드는 pkg/providers/anthropic/provider.go에 있으며, OAuth 및 token 경로에서만 도달합니다. api key를 사용하는 일반적인 자체 키 사용 사례에서는 어느 Anthropic 프로토콜도 cache_control을 전송하지 않습니다. Anthropic 자체 호환성 레이어를 사용할 때는 문서에 "Prompt caching is not supported, but it is supported in the Anthropic SDKs"라고 명시되어 있어 이 문제가 누적됩니다. OpenAI 형식 호출자를 위해 중단점을 삽입하는 게이트웨이를 사용하면 절약 효과는 대신 게이트웨이에서 회복됩니다. Kunavo의 캐싱 문서는 이를 수행한다고 설명하며 범위를 정확히 지정합니다. 즉, /v1/chat/completions 또는 /v1/responses를 통해 도달하는 Claude 모델입니다. 같은 페이지에서는 cache_control가 네이티브 Messages 라우트에서 번역되지 않은 채 전달된다고 설명합니다. 따라서 anthropic-messages 항목은 어느 쪽에서도 중단점을 얻지 못하며, 아래의 두 번째 열은 openai-프로토콜 항목만 설명합니다. 다른 게이트웨이가 중단점을 삽입하는지는 확인하지 않았으며, 이 중 어느 것도 PicoClaw 내부에서 관찰한 것은 아닙니다.

이 값은 측정된 작업 비용이나 청구 상한이 아니라 예시적인 토큰 산술입니다. 10회의 도구 라운드로 이루어진 에이전트 턴 하나를 가정합니다. 각 라운드는 동일한 20,000토큰 접두사(시스템 프롬프트, 도구 스키마, 현재까지의 대화 기록)를 다시 보내고, 1,000개의 새 입력 토큰을 추가하며 600개의 출력 토큰을 반환합니다. 이러한 비율은 설명을 위한 가정입니다. 첫 번째 열은 각 라운드의 입력을 전체 요율로 청구하고, 두 번째 열은 두 번째 라운드부터 반복되는 접두사에 캐시 읽기 요율을 적용합니다. 요율은 100만 토큰당 Kunavo 카탈로그의 실시간 가격입니다.

이러한 가정에서 Claude Sonnet 4.6은 동일한 작업에 대해 $0.504에서 $0.164로 이동합니다. 두 번째 열은 낙관적인 값으로 읽으세요. 캐시 쓰기는 자체 요율로 청구되며 어느 방향에도 모델링되지 않았고, 매 라운드 변경되는 접두사는 캐시 적중이 전혀 발생하지 않습니다. 이 값을 예산으로 간주하기 전에 하루 작업 횟수를 곱하세요.

진행하는 동안 두 청구액을 분리하세요. PicoClaw 자체는 무료입니다. 저장소는 MIT 라이선스이며 두 Anthropic 프로토콜을 포함해 어떤 프로토콜도 구매해야 사용할 수 있도록 제한되어 있지 않습니다. 반복적으로 발생하는 비용은 provider의 요율에 따른 모델 토큰 비용입니다. Kunavo 카탈로그 금액은 상한이 아니라 청구 하한입니다. 업스트림이 요금을 보고하면 청구액은 카탈로그 비용과 업스트림 비용에 해당 마크업을 곱한 값 중 큰 금액입니다. 최소 충전액은 선불 크레딧 10$이며, 작업 요금이나 구독료가 아닌 자금 충전 최소 금액입니다. 결제 세부 정보를 참조하세요.

직접 vendor, gateway, subscription 또는 local

라우트가 아니라 런타임을 선택하는 중인가요? PicoClaw와 OpenClaw 비교에서 배포 형태를 기준으로 두 제품을 비교합니다. 게이트웨이를 선택하고 키에 자금을 충전하려면 Kunavo 계정 생성 후 도구 호출이 포함된 제한된 작업 하나를 보내고 계정에 실제로 기록된 요금을 확인하세요.

자주 묻는 질문

2026년 9월 21일 확인. 이 작업에서 v0.3.1 태그를 기준으로 다시 검증한 항목은 다음과 같습니다. 프로바이더 가이드의 프로토콜 참고 사항과 Anthropic 공급업체 행, factory_provider.go의 anthropic 분기와 기본 분기, NormalizeBaseURL, anthropic-messages의 URL·헤더·404 문자열, openai_compat의 URL 연결과 Bearer 헤더, HTTP 요청 전 단계의 "not found in model_list" 문자열 세 개, 웹 백엔드의 404, 점을 하이픈으로 바꾸는 코드의 유일한 등장 위치, 프로바이더 옵션 표의 SupportsFetch 열, docs/operations/troubleshooting.md의 OpenRouter 예시입니다. 또한 릴리스 API(v0.3.1, 2026년 7월 3일 게시)와 이슈 #1624, #958, #269의 제목·상태·날짜·댓글도 확인했습니다. Anthropic의 OpenAI SDK 호환성 페이지도 같은 날 읽었습니다. 2026년 10월 1일 실행: 컨테이너에서 v0.3.1 릴리스 바이너리를 로컬 기록 엔드포인트를 대상으로 실행하고, 유효하지 않은 키로 Kunavo를 대상으로도 실행했습니다. 위 표의 모든 행이 이 실행에 해당합니다. 검증하지 않은 항목: 조사에서 차이를 비교한 파일 이외의 main 내용, 이슈 #269가 닫힌 이유, OAuth 및 토큰 경로, Kunavo를 통해 완료된 요청. Kunavo 토큰 요율은 실시간 카탈로그에서 가져오며, 여기의 모든 달러 금액은 예시적인 토큰 산술입니다.