OpenClaw

Một mục models.providers trong ~/.openclaw/openclaw.json — baseUrl https://api.kunavo.com, api "anthropic-messages" — kết nối tác nhân OpenClaw luôn hoạt động với Claude; cacheRetention được đặt cùng mục này, vì một điểm cuối Anthropic tùy chỉnh sẽ không nhận bất kỳ dấu mốc bộ nhớ đệm nào cho đến khi thiết lập đó được đặt.

// ~/.openclaw/openclaw.json — merge into the file you already have
{
  models: {
    mode: "merge",
    providers: {
      kunavo: {
        baseUrl: "https://api.kunavo.com",   // origin — no /v1 on this wire
        apiKey: "${KUNAVO_API_KEY}",         // from the environment or ~/.openclaw/.env
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
            contextTokens: 200000,           // optional: compact here, not at 1M
            maxTokens: 32000,
          },
          {
            id: "claude-haiku-4-5",
            name: "Claude Haiku 4.5",
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 16000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "kunavo/claude-sonnet-5" },
      models: {
        // Required for caching: a custom Anthropic endpoint gets no cache
        // markers from OpenClaw until cacheRetention is set explicitly.
        "kunavo/claude-sonnet-5": { params: { cacheRetention: "short" } },
        "kunavo/claude-haiku-4-5": { params: { cacheRetention: "short" } },
      },
    },
  },
}

Từng bước

1. Tạo khóa tại /app/keys rồi sao chép khóa — khóa chỉ hiển thị một lần.
2. Cung cấp khóa cho Gateway: thêm KUNAVO_API_KEY=sk-kn-... vào ~/.openclaw/.env, hoặc xuất khóa trong môi trường mà Gateway khởi chạy. Giá trị ${KUNAVO_API_KEY} trong khối cấu hình sẽ được thay thế bằng giá trị từ đó khi tải cấu hình.
3. Gộp khối cấu hình vào ~/.openclaw/openclaw.json, giữ nguyên các mục providers, agents và channels hiện có. Tệp dùng định dạng JSON5 nên có thể giữ lại các chú thích.
4. Chạy openclaw config validate. OpenClaw từ chối khởi động khi tệp chứa một thiết lập mà nó không nhận diện được, vì vậy phát hiện lỗi đánh máy ở đây sẽ tốt hơn là đợi đến lần khởi động lại tiếp theo.
5. Chạy openclaw models list --provider kunavo và kiểm tra xem cả hai mã định danh đều có trong danh sách. Nếu Gateway đang chạy chưa nhận thay đổi, hãy chạy openclaw gateway restart.
6. Mở phiên mới bằng /new — phiên hiện có vẫn giữ mô hình đã dùng — gửi hai tin nhắn, rồi đọc /usage tokens: lượt thứ hai dự kiến sẽ báo cacheRead.

Đã kiểm tra đối chiếu với Tài liệu tham khảo về nhà cung cấp tùy chỉnh của OpenClaw vào 5 tháng 10, 2026. Cài đặt của bên thứ ba có thể thay đổi; nếu tên trường ở đây không còn khớp với những gì bạn thấy, trang đó là nguồn có thẩm quyền, không phải trang này.

Xác minh trước khi gỡ lỗi ứng dụng khách

Một yêu cầu sẽ xác định liệu lỗi nằm ở endpoint, khóa hay tệp cấu hình. Nếu lệnh này trả về JSON, cùng base URL và khóa sẽ hoạt động trong OpenClaw.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Đặt model id nào vào trường

Mọi mô hình văn bản đều có thể truy cập bằng model id — danh sách đang hoạt động là GET /v1/models, còn danh mục kèm giá nằm trên trang mô hình. Mức giá tính bằng USD trên mỗi 1M token, đầu vào / đầu ra.

Giao thức tương thích OpenAI

Cùng một khóa có thể kết nối với mọi họ mô hình khác thông qua /v1/chat/completions. Hãy đăng ký khóa đó thành mục nhà cung cấp thứ hai để tách biệt hai giao thức, rồi tham chiếu các mô hình bằng kunavo-openai/<id>:

// ~/.openclaw/openclaw.json — a second entry, beside "kunavo"
{
  models: {
    providers: {
      "kunavo-openai": {
        baseUrl: "https://api.kunavo.com/v1",   // this wire keeps /v1
        apiKey: "${KUNAVO_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol",
            reasoning: true,
            input: ["text"],
            contextWindow: 1050000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

// then: /model kunavo-openai/gpt-6-sol

Có ba điểm khác với khối ở đầu trang. URL cơ sở giữ /v1 theo định dạng trong các ví dụ nhà cung cấp tùy chỉnh của chính OpenClaw. api là openai-completions — đây cũng là giá trị OpenClaw mặc định giả định khi nhà cung cấp tùy chỉnh có baseUrl nhưng không có api. Và trên thực tế, maxTokens không còn là tùy chọn: khi không biết giới hạn đầu ra của mô hình, OpenClaw hoàn toàn không gửi giới hạn trên giao thức này, và khi đó Kunavo sẽ kết thúc câu trả lời Claude ở mức 4.096 token.

Mã định danh Claude cũng hoạt động trên giao thức này; đây là giao thức nên dùng nếu bạn muốn một mục cấu hình cho mọi thứ. Có hai điểm thay đổi với Claude: cấp độ suy luận không được chuyển tiếp qua chat completions, và Kunavo đặt các điểm đánh dấu bộ nhớ đệm thay cho OpenClaw.

Bộ nhớ đệm lời nhắc trên từng giao thức

Trên giao thức Anthropic, OpenClaw tự đặt các điểm đánh dấu bộ nhớ đệm, nhưng đối với điểm cuối tùy chỉnh, OpenClaw chỉ làm vậy khi cacheRetention được thiết lập. Tài liệu tham khảo về bộ nhớ đệm lời nhắc nêu rõ điều này: giá trị mặc định short chỉ được thiết lập sẵn cho các nhà cung cấp anthropic và anthropic-vertex, còn mọi tuyến khác thuộc họ Anthropic cần có giá trị tường minh. /v1/messages của Kunavo chuyển tiếp nội dung yêu cầu đúng như được gửi đến và không thêm điểm đánh dấu nào, nên cấu hình thiếu các dòng đó sẽ không lưu gì vào bộ nhớ đệm.

short yêu cầu mục nhập năm phút, còn long yêu cầu mục nhập một giờ. Kunavo chuyển tiếp cả hai dấu mốc và tính phí ghi theo cùng mức giá. Trước khi lập lịch dựa trên mục nhập một giờ, bạn nên xác nhận qua dữ liệu sử dụng của chính mình xem mục nhập đó còn tồn tại khi nhịp tim tiếp theo đến hay không: lượt báo cacheRead đã giữ được bộ nhớ đệm, còn lượt lại báo cacheWrite thì không. /usage tokens và /status hiển thị cả hai bộ đếm.

Trên giao thức tương thích OpenAI thì ngược lại. OpenClaw không gửi gợi ý bộ nhớ đệm đến điểm cuối proxy, còn Kunavo tự đặt các điểm đánh dấu cho mô hình Claude — trên lời nhắc hệ thống, định nghĩa công cụ và cuối cuộc trò chuyện — khi lời nhắc đủ dài để lưu vào bộ nhớ đệm. Không cần thiết lập gì; nhà cung cấp tự động lưu bộ nhớ đệm cho mô hình GPT.

Dù bên nào đặt các điểm đánh dấu, hóa đơn vẫn như nhau. Với Claude Sonnet 5, một lần đọc bộ nhớ đệm có giá $0.14 cho mỗi 1M token, so với $1.40 cho đầu vào mới; một lần ghi bộ nhớ đệm có giá $1.75 — mức phụ phí ghi mà Claude tính thêm trên đầu vào, được tính theo cùng mức đó khi mục nhập yêu cầu thời hạn một giờ. Mỗi mục nhập tồn tại năm phút và mỗi lần đọc sẽ làm mới thời hạn, vì vậy chi phí của tác nhân phụ thuộc ít hơn vào mô hình và phụ thuộc nhiều hơn vào việc yêu cầu tiếp theo có đến trong khoảng thời gian đó hay không. Xem mức giá bộ nhớ đệm của từng mô hình trên trang bộ nhớ đệm lời nhắc.

OpenClaw có thể hiển thị phép tính tương tự ngay trên máy của bạn. Bản tóm tắt /usage cost và dòng chi phí trong /status cần có đối tượng cost trên mỗi dòng mô hình; nếu thiếu, chúng sẽ hiển thị bằng không dù Kunavo vẫn tính phí như thường. Các dòng này được tạo từ danh mục đang hoạt động:

// merge into the rows of models.providers.kunavo.models — USD per 1M tokens
{ id: "claude-sonnet-5", cost: { input: 1.4, output: 7, cacheRead: 0.14, cacheWrite: 1.75 } },
{ id: "claude-haiku-4-5", cost: { input: 0.7, output: 3.5, cacheRead: 0.07, cacheWrite: 0.875 } },
{ id: "claude-opus-5-5", cost: { input: 2.8, output: 14, cacheRead: 0.14, cacheWrite: 3.5 } },
{ id: "claude-fable-5", cost: { input: 7, output: 35, cacheRead: 0.7, cacheWrite: 8.75 } },

Chi phí mỗi ngày của tác nhân luôn hoạt động

Tác tử OpenClaw vẫn phát sinh phí khi không có ai trò chuyện với nó, do heartbeat: một lượt hoạt động của tác tử được lên lịch chạy mặc định mỗi 30 phút, tức 48 lượt mỗi ngày. Nếu không được chỉ định khác, lượt này chạy trong phiên chính và gửi lại cuộc hội thoại — tài liệu tham khảo của OpenClaw ước tính một lượt như vậy sử dụng khoảng 100.000 token, và còn vài nghìn token khi được chạy tách biệt. Ba mươi phút dài hơn thời gian lưu bộ nhớ đệm năm phút, nên mỗi lượt chạy lại tính phí toàn bộ prompt: theo đơn giá đầu vào, hoặc theo đơn giá ghi cao hơn tại vị trí đặt điểm ngắt. Bảng tính chi phí cho một ngày không có tương tác theo đơn giá đầu vào, với 5.000 token cho lượt chạy tách biệt:

Khối cấu hình dưới đây là một phương án ít tốn kém trong bảng: heartbeat trên Haiku, trong một phiên tách biệt, không có các tệp khởi tạo workspace và chỉ chạy trong giờ thức. Mọi cài đặt trong đó đều lấy từ tài liệu tham khảo heartbeat của OpenClaw. Tăng khoảng thời gian every là một cách điều chỉnh khác, còn "0m" sẽ tắt lượt chạy định kỳ.

// ~/.openclaw/openclaw.json — what decides the cost of an idle day
{
  agents: {
    defaults: {
      utilityModel: "kunavo/claude-haiku-4-5",   // titles and other short internal tasks
      heartbeat: {
        every: "30m",                            // the default with an API key
        model: "kunavo/claude-haiku-4-5",        // wake-ups on the cheapest tier
        isolatedSession: true,                   // a fresh session, not the whole conversation
        lightContext: true,                      // skip the workspace bootstrap files
        activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

Số giờ tác nhân thực sự hoạt động là nửa còn lại của hóa đơn, và ở đó bộ nhớ đệm quyết định chi phí. Xét 100 yêu cầu liên tiếp, mỗi yêu cầu gửi lại ngữ cảnh 100.000 token, kèm thêm 2.000 token mới và trả về 800 token đầu ra. Với Claude Sonnet 5, chi phí khoảng $2.31 khi ngữ cảnh được đọc từ bộ nhớ đệm, và khoảng $14.84 khi ngữ cảnh đó được tính phí như đầu vào mới trong mỗi yêu cầu. Cùng một khối lượng công việc, cùng một mô hình: khác biệt nằm ở việc có đặt các điểm ngắt hay không và các yêu cầu cách nhau dưới năm phút.

Để có cơ sở so sánh, đây là số liệu đo được chứ không phải giả định: trong các tài khoản Kunavo chạy agent luôn hoạt động, một ngày hoạt động ở mức trung vị có chi phí $12.67, còn một ngày ở phân vị thứ 90 có chi phí khoảng $163. Đây là các khoản được tính phí tính đến 5 tháng 10, 2026, theo mức giá có hiệu lực trong từng ngày. Nhóm này nhỏ, vì vậy hãy xem số liệu như độ rộng của khoảng giá trị, không phải dự báo cho agent của bạn.

Khi số dư cạn

Kunavo dùng hình thức trả trước: mọi lệnh gọi đều được thanh toán từ ví, và một agent hoạt động khi bạn ngủ sẽ làm cạn ví trong lúc bạn ngủ. Yêu cầu mà số dư ví không đủ chi trả sẽ bị từ chối với HTTP 402 và mã insufficient_balance trên cả hai giao thức; yêu cầu đó không bị tính phí. Việc từ chối xảy ra trước khi số dư ví về không: mỗi yêu cầu trước tiên tạm giữ một khoản bằng chi phí tối đa có thể phát sinh, gồm prompt cộng với câu trả lời dài nhất được phép tạo ra. Vì vậy, giới hạn đầu ra agent yêu cầu càng cao thì các lệnh gọi càng sớm bắt đầu bị từ chối. Lỗi cho biết số tiền còn thiếu qua balance_usd và needed_usd.

OpenClaw xác định ý nghĩa của mã 402 dựa trên thông báo đi kèm. Theo các quy tắc trong OpenClaw 2026.9.8, việc từ chối do ví được xem là lỗi thanh toán, và tài liệu tham khảo về chuyển đổi dự phòng của OpenClaw mô tả diễn biến tiếp theo: thông tin xác thực bị vô hiệu hóa trong mười phút, lượt chạy chuyển sang mô hình tiếp theo trong agents.defaults.model.fallbacks, và việc nạp tiền không xóa khoảng thời gian này — vì vậy, sau khi nạp thêm, tác tử có thể vẫn không sử dụng kunavo/… cho đến khi khoảng thời gian đó kết thúc. Việc từ chối do hạn mức hằng tháng của khóa được diễn giải khác. Thông báo của nó nêu một hạn mức sẽ được đặt lại, điều mà cùng bộ quy tắc đó xem là giới hạn tốc độ: OpenClaw thử lại, sau đó tạm ngưng sử dụng thông tin xác thực trong 30 giây lúc đầu và tối đa năm phút. openclaw models status liệt kê thông tin xác thực bị vô hiệu hóa và thời điểm khôi phục.

Có hai thiết lập liên quan đến việc này, và mỗi thiết lập đảm nhiệm một việc khác nhau:

• Tự động nạp, trong Thanh toán. Lưu thẻ một lần và thiết lập ba con số: ngưỡng số dư để nạp thêm, số tiền nạp mỗi lần và hạn mức hàng tháng. Sau đó, ví sẽ được nạp lại trong vòng vài giây sau một lệnh gọi khiến số dư ở dưới ngưỡng, miễn là lần nạp không bị các giới hạn nạp tiền chặn lại; các giới hạn này gồm có hạn mức trừ tiền hàng tháng mà bạn đặt, số lần trừ tiền thẻ tối đa mỗi ngày, một khoảng chờ ngắn trước lần nạp tiếp theo và một khoảng chờ dài hơn sau một lần trừ tiền thẻ bị từ chối. Khi số dư ví không đủ cho một yêu cầu, Kunavo sẽ nạp tiền với cùng ngưỡng và cùng các giới hạn đó rồi thử lại yêu cầu thêm một lần trước khi phản hồi; nếu đang có một lần nạp diễn ra, yêu cầu sẽ chờ lần nạp đó trong vài giây. 402 vẫn được trả về khi không có lần nạp nào được thực hiện (ví dụ thẻ bị từ chối, đã chạm một giới hạn, hoặc số dư không thấp hơn ngưỡng), khi lần nạp đang diễn ra chưa vào ví trong vài giây đó, hoặc khi sau lần nạp, số dư ví vẫn không đủ cho khoản cần tạm giữ cho yêu cầu. Số dư được so với ngưỡng là số dư trước khi trừ đi các khoản đang được tạm giữ cho những yêu cầu và tác vụ đang chạy, vì vậy khi số dư không thấp hơn ngưỡng thì sẽ không có lần nạp nào, kể cả khi, sau khi trừ các khoản tạm giữ đó, phần còn lại không đủ cho yêu cầu tiếp theo. Cần có thẻ hoặc Link — không thể tự động tính phí qua Alipay, WeChat Pay, Pix và các phương thức thanh toán địa phương khác.
• Giới hạn hàng tháng cho khóa, trong Khóa API. Cấp cho tác nhân một khóa riêng và đặt mức chi tiêu tối đa mà khóa đó được phép sử dụng trong một tháng dương lịch. Khi vượt quá mức này, các lệnh gọi của khóa sẽ bị từ chối với 402 và không phát sinh khoản phí nào, trong khi các khóa khác của bạn vẫn hoạt động. Đây là mức trần cần thiết để ngăn vòng lặp chạy mất kiểm soát, điều mà ví không thể cung cấp vì mọi khóa đều dùng chung một ví.

Đặt ngưỡng nạp tiền cao hơn khoản tiền một yêu cầu tạm giữ, và chọn số tiền nạp dựa trên chi phí một ngày hoạt động của tác nhân, thay vì chọn mức tối thiểu: lần nạp nhỏ nhất là $10, còn chi phí trung vị cho một ngày hoạt động liên tục ở trên là $12.67. Các giới hạn của tính năng nạp tiền tự động được nêu trên trang thanh toán, còn toàn bộ nội dung lỗi có trên trang lỗi.

Hướng dẫn liên quan

• API tốt nhất cho OpenClaw — chọn nhà cung cấp và mô hình cho từng loại tác vụ.
• Chi phí OpenClaw — toàn bộ chi phí vận hành: phần mềm, dịch vụ lưu trữ, mô hình và công cụ.
• Dùng OpenClaw với nhiều tác nhân và mô hình — định tuyến từng tác nhân đến mô hình riêng và phân bổ chi phí theo tuyến.
• So sánh Hermes với OpenClaw — cùng cách thiết lập cho tác nhân còn lại trên trang Hermes Agent.