OpenClaw llama.cpp Provider托管 llama-server、本地 GGUF 聊天模型与本地 Embedding 实战指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本篇基于 OpenClaw 仓库中的 llama.cpp 插件文档 及其插件源码系统讲解llama-cpp模型的接入方式从安装插件、选择「托管服务器 / 已有 llama-server」两种所有权模式到模型推荐机制、执行后端、认证与端点替换、手动配置以及本地 memory embedding 的完整落地路径。读完后可独立完成llama-cpp/model本地模型的配置并理解 OpenClaw 在 setup 阶段做硬件探测、模型校验与索引身份管理的底层逻辑。插件概览与安装llama-cpp插件提供单一的llama-cpp模型 providerOpenClaw 可以自行管理一个本地llama-server进程也可以连接你自己运营的服务器。两种方式都使用llama-cpp/model模型引用并走 OpenAI 兼容传输协议。安装与引导配置openclaw plugins install openclaw/llama-cpp-provider openclaw onboard从插件入口 index.ts 看register()只做两件事注册 id 为local的 embedding provider 适配器llamaCppEmbeddingProviderAdapter以及注册llama-cpp模型 providerregisterLlamaCppProvider。插件清单 openclaw.plugin.json 声明了enabledByDefault: true、syntheticAuthRefs: [llama-cpp]并把LLAMA_SERVER_API_KEY登记为 setup 阶段识别的环境变量。选择服务器所有权配置选择进程所有者本地 embeddingManaged local serverOpenClaw支持Existing llama-server你或外部 supervisor不支持models.providers.llama-cpp.localService是所有权判别字段只要它存在OpenClaw 就负责管理该进程若不存在则用baseUrl指向一个已存在的端点。在两种模式之间切换时OpenClaw 会重写同一 provider 下与所有权相关的状态但绝不会创建第二个 provider 命名空间。这一点在源码中可直接印证managed-provider.ts 的catalog.run里configured?.localService存在时走托管配置构建否则调用discoverLlamaServerProvider对外部端点做发现而 managed-provider-config / stream 包装 也仅在localService存在时才会为每次聊天请求先确保托管服务器就绪。托管本地服务器Managed local server当你希望 OpenClaw 负责安装、启动和停止llama-server时选择Managed local server。setup 读取的是Gateway 宿主机的硬件并根据可用内存、GPU 能力和磁盘余量推荐模型。注意浏览器连接到远程 Gateway 时模型安装和运行发生在该 Gateway 上而不是浏览器所在的电脑。硬件探测与模型推荐机制setup 会先对 Gateway 主机做一次硬件探测。从源码 detectLlamaCppHardware 看探测内容包括内存Linux 读/proc/meminfo的MemAvailablemacOS 用vm_stat的 free inactive 页避免把文件缓存误判为压力并优先使用 Node 的constrainedMemory()计入容器内存限制磁盘分别测量模型缓存目录和运行时目录的可用空间并通过文件系统设备号识别两者是否共享容量池Linux 上对 ext2/3/4、XFS、F2FS 识别容量组macOS 上通过diskutil识别 APFS 容器无法确认独立性的存储池按「共享」处理加速器macOS arm64 判定为 MetalLinux/Windows 上运行nvidia-smi采集每块卡的显存总量/空闲显存、驱动版本与计算能力。在此基础上resolveLlamaCppModelCandidates 计算内存预算系统内存预算为「可用内存」与「总内存减去至少 2 GiB 或 25% 的系统预留」取较小值CUDA 场景下取单张卡的显存预算每张卡预留至少 1 GiB 或 10%。源码注释明确解释了为什么多卡不叠加Require one device to hold the model; summing cards would assume a topology and tensor-split configuration that setup has not measured or configured——要求单张卡装下模型而不是假设可以做张量切分。磁盘侧recommendLlamaCppModel 为运行时预留约 3 GiBCUDA 构建或 2 GiBCPU 构建空间当缓存与运行时位于共享卷时两个分配必须合在一起装下已缓存的模型与 embedding 模型不再重复计费——这对应文档所述「setup 验证并复用缓存的推荐项只为缺失的模型和运行时文件占用磁盘空间」。推荐模型目录setup 按内存允许程度优先推荐以下纯文本 recipe每个都使用 65,536 token 上下文并支持工具调用模型聊天下载量最低主机内存Qwen3.5 4B Q4_K_M约 2.7 GB8 GiBQwen3.5 9B Q4_K_M约 5.7 GB16 GiBGemma 4 12B IT Q4_K_M约 7.1 GB24 GiB 且需 GPU 加速Muse Glimmer 30B Q4_K_M约 16.8 GB32 GiB 且需 GPU 加速Qwen3.8 27B UD-Q4_K_M约 16.5 GB32 GiB 且需 GPU 加速内存预算够时Qwen3.8 是第一推荐Muse 的上下文缓存预算更小可能装入 Qwen3.8 装不下的 24 GiB NVIDIA 显卡纯 CPU 的推荐止步于 Qwen3.5 9B。Gemma 4 E2B、E4B 与 26B A4B 仍保留在目录中供已有路由和缓存下载继续使用。推荐顺序是产品默认不代表某个模型在所有任务上都胜出。这些是「选型的下限」不是保证装得下或跑得快。setup 会为操作系统、上下文缓存、运行时和默认 embedding 模型预留内存计入当前内存压力和容器内存限制当 RAM、显存或磁盘受限时可能推荐更小的模型。多张 NVIDIA 卡不会被叠加来假设模型装得下。已有的 Gemma 4 E4B 配置与缓存的自定义模型继续受支持。从 model-catalog.ts 看每条 recipe 都是钉死的构件Hugging Face 仓库、文件名、revision 与 SHA-256 校验和全部写死在源码中例如 Qwen3.8 27B 对应unsloth/Qwen3.8-27B-GGUF下 16,464,440,224 字节的Qwen3.8-27B-UD-Q4_K_M.gguf下载后逐字节校验。默认模型为 Gemma 4 E4Bhf:unsloth/gemma-4-E4B-it-GGUF/gemma-4-E4B-it-Q4_K_M.gguf约 4.98 GB其 64K 上下文选择有明确注释依据defaults.ts 说明 OpenClaw 完整的 agent 系统提示词本身约 31K token8K 上下文在第一轮就会溢出64K 才能为历史与工具输出留足余量。聊天下载量还包含你配置的本地 embedding 模型默认是 EmbeddingGemma约 0.3 GB。需要为运行时和下载暂存预留额外磁盘空间setup 会在提供新模型之前检查这些。当缓存与运行时使用独立卷时setup 分别检查每个卷的可用空间共享存储池或无法确认独立性的卷使用合并预留。自定义 embedding 模型可能需要超出这些预算的内存和磁盘。执行后端Gateway 主机托管后端macOSApple 芯片Metal统一内存macOSIntelCPULinux x64 或 arm64CPU支持 NVIDIA GPU 的 Windows x64CUDA 12.4无受支持 CUDA 的 Windows x64或 Windows arm64CPU经验证的 Windows CUDA 构建要求 NVIDIA 驱动 551.78 及以上、计算能力 5.0 及以上。setup 会检查驱动和已安装运行时的设备发现结果当某块 NVIDIA GPU 没有兼容的托管 CUDA 构建时setup 会在确认环节说明限制并点名 CPU 执行。对于其他加速后端请自行运行兼容服务器并选择Existing llama-server。验证流程与失败处理确认下载前请先审阅具名的主机、执行后端、模型与下载体积。setup 会校验钉住的模型文件和 llama.cpp 构建准备回环端点并在保存新默认模型前做一次推理检查。引导式激活还会让模型通过 OpenClaw 工具读取一个临时文件并返回其内容工具检查运行在隔离工作区中不包含你 agent 的 bootstrap 指令——仅有纯文本回复无法通过该检查。每项验证检查有 90 秒时限修改agents.defaults.timeoutSeconds不会延长 setup 验证。失败时会明确指出是响应检查还是工具使用检查超时。托管的本地模型会自动使用结构化 Tool Search除非你已显式配置过它。可选能力仍然可用其 schema 按需加载减少模型在回复前需要处理的输入。setup 不会开启 lean mode普通聊天仍包含你的 agent 指令。纯 CPU 主机上即使 setup 验证成功第一条回复也可能需要几分钟。如果没有任何推荐项装得下setup 会解释应释放内存、释放磁盘空间还是修复缓存目录权限。取消或验证失败会保留之前的默认模型。每个 setup 候选项有独立的服务器 preset因此验证不会改写已有托管服务器的 preset已下载的文件可能保留为缓存供重试。托管路由的 preset 会以确定性顺序保留已配置的聊天模型并移除该清单之外的模型段聊天与 embedding 的准备工作在更新其拥有的配置时保留文件头、[*]默认值、注释以及保留模型上的其他选项仅 embedding 的 setup 使用全新 preset。这些行为对应 llama-server-preset.ts 与 managed-server.ts 中的实现。托管 provider 的关键参数写在 defaults.ts默认端口19432、就绪等待 30 秒、空闲 10 分钟后自动停止进程buildLlamaCppProviderConfig 还会为托管模式注入合成的本地 API keyllama-cpp-local标记该标记在 插件清单 的nonSecretAuthMarkers中登记为非机密值。仅设置本地 Embedding当memory.search.provider为local且聊天 setup 无法继续或被拒绝时OpenClaw 会提供独立的「仅 embedding」setup在明确同意后只安装托管服务器和已配置的 embedding 模型不会添加 llama.cpp 聊天模型也不改变当前聊天模型。setup 的发现阶段保持只读绝不安装或下载任何东西。若 llama.cpp provider 下已配置任何聊天模型仅 embedding setup 会保持其不变需先把聊天路由迁移到其他 provider 并删除这些模型条目再重试已有的外部 llama.cpp 服务器配置也必须先移除OpenClaw 才能接管 embedding。使用其他托管 GGUF在models.providers.llama-cpp.models下添加一个模型选中其llama-cpp/id引用再运行一次托管 setup{ 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即状态目录下的models/llama.cpp见 resolveLlamaCppModelCacheDir已配置的modelCacheDir在托管 setup 中保持权威。若源是hf:或 HTTPS URLresolveCachedLlamaCppModelPath 会返回空表示文件需下载并缓存在该目录中。连接已有 llama-serverExisting llama-server当进程由另一个终端、容器、服务管理器或另一台机器负责时选择Existing 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选择Existing llama-server并输入端点。仅当服务器或代理要求时才启用 API key 认证。第 3 步选择模型openclaw models list --provider llama-cpp openclaw models set llama-cpp/my-model外部服务器的默认端点是http://127.0.0.1:8080认证环境变量为LLAMA_SERVER_API_KEY发现超时 5 秒见 external-server/defaults.ts。发现机制的边界OpenClaw 读取/health、/models回退到/v1/models与/props路由器属性探测使用autoloadfalse。发现过程绝不加载、唤醒、卸载、下载或重载模型——这在 discoverLlamaServer 的注释与实现中得到确认它复用 OpenAI 兼容本地模型发现healthPath为/health、模型路径采用「server-first」顺序并附带路由器属性。从 discovery.ts 看发现结果默认有 30 秒缓存 TTL一旦请求携带 API key 或自定义头存在凭据作用域TTL 归零、不做缓存避免凭据变化导致清单失真。显式配置的模型行对同 ID 的发现行保持权威。刷新已配置的外部服务器失败时会报告认证拒绝或不可用此前发现的模型只有在端点和凭据均未变化时才继续可见一次成功的空列表会移除发现行而显式配置的模型始终保留。恢复服务器或更正凭据后再次刷新即可恢复实时清单。认证与端点替换已有端点支持无认证、API key、SecretRef、auth profile 以及显式Authorization头。除非 setup 收到新 key显式Authorization头优先于环境 API key 发现。选择「无 API key」会移除默认 llama.cpp auth profile 和陈旧的行内 key 字段同时保留显式Authorization头与无关的头。端点 URL 中携带用户名或密码的会被拒绝。export LLAMA_SERVER_API_KEYAPI_KEY openclaw onboard当端点发生变化时setup 不会把旧端点的环境变量、profile、配置 key 或头凭据发给替换端点。从托管模式切换过来时发现前会先移除localService、托管模型/缓存参数和托管请求超时。非交互式 setupopenclaw 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该 CLI 选项在 插件清单 的providerAuthChoices中以cliFlag登记。LLAMA_SERVER_API_KEY仍可用于初始 setup 和端点未变化的场景。手动配置引导式 setup 更推荐因为它会验证发现结果。最小手动配置形态{ 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工具 schema profile参见 自定义 provider 能力声明。models: []留空即可——目录由运行时发现填充插件清单 中modelCatalog.discovery[llama-cpp] refreshable表明该发现可刷新。请求、兼容性与本地 Embedding两种所有权方式都走 OpenClaw 常规聊天、图片、流式与工具传输。llama.cpp 兼容族插件清单中providerRequest.providers[llama-cpp].family llama-cpp且openAICompletions.supportsStreamingUsage: true会清理不支持的工具 schema 约束、把「关闭 thinking」的请求映射到 Qwen 的 chat-template 标志并为旧版 llama-server 构建适配 JSON Schema 请求。工具兼容钩子由 managed-provider.ts 的buildProviderToolCompatFamilyHooks(llamacpp-gbnf)装配模型 recipe 中对应的toolSchemaProfile: llamacpp声明见 model-catalog.ts。本地 memory embedding 需要托管模式{ memory: { search: { provider: local, local: { modelPath: hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf, }, }, }, }默认 embedding 模型即该 EmbeddingGemma QAT Q8_0 GGUF328,577,056 字节约 0.3 GB校验和与默认值同 defaults.ts 钉死。插件保留历史性的localembedding provider 与索引身份embedding-provider.ts 中当使用默认 embedding 模型时索引身份会附带一组别名当前默认路径、legacy 默认路径、缓存文件名等保证更换缓存目录或从 legacy 路径迁移时索引仍然被识别。运行时内联查询超时为 5 分钟、批量为 10 分钟L222-L228。在有意更换 embedding 模型之后运行openclaw memory status --index查看新的索引身份。故障排查托管 setup运行openclaw doctor与openclaw memory status --deep。已有服务器检查/health、/models、/props。HTTP 503 表示模型仍在加载。工具缺失确认/props中的两个工具能力标志并使用支持工具调用的 Jinja chat template。运行时依赖托管 Linux 构建要求 x64 上 glibc 2.34、arm64 上 glibc 2.38Windows 构建要求 Microsoft Visual C 2015-2022 可再发行组件包。模型能通过简单提示但不通过 setup 工具检查它不会被选为默认模型。检查其工具支持后重试或换一个模型。没有经验证托管构建的平台应使用已有服务器。OpenClaw 不会自动选择 ROCm、SYCL、OpenVINO 或 Vulkan 归档包。相关文档本地模型服务模型 ProviderLM Studiollama.cpp 插件参考——托管与外部 llama.cpp 服务器的 manifest 与配置参考【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考