Clawdbot 完整安装与运维指南：打造你的 24/7 私人 AI 助手
一、准备工作：系统要求与核心依赖
在开始安装前，需完成硬件、软件及必备账号的准备，确保部署过程顺畅，避免因环境不符导致失败。
1. 硬件要求
- 推荐配置：CPU 4核+、内存 8GB+、硬盘 20GB+ 可用空间，运行更流畅，支持多任务同时处理；
- 最低配置：CPU 2核、内存 4GB、硬盘 10GB+ 可用空间，可满足基础功能运行；
- 24/7 运行建议：优先使用服务器、树莓派或 Mac Mini 等低功耗设备，避免频繁关机，确保助手全天候在线。
2. 软件要求与平台兼容性
不同平台的支持方式略有差异，核心依赖版本需严格遵循要求，具体如下：
（1）核心依赖清单
依赖项 | 版本要求 | 说明 |
|---|---|---|
Node.js | ≥ 22.x | Clawdbot 核心运行环境，版本过低会导致部署失败 |
npm/pnpm | 最新版 | Node.js 包管理器，优先推荐 pnpm，兼容性更好 |
Git | 最新版 | 源码安装、Docker 部署时必备，用于克隆仓库 |
WSL2 | 最新版 | Windows 用户必备，需安装 Ubuntu 子系统配合使用 |
（2）平台兼容性说明
平台 | 支持方式 | 特殊要求 |
|---|---|---|
macOS/Linux | 原生支持 | 无特殊要求，直接执行安装命令即可 |
Windows | 通过 WSL2 支持 | 需启用 WSL2 并安装 Ubuntu 22.04 LTS 子系统 |
云服务器 | 完全支持 | 推荐 2GB 以上内存，确保 24/7 在线，需配置防火墙 |
3. 必备账号与密钥
部分功能需依赖外部账号与密钥，提前准备可节省配置时间，至少需满足其中1个聊天平台账号和1个模型相关密钥（本地模型可无需密钥）：
- 大模型 API 密钥：优先推荐 Claude 3（Anthropic 平台），也可使用 GPT-4（OpenAI 平台），若追求隐私优先，可选择本地模型（如 Ollama、LM Studio），无需 API 密钥；
- 聊天平台账号：Telegram、WhatsApp 等（至少一个），用于与 Clawdbot 交互下达指令；
- Telegram Bot Token（可选）：若使用 Telegram 交互，需创建专属机器人获取 Token，后续用于渠道绑定。
密钥获取直达链接：Anthropic 控制台（Claude 3 API）、OpenAI 控制台（GPT-4 API），Telegram 可通过搜索 @BotFather 创建机器人获取 Token。
二、安装方式详解（四选一，按需选择）
Clawdbot 提供四种安装方式，适配不同用户基础，新手优先选择一键脚本安装，进阶用户可根据需求选择手动、Docker 或源码安装，所有方式最终均可实现完整功能。
1. 一键脚本安装（推荐，新手首选）
该方式自动处理依赖与环境配置，全程引导，无需手动解决复杂依赖问题，适配 macOS、Linux 及 Windows WSL2，Windows 原生需使用 PowerShell 执行专属命令。
系统/环境 | 安装命令（直接复制执行） | 后续操作 |
|---|---|---|
Linux/macOS | curl -fsSL https://clawd.bot/install.sh | bash | 执行 exec bash 重新载入环境变量，再执行 clawdbot onboard --install-daemon 启动配置向导并安装守护进程 |
Windows（WSL2） | curl -fsSL https://clawd.bot/install.sh | bash | 同 Linux/macOS 后续操作 |
Windows（PowerShell 管理员模式） | iwr -useb https://clawd.bot/install.ps1 | iex | 直接执行 clawdbot onboard --install-daemon 启动配置向导 |
自动化安装（无交互，适合服务器部署）：curl -fsSL https://clawd.bot/install.sh | bash -s -- --no-onboard
2. 手动 npm 安装（适合有 Node.js 基础的用户）
需手动安装 Node.js 及包管理器，步骤清晰，便于排查问题，适合想了解部署细节的进阶用户。
- 安装 Node.js 22+：可通过官网直接下载（https://nodejs.org/en/download），或使用 nvm 管理版本（推荐，避免权限问题），命令如下： curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 22 nvm use 22
- 安装 Clawdbot：使用 npm 或 pnpm 全局安装，优先推荐 pnpm，命令如下： npm install -g clawdbot@latest # 或使用 pnpm（推荐） pnpm add -g clawdbot@latest
- 启动安装向导：执行 clawdbot onboard --install-daemon，启动配置向导并安装守护进程，确保 24/7 运行。
3. Docker 部署（服务器推荐，环境隔离）
通过 Docker 实现环境隔离，版本控制简单，避免与本地其他软件冲突，适合服务器长期部署。
- 安装 Docker 与 Docker Compose： sudo apt update sudo apt install docker.io docker-compose -y sudo systemctl enable docker sudo systemctl start docker
- 克隆仓库并配置： git clone https://github.com/clawdbot/clawdbot.git cd clawdbot cp .env.example .env nano .env # 修改配置（AI名称、端口、API密钥等）
- 启动服务：执行 docker-compose up -d --build，后台启动服务。
- 验证部署：打开浏览器访问 http://localhost:8080，看到 Clawdbot 控制面板即部署成功。
4. 源码安装（适合开发者/自定义需求）
可获取最新功能，支持自定义开发与修改，适合有编程基础、需要二次开发的高级用户。
# 克隆仓库
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
# 安装依赖（推荐 pnpm）
npm install -g pnpm
pnpm install
# 构建 UI 与项目
pnpm ui:build
pnpm build
# 运行安装向导并安装守护进程
pnpm clawdbot onboard --install-daemon三、核心配置向导（关键步骤，必看）
无论选择哪种安装方式，最终都需执行 clawdbot onboard --install-daemon 进入交互式配置向导，完成核心设置后，Clawdbot 才能正常使用，以下是向导核心步骤详解。
1. 选择配置模式
- 快速开始：适合新手，自动配置基础选项，无需手动调整参数，全程引导完成；
- 高级配置：适合有经验用户，可自定义模型参数、端口、认证方式等，灵活适配需求。
2. Gateway 选择
- Local Gateway（推荐）：在本地设备运行，适合个人使用，操作便捷；
- Remote Gateway：在远程服务器运行，适合多设备访问，需配置端口转发。
3. 模型配置（核心，决定 AI 能力）
支持云模型与本地模型，按需选择，步骤如下：
- 选择模型提供商：Claude/OpenAI/Anthropic（云模型）或 Ollama/LM Studio（本地模型）；
- 云模型需粘贴提前获取的 API 密钥（注意无空格、不过期），本地模型需输入模型服务地址（如 Ollama 默认 http://localhost:11434）；
- 设置模型参数（温度、最大上下文等），新手可保持默认；
- 测试连接，确保模型能正常调用，显示“连接成功”再进入下一步。
4. 认证方式设置
- 密码认证：设置简单密码，便于登录 Web 仪表盘；
- Token 认证：生成随机访问令牌，安全性更高，适合服务器部署。
5. 聊天渠道绑定（至少选择一个，实现交互）
支持 Telegram、WhatsApp、Slack 等多种渠道，以下是最常用的两种渠道配置步骤：
（1）Telegram 配置（最稳定，推荐）
- 在 Telegram 中搜索 @BotFather，发送 /newbot 按提示创建机器人；
- 记录 BotFather 提供的 Token（格式：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11）；
- 在配置向导中选择 Telegram 渠道，粘贴 Token 并完成授权；
- 向创建的机器人发送 /start 命令，收到回复即绑定成功。
（2）WhatsApp 配置（需配对）
- 在向导中选择 WhatsApp 渠道；
- 扫描向导提供的二维码，或输入手机号完成设备配对（使用 WhatsApp Web 协议）；
- 等待连接成功，发送测试消息验证即可。
6. Skills 安装（功能扩展）
Skills 是 Clawdbot 的功能扩展模块，可根据需求选择安装，部分为必装项，确保基础功能可用。
- 必装技能：系统命令、文件操作、网络请求，是实现核心任务的基础；
- 推荐技能：日程管理、代码解释、文档处理、网页搜索，提升助手实用性；
- 安装方式：向导中可通过空格键选择技能，回车确认安装；后续可通过 clawdbot skill install <skill-name> 添加更多技能，通过 clawdbot skill list 查看已安装技能。
7. 守护进程安装（24/7 运行关键）
向导最后会询问是否安装系统服务，务必选择“是”，该服务会自动配置 systemd（Linux/WSL2）或 launchd（macOS），实现开机自启与后台运行，无需手动启动。
四、24/7 运行保障配置（关键，确保全天候在线）
安装守护进程后，需验证服务状态并配置开机自启，避免设备重启后服务停止，同时掌握日志查看方法，便于排查异常。
1. 服务状态验证（核心命令）
运行环境 | 状态查询命令 | 启动服务命令（未运行时执行） |
|---|---|---|
Linux/WSL2 | systemctl --user status clawdbot-gateway | systemctl --user start clawdbot-gateway |
macOS | launchctl list | grep clawdbot | launchctl start com.clawdbot.gateway |
提示：状态显示“active(running)”即表示服务正常运行。
2. 开机自启配置（永久生效）
# Linux/WSL2（systemd 系统）
systemctl --user enable clawdbot-gateway
# macOS（launchd 系统，自动配置，验证即可）
launchctl list | grep clawdbotWindows WSL2 额外配置：以管理员身份运行 PowerShell，创建任务计划程序，设置开机执行 WSL 命令，确保 WSL2 自动启动。
3. 日志查看与问题排查（故障急救关键）
日志是排查服务启动、模型调用、渠道连接问题的核心，不同环境的日志查看命令如下：
运行环境 | 日志查看命令（实时刷新，-f 参数） | 说明 |
|---|---|---|
Linux/WSL2 | journalctl --user -u clawdbot-gateway -f | 系统级日志，查看守护进程运行状态 |
macOS | log stream --predicate 'process == "clawdbot-gateway"' | 系统级日志，实时查看服务运行详情 |
全平台 | clawdbot log --follow（或 clawdbot gateway logs） | 官方内置命令，优先推荐，查看网关运行日志 |
4. 远程访问设置（可选，多设备使用）
- 端口转发：在路由器设置中转发 Clawdbot 端口（默认 3000 端口，Web 仪表盘），实现公网访问；
- Tailscale：安装 Tailscale VPN，无需公网 IP，即可实现安全远程访问，适合无公网 IP 的用户。
5. 安全加固（可选，推荐）
为避免未授权访问，保障隐私安全，可进行以下安全配置：
- 防火墙设置：仅开放必要端口，Linux 可通过 ufw 配置，命令如下： sudo ufw allow 3000/tcp # 允许 Web 仪表盘端口 sudo ufw enable macOS 可通过“系统设置 > 网络 > 防火墙”允许 Clawdbot 连接。
- 启用操作确认：执行 clawdbot config set security.confirmAllActions true，避免误操作；
- 限制访问 IP：执行 clawdbot config set network.allowedIps "192.168.1.0/24"，仅允许指定 IP 段访问；
- 禁用不必要的 Skills：执行 clawdbot skills disable <skill-name>，减少安全隐患；
- 定期更新：执行 clawdbot update，获取新功能与安全修复，保障服务稳定。
五、测试与验证（确认部署成功）
部署与配置完成后，需进行简单测试，确认 Clawdbot 能正常响应指令，核心测试步骤如下：
- 检查 Gateway 状态：执行 clawdbot gateway status，显示“Running”即表示网关正常；
- Web 仪表盘访问：打开浏览器访问 http://localhost:3000，使用配置时设置的认证方式登录，能正常进入仪表盘即成功；
- 功能测试（关键）：通过已绑定的聊天平台（如 Telegram）发送测试指令，示例如下：发送“帮我在本地创建一个名为 test 的文件夹”，机器人回复确认后，发送“确认”，查看本地是否生成 test 文件夹；发送“列出当前目录文件”，验证文件操作功能；发送“编写一个简单的 Python 脚本”，验证代码执行功能。
若所有测试均正常，说明你的 24/7 私人 AI 助手已成功部署！
六、常见问题排查（故障急救，快速解决）
部署与使用过程中，可能会遇到各类问题，以下是高频问题的现象、原因及解决方法，可直接复制命令执行修复。
1. Node.js 版本不兼容（最常见）
- 故障现象：服务启动失败，日志提示“node version < 22”；
- 核心原因：Node.js 版本低于 22.x，不满足运行要求；
- 解决命令： # 安装 nvm 管理 Node 版本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash exec bash # 安装并启用 Node.js 22 nvm install 22 nvm alias default 22 exec bash # 重新加载环境
2. 权限不足错误（Permission denied）
- 故障现象：安装或启动服务时，提示权限不足；
- 核心原因：npm 全局安装权限不足，或文件夹访问权限不够；
- 解决命令（Linux/macOS）： mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc exec bash
3. 聊天渠道连接失败
- 故障现象：仪表盘显示“渠道未连接”，发送消息无响应；
- 核心原因：Token/API 密钥错误、网络被拦截，或未完成配对；
- 解决方法： 核对 Token/API 密钥是否复制完整，无多余空格、未过期；确保网络可访问聊天平台 API，关闭防火墙临时验证；Telegram：重新生成 Bot Token，在仪表盘重新粘贴；WhatsApp：执行 clawdbot skills restart whatsapp，重新扫码配对；重启 Clawdbot 服务：clawdbot restart。
4. 守护进程启动失败
- 故障现象：systemctl/launchctl 查看状态为“failed”；
- 核心原因：守护进程未正确安装，或配置文件异常；
- 解决命令： # 重新安装守护进程 clawdbot service install --force # 启动服务 clawdbot service start # 查看详细错误日志 clawdbot log --error
5. 端口被占用（Web 仪表盘无法访问）
- 故障现象：浏览器访问 http://localhost:3000 提示“无法连接”，日志提示“port already in use”；
- 核心原因：3000 端口（默认）被其他软件占用；
- 解决方法： # 排查占用进程（全平台） lsof -i :3000 # 杀死占用进程（替换 <进程PID> 为实际PID） kill -9 <进程PID> # 重启服务 clawdbot gateway restart
6. 模型调用失败
- 故障现象：发送指令后，机器人回复“模型调用失败”；
- 核心原因：API 密钥错误/过期、额度不足（云模型），或本地模型服务未启动；
- 解决方法： 云模型：核对 API 密钥，检查平台额度，重新配置模型；本地模型：启动 Ollama/LM Studio 服务（如 Ollama 执行 ollama serve），重新配置模型地址。
7. 技能无法使用
- 故障现象：调用技能时，回复“技能未启用/执行失败”；
- 核心原因：技能未安装、未启用，或配置异常；
- 解决命令： # 查看已安装技能 clawdbot skill list # 启用技能（替换 <skill-name> 为技能名） clawdbot skill enable <skill-name> # 安装必装技能（若未安装） clawdbot skill install system file network # 重启网关 clawdbot gateway restart
七、日常运维与进阶优化
部署成功后，掌握常用运维命令与进阶配置，可提升 Clawdbot 的稳定性与实用性，适配更多个性化需求。
1. 常用运维命令（速查）
功能需求 | 执行命令 |
|---|---|
重启 Clawdbot 服务 | clawdbot restart |
更新 Clawdbot 到最新版本 | clawdbot update |
查看已安装技能 | clawdbot skill list |
安装新技能（如日程管理） | clawdbot skill install calendar |
卸载无用技能 | clawdbot skill uninstall <技能名> |
修改大模型/Token 配置 | clawdbot config set model.provider claude（claude/openai 二选一） |
停止 Clawdbot 服务 | clawdbot service stop |
查看网关状态 | clawdbot gateway status |
2. 核心配置文件路径（备份/修改必备）
全平台通用核心配置目录：~/.clawdbot，建议定期备份该目录，避免配置丢失。
- 核心配置文件：~/.clawdbot/config.json（含模型、渠道、认证等所有配置）；
- 技能配置目录：~/.clawdbot/skills/（各技能的独立配置文件）；
- 本地数据目录：~/.clawdbot/data/（任务记录、本地缓存等隐私数据）；
- 快速打开配置目录命令：cd ~/.clawdbot && ls（全平台）。
3. 进阶优化建议
- 模型切换：通过 clawdbot config set model.provider claude 切换大模型（claude/openai 二选一），按需调整模型参数；
- 性能优化：限制内存使用，避免占用过多资源，命令如下： clawdbot config set system.memoryLimit 4GB
- 本地模型部署：使用 Ollama 运行本地模型（如 Llama3），无需 API 密钥，隐私更有保障，命令如下： # 安装 Ollama 并运行模型 ollama run llama3 # 在 Clawdbot 中配置 Ollama 地址：http://localhost:11434
- 自定义 Skills 开发：适合开发者，可创建专属技能，命令如下： clawdbot skills create my-skill
- 服务器部署优化：配置监控脚本，异常时自动重启服务；使用 PM2 进程管理器增强稳定性，命令如下： npm install -g pm2 pm2 start "clawdbot gateway" pm2 startup
八、总结
通过本指南，你已掌握 Clawdbot 的全流程部署、配置、运维方法，成功打造了一款 24/7 运行的私人 AI 助手。Clawdbot 的核心优势在于本地部署带来的隐私保护、系统级执行带来的高效便捷，以及全渠道交互带来的灵活体验，无论是新手还是进阶用户，都能根据自身需求灵活配置。后续使用中，建议定期通过 clawdbot update 更新版本，备份核心配置文件，遇到问题可通过日志排查或参考本指南的常见问题部分解决。随着你对 Clawdbot 的熟悉，可安装更多技能、自定义配置，让它真正成为你的专属数字管家，帮你高效处理各类日常任务。
版权所属：SO JSON在线解析
原文地址：https://www.sojson.com/blog/578.html
转载时必须以链接形式注明原始出处及本声明。
如果本文对你有帮助，那么请你赞助我，让我更有激情的写下去，帮助更多的人。
