ClawdBot完整指南：从Dashboard访问、Token获取到功能验证
1. ClawdBot 是什么：你的本地AI助手，开箱即用
ClawdBot 不是一个远在云端的黑盒服务，而是一个真正属于你自己的个人AI助手——它运行在你自己的设备上，完全掌控在你手中。没有数据上传、没有隐私泄露风险、不依赖第三方API调用，所有推理都在本地完成。
它的后端由 vLLM 驱动，这意味着你能享受到接近生产级的推理吞吐和极低的响应延迟。vLLM 的 PagedAttention 技术让小显存设备也能流畅运行中等规模模型，比如 Qwen3-4B-Instruct 这类兼顾能力与效率的现代轻量级大模型。
你不需要懂 CUDA 编译、不用手动拉取模型权重、也不用配置复杂的环境变量。ClawdBot 把这些都封装好了：一个命令启动，一个界面管理，一套配置文件统一控制。它不是给工程师看的“玩具项目”，而是为真实使用场景设计的终端用户友好型 AI 工具。
你可以把它理解成「本地版的 Claude Desktop + 自带插件生态」：支持多智能体协作、工作区隔离、上下文自动压缩、子任务并行调度。但它的安装门槛比任何桌面AI应用都低——不需要下载安装包，不需要注册账号，甚至不需要图形界面。
一句话定位：ClawdBot 是面向终端用户的本地化 AI 助手框架，核心价值是「零云依赖、开箱即用、全链路可控」。
2. Dashboard 访问全流程：从拒绝连接到一键直达
很多用户第一次尝试访问 ClawdBot 的 Web 控制台时，会遇到浏览器打不开、页面空白或提示“连接被拒绝”的情况。这不是程序出错，而是安全机制在起作用——ClawdBot 默认不对外暴露 HTTP 服务，必须经过设备授权才能启用 Dashboard。
2.1 为什么不能直接打开 http://localhost:7860？
ClawdBot 采用设备配对（Device Pairing）机制保护本地服务。当你首次运行clawdbot dashboard或启动服务后，系统会在后台生成一个待审批的设备请求。这个请求不会自动通过，必须由你主动确认，防止恶意脚本静默接入。
所以，即使你看到终端输出了http://127.0.0.1:7860/?token=xxx，也不能直接复制粘贴进浏览器打开——因为此时服务尚未对你这台设备放行。
2.2 三步完成设备授权与访问
第一步：列出待处理的设备请求
在终端中执行：
clawdbot devices list你会看到类似这样的输出：
ID Status Created At Last Seen a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8 pending 2026-01-24 14:22:18 2026-01-24 14:22:18只要状态是pending，就说明这个请求正在等待你的批准。
第二步：批准该设备
复制上面显示的 ID（一长串带横杠的字符串），执行：
clawdbot devices approve a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8如果成功，你会看到提示：
Device approved successfully.第三步：获取可访问链接
此时再运行：
clawdbot dashboard输出中会出现两个关键信息：
Dashboard URL:后面是带 token 的完整地址（仅限当前设备）No GUI detected.后面是 SSH 端口转发命令（适用于远程服务器）
如果你是在本地笔记本运行，直接复制http://localhost:7860/?token=...到浏览器即可；
如果你是在云服务器或树莓派上运行，按提示执行 SSH 命令，然后在自己电脑浏览器中打开http://localhost:7860。
注意：token 是一次性且绑定设备 IP 的，每次重启服务或更换网络环境都可能变化。不要截图分享 token，也不建议长期保存。
3. Token 获取与安全机制详解
ClawdBot 的 token 不是传统意义上的 API 密钥，而是一种「会话级临时凭证」，它的设计目标很明确：既保证访问安全，又不增加用户记忆负担。
3.1 Token 的本质是什么？
它是一段 40 位十六进制字符串（如23588143fd1588692851f6cbe9218ec6b874bb859e775762），由服务端在设备授权成功后动态生成，有效期默认为 24 小时，且与以下要素强绑定：
- 设备唯一标识（MAC 地址哈希）
- 请求来源 IP（本地回环
127.0.0.1或 SSH 转发后的localhost） - 当前运行实例 PID（进程级隔离）
这意味着：即使你把 token 发给别人，对方也无法复用；即使你在同一台机器上开了多个终端，每个clawdbot dashboard命令生成的 token 也都不同。
3.2 如何稳定获取可用 token？
最可靠的方式永远是重新执行命令：
clawdbot dashboard它会实时检查当前设备是否已授权，并生成新的有效 token。你不需要记住旧的，也不需要手动修改配置文件。
如果你希望跳过每次输入命令的步骤，可以写一个简单的别名（alias）：
echo "alias cdb='clawdbot dashboard'" >> ~/.bashrc source ~/.bashrc # 之后只需输入 cdb 即可3.3 Token 安全提醒（务必阅读）
- ❌ 不要将 token 提交到 GitHub、Gist 或任何公开平台
- ❌ 不要在群聊、论坛、评论区直接贴出完整 token
- 可以截图 Dashboard 页面（token 字段会被前端自动遮蔽）
- 可以分享
clawdbot dashboard命令本身，这是公开、安全、可重复的操作
ClawdBot 的设计哲学是：安全不该是用户的责任，而是系统的默认行为。你不需要成为安全专家，也能用得安心。
4. 模型配置与验证：从 JSON 修改到终端确认
ClawdBot 支持灵活切换模型，但它的配置方式和传统 LLM 工具不同——它不靠环境变量或命令行参数，而是通过统一的 JSON 配置文件驱动整个系统。这种设计让模型、渠道、代理、工作区全部在一个地方管理，避免碎片化配置。
4.1 配置文件位置与结构说明
主配置文件路径为：
~/.clawdbot/clawdbot.json但在容器或某些部署环境中，它被映射到了：
/app/clawdbot.json你只需要编辑后者，改动会实时同步到前者。
该文件分为两大核心区块：
"agents"：定义智能体行为（默认模型、工作区路径、并发数、压缩策略等）"models"：定义模型提供方（vLLM、Ollama、OpenAI 兼容接口等）及其模型列表
4.2 修改模型为 vLLM 本地服务（推荐做法）
假设你已在本机启动了 vLLM 服务（监听http://localhost:8000/v1），只需在clawdbot.json中补全如下内容：
{ "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" } ] } } } }关键点说明：
"primary"中的模型 ID 必须与"models.providers.vllm.models[].id"完全一致（包括大小写和斜杠）"baseUrl"必须是 vLLM 的/v1接口地址，不是根路径"apiKey"可任意填写（vLLM 本地模式不校验），但不能留空"api": "openai-responses"表示使用 OpenAI 兼容协议，这是 ClawdBot 唯一支持的协议类型
改完保存后，无需重启服务——ClawdBot 会自动热重载配置。
4.3 终端验证模型是否加载成功
执行以下命令：
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：显示vllm/xxx表示识别成功Local：显示yes表示该模型走本地推理（非远程调用）Auth：显示yes表示认证通过（即 apiKey 和 baseUrl 可通）
如果某列是no，请检查：
- vLLM 服务是否正在运行（
curl http://localhost:8000/v1/models应返回 JSON） baseUrl是否拼写错误（常见错误：少写/v1、多写/、协议写成https）- 模型 ID 是否大小写不一致（JSON 区分大小写）
5. UI 界面操作指南：图形化配置更直观
虽然命令行足够强大，但 ClawdBot 也提供了完整的 Web 控制台，尤其适合不熟悉 JSON 格式或偏好可视化操作的用户。
5.1 进入模型配置页
登录 Dashboard 后，点击左侧导航栏的：
Config → Models → Providers你会看到一个表格，列出当前已启用的模型提供方（Provider）。默认只有vllm一项，点击右侧的铅笔图标即可编辑。
5.2 图形化编辑要点
Base URL：填http://localhost:8000/v1（注意末尾/v1）API Key：填任意非空字符串（如sk-local）API Type：选择OpenAI-compatibleModels：点击+ Add Model，填入ID和Name（两者相同即可，如Qwen3-4B-Instruct-2507）
填完点击Save，系统会自动测试连接并刷新模型列表。
5.3 实时效果对比：UI 与 CLI 一致性验证
修改完成后，回到终端再次运行：
clawdbot models list你会发现输出与 UI 中显示的模型完全一致——这说明 ClawdBot 的 UI 和 CLI 共享同一套配置引擎，不存在“界面上改了但实际没生效”的问题。
这也是它区别于其他工具的关键优势：所见即所得，所配即所用。
6. 功能验证实战：用一次对话确认全部就绪
配置完成 ≠ 可用。最后一步，必须通过一次真实对话来验证整个链路是否打通。
6.1 启动交互式终端会话
在终端中输入：
clawdbot chat你会进入一个类似 ChatGPT 的命令行聊天界面，提示符为：
You:6.2 发送第一条测试消息
输入：
你好，我是第一次使用 ClawdBot，请告诉我你现在用的是什么模型？按下回车，稍等 1–3 秒（取决于你的 GPU 显存和模型大小），你应该看到类似回复：
我是 ClawdBot，当前正在使用 Qwen3-4B-Instruct 模型，运行在本地 vLLM 推理服务上。我的上下文长度支持约 195K tokens，适合处理长文档和复杂推理任务。如果看到这样一段结构清晰、内容准确、无报错信息的回复，恭喜你——ClawdBot 已完全就绪。
6.3 常见失败信号与自查清单
| 现象 | 可能原因 | 快速排查 |
|---|---|---|
| 卡住不动，光标闪烁无响应 | vLLM 服务未启动 / 网络不通 | curl http://localhost:8000/v1/models |
| 返回错误：“model not found” | 模型 ID 在 JSON 中拼写错误 | 对照clawdbot models list输出检查 |
| 返回乱码或极短回复（如“嗯。”） | 模型加载失败或权重损坏 | 查看 vLLM 启动日志是否有ERROR |
| 提示 “gateway unreachable” | ClawdBot 主进程异常退出 | ps aux | grep clawdbot看进程是否存在 |
只要终端能打出一句像样的中文回复，就代表：设备授权、token 生效、模型加载、vLLM 连通、上下文调度——全部模块均已协同工作。
7. 总结：一条命令，一个界面，一个属于你的 AI 助手
ClawdBot 的价值，不在于它用了多前沿的模型，而在于它把原本需要数小时搭建的本地 AI 环境，压缩成了一条命令、一个 JSON 文件、一个 Web 页面。
它不强迫你成为 DevOps 工程师，也不要求你精通大模型原理。你只需要：
- 记住
clawdbot devices approve [ID]完成首次授权 - 学会
clawdbot dashboard获取当前可用链接 - 理解
clawdbot.json中agents.defaults.model.primary和models.providers.vllm.models[].id的对应关系 - 用
clawdbot models list和clawdbot chat做最终验证
剩下的，都交给 ClawdBot 自己处理。
它不会向你推销订阅套餐，不会限制你每天调用次数，也不会悄悄记录你的对话历史。它只是一个安静运行在你设备上的工具——就像你的文本编辑器、浏览器或终端一样自然、可信、可控。
这才是个人 AI 助手应有的样子。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
