Clawdbot 本地私有 AI 助手部署实操手册：搭建 7×24 小时可执行任务的智能管家

一、前期准备：硬件基线、环境依赖与前置资源核验

正式部署前完成资源清点，从根源规避依赖缺失、性能不足、权限报错等部署翻车问题。

1.1 硬件参考标准

• 最低基线：2 核 CPU、4GB 内存、磁盘空闲≥10GB，仅支持基础调试、轻量对话
• 推荐规格：4 核及以上 CPU、8GB 及以上内存、磁盘空闲≥20GB，可流畅加载多技能、本地大模型、并发任务
• 长期不间断运行选型：优先云服务器、树莓派、Mac Mini 这类低功耗设备，尽量减少主动关机、休眠，保障服务常驻

1.2 系统平台与依赖版本约束

不同操作系统支持形态不一样，核心组件版本硬性要求不能放宽。

表格

平台适配说明：

• Linux /macOS：原生直接支持，命令通用
• Windows：不支持原生 PowerShell 直跑，必须启用 WSL2+Ubuntu 子系统；仅一键脚本提供 PowerShell 适配版本
• 云服务器：完全兼容，建议内存≥2GB，部署后务必调整防火墙策略

1.3 提前准备密钥与接入凭证

至少准备一套对话渠道凭证 + 一套大模型能力方案（本地模型免 API 密钥）

1. 大模型方案二选一
   • 云端 API：Anthropic Claude3、OpenAI GPT4，提前在对应平台控制台生成 API Key，注意密钥不要带空格、留意余额与过期时间
   • 本地离线模型：Ollama、LM Studio，本地拉起推理服务，全程数据不出本机，隐私性更强，无需外网密钥
2. 交互渠道凭证（至少准备一个）
   • Telegram：通过 @BotFather 新建机器人，拿到 Bot Token
   • WhatsApp、Slack：按平台要求完成设备配对、授权

二、四种部署路线，按需挑选

Clawdbot 提供梯度化部署方式，新手优先一键脚本；服务器选 Docker；想二次开发选源码模式，全部部署路径最终能力完全一致。

路线 1：一键自动化脚本（新手首选）

脚本自动处理环境校验、依赖安装、注册服务，交互式引导配置，上手门槛最低。

• Linux / macOS / WSL2（Ubuntu）

curl -fsSL https://clawd.bot/install.sh | bash
exec bash
clawdbot onboard --install-daemon

• 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，想理清流程）

适合需要自主管控依赖、方便排错的用户，推荐用 nvm 管理 Node 版本，规避全局权限坑。

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
exec bash
# 部署Node22
nvm install 22
nvm use 22
# 安装Clawdbot
pnpm add -g clawdbot@latest
# 进入配置向导、注册常驻服务
clawdbot onboard --install-daemon

路线 3：Docker Compose 部署（服务器长期托管首选）

容器隔离环境，不和主机原有软件、包环境冲突，版本可控、迁移方便。

# 安装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

编辑.env 填入模型密钥、渠道信息、端口等参数后启动：

docker-compose up -d --build

部署完成后浏览器访问 http://localhost:8080 打开管理面板。

路线 4：源码编译部署（开发者、自定义改造场景）

适合需要修改源码、定制功能、抢先体验开发版新特性的用户：

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
npm install -g pnpm
pnpm install
pnpm ui:build
pnpm build
pnpm clawdbot onboard --install-daemon

三、交互式配置向导核心步骤（所有部署方式必经环节）

无论用哪种方式安装，都要执行 clawdbot onboard --install-daemon 进入向导，这是让 AI 具备执行能力、连通聊天渠道的核心环节。

1. 配置模式选择 快速开始：自动填充默认参数，适合快速上手；高级配置：自定义推理参数、端口、访问鉴权策略。
2. 网关模式 Local Gateway：本地设备运行，适合个人自用；Remote Gateway：远端服务器网关，适合多设备跨网访问，需要端口转发。
3. 大模型接入配置 选定服务商，填入密钥或本地推理地址（Ollama 默认 http://localhost:11434）；调整温度、上下文上限，新手保持默认；一定要执行连接测试，确认连通正常再往下走。
4. 访问鉴权 密码认证：简单，适合内网使用；Token 令牌认证：安全性更高，公网暴露服务时优先选。
5. 聊天渠道绑定（至少绑定一个）

• Telegram：@BotFather 拿到 Token，填入向导，绑定后给 Bot 发 /start，收到回复即连通
• WhatsApp：在向导调出配对二维码或者手机号绑定，复用 WhatsApp Web 协议完成连接

6. 功能插件（Skills）选配 插件是 AI 拓展执行能力的核心： 必装基础插件：系统命令、文件读写、网络请求； 推荐选配：日程管理、代码解释器、文档解析、网页检索； 后续增删插件命令：

clawdbot skill install 插件名
clawdbot skill list

7. 常驻守护服务安装 向导最后一步，务必确认安装：Linux/WSL2 注册 systemd 服务，macOS 注册 launchd，实现后台常驻、开机自启。

四、保障 7×24 稳定在线：服务管理、日志、远程访问与安全加固

4.1 服务状态管控命令

表格

状态输出为 active(running) 代表正常运行。

4.2 开机自启配置

# Linux/WSL2
systemctl --user enable clawdbot-gateway

macOS 安装守护进程时自动配置自启，只需要验证状态； WSL2 额外：Windows 任务计划程序新建任务，开机自动拉起 WSL 与服务，避免 Windows 重启后子系统休眠停机。

4.3 日志查看，定位异常

优先使用程序自带日志命令，通用性最强：

clawdbot log --follow

系统底层日志：

# Linux/WSL2
journalctl --user -u clawdbot-gateway -f
# macOS
log stream --predicate 'process == "clawdbot-gateway"'

4.4 远程访问两种方案

1. 端口转发：路由器把 3000 端口映射到本机，公网直接访问 Web 面板；
2. Tailscale 组网：没有公网 IP 的首选，虚拟局域网内安全访问，不用暴露端口到公网。

4.5 安全加固建议（公网部署强烈推荐）

# 所有高危操作强制二次确认
clawdbot config set security.confirmAllActions true
# 限制仅内网网段访问面板
clawdbot config set network.allowedIps "192.168.1.0/24"
# 防火墙放行端口示例（ufw）
sudo ufw allow 3000/tcp
sudo ufw enable

按需关闭不用的插件，缩小攻击面；定期执行 clawdbot update 更新版本，接收安全补丁。

五、上线验收：三步验证部署成果

1. 网关状态校验

clawdbot gateway status

返回 Running 代表网关正常。 2. Web 管理面板：浏览器打开 http://localhost:3000，使用设置好的凭证登录。 3. 渠道功能实测（Telegram/WhatsApp） 发送指令测试：

• 文件能力：新建test文件夹，确认提示后回复确认，检查本地目录；列出当前目录文件
• 代码能力：写一段简易Python脚本，验证代码解释插件正常运行

三项全部正常，代表私有 AI 管家部署完成。

六、高频故障速查

1. Node 版本报错 日志提示 node 版本不足 22，用 nvm 重新切换版本，参考前文 nvm 部署命令。
2. Permission denied 权限报错 npm 全局目录权限冲突，把 npm 全局路径迁移到用户目录，避免 sudo 污染环境。
3. 聊天渠道离线、消息无响应 核对 Token / 密钥、排查网络连通性；WhatsApp 重新扫码配对；执行 clawdbot restart 重启网关。
4. 守护进程启动失败

clawdbot service install --force
clawdbot service start
clawdbot log --error

5. 端口占用，面板打不开

lsof -i :3000
kill -9 进程号
clawdbot gateway restart

6. 调用大模型失败 云端 API：核对密钥、余额、限流；本地 Ollama：确认 ollama serve 已经启动，地址配置无误。
7. 插件调用失败

clawdbot skill list
clawdbot skill enable 插件名
clawdbot skill install system file network
clawdbot gateway restart

七、长期运维清单与进阶玩法

7.1 运维速查命令汇总

clawdbot restart                # 重启整套服务
clawdbot update                 # 升级程序
clawdbot skill list             # 查看已装插件
clawdbot skill install calendar  # 安装日程插件
clawdbot skill uninstall xxx    # 卸载插件
clawdbot service stop           # 停止服务
clawdbot gateway status         # 网关状态

7.2 配置备份路径

所有配置统一放在 ~/.clawdbot，定期备份这个目录，防止重装、换机器时配置丢失。

• 主配置：~/.clawdbot/config.json
• 插件配置：~/.clawdbot/skills/
• 数据缓存与任务记录：~/.clawdbot/data/

cd ~/.clawdbot && ls

7.3 进阶优化方向

• 资源管控：限制最大内存占用

clawdbot config set system.memoryLimit 4GB

• 离线本地模型：Ollama 拉起 Llama3 等模型，完全脱离外网 API

ollama run llama3

• 自研插件：

clawdbot skills create my-skill

• 服务器增强保活：搭配 PM2 托管进程，进程崩溃自动拉起

npm install -g pm2
pm2 start "clawdbot gateway"
pm2 startup

八、收尾

这套方案落地之后，你将拥有一个可以读写本机文件、执行脚本、联网检索、跨消息渠道交互的私有化 AI 助手。它的核心优势在于数据可控、权限可精细管控、可以持续后台运行。 日常维护两件事：定期升级版本、备份 .clawdbot 配置目录；遇到异常优先看内置日志定位问题。按需叠加插件、接入本地大模型，逐步打造成贴合你工作流的自动化管家。