ClawdBot环境部署：Ubuntu/CentOS/Docker Desktop多平台适配指南

ClawdBot 是一个你可以在自己设备上运行的个人 AI 助手，本应用使用 vLLM 提供后端模型能力。它不是云端黑盒服务，而是一个真正属于你的本地化智能中枢——能理解、能推理、能执行，所有数据留在你自己的机器里。它不依赖外部 API 密钥，不上传对话历史，也不强制联网验证。你装好就能用，改配置就能换模型，点几下就能调出控制台，像管理一台熟悉的开发服务器那样自然。

但和传统服务不同，ClawdBot 的部署方式更轻、更灵活：它既支持在 Ubuntu 或 CentOS 这类 Linux 服务器上原生运行，也兼容 Docker Desktop（Windows/macOS 用户最熟悉的容器环境），甚至能在树莓派等边缘设备上稳定工作。这意味着无论你是刚接触命令行的新手，还是习惯图形界面的办公用户，或是需要长期驻守后台的运维人员，都能找到最适合自己的启动路径。本文不讲抽象概念，只说“在哪敲哪条命令”“遇到报错怎么解”“页面打不开怎么办”，全程聚焦真实操作场景，帮你把 ClawdBot 真正跑起来、用起来、稳下来。

1. 部署前准备：系统要求与基础依赖

在动手安装之前，先确认你的设备满足最低运行条件。ClawdBot 对硬件并不苛刻，但不同平台有细微差异，我们按三类主流环境分别说明。

1.1 Ubuntu / Debian 系统（推荐 22.04+）

这是 ClawdBot 官方最常测试的环境，稳定性高，社区支持完善。你需要：

  • 系统版本：Ubuntu 22.04 LTS 或更新版本（Debian 12+ 同样适用）
  • 内存：至少 8GB（运行 Qwen3-4B 模型时建议 12GB+）
  • 磁盘空间：预留 20GB 可用空间（含模型缓存与日志）
  • Python 版本：系统自带 Python 3.10 或更高（无需手动安装）

注意：ClawdBot 不依赖 apt install python3-pip 全局安装包管理器。它会自动创建隔离的虚拟环境，避免污染系统 Python。你只需确保 python3 和 curl 命令可用即可。

1.2 CentOS / Rocky Linux / AlmaLinux（推荐 8.5+ 或 9.0+）

企业级 Linux 用户首选。CentOS Stream 9 或 Rocky Linux 9 是当前最稳妥的选择。需注意两点：

  • SELinux 默认启用：ClawdBot 的 Web 控制台（Gradio）默认绑定 127.0.0.1:7860，SELinux 通常不会拦截；但若你修改为 0.0.0.0:7860 并对外提供访问，需临时放行端口： 
    sudo semanage port -a -t http_port_t -p tcp 7860
  • EPEL 仓库建议启用：部分构建依赖（如 gcc, make）可通过 dnf install epel-release 后安装，避免编译失败。

1.3 Docker Desktop（Windows 11 / macOS Sonoma+）

这是对新手最友好的路径——不用碰终端权限、不担心依赖冲突、一键拉取即用。你只需要：

  • Windows：启用 WSL2（Docker Desktop 安装向导会自动提示）
  • macOS：Intel 或 Apple Silicon 芯片均可，Docker Desktop 4.30+ 版本
  • 磁盘空间：镜像约 1.2GB，加上模型缓存建议预留 15GB+

关键提醒：Docker Desktop 默认限制内存为 2GB。Qwen3-4B 模型加载需至少 6GB 内存。请务必进入 Docker Desktop 设置 → Resources → Memory，将值调至 6GB 或更高，否则启动时会卡在模型加载阶段，日志显示 OOM killed process。

2. 三步完成部署：各平台实操命令清单

ClawdBot 提供统一安装脚本，但不同平台的执行方式略有不同。以下命令均经过实测，复制粘贴即可运行，无需额外编辑。

2.1 Ubuntu / CentOS 原生命令部署

打开终端，逐行执行（无需 root 权限，普通用户即可）：

# 1. 下载并运行一键安装脚本（自动检测系统类型）
curl -fsSL https://raw.githubusercontent.com/clawd-bot/install/main/install.sh | bash

