本地模型服务

在 OpenClaw 发起模型和嵌入请求之前，按需启动本地模型服务器

models.providers.<id>.localService 按需启动由提供商拥有的本地模型服务器。当模型或嵌入请求选择该提供商时，OpenClaw 会探测健康端点；如果进程未运行，则启动进程，等待其就绪，然后发送请求。使用此功能可避免让昂贵的本地服务器全天运行。

工作原理

模型或嵌入请求会解析到已配置的提供商。
如果该提供商具有 localService，OpenClaw 会探测 healthUrl。
探测成功时，OpenClaw 使用已在运行的服务器。
探测失败时，OpenClaw 使用 args 启动 command。
OpenClaw 会轮询健康端点，直到 readyTimeoutMs 到期。
请求通过常规模型或嵌入传输通道发送。
如果该进程由 OpenClaw 启动且设置了 idleStopMs，则最后一个进行中的请求空闲达到该时长后，OpenClaw 会停止该进程。

OpenClaw 不会为此安装 launchd、systemd、Docker 或任何守护进程。该服务器只是第一个需要它的 OpenClaw 进程所创建的普通子进程。

系统会针对每组已配置的提供商及命令、参数和环境变量进行串行启动，因此，同一服务的并发聊天和嵌入请求不会产生重复的服务器。每个请求都会持有自己的租约，直到响应处理完成，因此空闲关闭会等待所有进行中的模型和嵌入请求结束。配置的提供商别名保持彼此独立：两个别名可以指向不同的 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`	是	可执行文件的绝对路径。不查找 shell PATH。
`args`	否	进程参数。不执行 shell 展开、管道、通配符匹配或引号处理。
`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。