openclaw使用llama.cpp 本地大模型部署教程

Ne0inhk

25 Mar 2026 — 4 min read

openclaw使用llama.cpp 本地大模型部署教程

本教程基于实际操作整理，适用于 Windows WSL2 环境

全程使用 openclaw 帮我搭建大模型

一、环境准备

1. 硬件要求

显卡	推荐模型	显存占用
GTX 1050 Ti (4GB)	Qwen2.5-3B Q4	~2.5GB
RTX 4060 (8GB)	Qwen2.5-7B Q4	~5GB
RTX 4090 (24GB)	Qwen2.5-32B Q4	~20GB

2. 安装编译工具（WSL Ubuntu）

sudoapt update sudoaptinstall -y cmake build-essential

二、下载和编译 llama.cpp

1. 克隆源码

mkdir -p ~/llama.cpp cd ~/llama.cpp git clone --depth 1 https://github.com/ggerganov/llama.cpp.git src

2. 编译

cd ~/llama.cpp/src mkdir build &&cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j$(nproc) llama-cli llama-server

编译完成后，可执行文件在 ~/llama.cpp/src/build/bin/ 目录下。

三、下载模型

1. 创建模型目录

mkdir -p ~/llama.cpp/models

2. 下载 GGUF 模型（使用国内镜像加速）

Qwen2.5-3B（适合 4GB 显存）：

curl -L -o ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf \"https://hf-mirror.com/Qwen/Qwen2.5-3B-Instruct-GGUF/resolve/main/qwen2.5-3b-instruct-q4_k_m.gguf"

Qwen2.5-7B（适合 8GB 显存）：

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"

四、运行模型

方式一：命令行交互模式

cd ~/llama.cpp/src/build/bin ./llama-cli -m ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf \ -c 4096\ --no-display-prompt

参数说明：

-m 模型路径
-c 上下文长度（默认 512，建议 4096）
-ngl GPU 层数（纯 CPU 可不加）

方式二：启动 API 服务

cd ~/llama.cpp/src/build/bin ./llama-server \ -m ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf \ --host 0.0.0.0 \ --port 8080\ -c 4096

服务启动后访问：http://localhost:8080

五、API 调用方法

API 信息

项目	值
地址	`http://localhost:8080`
API Key	不需要（或随意填写）
兼容格式	OpenAI API

端点列表

端点	说明
`POST /v1/chat/completions`	聊天补全
`POST /v1/completions`	文本补全
`GET /health`	健康检查
`GET /`	Web 聊天界面

调用示例

curl

curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json"\ -d '{ "model": "qwen2.5-3b", "messages": [ {"role": "system", "content": "你是一个有帮助的助手。"}, {"role": "user", "content": "你好，介绍一下你自己"} ], "temperature": 0.7, "max_tokens": 512 }'

Python（OpenAI SDK）

from openai import OpenAI client = OpenAI( base_url="http://localhost:8080/v1", api_key="not-needed") response = client.chat.completions.create( model="qwen2.5-3b", messages=[{"role":"system","content":"你是一个有帮助的助手。"},{"role":"user","content":"你好"}], temperature=0.7, max_tokens=512)print(response.choices[0].message.content)

Node.js

const response =awaitfetch('http://localhost:8080/v1/chat/completions',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({model:'qwen2.5-3b',messages:[{role:'user',content:'你好'}]})});const data =await response.json(); console.log(data.choices[0].message.content);

六、常用参数说明

服务端参数（llama-server）

参数	说明	示例
`-m`	模型路径	`-m model.gguf`
`--host`	监听地址	`--host 0.0.0.0`
`--port`	端口	`--port 8080`
`-c`	上下文长度	`-c 4096`
`-ngl`	GPU 层数	`-ngl 99`（全部放 GPU）
`-np`	并行请求数	`-np 4`
`--api-key`	设置 API Key	`--api-key your-key`

API 请求参数

参数	说明	默认值
`temperature`	随机性（0-2）	0.7
`max_tokens`	最大生成长度	模型上限
`top_p`	核采样	1.0
`stream`	流式输出	false
`stop`	停止词	[]

七、常见问题

Q1: 报错 “CUDA out of memory”

减少 -ngl 数值，让部分层用 CPU 计算：

./llama-server -m model.gguf -ngl 20# 只放 20 层到 GPU

Q2: 中文乱码

PowerShell 执行：

chcp 65001

Q3: 如何后台运行服务？

nohup ./llama-server -m model.gguf --host 0.0.0.0 --port 8080> server.log 2>&1&

Q4: 如何设置 API Key 认证？

./llama-server -m model.gguf --api-key "your-secret-key"

调用时需要带上：

curl -H "Authorization: Bearer your-secret-key"...

Q5: 从其他设备访问

查看 WSL IP：hostname -I
使用该 IP 访问，如 http://172.x.x.x:8080

八、推荐模型

模型	大小	适合场景
Qwen2.5-3B-Instruct Q4	~2GB	轻量对话、低配设备
Qwen2.5-7B-Instruct Q4	~4.5GB	通用对话、代码
Qwen2.5-14B-Instruct Q4	~9GB	复杂推理
DeepSeek-R1-Distill-Qwen-7B Q4	~4.5GB	数学、逻辑推理
Mistral-7B-v0.3 Q5	~5GB	英文、代码

下载地址： https://hf-mirror.com（国内镜像）

九、文件结构

~/llama.cpp/ ├── src/ # llama.cpp 源码 │ └── build/ │ └── bin/ │ ├── llama-cli # 命令行工具 │ └── llama-server # API 服务 └── models/ # 模型存放目录 └── qwen2.5-3b-instruct-q4_k_m.gguf

十、快速启动脚本

创建 start-server.sh：

#!/bin/bashcd ~/llama.cpp/src/build/bin ./llama-server \ -m ~/llama.cpp/models/qwen2.5-3b-instruct-q4_k_m.gguf \ --host 0.0.0.0 \ --port 8080\ -c 4096\ -np 4

赋予执行权限：

chmod +x start-server.sh ./start-server.sh

教程整理于 2026-02-03
基于 llama.cpp b7917 + Qwen2.5-3B-Instruct