QClaw 调用本地 Ollama 大模型完整教程

一、环境准备（前置条件）

1. Ollama 已安装并运行

   • 前往 ollama.com下载安装。

   • 验证：打开终端（CMD/PowerShell），输入 ollama run llama3.1:8b（或其他你需要的模型），确认能正常对话后 Ctrl+C退出。

   • 关键：Ollama 必须保持运行（任务栏有章鱼图标）。

2. QClaw 已安装

   • 从官网下载并安装，至少启动一次以生成配置文件目录。

3. 获取本机 IP（关键）

   • 由于 QClaw 可能通过容器或独立进程运行，不建议使用 localhost。

   • 你的 IP：根据你之前的配置，请使用 实际IP，如192.168.112.186样式（或通过 ipconfig查询本机实际 IP）。

二、配置文件修改（核心步骤）

文件路径：C:\Users\<你的用户名>\.qclaw\openclaw.json

注意：请先关闭 QClaw 客户端，再用 VS Code 或记事本修改此文件。

1. 完整配置文件（直接复制替换）

将以下内容完全覆盖到 openclaw.json文件中。此配置已包含：

• 保留原有的云端 qclaw模型（作为备用）。

• 新增 ollama-local提供商（指向你的本地 IP）。

• 设置默认模型为 glm-4.7-flash并配置界面别名。具体模型名以安装的模型为准，这里GLM-4.7只供参考。

{
  "models": {
    "mode": "merge",
    "providers": {
      "qclaw": {
        "baseUrl": "${QCLAW_LLM_BASE_URL}",
        "apiKey": "${QCLAW_LLM_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "modelroute",
            "name": "modelroute",
            "input": ["text", "image"]
          }
        ]
      },
      "ollama-local": {
        "baseUrl": "http://192.168.112.186:11434/v1",
        "apiKey": "ollama",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-4.7-flash:q4_K_M",
            "name": "glm-4.7-flash:q4_K_M"
          },
          {
            "id": "qwen3.5:35b-a3b",
            "name": "qwen3.5:35b-a3b"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama-local/glm-4.7-flash:q4_K_M",
        "fallbacks": ["qclaw/modelroute"]
      },
      "models": {
        "ollama-local/glm-4.7-flash:q4_K_M": {
          "alias": "🦞 本地 GLM-4"
        },
        "ollama-local/qwen3.5:35b-a3b": {
          "alias": "🦞 本地 Qwen"
        }
      }
    }
  }
}

2. 配置项说明（避坑指南）

三、重启与验证

1. 保存并重启：保存 openclaw.json文件，然后完全退出 QClaw（包括右下角托盘图标），再重新启动。

2. 界面验证：

   • 打开 QClaw，在输入框上方的模型选择栏中，你应该能看到 🦞 本地 GLM-4选项，且已默认选中。

3. 功能验证：

   • 发送一条测试消息（如“你好”）。

   • 成功标志：Ollama 终端或任务管理器中出现 GPU/CPU 占用飙升，且 QClaw 能正常回复。

   • 失败回退：如果长时间无响应，配置中的 fallbacks会使其自动切换到云端 qclaw模型。

四、常见问题排查（FAQ）

Q1：模型列表里看不到“本地 GLM-4”，只有默认模型？

A：检查 agents.defaults.models里的 alias是否配置正确。如果没有 alias，模型可能不会出现在 UI 下拉菜单中。

Q2：一直显示“连接中”或超时？

A：

1. 确认 Ollama 服务真的在运行（ollama list有输出）。

2. 确认 IP 地址不是 localhost，改为你的本机局域网 IP（如 192.168.xx.xx）。

3. 检查防火墙是否拦截了 11434 端口。

Q3：想换回云端模型怎么办？

A：将 agents.defaults.model.primary改回 "qclaw/modelroute"即可。

Q4：配置改了但没生效？

A：QClaw 有时热重载不灵敏，必须彻底关闭客户端再重新打开。