IronClawのカスタムAPI設定：プロバイダー、キー、プライバシー境界

IronClawでは、カスタムAPIを4フィールドの1つのブロックで指定します。~/.ironclaw/reborn/config.toml内の[llm.default]スロットにprovider_id、base_url、model、api_key_envを設定します。スロットがない場合は、フォールバックするLLM_BACKEND / LLM_BASE_URL / LLM_API_KEY環境変数を使用します。 どちらの形式も現行の文書化された方法です。ただし、設定ページが一か所にまとめていないのは、カスタムエンドポイントでは利用できない機能の一覧です。ネイティブストリーミング、モデル検出、Anthropicのcache_controlブレークポイント、正確なコスト表示などが該当します。プロバイダーを選ぶ前に読む価値があるのは、この一覧です。

まず、検索結果が他の製品に大きく占有されているため、対象を明確にします。このページが扱うのはgithub.com/nearai/ironclawです。リポジトリ自身のメタデータでは「IronClawはプライバシー、セキュリティ、拡張性を重視したAgent OS」と説明されています。Rust製で、アーカイブ済みでもフォークでもなく、スター数は12,626、作成日は2026年2月3日、最終プッシュは2026年9月21日です（同日のGitHub API）。同名のCorsair製ゲーミングマウス、Sanguine ProductionsのテーブルトップRPG、IRONCLAW暗号トークン、無関係なJoasASantos/ironclawリポジトリとは別物です。これらの価格や設定は、このページに持ち込むべきではありません。正式なドキュメントはdocs.ironclaw.comと、リポジトリ自身のdocs/ツリーです。同じタイトルで検索順位を得ている第三者のMintlifyミラーは、古い可能性があります。

帰属については、ベンダー自身の各ページで表現が異なるため、言い換えずに引用する価値があります。ironclaw.comでは、NEARのロゴの横に「Built by」と表示され、本文には「Near Foundation」と記載され、フッターには「— by NEAR AI」とあります。一方、GitHub組織はnearaiです。

IronClawの最小カスタムプロバイダー設定

ironclaw_configのスロット構造体は、正確に4つのオプションフィールドを受け付けます。構造体自身のドキュメントコメントでは、これらをカタログエントリの上書きとして説明しています。modelはプロバイダーのdefault_modelを上書きし、api_key_envはapi_key_envを上書きし、base_urlはdefault_base_urlを上書きします。プロバイダードキュメントには、base_urlは「プロキシまたはリージョナルエンドポイント経由でルーティングする必要がある場合、他のどのプロバイダーでも機能する」とも記載されています。したがって、これは汎用アダプターだけの機能ではありません。

[llm.default]
provider_id = "openai_compatible"
base_url    = "https://api.kunavo.com/v1"
model       = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"

重要なルールは3つあります。base_urlを省略すると致命的で、デフォルト値にはなりません。ドキュメントには「スロットがどこも指さない状態になり、モデル解決に失敗する」とあり、openai_compatibleのカタログエントリにはbase_url_required: trueが設定されています。api_key_envにはキーではなく変数名を指定します。貼り付けたシークレットは「黙って受け入れられるのではなく、解析時に拒否」され、ironclaw config set <provider>.api_keyは入力を非表示にして尋ねます。再起動するまで何も反映されません。config setは「何も再起動せず」、必要なironclaw service restart手順を表示するだけです。また、config setがスロットを書き込んでくれるとは考えないでください。設定ページでは[llm.default]を「config.tomlで直接編集」するセクションの1つとして挙げ、config setは「未対応のキーを黙って無視せず拒否する」と説明しています。

環境変数形式は、[llm.default]がない場合の文書化されたフォールバックです。ドキュメントでは選択肢を明確に示しています。「どちらも機能します……恒久的なインストールにはTOMLスロットを、単発実行とコンテナには環境変数形式を推奨します。」

export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6

# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120

