ClawdBot实战教程：5分钟在本地部署vLLM驱动的个人AI助手

1. 什么是ClawdBot？——你的本地AI助手，不联网也能思考

ClawdBot 不是一个云端服务，也不是需要注册账号的SaaS工具。它是一个真正属于你自己的AI助手，能直接运行在你手边的笔记本、台式机，甚至树莓派上。它不依赖外部API调用，所有推理都在本地完成；它不上传你的对话，不记录你的提问，隐私由你完全掌控。

它的核心能力来自 vLLM —— 当前最高效的开源大模型推理引擎之一。vLLM 通过 PagedAttention 技术大幅提升了显存利用率和吞吐量，让像 Qwen3-4B 这样的高质量模型，在消费级显卡（如 RTX 4060、RTX 4070）上也能实现秒级响应、多轮流畅对话。

ClawdBot 的定位很清晰：不是另一个聊天界面，而是一个可嵌入、可扩展、可定制的AI能力中枢。你可以把它当作：

  • 本地版的“Copilot”，随时帮你写邮件、改文案、理思路；
  • 私有知识库的问答入口，接入你的PDF、笔记、代码库后精准回答；
  • 自动化工作流的智能引擎，配合脚本完成重复性任务；
  • 甚至未来还能对接 Telegram、微信（需自建通道）、邮件等渠道，变成你专属的跨平台AI代理。

它不像某些“一键部署”项目那样只给你一个黑盒网页——ClawdBot 提供完整的配置体系、清晰的模型管理界面、可追溯的日志和结构化的 JSON 配置文件。你不需要懂 Python 或 Rust，但也不会被隔绝在技术之外。

2. 快速部署：从零到可对话，真的只要5分钟

ClawdBot 的安装设计得足够“懒人友好”。它不强制你装一堆依赖，也不要求你手动编译模型。整个过程只需要三步：拉镜像、启服务、配模型。我们以 Ubuntu/Debian 系统为例（macOS 和 Windows WSL 同样适用）：

2.1 前置准备：确认环境是否就绪

请先确保你的设备满足以下最低要求：

  • 操作系统：Linux（推荐 Ubuntu 22.04+）或 macOS（Intel/Apple Silicon）
  • GPU：NVIDIA 显卡（CUDA 12.1+），显存 ≥ 8GB（Qwen3-4B 推荐）
  • 软件：Docker 24.0+、docker-compose v2.20+、curl、jq（用于验证）
  • 注意：ClawdBot 默认不依赖 GPU 加速的 OCR 或语音模型，纯文本推理对显卡要求不高；若后续启用多模态功能，再按需安装对应组件。

执行以下命令检查关键组件：

# 检查 Docker 和 NVIDIA 容器工具
docker --version
nvidia-smi  # 应显示 GPU 信息，若报错请先安装 NVIDIA Container Toolkit

# 检查 docker-compose 是否为 v2（新版已集成）
docker compose version

2.2 一键拉起服务：三条命令搞定

ClawdBot 官方提供了预构建的 Docker 镜像，无需自己 build。打开终端，依次执行：

# 1. 创建工作目录并进入
mkdir -p ~/clawdbot && cd ~/clawdbot

# 2. 下载官方 docker-compose.yml（含 vLLM 后端 + ClawdBot 前端）
curl -fsSL https://raw.githubusercontent.com/clawd-bot/clawd/main/docker-compose.yml -o docker-compose.yml

# 3. 启动服务（后台运行）
docker compose up -d

成功标志：终端无报错，且 docker compose ps 显示 clawdbot 和 vllm 两个服务状态均为 running。

此时，vLLM 推理服务已在 http://localhost:8000/v1 就绪，ClawdBot 主程序也已启动，正等待你完成最后一步“身份认证”。

2.3 解锁 Web 控制台：处理设备授权请求

ClawdBot 采用设备码（Device Code）机制保障首次访问安全——这比直接暴露 token 更可靠，也避免了浏览器 CORS 问题。

执行以下命令查看待批准的设备请求：

clawdbot devices list

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

ID         Status     Created At           Last Seen
abc123     pending    2026-01-24 10:22:15  -

复制 ID（如 abc123），然后批准它：

clawdbot devices approve abc123

执行成功后，你就可以在浏览器中打开 http://localhost:7860 访问 ClawdBot 控制台了。

如果页面打不开，请不要反复刷新。先运行 clawdbot dashboard 获取带 token 的完整链接（见下文图示），或检查是否被防火墙拦截。ClawdBot 默认绑定 127.0.0.1，不对外网开放，安全性有保障。

3. 模型配置：把 vLLM 接入 ClawdBot 的完整流程

