1. 为什么要在 openclaw 里接本地大模型openclaw 是一个面向开发者的 AI 编程助手客户端它能通过 OpenAI 兼容协议对接各种推理后端。很多人第一次用它的时候默认连的是云端 API但如果你手头有一张 8GB 显存的显卡或者一台内存够大的笔记本完全可以把模型跑在本地让 openclaw 直接调用 llama.cpp 提供的接口。这样做的好处很直接数据不出本机、没有网络延迟、不用按 token 计费断网也能继续写代码。llama.cpp 是目前本地推理里最成熟的方案之一它用 C 写成支持 CPU 和 GPU 混合推理能把 GGUF 格式的量化模型跑出相当不错的吞吐。所谓 GGUF你可以理解成一种“打包好的模型文件”里面既有权重也有元数据llama.cpp 读进去就能直接推理不需要额外的转换步骤。量化则是把原本 16 位的权重压到 4 位或 5 位文件体积能缩小到原来的三分之一左右代价是精度略有损失但对日常对话和代码补全来说几乎感觉不到。这套组合适合谁一是显卡显存 6GB 到 12GB 的个人开发者跑 7B 级别的 Q4 量化模型刚好二是只有 CPU 但内存 16GB 以上的用户用 Q4 的 3B 模型也能获得可用的速度三是需要在内网或离线环境里做 AI 辅助编码的团队。整条链路的核心就是编译 llama.cpp → 下载 GGUF 模型 → 启动 llama-server → 在 openclaw 里填上本地地址和模型名。下面我按实际操作顺序拆开讲每一步都给可复制的命令。2. 编译 llama.cpp 与 GGUF 模型选择先说环境。我是在 WSL2 的 Ubuntu 里做的Windows 原生也能编译但 WSL2 的包管理和路径更顺手。先装编译工具sudo apt update sudo apt install -y cmake build-essential git curl然后拉源码并编译。llama.cpp 的构建系统是 CMake我们只需要llama-cli和llama-server两个目标mkdir -p ~/llama.cpp cd ~/llama.cpp git clone --depth 1 https://github.com/ggerganov/llama.cpp.git src cd src mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease make -j$(nproc) llama-cli llama-server编译完成后可执行文件在~/llama.cpp/src/build/bin/下。如果你有 NVIDIA 显卡并且装了 CUDA可以在 cmake 那步加上-DGGML_CUDAON这样-ngl参数才能把层卸载到 GPU。没有 CUDA 也能编只是纯 CPU 推理。接下来是模型选择这是最容易踩坑的地方。GGUF 模型的文件名里通常带量化标记比如q4_k_m、q5_k_m、q8_0。q4_k_m是 4 位量化的中等档性价比最高q5_k_m精度更好但体积大 20% 左右q8_0接近原始精度但 7B 模型也要 7GB 以上。显存和模型大小的对应关系可以这样估显卡显存推荐模型量化档文件大小上下文建议4GBQwen2.5-3B-Instructq4_k_m~2.0GB40966GBQwen2.5-7B-Instructq4_k_m~4.5GB40968GBQwen2.5-7B-Instructq5_k_m~5.5GB819212GBQwen2.5-14B-Instructq4_k_m~9GB819224GBQwen2.5-32B-Instructq4_k_m~20GB16384下载模型时用国内镜像会快很多mkdir -p ~/llama.cpp/models curl -L -o ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf这里有个关键权衡上下文长度-c会额外占用显存。KV Cache 的大小和层数、头数、上下文长度成正比。7B 模型在 4096 上下文下 KV Cache 大约 1GB开到 8192 就接近 2GB。所以如果你显存刚好卡在 8GB模型占 5.5GBKV Cache 再占 2GB加上 CUDA 运行时开销很容易 OOM。我的建议是先用 4096 跑通再逐步往上加观察nvidia-smi的显存占用。3. 启动 llama-server 并配置 openclaw 接入模型下好后先用命令行模式确认模型能正常加载cd ~/llama.cpp/src/build/bin ./llama-cli -m ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ -c 4096 -ngl 99 --no-display-prompt-ngl 99表示把所有层都放到 GPU如果显存不够就调小比如-ngl 20只放 20 层。能正常对话后换成 server 模式./llama-server \ -m ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 \ --port 8080 \ -c 4096 \ -ngl 99 \ -np 4 \ --api-key local-test-key-np 4是并行请求数openclaw 在补全时可能同时发多个请求设成 4 比较稳。--api-key是可选的但建议设上避免局域网里被别人白嫖。现在关键一步在 openclaw 里配置本地后端。openclaw 的配置文件通常是 JSON 格式路径在~/.openclaw/config.json或项目根目录的.openclaw/settings.json。你需要填三个东西Base URL、API Key、Model ID。配置片段如下{ provider: openai-compatible, baseUrl: http://127.0.0.1:8080/v1, apiKey: local-test-key, model: qwen2.5-7b-instruct, temperature: 0.7, maxTokens: 2048 }注意baseUrl一定要带/v1因为 llama-server 暴露的是 OpenAI 兼容端点。model字段填什么llama-server 其实不校验模型名你填qwen2.5-7b-instruct或者随便一个字符串都能通但为了可读性建议和实际模型对应。如果你用的是 Cline 或 CC Switch 这类工具配置项名称可能略有不同但核心三件套不变Base URL、Key、Model ID。还有一个细节openclaw 如果跑在 Windows 宿主机而 llama-server 跑在 WSL2 里127.0.0.1是不通的。你需要用 WSL2 的 IP在 WSL 里执行hostname -I拿到地址比如172.20.10.5然后 baseUrl 写成http://172.20.10.5:8080/v1。WSL2 的 IP 每次重启可能变可以在 Windows 的%USERPROFILE%\.wslconfig里配端口转发或者干脆在 WSL 里跑 openclaw。4. 用 curl 验证本地推理接口服务起来后别急着开 openclaw先用 curl 确认接口是通的。健康检查端点curl http://127.0.0.1:8080/health返回{status:ok}就说明服务活着。然后测聊天补全curl http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-test-key \ -d { model: qwen2.5-7b-instruct, messages: [ {role: system, content: 你是一个有帮助的助手。}, {role: user, content: 用一句话解释什么是量化。} ], temperature: 0.7, max_tokens: 256 }正常返回的 JSON 里choices[0].message.content就是模型输出。如果这一步通了说明 llama-server 没问题问题只可能在 openclaw 的配置上。Python 侧验证from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8080/v1, api_keylocal-test-key) resp client.chat.completions.create( modelqwen2.5-7b-instruct, messages[{role: user, content: 你好}], temperature0.7, max_tokens256 ) print(resp.choices[0].message.content)流式输出也值得测一下因为 openclaw 补全时用的是 stream 模式curl http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-7b-instruct,messages:[{role:user,content:数到五}],stream:true}你会看到一串data: {...}的 SSE 事件最后以data: [DONE]结束。如果流式正常但 openclaw 里没反应多半是 openclaw 的 baseUrl 少了/v1或者它默认走了别的 provider。实测下来7B Q4 模型在 RTX 4060 上首 token 延迟大约 0.3 秒生成速度 40 tokens/s 左右写代码补全完全够用。3B 模型在纯 CPU8 核上大概 8 tokens/s适合轻量对话。5. 常见报错排查401、OOM 与连接失败报错一401 Unauthorized。如果你在 llama-server 上设了--api-key但 openclaw 配置里的 apiKey 不一致就会返回 401。curl 测试时带上-H Authorization: Bearer local-test-key确认 key 对得上。如果没设--api-key有些客户端会强制要求非空 key这时随便填一个字符串即可llama-server 不校验。报错二CUDA out of memory。这是最常见的。报错信息通常是ggml_cuda_host_malloc: failed to allocate或CUDA error: out of memory。解决办法是降低-ngl让部分层回落到 CPU./llama-server -m model.gguf -ngl 20 -c 4096或者降低上下文-c 2048。KV Cache 在 4096 上下文下对 7B 模型约占 1GB减半能省 500MB。还可以用--no-kv-offload把 KV Cache 放内存而不是显存代价是速度下降。报错三local proxy failed 或 connection refused。这通常是 openclaw 连不上 llama-server。先确认 server 在监听ss -tlnp | grep 8080。如果 server 在 WSL 而 openclaw 在 Windows用 WSL 的 IP 而不是 127.0.0.1。另外检查防火墙有没有拦 8080 端口。报错四reading choices 时解析失败。这种多半是返回体不是标准 OpenAI 格式。llama-server 默认兼容但如果你开了--chat-template自定义模板可能输出结构变了。去掉自定义模板用模型自带的 chat template 即可。还有一种情况是max_tokens设得比模型上限还大导致返回空 choices把 max_tokens 调到 2048 以内。报错五OAuth 或鉴权流程卡住。有些客户端默认走 OAuth 登录云端接本地后端时要在设置里显式切换成 API Key 模式否则它会一直尝试刷新 token。在 openclaw 的 provider 设置里选openai-compatible填上 Base URL 和 Key别选带 OAuth 的选项。排查顺序建议先 curl/health再 curl/v1/chat/completions最后才查 openclaw 配置。这样能快速定位是服务端问题还是客户端问题。6. 把本地模型用起来接入与进阶服务跑通之后你可以把 openclaw 的默认模型指向本地日常写代码、改注释、生成单元测试都走本地推理。如果哪天需要更强的模型也可以在 openclaw 里配多个 provider本地和云端切换着用。对于长期做 Agent 开发或需要稳定编码助手的场景可以考虑用 Coding Plan 把本地和云端的能力编排起来本地负责高频轻量请求云端负责复杂推理。如果你还没拿到 API Key或者想先试试云端模型做对比可以到 API Keys 页面创建一个接入文档里有各语言的示例。想直接体验模型对话效果模型对话页面可以快速试跑。本地部署的价值在于可控和离线而云端方案胜在模型规模和免维护两者并不冲突按场景选就行。最后留一个实用技巧把启动命令写成脚本加上nohup后台运行日志重定向到文件这样关掉终端服务也不会断。#!/bin/bash cd ~/llama.cpp/src/build/bin nohup ./llama-server \ -m ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 \ -c 4096 -ngl 99 -np 4 \ --api-key local-test-key \ ~/llama.cpp/server.log 21 chmod x start-server.sh之后每次./start-server.sh就能拉起服务日志在server.log里出问题先看这个文件。模型文件建议放在 SSD 上机械硬盘加载 5GB 的 GGUF 会慢到怀疑人生。 
长河君 · 2026/10/15 23:46:47 · 阅读 1.2k openclaw 使用 llama.cpp 本地大模型部署教程：从模型量化到 API 服务
1. 为什么要在 openclaw 里接本地大模型openclaw 是一个面向开发者的 AI 编程助手客户端它能通过 OpenAI 兼容协议对接各种推理后端。很多人第一次用它的时候默认连的是云端 API但如果你手头有一张 8GB 显存的显卡或者一台内存够大的笔记本完全可以把模型跑在本地让 openclaw 直接调用 llama.cpp 提供的接口。这样做的好处很直接数据不出本机、没有网络延迟、不用按 token 计费断网也能继续写代码。llama.cpp 是目前本地推理里最成熟的方案之一它用 C 写成支持 CPU 和 GPU 混合推理能把 GGUF 格式的量化模型跑出相当不错的吞吐。所谓 GGUF你可以理解成一种“打包好的模型文件”里面既有权重也有元数据llama.cpp 读进去就能直接推理不需要额外的转换步骤。量化则是把原本 16 位的权重压到 4 位或 5 位文件体积能缩小到原来的三分之一左右代价是精度略有损失但对日常对话和代码补全来说几乎感觉不到。这套组合适合谁一是显卡显存 6GB 到 12GB 的个人开发者跑 7B 级别的 Q4 量化模型刚好二是只有 CPU 但内存 16GB 以上的用户用 Q4 的 3B 模型也能获得可用的速度三是需要在内网或离线环境里做 AI 辅助编码的团队。整条链路的核心就是编译 llama.cpp → 下载 GGUF 模型 → 启动 llama-server → 在 openclaw 里填上本地地址和模型名。下面我按实际操作顺序拆开讲每一步都给可复制的命令。2. 编译 llama.cpp 与 GGUF 模型选择先说环境。我是在 WSL2 的 Ubuntu 里做的Windows 原生也能编译但 WSL2 的包管理和路径更顺手。先装编译工具sudo apt update sudo apt install -y cmake build-essential git curl然后拉源码并编译。llama.cpp 的构建系统是 CMake我们只需要llama-cli和llama-server两个目标mkdir -p ~/llama.cpp cd ~/llama.cpp git clone --depth 1 https://github.com/ggerganov/llama.cpp.git src cd src mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease make -j$(nproc) llama-cli llama-server编译完成后可执行文件在~/llama.cpp/src/build/bin/下。如果你有 NVIDIA 显卡并且装了 CUDA可以在 cmake 那步加上-DGGML_CUDAON这样-ngl参数才能把层卸载到 GPU。没有 CUDA 也能编只是纯 CPU 推理。接下来是模型选择这是最容易踩坑的地方。GGUF 模型的文件名里通常带量化标记比如q4_k_m、q5_k_m、q8_0。q4_k_m是 4 位量化的中等档性价比最高q5_k_m精度更好但体积大 20% 左右q8_0接近原始精度但 7B 模型也要 7GB 以上。显存和模型大小的对应关系可以这样估显卡显存推荐模型量化档文件大小上下文建议4GBQwen2.5-3B-Instructq4_k_m~2.0GB40966GBQwen2.5-7B-Instructq4_k_m~4.5GB40968GBQwen2.5-7B-Instructq5_k_m~5.5GB819212GBQwen2.5-14B-Instructq4_k_m~9GB819224GBQwen2.5-32B-Instructq4_k_m~20GB16384下载模型时用国内镜像会快很多mkdir -p ~/llama.cpp/models curl -L -o ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf这里有个关键权衡上下文长度-c会额外占用显存。KV Cache 的大小和层数、头数、上下文长度成正比。7B 模型在 4096 上下文下 KV Cache 大约 1GB开到 8192 就接近 2GB。所以如果你显存刚好卡在 8GB模型占 5.5GBKV Cache 再占 2GB加上 CUDA 运行时开销很容易 OOM。我的建议是先用 4096 跑通再逐步往上加观察nvidia-smi的显存占用。3. 启动 llama-server 并配置 openclaw 接入模型下好后先用命令行模式确认模型能正常加载cd ~/llama.cpp/src/build/bin ./llama-cli -m ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ -c 4096 -ngl 99 --no-display-prompt-ngl 99表示把所有层都放到 GPU如果显存不够就调小比如-ngl 20只放 20 层。能正常对话后换成 server 模式./llama-server \ -m ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 \ --port 8080 \ -c 4096 \ -ngl 99 \ -np 4 \ --api-key local-test-key-np 4是并行请求数openclaw 在补全时可能同时发多个请求设成 4 比较稳。--api-key是可选的但建议设上避免局域网里被别人白嫖。现在关键一步在 openclaw 里配置本地后端。openclaw 的配置文件通常是 JSON 格式路径在~/.openclaw/config.json或项目根目录的.openclaw/settings.json。你需要填三个东西Base URL、API Key、Model ID。配置片段如下{ provider: openai-compatible, baseUrl: http://127.0.0.1:8080/v1, apiKey: local-test-key, model: qwen2.5-7b-instruct, temperature: 0.7, maxTokens: 2048 }注意baseUrl一定要带/v1因为 llama-server 暴露的是 OpenAI 兼容端点。model字段填什么llama-server 其实不校验模型名你填qwen2.5-7b-instruct或者随便一个字符串都能通但为了可读性建议和实际模型对应。如果你用的是 Cline 或 CC Switch 这类工具配置项名称可能略有不同但核心三件套不变Base URL、Key、Model ID。还有一个细节openclaw 如果跑在 Windows 宿主机而 llama-server 跑在 WSL2 里127.0.0.1是不通的。你需要用 WSL2 的 IP在 WSL 里执行hostname -I拿到地址比如172.20.10.5然后 baseUrl 写成http://172.20.10.5:8080/v1。WSL2 的 IP 每次重启可能变可以在 Windows 的%USERPROFILE%\.wslconfig里配端口转发或者干脆在 WSL 里跑 openclaw。4. 用 curl 验证本地推理接口服务起来后别急着开 openclaw先用 curl 确认接口是通的。健康检查端点curl http://127.0.0.1:8080/health返回{status:ok}就说明服务活着。然后测聊天补全curl http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-test-key \ -d { model: qwen2.5-7b-instruct, messages: [ {role: system, content: 你是一个有帮助的助手。}, {role: user, content: 用一句话解释什么是量化。} ], temperature: 0.7, max_tokens: 256 }正常返回的 JSON 里choices[0].message.content就是模型输出。如果这一步通了说明 llama-server 没问题问题只可能在 openclaw 的配置上。Python 侧验证from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8080/v1, api_keylocal-test-key) resp client.chat.completions.create( modelqwen2.5-7b-instruct, messages[{role: user, content: 你好}], temperature0.7, max_tokens256 ) print(resp.choices[0].message.content)流式输出也值得测一下因为 openclaw 补全时用的是 stream 模式curl http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-7b-instruct,messages:[{role:user,content:数到五}],stream:true}你会看到一串data: {...}的 SSE 事件最后以data: [DONE]结束。如果流式正常但 openclaw 里没反应多半是 openclaw 的 baseUrl 少了/v1或者它默认走了别的 provider。实测下来7B Q4 模型在 RTX 4060 上首 token 延迟大约 0.3 秒生成速度 40 tokens/s 左右写代码补全完全够用。3B 模型在纯 CPU8 核上大概 8 tokens/s适合轻量对话。5. 常见报错排查401、OOM 与连接失败报错一401 Unauthorized。如果你在 llama-server 上设了--api-key但 openclaw 配置里的 apiKey 不一致就会返回 401。curl 测试时带上-H Authorization: Bearer local-test-key确认 key 对得上。如果没设--api-key有些客户端会强制要求非空 key这时随便填一个字符串即可llama-server 不校验。报错二CUDA out of memory。这是最常见的。报错信息通常是ggml_cuda_host_malloc: failed to allocate或CUDA error: out of memory。解决办法是降低-ngl让部分层回落到 CPU./llama-server -m model.gguf -ngl 20 -c 4096或者降低上下文-c 2048。KV Cache 在 4096 上下文下对 7B 模型约占 1GB减半能省 500MB。还可以用--no-kv-offload把 KV Cache 放内存而不是显存代价是速度下降。报错三local proxy failed 或 connection refused。这通常是 openclaw 连不上 llama-server。先确认 server 在监听ss -tlnp | grep 8080。如果 server 在 WSL 而 openclaw 在 Windows用 WSL 的 IP 而不是 127.0.0.1。另外检查防火墙有没有拦 8080 端口。报错四reading choices 时解析失败。这种多半是返回体不是标准 OpenAI 格式。llama-server 默认兼容但如果你开了--chat-template自定义模板可能输出结构变了。去掉自定义模板用模型自带的 chat template 即可。还有一种情况是max_tokens设得比模型上限还大导致返回空 choices把 max_tokens 调到 2048 以内。报错五OAuth 或鉴权流程卡住。有些客户端默认走 OAuth 登录云端接本地后端时要在设置里显式切换成 API Key 模式否则它会一直尝试刷新 token。在 openclaw 的 provider 设置里选openai-compatible填上 Base URL 和 Key别选带 OAuth 的选项。排查顺序建议先 curl/health再 curl/v1/chat/completions最后才查 openclaw 配置。这样能快速定位是服务端问题还是客户端问题。6. 把本地模型用起来接入与进阶服务跑通之后你可以把 openclaw 的默认模型指向本地日常写代码、改注释、生成单元测试都走本地推理。如果哪天需要更强的模型也可以在 openclaw 里配多个 provider本地和云端切换着用。对于长期做 Agent 开发或需要稳定编码助手的场景可以考虑用 Coding Plan 把本地和云端的能力编排起来本地负责高频轻量请求云端负责复杂推理。如果你还没拿到 API Key或者想先试试云端模型做对比可以到 API Keys 页面创建一个接入文档里有各语言的示例。想直接体验模型对话效果模型对话页面可以快速试跑。本地部署的价值在于可控和离线而云端方案胜在模型规模和免维护两者并不冲突按场景选就行。最后留一个实用技巧把启动命令写成脚本加上nohup后台运行日志重定向到文件这样关掉终端服务也不会断。#!/bin/bash cd ~/llama.cpp/src/build/bin nohup ./llama-server \ -m ~/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 \ -c 4096 -ngl 99 -np 4 \ --api-key local-test-key \ ~/llama.cpp/server.log 21 chmod x start-server.sh之后每次./start-server.sh就能拉起服务日志在server.log里出问题先看这个文件。模型文件建议放在 SSD 上机械硬盘加载 5GB 的 GGUF 会慢到怀疑人生。