了解 ClawdBot：本地 AI 助手的开箱即用方案
ClawdBot 是一个运行在你个人设备上的轻量级 AI 助手框架，它不是云端服务，也不依赖厂商 API 密钥。它的核心优势在于把大模型能力真正交到你手上：你可以把它装在笔记本、旧台式机，甚至树莓派上，全程离线运行，数据不出设备。
后端由 vLLM 驱动，这意味着你能享受到接近生产级的推理吞吐和低延迟响应。但和那些需要调参、配环境、改代码的'硬核'方案不同，ClawdBot 的设计哲学是「先跑起来，再调细节」——它默认就带好模型、接口和界面，你只需要执行一条命令，就能看到一个可交互的 AI 控制台。
它不追求'最全功能'，而是专注解决三个核心问题：
- 怎么安全地连上它？（Web 控制台不是直接暴露的，有设备信任机制）
- 怎么让它听懂你想用什么模型？（不只是换名字，而是真正切换底层推理引擎）
- 怎么在浏览器里直观地操作和验证？（不是只靠命令行，而是有可视化反馈）
这三点，正是本文要带你一步步打通的关键路径。
设备授权：确保控制台安全访问
ClawdBot 的 Web 控制台默认不对外网开放，也不允许任意设备访问。这是出于隐私和安全考虑：你的本地 AI 助手，理应只对你本人开放。所以首次访问时，你会遇到'页面打不开'或'连接被拒绝'的提示——这不是故障，而是系统在等你完成身份确认。
整个过程分三步，全部通过终端命令完成，无需修改配置文件或重启服务。
查看待处理的设备请求
打开终端，输入以下命令：
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 条目，请刷新一次网页再执行命令。
批准该设备访问权限
复制上面输出中 pending 行的 ID（比如 abc123），然后执行：
clawdbot devices approve abc123
如果成功，终端会返回类似提示：
Device abc123 approved. You may now access the dashboard.
此时，你刚才打开的浏览器标签页刷新一下，Web 控制台就会正常加载——左侧导航栏、顶部状态栏、中间工作区全部就位。
如果仍无法访问？用 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 在易用性和防护之间做的一个很实在的平衡。
模型管理：三种方式灵活切换推理引擎
ClawdBot 默认内置了一个轻量但够用的模型（如 vllm/Qwen3-4B-Instruct-2507），适合快速体验。但如果你已有自己的 vLLM 服务，或者想试试其他开源模型，它支持灵活替换。我们提供三种互不冲突的方式，你可以按熟悉程度选择。
方式一：修改 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就会生效
方式二：通过 Web UI 界面操作
进入已授权的 Dashboard 后，点击左侧菜单栏的 Config → Models → Providers，你会看到一个清晰的表格界面：
- 左侧是 provider 类型（如
vllm） - 中间是 base URL 和认证设置
- 右侧是已注册模型列表，带'+ Add Model'按钮
点击添加，填入模型 ID 和显示名称，保存即可。整个过程就像管理邮箱账户一样直观，连 JSON 格式都不用碰。
方式三：命令行快速验证模型是否就绪
无论你用哪种方式修改，最终都要确认模型真的'活'了。执行：
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 错误，或模型名拼写有误——这时回到前两步检查即可。
Dashboard 实战：不只是聊天框，更是调试中枢
ClawdBot 的 Web 控制台（Dashboard）不是简单的'模型选择器 + 聊天框'。它是一个面向开发者和高级用户的调试与观察平台。界面虽简洁，但每个区域都有明确职责。
顶部状态栏：实时掌握系统健康度
- Gateway Status：显示后端服务连接状态（绿色 表示正常，红色 ❌ 表示 vLLM 未启动或网络不通）
- Active Models：列出当前已加载并可调用的模型数量
- Uptime：服务已连续运行时间，帮助你判断是否需要重启
这个区域是你排查问题的第一站。比如发现聊天无响应，先看 Gateway 是否绿色；发现模型列表为空，先看 Active Models 是否为 0。
左侧导航栏：功能模块化，各司其职
- Chat：主对话界面，支持多轮上下文、历史记录导出
- Config：集中管理所有配置项，包括模型、渠道、工作区路径等
- Logs：实时滚动日志，比终端
docker logs更聚焦（自动过滤无关信息，高亮错误） - Metrics：简单性能看板，显示当前并发请求数、平均响应延迟、GPU 显存占用（如有）
特别提醒：不要跳过 Logs 页面。很多'奇怪行为'（比如某条消息卡住、翻译结果乱码）在 Logs 里都能看到具体报错，比如 OCR timeout 或 Whisper model not found，比凭空猜测高效得多。
主工作区：所见即所得的交互验证场
在 Chat 页面，你可以做三件关键事：
- 测试模型切换效果：在右上角下拉菜单中切换不同模型，对比同一提示词下的输出风格差异
- 验证多模态能力：上传一张含文字的图片，看是否能自动 OCR + 翻译（这背后调用了 PaddleOCR）
- 模拟真实场景：输入类似
请用英文写一封辞职信，语气专业但友好的复杂指令，观察模型是否理解'语气''专业''友好'等抽象要求
这不是为了炫技，而是帮你建立对模型能力边界的直观认知——哪些任务它擅长，哪些需要加提示词引导，哪些干脆不适合交给它。
扩展建议：Telegram 集成的现实考量
文档中提到的 channel-telegram 配置，目标是让 ClawdBot 成为 Telegram 群聊里的 AI 助手。但根据国内网络环境实测，这条路目前存在两个现实瓶颈：
- Telegram API 访问不稳定：即使配置了代理，
botToken验证阶段也常因 DNS 污染或连接超时失败 - 群聊自动识别准确率波动大：尤其在中文混合英文、带 emoji 的消息中，源语言检测容易误判，导致翻译结果南辕北辙
因此，我们建议：
- 优先走 Web 控制台路线：把 ClawdBot 当作你的'AI 工作站'，在浏览器里完成所有调试、测试和内容生成
- 用 Telegram 仅作通知通道：比如配置一个 webhook，当模型完成批量处理任务时，自动发一条摘要到你的 Telegram 私聊
- 暂不强求群聊全自动接入：除非你有稳定海外服务器 + 可控代理链路，否则投入产出比不高
一句话总结：ClawdBot 的核心价值在于「本地可控的 AI 能力」，而不是「又一个 Telegram 机器人」。把精力放在用好它的模型、日志和指标上，远比纠结频道配置更有收获。
核心认知：构建本地 AI 工作流的三个关键点
回顾整个流程，你会发现 ClawdBot 的设计思路非常清晰：它不试图让你成为 DevOps 工程师，而是帮你绕过所有基础设施陷阱，直奔 AI 能力本身。这背后有三个值得记住的认知：
- 设备授权不是障碍，而是信任起点：每一次
approve，都是你在告诉系统：'这是我信任的设备'。这种显式授权机制，比'默认开放 + 密码保护'更符合本地化 AI 的安全逻辑。 - 模型切换不是技术动作，而是能力实验：换一个模型 ID，不只是改个名字，而是切换整套推理引擎、上下文长度、支持的语言和风格偏好。把它当作一个低成本的
