ClawdBot新手教程：Dashboard访问失败？pending device处理全解

本文介绍了如何在星图GPU平台上自动化部署ClawdBot镜像，快速启用本地化AI助手服务。该镜像基于vLLM引擎，支持Qwen3-4B-Instruct等轻量中文大模型，典型应用场景包括本地文案撰写、笔记整理与编程辅助，全程数据不出设备，保障隐私安全。

丹力

372人浏览 · 2026-02-04 00:11:30

丹力 · 2026-02-04 00:11:30 发布

ClawdBot新手教程：Dashboard访问失败？pending device处理全解

1. ClawdBot是什么：你的本地AI助手，开箱即用

ClawdBot 是一个真正属于你自己的个人 AI 助手——它不依赖云端服务，也不把你的对话发往远程服务器。你把它装在自己的电脑、树莓派甚至老旧笔记本上，它就安静地运行在本地，听你指挥，为你服务。

它的核心能力来自 vLLM（一个高性能大模型推理引擎），这意味着它能以极低的显存占用、极快的响应速度，跑起像 Qwen3-4B-Instruct 这样实用又轻量的中文大模型。不是“能跑”，而是“跑得稳、回得快、记得住上下文”。

它不像某些需要注册账号、绑定邮箱、等审核才能用的 AI 工具；ClawdBot 的设计哲学是：你装好，它就在；你关掉，它就停；你删掉，不留痕。没有后台进程偷偷上传数据，没有隐藏的 API 调用，所有推理、记忆、文件处理，都发生在你设备的内存和硬盘里。

简单说：它是你桌面上那个沉默但可靠的“AI同事”，不需要你懂 Docker、不用配环境变量、更不用研究 CUDA 版本——只要你会复制粘贴几行命令，5 分钟内，它就能在你浏览器里打开，开始帮你写文案、查资料、整理笔记、甚至辅助编程。

而今天这篇教程，要解决的是绝大多数新手第一次启动 ClawdBot 时最常卡住的问题：Dashboard 打不开，页面一直白屏或报错，控制台提示“连接被拒绝”或“无法访问”。别急，这不是你装错了，也不是模型坏了——它只是在等你轻轻点一下“同意”。

2. 为什么 Dashboard 打不开？根源在于“设备授权”

当你首次运行 ClawdBot 并尝试访问 http://localhost:7860 时，浏览器大概率会显示空白页、加载转圈，或者直接报错 ERR_CONNECTION_REFUSED。这时候很多人会立刻怀疑：是不是端口没开？是不是模型没加载？是不是 JSON 配置写错了？

其实都不是。真正的原因藏在一个你几乎不会注意到的地方：ClawdBot 把每一次浏览器访问，都当作一次“新设备接入请求”来对待。

这背后是它的安全设计逻辑：

Dashboard 不是一个开放网页，而是一个受控的 Web 控制台；
每次有新浏览器（哪怕是你自己换了个 Chrome 标签页）尝试连接，ClawdBot 都会生成一条 pending device（待处理设备）记录；
它默认不会自动信任任何设备，必须由你手动批准，才允许该设备建立 WebSocket 连接、加载 UI、调用模型。

所以，你看到的“打不开”，本质是：请求已发出，服务已运行，但连接被主动拦截，等待你的“放行令”。

这个机制听起来有点麻烦，但它保护了你——比如你把 ClawdBot 部署在公司内网或 NAS 上，别人扫到 IP 尝试访问，也会卡在这一步，看不到任何界面，更拿不到你的本地模型和工作区数据。

3. 三步搞定 pending device：从终端到可用 Dashboard

解决这个问题，不需要改代码、不用重装、更不用重启整个服务。只需要三行清晰、可复制、零歧义的终端命令。我们一步步来：

3.1 第一步：确认 pending 请求是否存在

打开你的终端（Windows 用 PowerShell 或 WSL，Mac/Linux 用 Terminal），确保你当前处于 ClawdBot 运行环境（比如已进入容器，或在项目根目录下）。执行：

clawdbot devices list

你会看到类似这样的输出：

🦞 Clawdbot 2026.1.24-3 (885167d) — Your device is pending; your patience is appreciated.

ID                                    Status     Last Seen          IP Address      User Agent
a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8  pending    2026-01-24 14:22:18  127.0.0.1       Mozilla/5.0 (X11; Linux x86_64)...

只要看到 Status 列里有 pending，就说明问题定位准确了——这就是拦住你 Dashboard 的“守门人”。

小贴士：如果你执行后提示 command not found，说明你还没正确激活 ClawdBot 的 CLI 环境。请先确认是否已通过 docker exec -it clawdbot bash 进入容器，或检查是否已将 clawdbot 命令加入系统 PATH。

3.2 第二步：批准你的设备（关键操作）

从上一步输出中，复制那串长长的 ID（就是那一长串带横杠的字母数字组合，例如 a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8），然后执行：

clawdbot devices approve a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8

