OpenClaw版本升级与本地模型Qwen对接教程

最近，

终于不再疯狂的更新了，有时间把旧的版本，本文记录了升级、配置的过程，并分享踩坑与排错经验。

为什么要用 OpenClaw + 本地模型？

• 数据隐私
  ：所有对话和工具调用都运行在本地，不经过第三方 API。

• 成本可控
  ：使用开源模型（如 Qwen、Llama）可大幅降低调用成本。

• 灵活扩展
  ：OpenClaw 的插件体系让智能体不仅能聊天，还能执行实际操作（文件、浏览器、设备等）。

第一步：升级 OpenClaw 到最新版

OpenClaw 团队迭代很快，建议始终使用最新稳定版。升级方式取决于你的安装方式：

直接安装（推荐）

powershell -c "irm https://openclaw.ai/install.ps1 | iex"

通过 npm 全局安装

npm update -g openclaw

检查版本：

openclaw --version
# 示例输出：2026.7.1-2 (0790d9f)

第二步：配置自定义模型提供者（本地 Qwen 服务）

我的本地模型服务通过LM Studio或Ollama启动，运行在 http://192.168.1.12:1234/v1 ，模型ID为 qwen3.6-35b-a3b 。

使用onboard非交互式命令一次性配置

OpenClaw 提供了 onboard 向导，我们使用非交互模式（适合脚本化和重复执行）：

openclaw onboard --non-interactive --accept-risk 
  --auth-choice custom-api-key 
  --custom-provider-id my-local-llm 
  --custom-base-url http://192.168.1.12:1234/v1 
  --custom-model-id qwen3.6-35b-a3b 
  --custom-api-key "none" 
  --custom-compatibility openai

：

• --accept-risk：必须显式确认风险（AI 智能体有系统访问权限）。
• --auth-choice custom-api-key：使用自定义 API Key 方式（本地模型无需真实 key）。
• --custom-provider-id：给这个提供商起一个唯一名称，例如 my-local-llm。
• --custom-base-url：你的本地 API 端点。
• --custom-model-id：模型实际 ID。
• --custom-api-key：本地服务若无认证，填 "none" 即可。
• --custom-compatibility openai：大多数本地服务兼容 OpenAI API 格式。

执行后，配置会写入 ~/.openclaw/openclaw.json。如果遇到健康检查超时（因为网关未启动），无需担心，配置已经保存。

设置默认模型

虽然提供商已添加，但 OpenClaw 的 Agent 默认可能仍使用 OpenAI。我们需要手动指定默认模型路径（格式为 provider/model）：

openclaw config set agents.defaults.model "my-local-llm/qwen3.6-35b-a3b"

如果希望特定 Agent（如 main）也使用该模型：

openclaw agents set main --model "my-local-llm/qwen3.6-35b-a3b"

：早期版本的 OpenClaw 不支持 agents.defaults.provider，只能设置 model，且必须包含提供商前缀。

第三步：启动网关并访问 Web 控制台

启动网关（前台运行，便于调试）

openclaw gateway run

日志显示 http server listening 和 agent model: my-local-llm/qwen3.6-35b-a3b 即表示成功。

作为后台服务运行（推荐）

为了开机自启，可以安装为系统服务（Windows 计划任务）：

openclaw gateway install   # 或 openclaw onboard --install-daemon

启动/停止/重启：

openclaw gateway start
openclaw gateway stop
openclaw gateway restart

获取 Web 控制台地址

网关默认监听 127.0.0.1:18789，访问地址为 http://127.0.0.1:18789/。

但首次访问需要认证 Token，可通过以下命令获取完整链接（含 Token）：

openclaw dashboard --no-open

复制输出的 URL 到浏览器即可进入控制台。

第四步：验证与测试

在 Web 控制台发送一条消息，例如“北京今天天气怎么样？”，观察网关日志：

[provider-transport-fetch] [model-fetch] start provider=my-local-llm model=qwen3.6-35b-a3b url=http://192.168.1.12:1234/v1/chat/completions
[provider-transport-fetch] [model-fetch] response status=200 elapsedMs=351 contentType=text/event-stream

如果看到 status=200，说明模型调用成功。如果天气插件已启用，你还会看到工具调用日志。

常见问题与解决

No API key found for provider "openai"

：Agent 仍回退到默认 OpenAI 提供者。

：首先，仔细检查 agents.defaults.model 是否正确设置为 my-local-llm/qwen3.6-35b-a3b 。其次，认真确认配置中是否不存在残留的 agents.defaults.provider 。

Config path not found: agents.defaults.provider

：你的配置版本不支持该路径，直接设置 model 即可，无需设置 provider。

网关启动失败，端口 18789 被占用

：使用 openclaw gateway stop 停止旧进程，或换端口启动：openclaw gateway run --port 18790。

Web 控制台无法连接（WebSocket 错误）

• 检查网关是否正在运行：openclaw status
• 检查防火墙是否放行 18789 端口。
• 访问时需带上 Token 参数（或通过 openclaw dashboard --no-open 生成的完整链接）。

本地模型服务不可达

• 验证服务是否在 http://192.168.1.12:1234/v1/models 可访问。
• 检查 IP 地址是否正确，若为动态 IP，建议使用静态 IP 或主机名。

配置文件片段（供参考）

最终 ~/.openclaw/openclaw.json 中关键部分如下（已隐去敏感信息）：

{
  "models": {
    "providers": {
      "my-local-llm": {
        "baseUrl": "http://192.168.1.12:1234/v1",
        "apiKey": "none",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.6-35b-a3b",
            "name": "Qwen 3.6",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 8192,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "my-local-llm/qwen3.6-35b-a3b"
    },
    "main": {
      "model": "my-local-llm/qwen3.6-35b-a3b"
    }
  },
  "gateway": {
    "auth": {
      "token": "claw-xxxx-xxxx-xxxx"   // 请妥善保管
    },
    "port": 18789
  }
}

总结

通过上述步骤，我成功将 OpenClaw 升级到最新版，并完成了本地模型的对接。现在，我可以：

• 在漂亮的 Web 控制台与智能体对话。
• 调用内置插件（天气、搜索、文件等），而所有 AI 推理都运行在本地。
• 享受与云端模型接近的体验，同时拥有完全的隐私和控制权。

OpenClaw 的模块化设计让接入自定义模型非常顺畅，即使是非交互式配置也足够灵活。如果你也想打造自己的专属 AI 助理，不妨按照本文试一试！