ローカルモデル

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ハードウェアの下限

​

バックエンドを選ぶ

​

推奨: LM Studio + 大規模ローカルモデル（Responses API）

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "Local" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• LM Studio をインストールします: https://lmstudio.ai
• LM Studio で 利用可能な最大のモデルビルド をダウンロードし（「small」や大幅に量子化されたバリアントは避ける）、サーバーを起動し、http://127.0.0.1:1234/v1/models にそれが一覧表示されることを確認します。
• my-local-model を、LM Studio に表示される実際のモデル ID に置き換えます。
• モデルを読み込んだままにします。コールドロードは起動レイテンシを追加します。
• LM Studio ビルドが異なる場合は、contextWindow/maxTokens を調整します。
• WhatsApp では、最終テキストだけが送信されるように Responses API を使い続けます。

​

ハイブリッド設定: ホスト型をプライマリ、ローカルをフォールバック

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "lmstudio/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​

ローカル優先、ホスト型の安全網付き

​

リージョン別ホスティング / データルーティング

• ホスト型の MiniMax/Kimi/GLM バリアントは、OpenRouter にもリージョン固定エンドポイント（例: 米国ホスト）付きで存在します。選択した法域内にトラフィックを維持しつつ、Anthropic/OpenAI フォールバックのために models.mode: "merge" を使い続けるには、そこでリージョン別バリアントを選びます。
• ローカル専用が最も強力なプライバシー経路です。ホスト型リージョナルルーティングは、プロバイダー機能が必要だがデータフローを制御したい場合の中間策です。

​

その他の OpenAI 互換ローカルプロキシ

