Wiki AI

本地模型服务（按需启动）

3分钟阅读

models.providers.<id>.localService 允许 OpenClaw 按需启动本地模型服务器。当选中该 provider 的模型时，OpenClaw 自动探测、启动并等待服务就绪后再发送请求。

适用场景：本地服务器（ds4、inferrs、vLLM、llama.cpp、MLX 等）运行成本高，不适合全天保持运行。

工作流程

  1. 模型请求解析到配置了 localService 的 provider
  2. OpenClaw 探测 healthUrl
  3. 探测成功 → 使用已有服务器
  4. 探测失败 → 用 command + args 启动进程
  5. 轮询就绪直到 readyTimeoutMs 超时
  6. 通过正常 provider transport 发送请求
  7. 若 idleStopMs > 0，最后一个请求空闲后停止进程

配置结构

{
  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,
        },
      },
    },
  },
}

字段说明

字段说明
command绝对路径，不使用 shell 查找
args进程参数，无 shell 展开
cwd可选工作目录
env合并到 OpenClaw 进程环境的变量
healthUrl就绪检测 URL，默认为 baseUrl + /models
readyTimeoutMs启动就绪超时，默认 120000
idleStopMs空闲停止延迟，0 或省略表示保持运行直到 OpenClaw 退出

Inferrs 示例

{
  models: {
    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,
        },
      },
    },
  },
}

操作注意事项

  • 同一 OpenClaw 进程管理其启动的子进程；另一个 OpenClaw 进程看到已运行的服务会复用但不接管
  • 同一 command+args 的并发请求不会启动重复服务器（串行化）
  • 活跃流式响应持有租约，空闲停止等待响应完成
  • 慢速本地 provider 建议设置 timeoutSeconds 避免超时

相关链接

关系图谱

反向链接