OpenClaw 可在模型请求时自动启动本地模型服务器（如 inferrs、ds4、vLLM 等），避免常驻进程浪费资源。在 provider 配置中设置 localService 对象，指定 command、args、healthUrl 和 readyTimeoutMs，OpenClaw 会自动探测健康端点、启动子进程并等待就绪，空闲后可配置 idleStopMs 自动关闭。启动是串行的，不会重复启动同一配置，且仅管理自己启动的进程。

OpenClaw 本地模型服务配置：按需启动模型服务器

models.providers.<id>.localService 让 OpenClaw 在需要时自动启动该 provider 对应的本地模型服务器。这是 provider 级别的配置：当选择的模型属于该 provider 时，OpenClaw 先探测服务是否存活，若端点不可用则启动进程，等待就绪后再发送模型请求。

适合那些全天运行代价较高的本地服务器，或需要“选模型即启动后端”的手动部署场景。

工作流程

1. 模型请求解析到已配置的 provider。
2. 如果该 provider 包含 localService，则 OpenClaw 先探测 healthUrl。
3. 探测成功 → OpenClaw 直接使用已有服务器。
4. 探测失败 → OpenClaw 用 command 和 args 启动进程。
5. OpenClaw 轮询就绪状态，直到 readyTimeoutMs 超时。
6. 模型请求通过正常的 provider 传输通道发出。
7. 如果进程由 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 进程的环境之上。
• healthUrl：就绪检查 URL。如果省略，OpenClaw 会追加 /models 到 baseUrl，例如 http://127.0.0.1:8000/v1 变成 http://127.0.0.1:8000/v1/models。
• readyTimeoutMs：启动就绪超时时间，默认值 120000（120 秒）。
• idleStopMs：空闲关闭延迟，仅对 OpenClaw 启动的进程有效。设置为 0 或省略则保持进程运行，直到 OpenClaw 退出。

Inferrs 示例

Inferrs 是一个自定义的 OpenAI 兼容 /v1 后端，因此相同的 localService 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 示例

完整配置、上下文窗口调整指南和验证命令请参见 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 进程如果看到相同的 health URL 已经响，会直接复用，不会接管进程所有权。
• 同一 provider 的命令和参数集是串行启动的，因此并发请求不会为同一配置启动多个重复服务器。
• 流式响应会持有租约；空闲关闭会等响应体处理完毕后再执行。
• 对于慢速的本地 provider，请增大 timeoutSeconds，避免冷启动或长生成任务被默认的模型请求超时截断。
• 如果服务器在 /v1/models 之外暴露就绪端点，请使用显式的 healthUrl。

常见问题

如何让 OpenClaw 自动启动我的本地模型服务器？

在对应的 provider 配置中添加 localService 对象，设置 command（可执行文件绝对路径）、args 启动参数、healthUrl 健康检查地址和 readyTimeoutMs 超时时间。当模型请求路由到该 provider 时，OpenClaw 会自动探测并启动进程。

idleStopMs 设置为 0 是什么意思？

idleStopMs 为 0 或省略表示 OpenClaw 不会自动关闭由它启动的模型服务器，该进程会一直运行直到 OpenClaw 退出。如果希望在空闲一段时间后自动关闭，请设置一个正数（单位为毫秒），例如 300000 代表 5 分钟无请求后关闭。

健康检查 URL 不配置会怎样？

如果省略 healthUrl，OpenClaw 会自动在 baseUrl 后追加 /models。例如 baseUrl: "http://127.0.0.1:8000/v1" 会变成 http://127.0.0.1:8000/v1/models。如果你的服务器就绪端点不是 /v1/models，则必须显式设置 healthUrl，否则探测会失败。