OpenClaw

~/.openclaw/openclaw.json の models.providers エントリーを1つ設定し、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. ゲートウェイにキーを設定します。KUNAVO_API_KEY=sk-kn-...を~/.openclaw/.envに追加するか、ゲートウェイの起動時に使う環境でエクスポートします。設定の読み込み時に、ブロック内の${KUNAVO_API_KEY}がその値に置き換えられます。
3. ブロックを~/.openclaw/openclaw.jsonに統合し、既存のproviders、agents、channelsはそのまま残します。このファイルはJSON5形式なので、コメントもそのまま残せます。
4. openclaw config validateを実行してください。設定ファイルに認識できない項目があるとOpenClawは起動を拒否するため、タイプミスは次回の再起動時ではなく、ここで見つけるのが適切です。
5. openclaw models list --provider kunavoを実行し、両方のIDが一覧に表示されることを確認します。実行中のゲートウェイに変更が反映されていない場合は、openclaw gateway restartを実行してください。
6. /newで新しいセッションを開始します。既存のセッションでは、それまで使っていたモデルが維持されます。メッセージを2件送ってから/usage tokensを確認してください。2ターン目にはcacheReadが表示されるはずです。

OpenClawのカスタムプロバイダーに関するリファレンスで2026年10月5日に確認しました。サードパーティの設定は変更されます。ここに記載されたフィールド名が表示内容と一致しなくなった場合は、このページではなく、そのページを正しい情報源としてください。

クライアントをデバッグする前に確認すること

1回のリクエストで、失敗の原因がエンドポイント、キー、設定ファイルのどれかを特定できます。これが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、価格付きのカタログはモデルページにあります。料金は100万トークンあたりのUSDで、入力 / 出力の順です。

OpenAI互換の通信方式

同じキーを使って、/v1/chat/completions経由で他のすべてのモデルファミリーにも接続できます。2つの通信方式を分けておくため、2つ目のプロバイダーエントリーとして登録し、そのモデルは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

上部のブロックとは3点異なります。ベースURLには、OpenClaw自身のカスタムプロバイダーの例と同じ/v1を付けます。apiはopenai-completionsです。これは、カスタムプロバイダーにbaseUrlがあり、apiがない場合にOpenClawがデフォルトで使う形式でもあります。また、実際にはmaxTokensは必須です。モデルの出力上限が不明な場合、この通信方式ではOpenClawは上限を送信しません。その場合、KunavoはClaudeの返信を4,096トークンで打ち切ります。

ClaudeのIDもこの通信方式で使えます。すべてのモデルを1つのエントリーにまとめたい場合は、この通信方式を使用してください。Claudeで変わる点は2つあります。chat completionsではthinkingレベルが転送されず、キャッシュのブレークポイントはOpenClawではなくKunavoが配置します。

各通信方式でのプロンプトキャッシュ

Anthropicの通信方式ではOpenClawがキャッシュのブレークポイントを配置しますが、カスタムエンドポイントの場合はcacheRetentionが設定されている場合に限ります。プロンプトキャッシュのリファレンスでは明確に説明されており、shortのデフォルト値が設定されるのはanthropicとanthropic-vertexプロバイダーのみです。それ以外のAnthropicファミリーのルートでは、明示的な値が必要です。Kunavoの/v1/messagesは送信された本文をそのまま転送し、ブレークポイントを追加しません。そのため、これらの行がない設定では何もキャッシュされません。

shortは5分間のエントリー、longは1時間のエントリーを指定します。Kunavoはどちらのマーカーも転送し、書き込みには同じレートを適用します。次のハートビート時に1時間のエントリーが残っているかどうかは、実際の利用状況で確認してから実行間隔を決めてください。cacheReadと表示されたターンではキャッシュが維持され、再びcacheWriteと表示されたターンでは維持されなかったことがわかります。/usage tokensと/statusで両方のカウンターを確認できます。

OpenAI互換の通信方式では、逆の仕組みです。OpenClawはプロキシエンドポイントにキャッシュヒントを送信しません。KunavoがClaudeモデルのブレークポイントを配置します。プロンプトがキャッシュ可能な長さになると、システムプロンプト、ツール定義、会話の末尾に配置されます。設定は不要です。GPTモデルはベンダーによって暗黙的にキャッシュされます。

ブレークポイントをどちら側が配置しても、請求額は同じです。Claude Sonnet 5では、100万トークンあたりのキャッシュ読み取り料金は$0.14で、新規入力料金は$1.40、キャッシュ書き込み料金は$1.75です。この書き込み料金は Claude の入力料金より割高で、エントリーの有効期間を1時間にした場合も同じレートで課金されます。エントリーの有効期間は5分で、読み取りのたびに更新されます。そのため、エージェントの支払額はモデルよりも、次のリクエストがその期間内に届くかどうかに左右されます。各モデルのキャッシュ料金はプロンプトキャッシュのページをご覧ください。

OpenClawでは同じ計算結果をローカルで表示できます。/usage costの概要と/statusの費用欄で費用を計算するには、各モデル行にcostオブジェクトが必要です。指定がない場合はどちらも0と表示されますが、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 } },

常時稼働エージェントの1日あたりの費用

OpenClawのエージェントは、誰も会話していない間もハートビートによって課金されます。ハートビートとは、デフォルトで30分ごとに実行される定期的なエージェントターンで、1日に48回実行されます。別途指定しない限り、これはメインセッションで実行され、会話内容が再送されます。OpenClawのリファレンスによると、このような実行では約100,000トークンが使われ、分離した場合は数千トークンになります。30分はキャッシュの有効時間である5分より長いため、実行のたびにプロンプト全体が再度請求されます。入力料金、またはブレークポイントが設定されている場合はそれより高い書き込み料金が適用されます。次の表では、分離した実行に5,000トークンを使用する場合の、入力料金で計算したアイドル状態の1日分の費用を示します。

以下の設定は、この表の中でも費用を抑えた条件にあたります。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トークンのコンテキストを再送し、その上に2,000個の新しいトークンを追加して、800トークンの出力を受け取るとします。Claude Sonnet 5では、コンテキストがキャッシュから読み込まれる場合は約$2.31、各リクエストで新しい入力として請求される場合は約$14.84です。同じ処理、同じモデルでも、ブレークポイントが設定されているか、そしてリクエストの間隔が5分未満かどうかで差が生じます。

規模感を示すため、推定ではなく実測値を紹介します。常時稼働エージェントを実行しているKunavoアカウント全体では、稼働日のコスト中央値は$12.67、90パーセンタイルの日は約$163です。これらは2026年10月5日までに、その日の適用料金で請求された金額です。対象は少数のグループなので、ご自身のエージェントの予測値ではなく、金額の幅の参考としてご覧ください。

残高がなくなった場合

Kunavoはプリペイド方式です。すべての呼び出しはウォレットから支払われるため、あなたが眠っている間も稼働するエージェントは、その間にウォレット残高を使い切ります。ウォレットで支払えないリクエストは、どちらの通信方式でもHTTP 402とコードinsufficient_balanceを返して拒否され、料金は発生しません。残高がゼロになる前に拒否が起こるのは、各リクエストの処理前に、プロンプトと許可される最大応答量を合わせた最悪ケースの費用が確保されるためです。そのため、エージェントが要求する出力上限が大きいほど、呼び出しは早く拒否され始めます。エラーには、不足額がbalance_usdとneeded_usdで示されます。

OpenClawは、エラーのメッセージに基づいて402の意味を判断します。OpenClaw 2026.9.8のルールでは、ウォレットによる拒否は課金エラーとして扱われ、その後の動作はフェイルオーバーのリファレンスに記載されています。認証情報は10分間無効になり、実行はagents.defaults.model.fallbacksにある次のモデルに移ります。再チャージしても無効期間は解除されないため、期間が終了するまでエージェントはkunavo/…で実行できないことがあります。キーの月間上限による拒否は別の方法で解釈されます。メッセージにはリセットされる上限が記載されており、同じルールではレート制限として扱われます。OpenClawは再試行した後、認証情報を最初は30秒間、最長で5分間クールダウンします。openclaw models statusでは、無効になった認証情報とその復旧時期を確認できます。

エージェントを無人稼働させる際に、この状態を防ぐ設定が2つあります。それぞれ役割が異なります。

• 自動チャージ、請求で設定します。カードを一度登録し、3つの数値を設定します。補充を開始する残高のしきい値、1回あたりの補充額、月間上限です。これにより、利用によって残高がしきい値を下回ると、数秒以内にウォレットが補充されます。ウォレットの残高が不足している間に届いたリクエストは、その請求が完了するまで待機し、その後、拒否されずに処理されます。請求を実行できない場合（カードが拒否された場合や月間上限に達した場合）、または1件のリクエストで補充後のウォレット残高を超える金額が予約される場合は、402が返されます。自動課金にはカードまたはLinkが必要です。Alipay、WeChat Pay、Pixなどの現地決済方法は自動課金できません。
• キーごとの月間上限をAPI キーで設定します。エージェント専用のキーを発行し、そのキーが暦月内に使用できる金額の上限を設定します。上限を超えると、そのキーからの呼び出しは402で拒否され、課金は発生しません。他のキーは引き続き利用できます。これにより、制御不能なループによる支出を制限できます。すべてのキーが同じウォレットを利用するため、ウォレットではこの制限を設定できません。

チャージのしきい値は、1回のリクエストで確保される金額より高く設定してください。チャージ額は最低額ではなく、エージェントの1日分の費用を目安に決めます。最小チャージ額は$10で、上記の常時稼働エージェントの1日あたりの費用の中央値は$12.67です。自動チャージの制限は請求ページ、エラーの全内容はエラーページをご覧ください。

関連ガイド

• OpenClawに最適なAPI — タスクごとにプロバイダーとモデルを選ぶ方法。
• OpenClawの料金 — ソフトウェア、ホスティング、モデル、ツールを含む運用費用の全体。
• 複数のエージェントとモデルを使うOpenClaw — 各エージェントを専用モデルに振り分け、ルートごとに費用を把握する方法。
• HermesとOpenClawの比較 — もう一方のエージェントで同じ設定を行う方法は、Hermes Agentのページをご覧ください。