Giá và thiết lập API PicoClaw: model, giao thức và khóa

Phần mềm PicoClaw miễn phí: kho lưu trữ được cấp phép MIT và FAQ riêng của picoclaw.io nói rằng "Phần mềm là miễn phí. Bạn chỉ trả tiền cho mức sử dụng API LLM" — vì vậy "giá PicoClaw" có nghĩa là hóa đơn API mô hình của bạn, cộng với mọi chi phí của thiết bị. Sipeed không quảng cáo gói đăng ký PicoClaw hay gói được lưu trữ. Con số đáng lập ngân sách là số token mỗi lượt agent, còn thiết lập dễ gây bất ngờ nhất là giới hạn lặp công cụ của PicoClaw: 50 khi trường này vắng mặt, 20 trong cấu hình mẫu được cung cấp.

Trước hết cần phân biệt hai điểm, vì trang kết quả trộn lẫn chúng. Tên miền chính thức là picoclaw.io — đây là trường homepage của github.com/sipeed/picoclaw. Trang trông tương tự pico-claw.com nêu trong chân trang rằng nó "không chính thức liên kết với Sipeed hoặc PicoClaw", và giá gói hằng tháng trên đó thuộc về mô-đun lưu trữ được quản lý riêng của trang, không thuộc PicoClaw. Một trang trông tương tự khác, picoclaw.net, cũng không phải tên miền chính thức. Trang này đề cao "95% Mã do AI tạo" và "3 Kiến trúc được hỗ trợ" — x86_64, ARM64 và RISC-V — trong khi FAQ trên picoclaw.io liệt kê sáu kiến trúc. Và PicoClaw không phải là fork của OpenClaw; đây là một implementation Go độc lập tự benchmark với OpenClaw và NanoBot.

Giá PicoClaw, từng dòng một

Tất cả được kiểm tra ngày 21 tháng 9 năm 2026. Phiên bản, để ghi nhận: bản phát hành được gắn thẻ mới nhất là v0.3.1, phát hành ngày 3 tháng 7 năm 2026, trong khi kho lưu trữ được push lần cuối vào ngày 17 tháng 9 năm 2026 — vì vậy mã trên main mới hơn thẻ, còn danh sách tin tức riêng của README thậm chí cũ hơn, với mục phát hành mới nhất là v0.2.9 ngày 28 tháng 5 năm 2026. Mọi hành vi bên dưới đều được đọc trên main, không phải từ binary v0.3.1 mà bạn sẽ tải xuống; người đọc dùng bản phát hành được gắn thẻ có thể thấy điều khác. Một điều kiện trực tiếp vào ngày kiểm tra: chứng chỉ TLS của picoclaw.io đã hết hạn (có hiệu lực từ ngày 25 tháng 2 đến ngày 10 tháng 9 năm 2026), nên trình duyệt hiển thị cảnh báo bảo mật trên trang tải xuống chính thức. Điều này có thể được khắc phục bất kỳ ngày nào và không nói lên điều gì về dự án; GitHub Releases không bị ảnh hưởng.

Thiết lập khóa API PicoClaw: model_list và .security.yml

picoclaw onboard tạo ~/.picoclaw/config.json và workspace. Các model được khai báo trong một mảng model_list và được chọn theo tên từ agents.defaults.model_name; hai giá trị này phải khớp nhau, đây là trường hợp duy nhất được tài liệu khắc phục sự cố của PicoClaw đề cập.

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

Các khóa nằm trong tệp thứ hai. Tài liệu bảo mật của PicoClaw gọi config.json là "Cấu hình chính (an toàn để chia sẻ)" và .security.yml là "Dữ liệu bảo mật (tuyệt đối không chia sẻ)", đồng thời yêu cầu bạn chmod 600 tệp này. Cấu trúc YAML là một bản đồ với khóa là model_name, không phải mảng được dùng trong config.json, và api_keys là số nhiều và là một mảng ngay cả khi chỉ có một khóa.

