跳转至

llmman

llmman 将模型作为 OCI 构件从任何注册表或 Hugging Face 拉取,并通过未经修改的上游引擎提供服务:llama-server 用于 GGUF,vllm 或 mlx-lm 用于 safetensors。一个守护进程暴露兼容 Ollama、OpenAI 和 Anthropic 的 API,并且还可以将请求转发给托管提供商。OpenClaw 通过通用的 openai-completions 适配器在 /v1 上与之通信。

支持三种模式:

模式 使用方式
仅本地 在 Gateway 主机或 LAN 上运行 llmman serve,为诸如 qwen3.8 的已拉取模型提供服务
混合 一个 llmman.hybrid/<local>,<provider>/<model> 引用;llmman 根据每个请求选择本地或托管侧
通过 llmman 托管 llmman.provider/<provider>/<model> 引用;llmman 在保持一个本地端点的同时将请求转发到托管提供商
属性 值
提供商 ID llmman(自定义;在 models.providers.llmman 下配置)
插件 无;不是 OpenClaw 内置提供商插件,因此模型需明确列出
API 兼容 OpenAI(api: "openai-completions")
默认基础 URL http://127.0.0.1:17434/v1
认证 llmman 没有身份验证;OpenClaw 将您配置的 apiKey 作为 bearer 发送
参考模型 qwen3.8(Qwen3.8 27B,支持视觉,原生上下文 262,144 token)

Warning

llmman serve 没有身份验证,也没有 TLS。除非受信任的网络边界限制访问,否则请保持默认的环回绑定,切勿将其暴露在公共接口上。

Info

版本范围:本页面已针对 llmman v0.1.334 及提交 22b6d73 进行验证。本页面中的模型名称、混合路由、视觉和工具调用均使用 qwen3.8 在该构建上进行了测试。

认证规则

本地 llmman 无认证

llmman serve 从不检查凭据。OpenClaw 仍然需要在提供商条目上配置非空的 apiKey,该提供商才会被视为已配置。本页面使用 LLMMAN_API_KEY=llmman-local 配合 apiKey: "${LLMMAN_API_KEY}",与 OLLAMA_API_KEY=ollama-local 的约定保持一致。使用字面量 apiKey: "llmman-local" 同样可行。

混合引用和托管引用中的 bearer 很重要

对于 llmman.hybrid/... 和 llmman.provider/... 引用,llmman 会将 OpenClaw 提交的 bearer 作为该托管提供商的 API 密钥转发。唯一的例外是字面量占位符 llmman,它告诉守护进程使用自己的密钥。参见 混合推理 了解这两种模式。诸如 llmman-local 这样的标记会被发送到托管提供商并在那里被拒绝。

远程 llmman 主机

在环境中以 LLMMAN_HOST=0.0.0.0 启动的守护进程会绑定所有接口,且没有认证。仅在您信任的网络中让 OpenClaw 指向 LAN 主机;OpenClaw 无法发送任何 llmman 会强制检查的凭据。可通过非环回地址访问的守护进程也拒绝为未提供任何密钥的调用方使用其自身的托管提供商密钥。

环境变量替换

${LLMMAN_API_KEY} 从 Gateway 进程环境或 ~/.openclaw/.env 中解析。如果该变量缺失,OpenClaw 会记录配置警告并将该提供商视为不可用,因此请将 export 放在 Gateway 可读取的位置。参见 环境。

快速开始

1. 安装 llmman

curl -fsSL https://llmmanorg.github.io/install.sh | sh   # Linux, macOS
brew install llmmanorg/tap/llmman                         # Homebrew

Windows:irm https://llmmanorg.github.io/install.ps1 | iex 或 winget install llmmanorg.llmman。其他方式:cargo binstall llmman。

2. 拉取模型并启动服务器

llmman pull qwen3.8
llmman serve

像 qwen3.8 这样的裸名称会解析到 Docker Hub 精选的 docker.io/ai/<name>:latest。owner/repo 名称解析到 hf.co/owner/repo;完整引用(ghcr.io/...、hf.co/...)会按原样使用。

llmman serve 不需要参数(可选的模型参数会预加载该模型):它监听 127.0.0.1:17434,并在第一个指定该模型的请求时加载任何已拉取的模型,然后在空闲五分钟后将其卸载。GPU 加速(CUDA、ROCm、Vulkan、Metal)会自动检测,如果 PATH 中没有匹配的 llama-server,则会下载它。其他一切通过守护进程的环境进行调优:LLMMAN_HOST 用于绑定地址,LLMMAN_CONTEXT_LENGTH 用于服务器上下文,LLMMAN_KEEP_ALIVE 用于空闲卸载计时器(参见 高级配置)。

