OpenClaw 接入 llmman 本地模型服务：OpenAI 兼容适配、按需启动与故障排查实战指南

OpenClaw 接入 llmman 本地模型服务OpenAI 兼容适配、按需启动与故障排查实战指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文围绕 OpenClaw 仓库中 docs/providers/llmman.md由/providers/inferrs重定向而来见 docs/docs.json展开讲解如何把自托管模型服务器 llmman 作为 OpenAI 兼容后端接入 OpenClaw。llmman 能从 OCI 镜像仓库拉取 GGUF/safetensors 模型并通过 Ollama、OpenAI、Anthropic 兼容 API 对外服务OpenClaw 通过通用的openai-completions适配器与之对话。读完本文你将掌握llmman 的启动与环境变量调优、OpenClaw 侧完整的 provider 配置、让 OpenClaw 按需拉起 llmman 进程的localService机制以及requiresStringContent、supportsTools等兼容性开关的适用场景与排查方法。llmman 是什么一个自托管的 OpenAI 兼容模型服务llmman 是一个自定义的自托管后端它从 OCI 镜像仓库Registry拉取 GGUF/safetensors 格式的模型文件然后在本地把它们服务在 Ollama、OpenAI、Anthropic 兼容的 API 之后。其中GGUF 模型由llama-server加载safetensors 模型则由vllm或mlx_lm.server提供推理能力。对 OpenClaw 而言llmman不是内置的 provider 插件而是一个自定义 OpenAI 兼容后端因此不能在 onboarding 授权选项里直接选择而要在models.providers.llmman下手动配置。两者之间的关键属性如下属性值Provider idllmman自定义在models.providers.llmman下配置插件无 —— 不是 OpenClaw 内置 provider 插件鉴权环境变量不需要任意值均可llmman serve本身无鉴权APIOpenAI 兼容openai-completions默认 base URLhttp://127.0.0.1:17434/v1版本说明本文内容以 llmman b315commit0e7a3ed为验证范围实际使用时请以你安装的 llmman 版本行为为准。如果你想要的是内置插件 自动发现的体验可以改用 OpenClaw 自带 provider 插件的 SGLang 或 vLLMllmman 的定位则是完全手动、高度可控的自定义后端。快速开始三步跑通本地 Gemma第 1 步用 llmman 启动一个模型LLMMAN_CONTEXT_LENGTH65536 llmman serve gemma4几个关键行为需要注意llmman serve默认监听127.0.0.1:17434。没有--host/--port参数要改绑定地址必须在启动前设置LLMMAN_HOST环境变量。GPU 加速CUDA、ROCm、Vulkan 或 Metal是自动检测的因为没有--device参数需要手动覆盖时通过LLMMAN_LLM_LIBRARY环境变量指定。model参数是可选的省略它时服务器先启动等第一个指名模型的请求到达时再加载对应模型。示例把服务端上下文固定为 65,536 tokensOpenClaw 侧配置也使用同一数值。如果你修改了LLMMAN_CONTEXT_LENGTH请保证 OpenClaw 模型条目里的contextWindow小于或等于该值避免上下文超限。第 2 步验证服务器可达curl http://127.0.0.1:17434/v1/models curl http://127.0.0.1:17434/api/versionllmman serve在顶层没有专门的/health路由就绪探针请使用/v1/models或/api/version。第 3 步添加 OpenClaw provider 条目在 OpenClaw 配置中显式添加 provider 条目并把默认模型指向它完整示例见下一节。完整配置示例Gemma 4 on llmman以下配置将默认模型指向llmman/gemma4并在models.providers.llmman下声明模型的元数据{ agents: { defaults: { model: { primary: llmman/gemma4 }, models: { llmman/gemma4: { alias: Gemma 4 (llmman), }, }, }, }, models: { mode: merge, providers: { llmman: { baseUrl: http://127.0.0.1:17434/v1, apiKey: llmman-local, api: openai-completions, models: [ { id: gemma4, name: Gemma 4 (llmman), reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 65536, maxTokens: 4096, }, ], }, }, }, }配置要点agents.defaults.model.primary使用llmman/gemma4这种provider/model-id引用格式是 OpenClaw 跨 provider 的模型引用约定api: openai-completions指定走通用 OpenAI 兼容适配器而不是openai-responses这对后面代理式行为一节有直接影响apiKey任意值即可llmman-local因为 llmman 本身不校验鉴权本地模型的成本直接标 0reasoning: false表示该模型无推理reasoning阶段。按需启动让 OpenClaw 自己拉起 llmman如果不想让 llmman 常驻后台可以在同一个 provider 条目上追加localService让 OpenClaw 在某个llmman/...模型被选中时才启动 llmman{ models: { 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, }, ], }, }, }, }localService的完整机制与字段说明见 docs/gateway/local-model-services.md其工作流程大致是某个模型/嵌入请求解析到配置了localService的 providerOpenClaw 先探测healthUrl探测成功 → 直接复用已在运行的服务器探测失败 → 以commandargs拉起子进程轮询健康端点直到readyTimeoutMs到期请求走正常的模型/嵌入传输通道若是 OpenClaw 启动的进程且设置了idleStopMs则在最后一个进行中的请求空闲超过该时长后停止进程。字段含义如下字段必填说明command是可执行文件的绝对路径不做 shell PATH 查找args否进程参数不做 shell 展开、管道、通配符或引号处理cwd否进程工作目录env否环境变量合并到 OpenClaw 进程环境之上healthUrl否就绪探测 URL默认取baseUrl追加/modelsreadyTimeoutMs否启动就绪截止时间默认120000idleStopMs否空闲停止延迟0或省略则保持进程存活直到 OpenClaw 退出针对 llmman 的实操建议command必须是绝对路径在 Gateway 主机上执行which llmman拿到真实路径后填入建议把timeoutSeconds放在provider 条目而非localService上避免冷启动慢、生成时间长时撞上默认模型请求超时llmman 默认监听 loopback且 API 无鉴权除非有可信网络边界做访问限制否则保持默认 loopback 绑定即可。OpenClaw 不会为此安装 launchd、systemd、Docker 或任何守护进程——llmman 只是第一个需要它的 OpenClaw 进程的普通子进程。启动按 provider command/args/env 集合串行化同一服务的并发聊天与嵌入请求不会拉起重复进程每个请求持有独立租约直到响应处理完成因此空闲停机会等待所有在途请求。高级配置三个兼容性开关与一个行为边界为什么requiresStringContent可能很重要llmman 会解析并加载被请求的模型、为所选后端改写模型 id并追加repeat_penalty之类的生成默认值。但它不会对消息内容和工具 schema 做归一化这些字段的兼容性取决于所选后端与模型。如果 OpenClaw 运行报错messages[1].content: invalid type: sequence, expected a string就在模型条目里设置compat.requiresStringContent: true。开启后OpenClaw 会在发送请求前把纯文本 content 部分拍平成普通字符串compat: { requiresStringContent: true }工具 schema 兼容性提醒如果模型能接受小的直接/v1/chat/completions请求却在完整的 OpenClaw agent 运行时轮次中失败可以优先尝试关闭工具 schema 面compat: { supportsTools: false }这会降低对更严格的本地后端的提示词压力。如果小直连请求能通、但正常 OpenClaw agent 轮次在llama-server内部持续崩溃应视为上游模型/服务器的限制而不是 OpenClaw 传输层的问题。手动冒烟测试分层验证配置完成后建议分两层测试curl http://127.0.0.1:17434/v1/chat/completions \ -H content-type: application/json \ -d {model:gemma4,messages:[{role:user,content:What is 2 2?}],stream:false}openclaw infer model run \ --model llmman/gemma4 \ --prompt What is 2 2? Reply with one short sentence. \ --json第一层验证 llmman 与模型本身第二层验证 OpenClaw 侧配置与传输。若第一个命令正常而第二个失败进入下面的排查清单。openclaw infer相关命令的完整用法可参考 docs/cli/infer.md。代理式行为不会发送原生 OpenAI 专属字段由于 llmman 走的是通用openai-completions适配器而非openai-responsesOpenAI 原生的请求塑形逻辑一概不生效不会发送service_tier、不会发送 Responsesstore、不会发送提示词缓存提示prompt-cache hints也不会有 OpenAI reasoning 兼容的载荷塑形。故障排查清单现象处置curl /v1/models失败llmman serve未运行或地址不可达。默认是127.0.0.1:17434若设置了LLMMAN_HOST请同步更新 OpenClaw 的baseUrl与healthUrl报错messages[].content expected a string在模型条目设置compat.requiresStringContent: true见上文直接/v1/chat/completions能通但openclaw infer model run失败两次探测都不带工具compat.supportsTools无法改变该现象。检查 base URL 与模型 id、查看 llmman/后端日志对比两次请求的载荷与响应模型 run 通过但正常 agent 轮次失败agent 轮次提示词更大、可能带工具 schema先用compat.supportsTools: false隔离工具 schema 压力llama-server在大 agent 轮次下仍崩溃schema 错误消除后仍崩溃属于上游 llama.cpp 或模型限制应降低提示词压力或更换后端/模型更通用的排障入口见 docs/help/troubleshooting.md 与 docs/help/faq.md针对本地 OpenAI 兼容后端直接探测通过但 agent 运行失败这类场景docs/gateway/troubleshooting.md 有专门小节。延伸阅读本地模型Local models让 OpenClaw 对接本地模型服务器的通用方法本地模型服务Local model services为配置好的 provider 按需启动本地模型服务器含 llmman 专属示例与全部字段说明Gateway 故障排查排查本地 OpenAI 兼容后端直接探测通过、agent 运行却失败模型与 provider 总览全部 provider、模型引用格式与故障转移行为llama.cpp Provider官方 llama.cpp provider 会自动生成localService形态配置可作为对照参考。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考