ClawdBot Web Dashboard 访问失败原因与修复方案
ClawdBot 是一个可以在本地设备上运行的个人 AI 助手，使用 vLLM 提供后端模型能力。它无需注册账号或担心隐私泄露，支持对话、推理及工具调用，并通过 Web 界面管理功能。
部署后若遇到浏览器输入 http://localhost:7860 显示'无法访问''连接被拒绝'或 404，通常由以下四种原因导致：
1. 设备授权未完成：Pending 请求卡住入口
ClawdBot 的 Web 控制台采用设备配对机制（Device Pairing）。首次访问时，前端向后端发起认证请求进入 pending 状态，此时 Dashboard 页面加载失败，但后端已正常运行。
1.1 如何确认是这个问题？
在终端中执行：
clawdbot devices list
如果输出中包含状态为 pending 的记录，说明问题在此：
ID Status Created At Last Seen d1a2b3c4 pending 2026-01-24 14:22:03 -
注意：此命令需在 ClawdBot 进程运行时执行。
1.2 修复步骤：手动批准设备请求
复制输出中的 ID（如 d1a2b3c4），执行批准命令：
clawdbot devices approve d1a2b3c4
成功后刷新浏览器即可正常加载。
1.3 补充说明
这是隐私保护设计，默认不信任未经验证的客户端连接，避免本地服务被局域网内其他设备意外访问。
2. 本地监听地址未正确映射：服务只绑定了 127.0.0.1
ClawdBot 默认将 Web UI 绑定在 127.0.0.1:7860，仅接受本机回环访问。若在远程服务器部署并从外部访问，会因服务未监听该 IP 而失败。
2.1 如何确认是这个问题？
执行以下命令查看当前监听地址：
ss -tuln | grep :7860
如果输出只有 127.0.0.1:7860，说明不响应外部请求。
2.2 修复方案一：启用远程访问（推荐用于开发/测试）
编辑配置文件 /app/clawdbot.json（或 ~/.clawdbot/clawdbot.json）：
{
"web": {
"host": "0.0.0.0",
"port": 7860,
"enableCors": true
}
}
保存后重启 ClawdBot 服务。
2.3 修复方案二：SSH 端口转发（更安全，推荐生产环境）
直接在本地电脑终端执行：
ssh -N -L 7860:127.0.0.1:7860 user@your-server-ip
然后在本地浏览器打开 http://localhost:7860。
3. Token 链接未正确使用：带 token 的 URL 被忽略
ClawdBot 启用了 token 认证机制，缺少 token 的 URL 会被拒绝访问。
3.1 如何获取有效 Token 链接？
在终端中运行：
clawdbot dashboard
输出类似：
Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
必须完整复制整行链接，包括 ?token=... 部分。
3.2 进阶技巧：让 token 永久生效（可选）
若希望每次启动都用固定 token，可在配置中指定：
{
"web": {
"token": "my-super-secret-token-2026"
}
}
4. vLLM 后端未就绪：Dashboard 已启动，但模型服务不可用
Web 界面依赖后端 vLLM 服务提供模型推理能力。如果 vLLM 未启动、端口冲突或模型加载失败，会出现'加载中…'或白屏。
4.1 如何快速验证 vLLM 是否就绪？
ClawdBot 自带诊断命令：
clawdbot models list
正常输出应列出模型信息。若报错 Error: failed to connect to vLLM at http://localhost:8000/v1，说明服务未运行或地址配置错误。
4.2 检查 vLLM 配置是否匹配
打开 /app/clawdbot.json，确认 models.providers.vllm.baseUrl 与实际运行的 vLLM 地址一致：
"providers": {
"vllm": {
"baseUrl": "http://localhost:8000/v1",
"apiKey": "sk-local",
"api": "openai-responses"
}
}
常见错误包括 localhost 与 127.0.0.1 不等价、端口不一致等。修复方法：统一改为 http://host.docker.internal:8000/v1（Docker 容器内访问宿主机）或实际 IP 地址。
4.3 一键启动 vLLM（以 Qwen3-4B 为例）
确保已安装 vLLM，可用以下命令快速拉起：
python -m vllm.entrypoints.api_server --model Qwen/Qwen3-4B-Instruct --dtype bfloat16 --tensor-parallel-size 1 --port 8000 --host 0.0.0.0
启动成功后，再次运行 clawdbot models list 应能列出模型。
总结：4 步定位，1 次解决
按顺序排查可解决 90% 的问题：
- 检查设备授权：运行
clawdbot devices list，若有pending条目，立即approve。 - 确认监听地址：运行
ss -tuln | grep :7860，若只绑定127.0.0.1，则改配置host: "0.0.0.0"或用 SSH 转发。 - 使用完整 Token 链接：必须运行
clawdbot dashboard复制整条 URL，不能省略?token=...。 - 验证 vLLM 后端连通性：运行
clawdbot models list，失败则检查baseUrl配置与 vLLM 实际运行状态。
