第一次运行 ClawdBot，最容易卡住新手的不是安装，也不是模型加载，而是那个看似简单的“设备授权”。很多人启动容器后直接访问页面，看到白屏或“Device not approved”提示，就以为部署失败了。其实这正是 ClawdBot 的安全机制在起作用：它默认把每一台访问设备视为“陌生访客”，必须手动批准后才能进入完整界面。
这个授权流程的核心是“Pending 请求”——只有当浏览器真正访问过一次前端页面，后端才会生成一条待批准的设备记录。没有这条记录，任何 approve 操作都会失败。本文从零开始，手把手带你走通第一次运行 ClawdBot 的完整路径，重点解决设备授权与 Pending 请求的每一个细节，让你 5 分钟内看到真正的控制台界面。
文章导航
1. ClawdBot 是什么？为什么需要设备授权
ClawdBot 是一个完全本地化的 AI 助手平台，所有推理、对话、文件处理都在你自己的设备上完成，不依赖任何云端 API。它内置 vLLM 后端，支持 Qwen3、Llama3 等主流开源模型，在普通笔记本、NAS 甚至树莓派上都能流畅运行。
设备授权是 ClawdBot 的核心安全设计之一。默认情况下，它启用设备白名单机制：只有被明确批准的设备才能访问完整功能。这既防止了局域网内其他人随意访问你的 AI 实例，也确保了你对隐私的绝对控制权。
授权流程基于“Pending → Approve”的两步交互：
– 浏览器访问前端 → 触发一条 Pending 设备请求
– 使用 CLI 批准该请求 → 设备加入白名单
整个过程简单，但顺序不能错。接下来我们一步步操作。
2. 部署前准备：三件事缺一不可
在启动之前，先确认以下基础环境：
| 项目 | 推荐配置 | 说明 |
|---|---|---|
| 系统 | Ubuntu 22.04/24.04、Debian 12+ | macOS 和 Windows WSL2 也可，但稳定性稍低 |
| Docker | 24.0+ | 必须，ClawdBot 依赖容器化部署 |
| Docker Compose | v2.20+ | 用于一键启动服务栈 |
| 内存 | 至少 8GB | Qwen3-4B 模型加载约需 6GB |
| Python | 3.10 或 3.11 | 系统自带或 pyenv 安装 |
拉取镜像与创建目录
# 创建工作目录
mkdir -p ~/clawdbot && cd ~/clawdbot
# 拉取官方最新镜像
docker pull clawdbot/clawdbot:latest
首次启动时，ClawdBot 会在你的家目录自动生成配置文件：~/.clawdbot/clawdbot.json。所有后续修改都应在此文件进行，切勿进入容器内部修改。
3. 一键启动服务：docker-compose.yml 写法
在 ~/clawdbot 目录下创建 docker-compose.yml：
version: '3.8'
services:
clawdbot:
image: clawdbot/clawdbot:latest
ports:
- "7860:7860" # Web UI
- "18780:18780" # WebSocket 网关
volumes:
- ~/.clawdbot:/app/.clawdbot
- ./workspace:/app/workspace
restart: unless-stopped
启动命令：
docker compose up -d
docker compose logs -f clawdbot
看到类似日志即表示服务正常：
INFO: Uvicorn running on http://0.0.0.0:7860
INFO: Application startup complete.
此时不要急着打开浏览器，先理解下一步的关键动作。
4. 触发 Pending 请求：授权流程的第一步（最容易忽略）
很多人直接跳到 approve 命令，结果发现 clawdbot devices list 返回空，这就是因为缺少 Pending 请求。
正确顺序是：
- 确保容器正在运行（
docker ps | grep clawdbot） - 用浏览器访问 http://localhost:7860
（即使页面显示空白或“Device not approved”，也要完整加载一次）
这一步非常关键：浏览器访问会向后端发送设备指纹信息，后端生成一条状态为 pending 的记录。只有这条记录存在，approve 才有目标。
5. 查看 Pending 请求并完成授权
步骤 1：列出待批准设备
在宿主机终端（不是容器内）执行：
clawdbot devices list
正常情况下你会看到类似输出：
ID Status Created At IP User Agent
a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8 pending 2026-02-01 10:22:31 127.0.0.1 Mozilla/5.0 (X11; Linux x86_64)...
如果返回空，请回到第 4 步，确保已经用浏览器完整访问过一次页面。
步骤 2：批准设备
复制上一步输出的完整 ID，执行：
clawdbot devices approve a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8
成功后会提示：
Device approved successfully.
步骤 3：刷新页面
返回浏览器，强制刷新（Ctrl+Shift+R 或 Cmd+Shift+R），你应该看到完整的 ClawdBot 控制台：左侧菜单、顶部状态栏、中间聊天窗口全部就位。
6. 常见问题速查表（95% 的授权失败都在这里）
| 现象 | 最可能原因 | 解决方法 |
|---|---|---|
devices list 返回空 |
未触发 Pending 请求 | 重新用浏览器访问 http://localhost:7860，等待页面加载完成后再 list |
| approve 报 “device not found” | ID 复制错误或在容器内执行 CLI | 确认在宿主机终端操作，ID 完整复制（包含所有连字符） |
| 页面仍白屏，刷新无效 | 浏览器缓存 | 强制刷新（Ctrl+Shift+R）或执行 clawdbot dashboard 获取带 token 链接 |
| CLI 命令找不到 clawdbot | 配置路径未识别 | 使用 CLAWDBOT_CONFIG_PATH=~/.clawdbot/clawdbot.json clawdbot devices list |
| 树莓派上 list 无输出 | 浏览器访问未触发（SSH 无图形界面） | 执行 clawdbot dashboard 生成带 token 链接，用本地浏览器打开 |
7. 进阶技巧：让授权更顺畅
使用 dashboard 命令一键打开
授权成功后，执行：
clawdbot dashboard
它会输出一个带 token 的完整 URL，直接复制到浏览器打开，绕过缓存问题。
多设备授权
局域网内其他设备访问时，会生成新的 pending 记录，按同样流程 approve 即可。已批准设备永久有效，除非手动 revoke。
关闭设备授权（不推荐）
如果你在完全可信的单机环境，可编辑 ~/.clawdbot/clawdbot.json，添加：
{
"security": {
"deviceApproval": false
}
}
重启容器后所有设备无需批准即可访问，但会降低安全性。
8. 授权完成后下一步：连接本地模型
授权只是入口，真正让 ClawdBot 活起来还需要配置模型。最常用的是内置 vLLM + Qwen3-4B。
编辑 ~/.clawdbot/clawdbot.json，在 models 节点添加：
{
"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"
}
]
}
}
}
}
保存后执行：
clawdbot models reload
刷新页面，你将在模型选择器中看到新添加的本地模型。
9. 从第一次运行到完全掌控
第一次运行 ClawdBot 的核心只有一句话：先访问页面触发 Pending 请求，再 approve。掌握了这个顺序，你就跨过了最常见的门槛。
从设备授权这一小步开始，你已经拥有了一个完全属于自己的本地 AI 助手：数据不出设备、配置全在掌控、模型随意切换。后续你可以继续探索 Telegram 接入、多模态能力、Agent 工作流等高级功能，但一切都建立在这一次成功的“设备批准”之上。
现在，打开终端，跟着上面的步骤操作吧——5 分钟后，你将看到属于自己的 ClawdBot 控制台真正亮起。
延展阅读：
