PicoClaw model not found 404: mã model và giao thức Anthropic

Trong PicoClaw, "model not found" và 404 là bốn lỗi khác nhau, và chỉ một lỗi xảy ra bên ngoài máy của bạn. Ba lỗi là cục bộ — alias không được phân giải, backend web của chính PicoClaw trả về 404 và chuỗi giao thức không xác định — còn lỗi thứ tư là 404 từ upstream, với nội dung phản hồi cho biết route sai hay model id sai. Đọc nội dung lỗi trước tiên sẽ ngăn bạn đổi giao thức để sửa một lỗi gõ.

Trang này giả định bạn đã có mục model_list hoạt động và một khóa; phần thiết lập cũng như chi phí PicoClaw được trình bày trong giá và thiết lập API PicoClaw. Mọi nội dung dưới đây được đọc tại tag phát hành v0.3.1, được API phát hành xác nhận là bản mới nhất vào ngày 21 tháng 9 năm 2026, phát hành ngày 3 tháng 7 năm 2026. Repository được push lần cuối vào ngày 17 tháng 9 năm 2026, vì vậy main mới hơn tag — khi điều đó quan trọng, nội dung sẽ nêu rõ. Vào ngày 1 tháng 10 năm 2026, v0.3.1 vẫn là bản phát hành mới nhất, và binary phát hành sau đó được chạy với endpoint ghi nhận cục bộ và, bằng một khóa cố ý không hợp lệ, với Kunavo; những gì thử nghiệm cho thấy được ghi lại bên dưới.

Bốn lỗi, một cụm từ

Do đó, điều đầu tiên cần xác định là yêu cầu có rời khỏi máy của bạn hay không, và riêng chuỗi lỗi đã đủ kết luận. Alias không khớp là một trường hợp đã được ghi nhận, không phải giả thuyết: issue #958 của PicoClaw báo cáo error creating provider: model "llama3.2" not found in model_list trong khi picoclaw status cho thấy endpoint Ollama có thể truy cập và model hiện diện dưới dạng llama3.2:latest. Issue được đóng vào ngày 25 tháng 3 năm 2026 bởi bot đánh dấu issue cũ của repository. Lưu ý rằng trong repository này, một issue đã đóng được đánh dấu completed không có nghĩa là đã được sửa — chính bot đó đã đóng #1624 với cùng cách diễn đạt.

Nội dung bọc cho biết giao thức nào thực sự đã chạy

Vì anthropic với api key và anthropic-messages tạo ra các nhà cung cấp khác nhau, các lớp bọc 404 của chúng cũng khác nhau — khiến chuỗi lỗi trở thành một công cụ chẩn đoán miễn phí.

Vì sao hướng dẫn 404 của chính PicoClaw có thể dẫn bạn sai hướng

Hướng dẫn nhà cung cấp của PicoClaw bảo bạn chuyển sang anthropic-messages khi "Giao thức anthropic hiện có trả về lỗi 404 (cho biết endpoint không hỗ trợ định dạng tương thích OpenAI)", đồng thời thêm ghi chú làm rõ cách đặt tên: "Giao thức anthropic sử dụng định dạng tương thích OpenAI (/v1/chat/completions), còn anthropic-messages sử dụng định dạng gốc của Anthropic (/v1/messages)." Cả hai trích dẫn đều được đọc lại tại v0.3.1 vào ngày 21 tháng 9 năm 2026.

Hướng dẫn đó đúng với 404 của route nhưng sai với 404 của model. Nó cũng nằm thấp hơn 294 dòng so với một bảng trong cùng tệp, trong đó cột Protocol ghi Anthropic cho dòng anthropic, trái ngược hoàn toàn. Mã nguồn giải quyết mâu thuẫn này theo một cách không dễ nhận ra: anthropic là hai giao thức, tùy thuộc vào auth_method. Với oauth hoặc token, nó tạo nhà cung cấp SDK Anthropic gốc và bảng là đúng; với khóa api, nó rơi xuống cùng nhà cung cấp tương thích OpenAI được openai và toàn bộ họ của nó sử dụng, nên ghi chú là đúng.

Có hai hệ quả trực tiếp. Với họ openai, viết https://api.kunavo.com thay vì https://api.kunavo.com/v1 sẽ tạo thành https://api.kunavo.com/chat/completions — một 404 của route do chính cấu hình của bạn gây ra, và là trường hợp phổ biến nhất. Với cả hai giao thức Anthropic, lỗi đó là không thể xảy ra vì /v1 luôn bị buộc theo một trong hai cách; nhưng chính việc ép buộc này cũng có nghĩa là một gateway có đường dẫn không được kết thúc bằng /v1 hoàn toàn không thể được biểu diễn qua chúng, và thay vào đó phải đi qua giao thức openai. Tài liệu riêng của PicoClaw dùng lối thoát đó cho một nhà cung cấp có base kết thúc bằng một phân đoạn phiên bản khác.

Một nhận định cần xem là chưa được xác định. Bình luận duy nhất trên issue #269 của PicoClaw khẳng định rằng gửi đến /v1/chat/completions trả về 404 tại Anthropic vì endpoint đúng là /v1/messages. Tài liệu riêng của Anthropic mâu thuẫn với điều đó: tài liệu công bố lớp tương thích OpenAI SDK với base_url https://api.anthropic.com/v1/ và đánh dấu header authorization là "Được hỗ trợ đầy đủ" (đã kiểm tra ngày 21 tháng 9 năm 2026), đồng thời cảnh báo trên cùng trang rằng lớp này "không được xem là giải pháp dài hạn hoặc sẵn sàng cho môi trường production đối với hầu hết trường hợp sử dụng". Issue #269 đã được đóng vào ngày 13 tháng 3 năm 2026 mà không có bình luận đóng — API issues cho thấy có một bình luận trên đó, chính là phân tích ở trên, từ một tài khoản không liên kết với repository — vì vậy không rõ điều gì thực sự đã giải quyết nó. Hãy tin vào nội dung phản hồi 404 của chính bạn hơn là một trong hai lời giải thích đó.

Khi 404 là do model id

Issue #1624 của PicoClaw — mở ngày 16 tháng 3 năm 2026, đóng ngày 31 tháng 3 năm 2026 — ghi lại chính xác nội dung phản hồi cho một Claude id có dấu chấm được cấu hình là "model": "anthropic/claude-sonnet-4.6": Status: 404 với {"error":{"code":"not_found_error","message":"model: claude-sonnet-4.6 was not found. Did you mean claude-sonnet-4-6?"…. Tiêu đề và bình luận duy nhất của issue được đọc lại từ API issues vào ngày 21 tháng 9 năm 2026: bình luận đó do bot xử lý các issue lâu không có hoạt động đăng, vì vậy issue đã đóng nhưng không có bằng chứng về bản sửa lỗi.

Gợi ý "bạn có muốn nói" là dấu hiệu nhận biết. Nó chỉ được trả về từ một endpoint đã phân tích yêu cầu, vì vậy route đã hoạt động và thay đổi giao thức sẽ không giúp ích. Lý do PicoClaw không tự sửa chính tả cho bạn rất cụ thể và có thể kiểm tra: strings.ReplaceAll(model, ".", "-") xuất hiện một lần trong repository, tại pkg/providers/anthropic/provider.go dòng 219 — nhà cung cấp SDK được dùng trên các đường dẫn OAuth và token. Cả anthropic_messages/provider.go lẫn openai_compat/provider.go đều không chứa nó. Cả hai nhận định đã được kiểm tra lại tại v0.3.1 vào ngày 21 tháng 9 năm 2026, và nghiên cứu trước trang này đã tải lại chính các tệp đó từ main cùng ngày với cùng kết quả. Việc chạy binary v0.3.1 vào ngày 1 tháng 10 năm 2026 đã xác nhận điều đó trên cả hai đường dẫn khóa API: id có dấu chấm đến endpoint đúng như được viết và nhận 404 của chính endpoint (xem những gì việc chạy v0.3.1 cho thấy). Đường dẫn OAuth và token, đường dẫn duy nhất có phép viết lại, chưa được chạy.

