ClawdBot 快速上手：Web 控制台配置、设备授权与 Dashboard 访问
1. 什么是 ClawdBot？——你的本地 AI 助手，开箱即用
ClawdBot 是一个运行在你个人设备上的轻量级 AI 助手框架，不是云端服务，也不依赖厂商 API 密钥。它把大模型能力真正交到你手上：你可以把它装在笔记本、旧台式机，甚至树莓派上，全程离线运行，数据不出设备。
它的后端由 vLLM 驱动，这意味着你能享受到接近生产级的推理吞吐和低延迟响应。但和那些需要调参、配环境、改代码的'硬核'方案不同，ClawdBot 的设计哲学是「先跑起来，再调细节」——它默认就带好模型、接口和界面，你只需要执行一条命令，就能看到一个可交互的 AI 控制台。
它不追求'最全功能'，而是专注解决三个核心问题：
- 怎么安全地连上它？（Web 控制台不是直接暴露的，有设备信任机制）
- 怎么让它听懂你想用什么模型？（不只是换名字，而是真正切换底层推理引擎）
- 怎么在浏览器里直观地操作和验证？（不是只靠命令行，而是有可视化反馈）
这三点，正是本文要带你一步步打通的关键路径。
2. 第一步：让 Web 控制台'认出你'——设备授权全流程
ClawdBot 的 Web 控制台默认不对外网开放，也不允许任意设备访问。这是出于隐私和安全考虑：你的本地 AI 助手，理应只对你本人开放。所以首次访问时，你会遇到'页面打不开'或'连接被拒绝'的提示——这不是故障，而是系统在等你完成身份确认。
整个过程分三步，全部通过终端命令完成，无需修改配置文件或重启服务：
2.1 查看待处理的设备请求
打开终端，输入以下命令：
clawdbot devices list
你会看到类似这样的输出：
ID Status Created At Last Seen IP Address abc123 pending 2026-01-24 14:22:01 2026-01-24 14:22:05 192.168.1.105 def456 approved 2026-01-23 09:15:33 2026-01-24 10:01:22 127.0.0.1
其中 pending 状态的条目，就是你当前浏览器发起的访问请求。ClawdBot 已经捕获到了这次连接尝试，但它还在等你'点头同意'。
注意：这个请求通常在你第一次打开
http://localhost:7860或http://你的 IP:7860时自动触发。如果没看到 pending 条目，请刷新一次网页再执行命令。
2.2 批准该设备访问权限
复制上面输出中 pending 行的 ID（比如 abc123），然后执行：
clawdbot devices approve abc123
如果成功，终端会返回类似提示：
Device abc123 approved. You may now access the dashboard.
此时，你刚才打开的浏览器标签页刷新一下，Web 控制台就会正常加载——左侧导航栏、顶部状态栏、中间工作区全部就位。
2.3 如果仍无法访问？用 Dashboard 命令获取直连链接
极少数情况下（比如你在远程服务器上部署，本地没有图形界面），直接访问 localhost:7860 不生效。这时别折腾端口转发或 Nginx 反代，ClawdBot 提供了更简单的方案：
clawdbot dashboard
输出会包含一段关键信息：
Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762 No GUI detected. Open from your computer: ssh -N -L 7860:127.0.0.1:7860 [email protected] Then open: http://localhost:7860/ http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
这里有两个实用技巧：
- 本地开发：直接复制
http://localhost:7860/...链接，在本机浏览器打开即可（token 是单次有效，但有效期足够长） - 远程服务器：按提示执行
ssh -N -L ...命令，它会在你本地建立一条安全隧道，之后所有对localhost:7860的访问都会被转发到远端服务，完全透明
这个机制既保证了安全性（每次访问需 token），又兼顾了便利性（不用手动配代理），是 ClawdBot 在易用性和防护之间做的一个很实在的平衡。
3. 第二步：换掉默认模型——三种方式，总有一种适合你
ClawdBot 默认内置了一个轻量但够用的模型（如 vllm/Qwen3-4B-Instruct-2507），适合快速体验。但如果你已有自己的 vLLM 服务，或者想试试其他开源模型，它支持灵活替换。我们提供三种互不冲突的方式，你可以按熟悉程度选择：
3.1 方式一：修改 JSON 配置文件（推荐给习惯命令行的用户）
配置文件路径为 /app/clawdbot.json（容器内）或 ~/.clawdbot/clawdbot.json（宿主机）。打开后找到 models.providers.vllm 区块，按如下结构修改：
{ "models": { "mode": "merge", "providers": { "vllm": { "baseUrl": "http://localhost:8000/v1", "apiKey": "sk-local", "api": "openai-responses", "models": [ { "id": "Qwen3-4B-Instruct-2507", "name": "Qwen3-4B-Instruct-2507" }, { "id": "Phi-3-mini-4k-instruct", "name": "Phi-3-mini-4k-instruct" } ] } } } }
关键点说明：
baseUrl指向你已启动的 vLLM 服务地址（注意端口是否正确）models数组里可以添加多个模型，ClawdBot 会自动识别并注册- 修改后无需重启服务，下一次调用
clawdbot models list就会生效
3.2 方式二：通过 Web UI 界面操作（推荐给视觉型用户）
进入已授权的 Dashboard 后，点击左侧菜单栏的 Config → Models → Providers，你会看到一个清晰的表格界面：
- 左侧是 provider 类型（如
vllm） - 中间是 base URL 和认证设置
- 右侧是已注册模型列表，带'+ Add Model'按钮
点击添加，填入模型 ID 和显示名称，保存即可。整个过程就像管理邮箱账户一样直观，连 JSON 格式都不用碰。
3.3 方式三：命令行快速验证模型是否就绪
无论你用哪种方式修改，最终都要确认模型真的'活'了。执行：
clawdbot models list
正常输出应类似：
Model Input Ctx Local Auth Tags vllm/Qwen3-4B-Instruct-2507 text 195k yes yes default vllm/Phi-3-mini-4k-instruct text 4k yes yes -
重点关注三列：
- Model：显示完整模型标识符，格式为
provider/model-id - Local Auth：
yes表示该模型由本地 vLLM 提供，不走外部 API - Ctx：上下文长度，帮你判断是否适合长文本任务
如果某模型显示 no 或为空，说明 baseUrl 不通、API Key 错误，或模型名拼写有误——这时回到前两步检查即可。
4. 第三步：理解界面逻辑——Dashboard 不是花架子，而是调试中枢
ClawdBot 的 Web 控制台（Dashboard）不是简单的'模型选择器 + 聊天框'。它是一个面向开发者和高级用户的调试与观察平台。界面虽简洁，但每个区域都有明确职责：
4.1 顶部状态栏：实时掌握系统健康度
- Gateway Status：显示后端服务连接状态（绿色 表示正常，红色 ❌ 表示 vLLM 未启动或网络不通）
- Active Models：列出当前已加载并可调用的模型数量
- Uptime：服务已连续运行时间，帮助你判断是否需要重启
这个区域是你排查问题的第一站。比如发现聊天无响应，先看 Gateway 是否绿色；发现模型列表为空，先看 Active Models 是否为 0。
4.2 左侧导航栏：功能模块化，各司其职
- Chat：主对话界面，支持多轮上下文、历史记录导出
- Config：集中管理所有配置项，包括模型、渠道、工作区路径等
- Logs：实时滚动日志，比终端
docker logs更聚焦（自动过滤无关信息，高亮错误） - Metrics：简单性能看板，显示当前并发请求数、平均响应延迟、GPU 显存占用（如有）
特别提醒：不要跳过 Logs 页面。很多'奇怪行为'（比如某条消息卡住、翻译结果乱码）在 Logs 里都能看到具体报错，比如 OCR timeout 或 Whisper model not found，比凭空猜测高效得多。
4.3 主工作区：所见即所得的交互验证场
在 Chat 页面，你可以做三件关键事：
- 测试模型切换效果：在右上角下拉菜单中切换不同模型，对比同一提示词下的输出风格差异
- 验证多模态能力：上传一张含文字的图片，看是否能自动 OCR + 翻译（这背后调用了 PaddleOCR）
- 模拟真实场景：输入类似
请用英文写一封辞职信，语气专业但友好的复杂指令，观察模型是否理解'语气''专业''友好'等抽象要求
这不是为了炫技，而是帮你建立对模型能力边界的直观认知——哪些任务它擅长，哪些需要加提示词引导，哪些干脆不适合交给它。
5. 补充说明：关于 Telegram 频道配置的务实建议
文档中提到的 channel-telegram 配置，目标是让 ClawdBot 成为 Telegram 群聊里的 AI 助手。但根据国内网络环境实测，这条路目前存在两个现实瓶颈：
- Telegram API 访问不稳定：即使配置了代理，
botToken验证阶段也常因 DNS 污染或连接超时失败 - 群聊自动识别准确率波动大：尤其在中文混合英文、带 emoji 的消息中，源语言检测容易误判，导致翻译结果南辕北辙
因此，我们建议：
优先走 Web 控制台路线：把 ClawdBot 当作你的
