🖥️ OpenClaw 本地大模型部署完全指南

导读：不想把数据发到云端？想用免费的开源模型跑Agent？本教程手把手教你在OpenClaw中接入本地大模型，从Ollama一键部署到vLLM高性能推理，总有一款适合你。

🎯 为什么选择本地部署？

📋 方案对比一览

特性	Ollama	vLLM	llama.cpp
安装难度	⭐ 极简	⭐⭐⭐ 中等	⭐⭐ 较简
GPU要求	可选	必须	可选
并发性能	一般	极强	中等
模型格式	GGUF	HF原版	GGUF
API兼容	OpenAI兼容	OpenAI兼容	OpenAI兼容
适合场景	个人/测试	生产环境	边缘设备

🚀 方案一：Ollama（推荐新手）

Ollama是目前最简单的本地大模型运行方案，一行命令即可启动。

1. 安装Ollama

# Linux / macOS
curl -fsSL https://ollama.com/install.sh | sh

# macOS (Homebrew)
brew install ollama

# Windows
# 从 https://ollama.com/download 下载安装包

2. 下载并运行模型

# 下载 Llama 3 8B（推荐入门）
ollama pull llama3:8b

# 下载 Qwen2 7B（中文优秀）
ollama pull qwen2:7b

# 下载 DeepSeek Coder V2（代码专用）
ollama pull deepseek-coder-v2:16b

# 运行模型
ollama run llama3:8b

3. 配置OpenClaw连接Ollama

# ~/.openclaw/config.yaml
providers:
  ollama:
    type: openai
    baseURL: http://localhost:11434/v1
    apiKey: "ollama"  # Ollama不需要真实key
    models:
      - llama3:8b
      - qwen2:7b
      - deepseek-coder-v2:16b

agents:
  default:
    model: ollama/llama3:8b

4. 验证连接

# 测试API是否正常
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3:8b",
    "messages": [{"role": "user", "content": "你好"}]
  }'

# 在OpenClaw中测试
openclaw chat --model ollama/llama3:8b "Hello!"

⚡ 方案二：vLLM（推荐生产环境）

vLLM是高性能推理引擎，支持PagedAttention技术，吞吐量是普通方案的数倍。

1. 安装vLLM

# 推荐使用Docker（省去CUDA依赖问题）
docker pull vllm/vllm-openai:latest

# 或pip安装
pip install vllm

2. 启动推理服务

# Docker方式启动（推荐）
docker run -d --gpus all \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --name vllm \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2-7B-Instruct \
  --served-model-name qwen2-7b \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.85

# 直接运行
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --served-model-name qwen2-7b \
  --port 8000

3. 配置OpenClaw连接vLLM

# ~/.openclaw/config.yaml
providers:
  vllm:
    type: openai
    baseURL: http://localhost:8000/v1
    apiKey: "vllm"
    models:
      - qwen2-7b

agents:
  default:
    model: vllm/qwen2-7b

🔧 方案三：llama.cpp（推荐边缘设备）

llama.cpp是纯C/C++实现的推理引擎，资源占用最低，甚至可以在树莓派上运行。

1. 编译安装

# 克隆仓库
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# 编译（启用CUDA加速）
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

# 或使用Metal加速（macOS）
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release

2. 下载GGUF模型

# 从Hugging Face下载量化模型
# 推荐来源：TheBloke, bartowski, unsloth
wget https://huggingface.co/bartowski/Qwen2-7B-Instruct-GGUF/resolve/main/Qwen2-7B-Instruct-Q4_K_M.gguf

# 启动OpenAI兼容服务
./build/bin/llama-server \
  -m Qwen2-7B-Instruct-Q4_K_M.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 99 \
  -c 4096

3. 配置OpenClaw

# ~/.openclaw/config.yaml
providers:
  llamacpp:
    type: openai
    baseURL: http://localhost:8080/v1
    apiKey: "llamacpp"
    models:
      - qwen2-7b-gguf

agents:
  default:
    model: llamacpp/qwen2-7b-gguf

🤖 推荐开源模型清单

模型	参数量	擅长领域	最低显存
Llama 3.1 8B	8B	通用对话、英文	6GB
Qwen2 7B	7B	中文、多语言	6GB
DeepSeek Coder V2	16B (MoE)	代码生成	12GB
Mistral 7B	7B	推理、指令遵循	6GB
Yi 1.5 34B	34B	复杂推理、中文	24GB
Phi-3 Mini	3.8B	轻量级、边缘设备	4GB
Gemma 2 9B	9B	多语言、安全	8GB

🏗️ OpenClaw Agent配置示例

完整配置文件

# ~/.openclaw/config.yaml - 完整示例
name: my-local-agent
default_model: ollama/qwen2:7b

providers:
  ollama:
    type: openai
    baseURL: http://localhost:11434/v1
    apiKey: "ollama"
    models:
      - qwen2:7b
      - llama3:8b

agents:
  default:
    model: ollama/qwen2:7b
    systemPrompt: |
      你是一个专业的AI助手，擅长中文对话和技术问题解答。
      使用简洁专业的语言回答问题。
    temperature: 0.7
    maxTokens: 4096

  coder:
    model: ollama/deepseek-coder-v2:16b
    systemPrompt: |
      你是一个专业的编程助手。
      优先使用Python和TypeScript。
      代码要简洁、有注释、符合最佳实践。

channels:
  telegram:
    enabled: true
    token: "your-bot-token"
  discord:
    enabled: true
    token: "your-bot-token"

多模型路由策略

# 简单问题用小模型，复杂问题用大模型
routing:
  strategy: complexity-based
  rules:
    - match: "代码|编程|debug"
      model: ollama/deepseek-coder-v2:16b
    - match: "翻译|写文章"
      model: ollama/qwen2:7b
    - default:
      model: ollama/llama3:8b

📊 性能优化技巧

1. 量化策略选择

• Q4_K_M - 最佳平衡：质量损失小，显存节省50%（推荐）
• Q5_K_M - 高质量：几乎无损，显存节省40%
• Q8_0 - 最高质量：几乎无损，显存节省25%
• Q2_K - 极限压缩：质量损失明显，仅用于测试

2. 上下文窗口优化

# Ollama设置上下文长度
OLLAMA_NUM_CTX=4096 ollama serve

# vLLM设置最大序列长度
--max-model-len 8192

# llama.cpp设置上下文
-c 4096  # 4K上下文
-c 8192  # 8K上下文（需要更多内存）

3. 批处理与并发

# vLLM并发设置（生产环境推荐）
--tensor-parallel-size 2        # 多GPU并行
--max-num-seqs 64               # 最大并发请求数
--max-num-batched-tokens 8192   # 批处理token上限

🔒 安全最佳实践

• 🔒 网络隔离：推理服务只监听localhost，不暴露到公网
• 🛡️ 模型验证：只从可信来源（Hugging Face官方）下载模型
• 📝 日志审计：启用请求日志，记录所有推理请求
• 🔑 访问控制：使用防火墙限制推理端口访问
• 💾 定期更新：保持推理引擎和模型的最新安全版本

🆘 常见问题