本地模型服务

models.providers.<id>.localService 会按需启动一个 provider 自有的本地模型服务器。当模型或嵌入请求选中该 provider 时，OpenClaw 会探测健康检查端点，如果进程未运行则启动它，等待就绪后发送请求。使用此功能可避免昂贵的本地服务器全天候运行。

工作原理¶

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

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

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

OpenClaw 在关闭本地服务时，会等待任何已在进行的空闲关闭完成。同一服务的新请求会先等待该停止完成，然后才获取替代服务。关闭错误保持可见；后续请求在启动替代进程前会重新检查自有进程。

关闭完成要求子进程及其输出流关闭，并且挂起的进程树终止操作完成。仅 PID 缺失并不会释放该服务以供替代。

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

托管的 llama.cpp¶

官方 llama.cpp provider 会自动生成这种配置形态。其引导式安装流程会安装一个固定版本且经过验证的 llama-server，写入绝对路径的 command 和 router 预设，选择一个空闲的回环端口，并存储生成的 baseUrl 和 localService 配置。聊天和本地嵌入通过常规的 OpenAI 兼容传输通道租用同一个托管 router。

不要在多台机器之间复制生成的 command 路径。请在每个 Gateway 主机上运行 llama.cpp 安装流程，以便 OpenClaw 选择和验证匹配的平台构建。参见 llama.cpp Provider。

配置结构¶

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

在 provider 条目上设置 timeoutSeconds（而不是在 localService 上），这样缓慢的冷启动和长时间生成不会触发默认的模型请求超时。当你的服务器在 base URL 上除 /models 之外的其他位置暴露就绪状态时，请设置显式的 healthUrl。

在 memory_search 期间，托管嵌入的启动使用 readyTimeoutMs，而不是搜索和查询嵌入的超时时间。这些计时器在服务就绪后恢复。嵌入请求、检索和结果处理保留其现有的时间限制。并发的 wiki 搜索和管理器清理保持各自的限制，调用方的取消操作仍可停止启动。

字段¶

字段	必填	描述
`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 退出。

字段	必需	描述

llmman 示例¶

llmman 是一个自定义的 OpenAI 兼容 /v1 后端，因此相同的 localService API 可用于 llmman 提供程序条目。默认情况下，它监听 127.0.0.1:17434；LLMMAN_HOST 会覆盖绑定地址，而 LLMMAN_LLM_LIBRARY 会覆盖 GPU 自动检测。其 API 没有身份验证，因此除非可信网络边界限制访问，否则请保持默认回环绑定。llmman 没有 /health 路由；请使用 /v1/models 或 /api/version 作为 healthUrl。

{
  agents: {
    defaults: {
      model: { primary: "llmman/qwen3.8" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      llmman: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/opt/homebrew/bin/llmman",
          args: ["serve"],
          env: { LLMMAN_CONTEXT_LENGTH: "65536" },
          healthUrl: "http://127.0.0.1:17434/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "qwen3.8",
            name: "Qwen3.8 (llmman)",
            reasoning: true,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 65536,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

将 command 替换为在运行 OpenClaw 的机器上执行 which llmman 的结果，并在 ~/.openclaw/.env 中设置 LLMMAN_API_KEY=llmman-local。直接运行 llmman serve 不需要模型参数，并会在首次请求中指定该模型时加载模型；可选的模型参数则会预先加载该模型。诸如 LLMMAN_CONTEXT_LENGTH 之类的守护进程设置应放在 env 中。完整的 llmman 设置，包括本地 + 托管混合路由：llmman。

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。

本地模型

本地模型设置、提供程序选择和安全指南。

llmman

本地模型、本地 + 托管混合路由，以及使用 llmman 的按需启动。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw