本地模型服务

models.providers.<id>.localService 让 OpenClaw 能够按需启动提供商拥有的本地模型服务器。这是提供商级别的配置：当所选模型属于该提供商时，OpenClaw 会探测服务，如果端点关闭则启动进程，等待就绪，然后发送模型请求。

将其用于全天候运行成本高昂的本地服务器，或用于仅需选择模型即可启动后端的手动设置。

工作原理

模型请求会解析为已配置的提供商。
如果该提供商具有 localServiceOpenClaw，OpenClaw 将探测 healthUrl。
如果探测成功，OpenClaw 将使用现有的服务器。
如果探测失败，OpenClaw 会使用 args 启动 OpenClawcommand。
OpenClaw 轮询就绪状态，直到 OpenClawreadyTimeoutMs 过期。
模型请求通过正常的提供商传输发送。
如果 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：可执行文件的绝对路径。不使用 Shell 查找。
args：进程参数。不应用 Shell 展开、管道、通配符或引用规则。
cwd：进程的可选工作目录。
env：可选的环境变量，将合并到 OpenClaw 进程环境中。
healthUrlOpenClaw：就绪 URL。如果省略，OpenClaw 会将 /models 追加到 baseUrl，因此 http://127.0.0.1:8000/v1 会变为 http://127.0.0.1:8000/v1/models。
readyTimeoutMs：启动就绪截止时间。默认值：120000。
idleStopMsOpenClaw：OpenClaw 启动的进程的空闲关闭延迟。0OpenClaw 或省略将使进程保持运行，直到 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,
            },
          },
        ],
      },
    },
  },
}

将 command 替换为运行 OpenClaw 的机器上 which inferrs 的结果。

ds4 示例

有关完整的设置、上下文大小指导原则和验证命令，请参阅 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: [],
      },
    },
  },
}

操作说明

一个 OpenClaw 进程管理其启动的子进程。另一个 OpenClaw 进程如果发现相同的运行状况 URL 已处于活动状态，将直接重用它，而不会接管它。
启动过程是按提供商命令和参数集串行化的，因此并发请求不会针对相同的配置生成重复的服务器。
活动的流式响应持有租约；空闲关闭会等待直到响应正文处理完成。
在速度较慢的本地提供商上使用 timeoutSeconds，以免冷启动和长时间生成受到默认模型请求超时的影响。
如果您的服务器在 /v1/models 以外的位置暴露就绪状态，请使用显式的 healthUrl。