# 2. 初始化配置（生成 ~/.clawdbot/clawdbot.json）
clawdbot init

# 3. 启动服务（后台运行，日志自动轮转）
clawdbot start

执行完 clawdbot start 后，服务会在后台持续运行。你可以随时用 clawdbot status 查看状态，用 clawdbot logs --tail 50 查看最近 50 行日志。

2.2 Docker Desktop 一键部署

在 Windows PowerShell 或 macOS 终端中执行（确保 Docker Desktop 已启动）：

# 拉取官方镜像（首次运行需约 2 分钟）
docker pull clawdbot/clawdbot:latest

# 启动容器（映射端口、挂载配置目录、分配足够内存）
docker run -d \
  --name clawdbot \
  -p 7860:7860 \
  -p 18780:18780 \
  -v ~/.clawdbot:/app/.clawdbot \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --memory=6g \
  --restart=unless-stopped \
  clawdbot/clawdbot:latest

为什么挂载两个目录？
-v ~/.clawdbot 保存你的配置文件（clawdbot.json）和会话数据；
-v ~/.cache/huggingface 复用你本地已下载的模型，避免重复拉取（如果你之前用过 Hugging Face 模型，这一步能省下 10 分钟以上）。

2.3 验证部署是否成功

无论哪种方式，启动后都执行同一命令检查核心服务：

clawdbot health

正常输出应类似：

 Gateway: running (ws://127.0.0.1:18780)
 Model server: vLLM online (http://localhost:8000/v1)
 Web UI: ready (http://127.0.0.1:7860)
 Config: loaded from /home/youruser/.clawdbot/clawdbot.json

如果某一项显示 ，请根据提示检查对应服务（如 Model server 失败，大概率是 vLLM 未启动或端口被占用）。

3. 首次访问控制台：解决“页面打不开”的三大原因

很多用户卡在这一步：执行 clawdbot start 后，浏览器打开 http://localhost:7860 显示无法连接。这不是安装失败，而是 ClawdBot 的安全设计所致——它要求设备认证后才开放 Web 界面。以下是三种常见情况及对应解法：

3.1 场景一：新设备首次连接（最常见）

ClawdBot 将每台访问控制台的设备视为独立客户端，需人工批准。执行：

# 列出待批准的设备请求
clawdbot devices list

# 输出示例：
# ID: 123e4567-e89b-12d3-a456-426614174000 | Status: pending | IP: 192.168.1.100 | OS: Windows 11

找到 Status: pending 的条目，复制其 ID，执行批准：

clawdbot devices approve 123e4567-e89b-12d3-a456-426614174000

批准后刷新页面，即可正常进入。

3.2 场景二：远程访问（如通过 SSH 连接服务器）

你在公司电脑 SSH 登录家里的 Ubuntu 服务器，想在本地浏览器打开控制台。此时 localhost:7860 指向的是服务器本机，而非你的电脑。正确做法是：

# 在服务器终端执行（自动生成带 token 的链接）
clawdbot dashboard

# 输出示例：
# Dashboard URL: http://127.0.0.1:7860/?token=abc123...
# Then open: http://localhost:7860/

按提示，在你的本地电脑浏览器中打开 http://localhost:7860/（不是服务器 IP），同时建立 SSH 端口转发：

# 在本地电脑终端执行（Windows 用 PowerShell，macOS/Linux 用 Terminal）
ssh -N -L 7860:127.0.0.1:7860 user@your-server-ip

这样，你本地的 localhost:7860 就被安全地映射到了服务器的 127.0.0.1:7860。

3.3 场景三：Docker Desktop 环境下端口未暴露

Docker 容器默认不自动暴露端口给宿主机。如果你用 docker run 启动但没加 -p 7860:7860，则需重新运行：

# 先停止并删除旧容器
docker stop clawdbot && docker rm clawdbot

# 再用完整命令启动（务必包含 -p 参数）
docker run -d --name clawdbot -p 7860:7860 -p 18780:18780 -v ~/.clawdbot:/app/.clawdbot clawdbot/clawdbot:latest

4. 模型配置实战：从默认 Qwen3 到自定义模型

ClawdBot 默认使用 vllm/Qwen3-4B-Instruct-2507，但你完全可以替换成其他开源模型。配置方式有两种，推荐优先使用配置文件法（稳定、可复现、易备份）。

4.1 修改配置文件（推荐）

编辑 ~/.clawdbot/clawdbot.json（Linux/macOS）或 %USERPROFILE%\.clawdbot\clawdbot.json（Windows）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "vllm": {
        "baseUrl": "http://localhost:8000/v1",
        "apiKey": "sk-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "Qwen2.5-7B-Instruct",
            "name": "Qwen2.5-7B-Instruct"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "vllm/Qwen2.5-7B-Instruct"
      }
    }
  }
}

关键点说明：

  • "id" 必须与 Hugging Face 模型 ID 完全一致（如 Qwen2.5-7B-Instruct）；
  • "primary" 字段必须写成 vllm/模型ID 格式；
  • 修改后需重启服务：clawdbot restart（Docker 用户执行 docker restart clawdbot）。

4.2 通过 Web 界面修改（适合快速尝试）

进入 http://localhost:7860 → 左侧菜单点击 Config → Models → Providers → 找到 vllm 条目 → 点击右侧铅笔图标 → 在 Models 数组中添加新对象：

{
  "id": "Phi-3.5-mini-instruct",
  "name": "Phi-3.5-mini-instruct"
}

然后在 Agents → Defaults → Model 中，将 Primary model 下拉框切换为新模型名。

4.3 验证模型是否加载成功

无论哪种方式，最终都用命令验证：

clawdbot models list

成功输出应包含你配置的模型，且 Local Auth 列为 yes：

Model                                      Input      Ctx      Local Auth  Tags
vllm/Qwen2.5-7B-Instruct                   text       131k     yes   yes   default

若只显示默认模型，说明配置未生效，请检查 JSON 格式是否合法（推荐用 JSONLint 在线校验）。

5. 常见问题速查表：高频报错与解决方案

报错现象 可能原因 解决方案
Gateway not reachable: Error: gateway closed (1006) vLLM 服务未启动或崩溃 执行 clawdbot logs --service vllm 查看错误；常见原因是内存不足，升级 RAM 或换更小模型
Connection refused 访问 http://localhost:7860 Web 服务未运行或端口被占 clawdbot status 检查 UI 状态；lsof -i :7860 查看端口占用，杀掉冲突进程
No module named 'vllm' Python 环境未正确初始化 删除 ~/.clawdbot/.venv 目录，重新运行 clawdbot init
Docker 启动后 clawdbot 命令不存在 宿主机未安装 CLI 工具 Docker 部署用户无需本地 CLI；所有操作通过 docker exec -it clawdbot clawdbot [command] 执行
模型加载慢（>5 分钟） 首次下载模型需时间 耐心等待；可提前在另一终端执行 huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ~/models/qwen25 预热

6. 总结：让 ClawdBot 成为你真正的本地 AI 助手

ClawdBot 的价值，不在于它用了多前沿的架构，而在于它把复杂的技术封装成可触摸、可调试、可掌控的日常工具。你不需要成为大模型专家，也能：

  • 在 Ubuntu 服务器上把它当作后台服务，7×24 小时响应你的指令；
  • 在 macOS 笔记本里用 Docker Desktop 一键启停，开会前 30 秒就准备好会议纪要助手；
  • 在 CentOS 企业环境中，通过 SELinux 策略和端口隔离，让它安全地融入现有 IT 架构；
  • 更重要的是，所有模型、所有对话、所有配置，都在你自己的硬盘上——没有第三方能访问，也没有服务条款的隐形约束。

部署只是开始。接下来，你可以用它自动整理邮件、辅助写技术文档、实时翻译外文论文，甚至接入你自己的数据库做私有知识问答。它的能力边界，由你的需求定义，而不是由厂商的 API 限额决定。

现在，关掉这篇教程，打开你的终端，输入第一条命令。五分钟后，那个属于你自己的 AI 助手，就会在浏览器里向你打招呼。

获取更多AI镜像

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

Logo
龙虾开发者社区

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

更多推荐

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

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

avatar 龙虾开发者社区

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

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

avatar 龙虾开发者社区

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

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

avatar 龙虾开发者社区