ClawdBot基础教程：devices list/approve命令详解与排错指南

你刚部署好ClawdBot，打开浏览器却看到一片空白——页面加载失败、提示连接拒绝、或者干脆打不开控制台。别急，这不是模型没跑起来，也不是vLLM后端挂了，大概率只是你的设备还没被“认领”。ClawdBot采用严格的设备授权机制，默认禁止未验证终端访问管理界面。本文不讲原理、不堆参数，只聚焦一个最常卡住新手的环节：如何用好 clawdbot devices list 和 clawdbot devices approve 这两个命令，快速打通访问链路。

全文基于真实部署场景编写，所有操作均在本地环境实测通过（Ubuntu 22.04 + Docker 24.0.7），不依赖网络代理、不修改源码、不碰证书配置。你会看到：命令执行时的真实输出、常见报错的直白解读、每一步背后的实际作用，以及当一切都不起效时，那条真正管用的备用路径。

---

1. 先搞清楚：为什么需要 devices list 和 approve？

ClawdBot不是传统Web服务，它把“谁可以访问我”这件事交给了自己管理。当你第一次在浏览器里输入 http://localhost:7860，ClawdBot不会直接放行，而是悄悄记下这个请求，把它放进一个叫“待审批设备队列”的地方。这个队列里的每一项，都代表一次来自新设备、新浏览器、甚至新标签页的访问尝试。

你可以把它想象成小区门禁系统：

• 你站在门口按门铃 → 相当于你在浏览器里打开页面；
• 保安室收到呼叫但不认识你 → 相当于 clawdbot devices list 能看到一条 pending 状态的记录；
• 保安打电话给业主确认 → 相当于你手动运行 clawdbot devices approve 告诉系统“这个人可信”；
• 门禁才咔哒一声打开 → 你才能真正看到控制台界面。

所以，list 是查看“谁在敲门”，approve 是替系统做决定“放谁进来”。它们不涉及模型加载、不修改配置文件、也不重启服务——纯粹是访问权限的开关操作。

---

2. 执行 clawdbot devices list：看清当前有哪些“敲门者”

2.1 命令怎么写？在哪执行？

确保你已进入ClawdBot容器内部（或宿主机上已配置好CLI环境）：

docker exec -it clawdbot bash
# 或如果你是用 docker-compose 启动的：
docker-compose exec clawdbot bash

然后直接运行：

clawdbot devices list

注意：不要加 sudo，也不要试图在宿主机目录下直接运行该命令——它必须在容器内或已正确初始化的CLI环境中执行。

2.2 输出内容怎么看？关键字段解析

正常输出类似这样（已精简无关行）：

🦞 Clawdbot 2026.1.24-3 (885167d) — Your device is queued for approval.

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

重点关注三列：

• ID：一长串字母数字组合，这是设备的唯一身份标识，后面 approve 时要用到；
• Status：当前状态。pending 表示等待批准，approved 表示已放行，rejected 表示被拒；
• IP Address：发起请求的IP。如果是 172.18.0.1 或 127.0.0.1，说明是你本机浏览器发来的；如果是其他地址，可能是同事或远程设备尝试访问。

如果输出为空，或提示 No devices found，说明：
你还没在浏览器里打开过ClawdBot页面；
或者你之前已经批准过当前设备，系统不再重复记录；
又或者ClawdBot网关服务根本没启动（此时应先检查 clawdbot gateway status）。

2.3 常见异常输出及含义

输出片段	含义	应对建议
Error: gateway not reachable	后端服务未运行或端口冲突	运行 clawdbot gateway status 查看状态，确认 http://localhost:8000/v1 是否可通
Permission denied	当前用户无权读取设备数据库	切换到容器内root用户，或检查 /app/.clawdbot/devices.db 文件权限
command not found	CLI未正确安装或PATH未配置	检查是否在容器内执行，或重新安装ClawdBot CLI工具

---

3. 执行 clawdbot devices approve：让设备真正“进门”

3.1 命令格式与实操步骤

从上一步 list 输出中复制完整的 ID（注意不要漏掉任何字符），然后执行：

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

成功时会返回：

🦞 Clawdbot 2026.1.24-3 (885167d) — Device approved. You may now access the dashboard.

Approved device: a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8
Status changed to: approved

