本地模型服务
models.providers.<id>.localService 会按需启动由 provider 拥有的本地模型服务器。当模型或 embedding 请求选择该 provider 时,OpenClaw 会检查健康端点,如果进程已停止则启动进程,等待就绪,然后发送请求。使用它可以避免昂贵的本地服务器整天保持运行。
工作原理¶
- 模型或 embedding 请求解析到一个已配置的 provider。
- 如果该 provider 有
localService,OpenClaw 会检查healthUrl。 - 检查成功时,OpenClaw 使用已在运行的服务器。
- 检查失败时,OpenClaw 使用
args启动command。 - OpenClaw 轮询健康端点,直到
readyTimeoutMs过期。 - 请求通过正常的模型或 embedding 传输层发送。
- 如果 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 进行按需启动。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw