ClawdBot入门指南：Web控制台Device授权流程与Pending请求处理

ClawdBot入门指南：Web控制台Device授权流程与Pending请求处理

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

ClawdBot 是一个你可以在自己设备上运行的个人 AI 助手。它不依赖云端API调用，所有推理都在本地完成——这意味着你的对话内容、上传的文件、工作空间里的文档，全程不出设备，隐私有保障。

它的后端由 vLLM 驱动，专为高效、低延迟的大模型服务而设计。vLLM 的 PagedAttention 技术让 ClawdBot 能在消费级显卡（如 RTX 4090 或甚至 3060）上流畅运行 Qwen3-4B、Phi-3、Llama-3-8B 等主流中型模型，支持高并发、长上下文（最高达195K tokens），响应快、吞吐稳。

和那些需要注册账号、绑定邮箱、等待审核的SaaS工具不同，ClawdBot 是“装好就能用”的本地应用。你不需要理解 tokenization、KV cache 或 quantization，只要一条命令启动，再点几下网页，就能拥有一个真正属于自己的、可定制、可审计、可离线使用的AI工作台。

它不是玩具，也不是 Demo。它是为真实使用场景打磨的工具：写周报、读PDF、总结会议录音、翻译技术文档、生成代码注释、辅助学习外语……所有操作都发生在你自己的机器里。

2. 为什么先要处理 Device 授权？Web 控制台的“门禁系统”

刚启动 ClawdBot 后，你可能会发现：打开浏览器访问 http://localhost:7860，页面一片空白，或者提示“Unauthorized”、“Forbidden”，甚至直接跳转到错误页。这不是安装失败，也不是网络问题——而是 ClawdBot 的安全机制在起作用。

ClawdBot 把 Web 控制台当作一个受保护的管理界面，就像路由器后台或NAS管理页一样，必须经过明确的设备授权才能进入。这个机制叫 Device Authorization Flow（设备授权流程），核心逻辑很简单：

• 每次你通过浏览器首次访问控制台，ClawdBot 会生成一个临时的、带签名的“入网申请”；
• 这个申请不会自动通过，它会进入一个待决队列（Pending Requests）；
• 你必须在终端里手动确认这个请求，相当于对设备说：“我允许这台电脑访问我的AI助手”。

这一步看似多此一举，实则至关重要：

• 防止局域网内其他设备未经许可访问你的AI工作台；
• 避免误点链接导致配置被篡改或数据被导出；
• 为后续多设备协同（比如手机扫码登录、平板远程管理）打下安全基础。

所以，“无法访问控制台”不是故障，而是系统在认真履行它的职责——它在等你点头。

3. 三步搞定 Device 授权：从 Pending 到可用

整个授权过程只需三步，全部在终端中完成，无需修改任何配置文件，也不需要重启服务。

3.1 查看当前待处理的设备请求

在 ClawdBot 运行的终端窗口（或新打开一个终端，确保在 ClawdBot 所在目录），执行：

clawdbot devices list 

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

🦞 Clawdbot 2026.1.24-3 (885167d) — Your device is knocking; I'm checking the peephole. ID Status Created At IP Address User Agent d7f2a1b4 pending 2026-01-25 14:22:08 127.0.0.1 Mozilla/5.0 (X11; Linux x86_64)... 

注意 Status 列显示为 pending，这就是那个“正在敲门”的设备请求。ID 是它的唯一标识，后面要用到。

小贴士：如果你之前多次刷新过页面，这里可能列出多个 pending 请求。只需批准最新的一条即可，旧的会随时间自动过期。

3.2 批准该设备请求

复制上面输出中的 ID（例如 d7f2a1b4），然后执行批准命令：

clawdbot devices approve d7f2a1b4 

成功后你会看到：

 Approved device request d7f2a1b4. You may now access the web UI at http://localhost:7860 

此时，ClawdBot 已将该设备加入白名单，并向浏览器发送了授权凭证。

3.3 刷新页面，正式进入控制台

回到你的浏览器，强制刷新页面（Ctrl+Shift+R 或 Cmd+Shift+R），而不是简单点击刷新按钮。这是因为浏览器可能缓存了之前的未授权状态。

刷新后，你将看到 ClawdBot 的 Web 控制台首页：左侧是导航栏（Chat、Models、Config、Docs），中间是欢迎面板，右上角显示你的设备名和在线状态。

恭喜，你已成功通过第一道门。

4. 如果还是打不开？备用方案：Dashboard Token 直连

极少数情况下，即使批准了 pending 请求，页面仍无法加载。常见原因包括：

• 浏览器启用了严格隐私模式（如 Firefox 的 Enhanced Tracking Protection）；
• 企业网络或防火墙拦截了 WebSocket 连接；
• 你正在通过 SSH 端口转发访问（比如 ssh -L 7860:localhost:7860 user@server），但本地机器未正确配置。

这时，ClawdBot 提供了一个更可靠的入口：带一次性 Token 的 Dashboard 链接。

在终端中执行：

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 [email protected] Then open: http://localhost:7860/ http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762 Docs: https://docs.clawd.bot/gateway/remote https://docs.clawd.bot/web/control-ui 

把最后一行带 ?token= 的完整链接，直接粘贴到浏览器地址栏中回车。这个 Token 是短期有效的（默认 24 小时），且与设备绑定，安全性不输授权流程。

注意：不要把带 token 的链接分享给他人，也不要截图上传到公开平台。Token 泄露等于控制台权限泄露。

5. 模型配置实战：从 CLI 到 UI，换掉默认模型只需两分钟

ClawdBot 默认使用 vllm/Qwen3-4B-Instruct-2507，但你完全可以换成自己偏好的模型，比如 phi-3-mini-4k-instruct、gemma-2-2b-it，甚至本地微调的小模型。

有两种方式，推荐按顺序尝试：

5.1 方式一：修改 JSON 配置（推荐，适合批量/脚本化）

编辑配置文件 /app/clawdbot.json（Docker 容器内路径）或 ~/.clawdbot/clawdbot.json（宿主机路径）：

找到 "models" 区块，按如下结构添加你的模型：

{ "models": { "mode": "merge", "providers": { "vllm": { "baseUrl": "http://localhost:8000/v1", "apiKey": "sk-local", "api": "openai-responses", "models": [ { "id": "phi-3-mini-4k-instruct", "name": "Phi-3 Mini 4K Instruct" } ] } } } } 

保存后，无需重启 ClawdBot，它会自动热重载配置。验证是否生效：

clawdbot models list 

如果看到新模型出现在列表中，说明配置成功。

5.2 方式二：Web UI 点选（适合快速试用）

进入控制台 → 左侧导航栏点击 Config → 再点 Models → 展开 Providers → 找到 vllm 条目 → 点击右侧 Edit 图标（铅笔）→ 在弹窗中修改 models 数组 → 点击 Save。

整个过程像设置手机壁纸一样直观，改完立刻生效，适合边测试边调整。

实用建议：初次更换模型时，建议先用 clawdbot models list 确认模型 ID 拼写完全一致（大小写、连字符、斜杠都不能错），否则会静默失败。

6. 常见问题与避坑指南

以下是你在入门阶段最可能遇到的几个“小坎”，附上直击要害的解决方案：

6.1 “clawdbot: command not found”

说明 ClawdBot 的 CLI 工具未加入系统 PATH。
解决：使用绝对路径调用，例如 /opt/clawdbot/bin/clawdbot devices list；或进入 ClawdBot 安装目录后再执行命令。

6.2 clawdbot devices list 返回空列表

说明你尚未触发任何 Web 访问请求。
解决：先在浏览器中打开 http://localhost:7860（哪怕只显示错误页），再执行该命令，pending 请求就会出现。

6.3 批准后仍提示“Invalid token”或“Session expired”

这是浏览器缓存或 Cookie 冲突导致。
解决：关闭所有相关标签页 → 清除 localhost:7860 的站点数据（Chrome：设置 → 隐私和安全 → 站点设置 → 所有站点 → 搜索 localhost → 删除）→ 重新打开并批准。

6.4 想用 Telegram 但配置失败？

文中提到的 channel-telegram 配置在国内环境存在连接障碍，不建议新手首次部署就尝试。
建议：先确保 Web 控制台完全跑通，再参考官方文档 https://docs.clawd.bot/channels/telegram 配置代理（如 proxy: "http://127.0.0.1:7890"）和 Bot Token。务必开启 SOCKS5 代理支持。

6.5 模型列表里看不到刚加的模型？

检查三点：
① 配置文件 JSON 格式是否合法（用 JSONLint 验证）；
② baseUrl 是否指向正确的 vLLM 服务地址（默认 http://localhost:8000/v1）；
③ vLLM 服务本身是否已启动且模型已加载（执行 curl http://localhost:8000/v1/models 应返回模型列表）。

7. 总结：你已掌握 ClawdBot 的“钥匙”与“地图”

现在，你已经完成了 ClawdBot 入门最关键的一步：
理解了 Device 授权的本质——不是障碍，而是为你守门的安全卫士；
掌握了 clawdbot devices list 和 approve 这两个核心命令，能自主管理所有接入设备；
学会了两种模型切换方式，CLI 适合稳定生产，UI 适合快速探索；
积累了常见问题的排查思路，不再被“打不开”“找不到”“不生效”卡住。

ClawdBot 的价值，不在于它有多炫酷的界面，而在于它把大模型能力真正交还到你手中：你可以决定用什么模型、处理什么数据、开放给哪些设备、保留多久记录。它不是一个黑盒服务，而是一套可触摸、可调试、可进化的本地AI基础设施。

接下来，你可以试着上传一份 PDF 让它总结，或拖入一张技术架构图让它解释，又或者在 Chat 页面输入“用 Python 写一个爬取天气预报的脚本”，看看它的实时响应能力——这才是属于你自己的 AI 助手该有的样子。

获取更多AI镜像

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