OpenClaw

在 ~/.openclaw/openclaw.json 中新增一筆 models.providers 設定，指定 baseUrl https://api.kunavo.com、api "anthropic-messages"，即可讓常駐執行的 OpenClaw 代理使用 Claude；並在旁設定 cacheRetention，因為自訂 Anthropic 端點在設定此參數之前，不會收到任何快取標記。

// ~/.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" } },
      },
    },
  },
}

逐步操作

1. 在 /app/keys 建立金鑰並複製——金鑰只會顯示一次。
2. 將金鑰提供給 Gateway：把 KUNAVO_API_KEY=sk-kn-... 加入 ~/.openclaw/.env，或在啟動 Gateway 的環境中匯出該變數。載入設定時，區塊中的 ${KUNAVO_API_KEY} 會替換為該環境變數的值。
3. 將此區塊合併至 ~/.openclaw/openclaw.json，並保留您現有的 providers、agents 和 channels。此檔案採用 JSON5 格式，因此註解可以保留。
4. 執行 openclaw config validate。如果檔案中有 OpenClaw 不認得的設定，OpenClaw 就會拒絕啟動；因此最好在這裡發現拼字錯誤，而不是等到下次重新啟動時才發現。
5. 執行 openclaw models list --provider kunavo，確認兩個 ID 都列在清單中。若執行中的 Gateway 尚未套用變更，請執行 openclaw gateway restart。
6. 使用 /new 開啟新的工作階段；現有工作階段會繼續使用原本的模型。傳送兩則訊息後，查看 /usage tokens：第二輪應會顯示 cacheRead。

已於 2026年10月5日 根據 OpenClaw 自訂供應商參考資料 進行確認。第三方設定會變動；如果這裡的欄位名稱不再與你看到的內容相符，應以該頁面為準，而不是本頁。

除錯用戶端前先驗證

一個請求就能判斷失敗原因是端點、金鑰還是設定檔。如果這裡回傳 JSON，則相同的基礎 URL 與金鑰在 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"}]}'

欄位中應填入哪個模型 ID

每個文字模型都能以模型 ID 存取——即時清單位於 GET /v1/models，帶有價格的目錄位於模型頁面。費率是每 1M 權杖的美元價格，輸入／輸出。

OpenAI 相容通訊協定

同一把金鑰也可透過 /v1/chat/completions 連接其他所有模型系列。請將它登錄為第二筆供應商設定，讓兩種通訊協定保持分開，並以 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

相較於上方區塊，這裡有三項不同之處。base URL 保留 /v1，這是 OpenClaw 自訂供應商範例所用的格式。api 為 openai-completions；當自訂供應商提供 baseUrl 而未提供 api 時，OpenClaw 也會採用此預設值。實際使用時，maxTokens 也不再是選填設定：若模型的輸出上限未知，OpenClaw 在此通訊協定上完全不會傳送上限，Kunavo 因而會在 4,096 個 token 時結束 Claude 回覆。

此處也可使用 Claude ID；若您希望用一筆設定涵蓋所有模型，請使用此通訊協定。使用 Claude 時有兩點不同：在聊天補全介面上不會轉送思考層級，快取斷點則由 Kunavo 設定，而非 OpenClaw。

各通訊協定的提示快取

在 Anthropic 通訊協定上，OpenClaw 會自行設定快取斷點，但自訂端點只有在設定 cacheRetention 時才會如此。OpenClaw 的提示快取參考資料對此說明得很明確：僅 anthropic 和 anthropic-vertex 供應商會預設使用 short，其他所有 Anthropic 系列路由都需要明確指定值。Kunavo 的 /v1/messages 會依原樣轉送主體內容，不會新增斷點，因此若設定中沒有這些行，就不會快取任何內容。

short 要求建立五分鐘的快取項目，long 則要求建立一小時的快取項目。Kunavo 會轉送任一標記，並以相同費率計收寫入費用。在據此規劃心跳頻率之前，建議先根據自己的使用紀錄確認一小時的快取項目在下一次心跳到達時是否仍然存在：若某輪回報 cacheRead，代表快取仍然保留；若再次回報 cacheWrite，則代表快取未能保留。/usage tokens 和 /status 都會顯示這兩項計數。

在 OpenAI 相容通訊協定上，情況正好相反。OpenClaw 不會向代理端點傳送快取提示，而 Kunavo 會在提示詞足夠長、可進行快取時，自行為 Claude 模型設定斷點，位置包括系統提示詞、工具定義和對話結尾。無須進行任何設定；GPT 模型則由其供應商以隱式方式快取。

無論由哪一端設定快取斷點，費用計算方式都相同。在 Claude Sonnet 5 上，快取讀取費率為每 1M 個 token $0.14，新輸入則為 $1.40；快取寫入費率為 $1.75，也就是 Claude 在輸入費率上加收的寫入溢價；若項目要求快取保留一小時，仍按相同費率計費。快取項目保留五分鐘，每次讀取都會續期，因此代理的費用與模型的關聯較小，主要取決於下一次請求是否在這段期間內送達。各模型的快取費率請見提示快取頁面。

OpenClaw 也能在本機顯示相同的費用計算結果。其 /usage cost 摘要與 /status 中的費用行都需要在每個模型項目中設定 cost 物件；若未設定，顯示值會是零，但 Kunavo 仍會照常計費。這些項目是根據即時目錄產生的：

