ClawdBot新手教程：首次运行时pendding设备处理与权限授予实操

本文介绍了如何在星图GPU平台上自动化部署ClawdBot镜像，快速构建本地AI助手工作台。通过平台一键拉取与启动，用户可高效完成设备权限授予与模型配置，典型应用于个人知识管理、本地化AI对话及插件化智能代理开发，兼顾隐私安全与深度定制能力。

雷鸣泽基

308人浏览 · 2026-01-30 00:41:57

雷鸣泽基 · 2026-01-30 00:41:57 发布

ClawdBot新手教程：首次运行时pending设备处理与权限授予实操

你刚下载完ClawdBot，双击启动，浏览器打开http://localhost:7860——结果页面一片空白，或者提示“连接被拒绝”。别急，这不是安装失败，也不是网络问题，而是ClawdBot在用它自己的方式说：“你好，我是你的AI助手，但得先确认你是谁。”

这正是本文要解决的核心问题：首次运行时出现的 pending 设备请求，以及如何正确完成权限授予，让前端控制台真正跑起来。整个过程不涉及编译、不依赖云服务、不需要改防火墙，只需要几条清晰命令和一次手动确认。

ClawdBot 是一个你可以在自己设备上运行的个人 AI 助手，本应用使用 vLLM 提供后端模型能力。它不是网页版聊天框，而是一个可本地部署、可深度定制、带完整控制台的AI工作台——你可以把它理解成“本地版的 Claude Desktop + 自研插件中心”。

而文中提到的 MoltBot，则是另一个独立项目：2025 年开源的「多语言、多平台、零配置」Telegram 翻译机器人。它和 ClawdBot 没有技术耦合，仅在部署理念上一脉相承——都强调离线可用、开箱即用、隐私可控。我们会在文末稍作区分，避免混淆。

下面进入正题：从第一次执行 clawdbot start 开始，到真正看到控制台界面，每一步都为你拆解清楚。

1. 首次启动后的典型现象：为什么打不开控制台？

当你首次运行 ClawdBot（例如通过 docker run 或 clawdbot start），系统会自动初始化服务、加载默认模型配置，并启动 WebUI 服务（Gradio）。但此时你直接访问 http://localhost:7860，大概率会遇到以下三种情况之一：

页面显示 “Connection refused” 或 “This site can’t be reached”
页面加载出 Gradio 的基础框架，但所有按钮灰显、输入框无响应
页面弹出授权提示，但没有明确操作入口

这些都不是 bug，而是 ClawdBot 的设备信任机制在起作用。

ClawdBot 将每一次前端访问（无论来自本机浏览器还是远程设备）视为一次“设备接入请求”。出于安全考虑，它不会自动信任任何新设备，而是将请求暂存为 pending 状态，等待管理员手动批准。这个设计借鉴了企业级终端管理逻辑——就像 macOS 首次连接 iPhone 时需要点击“信任”，或 Linux SSH 首次登录时提示“Are you sure you want to continue connecting?”。

所以，第一步不是查端口、不是重装、更不是翻代理，而是确认是否存在 pending 请求，并完成批准。

2. 查看 pending 设备请求：三步定位问题源头

2.1 进入运行环境

ClawdBot 通常以容器方式运行（Docker 或 Podman），你需要先进入其运行上下文。如果你是用 Docker 启动的，执行：

docker exec -it clawdbot bash

如果容器名不同（比如叫 clawdbot-dev），请替换为实际名称。不确定容器名？运行 docker ps 查看正在运行的容器列表。

注意：有些镜像默认不带 bash，可尝试 sh 替代：
docker exec -it clawdbot sh

2.2 执行设备列表命令

在容器内，直接运行：

clawdbot devices list

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

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

ID                                    Status    IP            User Agent                     Created
a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8  pending   172.17.0.1    Mozilla/5.0 (X11; Linux x86_64)  2026-01-24 10:22:15

关键信息就在这里：

Status 列显示 pending，说明该设备尚未被授权；
IP 是发起请求的客户端地址（本机浏览器通常是 172.17.0.1 或 127.0.0.1）；
ID 是唯一请求标识，后面批准时要用到。

如果没有输出，或提示 No devices found，说明请求尚未生成——这时请先在浏览器中刷新一次 http://localhost:7860，再回来执行 list 命令。

2.3 理解 pending 的本质

这个 pending 状态不是错误，而是一个安全守门员。它确保：

无人能绕过你直接访问你的本地 AI 助手；
即使服务暴露在局域网，陌生设备也无法擅自连入；
所有交互起点都经过你的一次主动确认。

它不像传统 Web 应用靠 Cookie 或 Session 认证，而是采用设备级白名单机制，更贴近操作系统原生权限模型。

3. 批准 pending 请求：一条命令解锁全部功能

3.1 执行 approve 命令

复制上一步中 ID 列的完整字符串（注意不要漏掉中间的 -），执行：

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

成功后你会看到：

🦞 Clawdbot 2026.1.24-3 (885167d) — Device approved. Your trust has been recorded in /app/.device-trust.db.

 Approved device: a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8
→ Now authorized for full UI access, model invocation, and config editing.

此时，立刻回到浏览器，刷新 http://localhost:7860。你会发现界面完全加载，左侧菜单可点，聊天框可输入，模型下拉框有内容——一切恢复正常。

小贴士：如果你有多台设备（比如手机、平板、另一台电脑）同时访问，每个设备都会生成独立的 pending 请求，需分别批准。

3.2 如果 approve 后仍无法访问？检查 dashboard token