{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

• OpenClaw はこれらを、ネイティブ OpenAI エンドポイントではなく、プロキシ形式の OpenAI 互換ルートとして扱います
• ここではネイティブ OpenAI 専用のリクエスト整形は適用されません。つまり、 service_tier なし、Responses の store なし、OpenAI 推論互換ペイロード 整形なし、プロンプトキャッシュヒントなしです
• 非表示の OpenClaw 帰属ヘッダー（originator、version、User-Agent）は、 これらのカスタムプロキシ URL には注入されません

• 一部のサーバーは、Chat Completions で構造化された content-part 配列ではなく、 文字列の messages[].content のみを受け入れます。そのようなエンドポイントには models.providers.<provider>.models[].compat.requiresStringContent: true を設定してください。
• 一部のローカルモデルは、[tool_name] に続く JSON と [END_TOOL_REQUEST] のような、 独立した角括弧付きツールリクエストをテキストとして出力します。OpenClaw は、 その名前がそのターンに登録済みのツールと完全に一致する場合にのみ、 それらを実際のツール呼び出しに昇格します。一致しない場合、そのブロックは未対応のテキストとして扱われ、 ユーザーに表示される返信からは隠されます。
• モデルが JSON、XML、またはツール呼び出しのように見える ReAct 形式のテキストを出力したが、 provider が構造化 invocation を出力しなかった場合、OpenClaw はそれをテキストのまま残し、 実行 ID、provider/model、検出されたパターン、利用可能な場合はツール名を含む警告をログに記録します。 これは完了したツール実行ではなく、provider/model のツール呼び出し 非互換性として扱ってください。
• ツールが実行されず、たとえば生の JSON、 XML、ReAct 構文、または provider レスポンス内の空の tool_calls 配列のように、assistant テキストとして表示される場合は、 まずサーバーがツール呼び出し対応のチャットテンプレート / パーサーを使用していることを確認してください。 ツール使用が強制された場合にのみパーサーが動作する OpenAI 互換 Chat Completions バックエンドでは、 テキスト解析に頼る代わりに、モデルごとのリクエスト上書きを設定します。
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  これは、すべての通常ターンでツールを呼び出すべきモデル / セッションにのみ使用してください。 OpenClaw のデフォルトのプロキシ値 tool_choice: "auto" を上書きします。 local/my-local-model は、openclaw models list に表示される正確な provider/model 参照に置き換えてください。
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• カスタム OpenAI 互換モデルが、組み込みプロファイルを超える OpenAI 推論 effort を受け入れる場合は、 モデルの compat ブロックで宣言してください。ここに "xhigh" を追加すると、 /think xhigh、セッションピッカー、Gateway 検証、llm-task 検証で、その設定済み provider/model 参照のレベルが公開されます。
  {
    models: {
      providers: {
        local: {
          baseUrl: "http://127.0.0.1:8000/v1",
          apiKey: "sk-local",
          api: "openai-responses",
          models: [
            {
              id: "gpt-5.4",
              name: "GPT 5.4 via local proxy",
              reasoning: true,
              input: ["text"],
              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
              contextWindow: 196608,
              maxTokens: 8192,
              compat: {
                supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
                reasoningEffortMap: { xhigh: "xhigh" },
              },
            },
          ],
        },
      },
    },
  }
  

​

小型またはより厳格なバックエンド

1. ローカルモデル自体が応答することを確認します。 ツールもエージェントコンテキストも使いません。
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. Gateway ルーティングを確認します。 指定したプロンプトのみを送信します。トランスクリプト、AGENTS ブートストラップ、コンテキストエンジンの組み立て、ツール、同梱 MCP サーバーはスキップしますが、Gateway ルーティング、認証、プロバイダー選択は引き続き実行されます。
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. 軽量モードを試します。 両方のプローブが通るのに実際のエージェントターンが不正なツール呼び出しや過大なプロンプトで失敗する場合は、agents.defaults.experimental.localModelLean: true を有効にします。これにより、最も重い 3 つのデフォルトツール（browser、cron、message）が削除され、プロンプトの形が小さくなり、壊れにくくなります。詳しい説明、使用するタイミング、有効化されていることの確認方法については、実験的機能 → ローカルモデル軽量モードを参照してください。
4. 最後の手段としてツールを完全に無効化します。 軽量モードでも不十分な場合は、そのモデルエントリに models.providers.<provider>.models[].compat.supportsTools: false を設定します。すると、そのモデルではエージェントがツール呼び出しなしで動作します。
5. それ以降のボトルネックはアップストリームです。 軽量モードと supportsTools: false の後でも、大きめの OpenClaw 実行でのみバックエンドが失敗する場合、残る問題は通常、アップストリームのモデルまたはサーバー容量です。コンテキストウィンドウ、GPU メモリ、kv-cache の退避、またはバックエンドのバグが原因です。その時点では OpenClaw のトランスポート層の問題ではありません。

​

トラブルシューティング

• Gateway はプロキシに到達できますか？ curl http://127.0.0.1:1234/v1/models。
• LM Studio モデルがアンロードされていますか？ 再読み込みしてください。コールドスタートは「ハング」の一般的な原因です。
• ローカルサーバーが terminated、ECONNRESET と表示する、またはターンの途中でストリームを閉じますか？ OpenClaw は、低カーディナリティの model.call.error.failureKind と OpenClaw プロセスの RSS/ヒープスナップショットを診断に記録します。LM Studio/Ollama の メモリ圧迫については、そのタイムスタンプをサーバーログまたは macOS のクラッシュ / jetsam ログと照合し、モデルサーバーが強制終了されたかどうかを確認してください。
• OpenClaw は、検出されたモデルウィンドウ、または agents.defaults.contextTokens が有効ウィンドウを下げている場合は上限なしのモデルウィンドウから、コンテキストウィンドウのプリフライトしきい値を導出します。20% 未満では 8k の下限で警告します。ハードブロックは 4k の下限で 10% のしきい値を使用し、有効コンテキストウィンドウまでに制限されるため、過大なモデルメタデータによって本来有効なユーザー上限が拒否されることはありません。このプリフライトに当たる場合は、サーバー/モデルのコンテキスト上限を引き上げるか、より大きなモデルを選択してください。
• コンテキストエラーですか？ contextWindow を下げるか、サーバー上限を引き上げてください。
• OpenAI 互換サーバーが messages[].content ... expected a string を返しますか？ そのモデルエントリに compat.requiresStringContent: true を追加してください。
• OpenAI 互換サーバーが validation.keys を返す、またはメッセージエントリでは role と content のみが許可されると言いますか？ そのモデルエントリに compat.strictMessageKeys: true を追加してください。
• 小さな直接の /v1/chat/completions 呼び出しは動作するのに、openclaw infer model run --local が Gemma または別のローカルモデルで失敗しますか？ まずプロバイダー URL、モデル参照、認証 マーカー、サーバーログを確認してください。ローカルの model run にはエージェントツールは含まれません。 ローカルの model run が成功するのに大きめのエージェントターンが失敗する場合は、 localModelLean または compat.supportsTools: false でエージェントの ツール対象範囲を減らしてください。
• ツール呼び出しが生の JSON/XML/ReAct テキストとして表示される、またはプロバイダーが 空の tool_calls 配列を返しますか？ アシスタントテキストを盲目的に ツール実行へ変換するプロキシを追加しないでください。先にサーバーのチャットテンプレート/パーサーを修正してください。 ツール使用を強制した場合にのみモデルが動作するなら、上記のモデル単位の params.extra_body.tool_choice: "required" オーバーライドを追加し、毎ターンでツール呼び出しが期待される セッションにのみそのモデルエントリを使用してください。
• 安全性: ローカルモデルはプロバイダー側フィルターをスキップします。プロンプトインジェクションの影響範囲を制限するため、エージェントは狭く保ち、Compaction を有効にしてください。

​

関連

• 設定リファレンス
• モデルフェイルオーバー