Các tệp riêng của PicoClaw cũng không thống nhất về cách viết: provider_metadata.go liệt kê id có dấu gạch nối cho cả hai mục Anthropic, ví dụ anthropic trong hướng dẫn nhà cung cấp dùng id có dấu chấm, còn anthropic-messages trả về giá trị mặc định có dấu chấm từ GetDefaultModel — chính cách viết mà #1624 cho thấy bị từ chối. Mọi Claude API id được in trên tổng quan model của Anthropic đều dùng dấu gạch nối, và trang đó liệt kê Claude Sonnet 4.6 cùng Claude Opus 4.6 dưới mục "Model cũ (vẫn khả dụng)" — vì vậy việc ngừng cung cấp không phải lý do khiến id 4.6 trả về 404 trên Anthropic hiện nay. Điều đó loại trừ một nguyên nhân, không phải mọi nguyên nhân: một id có dấu gạch nối vẫn có thể bị gateway từ chối nếu gateway không có model đó. Hãy sao chép id từ endpoint bạn đang gọi, không phải từ README.

Ghi rõ cả hai mục và giữ id có dấu gạch nối. Không đặt key trong tệp này — PicoClaw đọc chúng từ ~/.picoclaw/.security.yml, nội dung này được đề cập trong hướng dẫn thiết lập.

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

Mục đầu tiên tự cung cấp /v1 vì nhóm giao thức tương thích OpenAI nối nguyên văn /chat/completions vào api_base. Mục thứ hai cố ý bỏ qua nó để cho thấy rằng trên anthropic-messages, cả hai cách viết đều được chuẩn hóa thành cùng một URL cơ sở. URL cơ sở được Kunavo công bố là https://api.kunavo.com/v1 cho hoàn thành hội thoại và https://api.kunavo.com/v1/messages cho đường dẫn Messages. Việc hai nhóm phép tính URL cho cùng kết quả được suy ra bằng phép tính dựa trên hai bộ tài liệu — và vào ngày 1 tháng 10 năm 2026, cả hai mục đều được chạy từ v0.3.1 đến Kunavo bằng một khóa cố ý không hợp lệ: mục openai đến /v1/chat/completions và mục anthropic-messages đến /v1/messages, cả hai đều nhận lại 401 của Kunavo. Điều đó chứng minh các URL, không phải một yêu cầu đã hoàn tất: không chỗ nào trên trang này tuyên bố đã kiểm thử tích hợp. Để xem dạng tổng quát của câu hỏi về URL cơ sở, hãy xem tài liệu URL cơ sở của Anthropic.

Gateway cũng có thể chủ động trả về 404, và đó không phải lỗi của PicoClaw. Kunavo trả về 404 cho model tạm thời bị tạm dừng, với nội dung nêu tên model và model thay thế cần dùng, đồng thời loại các model đang tạm dừng khỏi /v1/models; hãy đối chiếu cấu trúc của thông báo đó thay vì một tên cụ thể, vì các model nào bị tạm dừng có thể thay đổi. Kunavo cũng không cung cấp model embedding, text-to-speech hoặc speech-to-text, vì vậy một mục model_list chỉ định một trong các loại đó sẽ trả về 404 bất kể bạn chọn giao thức nào — hãy trỏ các mục đó đến nhà cung cấp khác và chỉ giữ các mục chat trên khóa Kunavo.

Những gì việc chạy v0.3.1 cho thấy

