ClawdBot Web Dashboard 访问失败原因与修复方案

说明它只监听 127.0.0.1，不响应外部请求。

2.2 修复方案一：启用远程访问（推荐用于开发/测试）

编辑配置文件 /app/clawdbot.json（或 ~/.clawdbot/clawdbot.json）：

{
  "web": {
    "host": "0.0.0.0",
    "port": 7860,
    "enableCors": true
  }
}

注意："host": "0.0.0.0" 表示监听所有网络接口；"enableCors": true 允许跨域请求（否则前端资源可能加载失败）。

保存后重启 ClawdBot 服务（如使用 Docker，则 docker restart clawdbot）。

2.3 修复方案二：SSH 端口转发（更安全，推荐生产环境）

无需改配置，直接在本地电脑终端执行：

ssh -N -L 7860:127.0.0.1:7860 user@your-server-ip 

然后在本地浏览器打开 http://localhost:7860 即可。这种方式不暴露服务到公网，所有流量经 SSH 加密隧道传输，安全性更高。

3. Token 链接未正确使用：带 token 的 URL 被忽略

ClawdBot 的 Dashboard 启用了 token 认证机制，每次启动都会生成一个一次性访问令牌（token）。即使服务已运行、地址也正确，缺少 token 的 URL 仍会被拒绝访问。

3.1 如何获取有效 Token 链接？

在终端中运行：

clawdbot dashboard 

你会看到类似输出：

Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762 

这个完整链接才是有效的。只访问 http://127.0.0.1:7860 是不行的。

3.2 常见误区与纠正

• ❌ 错误做法：复制 http://127.0.0.1:7860 后手动拼接 token
• 正确做法：完整复制整行 Dashboard URL: 后的链接，包括 ?token=... 部分
• 注意：token 有有效期（默认 24 小时），过期后需重新运行 clawdbot dashboard 获取新链接

3.3 进阶技巧：让 token 永久生效（可选）

若希望每次启动都用固定 token，可在配置中指定：

{
  "web": {
    "token": "my-super-secret-token-2026"
  }
}

这样生成的链接就是 http://127.0.0.1:7860/?token=my-super-secret-token-2026，便于书签收藏或自动化脚本调用。

4. vLLM 后端未就绪：Dashboard 已启动，但模型服务不可用

ClawdBot 的 Web 界面本身轻量，但它严重依赖后端 vLLM 服务提供模型推理能力。如果 vLLM 未启动、端口冲突、模型加载失败，Dashboard 虽然能打开，但会出现'加载中…''模型不可用''Connection refused'等提示，甚至白屏。

4.1 如何快速验证 vLLM 是否就绪？

ClawdBot 自带诊断命令：

clawdbot models list 

正常输出应类似：

Model Input Ctx Local Auth Tags vllm/Qwen3-4B-Instruct-2507 text 195k yes yes default 

如果报错如 Error: failed to connect to vLLM at http://localhost:8000/v1，说明 vLLM 服务未运行或地址配置错误。

4.2 检查 vLLM 配置是否匹配

打开 /app/clawdbot.json，确认 models.providers.vllm.baseUrl 与你实际运行的 vLLM 地址一致：

{
  "providers": {
    "vllm": {
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": "sk-local",
      "api": "openai-responses"
    }
  }
}

常见错误：

• vLLM 实际运行在 http://127.0.0.1:8000/v1，但配置写成了 http://localhost:8000/v1（在某些容器环境中二者不等价）
• vLLM 使用了非标准端口（如 8080），但配置仍是 8000
• vLLM 运行在另一台机器，但 baseUrl 写的是 localhost

修复方法：统一改为 http://host.docker.internal:8000/v1（Docker 容器内访问宿主机）或实际 IP 地址。

4.3 一键启动 vLLM（以 Qwen3-4B 为例）

如果你尚未启动 vLLM，可用以下命令快速拉起（确保已安装 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 次解决

Web Dashboard 打不开？别急着重装、别盲目查日志。按下面这个顺序快速排查，90% 的问题都能当场解决：

1. 检查设备授权 → 运行 clawdbot devices list，若有 pending 条目，立即 approve

2. 确认监听地址 → 运行 ss -tuln | grep :7860，若只绑定 127.0.0.1，则改配置 host: "0.0.0.0" 或用 SSH 转发

3. 使用完整 Token 链接 → 必须运行 clawdbot dashboard 复制整条 URL，不能省略 ?token=...

4. 验证 vLLM 后端连通性 → 运行 clawdbot models list，失败则检查 baseUrl 配置与 vLLM 实际运行状态

这四步不是理论推演，而是从上百次真实部署反馈中提炼出的最小可行路径。它们不依赖经验、不考验耐心，只要照着命令敲，就能看到 Dashboard 真正亮起来。

你不需要成为系统管理员，也不必读懂每一行 JSON。ClawdBot 的设计哲学是：强大，但不复杂；安全，但不繁琐；本地，但不封闭。

现在，关掉这篇指南，打开终端，输入第一条命令——你的个人 AI 助手，只差一次 approve。