OpenClaw 本地部署 LM Studio 全模型接入热切换教程

系列：Windows AI 环境搭建
环境：Windows 11 · OpenClaw 2026.3.14 · LM Studio · Node.js v25 · pnpm v10

OpenClaw 及衍生版本官方链接整理（2026年3月最新）

OpenClaw 手机直连配置全流程

OpenClaw搭配LM Studio VS Ollama：Windows CUDA实战深度对比与完全配置指南

【OpenClaw 本地实战 Ep.4】终极提效：一劳永逸解决切换浏览器 Token 鉴权失败与断连问题

【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆

【OpenClaw 本地实战 Ep.2】零代码对接：使用交互式向导快速连接本地 LM Studio 用 CUDA GPU 推理

【OpenClaw 本地实战 Ep.1】抛弃 Ollama？转向 LM Studio！Windows 下用 NVIDIA 显卡搭建 OpenClaw 本地极速推理服务

Windows 从源代码部署 OpenClaw

OpenClaw安装排错笔记

前言

OpenClaw 支持接入自定义 OpenAI 兼容接口，LM Studio 本地跑的模型天然满足这个条件。但很多人配置完发现 UI 里的模型下拉只有一个选项，切换不了——这不是 Bug，而是 OpenClaw 的模型注册机制需要同时维护两处配置，少一处就不会出现在下拉里。

本文覆盖从零开始的完整接入流程，包含所有坑点。

一、核心概念：为什么要配两处

OpenClaw 的配置文件 ~/.openclaw/openclaw.json 里，模型相关有两个完全独立的字段：

字段 职责
models.providers.{providerId}.models 定义模型参数（contextWindow、maxTokens、cost 等）
agents.defaults.models 决定哪些模型出现在 UI 下拉和 models list 里

两者缺一不可。 只配第一处，模型能被调用但不出现在 UI；只配第二处，模型会出现但缺少参数定义。

用 pnpm openclaw models list 验证时，Tags 列出现 configured 才说明两处都配好了：

Model                                      Tags
custom-127-0-0-1-1234/openai/gpt-oss-20b   default,configured,alias:gpt-oss-20b

二、查询 LM Studio 当前加载的模型

LM Studio 启动后默认监听 http://127.0.0.1:1234，通过标准 OpenAI 接口查询已加载模型列表：

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

返回示例：

{
  "data": [
    { "id": "openai/gpt-oss-20b", "object": "model" },
    { "id": "google/gemma-3-27b", "object": "model" },
    { "id": "meta-llama-3.1-8b-instruct-128k", "object": "model" }
  ]
}

把所有 id 记录下来，后续配置要用到。

注意：id 字段必须与 LM Studio 返回的完全一致，包括大小写和斜杠。

三、配置 models.providers（定义模型参数）

打开配置文件：

notepad C:\Users\你的用户名\.openclaw\openclaw.json

找到 models.providers.custom-127-0-0-1-1234.models 数组，按以下格式为每个模型添加一条记录：

{
  "id": "openai/gpt-oss-20b",
  "name": "GPT-OSS 20B",
  "reasoning": false,
  "input": ["text"],
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
  "contextWindow": 32000,
  "maxTokens": 8192
}

字段说明：

  • id：必须与 LM Studio /v1/models 返回的 id 完全一致
  • name：UI 中的显示名称，可自定义
  • reasoning：是否为思维链模型，普通模型填 false
  • input：输入类型，纯文本模型填 ["text"]，多模态填 ["text", "image"]
  • cost：本地模型全填 0
  • contextWindow：模型最大上下文长度
  • maxTokens：单次最大输出 token 数

contextWindow 参考值：

模型类型 建议值
普通 7B/8B/9B 32000
名字含 128k 的模型 131072
小型模型（2B 以下） 8192
GPT-2 系列 1024

坑点：embedding 模型（如 text-embedding-nomic-embed-text-v1.5）不能用于对话，不要加进来。

四、配置 agents.defaults.models（注册到 UI）

在同一个配置文件里，找到 agents.defaults.models 字段，为每个模型添加一条记录。

key 的格式是 {providerId}/{modelId}，value 可以是空对象，也可以加 alias 设置别名：

"agents": {
  "defaults": {
    "model": {
      "primary": "custom-127-0-0-1-1234/openai/gpt-oss-20b"
    },
    "models": {
      "custom-127-0-0-1-1234/openai/gpt-oss-20b": { "alias": "gpt-oss-20b" },
      "custom-127-0-0-1-1234/google/gemma-3-27b": {},
      "custom-127-0-0-1-1234/meta-llama-3.1-8b-instruct-128k": {},
      "custom-127-0-0-1-1234/neuraldaredevil-8b-abliterated": {}
    },
    "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace"
  }
}

坑点：providerId 是 custom-127-0-0-1-1234（端口 1234 被编码进了 id），如果你改过 LM Studio 端口，providerId 会不同，注意对应。

五、完整配置文件示例

以下是包含多个模型的完整 openclaw.json 关键部分：

{
  "models": {
    "mode": "merge",
    "providers": {
      "custom-127-0-0-1-1234": {
        "baseUrl": "http://127.0.0.1:1234/v1",
        "apiKey": "你的apikey",
        "api": "openai-completions",
        "models": [
          {
            "id": "openai/gpt-oss-20b",
            "name": "GPT-OSS 20B",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 32000,
            "maxTokens": 8192
          },
          {
            "id": "google/gemma-3-27b",
            "name": "Gemma 3 27B",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 32000,
            "maxTokens": 8192
          },
          {
            "id": "meta-llama-3.1-8b-instruct-128k",
            "name": "Llama 3.1 8B 128K",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom-127-0-0-1-1234/openai/gpt-oss-20b"
      },
      "models": {
        "custom-127-0-0-1-1234/openai/gpt-oss-20b": { "alias": "gpt-oss-20b" },
        "custom-127-0-0-1-1234/google/gemma-3-27b": {},
        "custom-127-0-0-1-1234/meta-llama-3.1-8b-instruct-128k": {}
      },
      "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace"
    }
  }
}

六、验证配置

保存配置文件后，重启 gateway：

pnpm openclaw gateway

新开终端验证模型列表：

pnpm openclaw models list

正确输出应该能看到所有配置的模型，Tags 列都有 configured：

Model                                      Input   Ctx    Local  Auth  Tags
custom-127-0-0-1-1234/openai/gpt-oss-20b   text    31k    yes    yes   default,configured,alias:gpt-oss-20b
custom-127-0-0-1-1234/google/gemma-3-27b   text    31k    yes    yes   configured
custom-127-0-0-1-1234/meta-llama-3.1-8b... text    128k   yes    yes   configured

如果某个模型没有 configured 标签，检查它是否在 agents.defaults.models 里漏掉了。

打开 Control UI（http://127.0.0.1:18789?token=你的token），进入代理 → Overview → Model Selection，下拉列表应出现所有模型，点击即可热切换。

七、以后新增模型的流程

LM Studio 加载了新模型后，只需编辑 openclaw.json 做两处追加，重启 gateway 即可：

第一处，在 models.providers.custom-127-0-0-1-1234.models 数组末尾追加：

{
  "id": "新模型的id",
  "name": "自定义显示名",
  "reasoning": false,
  "input": ["text"],
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
  "contextWindow": 32000,
  "maxTokens": 8192
}

第二处，在 agents.defaults.models 对象里追加：

"custom-127-0-0-1-1234/新模型的id": {}

八、常见问题

Q：保存配置后 UI 下拉仍然只有一个模型？
A：先确认 agents.defaults.models 里是否真的加了新模型，用 pnpm openclaw models list 验证。如果 CLI 里也只有一个模型，说明配置文件没有正确保存，或者 gateway 没有重启。

Q：pnpm openclaw config set 命令设置数组类型报错 expected array, received string？
A：PowerShell 的引号问题，数组类型必须用转义引号写法：

pnpm openclaw config set 字段名 '[\"值1\",\"值2\"]'

直接编辑 openclaw.json 文件更可靠，避免这个问题。

Q：模型 id 里含有 @ 符号（如量化版本），能正常使用吗？
A：可以，@ 在 JSON key 里合法，正常配置即可：

"custom-127-0-0-1-1234/qwen3.5-9b@q4_k_m": {}

Q：LM Studio 重启后切换了加载的模型，OpenClaw 需要重新配置吗？
A：不需要，openclaw.json 里只是定义了模型的参数元数据，实际调用时发给 LM Studio 的是 model id，LM Studio 自己处理。只要模型 id 对应的模型在 LM Studio 里是加载状态，调用就能成功。

Q：切换模型后，OpenClaw 首轮对话为什么那么慢？
A：因为切换模型后，模型需要重新加载，首次加载完成过后，连续聊天就没有那么慢了，另外显卡参数也影响着模型体验。LM Studio 中设置的模型“最大等待时间”，也影响着间隔时长后的首轮对话速度（显存释放与模型重载）。

小结

步骤 操作
1 curl http://127.0.0.1:1234/v1/models 获取所有模型 id
2 在 models.providers.xxx.models 数组里为每个模型定义参数
3 在 agents.defaults.models 对象里为每个模型添加 "providerId/modelId": {}
4 重启 gateway，models list 验证出现 configured 标签
5 UI 下拉热切换

两处配置的分工记清楚，后续维护模型列表就很轻松了。

# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区