解決順序はcompiled defaults < config.toml < environment variables < CLI flagsです。そのため、エクスポート済みの変数は、編集したばかりのファイルよりも静かに優先されます。CLI経由なら手作業で編集する必要はありません。ironclaw models list、次にironclaw models set-provider <id> --model <model>、最後にironclaw models statusを実行します。文書に記載された場所をそのまま信頼せず、ironclaw config pathでパスを確認してください。クイックスタートページではすべてが~/.ironclawの下にあるとされる一方、設定ページとオンボーディングページでは~/.ironclaw/rebornの下にあるとされています。ホスト型ユーザー向けの運用上の注意点として、設定ページにはironclaw serviceコマンドは「NEAR AIのホスト型インスタンスでは機能しない。呼び出すユーザーサービスマネージャーがないため」とあります。したがって、ironclaw configのためにSSH接続し、Agent Dashboardから再起動してください。引用はすべて、2026年9月21日時点のmainブランチから確認しました。

カスタムエンドポイントでは利用できないもの

これらは、mainのソースコードとコントラクトファイルから読み取った、IronClaw自身による意図した実行時動作についての記述です。実際の実行結果ではありません。確認時点では、mainは2026年8月28日に公開された1.4.0リリースタグより先行していました（GitHub releases APIによる）。

IronClawのカタログはチャット用カタログです。Kunavoは埋め込み、テキスト読み上げ、音声認識のモデルを提供していないため、設定のうちそれらを必要とする部分は、完全に別の場所を指す必要があります。

IronClawのコスト表示は請求額ではありません

IronClaw内部では、2つの別々の経路が金額を計算しており、互いに一致せず、どちらもプロバイダーを読み取りません。ironclaw_common内のprice_usage()は、ハードコードされたトークン単価テーブルを使い、default_cost()にフォールバックします。入力は1トークンあたり0.0000025、もう一方の単価は1トークンあたり0.00001で、100万トークンあたり$2.50 / $10.00というGPT-4o型の料金です。その理由は「新しい有料モデルの料金が、黙ってゼロとして計算されることがないようにする」とされています。一方、loop hostのStaticModelCostTableは予算予約について逆の動作をします。テーブルにないプロファイルは「Noneにフォールバックし、会計処理ではコストゼロとして扱う」とされています。また、llm_costs経路では、キャッシュ読み取りの割引率をモデル名の部分文字列から推測します。claudeは10で割り、gptまたはo1/o3/o4のプレフィックスは2で割り、それ以外は1で割ります。

実際の意味は、IronClawのbudget.user_daily_usd、budget.pause_at、その他の[budget]キーが管理するのは請求ではなく見積もりだということです。常時稼働するエージェントでは、暴走したループを早期に停止することが目的なので、これらを設定する価値はあります。ただし、照合する相手は画面上の数字ではなく、プロバイダーが記録した使用量です。

あるエージェントの1日の試算

これはトークン計算であり、測定したタスクコストでも請求上限でもありません。エージェントが1日活動し、合計でキャッシュされない入力トークン1,000,000と出力トークン40,000を使用すると仮定します。これは説明のための仮定であり、常時稼働するランタイムが長い返信ではなく、ハートビートやルーチンを通じて入力を蓄積することを踏まえて選んだものです。料金は、100万トークンあたりのKunavoカタログの最新価格です。

最後の列が有用な意外性を示しています。これはモデルの性質ではなく、ID文字列の性質です。vision_models.rsは、claude-opus-、claude-sonnet-、claude-haiku-、claude-fable-を含む固定リストと部分文字列を照合します。そのため、これらのIDは画像添付をルーティングします。上の表の他のIDはgpt-4o、gemini-1.5、gemini-2などリストのどれにも一致せず、テキスト専用に分類されます。一致しない場合、loop-hostゲートウェイは画像部分を除いたメッセージテキストを送信し、エラーを発生させません。永続トランスクリプトには<attachments>ポインターが残りますが、モデルは画像を認識しません。画像入力が機能すると考える前に、入力する予定の正確なIDをパターンリストで確認してください。金額は、自分の日数に合わせて拡大してから予算として扱ってください。Kunavoのカタログ金額は上限ではなく課金の下限です。上流側が料金を報告すると、請求額はカタログコストと、該当するマークアップを掛けた上流コストの大きい方になります。キャッシュ料金と外部ツールはこの例の対象外で、最低チャージ額は前払いクレジットの$10です。これは資金投入の最低額であり、タスク料金でもサブスクリプションでもありません。請求の詳細をご覧ください。

