本地模型接入教程

在 OpenClaw Portable 和 Hermes Portable 中接入本地大模型，实现零成本、完全离线、数据不出本机的 AI 对话。

本教程覆盖最常用的四种本地模型运行时：Ollama、LM Studio、vLLM、llama.cpp / LocalAI。两个项目都通过 OpenAI 兼容 API 接入本地模型，配置方式几乎一致。

前置条件

硬件要求

软件要求

• OpenClaw Portable 或 Hermes Portable（任一即可）
• 本地模型运行时（下文详述安装方法）
• 足够的磁盘空间（7B 模型约 4-5 GB，70B 模型约 40 GB）

运行时对比

方案一：Ollama（推荐）

第一步：安装 Ollama

ollama --version

# 推荐：Qwen 2.5 7B（中文能力强，7B 体积小）
ollama pull qwen2.5:7b

# 或者：Llama 3.1 8B（英文能力强）
ollama pull llama3.1:8b

# 或者：DeepSeek V2.5（代码能力强）
ollama pull deepseek-v2.5

# 查看已下载的模型列表
ollama list

# macOS / Linux
ollama serve

# Windows：Ollama 安装后自动作为系统服务运行，无需手动启动

第二步：验证 API 可用

在终端执行以下命令，确认 Ollama API 正常响应：

# 列出可用模型（应返回 JSON）
curl http://127.0.0.1:11434/api/tags

# 测试对话（应返回模型回复）
curl http://127.0.0.1:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen2.5:7b","messages":[{"role":"user","content":"你好"}]}'

看到模型回复即表示 Ollama 已就绪，可以接入 OpenClaw / Hermes。

方案二：LM Studio

第一步：安装 LM Studio

第二步：验证

curl http://127.0.0.1:1234/v1/models

返回 JSON 列表即表示 LM Studio 服务器就绪。

方案三：vLLM

vLLM 适合有 NVIDIA GPU 的用户，提供极高的推理吞吐量。

第一步：安装

# 需要 Python 3.9+ 和 NVIDIA GPU（CUDA 12+）
pip install vllm

第二步：启动服务

# 启动 OpenAI 兼容 API 服务器
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 127.0.0.1 \
  --port 8000 \
  --max-model-len 8192

首次启动会自动从 HuggingFace 下载模型（需要网络）。下载完成后即可离线使用。

第三步：验证

curl http://127.0.0.1:8000/v1/models

方案四：llama.cpp / LocalAI

llama.cpp 是最底层的推理引擎，性能极致但配置稍复杂。LocalAI 是它的 OpenAI 兼容封装。

使用 llama.cpp 的 server 模式

# 从 GitHub 下载预编译版本
# https://github.com/ggerganov/llama.cpp/releases

# 启动服务器（以 GGUF 模型文件为例）
./llama-server \
  -m /path/to/qwen2.5-7b-instruct-q4_k_m.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 99   # GPU 层数，Apple Silicon 设为 99 表示全部卸载到 GPU

使用 LocalAI（Docker 方式）

# 一行命令启动（自动下载模型）
docker run -p 8080:8080 localai/localai:latest

验证

curl http://127.0.0.1:8080/v1/models

OpenClaw Portable 配置方法

OpenClaw 的配置中心（http://127.0.0.1:18750）可以自动检测 Ollama 和 LM Studio。其他运行时需要手动配置为"自定义中转站"。

方式一：自动检测（Ollama / LM Studio）

方式二：手动配置（vLLM / llama.cpp / 其他）

Hermes Portable 配置方法

Hermes Portable 的配置面板在 http://127.0.0.1:17520。本地模型通过"自定义 / 中转站"提供商接入。

通过配置面板（推荐）

通过 .env 文件（高级）

也可以直接编辑 data/.env 文件：

# Ollama 示例
CUSTOM_API_KEY=ollama
CUSTOM_BASE_URL=http://127.0.0.1:11434/v1

# vLLM 示例
CUSTOM_API_KEY=local
CUSTOM_BASE_URL=http://127.0.0.1:8000/v1

然后编辑 data/config.yaml：

model:
  default: "custom/qwen2.5:7b"
  provider: "custom"

保存后重启 Hermes 即可生效。

常见问题

连接失败：Connection refused

原因：本地模型服务未启动，或端口不对。

解决：

1. 确认模型服务正在运行：curl http://127.0.0.1:11434/api/tags（Ollama）或对应端口
2. 如果返回 "Connection refused"，重新启动服务：ollama serve
3. 检查是否有防火墙阻止本地连接

模型响应很慢

原因：模型太大，超出可用内存，系统在用磁盘交换。

解决：

1. 换一个更小的模型（如从 14B 降到 7B）
2. 使用更激进的量化（如从 Q8 降到 Q4_K_M）
3. 关闭其他占用内存的应用
4. Apple Silicon Mac：确认 Ollama 在使用 Metal GPU 加速（默认开启）

OpenClaw 扫描不到本地模型

原因：模型服务绑定了非标准端口，或绑定了 0.0.0.0 而非 127.0.0.1。

解决：

1. 确认服务绑定在 127.0.0.1（不是 0.0.0.0）
2. 确认使用的是标准端口（Ollama: 11434, LM Studio: 1234）
3. 如果用了非标准端口，使用「自定义中转站」手动配置

API Key 字段不能为空怎么办

本地模型不需要真实的 API Key，但配置界面要求非空。填任意字符串即可：

• Ollama：填 ollama
• LM Studio：填 lm-studio
• vLLM / llama.cpp：填 local 或 none

Hermes 报错 "model not found"

原因：config.yaml 中的模型名与本地服务实际提供的模型名不匹配。

解决：

1. 查询实际模型名：curl http://127.0.0.1:11434/v1/models
2. 复制返回 JSON 中的 id 字段值
3. 粘贴到配置面板的模型名输入框中

想同时使用云端模型和本地模型

两个项目都支持。在 OpenClaw 中，配置中心保存的是默认模型；你可以在聊天时通过命令切换。在 Hermes 中，可以配置 fallback 链：主模型用云端，fallback 用本地（或反过来）。

总结

最后更新：2026-05-20 · ·