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

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 设定，且会记住。

正确做法：在聊天界面，点击右上角模型名称旁的图标，选择