ClawdBot 本身不自带大模型，它是一个“模型调度器”。你需要告诉它：去哪里找模型、用哪个模型、怎么调用它。而 vLLM 正是我们本地的模型服务器。

3.1 理解配置逻辑：三层结构一目了然

ClawdBot 的模型配置分为三个层级，理解它们能让你少走90%弯路：

层级 配置位置 作用 修改频率
Provider（提供方） models.providers.vllm 定义 vLLM 服务地址、认证方式、支持的模型列表 首次部署后基本不变
Model ID（模型标识） models.providers.vllm.models[].id 给本地模型起一个内部代号，如 Qwen3-4B-Instruct-2507 每新增一个模型时添加
Agent 默认模型（使用入口） agents.defaults.model.primary 指定用户对话默认调用哪个模型 ID 可随时切换，影响所有新会话

这个设计的好处是：你可以在同一套 ClawdBot 中，同时接入多个 vLLM 实例（比如一个跑 Qwen3，一个跑 Phi-3），并通过 Agent 配置灵活路由。

3.2 修改配置文件：两种方式任选其一

方式一：直接编辑 JSON 文件（推荐，最可控）

ClawdBot 的主配置文件位于 ~/.clawdbot/clawdbot.json（容器内映射为 /app/clawdbot.json）。用你喜欢的编辑器打开它，找到 models 和 agents 节点，按如下结构补全：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "vllm/Qwen3-4B-Instruct-2507"
      },
      "workspace": "/app/workspace",
      "maxConcurrent": 4
    }
  },
  "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"
          }
        ]
      }
    }
  }
}

关键点说明：

  • "baseUrl": "http://localhost:8000/v1"：这是 vLLM 服务的 OpenAI 兼容接口地址，ClawdBot 会像调用 ChatGPT API 一样与之通信；
  • "apiKey": "sk-local"：vLLM 默认接受任意 key，这里填什么都可以，但必须存在；
  • "id": "vllm/Qwen3-4B-Instruct-2507"：格式固定为 provider/model-id，ClawdBot 用它唯一识别模型；
  • 修改后保存文件，无需重启容器，ClawdBot 会自动热重载配置（约5秒内生效）。
方式二：通过 Web UI 图形化配置（适合尝鲜）

打开 http://localhost:7860 → 左侧菜单点击 Config → Models → Providers → 点击右上角 + Add Provider → 选择 vLLM → 填入：

  • Base URL：http://localhost:8000/v1
  • API Key：sk-local
  • Model ID：Qwen3-4B-Instruct-2507
  • Model Name：Qwen3-4B-Instruct-2507

点击 Save，再进入 Agents → Defaults → Model，将 Primary Model 切换为你刚添加的 ID 即可。

3.3 验证模型是否真正就绪

配置完成后，别急着聊天，先用命令行确认模型已“在线”：

clawdbot models list

你应该看到类似输出：

Model                                      Input      Ctx      Local Auth  Tags
vllm/Qwen3-4B-Instruct-2507                text       195k     yes   yes   default

出现这一行，代表：

  • ClawdBot 已成功连接 vLLM 服务；
  • vLLM 确实加载了 Qwen3-4B-Instruct-2507 模型；
  • 模型支持文本输入，上下文长度达 195K tokens（远超 GPT-4 Turbo）；
  • “Local Auth: yes” 表示该模型由本地 vLLM 提供，不走网络。

此时，你已经完成了从部署到模型接入的全部技术环节。接下来，就是最令人期待的部分——和你的本地 AI 助手说第一句话。

4. 开始对话：不只是聊天，而是开启一个私有AI工作区

ClawdBot 的 Web 界面（http://localhost:7860）不是一个简陋的聊天框，而是一个轻量级的 AI 工作台。它默认提供三个核心区域：

4.1 主对话区：自然、连贯、带记忆的交互体验

在首页中央的输入框中，试着输入：

“你好，我是第一次用 CladwBot。请用一句话介绍你自己，并告诉我你能帮我做什么。”

你会立刻看到回应——不是几秒后，而是几乎实时（通常 < 800ms）。这是因为 vLLM 的高效推理 + ClawdBot 的低开销调度共同实现了极短延迟。

更关键的是，ClawdBot 默认启用会话上下文管理。你接着问：

“刚才你说能帮我整理会议纪要，那我现在发一段录音文字，你能总结要点吗？”

它会结合前文理解你的意图，而不是当成孤立的新请求。这种“连续对话感”，正是本地部署带来的体验升级：没有网络抖动，没有 token 限流，没有突然的“抱歉我无法回答”。

4.2 Workspace（工作区）：把 AI 变成你的第二大脑