# The map key must equal the model_name in config.json.
# api_keys is plural and is an array even for one key.
model_list:
  gateway-sonnet:
    api_keys:
      - "sk-kn-..."

Bốn chi tiết dễ khiến người dùng mắc lỗi. provider là tùy chọn: đặt giá trị này thì model được gửi lên phía nhà cung cấp không thay đổi; bỏ qua thì PicoClaw đọc mọi thứ trước / đầu tiên trong model làm nhà cung cấp, đây là dạng protocol/model cũ. Cấu hình có phiên bản lược đồ và phiên bản 3 là phiên bản hiện tại; quá trình di chuyển tạo bản sao lưu có đóng dấu ngày, đồng thời tài liệu cảnh báo rằng tệp V3 không thể được các bản dựng chỉ hỗ trợ V2 cũ tải một cách an toàn. Trong quá trình di chuyển từ V1 sang V2, enabled được tự động suy ra — các mục không có khóa API và không có tên local-model sẽ mặc định là đã tắt — đó là lý do ví dụ trên đặt enabled một cách rõ ràng sau khi các khóa đã được chuyển sang .security.yml. Ngoài ra, tính năng streaming mặc định bị tắt và được kiểm soát qua hai lớp: streaming.enabled của mục model và settings.streaming.enabled của kênh đều phải là true.

Có một ranh giới cần nêu rõ trước khi bạn viết các mục: bảng nhà cung cấp của PicoClaw liệt kê Groq là "LLM + phiên âm giọng nói (Whisper)", còn Kunavo không cung cấp chuyển giọng nói thành văn bản, chuyển văn bản thành giọng nói hoặc embeddings — một mục phiên âm hoặc embedding phải trỏ đến nhà cung cấp khác, và chỉ các mục chat mới có thể dùng khóa Kunavo.

Tên giao thức bị đảo ngược, và đó chính là cái bẫy

Trong PicoClaw, anthropic có nghĩa là các model dạng Claude qua định dạng wire của OpenAI, còn anthropic-messages có nghĩa là Messages API gốc của Anthropic. Tài liệu nói thẳng: "Giao thức anthropic sử dụng định dạng tương thích với OpenAI (/v1/chat/completions), còn anthropic-messages sử dụng định dạng gốc của Anthropic (/v1/messages)." Mã nguồn cũng xác nhận điều đó — factory_provider.go xây dựng provider HTTP dùng chung, tương thích với OpenAI cho anthropic và một provider gốc riêng cho anthropic-messages. Bảng "Tất cả nhà cung cấp được hỗ trợ" của PicoClaw lại mâu thuẫn với cả hai khi gắn nhãn "Anthropic" cho cột giao thức của hàng anthropic; người đọc chỉ xem bảng này sẽ cấu hình sai.

Đọc từ openai_compat/provider.go, common/anthropic_common.go, anthropic_messages/provider.go và factory_provider.go trên main, ngày 21 tháng 9 năm 2026 — được suy ra từ mã nguồn, không phải quan sát dữ liệu truyền qua mạng. Hệ quả là cụ thể: bạn không thể trỏ anthropic hoặc anthropic-messages đến một gateway có đường dẫn không được kết thúc bằng /v1, vì PicoClaw luôn thêm nó. Gateway tại https://gw.example.com/anthropic sẽ trở thành https://gw.example.com/anthropic/v1/messages. Với một endpoint như vậy, giao thức openai, vốn tôn trọng nguyên trạng đường dẫn, là giao thức duy nhất có thể biểu diễn URL đó. Chỉ ba giao thức này đã được kiểm tra; không được khái quát hóa quy tắc cho gemini, azure hoặc phần còn lại.