默认情况下,llmman 最多使用 262,144 个 token,上限为模型训练时的上下文长度(qwen3.8 为 262,144),并且在内存不足时会重试,将上下文减半,直到 16,384 的下限。llmman ps 显示已加载模型实际获得的上下文;请将 OpenClaw 模型的 contextWindow 保持在该值或以下。

3. 验证服务器

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

没有 /health 路由;请使用 /api/version 或 /v1/models 作为就绪检查。/v1/models 会列出完全限定的 ID,例如 docker.io/ai/qwen3.8:latest;请求可以使用该形式,也可以使用短名称。

4. 设置标记凭据

添加到 ~/.openclaw/.env(或在 Gateway 的 shell 中导出):

LLMMAN_API_KEY=llmman-local

5. 添加提供商并选择模型

添加以下配置,然后:

openclaw models list --provider llmman
openclaw models set llmman/qwen3.8

Note

llmman launch openclaw --model qwen3.8 可以通过针对 llmman 端点运行非交互式引导流程,来引导首次运行的 OpenClaw 安装。它仅在尚不存在 openclaw.json 时适用;对于现有安装,请使用本页中的显式配置。

完整配置示例

本地 llmman 服务器上的 Qwen3.8:

{
  agents: {
    defaults: {
      model: { primary: "llmman/qwen3.8" },
      models: {
        "llmman/qwen3.8": { alias: "Qwen3.8 (llmman)" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      llmman: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        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,
          },
        ],
      },
    },
  },
}

models.mode: "merge" 可保留托管提供商作为回退。timeoutSeconds 为冷启动模型加载和长生成留出空间,避免模型请求超时触发。

模型发现

llmman 不是 OpenClaw 捆绑插件,因此没有隐式发现。请在 models.providers.llmman.models 下列出所有需要的模型,并使用提供商本地 id(不带 llmman/ 前缀)。

行为 详情
模型 ID 短名称(qwen3.8、qwen3.5:9b)、Hugging Face(unsloth/Qwen3.5-0.8B-GGUF)或完全限定名称(docker.io/ai/qwen3.8:latest)均可使用
默认标签 省略时为 :latest
能力 当存在配套的 mmproj 投影器时,llmman show <model> 和 POST /api/show 会报告 completion 以及 vision;将此类模型标记为 input: ["text", "image"]
推理 对于 Qwen3.8 等思考模型,请设置 reasoning: true;llmman 会将思考内容作为 reasoning_content 返回
上下文 llmman show <model> 会打印训练上下文长度;llmman ps 会打印运行中服务器启动时使用的上下文
成本 全部为 0;混合引用的托管部分由该提供商计费,OpenClaw 不跟踪
llmman list
llmman show qwen3.8
openclaw models list --provider llmman

要添加模型,请拉取它并添加匹配条目:

llmman pull qwen3.5:9b

冒烟测试

一个跳过完整代理工具集的窄范围文本检查:

LLMMAN_API_KEY=llmman-local \
  openclaw infer model run \
    --local \
    --model llmman/qwen3.8 \
    --prompt "Reply with exactly: pong" \
    --json

添加 --file 并指定图像,以进行精简的视觉模型检查(PNG/JPEG/WebP; 非图像文件会在调用 llmman 之前被拒绝;音频请使用 openclaw infer audio transcribe):

LLMMAN_API_KEY=llmman-local \
  openclaw infer model run \
    --local \
    --model llmman/gemma4:e4b \
    --prompt "Describe this image in one sentence." \
    --file ./photo.jpg \
    --json

这两条路径都不会加载聊天工具、内存或会话上下文。如果检查成功而正常代理回复失败,问题通常在于后端中的工具模式处理或上下文压力,而不是端点;参见 故障排除。

带有工具调用的完整代理回合才是真正的测试:

openclaw agent --local --session-id llmman-smoke \
  --message "Read the file ./README.md with a tool and summarize it in one sentence."

混合推理

llmman 可以在单个模型名称下将本地模型与托管模型配对,并按请求选择一侧。OpenClaw 只需将该配对配置一次为普通模型 ID,即可获得本地优先推理和托管溢出,而无需代理级回退开关。

引用格式为 llmman.hybrid/<local>,<provider>/<model>。以 qwen3.8 作为本地部分,OpenAI 的 gpt-5.6-luna 作为托管部分:

llmman.hybrid/qwen3.8,openai/gpt-5.6-luna

哪一侧处理请求:

  1. x-llmman-route: local 或 cloud 请求头优先。任何其他值都会返回 400。
  2. 否则,按大小。 请求体大于本地上下文可容纳范围时,会发送到托管模型。预算为 LLMMAN_CONTEXT_LENGTH 每个 token 4 字节;LLMMAN_HYBRID_LOCAL_BYTES 可直接设置该值,0 会禁用大小规则。
  3. 否则,使用本地。

如果 llmman 保留在本地处理的请求随后被本地后端以超出其上下文为由拒绝,llmman 会在任何内容到达 OpenClaw 之前将其重新发送到托管部分。local 固定永远不会以这种方式被覆盖。每个路由请求都会记录其侧别和原因。原始补全响应可能报告后端模型或 GGUF 路径;OpenClaw 的结果封装会保留已配置的配对引用。

托管提供商密钥

托管部分像任何 llmman --provider 请求一样进行身份验证。选择其一:

将 llmman 提供商的 apiKey 设置为托管提供商的密钥。llmman 会按请求转发它,并且从不持久化它。同一提供商条目中仅限本地的模型会忽略该值。

    # ~/.openclaw/.env
    LLMMAN_API_KEY=sk-...   # your OpenAI API key
    ```

    请在下面的配置中保留 `apiKey: "${LLMMAN_API_KEY}"`。

=== "llmman 持有密钥"

    为守护进程提供它自己的密钥,并让 OpenClaw 发送字面占位符 `llmman`:

    ```bash
    llmman config set providers.openai.api_key sk-...
    llmman serve
    ```

    守护进程环境中的 `OPENAI_API_KEY` 也可以,并且会覆盖配置文件。

    ```bash
    # ~/.openclaw/.env
    LLMMAN_API_KEY=llmman
    ```

    占位符必须恰好是 `llmman`;任何其他 bearer 令牌都会被当作真实密钥并转发到托管提供商。llmman 仅对回环调用方消耗自己的密钥,因此此模式要求守护进程和 Gateway 位于同一主机上。

### 混合配置 {#hybrid-config}

```json5
{
  agents: {
    defaults: {
      model: { primary: "llmman/llmman.hybrid/qwen3.8,openai/gpt-5.6-luna" },
      models: {
        "llmman/llmman.hybrid/qwen3.8,openai/gpt-5.6-luna": { alias: "Qwen3.8 + Luna" },
        "llmman/qwen3.8": { alias: "Qwen3.8 local" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      llmman: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "llmman.hybrid/qwen3.8,openai/gpt-5.6-luna",
            name: "Qwen3.8 + GPT-5.6 Luna (hybrid)",
            reasoning: true,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 65536,
            maxTokens: 8192,
          },
          {
            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,
          },
        ],
      },
    },
  },
}

守护进程在启动时计算一个混合字节预算:LLMMAN_CONTEXT_LENGTH 的每个 token 4 字节,未设置时为 262144 × 4 = 1048576 字节。此预算不会遵循模型的训练上下文上限,也不会遵循后续的内存不足缩减。在守护进程环境中设置 LLMMAN_CONTEXT_LENGTH=65536 以匹配示例,或设置 LLMMAN_HYBRID_LOCAL_BYTES 直接选择字节预算。显式设置 LLMMAN_CONTEXT_LENGTH=0 会禁用基于大小的路由,除非正的 LLMMAN_HYBRID_LOCAL_BYTES 提供了预算;将字节覆盖值设置为 0 也会禁用该规则。除非请求被固定为本地,否则本地上下文拒绝回退仍然适用。

将配对上的 contextWindow 设置为本地模型可用的 token 上下文。然后 OpenClaw 会围绕本地模型的限制进行上下文压缩,因此大多数轮次保持本地;当请求超过该限制时,llmman 仍会溢出到 gpt-5.6-luna。如果你希望减少压缩并增加托管流量,可以将其设置为托管模型的窗口。

固定一侧

OpenClaw 会在每个请求上发送提供商级别的 headers,因此同一 base URL 上的第二个提供商条目可以强制使用配对的一侧:

{
  models: {
    providers: {
      llmman: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "llmman.hybrid/qwen3.8,openai/gpt-5.6-luna",
            name: "Hybrid",
            input: ["text", "image"],
          },
        ],
      },
      "llmman-cloud": {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        headers: { "x-llmman-route": "cloud" },
        models: [
          {
            id: "llmman.hybrid/qwen3.8,openai/gpt-5.6-luna",
            name: "Hybrid (hosted)",
            input: ["text", "image"],
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "llmman/llmman.hybrid/qwen3.8,openai/gpt-5.6-luna",
        fallbacks: ["llmman-cloud/llmman.hybrid/qwen3.8,openai/gpt-5.6-luna"],
      },
    },
  },
}