极少数情况下，即使设备已批准，前端仍无法连接。这通常是因为 Gradio 默认启用了 token 验证，而浏览器未携带有效 token。

此时，请在容器内运行：

clawdbot dashboard

输出中会包含两行关键 URL：

Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
...
Then open:
http://localhost:7860/
http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762

请直接复制第二行带 ?token= 的完整链接，在浏览器中新开标签页粘贴访问。这是最可靠的方式，绕过了所有本地代理、缓存或跨域干扰。

补充说明：这个 token 是单次有效的会话凭证，每次 clawdbot dashboard 都会生成新 token。它不等同于 API Key，也不用于模型调用，仅用于 WebUI 登录校验。

4. 配置文件位置与结构：哪里在管这些权限？

ClawdBot 的设备信任记录、模型配置、通道设置，全部集中在一个 JSON 文件中：
/app/clawdbot.json（容器内路径）
对应宿主机上的位置通常是：
~/.clawdbot/clawdbot.json

这个文件就是你的“ClawdBot 中枢大脑”。它不是只读配置，而是运行时动态读写的主配置源。你看到的 devices list 和 approve 操作，底层就是在读写这个文件中的 devices 字段。

打开它，你会看到类似结构：

{
  "devices": {
    "trusted": [
      "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"
    ],
    "pending": []
  },
  "agents": { ... },
  "models": { ... }
}

trusted 数组存放已批准设备 ID；
pending 数组存放待批准请求（批准后自动移入 trusted）；
其他字段如 agents、models 控制 AI 行为，与设备权限无关。

重要提醒：不要手动编辑 pending 或 trusted 数组！必须通过 clawdbot devices approve 命令操作。直接修改 JSON 可能导致格式错误或签名失效，引发服务异常。

5. 模型配置验证：确认后端真正就绪

设备权限只是“进门钥匙”，真正让 ClawdBot 跑起来的，是后端模型服务。很多新手误以为界面打开了就万事大吉，结果一发消息就卡住——其实是模型没加载成功。

5.1 快速验证模型是否就绪

在容器内执行：

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

关键看三列：

Model：显示模型 ID，说明已识别；
Local Auth：yes 表示本地 vLLM 服务已连接；
Ctx：上下文长度（195k），说明模型加载完整。

如果这里为空、报错或显示 no，说明 vLLM 后端未启动或配置错误。请检查：

vLLM 服务是否在 http://localhost:8000/v1 可达（容器内执行 curl -s http://localhost:8000/v1/models | jq .）；
clawdbot.json 中 models.providers.vllm.baseUrl 是否指向正确地址；
模型权重是否已下载到 vLLM 指定目录。

5.2 修改模型配置的两种方式

你有两种方式切换模型，推荐按优先级选择：

方式一：修改配置文件（稳定、可复现）

编辑 /app/clawdbot.json，找到 models.providers.vllm.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"
        },
        {
          "id": "deepseek-v3-7B",
          "name": "DeepSeek-V3-7B"
        }
      ]
    }
  }
}

保存后重启 ClawdBot（clawdbot restart 或 docker restart clawdbot），再执行 clawdbot models list 即可看到新增模型。

方式二：UI 界面操作（快捷、适合调试）

打开已授权的控制台 → 左侧菜单点 Config → Models → Providers → 在 vLLM Provider 下点击 “+ Add Model”，填入 ID 和名称即可。这种方式无需重启，但修改不持久（容器重建后丢失），适合临时测试。

6. 常见误区与避坑指南

6.1 “我改了配置，为什么没生效？”

ClawdBot 的配置是运行时热加载，但有两个例外：

设备信任状态（devices）只在启动时读取一次，approve 后需刷新页面；
模型 provider 配置（models.providers）修改后，需执行 clawdbot models reload 或重启服务。

❌ 错误做法：改完 clawdbot.json 就直接刷新页面，期待模型立刻出现。
正确做法：改完 → clawdbot models reload → clawdbot models list 验证 → 刷新 UI。

6.2 “为什么 Telegram 频道配置一直失败？”

文中提到的 channel-telegram 配置，属于 ClawdBot 的扩展通道模块，与设备权限完全无关。它失败的常见原因有：

国内网络无法直连 Telegram API（需代理，且代理需配置在 clawdbot.json 的 proxy 字段）；
botToken 格式错误（必须是 1234567890:ABCdefGHIjklMNOpqrSTUvwxyz123456789 格式）；
channels.telegram.enabled 设为 true 后，未重启服务。

但请注意：Telegram 配置失败，不影响 WebUI 使用。WebUI 是独立服务，只要设备批准+模型就绪，就能正常使用全部 AI 能力。

6.3 “ClawdBot 和 MoltBot 到底什么关系？”

一句话厘清：

ClawdBot 是一个通用 AI 助手运行时平台，核心能力是“本地大模型调度 + 多模态交互 + 可视化控制台”，它本身不内置翻译、天气等功能，但可通过插件或自定义 agent 实现；
MoltBot 是一个垂直场景机器人，专为 Telegram 设计，开箱即用支持翻译、OCR、语音转写、汇率查询，所有能力打包进一个轻量 Docker 镜像，目标是“5 分钟上线”。

二者定位不同：ClawdBot 是“操作系统”，MoltBot 是“预装应用”。你可以把 MoltBot 的 OCR 模块单独抽出来，作为 ClawdBot 的一个子 agent 使用，但它们不是同一项目，代码库、维护团队、更新节奏均无关联。