Đường dẫn native còn có hai giới hạn khác, đều được đọc trong cùng tệp. anthropic-messages yêu cầu khóa API và báo lỗi nghiêm trọng nếu thiếu, vì vậy nhánh OAuth — được factory_provider.go nối với anthropic và openai, cùng các cầu nối CLI và antigravity — không thể được truy cập qua đó. Ngoài ra, trong khi năm nhánh trong factory_provider.go chuyển tiếp cfg.CustomHeaders, nhánh anthropic-messages không nằm trong số đó: hàm khởi tạo của nó chỉ nhận khóa, URL cơ sở, user agent và timeout. Vì vậy, tùy chọn thoát custom_headers được tài liệu ghi nhận cho gateway có cơ chế xác thực không chuẩn dường như áp dụng cho các giao thức tương thích với OpenAI, chứ không áp dụng cho Messages native. Đây là kết luận từ việc đọc mã nguồn, không phải phép thử lúc chạy. Điều mà đường dẫn native không làm bạn mất là khả năng gọi công cụ: nó tạo tools native với input_schema và xử lý các khối tool_use và tool_result.

Đối với Kunavo, hai URL cơ sở được tài liệu ghi nhận là https://api.kunavo.com/v1 cho chat completions và https://api.kunavo.com/v1/messages cho route Messages, đồng thời trình xử lý Messages của Kunavo đọc khóa từ cả x-api-key lẫn Authorization: Bearer. Về lý thuyết, các URL này khớp với phép tính URL của PicoClaw theo cả hai chiều. Đây là phép tính dựa trên hai bộ tài liệu — chưa có yêu cầu PicoClaw nào được gửi đến Kunavo tại đây và trang này không khẳng định bất kỳ giao thức PicoClaw nào đã được kiểm thử với Kunavo. Xem tài liệu URL cơ sở Anthropic và tài liệu endpoint chat để biết chính xác cấu trúc, sau đó tự gửi một yêu cầu có giới hạn.

Ước tính chi phí API PicoClaw có minh họa

Đây 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 hoàn tất trong 8 vòng gọi công cụ, trong đó mỗi vòng gửi lại một transcript trung bình gồm 12.000 token đầu vào và trả về 700 token đầu ra. Các tỷ lệ này chỉ là giả định để minh họa. Cột thứ hai áp dụng cùng cấu trúc cho giá trị mặc định max_tool_iterations được biên dịch là 50 trong pkg/config/defaults.go, được dùng khi trường này không xuất hiện — config/config.example.json đi kèm ghi 20, vì vậy hãy đọc tệp của bạn trước khi coi 50 là mức trần. Đơn giá là giá trong danh mục Kunavo hiện hành trên mỗi triệu token.

Hãy đọc hai cột như một thông tin thống nhất. Từ 8 vòng lên mức trần 50 vòng sẽ nhân mọi hàng với cùng 6,25x, vì độ dài vòng lặp độc lập với đơn giá: một lượt Claude Sonnet 4.6 là $0,260 ở 8 vòng và $1,627 ở mức trần, còn Claude Haiku 4.5 ở chính mức trần đó là $0,542. Vì vậy, hãy giới hạn max_tool_iterations ở một con số bạn đã thực sự quan sát trước khi tìm đơn giá rẻ hơn — giá trị này nằm dưới agents.defaults và có thể được ghi đè bằng biến môi trường PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS. Sau đó nhân theo số lượt mỗi ngày.

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 mức markup áp dụng. Các lần đọc và ghi cache được tính theo đơn giá riêng và không được mô hình hóa ở cả hai chiều trong ví dụ này; các lần gọi công cụ bên ngoài cũng nằm ngoài ví dụ. Mức 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 chứ không phải phí tác vụ hay gói đăng ký — xem chi tiết thanh toán và tối ưu hóa chi phí AI để biết phương pháp đo lường.

API tốt nhất cho PicoClaw: chọn route nào trong trường hợp nào

Số lượng provider không phải là tiêu chí so sánh ở đây: chính các tệp của PicoClaw cũng không thống nhất với nhau về những provider nào tồn tại, vì vậy cách diễn đạt "30+ LLM providers" trong README là điều an toàn nhất để nhắc lại. Để biết PicoClaw đứng ở đâu giữa các agent đơn nhị phân khác, thư mục API agent AI liệt kê bề mặt cấu hình của nó bên cạnh các agent kia, còn các lựa chọn thay thế OpenRouter so sánh các route gateway theo điều khoản nạp tiền thay vì độ sâu tích hợp.