对于应该走托管的轮次,使用 /model llmman-cloud/... 切换;或者对于必须永不离开本机的条目,使用 headers: { "x-llmman-route": "local" }。

混合模式与 OpenClaw 回退

机制 决策位置 切换条件
llmman 混合对 每个请求,在 llmman 内部 请求大小与本地上下文比较,或显式路由头
agents.defaults.model.fallbacks 每轮,在 OpenClaw 内部 提供商错误、超时、速率限制、认证失败

它们可以组合。一种常见形式是将混合对作为 primary,并将直接托管模型作为回退,以应对 llmman 本身宕机的情况:

{
  agents: {
    defaults: {
      model: {
        primary: "llmman/llmman.hybrid/qwen3.8,openai/gpt-5.6-luna",
        fallbacks: ["openai/gpt-5.6-luna"],
      },
    },
  },
}

通过 llmman 使用托管模型

llmman.provider/<provider>/<model> 会转发到没有本地部分的托管提供商。当你希望所有模型(本地或托管)都位于一个端点和一套密钥处理流程之后时,请使用它:

{
  models: {
    providers: {
      llmman: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "qwen3.8", name: "Qwen3.8 (llmman)", reasoning: true, input: ["text", "image"] },
          {
            id: "llmman.provider/openai/gpt-5.6-luna",
            name: "GPT-5.6 Luna via llmman",
            reasoning: true,
            input: ["text", "image"],
          },
        ],
      },
    },
  },
}

提供商目录来自 models.dev,并由守护进程缓存。llmman providers 显示哪些提供商拥有密钥;llmman list --provider openai 列出该提供商的模型和价格。若要直接访问托管服务而不经过 llmman,请改为配置 OpenAI 提供商。

视觉与图像描述

附带配套 mmproj 投影器的模型具备视觉能力;qwen3.8 和 gemma4:e4b 就是。llmman show <model> 会记录 found companion mmproj file, /api/show 会报告 vision 能力。将这些模型标记为 input: ["text", "image"],以便将图像附件注入到代理轮次中。

llmman pull gemma4:e4b
openclaw infer image describe --file ./photo.jpg --model llmman/gemma4:e4b --json

--model 必须是完整的 <provider/model> 引用。对于 OpenClaw 的图像理解流程 以及已配置的 imageModel,请使用 infer image describe;对于使用自定义提示词 的原始多模态检查,请使用 infer model run --file。

要将某个 llmman 模型设为入站媒体的默认图像理解提供方:

{
  agents: {
    defaults: {
      imageModel: {
        primary: "llmman/gemma4:e4b",
      },
    },
  },
  models: {
    providers: {
      llmman: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        models: [{ id: "gemma4:e4b", name: "Gemma 4 E4B (llmman)", input: ["text", "image"] }],
      },
    },
  },
  tools: {
    media: {
      image: {
        timeoutSeconds: 180,
      },
    },
  },
}

OpenClaw 会拒绝针对未标记为图像能力的模型的图像描述请求。较慢的本地视觉模型 可能需要比托管模型更长的图像理解超时时间;models.providers.llmman.timeoutSeconds 仍然控制普通模型调用的底层 HTTP 请求。

配置

