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 配置了localServiceOpenClaw 先探测healthUrl探测成功直接复用已在运行的服务器探测失败以commandargs拉起子进程轮询健康端点直到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字段被标记为sensitivez.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配置 Schemasrc/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否启动就绪的截止时间。默认120000120 秒。idleStopMs否OpenClaw 启动进程的空闲关闭延迟。0或省略表示保持运行直到 OpenClaw 退出。两点实现提示command不使用 PATH 查找意味着必须在配置中写入绝对路径如果路径写错或二进制未安装探测失败后的拉起会直接失败并反映在启动日志中env是合并叠加语义OpenClaw 自身环境中的同名变量会被覆盖但未提及的变量继续保留。五、实战一受管的 llama.cppManaged 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:17434LLMMAN_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本地 DeepSeekds4 示例使用本地 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: 3000005 分钟为 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），仅供参考 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 配置了localServiceOpenClaw 先探测healthUrl探测成功直接复用已在运行的服务器探测失败以commandargs拉起子进程轮询健康端点直到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字段被标记为sensitivez.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配置 Schemasrc/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否启动就绪的截止时间。默认120000120 秒。idleStopMs否OpenClaw 启动进程的空闲关闭延迟。0或省略表示保持运行直到 OpenClaw 退出。两点实现提示command不使用 PATH 查找意味着必须在配置中写入绝对路径如果路径写错或二进制未安装探测失败后的拉起会直接失败并反映在启动日志中env是合并叠加语义OpenClaw 自身环境中的同名变量会被覆盖但未提及的变量继续保留。五、实战一受管的 llama.cppManaged 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:17434LLMMAN_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本地 DeepSeekds4 示例使用本地 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: 3000005 分钟为 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），仅供参考