Yêu cầu đầu tiên, vòng gọi công cụ đầu tiên và lỗi 404

Chạy một tác vụ có phạm vi giới hạn và xem xét ba điểm theo thứ tự. Lỗi model not found in model_list là trường hợp đã được ghi nhận trong tài liệu và xuất phát từ việc tên không khớp: agents.defaults.model_name phải bằng một mục model_name, và một id không có tiền tố khi chưa thiết lập provider sẽ không chọn nhà cung cấp mà bạn muốn — thay vào đó, nó quay về giao thức openai, tương ứng với trường hợp "model": "free" đã được ghi nhận trong tài liệu, trong đó OpenRouter nhận id nguyên văn là free và từ chối id đó. Lỗi 404 ngay ở yêu cầu đầu tiên là dấu hiệu đã được ghi nhận trong tài liệu cho thấy bạn đã chọn sai giao thức Anthropic — hướng dẫn của chính PicoClaw nêu rõ cần chuyển sang anthropic-messages khi "giao thức anthropic hiện tại trả về lỗi 404 (cho thấy điểm cuối không hỗ trợ định dạng tương thích với OpenAI)". Hãy đối chiếu URL đã được ghép hoàn chỉnh với bảng ở trên trước khi thay đổi bất kỳ điều gì khác; không có mục khắc phục sự cố chính thức nào cho trường hợp này, nên chẩn đoán đó dựa trên ghi chú về các nhà cung cấp và mã nguồn, chứ không phải một trang hỗ trợ. Thứ ba, nếu lượt gọi công cụ đầu tiên thất bại trong khi trò chuyện thông thường vẫn hoạt động, hãy nghi ngờ các yêu cầu nghiêm ngặt về lược đồ thay vì vấn đề xác thực: theo mặc định, PicoClaw chuyển tiếp nguyên trạng các lược đồ công cụ, và tool_schema_transform: "simple" là tùy chọn theo từng mô hình để bỏ hành vi mặc định này đối với các điểm cuối từ chối $ref, $defs, anyOf, oneOf, allOf hoặc pattern.

Kunavo không công bố trang thiết lập PicoClaw và chưa thực hiện kiểm thử tương thích PicoClaw; hãy giữ sẵn một route đang hoạt động trong khi thử, sau đó đọc khoản phí thực tế được ghi nhận vào tài khoản cho tác vụ đó thay vì ước tính từ trang này. Tạo tài khoản Kunavo khi bạn sẵn sàng nạp tiền cho một khóa, và so sánh đơn giá model tại Claude API rẻ nhất nếu Claude là dòng model bạn đã chọn.

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

Đã kiểm tra ngày 21 tháng 9 năm 2026: kho GitHub và API phát hành, picoclaw.io (được đọc khi tắt xác thực chứng chỉ vì chứng chỉ đã hết hạn), README, docs/guides/providers.md, docs/security/security_configuration.md, docs/reference/config-versioning.md, docs/guides/configuration.md, docs/operations/troubleshooting.md, config/config.example.json, và bảy tệp mã nguồn trên nhánh main — factory_provider.go, openai_compat/provider.go, common/anthropic_common.go, anthropic_messages/provider.go, provider_metadata.go, pkg/config/defaults.go và pkg/config/config.go — cùng hai tên miền dễ gây nhầm lẫn. Chưa kiểm tra: hạn mức của bên thứ ba trong bảng so sánh riêng của PicoClaw, giá phần cứng bán lẻ và ghi chú phát hành v0.3.1. Không cài đặt hoặc chạy gì: không có yêu cầu PicoClaw nào được gửi đến bất kỳ endpoint nào. Đơn giá token của Kunavo lấy từ danh mục hiện hành, và mọi ví dụ tính bằng đô la ở đây đều là phép tính token minh họa chứ không phải chi phí tác vụ được đo lường.