ClawdBot入门指南：Web UI中Config→Models→Providers模型热切换教学

ClawdBot入门指南：Web UI中Config→Models→Providers模型热切换教学

1. 什么是ClawdBot？——你的本地AI助手，开箱即用

ClawdBot 是一个专为个人用户设计的轻量级 AI 助手，它不依赖云端服务，所有推理和交互都在你自己的设备上完成。你可以把它理解成一个“装在自己电脑里的智能副驾驶”：不需要注册账号、不上传隐私数据、不绑定手机号，下载即用，关机即停。

它的核心能力由 vLLM 提供支撑——这是目前最高效的开源大模型推理引擎之一，支持高吞吐、低延迟的文本生成。这意味着，哪怕你只有一台中端笔记本或树莓派，也能流畅运行 Qwen3、Phi-3、Llama-3 等主流 4B 级别模型，响应速度接近实时。

和市面上很多“套壳聊天界面”不同，ClawdBot 的设计哲学是可配置、可观察、可切换。它不是把模型硬编码进程序里，而是把模型当作“插件”来管理：你可以随时在 Web 界面里添加新模型、删掉旧模型、切换默认模型，甚至让不同对话使用不同模型——整个过程无需重启服务、不中断当前会话、不修改一行代码。

这正是本教程要带你掌握的核心能力：在 Web UI 中，通过 Config → Models → Providers 三级路径，完成模型的热切换。它不是高级功能，而是 ClawdBot 的基础操作，就像换手机壁纸一样简单直接。

2. 准备工作：先让 Web 控制台跑起来

在动手改模型之前，得先让 ClawdBot 的 Web 控制台（Control UI）能正常打开。很多新手卡在这一步，不是配置错了，而是忽略了它的安全机制——ClawdBot 默认启用设备认证，防止未授权访问。

2.1 启动服务并获取初始访问权限

假设你已通过 Docker 或源码方式成功启动 ClawdBot（如docker run -p 7860:7860 -v ~/.clawdbot:/app clawdbot/clawdbot），此时直接访问http://localhost:7860通常会失败，页面显示空白或连接拒绝。

这是因为 ClawdBot 启动后会自动生成一个待审批的设备请求。你需要进入容器或宿主机终端，执行：

clawdbot devices list

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

ID Status Created At Last Seen a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8 pending 2026-01-24 14:22:18 -

状态为pending的条目，就是你的浏览器正在尝试连接但尚未被授权的设备。复制 ID，执行批准命令：

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

批准后，刷新网页，控制台就能正常加载了。

2.2 如果还是打不开？用 token 链接直连

极少数情况下（比如你在远程服务器部署、或本地网络环境特殊），即使批准了设备，前端仍可能无法建立 WebSocket 连接。这时不要反复重试，直接用内置命令获取带认证的直连地址：

clawdbot dashboard

输出中会明确给出两个链接：

Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762 ... Then open: http://localhost:7860/ http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762

请务必使用带?token=...的完整链接。这个 token 是单次有效、有时效性的临时凭证，绕过了设备认证流程，确保你能第一时间进入 UI。

小贴士：ClawdBot 的配置文件默认存放在~/.clawdbot/clawdbot.json，Docker 容器内映射为/app/clawdbot.json。所有后续的模型配置变更，最终都会写入这个文件。你完全可以用nano或vim直接编辑它，但本教程推荐优先使用 Web UI —— 更直观、更少出错、还能实时校验格式。

3. 模型热切换实战：三步完成 Providers 配置

现在，我们正式进入主题。ClawdBot 的模型管理采用三层结构：Providers（提供方）→ Models（模型列表）→ Agent 默认模型（使用入口）。热切换的关键，在于前两层；而“热”的本质，是 UI 操作会自动触发配置重载，无需手动 restart。

3.1 进入模型配置界面

打开 Web 控制台后，鼠标移至左侧导航栏，依次点击：

• Config（全局配置入口）
• Models（模型管理中心）
• Providers（模型提供方设置）

你会看到一个简洁的表格，当前只有一行：vllm。这就是默认的模型后端，指向本地运行的 vLLM 服务（通常监听http://localhost:8000/v1）。

注意：这个vllm不是模型名，而是“提供方标识符”。你可以把它想象成一个插槽名称，后面可以插任意兼容 OpenAI API 格式的后端，比如 Ollama、LM Studio、甚至远程的 Together.ai 或 Groq。

3.2 添加第二个 Providers：支持本地 Ollama

