企业官网建设流程全解析

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下手动配置。两者之间的关键属性如下：

版本说明：本文内容以 llmman b315（commit0e7a3ed）为验证范围，实际使用时请以你安装的 llmman 版本行为为准。

如果你想要的是内置插件 + 自动发现的体验，可以改用 OpenClaw 自带 provider 插件的 SGLang 或 vLLM；llmman 的定位则是完全手动、高度可控的自定义后端。

快速开始：三步跑通本地 Gemma

第 1 步：用 llmman 启动一个模型

LLMMAN_CONTEXT_LENGTH=65536 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 tokens，OpenClaw 侧配置也使用同一数值。如果你修改了LLMMAN_CONTEXT_LENGTH，请保证 OpenClaw 模型条目里的contextWindow小于或等于该值，避免上下文超限。

第 2 步：验证服务器可达

curl http://127.0.0.1:17434/v1/models curl http://127.0.0.1:17434/api/version

llmman 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 本身不校验鉴权；
• 本地模型的成本直接标 0，reasoning: 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，其工作流程大致是：

1. 某个模型/嵌入请求解析到配置了localService的 provider；
2. OpenClaw 先探测healthUrl；
3. 探测成功 → 直接复用已在运行的服务器；
4. 探测失败 → 以command+args拉起子进程；
5. 轮询健康端点直到readyTimeoutMs到期；
6. 请求走正常的模型/嵌入传输通道；
7. 若是 OpenClaw 启动的进程且设置了idleStopMs，则在最后一个进行中的请求空闲超过该时长后停止进程。

字段含义如下：

针对 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-responses），OpenAI 原生的请求塑形逻辑一概不生效：不会发送service_tier、不会发送 Responsesstore、不会发送提示词缓存提示（prompt-cache hints），也不会有 OpenAI reasoning 兼容的载荷塑形。

故障排查清单

更通用的排障入口见 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