此时，立刻刷新你的浏览器页面（不是新开标签页，是原标签页刷新），你应该能看到ClawdBot控制台的登录界面或主面板。

3.2 一次批准多个设备？可以，但没必要

approve 支持批量操作，语法为：

clawdbot devices approve id1 id2 id3

不过实际使用中极少需要。因为：

• 每个浏览器指纹不同，Chrome 和 Firefox 会被视为两个设备；
• 同一浏览器的不同隐身窗口也各自独立；
• 但只要一个设备被批准，后续同IP、同User-Agent的请求通常会自动继承权限（取决于配置中的 deviceTrustPolicy）。

所以，首次部署只需批准当前正在用的那个ID即可。其他设备按需再批。

3.3 批准后还是打不开？别跳过这三步检查

即使 approve 显示成功，页面仍白屏，按顺序排查：

1. 确认是否刷新了正确页面
   不要新开一个 http://localhost:7860 标签页，而要回到你最初点击“打不开”的那个标签页，按 Ctrl+R（Windows/Linux）或 Cmd+R（Mac）强制刷新。

2. 检查浏览器控制台（F12 → Console）是否有报错
   常见如 Failed to fetch、net::ERR_CONNECTION_REFUSED，说明前端连不上后端网关。此时运行：

   curl -s http://localhost:8000/v1/models | jq .model
   

   若返回模型名（如 "Qwen3-4B-Instruct-2507"），说明vLLM正常；若报错，则需先修复模型服务。

3. 确认没有启用“隐私模式”或广告拦截插件
   部分插件会屏蔽WebSocket连接（ClawdBot UI依赖WS通信），临时禁用所有扩展再试。

---

4. 终极备选方案：clawdbot dashboard 命令直出可用链接

如果以上步骤都做了，页面依然拒绝服务，别折腾配置文件或重装镜像——直接用ClawdBot内置的诊断命令：

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/ —— 本地直连地址（适用于Docker Desktop或WSL2）
• http://localhost:7860/?token=... —— 带认证令牌的地址（绕过设备审批，临时有效）

直接复制第二行完整URL，粘贴进浏览器地址栏回车。这个链接自带一次性访问凭证，无需设备审批，100%能打开界面。它不是“后门”，而是ClawdBot官方提供的调试通道。

小技巧：把这个带token的链接收藏为书签，以后每次重启容器后，点一下就能进，比反复 list/approve 快得多。

---

5. 配置文件位置与安全提醒：别误改关键路径

所有设备审批记录、模型配置、渠道设置，都存放在一个统一位置：

/app/clawdbot.json   ← 容器内路径（也是文档中提到的映射路径）
~/.clawdbot/clawdbot.json   ← 宿主机对应路径（Docker volume挂载点）

你可能会看到网上教程说“去改 /app/clawdbot.json 里的 devices 字段”，请务必停止这种操作。ClawdBot的设备列表是二进制数据库（SQLite），不是JSON字段。手动编辑JSON文件中的 devices 会破坏结构，导致后续 list/approve 命令失效。

正确的做法永远是：

• 查设备 → clawdbot devices list
• 批设备 → clawdbot devices approve <id>
• 清设备（如需重置）→ clawdbot devices reset（慎用，会清空全部记录）

另外提醒一句：clawdbot.json 中若出现 botToken、apiKey 等敏感字段，请确保该文件不在Git仓库中公开，也不要在日志里打印完整内容——ClawdBot CLI本身已做基础脱敏（如显示 sk-****），但你自己写脚本调用时需注意。

---

6. 总结：三句话记住核心逻辑

clawdbot devices list 和 approve 不是玄学命令，它们解决的是一个非常具体的问题：让浏览器和后端建立可信连接。掌握这三点，你就不会再被卡在登录页之外：

• list 是“查岗”——它告诉你谁在门外等着，而不是帮你修网关；
• approve 是“开门”——它只改变设备状态，不重启服务、不重载模型；
• dashboard 是“应急钥匙”——当常规流程走不通时，带token的链接就是最短路径。

最后强调：ClawdBot的设计哲学是“开箱即用，但默认保守”。它的设备审批机制不是为了增加复杂度，而是为了防止本地部署的服务被意外暴露在公网。你每一次 approve，都是在明确告诉系统：“我信任这个访问来源。” 这种可控的信任，恰恰是个人AI助手最基础也最重要的安全边界。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。