跳转至

llama.cpp 提供商

llama-cpp 插件提供一个 llama-cpp 模型提供者。OpenClaw 可以管理本地 llama-server,也可以连接由你运行的实例。两种选择都使用 llama-cpp/<model> 引用和 OpenAI 兼容传输。

openclaw plugins install @openclaw/llama-cpp-provider
openclaw onboard

选择服务器所有权

设置选择 进程所有者 本地嵌入
托管本地服务器 OpenClaw 是
现有 llama-server 你或外部管理器 否

models.providers.llama-cpp.localService 是所有权判别字段。如果它存在,OpenClaw 会管理该进程。如果没有它,baseUrl 用于标识现有端点。切换选择会在同一提供者上重写所有权相关状态。它绝不会创建另一个提供者命名空间。

托管本地服务器

当 OpenClaw 应该安装、启动和停止服务器时,选择 托管本地服务器。设置会读取 Gateway 主机的硬件,并根据其可用内存、GPU 能力和空闲磁盘空间推荐模型。连接到远程 Gateway 的浏览器会在该 Gateway 上安装并运行模型,而不是在浏览器所在的计算机上。

请查看指定的主机、执行后端、模型和下载大小,然后确认下载。设置会验证固定的模型文件和 llama.cpp 构建,准备一个回环端点,并在保存新默认值之前检查推理。引导式激活还会要求模型通过 OpenClaw 工具读取一个临时文件并返回其内容。工具检查使用一个隔离工作区,不包含你的代理的引导指令。仅靠纯文本回复无法通过该检查。每个验证检查都有 90 秒的时限。更改 agents.defaults.timeoutSeconds 不会延长设置验证。失败信息会指明是响应检查还是工具使用检查超时。

如果配置的服务器可执行文件在 OpenClaw 当前托管安装中缺失,聊天和本地嵌入会在启动前恢复同一已验证构建。自定义服务器路径和来自旧版本发布的安装仍需要手动修复或重新运行设置。

托管本地模型会自动使用结构化 Tool Search,除非你已显式配置它。可选能力仍然可用。它们的模式会按需加载,减少模型在回复前必须处理的输入。设置不会启用精简模式。普通聊天仍会包含你的代理指令。在仅 CPU 的主机上,即使设置验证成功,首次回复也可能需要几分钟。

模型推荐

在内存允许的情况下,设置会优先选择这些纯文本配方。每个配方都使用 65,536 个 token 的上下文并支持工具:

模型 聊天下载 最低主机内存
Qwen3.5 4B Q4_K_M 约 2.7 GB 8 GiB
Qwen3.5 9B Q4_K_M 约 5.7 GB 16 GiB
Gemma 4 12B IT Q4_K_M 约 7.1 GB 24 GiB 和 GPU 加速
Muse Glimmer 30B Q4_K_M 约 16.8 GB 32 GiB 和 GPU 加速
Qwen3.8 27B UD-Q4_K_M 约 16.5 GB 32 GiB 和 GPU 加速

当内存预算满足时,Qwen3.8 是首选推荐。Muse 的上下文缓存预算更小,在 Qwen3.8 无法适配的 24 GiB NVIDIA 显卡上可能可以适配。CPU 推荐最高到 Qwen3.5 9B。Gemma 4 E2B、E4B 和 26B A4B 仍保留在目录中,用于现有路由和缓存下载。推荐顺序是产品默认值,并非声称某个模型在所有任务中都胜出。

这些是选择下限,而非保证适配或速度。设置会为操作系统、上下文缓存、运行时和默认嵌入模型保留内存。它会考虑当前内存压力和容器内存限制,并在 RAM、GPU 内存或磁盘空间有限时推荐更小的模型。不会将多块独立的 NVIDIA 显卡相加来假设某个模型可以适配。现有的 Gemma 4 E4B 配置和缓存的自定义模型仍受支持。

聊天下载还包括你配置的本地嵌入模型,默认是 EmbeddingGemma(约 0.3 GB)。请为运行时和下载暂存预留额外磁盘空间。设置在提供推荐模型之前会检查这一点。当缓存和运行时使用独立卷时,设置会分别检查每个卷的空闲空间。共享存储池以及无法确定其独立性的卷会使用合并预留。自定义嵌入模型可能需要比这些预算更多的内存和磁盘空间。

执行后端

Gateway 主机 托管后端
使用 Apple 芯片的 macOS 统一内存的 Metal
使用 Intel 的 macOS CPU
Linux x64 或 arm64 CPU
带有受支持 NVIDIA GPU 的 Windows x64 CUDA 12.4
没有受支持 CUDA 的 Windows x64,或 Windows arm64 CPU

已验证的 Windows CUDA 构建需要 NVIDIA 驱动 551.78 或更新版本,以及计算能力 5.0 或更新版本。设置会检查驱动和已安装运行时的设备发现。当 NVIDIA GPU 没有兼容的托管 CUDA 构建时,设置会说明该限制,并在确认中指明 CPU 执行。对于其他加速后端,请自行运行兼容的服务器,并选择 现有 llama-server。