{
  models: {
    providers: {
      llmman: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "qwen3.8",
            name: "Qwen3.8 (llmman)",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 65536,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
在 GPU 机器上启动服务器,并在其环境中设置 `LLMMAN_HOST=0.0.0.0`
(可选设置 `LLMMAN_CONTEXT_LENGTH=65536`),然后将 OpenClaw 指向它:

```bash
llmman serve
```

```json5
{
  models: {
    providers: {
      llmman: {
        baseUrl: "http://gpu-box.local:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 420,
        models: [
          {
            id: "qwen3.8",
            name: "Qwen3.8 (gpu-box)",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 65536,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
```

Warning

远程守护进程没有身份验证。仅在受信任的网络内执行此操作,并且不要针对非回环守护进程使用“llmman 持有密钥”的混合引用;它会拒绝为远程调用方消耗自己的密钥。

当请求 llmman/... 模型时,OpenClaw 会按需启动 llmman。此示例让守护进程保持运行, 直到 OpenClaw 退出(idleStopMs: 0)。设置一个正的 idleStopMs,可在相应数量的 空闲毫秒后停止由 OpenClaw 启动的守护进程;这与 llmman 卸载空闲模型是分开的:

{
  models: {
    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"],
            contextWindow: 65536,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

command 必须是绝对路径;请使用 Gateway 主机上 which llmman 的输出。 env 是此处提供守护进程设置(例如 LLMMAN_CONTEXT_LENGTH)的方式。 healthUrl 必须是 /v1/models 或 /api/version,因为 llmman 没有 /health。 启动后的第一个请求还会加载模型,因此请保持 timeoutSeconds 足够宽松。 完整字段参考:本地模型服务。

常用配方

将模型 ID 替换为 llmman list 或 openclaw models list --provider llmman 中的名称。

本地 Qwen3.8 作为默认代理模型
llmman pull qwen3.8
llmman serve
echo 'LLMMAN_API_KEY=llmman-local' >> ~/.openclaw/.env
openclaw models set llmman/qwen3.8

对于提供方条目,请使用完整配置示例,如果希望服务器上下文与其完全匹配, 请在守护进程环境中设置 LLMMAN_CONTEXT_LENGTH=65536。

本地优先,托管溢出

上述混合配置:将 llmman.hybrid/qwen3.8,openai/gpt-5.6-luna 设为 primary, 将 LLMMAN_API_KEY 设置为 OpenAI 密钥,并使 LLMMAN_CONTEXT_LENGTH 与该组合的 contextWindow 匹配。将 openai/gpt-5.6-luna 添加到 fallbacks, 以便守护进程停止时不会阻塞回复。

小型本地配置

通过自定义 openai-completions 提供方提供的本地模型在未设置时会自动使用结构化 工具搜索。下面的显式设置固定了该能力面, 在保持可选能力可用的同时,仅在需要时加载其架构。在守护进程环境中使用 LLMMAN_CONTEXT_LENGTH=32768,将上下文限制为主机可运行的范围:

    {
      agents: {
        defaults: {
          model: { primary: "llmman/qwen3.8" },
        },
      },
      tools: {
        toolSearch: { mode: "tools" },
      },
      models: {
        providers: {
          llmman: {
            baseUrl: "http://127.0.0.1:17434/v1",
            apiKey: "${LLMMAN_API_KEY}",
            api: "openai-completions",
            models: [
              {
                id: "qwen3.8",
                name: "Qwen3.8 (llmman)",
                reasoning: true,
                input: ["text", "image"],
                contextWindow: 32768,
                contextTokens: 32768,
                maxTokens: 4096,
              },
            ],
          },
        },
      },
    }
    ```

    仅当模型或服务器在工具模式上可靠地失败时,才使用 `compat.supportsTools: false`;它会完全禁用工具使用。对于有意缩小范围的 agent,请优先使用 `tools.profile` 或按 agent 配置的工具策略。

??? note "多个 llmman 主机"

    运行多个守护进程时使用自定义 provider id;每个守护进程拥有自己的主机、模型和超时:

    ```json5
    {
      models: {
        providers: {
          "llmman-fast": {
            baseUrl: "http://mini.local:17434/v1",
            apiKey: "${LLMMAN_API_KEY}",
            api: "openai-completions",
            models: [{ id: "qwen3.5:9b", name: "qwen3.5:9b", input: ["text"], contextWindow: 32768 }],
          },
          "llmman-large": {
            baseUrl: "http://gpu-box.local:17434/v1",
            apiKey: "${LLMMAN_API_KEY}",
            api: "openai-completions",
            timeoutSeconds: 420,
            models: [{ id: "qwen3.8", name: "qwen3.8", reasoning: true, input: ["text", "image"], contextWindow: 131072 }],
          },
        },
      },
      agents: {
        defaults: {
          model: {
            primary: "llmman-fast/qwen3.5:9b",
            fallbacks: ["llmman-large/qwen3.8"],
          },
        },
      },
    }
    ```

    llmman 本身也可以池化多个守护进程:`llmman config set aggregation.peers <host>,<host>`(或 `LLMMAN_PEERS`)会让一个守护进程转发到对等节点,因此 OpenClaw 会看到一个端点,其模型列表覆盖整个组。

??? note "Hugging Face 或私有注册表模型"

    模型 id 可以是 llmman 解析的任何值。使用完整引用拉取,并将相同字符串用作 OpenClaw 模型 id:

    ```bash
    llmman pull hf.co/unsloth/Qwen3.5-0.8B-GGUF
    llmman pull ghcr.io/myorg/private-model:v1
    ```

    ```json5
    {
      models: {
        providers: {
          llmman: {
            baseUrl: "http://127.0.0.1:17434/v1",
            apiKey: "${LLMMAN_API_KEY}",
            api: "openai-completions",
            models: [
              { id: "hf.co/unsloth/Qwen3.5-0.8B-GGUF", name: "Qwen3.5 0.8B", input: ["text"] },
              { id: "ghcr.io/myorg/private-model:v1", name: "Private model", input: ["text"] },
            ],
          },
        },
      },
    }
    ```

    然后 agent 引用为 `llmman/hf.co/unsloth/Qwen3.5-0.8B-GGUF`。对于私有注册表,请先运行 `llmman login <registry>`。

### 模型选择 {#model-selection}

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "llmman/qwen3.8",
        fallbacks: ["llmman/qwen3.5:9b", "openai/gpt-5.6-luna"],
      },
    },
  },
}

对于较慢的本地模型,在提高整个 agent 运行时超时之前,请优先进行 provider 范围调优:models.providers.llmman.timeoutSeconds 仅覆盖该 provider 模型请求的连接建立、请求头、正文流式传输以及总 guarded-fetch 中止。

快速验证

# llmman daemon visible to this machine
curl http://127.0.0.1:17434/api/version
llmman ps

# OpenClaw catalog and selected model
openclaw models list --provider llmman
openclaw models status

# Direct model smoke
LLMMAN_API_KEY=llmman-local openclaw infer model run \
  --local --model llmman/qwen3.8 --prompt "Reply with exactly: ok" --json

对于远程主机,请将 127.0.0.1 替换为 baseUrl 主机。如果 curl 可以工作但 OpenClaw 不行,请检查 Gateway 是否运行在不同的机器、容器或服务账户上。

高级配置

上下文窗口

LLMMAN_CONTEXT_LENGTH 是服务器端上下文(没有相应标志)。按后端的语义如下:

  • llama-server (GGUF): 已设置时,它会作为生成模型的 --ctx-size 传入;0 表示训练上下文。未设置时,llmman 使用 262144,如果模型训练上下文更小则使用模型训练上下文,并在内存不足时以减半的上下文重试,下限为 16,384。
  • vLLM (safetensors): 正值会变为 --max-model-len;未设置时使用 vLLM 默认值。
  • mlx_lm.server: 不会转发。

LLMMAN_NUM_PARALLEL 会按该因子放大 --ctx-size,使每个槽位保留完整上下文。

在 OpenClaw 端,contextWindow 声明模型的窗口,contextTokens 限制活动输入。请将 contextWindow 保持在服务器值或以下;OpenClaw 会据此推导压缩和预检阈值。OpenClaw 的 contextWindow 不会更改 llmman 的混合字节预算;请按照 混合配置 中的说明单独配置守护进程。

{
  models: {
    providers: {
      llmman: {
        models: [
          {
            id: "qwen3.8",
            name: "qwen3.8",
            contextWindow: 65536,
            contextTokens: 49152,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
思考控制

Qwen3.8 默认会思考;llmman 将推理作为 reasoning_content 返回,OpenClaw 的 openai-completions 适配器会将其与最终文本分开。请求会被代理到 llama-server,因此 chat_template_kwargs 会透传。要在本地 Qwen 模型的 agent 回合中关闭思考:

{
  agents: {
    defaults: {
      models: {
        "llmman/qwen3.8": {
          params: {
            chat_template_kwargs: { enable_thinking: false },
          },
        },
      },
    },
  },
}

对于按运行或会话控制,请声明本地 Qwen 模型的思考格式:

```json5
{
  models: {
    providers: {
      llmman: {
        models: [
          {
            id: "qwen3.8",
            name: "Qwen3.8 (llmman)",
            reasoning: true,
            input: ["text", "image"],
            compat: { thinkingFormat: "qwen-chat-template" },
          },
        ],
      },
    },
  },
}
```

有了此声明,`openclaw agent --model llmman/qwen3.8 --thinking off`、`/think off` 和 `openclaw infer model run --local --model llmman/qwen3.8 --thinking off --prompt "Reply with exactly: pong" --json` 会将思考设置映射到 `chat_template_kwargs.enable_thinking`。如果没有它,通用代理默认值不会发送此控制项或 `reasoning_effort`。

精简的 `infer model run` 路径不会读取上述代理级别的 `params` 配方;对于该检查,请使用兼容性声明和 `--thinking off`。不要将固定的 `enable_thinking` 代理参数与按运行控制结合使用,因为固定参数会覆盖生成的值。仅当混合引用的本地和托管后端都接受 Qwen 特定控制项时,才将其应用于混合引用。
模型生命周期与保活

模型在首次请求时加载,每个模型都在自己的后端子进程中,并在空闲五分钟后卸载。可通过以下方式调整:

变量 含义
LLMMAN_KEEP_ALIVE 空闲卸载计时器(默认 5m);0 表示每次请求后立即卸载
LLMMAN_MAX_LOADED_MODELS 并发加载模型的上限;空闲模型按 LRU 逐出,繁忙模型返回 503
LLMMAN_MAX_QUEUE 触发 503 之前的待处理请求上限(默认 512)
LLMMAN_LOAD_TIMEOUT 加载停滞超时(默认 10m)

llmman ps 显示已加载模型及其上下文和过期时间;llmman stop <model> 立即卸载一个模型。启动后或空闲卸载后的首次请求需要支付加载成本,因此请在 provider 上设置 timeoutSeconds,并提高 LLMMAN_KEEP_ALIVE 以保持守护进程处于热状态,用于聊天界面。

GPU 与后端选择

llmman 会检查 CUDA、ROCm、Vulkan(Linux/Windows)或 Metal(macOS),如果 PATH 中没有,则下载匹配的 llama-server 发行版。使用 LLMMAN_LLM_LIBRARY 覆盖:cpu、cuda、cuda13、rocm、vulkan 或 metal。其他选项:LLMMAN_FLASH_ATTENTION(on/off/auto)、LLMMAN_KV_CACHE_TYPE(f16、q8_0、q4_0)、用于多 GPU 层拆分的 LLMMAN_SCHED_SPREAD、用于计入集成 GPU 的 LLMMAN_IGPU_ENABLE。在 Linux 上,llmman serve --ociman docker|podman 会从 ghcr.io/ggml-org/llama.cpp 镜像中运行 llama-server,而不是本地二进制文件。LLMMAN_DEBUG=1 会打印检查结果。

内存嵌入

llmman 为 GGUF 嵌入模型提供 /v1/embeddings,因此 内存搜索 可以通过通用 openai-compatible 嵌入 provider 使用它:

llmman pull embeddinggemma
{
  memory: {
    search: {
      provider: "openai-compatible",
      model: "embeddinggemma",
      remote: {
        baseUrl: "http://127.0.0.1:17434/v1",
        apiKey: "${LLMMAN_API_KEY}",
      },
    },
  },
}

嵌入模型会被限制在其训练上下文内,无论 LLMMAN_CONTEXT_LENGTH 如何设置。其余字段参见 内存配置。

Ollama 兼容 API

llmman 还实现了 Ollama 原生的 /api/chat、/api/tags、/api/show 和 /api/ps,并且 OLLAMA_HOST=127.0.0.1:17434 ollama run <model> 可以针对它工作。无论如何,请优先从 OpenClaw 使用 api: "openai-completions":llmman 的 /api/show 仅报告 completion 和 vision 能力,因此内置 Ollama 插件的发现机制会将每个 llmman 模型标记为 compat.supportsTools: false。如果你确实将 Ollama 插件指向 http://127.0.0.1:17434(不带 /v1),请显式列出模型,而不是依赖发现机制。

兼容标志

llmman 会将消息内容和工具 schema 转发到后端,而不会对其进行规范化,因此兼容性取决于所选引擎和模型。结构化内容部分(文本 + 图像)和 OpenClaw 的完整工具 schema 在 llama-server 上与 qwen3.8 配合使用。如果其他后端或模型拒绝它们:

  • messages[].content: invalid type: sequence, expected a string → 在模型条目上设置 compat.requiresStringContent: true。OpenClaw 随后会将纯文本内容部分展平为普通字符串。
  • 400 JSON schema conversion failed → llama-server 无法将工具 schema 编译为其语法子集。请先更新 OpenClaw;如果第三方工具或 MCP 服务器提供了有问题的 schema,请针对该代理禁用它,并仅将 compat.supportsTools: false 作为最后手段使用。
{
  models: {
    providers: {
      llmman: {
        models: [
          {
            id: "qwen3.8",
            name: "qwen3.8",
            compat: {
              requiresStringContent: true,
            },
          },
        ],
      },
    },
  },
}
代理式行为

由于 llmman 是非原生 openai-completions 端点,OpenClaw 将其视为代理路由:没有 service_tier,没有 Responses store,没有提示缓存提示,没有 OpenAI 推理兼容负载整形,没有隐藏的 OpenClaw 归属头,并且 compat.supportsDeveloperRole 被强制为 false。供应商特定字段可以通过 agents.defaults.models["llmman/<model>"].params.extra_body 合并到请求体中。

模型成本

本地 llmman 模型是免费的,因此将所有成本设置为 0。混合部署中的托管部分或 llmman.provider/... 引用会由相应提供商计费;llmman list --provider openai 会显示其每百万 Token 的价格。

故障排查

curl /v1/models 失败

llmman serve 未运行,或在配置的地址上不可达。默认值为 127.0.0.1:17434;如果你设置了 LLMMAN_HOST,请更新 OpenClaw 的 baseUrl 和 healthUrl 以保持一致。

llmman serve
curl http://127.0.0.1:17434/api/version
提供商不可用或无法解析密钥

配置警告中的 models.providers.llmman.apiKey: *** env var "LLMMAN_API_KEY" 表示替换未找到值。将 LLMMAN_API_KEY=llmman-local 添加到 ~/.openclaw/.env,或将 "${LLMMAN_API_KEY}" 替换为字面量 "llmman-local"。

未知模型

模型未拉取,或配置中的 id 与 llmman 解析的结果不匹配。与 llmman list 进行比较;短名称映射到 docker.io/ai/<name>:latest,而 owner/repo 名称映射到 hf.co/owner/repo。

llmman pull qwen3.8
llmman list
冷模型超时

大型模型可能需要几分钟才能加载,尤其是在空闲卸载后的第一个请求。提高 models.providers.llmman.timeoutSeconds,先用 openclaw infer model run 预热模型,并考虑在守护进程上设置更长的 LLMMAN_KEEP_ALIVE。

混合请求因提供商没有 API 密钥而失败

llmman 将请求路由到托管部分,但未找到可用密钥。要么 OpenClaw 发送的 Bearer 是标记(llmman-local)而不是真实密钥,要么你使用了 llmman 占位符但没有为守护进程提供其自身的 OPENAI_API_KEY,要么守护进程绑定在非回环地址上并拒绝使用其自身密钥。参见 托管提供商密钥。

混合请求从不走托管(或总是走托管)

检查守护进程日志;每个被路由的请求都会记录侧别和原因。除非设置了 x-llmman-route,否则路由依据是请求体大小相对于 LLMMAN_CONTEXT_LENGTH(每个 Token 4 字节)。降低 LLMMAN_HYBRID_LOCAL_BYTES 可更早溢出,提高它可更长时间保持本地,或按 固定一侧 中的方式通过提供商 headers 条目固定一侧。

直接 /v1/chat/completions 调用通过,但 openclaw infer model run 失败

这两项检查都不使用工具,因此 compat.supportsTools 无法改变此失败。检查配置的基础 URL、模型 id 和 LLMMAN_API_KEY,检查守护进程和后端日志,并比较两个请求负载。

模型运行通过,但普通代理轮次失败

代理轮次会添加更大的 Prompt 和工具架构。400 JSON schema conversion failed 表示 llama-server 拒绝了工具架构;更新 OpenClaw 并检查第三方工具或 MCP 服务器。否则启用 工具搜索 以延迟架构,确认服务器的实际上下文分配,并仅在最后手段时使用 compat.supportsTools: false。参见 更小或更严格的后端。

llama-server 在更大的代理轮次上崩溃

如果架构错误已消失,但生成的 llama-server 在更大的轮次上仍然崩溃,请将其视为上游 llama.cpp 或模型限制。降低 LLMMAN_CONTEXT_LENGTH,设置 LLMMAN_KV_CACHE_TYPE=q8_0 以减少内存,或切换后端或模型。

模型将工具 JSON 作为文本输出

确认模型的聊天模板支持工具调用,并且请求到达了 /v1/chat/completions(而不是通过代理到达 Ollama 或 Anthropic 端点)。如果模型只有在强制时才会调用工具,请按照 本地模型 中的说明,在该模型引用上设置 params.extra_body.tool_choice: "required"。

Note

更多帮助:故障排查 和 FAQ。

本地模型

针对本地模型服务器运行 OpenClaw。

本地模型服务

为已配置的提供商按需启动本地模型服务器。

OpenAI

直接托管访问用作混合溢出部分的模型。

推理 CLI

openclaw infer model run 以及本页使用的其他一次性检查。

模型提供商

所有提供商、模型引用和故障转移行为的概述。

网关故障排查

调试通过检查但代理运行失败的本地 OpenAI 兼容后端。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw