llama.cpp 提供商

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

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

选择服务器所有权¶

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

托管本地服务器¶

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

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

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

模型推荐¶

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

当内存预算满足时，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）。请为运行时和下载暂存预留额外磁盘空间。设置在提供新模型之前会检查这一点。当缓存和运行时使用独立卷时，设置会分别检查每个卷的空闲空间。共享存储池以及无法确定其独立性的卷会使用合并预留。 自定义嵌入模型可能需要比这些预算更多的内存和磁盘空间。

执行后端¶

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

如果没有推荐项适配，设置会说明应释放内存、释放磁盘空间，还是修复缓存目录权限。取消或引导式验证失败会保留之前选中的默认模型。设置候选项拥有自己的服务器预设，因此验证不会重写现有托管服务器的预设。已下载的文件可能保留在缓存中以供重试。设置会验证并复用已缓存的推荐项，并且只为缺失的模型和运行时文件占用磁盘空间。

托管路由器预设会按确定性顺序保留已配置的聊天模型，并删除该清单之外的模型部分。聊天和嵌入准备会更新其拥有的设置，同时保留头部、[*] 默认值、注释以及保留模型上的其他选项。仅嵌入设置使用全新预设。

仅设置本地嵌入¶

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

如果 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 密钥身份验证时，才启用 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 值会使这些能力不被通告。显式配置的模型行对于具有相同 ID 的发现行保持权威。

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

身份验证和端点替换¶

现有端点支持无身份验证、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: [],
      },
    },
  },
}

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

请求和本地嵌入¶

两种所有权选择都使用 OpenClaw 的常规聊天、图像、流式传输和工具传输。llama.cpp 兼容系列会清理不支持的工具架构约束。Agent 轮次和独立补全也会将 thinking-off 请求映射到服务器的 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",
      },
    },
  },
}

该插件保留历史 local 嵌入提供程序和索引身份。在有意更改嵌入模型后，运行 openclaw memory status --index。

故障排除¶

• 托管设置：运行 openclaw doctor 和 openclaw memory status --deep。
• 现有服务器：检查 /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 归档文件。

相关¶

• 本地模型服务
• 模型提供商
• LM Studio
• Llama Cpp 插件参考 — 托管和外部 llama.cpp 服务器的清单和配置参考