どの経路が優れているか、そしてIronClaw自体の費用

ソフトウェアは無料です。リポジトリのルートにはLICENSE-APACHEとLICENSE-MITの両方があり、READMEにはMIT OR Apache 2.0と記載されています。バイナリに有料版はなく、ライセンス料もありません。支払うのはトークン料金と、ベンダーのホスティングを利用する場合のホスティング料金です。

ホスティングプランの料金は、2026年9月21日にironclaw.comから読み取ったものです。/pricingページは存在せず、プランはホームページに掲載されており、レンダリングされたマークアップでは$5が取り消し線付きのspan内に表示され、現在の料金は$0になっています。ホームページには「信頼実行環境で最大5つのエージェントを起動し、月最大1億3,000万トークン」とも記載されています。この文は3つすべてのカードの上にあり、特定のプラン名を示していないため、1つのプランに紐づけないでください。このガイドで確認できず、推測もしない3点は、ホスティングプランがそもそもサードパーティキーを許可しているか、含まれるクレジットで実際に何を購入でき、使い切った場合にどうなるか、そして1億3,000万という数字がどのプランに属するかです。トークン料金は同日にnear.ai/pricingから読み取ったもので、「モデル料金に加えてプラットフォーム料金はかかりません」と記載されており、同社の機密テキストモデルのみを対象としています。

このランタイムを選ぶ理由だからこそ、プライバシーの境界を1つ明確に述べておきます。IronClaw自身のREADMEとセキュリティページが説明する制御 — シークレットの「保存時暗号化」とホスト境界での注入、信頼できないツール向けのWASMサンドボックス、エンドポイントの許可リスト、漏洩検知 — は、エージェントを実行するマシン上のローカル制御です。ハードウェア認証は別のNEAR AI Cloudの特性です。near.aiによれば、そこでの推論は「Intel TDX + NVIDIAの機密GPUエンクレーブ内で実行」され、「各レスポンスには検証可能なハードウェアクォートが付随」します。IronClawをサードパーティエンドポイントに向けると、プロンプトの内容はそのエンドポイントの規約に従って送信され、どちらの制御一覧もそこで引き継がれることはありません。ironclaw.comに掲載されたベンダー作成の「OpenClaw vs IronClaw」表は、一方の側によるマーケティングであり、中立的な比較ではありません。また検索結果には注意してください。2026年9月17日に取得した検索結果ページのサンプルでは、4つの検索語形式best api for ironclaw、cheapest api for ironclaw、best model for ironclaw、ironclaw custom providerのそれぞれで、上位10件中8件以上がOpenClawの結果となっており、そのモデルランキングは別の製品を説明しています。

設定後、最初の請求を確認する

Kunavo は、https://api.kunavo.com/v1 で OpenAI 形式のエンドポイントを公開しており、Anthropic 形式のエンドポイントも公開しています。これらはそれぞれ、プロバイダー ID openai_compatible と anthropic に対応します。Kunavo は IronClaw の実行時テストを行っていないため、上記のブロックは、互換性を主張するものではなく、文書化されたプロトコルに基づく出発点として扱ってください。動作するルートを利用可能な状態に保ち、範囲を限定したタスクを 1 つ実行して、アカウントに実際に記録された課金額を確認してください。ACP を介して IronClaw から Goose を操作する場合は、.env.example に Agent Client Protocol のサンドボックスとコマンド ironclaw acp add goose が記載されています。Goose 側については、Goose との連携で別途説明しています。また、準備ができたら、Kunavo アカウントを作成することでキーに資金を用意できます。関連する選択肢については、OpenAI 互換 API リファレンス、OpenRouter の代替サービス、AI コストの最適化をご覧ください。

よくある質問

リポジトリメタデータ、providers.json、CONTRACT.md、llm_costs.rs、vision_models.rs、docs/ツリー、ironclaw.com、near.ai/pricingはすべて2026年9月21日に、1.4.0リリースタグではなくmainブランチから読み取りました。IronClawのリクエストをKunavoのエンドポイントに送信したことはなく、ここでの互換性に関する記述はすべて双方のドキュメントを読んだ結果です。Kunavoのトークン料金は現在のカタログに基づいており、ドルの例はすべて説明用のトークン計算です。