跳轉到主要內容

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.

models.providers.<id>.localService 讓 OpenClaw 可依需求啟動由 provider 擁有的本機 模型伺服器。這是 provider 層級的設定：當選定的模型 屬於該 provider 時，OpenClaw 會探測服務，如果端點已停機就啟動程序， 等待就緒，然後送出模型請求。 可將它用於整天保持執行成本很高的本機伺服器，或用於 只要選擇模型就應足以啟動後端的手動設定。

​
運作方式

  1. 模型請求會解析到已設定的 provider。
  2. 如果該 provider 有 localService，OpenClaw 會探測 healthUrl。
  3. 如果探測成功，OpenClaw 會使用現有伺服器。
  4. 如果探測失敗，OpenClaw 會以 args 啟動 command。
  5. OpenClaw 會輪詢就緒狀態，直到 readyTimeoutMs 到期。
  6. 模型請求會透過一般的 provider 傳輸送出。
  7. 如果 OpenClaw 啟動了該程序，且 idleStopMs 為正數，程序會在最後一個 進行中的請求閒置達該時間後停止。
OpenClaw 不會為此安裝 launchd、systemd、Docker 或 daemon。 伺服器是第一個需要它的 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：絕對可執行檔路徑。不使用 shell 查找。
  • args：程序引數。不會套用 shell 展開、管線、glob 或引號 規則。
  • cwd：程序的選用工作目錄。
  • env：選用環境變數，會覆蓋合併到 OpenClaw 程序 環境之上。
  • healthUrl：就緒 URL。如果省略，OpenClaw 會將 /models 附加到 baseUrl，因此 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 provider 項目使用。 
{
  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 的結果。

​
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: [],
      },
    },
  },
}

​
操作注意事項

  • 一個 OpenClaw 程序會管理它啟動的子程序。另一個看到相同 health URL 已經在線的 OpenClaw 程序，會重用它而不接管它。
  • 啟動會依 provider 命令與引數集序列化，因此並行 請求不會為相同設定產生重複伺服器。
  • 作用中的串流回應會持有租約；閒置關閉會等到回應 body 處理完成。
  • 在較慢的本機 provider 上使用 timeoutSeconds，讓冷啟動和長時間生成 不會觸發預設模型請求逾時。
  • 如果你的伺服器在 /v1/models 以外的位置公開就緒狀態，請使用明確的 healthUrl。

​
相關

本機模型

本機模型設定、provider 選擇與安全指引。

Inferrs

透過 inferrs OpenAI 相容本機伺服器執行 OpenClaw。