ClawdBot 本地部署与控制台授权实操

方式一：改 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' 就能新增

如果只是加一个新模型，这种方式最快，也不容易把 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 控制台更像一个调试面板，不是单纯拿来聊天的。界面不复杂，但该有的观察项基本都在。

顶部状态栏

这里主要看三项：

• Gateway Status：后端连接状态，绿色正常，红色说明 vLLM 没起来或者网络不通
• Active Models：当前加载了几个可用模型
• Uptime：服务已经连续跑了多久

排障时先看这里，通常比直接翻日志快。

左侧导航栏

几个模块分工比较清楚：

• Chat：主对话界面，多轮上下文和历史导出都在这里
• Config：模型、渠道、工作区路径这些配置集中放在这里
• Logs：实时日志，通常比 docker logs 更聚焦，错误信息也更好找
• Metrics：看并发请求、平均延迟、GPU 显存占用这类基础指标

我比较建议先看 Logs。很多看起来'模型坏了'的问题，最后都能在这里找到具体报错，比如 OCR timeout 或 Whisper model not found。

主工作区

在 Chat 页面里，最实用的是三件事：

• 切换模型，对比同一提示词下的输出差异
• 上传图片，验证 OCR 和翻译链路是否正常
• 输入复杂指令，看看模型能不能理解语气、风格这类抽象要求

它的价值不在于'能聊天'，而在于你能很快知道模型的边界在哪儿。哪些任务能直接用，哪些得加提示词，哪些根本不该交给它，试两轮就知道了。

Telegram 集成：能用，但别把它当主线

文档里提到的 channel-telegram，目标是把 ClawdBot 接到 Telegram 群聊里。思路没问题，但放到国内网络环境里，实际会碰到两个麻烦：

• Telegram API 访问不稳定，botToken 验证阶段经常卡在 DNS 或超时上
• 群聊里的语言识别波动比较大，中文、英文和 emoji 混在一起时，翻译结果容易跑偏

所以我更倾向于这样用：

• 优先把 Web 控制台当主入口，调试和验证都在这里做
• Telegram 只拿来做通知，比如批量任务完成后推一条摘要
• 群聊全自动接入先别着急做，除非你已经有稳定的海外网络链路

ClawdBot 的重点还是本地可控的 AI 能力，不是把 Telegram 机器人做得多花。

这套流程里最重要的三件事

跑完整个流程后，会发现 ClawdBot 的设计其实挺直接：它不想把你拉进一堆基础设施细节里，而是尽快让你碰到模型本身。真正需要记住的，还是这几件事：

• 设备授权不是麻烦，是本地访问的边界线。approve 这一步让谁能连上来变得明确。
• 模型切换不是改个名字那么简单，它会直接影响上下文长度、推理风格和语言表现。
• Dashboard 的价值在于观察，不在于装饰。日志和指标看对了，很多问题不用猜。

如果你是第一次做本地 AI 助手，ClawdBot 这种'先能用，再优化'的路线会比一上来折腾全套工程化配置舒服得多。