OpenClawにOmniaKeyを設定する方法：API Providerとallowlist

2026年10月30日更新：よくある設定エラー4つを下にまとめ、それぞれ症状・原因・OpenClaw公式ドキュメントの対処法を書いています。

「OpenClaw API 設定方法」や「OpenClaw OmniaKey 設定方法」を探している場合、最初に理解すべきなのは、Providerの定義とモデルのallowlistは別の設定だということです。OpenClawはAgent loop、ツール利用、コード編集を提供し、実際の応答は接続したモデルProviderが担当します。

OmniaKeyをProviderとして追加する

設定ファイルは ~/.openclaw/openclaw.json です。models.providers の下に次のようなProviderを追加します。

{
  "models": {
    "mode": "merge",
    "providers": {
      "omniakey": {
        "baseUrl": "https://api.omniakey.com/v1",
        "apiKey": "your-omniakey-api-key",
        "api": "openai-completions",
        "models": [
          { "id": "claude-opus-4-8" },
          { "id": "gpt-5.5" },
          { "id": "gemini-3.1-pro-preview" },
          { "id": "grok-4.5" }
        ]
      }
    }
  }
}

mode: mergeは既存の設定を残したままProviderを追加する指定です。APIキーは実際の値に置き換え、Gitや公開チャットには保存しないでください。1つのOpenAI互換Providerで4つのモデルファミリーをまかなえます。OmniaKeyはモデルIDでモデルを選ぶため、claude-opus-4-8、gpt-5.5、gemini-3.1-pro-preview、grok-4.5 はすべて同じエントリで動きます。

忘れやすい手順：モデルをallowlistに追加する

Providerを定義しただけでは十分ではありません。OpenClawは使用可能なモデルをallowlistでも確認します。同じ openclaw.json の models と同じ階層に agents を追加します。

{
  "agents": {
    "defaults": {
      "models": ["omniakey/claude-opus-4-8", "omniakey/gpt-5.5", "omniakey/gemini-3.1-pro-preview", "omniakey/grok-4.5"],
      "model": "omniakey/claude-opus-4-8"
    }
  }
}

リクエスト本体で使うのはモデルIDですが、provider/model-id はOpenClaw内部の参照名です。Provider定義とallowlistの両方が必要です。片方だけ設定すると、キーが正しくても model not allowed になることがあります。

確認する

openclaw doctor

doctorは設定ファイル、Provider、キー形式、ライブ接続、モデルアクセスを確認します。問題がなければ agents.defaults のアクティブモデルを omniakey/gpt-5.5 などに設定できます。

よくあるセットアップエラー

• Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow. 選んだrefが、空でない agents.defaults.modelPolicy.allow の一覧に入っていません。OpenClawはこの一覧を /model、セッション内の上書き、--model のチェックに使います。正確なrefか omniakey/* のようなProviderワイルドカードを加えるか、一覧を空にするか、/model list にあるモデルを選んでください（OpenClawのモデルFAQ）。

• model_not_found や404が出るのに、同じモデルIDの直接呼び出しは通る。カスタムエントリが解決されるのは、baseUrl が /v1 で終わり、api が "openai-completions" で、カタログ側は接頭辞なしのIDのまま選択時だけProvider接頭辞を付ける、という3つがそろったときです。3つを確かめ、Provider接頭辞を付けて一度選んでから、同じプロンプトを再実行してください（ローカルバックエンドのトラブルシューティング）。

• 応答本文が「Your request was blocked」だけの403。この文言はふつう、エンドポイントの手前にあるセキュリティ層（CDN、WAF、botルール、リバースプロキシ）からのもので、openclaw.json の問題ではありません。openclaw logs --follow で、同じProviderの複数モデルが同じように失敗しているかを見ます。まずProvider側を直し、ルールはOpenClawが呼ぶパスだけを対象にして、サイト全体の保護は残してください（上流403のトラブルシューティング）。

• agent実行のたびに messages[...].content: invalid type: sequence, expected a string が出る。バックエンドがOpenAI形式の構造化contentパーツを受け付けていません。そのモデルのエントリに compat.requiresStringContent: true を設定して、同じプロンプトを再実行します。

OmniaKeyを使う理由

一つのキーと残高でClaude、GPT、Gemini、Grokを切り替えられ、料金はトークン単位です。allowlistに指定したモデルIDが実際に実行され、上流障害時に別モデルへ黙って置き換えられることはありません。 allowlist に書けるモデル ID はモデル一覧に、トークン単価は料金ページにあります。

詳細なツール別設定はコーディングAgentガイドを参照してください。手順を一つずつ確認したいときは、Hermes Agentのセットアップ、ClineのカスタムAPIキー設定、Claude Codeのセットアップの各ガイドをご覧ください。

よくある質問

OmniaKeyのProvider設定はどこに書きますか？

~/.openclaw/openclaw.json の models.providers の下です。"mode": "merge" を残すと、既存のProviderを置き換えずに追加できます。

OpenClawで「model not allowed」と出るのはなぜですか？

Providerは定義されているのに、モデルのrefがOpenClawのallowlistに入っていないため、キーが正しくても失敗します。omniakey/model-id の完全なrefを追加してから openclaw doctor を実行してください。

1つのOmniaKeyキーでClaude、GPT、Gemini、Grokを動かせますか？

はい。api: "openai-completions" のProviderエントリ1つで4つのファミリーにつながり、リクエストのモデルIDでどれが動くかが決まります。

OpenClawからOmniaKeyに届いているか確認するには？

openclaw doctor が設定ファイル、Provider、キー形式、ライブ接続、モデルアクセスを確認します。そのあと openclaw models list に、allowlistに入れたOmniaKeyのモデルが表示されます。

~/.openclaw/agents/main/agent/models.json は編集が必要ですか？

いいえ。このファイルは openclaw.json から再生成されます。Providerとallowlistは openclaw.json 側で編集してください。

確認した情報源

• OpenClaw: モデルと認証のFAQ
• OpenClaw: SkillsとモデルProvider