ローカルモデル

​

ハードウェアの下限

​

バックエンドを選ぶ

​

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
• 利用可能な最大のモデルビルドをダウンロードし（「small」や強く量子化されたバリアントは避ける）、サーバーを起動して、http://127.0.0.1:1234/v1/models に表示されることを確認します。
• my-local-model を LM Studio に表示される実際のモデル ID に置き換えます。
• モデルを読み込んだままにしてください。コールドロードは起動レイテンシを増やします。
• LM Studio ビルドが異なる場合は、contextWindow/maxTokens を調整します。
• WhatsApp では、最終テキストだけが送信されるように Responses API を使い続けます。
• ホスト型モデルをフォールバックとして利用できるように、models.mode: "merge" を維持します。

​

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

{
  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,
          },
        ],
      },
    },
  },
}

​

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

​

その他の 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 には注入されません。

• 文字列のみのコンテンツ: 一部のサーバーは、構造化されたコンテンツパート配列ではなく、文字列の messages[].content のみを受け付けます。models.providers.<provider>.models[].compat.requiresStringContent: true を設定します。
• 厳密なメッセージキー: サーバーが role/content 以外を持つメッセージエントリを拒否する場合は、compat.strictMessageKeys: true を設定します。
• 角括弧付きツールテキスト: 一部のローカルモデルは、[tool_name] に JSON と [END_TOOL_REQUEST] が続くような、単独の角括弧付きツールリクエストをテキストとして出力します。OpenClaw は、その名前がそのターンに登録されたツールと完全一致する場合にのみ、実際のツール呼び出しへ昇格します。それ以外の場合は、非表示の未対応テキストのままです。
• ツール呼び出しらしく見える非構造化テキスト: モデルがツール呼び出しのように見える JSON/XML/ReAct 形式のテキストを出力したものの、構造化された呼び出しではなかった場合、OpenClaw はそれをテキストのままにし、実行 ID、プロバイダー / モデル、検出されたパターン、利用可能な場合はツール名を含む警告をログに記録します。これはプロバイダー / モデルの非互換であり、完了したツール実行ではありません。
• ツール使用の強制: ツールがアシスタントテキスト（生の JSON/XML/ReAct、または空の tool_calls 配列）として現れる場合、まずサーバーのチャットテンプレート / パーサーがツール呼び出しに対応していることを確認してください。ツール使用を強制した場合にのみパーサーが動作するなら、モデルごとにデフォルトのプロキシ値 tool_choice: "auto" を上書きします。
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  これは通常のすべてのターンでツールを呼ぶべき場合にのみ使ってください。local/my-local-model を openclaw models list の正確な参照に置き換えるか、CLI で設定します。
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• 追加の推論 effort: カスタム OpenAI 互換モデルが組み込みプロファイルを超える OpenAI 推論 effort を受け付ける場合は、モデルの compat ブロックで宣言します。"xhigh" を追加すると、そのモデル参照について /think xhigh、セッションピッカー、Gateway 検証、llm-task 検証で利用可能になります。
  {
    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 ルーティングを確認する - transcript、AGENTS bootstrap、context-engine assembly、tools、バンドル済み MCP servers をスキップしてプロンプトのみを送信しますが、Gateway ルーティング、認証、プロバイダー選択は引き続き実行します。
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. リーンモードを試す 両方のプローブが成功しても、実際のエージェントターンが不正な形式のツール呼び出しや過大なプロンプトで失敗する場合は、agents.defaults.experimental.localModelLean: true を設定します。明示的に必要でない限り、重量級のブラウザー、Cron、メッセージ、メディア生成、音声、PDF ツールを除外し、より大きなツールカタログはデフォルトで構造化されたツール検索コントロールの背後に置きます。詳細と有効化の確認方法は、実験的機能 -> ローカルモデルリーンモード を参照してください。
4. 最後の手段としてツールを完全に無効化する そのモデルに models.providers.<provider>.models[].compat.supportsTools: false を設定します。これにより、エージェントはツール呼び出しなしで実行されます。
5. そこから先のボトルネックはアップストリームです。 リーンモードと supportsTools: false の後でも、より大きな OpenClaw 実行でのみバックエンドが失敗する場合、残っている問題は通常、OpenClaw のトランスポート層ではなく、モデルまたはサーバー自体、つまりコンテキストウィンドウ、GPU メモリ、kv-cache の退避、またはバックエンドのバグです。

​

トラブルシューティング

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

​

関連

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