运行时验证允许每个可执行文件版本检查最多两分钟,以便在安装后或复用运行时后完成 macOS 安全评估和 Metal 初始化。验证期间设置仍可取消。

The verified macOS builds require macOS 13.3 or later, and setup stops before downloading on older releases. To keep managed chat and local embeddings there, build llama-server on that Mac and set models.providers.llama-cpp.localService.command to its absolute path; see Local model services.

If no recommendation fits, setup explains whether to free memory, free disk space, or fix cache-directory permissions. Cancelling or failing guided verification leaves the previous default model selected. A setup candidate has its own server preset, so verification does not rewrite an existing managed server's preset. Downloaded files may remain cached for a retry. Setup verifies and reuses cached recommendations, and charges disk space only for missing model and runtime files.

Managed router presets retain configured chat models in deterministic order and remove model sections outside that inventory. Chat and embedding preparation update their owned settings while preserving the header, [*] defaults, comments, and additional options on retained models. Embedding-only setup uses a fresh preset.

Managed embeddings default to one server slot (parallel = 1), a 2,048-token context, and a 2,048-token physical batch (ubatch-size). Memory indexing reserves four positions for tokenizer overhead and the server's context boundary. These defaults also apply to custom GGUFs and legacy EmbeddingGemma cache paths. One slot bounds llama.cpp's large embedding output buffer to one input; the context bound avoids reserving a custom model's full training context for short memory chunks.

Existing context, batch, and slot settings in the embedding section, [*], or the managed service's arguments or environment remain authoritative. OpenClaw adds the context bound only when no slot count or per-slot context is configured, because llama.cpp can divide total context across slots. If you choose a different slot count, size its context too. Long queries or direct embedding requests may need larger native capacity settings on models that support them. Missing defaults are added on the next managed preset preparation.

仅设置本地嵌入

当 memory.search.provider 为 local,且聊天设置无法继续或被拒绝时,OpenClaw 会提供单独的仅嵌入设置。在明确同意后,它只安装托管服务器和已配置的嵌入模型。它不会添加 llama.cpp 聊天模型,也不会更改当前聊天模型。设置发现过程保持只读,从不安装或下载任何内容。

如果没有推荐的聊天模型符合你的内存预算,请启用本地内存搜索并重试设置,以获取仅嵌入选项(默认嵌入模型约 0.3 GB):

openclaw config set memory.search.provider local
openclaw models auth login --provider llama-cpp --method local

如果你使用 --profile,请对两条命令使用相同的 profile。

如果 llama.cpp 提供商已配置任何聊天模型,仅嵌入设置会保持其不变。重试前,请将任何聊天路由迁移到其他提供商,并删除这些模型条目。在 OpenClaw 能够管理嵌入之前,还必须删除现有的外部 llama.cpp 服务器配置。

使用其他托管 GGUF

在 models.providers.llama-cpp.models 下添加一个模型,选择其 llama-cpp/<id> 引用,然后再次运行托管设置:

{
  id: "my-local-model",
  name: "My local GGUF",
  reasoning: false,
  input: ["text"],
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 65536,
  maxTokens: 2048,
  params: {
    modelPath: "~/Models/my-model.Q4_K_M.gguf",
    contextSize: 65536,
  },
  compat: { supportsTools: true },
}

modelPath 接受本地路径、相对于缓存的文件名、完整的 hf: 文件 URI,以及发布 SHA-256 响应摘要的 HTTPS GGUF URL。默认缓存为 ~/.openclaw/models/llama.cpp。已配置的 modelCacheDir 对托管设置仍然具有权威性。

设置会将模型别名和账户限定引用解析到所选的已创建模型,即使该模型未缓存也会保留它。当可用时,它会显示来自固定配方或源元数据的下载大小,并在下载前询问。无效源会产生特定于该模型的错误,而不是给出其他推荐。拒绝会保持已配置的路由不变。当未配置托管聊天模型时,硬件推荐适用;自定义模型仍受源校验和运行时验证约束。

现有 llama-server

当另一个终端、容器、服务管理器或机器拥有该进程时,选择 现有 llama-server。

1. 启动 llama-server

为模型指定一个稳定的别名:

llama-server \
  --model /path/to/model.gguf \
  --alias my-model \
  --host 127.0.0.1 \
  --port 8080

2. 配置 OpenClaw

运行 openclaw onboard,选择 现有 llama-server,并输入端点。仅当服务器或代理需要时,才启用 API 密钥身份验证。

URL 提示接受 HTTP 或 HTTPS 端点以及主机简写,例如 localhost:8080。无效 URL 和嵌入的凭据会被内联拒绝,以便你可以在不重启设置的情况下更正端点。

3. 选择模型

openclaw models list --provider llama-cpp
openclaw models set llama-cpp/my-model

OpenClaw 会读取 /health、/models(回退到 /v1/models)和 /props。路由器属性检查使用 autoload=false。发现过程从不加载、唤醒、卸载、下载或重新加载模型。

