每日备份 2026-06-10 12:57:13

2026-06-10 12:57:14 +08:00
1 parent fda2ccb8c2
commit 3d2e638c6a
@@ -0,0 +1,366 @@
+# Ollama + OpenClaw 配置指南
+
+## 概述
+
+Ollama 是一个本地 LLM 运行时，让你能轻松在本地运行开源模型。OpenClaw 通过 OpenAI 兼容 API 与 Ollama 集成。
+
+---
+
+## 一、Ollama 安装与配置
+
+### 安装 Ollama
+
+```bash
+# Linux
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# 启动服务
+ollama serve
+
+# 设置开机自启（Linux）
+sudo systemctl enable ollama
+sudo systemctl start ollama
+```
+
+### 配置跨主机访问
+
+默认只监听 `127.0.0.1`，需要配置才能从其他机器访问：
+
+```bash
+# 方法1：环境变量
+export OLLAMA_HOST=0.0.0.0:11434
+
+# 方法2： systemd 服务配置
+sudo systemctl edit ollama
+```
+
+添加：
+```ini
+[Service]
+Environment="OLLAMA_HOST=0.0.0.0:11434"
+```
+
+重启服务：
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart ollama
+```
+
+验证：
+```bash
+curl http://192.168.0.66:11434/api/tags
+```
+
+---
+
+## 二、OpenClaw 配置 Ollama
+
+### 方法1：自动发现（推荐）
+
+设置环境变量即可自动发现模型：
+
+```bash
+# 设置 API key（任意值，Ollama 不验证）
+export OLLAMA_API_KEY="ollama-local"
+
+# 或在配置中设置
+openclaw config set models.providers.ollama.apiKey "ollama-local"
+```
+
+自动发现会：
+- 查询 `/api/tags` 和 `/api/show`
+- 只保留报告支持工具的模型
+- 自动设置 contextWindow 和 maxTokens
+
+### 方法2：显式配置（远程主机）
+
+当 Ollama 在其他主机时，需要显式配置：
+
+```json5
+{
+  "models": {
+    "providers": {
+      "ollama": {
+        "baseUrl": "http://192.168.0.66:11434/v1",
+        "apiKey": "ollama-local",
+        "api": "openai-completions"
+      }
+    }
+  }
+}
+```
+
+### 设置默认模型
+
+```json5
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "ollama/llama3.3",
+        "fallbacks": ["ollama/qwen2.5-coder:32b"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## 三、推荐模型
+
+### 对话模型
+
+| 模型 | 大小 | 说明 |
+|------|------|------|
+| llama3.3 | ~5GB | 70B 参数，推荐主力 |
+| qwen2.5-coder:32b | ~20GB | 代码能力强 |
+| deepseek-r1:32b | ~20GB | 推理能力强 |
+
+拉取命令：
+```bash
+ollama pull llama3.3
+ollama pull qwen2.5-coder:32b
+ollama pull deepseek-r1:32b
+```
+
+### Embedding 模型（用于内存管理）
+
+| 模型 | 大小 | 说明 |
+|------|------|------|
+| nomic-embed-text | ~137MB | 推荐，质量好 |
+| mxbai-embed-large | ~334MB | 更大，质量更好 |
+| all-minilm | ~23MB | 轻量级 |
+
+拉取命令：
+```bash
+# 推荐
+ollama pull nomic-embed-text
+
+# 或轻量级
+ollama pull all-minilm
+```
+
+### 验证 Embedding 模型
+
+```bash
+curl http://192.168.0.66:11434/api/tags | python3 -c "import sys,json; print([m['name'] for m in json.load(sys.stdin).get('models',[])])"
+```
+
+---
+
+## 四、内存管理器配置
+
+### 启用内存管理器
+
+内存管理器需要 embedding 模型：
+
+```json5
+{
+  "models": {
+    "providers": {
+      "ollama": {
+        "baseUrl": "http://192.168.0.66:11434/v1",
+        "apiKey": "ollama-local",
+        "api": "openai-completions",
+        "embedding": "nomic-embed-text"  // 指定 embedding 模型
+      }
+    }
+  }
+}
+```
+
+### 环境变量配置
+
+```bash
+# OpenClaw 配置文件
+export OLLAMA_API_KEY="ollama-local"
+export OLLAMA_EMBEDDING_MODEL="nomic-embed-text"
+```
+
+---
+
+## 五、故障排查
+
+### Ollama 未检测到
+
+```bash
+# 1. 检查 Ollama 是否运行
+ps aux | grep ollama
+
+# 2. 检查 API 是否可达
+curl http://localhost:11434/api/tags
+
+# 3. 重启 Ollama
+ollama serve
+
+# 4. 检查环境变量
+echo $OLLAMA_API_KEY
+```
+
+### 没有可用模型
+
+OpenClaw 只自动发现支持工具的模型：
+
+```bash
+# 检查模型是否安装
+ollama list
+
+# 拉取支持工具的模型
+ollama pull llama3.3
+
+# 或显式配置模型（如果不想用自动发现）
+openclaw config set models.providers.ollama.models[0].id "llama3.3"
+```
+
+### 连接被拒绝
+
+```bash
+# 检查端口
+lsof -i :11434
+
+# 检查防火墙
+sudo ufw status
+
+# Ollama 绑定地址
+curl http://127.0.0.1:11434/api/tags  # 本机测试
+curl http://192.168.0.66:11434/api/tags  # 远程测试
+```
+
+### 模型不工作
+
+```bash
+# 测试模型运行
+ollama run llama3.3 "Hello"
+
+# 检查模型信息
+ollama show llama3.3
+```
+
+---
+
+## 六、完整配置示例
+
+### 单机配置（Ollama 和 OpenClaw 同机）
+
+```json5
+{
+  "models": {
+    "providers": {
+      "ollama": {
+        "apiKey": "ollama-local",
+        "models": [
+          { "id": "llama3.3", "contextWindow": 32768 },
+          { "id": "qwen2.5-coder:32b" }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "ollama/llama3.3"
+      }
+    }
+  }
+}
+```
+
+### 多机配置（主力机 Ollama + OpenClaw 独立）
+
+**主力机 (192.168.0.66):**
+```bash
+# Ollama 配置
+export OLLAMA_HOST=0.0.0.0:11434
+systemctl restart ollama
+
+# 拉取模型
+ollama pull llama3.3
+ollama pull nomic-embed-text
+```
+
+**OpenClaw 主机:**
+```json5
+{
+  "models": {
+    "providers": {
+      "ollama": {
+        "baseUrl": "http://192.168.0.66:11434/v1",
+        "apiKey": "ollama-local",
+        "api": "openai-completions"
+      },
+      "minimax": { /* ... */ },
+      "deepseek": { /* ... */ }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "ollama/llama3.3",
+        "fallbacks": ["deepseek/deepseek-chat", "minimax/minimax-m2.1"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## 七、性能优化
+
+### 模型加载
+
+```bash
+# 预加载模型（加速首次调用）
+ollama pull llama3.3
+
+# 查看已加载模型
+ollama ps
+```
+
+### 资源管理
+
+```bash
+# 设置 GPU 使用率（如果有多 GPU）
+export CUDA_VISIBLE_DEVICES=0
+
+# 设置内存限制
+export OLLAMA_NUM_PARALLEL=4
+```
+
+### 监控
+
+```bash
+# 查看 Ollama 日志
+journalctl -u ollama -f
+
+# 查看资源使用
+htop | grep ollama
+```
+
+---
+
+## 八、相关命令速查
+
+| 任务 | 命令 |
+|------|------|
+| 列出模型 | `ollama list` |
+| 拉取模型 | `ollama pull <model>` |
+| 删除模型 | `ollama rm <model>` |
+| 运行模型 | `ollama run <model>` |
+| 查看模型信息 | `ollama show <model>` |
+| 查看运行中模型 | `ollama ps` |
+| 测试 API | `curl http://localhost:11434/api/tags` |
+
+---
+
+## 九、相关文档
+
+- [OpenClaw Ollama Provider](https://docs.openclaw.ai/providers/ollama)
+- [Ollama 官方文档](https://ollama.ai)
+- [Ollama Embedding 模型](https://ollama.com/blog/embedding-models)
+- [OpenClaw 模型配置](./GATEWAY_CONFIGURATION.md)
+
+---
+
+*最后更新: 2026-02-04*