Gateway
ローカルモデルサービス
models.providers.<id>.localService により、OpenClaw は必要に応じてプロバイダー所有のローカル
モデルサーバーを起動できます。これはプロバイダーレベルの設定です。選択されたモデルが
そのプロバイダーに属している場合、OpenClaw はサービスをプローブし、エンドポイントが
停止していればプロセスを起動し、準備完了を待ってからモデルリクエストを送信します。
一日中稼働させておくにはコストが高いローカルサーバーや、モデル選択だけでバックエンドを 起動できるようにしたい手動セットアップに使用します。
仕組み
- モデルリクエストは設定済みのプロバイダーに解決されます。
- そのプロバイダーに
localServiceがある場合、OpenClaw はhealthUrlをプローブします。 - プローブが成功すると、OpenClaw は既存のサーバーを使用します。
- プローブが失敗すると、OpenClaw は
commandをargsとともに起動します。 - OpenClaw は
readyTimeoutMsが期限切れになるまで準備完了をポーリングします。 - モデルリクエストは通常のプロバイダートランスポート経由で送信されます。
- OpenClaw がプロセスを起動していて、
idleStopMsが正の値の場合、最後の実行中リクエストが その時間だけアイドル状態になった後にプロセスを停止します。
OpenClaw は、このために launchd、systemd、Docker、またはデーモンをインストールしません。 サーバーは、それを最初に必要とした OpenClaw プロセスの子プロセスです。
設定の形
{ 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, }, ], }, }, },}フィールド
command: 絶対実行可能パス。シェル検索は使用されません。args: プロセス引数。シェル展開、パイプ、グロブ、引用符の ルールは適用されません。cwd: プロセスの任意の作業ディレクトリ。env: OpenClaw プロセス環境の上にマージされる任意の環境変数。healthUrl: 準備完了 URL。省略した場合、OpenClaw は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 バックエンドであるため、同じローカルサービス
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, }, }, ], }, }, },}OpenClaw を実行しているマシンでの which inferrs の結果に command を置き換えます。
ds4 の例
{ models: { providers: { ds4: { baseUrl: "http://127.0.0.1:18000/v1", apiKey: "ds4-local", api: "openai-completions", timeoutSeconds: 300, localService: { command: "/Users/you/Projects/oss/ds4/ds4-server", args: [ "--model", "/Users/you/Projects/oss/ds4/ds4flash.gguf", "--host", "127.0.0.1", "--port", "18000", "--ctx", "393216", ], cwd: "/Users/you/Projects/oss/ds4", healthUrl: "http://127.0.0.1:18000/v1/models", readyTimeoutMs: 300000, idleStopMs: 0, }, models: [], }, }, },}運用上の注意
- 1つの OpenClaw プロセスが、自身の起動した子プロセスを管理します。同じヘルス URL が すでに稼働中であることを確認した別の OpenClaw プロセスは、それを引き継がずに再利用します。
- 起動はプロバイダーのコマンドと引数の組み合わせごとに直列化されるため、同時リクエストで 同じ設定の重複サーバーは生成されません。
- アクティブなストリーミングレスポンスはリースを保持します。アイドルシャットダウンはレスポンス 本文の処理が完了するまで待機します。
- 低速なローカルプロバイダーでは
timeoutSecondsを使用し、コールドスタートや長い生成が デフォルトのモデルリクエストタイムアウトに達しないようにします。 - サーバーが
/v1/models以外の場所で準備完了を公開している場合は、明示的なhealthUrlを使用します。