ローカルモデルサービス

models.providers.<id>.localService は、プロバイダーが所有するローカルモデルサーバーを必要に応じて起動します。モデルまたは埋め込みリクエストでそのプロバイダーが選択されると、OpenClaw はヘルスエンドポイントをプローブし、停止している場合はプロセスを起動して、準備が整うまで待ってからリクエストを送信します。高コストなローカルサーバーを一日中稼働させておくことを避けるために使用します。

仕組み

モデルまたは埋め込みリクエストが、設定済みのプロバイダーに解決されます。
そのプロバイダーに localService がある場合、OpenClaw は healthUrl をプローブします。
プローブが成功すると、OpenClaw はすでに稼働中のサーバーを使用します。
プローブが失敗すると、OpenClaw は args を指定して command を起動します。
OpenClaw は readyTimeoutMs が期限切れになるまでヘルスエンドポイントをポーリングします。
リクエストは通常のモデルまたは埋め込みトランスポートを経由します。
OpenClaw がプロセスを起動し、idleStopMs が設定されている場合、処理中の最後のリクエストがその時間にわたってアイドル状態になると、プロセスを停止します。

このために OpenClaw が launchd、systemd、Docker、またはデーモンをインストールすることはありません。サーバーは、最初に必要とした OpenClaw プロセスの通常の子プロセスです。起動は、設定済みのプロバイダーとコマンド、引数、環境変数の組み合わせごとに直列化されるため、同じサービスに対するチャットリクエストと埋め込みリクエストが同時に発生しても、重複するサーバーは起動されません。各リクエストは応答処理が完了するまで独自のリースを保持するため、アイドル時のシャットダウンは、処理中のすべてのモデルリクエストと埋め込みリクエストが完了するまで待機します。設定済みのプロバイダーエイリアスは別々に扱われます。2 つのエイリアスで異なる GPU ホストを指定しても、同じ Ollama、LM Studio、または OpenAI 互換アダプター ID に統合されることはありません。別の OpenClaw プロセスが同じ healthUrl ですでに正常なサーバーを稼働させている場合、このプロセスはそのサーバーを管理対象として引き継がずに再利用します（各プロセスが管理するのは、自ら起動した子プロセスだけです）。起動ログと終了ログには、長さを制限して機密情報を編集した子プロセス出力の末尾部分に加え、タイミングと終了の詳細が含まれます。設定済みの環境変数値が出力されることはありません。

設定形式

{
  models: {
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "local-model",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/absolute/path/to/server",
          args: ["--host", "127.0.0.1", "--port", "8000"],
          cwd: "/absolute/path/to/working-dir",
          env: { LOCAL_MODEL_CACHE: "/absolute/path/to/cache" },
          healthUrl: "http://127.0.0.1:8000/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "my-local-model",
            name: "My Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

コールドスタートが遅い場合や生成に時間がかかる場合に、デフォルトのモデルリクエストタイムアウトに達しないよう、プロバイダーエントリ（localService ではありません）に timeoutSeconds を設定します。サーバーの準備状態がベース URL の /models 以外の場所で公開される場合は、必ず明示的な healthUrl を設定してください。

フィールド

フィールド	必須	説明
`command`	はい	実行可能ファイルの絶対パス。シェルの PATH 検索は行いません。
`args`	いいえ	プロセス引数。シェル展開、パイプ、グロブ、引用符処理は行いません。
`cwd`	いいえ	プロセスの作業ディレクトリ。
`env`	いいえ	OpenClaw プロセスの環境に上書きマージされる環境変数。
`healthUrl`	いいえ	準備状態を確認する URL。デフォルトでは `baseUrl` に `/models` を追加します（`http://127.0.0.1:8000/v1` は `http://127.0.0.1:8000/v1/models` になります）。
`readyTimeoutMs`	いいえ	起動時の準備完了期限。デフォルト: `120000`。
`idleStopMs`	いいえ	OpenClaw が起動したプロセスのアイドル時シャットダウン遅延。`0` または省略した場合は、OpenClaw が終了するまで稼働し続けます。

Inferrs の例

Inferrs はカスタムの OpenAI 互換 /v1 バックエンドであるため、同じ localService API を inferrs プロバイダーエントリで使用できます。

{
  agents: {
    defaults: {
      model: { primary: "inferrs/google/gemma-4-E2B-it" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      inferrs: {
        baseUrl: "http://127.0.0.1:8080/v1",
        apiKey: "inferrs-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/opt/homebrew/bin/inferrs",
          args: [
            "serve",
            "google/gemma-4-E2B-it",
            "--host",
            "127.0.0.1",
            "--port",
            "8080",
            "--device",
            "metal",
          ],
          healthUrl: "http://127.0.0.1:8080/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "google/gemma-4-E2B-it",
            name: "Gemma 4 E2B (inferrs)",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 4096,
            compat: { requiresStringContent: true },
          },
        ],
      },
    },
  },
}

command を、OpenClaw を実行しているマシン上での which inferrs の結果に置き換えます。Inferrs の完全なセットアップ: Inferrs。

ds4 の例

{
  models: {
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "<DS4_DIR>/ds4-server",
          args: [
            "--model",
            "<DS4_DIR>/ds4flash.gguf",
            "--host",
            "127.0.0.1",
            "--port",
            "18000",
            "--ctx",
            "32768",
            "--tokens",
            "128",
          ],
          cwd: "<DS4_DIR>",
          healthUrl: "http://127.0.0.1:18000/v1/models",
          readyTimeoutMs: 300000,
          idleStopMs: 0,
        },
        models: [],
      },
    },
  },
}

完全なセットアップ、コンテキストサイズの設定、および検証コマンドについては、ds4 を参照してください。