假设你想同时接入 Ollama 运行的llama3.1:8b模型，让它和现有的 vLLM 并存，实现按需切换。操作如下：

1. 点击右上角+ Add Provider按钮
2. 在弹窗中填写：
   • Provider ID:ollama（自定义，建议小写无空格）
   • Base URL:http://localhost:11434/v1（Ollama 默认 API 地址）
   • API Type:openai-responses（Ollama 0.1.40+ 已原生兼容）
   • API Key: 留空（Ollama 无需密钥）
3. 点击Save

保存后，Providers 表格中会出现第二行：ollama。

3.3 为 Providers 添加具体模型

Providers 只是“渠道”，真正干活的是模型。接下来，我们要告诉ollama这个渠道，它能提供哪些模型：

1. 在ollama行右侧，点击Edit Models（铅笔图标）
2. 在弹出的模型列表中，点击+ Add Model
3. 填写：
   • Model ID:llama3.1:8b（必须与 Ollama 中ollama list显示的名称完全一致）
   • Display Name:Llama3.1-8B（本地Ollama）（仅用于UI显示，可自由命名）
4. 点击Add

此时，ollama行的 “Models” 列会显示llama3.1:8b。你还可以继续添加phi-3:mini、gemma2:2b等，只要它们已在 Ollama 中pull完毕。

3.4 验证新模型是否就绪

配置完成后，ClawdBot 会自动向新 Providers 发起探测请求。几秒钟后，你可以在 Providers 表格中看到状态列从?变为 （绿色对勾），表示连接成功。

为进一步确认，回到终端，执行：

clawdbot models list

你会看到输出中新增了一行：

ollama/llama3.1:8b text 128k yes no

这说明：
ollama提供方已注册成功
llama3.1:8b模型已被识别
它已加入全局模型池，可供任何 Agent 调用

整个过程耗时不到 20 秒，没有重启、没有报错、没有打断任何正在进行的对话——这就是真正的“热切换”。

4. 让模型真正用起来：从配置到对话的完整链路

光把模型加进列表还不够，你得知道怎么让它在实际对话中生效。ClawdBot 的模型调用逻辑非常清晰：Agent 决定用哪个模型 → Provider 决定从哪调用 → 模型 ID 决定具体实例。

4.1 修改 Agent 默认模型（全局生效）

最简单的方式，是修改所有新对话的默认模型。回到 Web UI：

• 点击左侧Config
• 找到Agents→Defaults区域
• 在Model下拉框中，选择你刚添加的ollama/llama3.1:8b
• 点击Save Changes

保存后，所有新开的聊天窗口，都将默认使用 Llama3.1 模型。你可以立刻在聊天框输入你好测试，响应内容、风格、速度都会与之前的 Qwen3 明显不同。

4.2 为单次对话指定模型（灵活切换）

如果你不想全局切换，只想在某个特定对话中试试新模型，ClawdBot 也支持“会话级覆盖”：

1. 打开任意一个聊天窗口
2. 点击右上角⋯（更多选项）
3. 选择Change Model
4. 从下拉菜单中选择ollama/llama3.1:8b

此时，该窗口的后续所有消息，都将发送给 Llama3.1 处理，而其他窗口仍使用原来的 Qwen3。这种粒度，让你能并行对比多个模型的效果，无需来回切换配置。

4.3 深度验证：检查模型实际调用日志

想确认某次回复真的来自 Llama3.1 而非缓存？最可靠的方法是看日志。在终端中执行：

clawdbot logs --tail 20

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

[INFO] agent-12345: using model 'ollama/llama3.1:8b' (provider: ollama) [DEBUG] ollama: POST http://localhost:11434/v1/chat/completions → 200 OK [INFO] agent-12345: response received in 1.82s, 124 tokens

其中provider: ollama和ollama/llama3.1:8b清晰表明了调用路径。如果看到vllm/Qwen3-4B-Instruct-2507，说明你切回了原模型——一切尽在掌握。

5. 进阶技巧：不止于切换，还能组合与优化

掌握了基础热切换，你已经超越了 80% 的新手。但 ClawdBot 的强大之处，在于它把模型管理变成了“乐高式搭建”。以下三个技巧，帮你把效率再提一档。

5.1 模型分组：用 Tags 实现语义化分类

ClawdBot 支持给每个模型打 Tag（标签），比如fast、creative、accurate、chinese。你可以在 Providers → Edit Models 的编辑页中添加：

• Model ID:Qwen3-4B-Instruct-2507
• Display Name:Qwen3-4B（中文强项）
• Tags:chinese, instruct

添加后，clawdbot models list输出中，该模型的 Tags 列就会显示chinese instruct。未来你写自动化脚本或配置 Agent 规则时，就可以按 Tag 筛选，而不是硬编码模型 ID。

5.2 故障隔离：为 Providers 设置 fallback

现实场景中，某个后端可能临时不可用（比如 Ollama 崩溃、vLLM 显存不足）。ClawdBot 支持配置 fallback 链：当主 Providers 调用失败时，自动降级到备用 Providers。

这需要手动编辑clawdbot.json，在models.providers下添加：

"vllm": { "baseUrl": "http://localhost:8000/v1", "apiKey": "sk-local", "api": "openai-responses", "fallback": ["ollama"], "models": [ ... ] }

这样，当 vLLM 返回 503 错误时，ClawdBot 会无缝转调ollama的同名模型，用户完全无感知。

5.3 性能微调：调整 Providers 的并发与超时

每个 Providers 都可独立配置性能参数。例如，Ollama 在 CPU 上运行较慢，你可以适当增加超时时间，避免频繁报错：

• 在 Providers 编辑页，展开Advanced Options
• 设置Timeout:120（秒）
• 设置Max Concurrent Requests:2（限制并发数，防 OOM）

这些参数不会影响其他 Providers，真正做到“各管各的，互不干扰”。

6. 常见问题与避坑指南

即使流程再简单，新手也常在细节上栽跟头。以下是实测高频问题及解决方案，帮你省下至少 2 小时调试时间。

6.1 问题：Providers 状态一直是 ❌，提示 “Connection refused”

原因：ClawdBot 尝试连接http://localhost:11434，但 Ollama 服务根本没启动，或监听在其他地址（如0.0.0.0:11434）。

解决：

• 先在终端执行ollama serve确保服务运行
• 检查curl http://localhost:11434/health是否返回{"status":"ok"}
• 如果你在 Docker 中运行 Ollama，ClawdBot 容器内localhost指向自身，需改用宿主机 IP（如http://host.docker.internal:11434/v1）

6.2 问题：clawdbot models list不显示新模型，但 UI 里能看到

原因：Providers 配置已保存，但 ClawdBot 还未完成模型探测（尤其网络稍慢时）。

解决：

• 等待 10–15 秒，刷新 UI，看状态是否变
• 或执行clawdbot models reload强制重新加载全部 Providers
• 终极方案：clawdbot restart（仅重启模型服务，不中断 Web UI）

6.3 问题：切换模型后，对话响应变慢，甚至超时

原因：新模型（如llama3.1:8b）在你的硬件上推理速度低于预期，而默认超时时间（30 秒）不够。

解决：

• 进入 Providers → Edit → Advanced Options → 调大Timeout
• 或在 Agents → Defaults 中，为该模型单独设置timeout: 90（单位：秒）
• 更治本：换用更轻量的模型，如phi-3:mini，它在 CPU 上也能秒级响应

6.4 重要提醒：不要手动编辑clawdbot.json后再进 UI 修改

ClawdBot 的 UI 会全量覆盖clawdbot.json文件。如果你先手工添加了 Providers，又进 UI 点了 Save，所有手工写的注释、额外字段都会被清空。唯一安全的手动编辑时机，是在 UI 完全关闭后。日常维护，请坚定地只用 Web UI。

7. 总结：热切换不是功能，而是工作流的起点

回顾整个过程，你其实只做了三件事：点开 Config → 进 Models → 点 Providers → 填两个地址、加一个名字。没有命令行恐惧，没有 JSON 格式报错，没有服务重启等待。ClawdBot 把原本属于运维工程师的复杂操作，压缩成了产品经理都能上手的点击流。

但这只是开始。当你能随心所欲地切换模型，真正的可能性才浮现出来：

• 用 Qwen3 写中文文案，用 Llama3.1 做英文润色，一次对话跨语言协作；
• 用 Phi-3 快速草拟思路，再用 Qwen3 深度扩展，形成“快+准”双模工作流；
• 为客服 Agent 配 fast 模型，为创意 Agent 配 creative 模型，让不同角色各司其职。

模型热切换，本质上切换的不是技术参数，而是你的思考方式。它把“AI 是一个黑盒工具”的认知，升级为“AI 是一组可编排的能力模块”。而 ClawdBot，正是帮你迈出这一步最平滑的那块垫脚石。

获取更多AI镜像

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