# 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*