点击顶部导航栏的 Workspace 标签，你会进入一个类似 Notion 的文档空间。这里不是用来记笔记的，而是用来喂养你的 AI：

  • 你可以拖入 PDF、TXT、Markdown 文件，ClawdBot 会自动切片、向量化并建立本地索引；
  • 支持 @workspace 语法在对话中引用特定文档，例如：“根据《产品需求文档_v2.pdf》第3节，列出三个核心功能点”；
  • 所有数据仅存于你本地磁盘（默认路径 /app/workspace），不会上传至任何服务器。

这意味着：你再也不用把敏感合同、未发布代码、内部调研报告发给第三方大模型——你的知识资产，始终在你手中。

4.3 Agents（智能体）：让 AI 主动帮你做事

ClawdBot 的 Agents 功能，是它区别于普通聊天界面的关键。它允许你定义“当发生某事时，自动执行某动作”的规则。

例如，你可以创建一个名为 Daily Summary 的 Agent：

  • 触发条件：每天上午 9:00
  • 执行动作：读取 ~/notes/daily/ 目录下最新 3 篇 Markdown 日志 → 总结今日重点 → 发送至指定 Telegram 群组（需额外配置 channel）

虽然 Telegram 配置在国内需代理（见后文提示），但纯本地 Agent（如定时生成周报、监控日志关键词、自动归档邮件摘要）已完全可用。你写的不是 prompt，而是可调度、可审计、可复用的 AI 工作流。

5. 进阶提示：避开常见坑，让体验更丝滑

即使是最顺滑的部署，也可能遇到几个“意料之中”的小状况。以下是真实用户高频反馈的问题与解决方案：

5.1 问题：vLLM 启动失败，日志显示 CUDA out of memory

原因：Qwen3-4B 默认以 bfloat16 加载，显存占用约 9GB；若你用的是 8GB 显卡（如 RTX 4070），需降级精度。

解决：修改 docker-compose.yml 中 vLLM 服务的启动命令，加入 --dtype auto 或 --dtype half：

services:
  vllm:
    # ... 其他配置
    command: >
      --model Qwen/Qwen3-4B-Instruct
      --tensor-parallel-size 1
      --dtype auto  # ← 关键！让 vLLM 自动选择 float16/bfloat16
      --port 8000
      --host 0.0.0.0

然后重启：docker compose down && docker compose up -d

5.2 问题：Web 界面打不开，clawdbot dashboard 显示 No GUI detected

原因：你在远程服务器（如云主机）上运行，本地没装图形界面，ClawdBot 无法自动打开浏览器。

解决：按提示执行 SSH 端口转发：

# 在你的本地电脑（Mac/Windows）终端中执行：
ssh -N -L 7860:127.0.0.1:7860 user@your-server-ip

然后在本地浏览器打开 http://localhost:7860 即可。这是最安全的远程访问方式，所有流量都经 SSH 加密。

5.3 问题：想用其他模型，比如 Llama-3.1-8B，该怎么加？

步骤清晰四步走：

  1. 下载模型到本地：huggingface-cli download Qwen/Qwen3-4B-Instruct --local-dir ./models/Qwen3-4B-Instruct
  2. 修改 docker-compose.yml，在 vLLM 服务中挂载该目录： 
    volumes:
  - ./models:/models
command: --model /models/Qwen3-4B-Instruct ...
  3. 在 clawdbot.json 的 models.providers.vllm.models 数组中新增一项： 
    { "id": "vllm/Llama-3.1-8B", "name": "Llama-3.1-8B" }
  4. 更新 agents.defaults.model.primary 为新 ID，保存即生效。

无需重启容器，ClawdBot 会在下次请求时自动发现新模型。

6. 总结：为什么 CladwBot 值得你花这5分钟？

ClawdBot 不是又一个玩具项目。它用极简的部署路径，交付了一个真正可落地的本地 AI 架构：vLLM 提供工业级推理性能，ClawdBot 提供人性化交互与工程化管理。它解决了三个长期存在的痛点：

  • 隐私焦虑：所有数据不出设备，连 prompt 都不离开内存；
  • 成本失控：告别按 token 计费，一次部署，永久免费使用；
  • 体验割裂：不再需要在 HuggingFace、Ollama、LM Studio、Chatbox 多个工具间切换。

更重要的是，它为你预留了充足的演进空间。今天你用它聊天气、写周报；明天你可以接入企业数据库做 BI 分析；后天可以把它包装成内部客服机器人，嵌入公司 OA 系统——底层能力不变，上层形态随需而变。

真正的 AI 自主权，不在于你能否调用最强的模型，而在于你能否在自己定义的边界内，稳定、可靠、低成本地使用它。ClawdBot，就是这条路上，一个扎实的起点。

获取更多AI镜像

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

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区