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

> OpenClawでOmniaKeyをOpenAI互換Providerとして設定する手順を解説。openclaw.json、モデルallowlist、doctorによる確認、設定ミスの対処をまとめます。

- Canonical HTML: https://omniakey.com/ja/blog/openclaw-setup
- Markdown: https://omniakey.com/ja/blog/openclaw-setup.md
- Published: 2026-05-19 (updated 2026-10-30)
- Author: Kiki, COO at OmniaKey
- Language: ja
- Category: Guide
- Reading time: 5 min
- All posts: https://omniakey.com/blog/llms.txt

---

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

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

## OmniaKeyをProviderとして追加する

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

```json
{
  "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` を追加します。

```json
{
  "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` になることがあります。

## 確認する

```bash
openclaw doctor
```

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

> `~/.openclaw/agents/main/agent/models.json` は手動編集しないでください。`openclaw.json`から再生成されます。JSONを壊した場合は、まずカンマや括弧を確認してから再実行します。

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

- `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](https://docs.openclaw.ai/help/faq-models#why-do-i-see-model-is-not-allowed-and-then-no-reply)）。

- `model_not_found` や404が出るのに、同じモデルIDの直接呼び出しは通る。カスタムエントリが解決されるのは、`baseUrl` が `/v1` で終わり、`api` が `"openai-completions"` で、カタログ側は接頭辞なしのIDのまま選択時だけProvider接頭辞を付ける、という3つがそろったときです。3つを確かめ、Provider接頭辞を付けて一度選んでから、同じプロンプトを再実行してください（[ローカルバックエンドのトラブルシューティング](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#local-openai-compatible-backend-passes-direct-checks-but-agent-runs-fail)）。

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

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

## OmniaKeyを使う理由

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

- **OpenAI-compatible**: <https://api.omniakey.com/v1>
- **Anthropic-native**: <https://api.omniakey.com>
- **Gemini-native**: <https://api.omniakey.com/v1beta>

詳細なツール別設定は[コーディングAgentガイド](https://docs.omniakey.com/ja/coding)を参照してください。手順を一つずつ確認したいときは、[Hermes Agentのセットアップ](https://omniakey.com/ja/blog/hermes-setup)、[ClineのカスタムAPIキー設定](https://omniakey.com/ja/blog/cline-custom-api-key)、[Claude Codeのセットアップ](https://omniakey.com/ja/blog/claude-code-setup)の各ガイドをご覧ください。

## よくある質問

### 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](https://docs.openclaw.ai/help/faq-models)
- [OpenClaw: SkillsとモデルProvider](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers)