ClawdBot入门指南：Web控制台Config→Models→Providers模型切换实操

优质文章学习记录

09 Apr 2026 — 11 min read

ClawdBot入门指南：Web控制台Config→Models→Providers模型切换实操

1. 什么是ClawdBot？一个真正属于你的本地AI助手

ClawdBot不是另一个云端API调用工具，也不是需要反复注册、绑定手机号的SaaS服务。它是一个能完整运行在你自己的设备上的个人AI助手——从模型推理、对话管理到多渠道接入，全部离线可控。

它的后端核心由vLLM驱动，这意味着你能享受到接近商用级的推理速度和显存利用率，同时完全掌握数据主权。不需要上传任何聊天记录，不依赖外部服务器稳定性，也不用担心某天服务突然下线。你装好，它就在；你关机，它就停；你改配置，它立刻响应。

更关键的是，ClawdBot的设计哲学是「可理解、可调试、可演进」。它的配置不是藏在层层GUI背后的黑盒，而是以清晰结构化的JSON文件呈现；它的模型切换不靠神秘按钮，而是一次明确的路径导航：Config → Models → Providers；它的扩展不依赖插件市场，而是通过标准OpenAI兼容接口，轻松对接你本地部署的任意vLLM、Ollama或FastChat服务。

换句话说，ClawdBot不是把你变成用户，而是帮你成为运维者、调试者、甚至二次开发者。这篇文章要带你走通的，就是这条从“打开页面”到“换上自己模型”的真实路径。

2. 快速启动：让Web控制台真正跑起来

很多新手卡在第一步：点开http://localhost:7860，浏览器显示“无法访问此网站”。这不是安装失败，而是ClawdBot的安全机制在起作用——它默认拒绝未经认证的设备连接，防止本地服务被意外暴露。

别急，三步就能搞定：

2.1 查看待授权设备列表

在终端中执行：

clawdbot devices list

你会看到类似这样的输出：

ID Status Last Seen IP Address a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8 pending 2026-01-24 14:22 192.168.1.105

这个pending状态，就是你的浏览器正在尝试连接但还没被允许。

2.2 手动批准设备请求

复制上面显示的ID（一长串带横杠的字符），执行批准命令：

clawdbot devices approve a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8

批准成功后，终端会返回Approved提示，此时刷新浏览器页面，Web控制台就能正常加载了。

2.3 备用方案：获取带Token的直连链接

如果上述方式仍不生效（比如你在远程服务器上操作），直接运行：

clawdbot dashboard

它会输出一个含临时Token的完整URL，形如：

http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762

把这个链接复制到你本地电脑的浏览器中打开即可。注意：这个Token有有效期，每次执行命令都会生成新的，无需担心长期泄露风险。

小贴士：ClawdBot的配置文件默认位于~/.clawdbot/clawdbot.json，但在Docker容器内已映射为/app/clawdbot.json。所有UI界面上的修改，最终都会实时写入这个文件——这意味着你既可以用图形界面点点点，也可以随时用编辑器手动调整，两者完全同步。

3. 模型切换实战：从Config到Providers的全流程操作

ClawdBot的模型管理分为三层：全局配置（Config）→ 模型定义（Models）→ 提供方设置（Providers）。这不像某些工具只让你选个下拉菜单，而是给你一张清晰的“模型地图”，每一步都可追溯、可复现。

我们以更换为本地vLLM服务中的Qwen3-4B-Instruct-2507模型为例，手把手走完一次完整切换。

3.1 路径导航：UI里的三步定位法

打开Web控制台后，按顺序点击左侧菜单：

Config → 进入全局配置总览页
Models → 进入模型定义管理页
Providers → 进入模型提供方设置页

这三步不是随意排列，而是遵循“谁提供 → 提供什么 → 如何使用”的逻辑链。Providers是源头，Models是目录，Config是调用规则。

3.2 Providers设置：告诉ClawdBot去哪里找模型

在Providers页面，你会看到一个预设的vllm提供方条目。点击右侧的编辑图标，进入配置编辑模式。

你需要填写的关键字段只有三个：

baseUrl: 你本地vLLM服务的地址，例如 http://localhost:8000/v1（注意末尾的/v1不能省）
apiKey: vLLM默认接受任意非空字符串，填 sk-local 即可
api: 选择 openai-responses（这是vLLM的OpenAI兼容模式）

下方的models数组里，默认已有一项：

{ "id": "Qwen3-4B-Instruct-2507", "name": "Qwen3-4B-Instruct-2507" }

这个id必须与你在vLLM启动时指定的--model参数完全一致（包括大小写和特殊字符），否则ClawdBot会报“模型不存在”。

保存后，ClawdBot会立即向该baseUrl发起探测请求，验证连接是否通畅。如果vLLM服务未运行或端口错误，这里会直接标红提示。

3.3 Models配置：定义模型在系统内的“身份证”

回到Models页面，点击顶部的“+ Add Model”按钮。这里不是添加新模型，而是为Providers中已声明的模型创建一个“系统内标识”。

填写以下内容：

ID: vllm/Qwen3-4B-Instruct-2507（格式为 provider-id/model-id，这是ClawdBot内部唯一标识）
Name: Qwen3-4B-Instruct-2507（显示名称，可自定义）
Provider: 从下拉菜单中选择刚才配置好的vllm
Model ID: 输入 Qwen3-4B-Instruct-2507（必须与Providers中定义的id完全一致）

其他字段如Input Type、Context Length可保持默认。ClawdBot会自动从vLLM的/v1/models接口读取真实能力参数。

3.4 Config全局设定：指定默认使用的模型

最后一步，进入Config页面，找到agents.defaults.model.primary这一项。点击右侧铅笔图标，将值改为：

vllm/Qwen3-4B-Instruct-2507

这个值必须与Models中定义的ID完全一致。它代表：当用户发起普通对话、没有特别指定模型时，ClawdBot自动调用这个模型。

改完记得点击右上角的保存按钮。此时ClawdBot会热重载配置，无需重启服务。

4. 验证与调试：确认模型真的切换成功

配置完成不等于万事大吉。我们必须用最直接的方式验证：ClawdBot是否真的在用我们指定的模型？

4.1 终端命令验证：一眼看清当前模型

在终端中执行：

clawdbot models list

正常输出应类似这样：

Model Input Ctx Local Auth Tags vllm/Qwen3-4B-Instruct-2507 text 195k yes yes default

重点关注三列：

Model列显示vllm/Qwen3-4B-Instruct-2507，说明模型已注册成功
Ctx列显示195k，代表该模型支持约195K tokens上下文（远超GPT-4 Turbo的128K），这是Qwen3的真实能力
Local Auth为yes，表示模型调用走本地网络，不经过公网

如果这里没出现你的模型，或者显示unavailable，请回头检查Providers中的baseUrl是否可达（用curl http://localhost:8000/v1/models测试）。

4.2 对话实测：用一句话触发真实推理

打开Web控制台的聊天界面，输入一句简单但有区分度的提示词，例如：

请用中文总结《三体》第一部的核心冲突，并用emoji分隔三个要点。

观察两点：

响应速度：Qwen3-4B在vLLM优化下，首token延迟通常在300ms内，整段响应在2秒左右完成。如果卡顿超过5秒，可能是vLLM显存不足或模型未正确加载。
输出质量：Qwen3系列对中文语境、文学概念理解扎实，且原生支持emoji。若输出生硬、漏要点或混用英文，大概率是模型没切对，还在用默认的轻量模型。

调试心法：ClawdBot的每一次模型调用，都会在终端日志中打印详细信息，包括provider、model_id、input_tokens、output_tokens。遇到问题，第一反应不是重装，而是看日志——它比任何文档都诚实。

5. 进阶提示：避开新手最容易踩的五个坑

模型切换看似简单，但实际操作中，有五个高频问题几乎每个新手都会遇到。提前知道，就能少花两小时排查。

5.1 坑一：vLLM服务没启动，却在ClawdBot里配了地址

ClawdBot的Providers验证只做HTTP连接测试，不校验模型是否真在vLLM里加载。如果你的vLLM只起了服务但没加载Qwen3模型（比如忘了加--model Qwen3-4B-Instruct-2507参数），ClawdBot会显示“连接成功”，但实际调用时返回404。

正确做法：先确保vLLM已加载目标模型。启动命令示例：

vllm serve --model Qwen3-4B-Instruct-2507 --port 8000 --host 0.0.0.0

5.2 坑二：Providers里的`model.id`和Models里的`Model ID`大小写不一致

JSON是严格区分大小写的。qwen3-4b-instruct-2507和Qwen3-4B-Instruct-2507在ClawdBot眼里是两个完全不同的模型ID。

正确做法：全程复制粘贴，不要手动输入。从vLLM的/v1/models接口返回结果中直接复制id字段值。

5.3 坑三：Config里设了`primary`模型，但聊天时仍用旧模型

ClawdBot支持多模型并行，primary只是默认选项。如果你在聊天窗口右上角手动切换过模型，这个选择会覆盖Config设定，且会记住。

正确做法：在聊天界面，点击右上角模型名称旁的图标，选择“Reset to Default”，强制回归Config设定。

5.4 坑四：修改了UI配置，但终端里`clawdbot models list`没刷新

ClawdBot的UI保存是异步的。有时你点了，但配置还没写入磁盘，终端命令就读到了旧状态。

正确做法：保存后，等待2秒，再执行clawdbot models list。或者，直接查看/app/clawdbot.json文件，确认models.providers.vllm.models和agents.defaults.model.primary字段是否已更新。

5.5 坑五：以为换了模型就能提升所有能力，忽略了上下文长度差异

Qwen3-4B支持195K上下文，但它的单次响应长度（max_tokens）默认仍是2048。如果你需要长文本生成，必须在Config中额外设置：

"agents": { "defaults": { "model": { "primary": "vllm/Qwen3-4B-Instruct-2507", "maxTokens": 8192 } } }

否则，即使模型能“看”195K字，你也只能让它“说”2048字。

6. 总结：你已经掌握了ClawdBot模型管理的核心脉络

回顾这一路操作，你其实已经打通了ClawdBot模型体系的任督二脉：

你知道Web控制台不是玩具，而是一个可审计、可回溯的配置中枢，每一步操作都对应着JSON文件里的一行真实代码；
你理解了Providers→Models→Config这三层结构的本质：Providers是水电厂（供应能源），Models是电器名录（登记设备），Config是开关面板（控制使用）；
你亲手完成了一次完整的模型替换闭环：从UI导航、字段填写、ID对齐，到终端验证、对话实测，整个过程不依赖任何黑盒魔法；
你记住了五个最易踩的坑，下次再遇到“模型不生效”，第一反应不再是重装，而是去查vLLM日志、核对大小写、重置默认选项；
最重要的是，你建立起一种本地AI运维的思维习惯：不盲信界面，以终端为准；不猜测原因，以日志为据；不追求一键，而重视每一步的确定性。

ClawdBot的价值，从来不在它预装了什么模型，而在于它把模型选择权，稳稳地交还到你手中。现在，你可以放心地把Qwen3换成Qwen2.5、换成Phi-3、换成你自己微调的小模型——只要它们跑在vLLM上，ClawdBot就能认出它们，调用它们，为你所用。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 ZEEKLOG星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

ClawdBot入门指南：Web控制台Config→Models→Providers模型切换实操

优质文章学习记录