> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 本地模型服务

`models.providers.<id>.localService` 会按需启动由提供方拥有的本地模型服务器。当某个模型或嵌入请求选择了该提供方时，OpenClaw 会探测健康检查端点；如果进程已停止则启动它，等待其就绪，然后发送请求。可用它来避免让昂贵的本地服务器全天运行。

## 工作原理

1. 模型或嵌入请求会解析到一个已配置的提供方。
2. 如果该提供方具有 `localService`，OpenClaw 会探测 `healthUrl`。
3. 探测成功后，OpenClaw 使用已经运行中的服务器。
4. 探测失败后，OpenClaw 使用 `args` 启动 `command`。
5. OpenClaw 会轮询健康检查端点，直到 `readyTimeoutMs` 过期。
6. 请求通过正常的模型或嵌入传输流程。
7. 如果 OpenClaw 启动了该进程并且设置了 `idleStopMs`，它会在最后一个进行中的请求空闲达到该时长后停止该进程。

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

启动会针对每个已配置的提供方以及 `command`/`argument`/`env` 集合进行串行化，因此针对同一服务的并发聊天和嵌入请求不会启动重复的服务器。每个请求都会持有自己的租约，直到响应处理完成，因此空闲关闭会等待所有进行中的模型和嵌入请求。已配置的提供方别名保持彼此独立：两个别名可以指向不同的 GPU 主机，而不会合并到同一个 Ollama、LM Studio 或 OpenAI 兼容适配器 id 上。

如果另一个 OpenClaw 进程已经在相同的 `healthUrl` 上有一个健康的服务器，则此进程会复用它，但不会接管它（每个进程只管理它自己启动的子进程）。启动和退出日志会包含有上限、已脱敏的子进程输出尾部，以及耗时和退出详细信息；已配置的环境变量值绝不会被输出。

## 配置结构

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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: "我的本地模型",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
```

将 `timeoutSeconds` 设置在 provider 条目上（而不是 `localService`） ，这样较慢的冷启动和较长的生成过程就不会触发默认的模型请求超时。只要你的服务器在除基础 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` provider 条目一起使用：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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](/providers/inferrs)。

## ds4 示例

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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](/providers/ds4)。

## 相关内容

<CardGroup cols={2}>
  <Card title="本地模型" href="/gateway/local-models" icon="server">
    本地模型设置、提供者选择和安全指导。
  </Card>

  <Card title="Inferrs" href="/providers/inferrs" icon="cpu">
    通过 inferrs 兼容 OpenAI 的本地服务器运行 OpenClaw。
  </Card>
</CardGroup>