Vào ngày 1 tháng 10 năm 2026, binary phát hành v0.3.1, được xác minh checksum theo tệp checksum riêng của bản phát hành, được chạy trong một container dùng một lần với từng mục model_list một và picoclaw agent -m. Endpoint là một máy chủ ghi cục bộ hoạt động giống định tuyến của Kunavo tại thời điểm đó — /v1/* là API, mọi đường dẫn khác trả về trang 404 HTML (hiện Kunavo trả về 404 JSON cho các đường dẫn đó và nêu cách khắc phục; xem các dòng Kunavo) — đồng thời biết claude-sonnet-5 và claude-sonnet-4-6 nhưng không biết id có dấu chấm; ba dòng cuối sử dụng api.kunavo.com thực tế với một khóa cố ý không hợp lệ, vì vậy không có khoản nào được tính phí.

Thử nghiệm này xác lập hai điều mà việc đọc mã nguồn chỉ có thể dự đoán. Lớp bao bọc lỗi thực sự nêu tên nhà cung cấp đã chạy, vì vậy có thể an toàn suy ra giao thức từ đó; và id có dấu chấm được gửi nguyên trạng trên cả hai đường dẫn khóa API, vì vậy lỗi "không tìm thấy model" trích dẫn id có dấu chấm được khắc phục bằng cách viết lại id, không phải bằng cách chuyển giao thức. Những điều thử nghiệm không bao quát: các đường dẫn OAuth và token, giao diện web của launcher, streaming, và mọi yêu cầu đã hoàn tất qua Kunavo — các dòng Kunavo cố ý dùng khóa không hợp lệ.

Thứ tự kiểm tra ngắn nhất

1. Có gì rời khỏi máy không? Lỗi terminal chứa không tìm thấy trong model_list mà không có trạng thái HTTP là lỗi cục bộ. Đặt agents.defaults.model_name bằng một mục model_name rồi dừng ở đó.
2. Nó có đến từ localhost không? Lỗi 404 trong trình duyệt khi chọn model mặc định trong giao diện web của PicoClaw cũng là cùng một sự không khớp, được backend riêng của PicoClaw cung cấp. Không có API model nào được gọi.
3. Nhà cung cấp nào đã chạy? Đối chiếu văn bản lớp bao bọc với bảng ở trên. Nếu lớp bao bọc không khớp với giao thức bạn nghĩ mình đã cấu hình, trường provider hoặc tiền tố model không như bạn nghĩ.
4. 404 của route hay 404 của model? Nội dung phản hồi nêu tên model — đặc biệt kèm gợi ý bạn có muốn nói — là 404 của model: sửa id. Trang HTML, nội dung trống hoặc thông báo không tìm thấy chung chung là 404 của route: suy ra lại URL đã ghép từ bảng trước khi làm bất cứ điều gì khác.
5. Hãy hỏi endpoint xem nó cung cấp gì. PicoClaw không thể làm điều này trên cả hai giao thức Anthropic vì không mục danh mục nào đặt cờ fetch. Dùng curl với /v1/models riêng của gateway, hoặc tạm thời trỏ cùng gateway đó sang giao thức openai. Model không được tìm thấy giữa các nhà cung cấp trình bày phương pháp này, còn Anthropic 404 không tìm thấy model trình bày các trường hợp bản thân id là vấn đề.
6. Chỉ bây giờ mới thay đổi giao thức, và chỉ khi bước 4 cho biết đó là 404 của route. Nếu header xác thực mới là yếu tố cản trở thay vì định dạng truyền tải, token xác thực so với khóa api giải thích sự khác biệt.
7. Xác minh lại bằng một lượt công cụ, không phải một lượt chat thông thường. Một cấu hình trả lời được tin nhắn đơn vẫn có thể thất bại ở lần gọi công cụ đầu tiên, vì vậy tác vụ có giới hạn dùng để xác nhận bản sửa lỗi nên bao gồm một lần gọi công cụ.

Lựa chọn giao thức khiến bạn phải trả giá gì

Hệ quả chi phí lớn nhất là bộ nhớ đệm prompt, và đây là vấn đề mang tính cấu trúc chứ không phải một thiết lập. Trong PicoClaw v0.3.1, mã duy nhất phát ra điểm ngắt bộ nhớ đệm nằm ở pkg/providers/anthropic/provider.go, chỉ được truy cập trên các đường dẫn OAuth và token. Với khóa api — trường hợp tự cung cấp khóa thông thường — không giao thức Anthropic nào gửi cache_control. Đối với lớp tương thích riêng của Anthropic, điều này còn cộng dồn vì tài liệu của họ nêu rõ rằng "Bộ nhớ đệm prompt không được hỗ trợ, nhưng được hỗ trợ trong các SDK Anthropic". Với gateway chèn điểm ngắt cho các caller định dạng OpenAI, khoản tiết kiệm được khôi phục tại gateway; tài liệu bộ nhớ đệm của Kunavo cho biết họ làm vậy và nêu phạm vi chính xác: các model Claude được truy cập qua /v1/chat/completions hoặc /v1/responses. Cùng trang đó nói cache_control được truyền nguyên trạng trên route Messages gốc — vì vậy mục anthropic-messages không nhận điểm ngắt từ phía nào, và cột thứ hai bên dưới chỉ mô tả mục giao thức openai. Chưa kiểm tra việc các gateway khác có chèn điểm ngắt hay không, và không điều nào trong số này được quan sát từ bên trong PicoClaw.

Giá trị của điều đó là phép tính token minh họa, không phải chi phí tác vụ được đo lường và không phải mức trần hóa đơn. Giả sử một lượt của agent gồm 10 vòng gọi công cụ, trong đó mỗi vòng gửi lại cùng một tiền tố 20.000 token (system prompt, schema công cụ, transcript cho đến hiện tại), thêm 1.000 token đầu vào mới và trả về 600 token đầu ra. Các tỷ lệ đó là giả định để minh họa. Cột thứ nhất tính phí đầu vào của mọi vòng theo toàn bộ mức giá; cột thứ hai tính tiền tố lặp lại theo mức đọc từ bộ nhớ đệm kể từ vòng thứ hai. Mức giá là giá trực tiếp của danh mục Kunavo cho mỗi triệu token.

Theo các giả định này, Claude Sonnet 4.6 chuyển từ $0,504 sang $0,164 cho cùng một công việc. Hãy xem cột thứ hai là lạc quan: việc ghi vào bộ nhớ đệm được tính theo mức giá riêng và không được mô hình hóa theo cả hai hướng, còn tiền tố thay đổi ở mỗi vòng sẽ không bao giờ trở thành một lượt truy cập bộ nhớ đệm hợp lệ. Hãy nhân theo số lượt mỗi ngày trước khi coi bất kỳ con số nào là ngân sách.

Trong khi đó, hãy tách riêng hai khoản thanh toán. Bản thân PicoClaw miễn phí — repository được cấp phép MIT, và không giao thức nào, kể cả cả hai giao thức Anthropic, bị khóa sau bất kỳ khoản mua nào. Chi phí định kỳ là token model theo mức giá của nhà cung cấp. Số tiền trong danh mục của Kunavo là mức sàn thanh toán chứ không phải mức trần: khi upstream báo chi phí, hóa đơn là giá trị lớn hơn giữa chi phí trong danh mục và chi phí upstream nhân với markup áp dụng. Khoản nạp tối thiểu là $10 tín dụng trả trước, là mức tối thiểu để nạp tiền chứ không phải phí tác vụ hay gói đăng ký — xem chi tiết thanh toán.

Nhà cung cấp trực tiếp, gateway, gói đăng ký hoặc cục bộ

Bạn đang chọn runtime thay vì route? PicoClaw so với OpenClaw so sánh hai bên về hình thức triển khai. Nếu bạn chọn gateway và muốn cấp tiền cho một khóa, tạo tài khoản Kunavo, sau đó gửi một tác vụ có giới hạn kèm một lần gọi công cụ và đọc khoản phí mà tài khoản của bạn thực sự ghi nhận.

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

Đã kiểm tra ngày 21 tháng 9 năm 2026. Được xác minh lại trong tác vụ này tại tag v0.3.1: ghi chú giao thức và dòng nhà cung cấp Anthropic trong hướng dẫn nhà cung cấp, nhánh anthropic và nhánh mặc định của factory_provider.go, NormalizeBaseURL, URL, các header và chuỗi 404 của anthropic-messages, phép nối URL và header Bearer của openai_compat, ba chuỗi "not found in model_list" trước HTTP, 404 của backend web, lần xuất hiện duy nhất của phép thay dấu chấm bằng dấu gạch ngang, cột SupportsFetch của bảng tùy chọn nhà cung cấp, và ví dụ OpenRouter trong docs/operations/troubleshooting.md; cùng với API releases (v0.3.1, phát hành ngày 3 tháng 7 năm 2026) và tiêu đề, trạng thái, ngày tháng cùng bình luận của các issue #1624, #958 và #269. Trang tương thích OpenAI-SDK của Anthropic cũng được đọc cùng ngày. Chạy ngày 1 tháng 10 năm 2026: binary phát hành v0.3.1 trong container đến endpoint ghi cục bộ và, với khóa không hợp lệ, đến Kunavo — mọi dòng trong bảng trên. Chưa xác minh: bất kỳ điều gì trong main ngoài các tệp mà nghiên cứu đã so sánh, điều gì đã đóng issue #269, các đường dẫn OAuth và token, và bất kỳ yêu cầu nào đã hoàn tất qua Kunavo. Mức giá token của Kunavo lấy từ danh mục trực tiếp, và mọi con số tính bằng đô la ở đây đều là phép tính token minh họa.