OpenClaw 本地模型服务（localService）：按需拉起本地模型服务器的完整指南-平芜编程栈

OpenClaw 本地模型服务（localService）：按需拉起本地模型服务器的完整指南

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

models.providers.<id>.localService是 OpenClaw Gateway 的按需本地模型服务机制：当一次模型或 Embedding 请求选中了某个配置了localService的 provider 时，OpenClaw 会先探测其健康端点，服务未运行时自动以子进程方式拉起，等待就绪后再发送请求，并可在空闲超时后自动关闭。本文围绕 docs/gateway/local-model-services.md 展开，完整覆盖其工作原理、完整配置结构、全部字段说明，以及 llama.cpp、llmman、ds4 三种实战接入示例，并结合仓库源码（配置 Schema 定义与相关文档）说明底层实现约束，帮助你为 OpenClaw 搭建"按需启动、用后即停"的本地模型服务。

一、localService 解决什么问题

本地模型服务器（vLLM、llama.cpp、MLX、Ollama、LM Studio 等）通常常驻内存，即使没有请求也会持续占用 GPU 显存与 CPU 资源。OpenClaw 的localService机制让本地模型服务器只在被真正选中时才启动：

模型或 Embedding 请求解析到配置了localService的 provider；
服务未运行时，由 OpenClaw 以普通子进程方式拉起（不依赖 launchd、systemd、Docker 或任何守护进程）；
请求完成后，可在空闲超时后自动停止进程，避免长时间空转。

这使得"昂贵"的本地推理资源（GPU 主机、大显存）可以在一天中大多数空闲时段保持关闭，只在需要时按需冷启动。相关背景可参阅 docs/gateway/local-models.md 中关于本地模型后端选型（ds4、LiteLLM 代理、llama.cpp、LM Studio、MLX/vLLM/SGLang、Ollama）的说明。

二、工作原理：从探测到空闲停止的完整流程

文档描述了如下七步生命周期：

模型或 Embedding 请求解析到某个已配置的 provider；
该 provider 配置了localService，OpenClaw 先探测healthUrl；
探测成功：直接复用已在运行的服务器；
探测失败：以command+args拉起子进程；
轮询健康端点直到readyTimeoutMs到期（超时则失败）；
请求走正常的模型或 Embedding 传输通道；
若进程由 OpenClaw 启动且设置了idleStopMs，则在最后一个在途请求空闲达到该时长后停止进程。

关键实现约束（均来自原文档，且与仓库 Schema 定义一致）：

不引入守护进程：服务器只是"第一个需要它的 OpenClaw 进程"的普通子进程。OpenClaw 不会为它安装 launchd/systemd 服务、Docker 容器或任何守护进程。
启动串行化：启动按 provider 与"command/参数/env 组合"串行化，因此并发的聊天与 Embedding 请求不会为同一服务拉起重复服务器。每个请求持有自己的 lease，直到响应处理完成才释放，所以空闲关闭会等待所有在途的模型与 Embedding 请求结束。
provider 别名保持独立：两个配置了不同别名的 provider 可以指向不同的 GPU 主机，而不会塌缩到同一个 Ollama/LM Studio/OpenAI 兼容适配器 id 上。
多进程复用但不接管：如果另一个 OpenClaw 进程在同一个healthUrl上已有健康服务，本进程直接复用，但不会"收养"它——每个进程只管理自己亲手启动的子进程。
日志安全：启动与退出日志包含有界、脱敏的子进程输出尾部及时间与退出信息；配置中的环境变量值绝不会出现在日志中。这与 src/config/zod-schema.core.ts 中env字段被标记为sensitive（z.record(z.string(), z.string().register(sensitive))）的实现是一致的——配置 Schema 层即对 env 值做了敏感注册，避免被快照/日志泄出。

关于 memory_search 的计时细节

在memory_search期间，受管 Embedding 服务的启动使用readyTimeoutMs作为超时，而不是搜索与查询 Embedding 的超时；服务就绪后，这些计时器恢复。Embedding 请求、检索与结果处理保持原有时间限制；并发的 wiki 搜索与 manager 清理保持独立限制，调用方的取消操作也可以随时中止启动流程。

三、配置结构：一个完整的 localService 示例

localService挂载在models.providers.<id>之下，与baseUrl、apiKey、api、timeoutSeconds、models等字段平级。以下为文档给出的完整配置形态：

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

配套要点：

timeoutSeconds必须设置在provider 条目上（而不是localService内部），这样慢冷启动与长生成不会撞上默认的模型请求超时；
当服务器的就绪探测点不在 baseUrl 的/models路径下时，显式设置healthUrl；
配置 Schema（src/config/zod-schema.core.ts）对每个字段的约束为：command非空字符串、args字符串数组、cwd非空字符串、env为字符串到字符串的记录（值注册为 sensitive）、healthUrl非空字符串、readyTimeoutMs为正整数、idleStopMs为非负整数，且该对象是strict()（严格模式）——即不允许出现上述字段之外的额外键。

四、字段速查表

字段	必填	说明
`command`	是	可执行文件的绝对路径。不做 shell PATH 查找。
`args`	否	进程参数。不做 shell 展开（无管道、glob、引号处理）。
`cwd`	否	进程的工作目录。
`env`	否	环境变量，合并叠加到 OpenClaw 进程自身环境之上。
`healthUrl`	否	就绪探测 URL。默认取`baseUrl`追加`/models`（如`http://127.0.0.1:8000/v1`→`http://127.0.0.1:8000/v1/models`）。
`readyTimeoutMs`	否	启动就绪的截止时间。默认：`120000`（120 秒）。
`idleStopMs`	否	OpenClaw 启动进程的空闲关闭延迟。`0`或省略表示保持运行直到 OpenClaw 退出。

两点实现提示：

command不使用 PATH 查找意味着必须在配置中写入绝对路径；如果路径写错或二进制未安装，探测失败后的拉起会直接失败并反映在启动日志中；
env是"合并叠加"语义，OpenClaw 自身环境中的同名变量会被覆盖，但未提及的变量继续保留。

五、实战一：受管的 llama.cpp（Managed llama.cpp）

官方 llama.cpp provider 会自动生成localService配置：

受引导的安装流程会安装一个固定版本并校验过的llama-server；
写入绝对路径的 command 与 router preset；
自动选择一个空闲的 loopback 端口；
将得到的baseUrl与localService配置一起保存；
聊天与本地 Embedding 通过常规 OpenAI 兼容传输共享同一个受管 router。

重要约束：不要在一台机器上拷贝生成的 command 路径到另一台机器使用。必须在每个 Gateway 主机上分别运行 llama.cpp setup，让 OpenClaw 选择并校验与当前平台匹配的构建。完整流程见 docs/plugins/llama-cpp.md。

六、实战二：llmman（自定义 OpenAI 兼容 /v1 后端）

llmman 是一个自定义的 OpenAI 兼容/v1后端，因此同样的localServiceAPI 可以直接用于 llmman provider 条目。它默认监听127.0.0.1:17434；LLMMAN_HOST可覆盖绑定地址，LLMMAN_LLM_LIBRARY可覆盖 GPU 自动检测。其 API 没有认证，因此除非有可信网络边界限制访问，否则请保持默认 loopback 绑定。

{ agents: { defaults: { model: { primary: "llmman/gemma4" }, }, }, models: { mode: "merge", providers: { llmman: { baseUrl: "http://127.0.0.1:17434/v1", apiKey: "llmman-local", api: "openai-completions", timeoutSeconds: 300, localService: { command: "/opt/homebrew/bin/llmman", args: ["serve", "gemma4"], env: { LLMMAN_CONTEXT_LENGTH: "65536" }, healthUrl: "http://127.0.0.1:17434/v1/models", readyTimeoutMs: 180000, idleStopMs: 0, }, models: [ { id: "gemma4", name: "Gemma 4 (llmman)", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 65536, maxTokens: 4096, }, ], }, }, }, }

操作提示：

将command替换为运行 OpenClaw 的机器上which llmman的输出（绝对路径）；
该示例将llmman设为默认主模型（agents.defaults.model.primary），并保持models.mode: "merge"以便托管模型可作兜底（与 docs/gateway/local-models.md 中混合配置建议一致）；
完整 llmman 安装说明见 docs/providers/llmman.md。

七、实战三：ds4（本地 DeepSeek）

ds4 示例使用本地 GGUF 模型文件启动ds4-server：

{ 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_DIR>需替换为实际的 ds4 安装目录（命令行中出现了绝对路径依赖）；
--ctx 32768控制上下文窗口、--tokens 128控制单次生成的 token 上限，需要根据硬件显存/内存调整；
readyTimeoutMs: 300000（5 分钟）为 GGUF 大模型冷加载预留了较长的就绪时间；
models: []表示模型清单为空——模型 id 等元数据由 ds4 侧提供，OpenClaw 通过该 provider 路由请求；
完整安装、上下文尺寸与验证命令见 docs/providers/ds4.md。

八、组合建议与安全提示

将localService与 docs/gateway/local-models.md 中的本地模型最佳实践组合使用时，请注意：

超时分层：models.providers.<id>.timeoutSeconds覆盖连接、请求头、响应体流式传输以及受管抓取的总中止时间；若 agent/run 超时更低，需要同步调高，但 provider 超时无法延长整个 run 的时长。
冷启动验证：本地模型能加载或回答短 prompt 不等于能完成完整 agent 回合。建议先用openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json验证模型响应，再用--gateway验证路由与鉴权，最后用真实任务验证工具调用与上下文预算。
安全边界：本地模型没有托管 provider 的安全过滤。llmman 等无认证服务务必保持 loopback 绑定；远程自定义 provider 的请求需要满足 private-network 信任配置（models.providers.<id>.request.allowPrivateNetwork: true）等条件。
空闲停止权衡：idleStopMs: 0（或省略）表示进程常驻到 OpenClaw 退出，适合需要持续低延迟的场景；设置正数空闲延迟可回收资源，但每次空闲后的首次请求会重新经历冷启动。默认readyTimeoutMs为 120000 ms，可根据模型加载耗时上调（如 ds4 示例使用 300000）。

九、小结

localService把"本地模型服务器生命周期管理"完全收进 OpenClaw 配置层：探测 → 拉起 → 就绪轮询 → 传输 → 空闲停止，全部由 Gateway 按需驱动，无需手工管理守护进程。配合官方 llama.cpp 的引导安装，或 llmman/ds4 等自定义 OpenAI 兼容后端的手写配置，即可在保留本地推理隐私优势的同时，避免服务器常驻带来的资源浪费。更多背景可继续阅读 docs/gateway/local-models.md、docs/gateway/configuration-reference.md 与 docs/concepts/model-failover.md。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考