// 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 } },

常駐代理程式的每日費用

OpenClaw 代理即使在沒有人與它對話時也會產生費用，原因是心跳：代理會依排程執行一輪，預設每 30 分鐘一次，也就是每天 48 次。若未另行指定，它會在主要工作階段中執行並重新傳送對話內容；OpenClaw 的參考資料指出，這類執行約需 100,000 個 token，而改用隔離工作階段後則會減少至數千個 token。30 分鐘超過五分鐘的快取時效，因此每次執行都會再次對整份提示詞計費：依輸入費率計價，或在設有斷點的部分依較高的寫入費率計價。下表依輸入費率計算閒置一天的費用，並假設隔離執行使用 5,000 個 token：

下方區塊列出該表中成本較低的情境：使用 Haiku，在隔離工作階段中執行心跳，不載入工作區啟動檔案，且只在清醒時段執行。區塊中的每項設定都取自 OpenClaw 的心跳參考資料。將 every 設得更長是另一種調整方式，而 "0m" 則會關閉定期執行。

// ~/.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" },
      },
    },
  },
}

代理實際運作時數是帳單的另一半，而這部分由快取決定。連續發出 100 個請求，每次都重新傳送包含 100,000 個 token 的上下文，並額外加入 2,000 個新 token，且回傳 800 個輸出 token。在 Claude Sonnet 5，上下文從快取讀取時，費用約為 $2.31；若每個請求都將其計為全新輸入，費用則約為 $14.84。工作相同，模型相同；差別在於是否設有斷點，以及請求間隔是否少於五分鐘。

以實際測量值說明規模，而非推測：在 Kunavo 使用常駐代理程式的帳戶中，活躍日的費用中位數為 $12.67，第 90 百分位數的活躍日費用約為 $163。這些金額是截至 2026年10月5日 已計費的費用，採用各日當時適用的費率。樣本群體不大，因此請將這些數字視為範圍的寬度，而非對你的代理程式的預測。

餘額用盡時

Kunavo 採預付制：每次呼叫都從錢包扣款，而在您睡覺時持續工作的代理也會在您睡覺時耗盡錢包餘額。若錢包餘額不足以負擔某個請求，該請求會在任一通訊協定上以 HTTP 402 和代碼 insufficient_balance 遭拒，且不會收取任何費用。拒絕發生在錢包餘額歸零之前：每個請求都會先預留其最壞情況下的費用，也就是提示內容加上允許產生的最大回覆，因此代理要求的輸出上限越高，其請求就越早開始遭拒。錯誤訊息會以 balance_usd 和 needed_usd 說明餘額不足的金額。

OpenClaw 會根據 402 錯誤訊息判斷其代表的狀況。依照OpenClaw 2026.9.8 的規則，錢包餘額不足的拒絕屬於計費失敗，而其備援切換參考資料說明後續處理方式：憑證會停用十分鐘，執行會切換至 agents.defaults.model.fallbacks 中的下一個模型，而且重新儲值不會清除這段停用期間，因此儲值後，代理仍可能要等到停用期間結束才會重新使用 kunavo/…。金鑰的每月上限所造成的拒絕則會以不同方式處理。錯誤訊息會指出一項會重設的上限；依照同一套規則，這會被視為速率限制：OpenClaw 會重試，然後讓憑證進入冷卻，初始為 30 秒，最長為五分鐘。openclaw models status會列出已停用的憑證及其恢復時間。

有兩項設定可避免無人值守的代理程式陷入這種狀況，兩者用途不同：

• 自動儲值，位於 儲值與帳單。儲存一張卡片，並設定三個數值：低於多少餘額時要儲值、每次要加多少，以及每月上限。之後，只要某次呼叫使餘額低於門檻，錢包就會在幾秒內自動補足。錢包餘額不足時送達的請求會等待該筆扣款完成，接著獲得處理，而非遭到拒絕。若無法扣款（例如卡片遭拒或已達每月上限），或單一請求預留的金額超過儲值後錢包持有的餘額，仍會回傳 402。此功能需要使用付款卡或 Link；Alipay、WeChat Pay、Pix 和其他當地付款方式無法用於自動扣款。
• API 金鑰的每月支出上限，位於 API 金鑰。為代理程式建立專屬金鑰，並設定該金鑰在一個日曆月內可支出的最高金額。超過此金額後，該金鑰發出的呼叫會以 402 遭拒，且不會扣款；其他金鑰則不受影響，仍可正常使用。這能為失控的迴圈設下支出上限，而錢包無法做到這一點，因為所有金鑰共用同一個錢包。

設定自動儲值門檻時，請高於單次請求的預留金額；設定儲值金額時，請以代理程式一天的費用為基準，而非最低金額：最低儲值金額為 $10，上文所列常駐代理程式的每日費用中位數為 $12.67。自動儲值的限制請見帳單頁面，完整錯誤主體請見錯誤頁面。

相關指南

• OpenClaw 最佳 API — 為各種任務選擇供應商和模型。
• OpenClaw 費用 — 完整營運費用：軟體、代管、模型和工具。
• OpenClaw 搭配多個代理和模型 — 將各代理路由至各自的模型，並按路由歸屬費用。
• Hermes 與 OpenClaw 比較 — 另一個代理的相同設定則請見Hermes Agent 頁面。