跳转至

本地模型服务

models.providers.<id>.localService 会按需启动由 provider 拥有的本地模型服务器。当模型或 embedding 请求选择该 provider 时,OpenClaw 会检查健康端点,如果进程已停止则启动进程,等待就绪,然后发送请求。使用它可以避免昂贵的本地服务器整天保持运行。

工作原理

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

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

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

OpenClaw 在关闭本地服务时,会等待任何已在进行的空闲关闭完成。针对同一服务的新请求会等待该停止操作完成,然后再获取替代进程。关闭错误仍然可见;后续请求在启动替代进程之前会重新检查其拥有的进程。

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

如果另一个 OpenClaw 进程已经在相同的 healthUrl 上拥有健康的服务器,则当前进程会复用它,但不会接管它(每个进程只管理它亲自启动的子进程)。启动和退出日志包含有界、已脱敏的子进程输出尾部,以及计时和退出详情;配置的环境变量值永远不会被输出。

对于其固定版本的托管安装,llama.cpp 会在新的宿主进程中的第一个 local-service 请求之前检查孤儿服务器。在原生 Apple silicon macOS 上,只有当原生可执行文件恰好是该状态目录的托管二进制文件,并且其显式 host、port 和 preset 参数匹配时,它才会回收被 launchd 接管的 router;相对 preset 还要求配置的工作目录。它会捕获匹配的后代进程,发送 SIGTERM,最多等待五秒,必要时使用 SIGKILL。在每次发送信号前,都会重新检查进程出生时间和可执行文件身份。存活的父进程、自定义二进制文件、其他状态目录、没有唯一显式 host/port/preset 参数的配置,以及不同的 port 或 preset 都会保持不动。然后新的托管子进程正常启动,包括在之前的 Gateway 因 SIGHUP、SIGKILL 或崩溃退出之后。这不会改变继承的 nohup 信号处理。

请同时更新宿主和插件以启用恢复功能;不具备恢复能力的旧版兼容宿主会保持其现有的复用行为。 不支持原生进程身份识别的宿主、Linux 和 Windows 会保留现有的复用行为;Linux 上的 PID 1 本身可能是一个存活的 Gateway,因此仅凭父 PID 无法识别孤儿进程。在受支持的宿主上,如果无法安全地识别匹配的孤儿进程, 启动过程会报告其 PID,并要求你在重试前手动停止它。

托管 llama.cpp

官方 llama.cpp provider 会自动生成此配置形状。其引导式设置会安装固定版本且经过验证的 llama-server,写入绝对 command 和 router 预设,选择一个空闲的 loopback 端口,并保存生成的 baseUrl 和 localService 配置。聊天和本地 embedding 通过正常的 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 期间,托管 embedding 启动使用 readyTimeoutMs,而不是搜索和 query-embedding 超时。这些计时器会在服务就绪后恢复。Embedding 请求、检索和结果处理保留其现有时间限制。并发的 wiki 搜索和 manager 清理保留独立限制,调用方取消仍然可以停止启动。

字段

| 字段 | 必填 | 描述 |

字段 必填 描述
---------------- -------- ------------------------------------------------------------------------------------------------------------------------------------
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,
          },
        ],
      },
    },
  },
}

在运行 OpenClaw 的机器上,将 command 替换为 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