对于发现的模型,只有当 /props 将 chat_template_caps.supports_reasoning_effort 设置为 true 时,OpenClaw 才会宣传推理和 effort 控制。缺失或为 false 的值会使这些能力不被宣传。显式配置的上下文和工具值相对于发现过程仍然具有权威性。

设置仅在实时 /props 验证上下文限制和工具支持时才保存它们。未加载的路由器模型会保留在已配置清单中,且这些字段未设置。运行时发现使用 128,000 个 token 的上下文回退值,并在这些事实未知时保持工具禁用;它不会将这些默认值保存为模型覆盖。在你自行加载模型后,刷新其实时事实:

openclaw models list --provider llama-cpp --refresh

刷新会从实时 /props 填充运行时目录中未设置的上下文和工具字段,而不会更改你的显式覆盖或加载其他模型。 旧版设置可能为未加载的模型保存了 contextWindow: 128000、 contextTokens: 128000 和 compat.supportsTools: false。 如果这些值是由设置生成的,而不是你打算固定的值,请从 models.providers.llama-cpp.models 中删除受影响的模型行,然后刷新或重新运行 现有 llama-server 设置。先加载模型以发现其实际限制。仅重新运行设置会保留现有覆盖。

刷新已配置的外部服务器时,如果发现失败,会报告身份验证被拒绝或不可用。 之前发现的模型仅在其端点和凭据未更改时保持可见。 成功的空列表会移除已发现的行。显式配置的模型会保留。恢复服务器或更正其凭据,然后再次刷新以恢复实时清单。

身份验证和端点替换

现有端点支持无身份验证、API 密钥、SecretRefs、身份验证配置文件和显式授权头。 显式 Authorization 头优先于环境 API 密钥发现,除非设置接收到新密钥。选择不使用 API 密钥会移除默认 llama.cpp 身份验证配置文件和过期的内联密钥字段,同时保留显式 Authorization 头和不相关的头。包含用户名或密码的端点 URL 会被拒绝。

export LLAMA_SERVER_API_KEY="<API_KEY>"
openclaw onboard

当端点更改时,设置不会将旧端点的环境、配置文件、已配置密钥或头凭据发送到替换端点。从托管模式切换还会在发现之前移除 localService、托管模型/缓存参数以及托管请求超时。

对于非交互式设置:

openclaw onboard \
  --non-interactive \
  --accept-risk \
  --auth-choice llama-cpp-existing-server \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id my-model

当替换端点需要新凭据时,使用 --llama-server-api-key <API_KEY>。LLAMA_SERVER_API_KEY 仍可用于初始设置和未更改的端点。

手动配置

建议进行引导式设置,因为它会验证发现。最小手动格式为:

{
  models: {
    mode: "merge",
    providers: {
      "llama-cpp": {
        baseUrl: "http://127.0.0.1:8080/v1",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        models: [],
      },
    },
  },
}

自定义 provider ID 也可以通过通用的 OpenAI 兼容路径指向 llama-server。它们仍然是自定义 provider,并且应显式声明 llamacpp 工具架构配置文件。参见 自定义 provider 能力声明。

请求和本地嵌入

两种所有权选择都使用 OpenClaw 的常规聊天、图像、流式传输和工具传输。llama.cpp 兼容系列会清理不支持的工具架构约束。代理轮次和独立补全还会将关闭思考的请求映射到服务器的 chat-template 标志,并为旧版 llama-server 构建适配 JSON Schema 请求。

本地内存嵌入需要托管模式:

{
  memory: {
    search: {
      provider: "local",
      local: {
        modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",
      },
    },
  },
}

默认 EmbeddingGemma 模型会自动为搜索查询和索引文档接收不同的任务前缀。未使用这些前缀构建的现有索引会在下次搜索或同步时重建一次,无需 --force。缓存的原始嵌入不会被重用,并且在恢复期间关键词搜索仍可用。在有意更改嵌入模型后,运行 openclaw memory status --index。

故障排除

  • 托管设置:运行 openclaw doctor 和 openclaw memory status --deep。
  • 托管运行时状态要求 /health、/models 和 /props 端点健康,并且没有模型加载错误。当自定义服务器省略 --metrics 时,可选的 /metrics 可能为 unavailable;这不会使运行时失败。
  • 现有服务器:检查 /health、/models 和 /props。HTTP 503 表示模型仍在加载。
  • 缺少工具:验证 /props 中的两个工具能力标志,并使用支持工具的 Jinja 聊天模板。
  • 托管 Linux 构建在 x64 上需要 glibc 2.34,在 arm64 上需要 2.38。Windows 构建需要 Microsoft Visual C++ 2015-2022 可再发行组件包。
  • 能够回复简单提示但在设置工具检查中失败的模型不会被选为默认模型。在审查其工具支持后重试,或选择另一个模型。
  • 没有经过验证的托管构建的平台应使用现有服务器。

OpenClaw 不会自动选择 ROCm、SYCL、OpenVINO 或 Vulkan 归档。

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