注意：请把上面示例中的 ID 替换成你实际看到的 ID。不要漏掉任何字符，包括开头的 a 和结尾的 8。

成功后，你会看到：

 Device approved. You may now access the Dashboard.

此时，回到你的浏览器，不用刷新，直接按 F5 强制刷新页面。几秒后，熟悉的 ClawdBot 控制台界面就会完整加载出来——左侧菜单栏、顶部状态栏、中间聊天窗口，全部就位。

3.3 第三步：如果仍打不开？获取带 Token 的直连链接

极少数情况下（比如你在远程服务器上部署，本地浏览器无法直连 localhost），即使批准了设备，Dashboard 依然无法访问。这时，ClawdBot 提供了一个“兜底方案”：生成一个带一次性 Token 的专属链接。

在终端中执行：

clawdbot dashboard

你会看到类似这样的输出：

🦞 Clawdbot 2026.1.24-3 (885167d) — Your .env is showing; don't worry, I'll pretend I didn't see it.

Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
Copy to clipboard unavailable.
No GUI detected. Open from your computer:
ssh -N -L 7860:127.0.0.1:7860 root@100.64.232.100
Then open:
http://localhost:7860/
http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
Docs:
https://docs.clawd.bot/gateway/remote
https://docs.clawd.bot/web/control-ui

重点看这一行：

http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762

把这个完整链接，粘贴到你本地电脑的浏览器地址栏中，然后回车。它会绕过设备授权环节，直接带你进入 Dashboard。

注意：这个 token 是临时的、一次性的，且只对当前会话有效。它不是密码，也不需要保存，用完即可丢弃。这是 ClawdBot 在安全与便利之间做的务实平衡。

4. 模型配置指南：让 ClawdBot “说人话”更准、更快

Dashboard 能打开了，下一步自然想让它干点实事。ClawdBot 默认自带 Qwen3-4B-Instruct 模型，但如果你想换其他模型（比如更小的 Phi-3、更强的 Qwen2.5-7B），或者想把后端换成你本地已有的 vLLM 服务，配置起来也很直观。

4.1 推荐方式：修改 `/app/clawdbot.json` 配置文件

ClawdBot 的核心配置统一放在 /app/clawdbot.json（容器内路径），它映射自你宿主机的 ~/.clawdbot/clawdbot.json。打开这个文件，找到 models 和 agents 两大部分。

下面是一个精简、可直接复用的配置模板，已适配本地 vLLM 服务（假设你已在 http://localhost:8000/v1 启动了 vLLM）：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "vllm/Qwen3-4B-Instruct-2507"
      },
      "workspace": "/app/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "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"
          }
        ]
      }
    }
  }
}

关键字段说明：

"baseUrl"：指向你本地 vLLM 的 OpenAI 兼容接口地址；
"apiKey"：vLLM 默认接受任意非空字符串，填 "sk-local" 即可；
"id"：必须与你在 vLLM 启动时指定的 --model 名称完全一致（如 Qwen3-4B-Instruct-2507）；
"primary"：告诉 ClawdBot 默认用哪个模型来响应聊天。

改完保存，无需重启服务。ClawdBot 会在几秒内热重载配置。

4.2 验证模型是否生效

回到终端，执行：

clawdbot models list

如果看到类似输出，说明配置成功：

🦞 Clawdbot 2026.1.24-3 (885167d) — Your task has been queued; your dignity has been deprecated.

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

其中 Local Auth: yes 表示模型确实在本地运行，Ctx: 195k 表示支持超长上下文，这才是真正“开箱即用”的本地大模型体验。

5. 常见误区与避坑提醒：少走弯路，专注体验

刚上手 ClawdBot，很容易踩进几个“看起来很合理，实则南辕北辙”的坑。这里总结三个最高频、最耽误时间的误区，帮你省下至少一小时调试时间：

5.1 误区一：“我改了 config.json，但 Dashboard 里没变化”

→ 真相：ClawdBot 的 UI 界面（Config → Models）只是配置的“只读视图”，它不支持在线编辑并保存。你在这里点来点去，改的只是前端展示，不会写入 /app/clawdbot.json。所有实质性配置，必须手动编辑 JSON 文件。

5.2 误区二：“我启用了 Telegram 频道，结果 Dashboard 直接崩了”

→ 真相：Telegram 频道配置（尤其是 botToken 和 proxy）在国内网络环境下极易触发连接超时，导致 Gateway 服务异常退出，进而连带 Dashboard 失联。官方文档也明确建议：“频道配置请最后尝试”。新手请务必先确保 Dashboard 和本地模型 100% 正常，再考虑对接外部平台。

5.3 误区三：“我用 `docker restart clawdbot` 重启，结果 pending device 又出现了”

→ 真相：restart 会清空内存中的设备授权状态。ClawdBot 的设备授权信息默认存在内存里（非持久化），每次重启都会重置。这不是 bug，是设计——它保证了每次重启都是“干净状态”。所以，重启后只需再执行一次 clawdbot devices approve [ID]，3 秒搞定。