折腾了这么多年自托管服务我越来越觉得真正好用的 AI 助手不是装个 App 那么简单的。你需要的其实是一个能 7x24 小时在线、能接入你常用的聊天工具、能自由切换云端模型和本地模型的服务端机器人。ClawdBot 就是干这个的。这篇 ClawdBot 安装指南我会从零开始把环境准备、配置项、启动守护、问题排查全部过一遍保证你照着做就能把 ClawdBot 跑起来得到一个真正属于自己的 24/7 私人 AI 助手。它适合有一定服务器基础、但又不想看一堆英文文档就动手折腾的人如果你完全没接触过 Docker 和命令行这篇文章也能带着你一步一步来不会让你卡在第一步。1. 为什么选 ClawdBot先把这个项目的定位和价值看清楚1.1 ClawdBot 不是聊天页面而是常驻服务端的调度中枢市面上 AI 工具非常多但大部分是给人“打开网页点一点”的。ClawdBot 不一样它是一个常驻在你自己机器上的服务进程像一个 7x24 小时不休息的“机器人管家”你通过 Telegram、Web 页面或者企业聊天工具给它发消息它把请求交给配置好的大模型处理再把结果通过同一个渠道回给你。拆开看ClawdBot 在架构上分四层接入层负责对接各种消息渠道和管理界面调度层负责决定这次请求该用哪个模型推理层负责真正调用云端 API 或者本地模型存储层负责把会话记录、日志和用户配置持久化下来。这个分层非常关键它决定了 ClawdBot 不是一个“套壳客户端”而是一个可扩展的 AI 基础设施。我打个比方ClawdBot 像一个公司的前台。你各种渠道的消息都是“来访的客人”前台先接待再根据客人要办的事分给对应部门。部门就是各种模型云端 API 是外包专家本地模型是自家团队。1.2 适合谁用三个能直接抄作业的场景第一类是个人知识助理。你私聊它丢一篇长链接让它帮你总结并生成要点或者设置每天早上的定时任务让它把行业新闻、邮件摘要整理好推送到你的聊天工具里。这比打开各种 App 挨个看高效得多。第二类是家庭或小团队共享助手。一个 ClawdBot 实例注册多个用户每个人有独立的会话记录管理员可以限制谁能用、一天能用多少次。这相当于把“一个人私聊 ChatGPT”升级成“一个小团队共用的 AI 服务台”成本比挨个开会员划算。第三类是技术玩家的模型网关。热搜词里常提“AI 代理助手加本地模型”ClawdBot 正好就是这个定位。你可以同时配置多家模型服务商的 API 和本地 Ollama 模型再根据消息类型、用户级别、模型负载做路由。比如白天用云端大模型保效果晚上用本地模型省钱保隐私。这种玩法才是这类项目真正的价值所在。2. 环境准备跑 ClawdBot 需要什么底子2.1 硬件配置下限与推荐部署方式先说结论如果你只跑 ClawdBot 本体、不跑本地模型2 核 CPU、2GB 内存的小机器就够了树莓派、老笔记本、NAS、云主机都能带得动。如果你要跑本地模型那配置就得看模型体积。我做过一张配置对照表基本可以照着选使用场景CPU/内存要求是否需要 GPU推荐部署方式仅调度云端模型 API1-2 核 / 1-2GB不需要Docker Compose 或裸机跑 7B 以下本地模型4 核 / 8GB建议有 6GB 显存N 卡优先Docker Ollama跑 13B-33B 本地模型8 核 / 16GB必须至少 10GB 显存独立 GPU 服务器多用户/多模型生产使用4 核 / 8GB看本地模型情况systemd Docker操作系统的选择上Linux 最顺手Ubuntu 22.04/24.04 我都试过。macOS 可以用 Docker Desktop 跑Windows 建议用 WSL2。如果你是群晖、威联通用户直接用 Docker 套件装镜像也完全没问题。2.2 Docker 和 Python 运行时怎么装ClawdBot 官方文档提供了两种方式Docker 镜像部署和源码部署。我个人强烈建议 Docker原因有三点依赖隔离不会污染宿主系统升级时只需替换镜像配合 systemd 和 docker compose 重启恢复非常方便。先确认 Docker 是否就绪执行docker --version docker compose version如果没装Ubuntu 上可以这样快速安装apt update apt install docker.io docker-compose-plugin systemctl enable --now docker源码部署方式则要求 Python 3.10 或更高版本然后创建虚拟环境git clone ClawdBot 官方仓库地址 clawdbot cd clawdbot python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt仓库地址和具体依赖清单以官方 README 为准我这里写的是通用流程。你如果之前装过 Python 3.11/3.12也可以直接用兼容性基本没问题。3. 保姆级配置把 ClawdBot 调通的关键步骤3.1 第一步复制 .env 配置文件ClawdBot 采用环境变量管理配置这是所有自托管服务里最常规、也最不容易出错的做法。刚拉完仓库或镜像后先把示例配置复制成正式配置cp .env.example .env打开 .env 后你会看到密密麻麻的参数。别慌真正必须改的只有几项。我的原则是开荒阶段只改必填项跑通了再回头调优可选参数。所有带_KEY、_SECRET、_TOKEN的字段都属于敏感信息千万不要提交到 Git 仓库也别截图发到群里。提示建议把.env文件的权限收紧执行chmod 600 .env。我见过很多教程忽略这一步一旦服务器被扫到密钥泄露就是分分钟的事。3.2 第二步接入云端模型 APIClawdBot 本身不生产模型它负责调度模型。所以要让它“开口说话”第一步是配置一个模型来源。在 .env 里通常会看到类似这样的字段# 模型服务商类型openai / anthropic / dashscope / zhipu / deepseek 等 MODEL_PROVIDERdeepseek # 模型名称例如 deepseek-chat MODEL_NAMEdeepseek-chat # 模型服务商提供的 API Key MODEL_API_KEYsk-xxxxxxxxxxxx # 可选的 API Base URL保留默认即可 MODEL_BASE_URL配置逻辑很简单MODEL_PROVIDER决定 ClawdBot 用哪种协议去调模型MODEL_API_KEY是你在模型服务商官方平台申请的密钥MODEL_NAME对应你实际要用的模型版本。申请 API Key 时记得在服务商后台配置好额度限制和 IP 白名单这是最基本的安全习惯。这里要特别说明一下“AI 代理助手”这个词ClawdBot 这一类项目确实可以叫 AI 代理助手但此“代理”是模型调度代理的意思——它把你的请求转发给不同的模型服务商而不是网络层面的代理。论文里、官方文档里说的都是这个意思别误解。配置好之后你可以先用 curl 验证一下 Key 是否有效、网络是否可达再启动 ClawdBot。curl 模型服务商兼容接口地址 \ -H Authorization: Bearer $MODEL_API_KEY \ -d {model:MODEL_NAME,messages:[{role:user,content:ping}]}能正常返回一段文本就说明模型通道是通的。3.3 第三步接入本地模型Ollama 实战接入本地模型是很多人部署 ClawdBot 的核心目的核心原因是数据隐私和长期成本。本地模型的安装我用 Ollama 举例因为它对新手最友好。第一步安装 Ollamacurl -fsSL https://ollama.com/install.sh | sh第二步拉取一个适合你硬件的模型。以 7B 档位的通义千问为例ollama pull qwen2.5:7b第三步确认服务在监听ollama serve curl http://localhost:11434/api/tags最后回到 ClawdBot 的 .env把模型来源切到本地MODEL_PROVIDERollama MODEL_NAMEqwen2.5:7b OLLAMA_BASE_URLhttp://localhost:11434如果你是用 Docker 跑 ClawdBot这里有个巨坑容器里的localhost和宿主机不是同一个网络。Docker 容器要访问宿主机的 Ollama得把地址写成http://host.docker.internal:11434macOS/Windows 桌面版支持或者直接写宿主机局域网 IPOLLAMA_BASE_URLhttp://192.168.1.10:11434本地模型接入后建议做一次模型切换测试让 ClawdBot 先用云端模型回一条“你是谁”再切到本地模型回一条对比延迟和回答质量。不同模型的差异感受会比看任何评测都直观。3.4 第四步绑定消息渠道ClawdBot 最舒服的使用方式不是蹲在服务器前看命令行输出而是把它绑到你每天都在用的聊天工具里。以 Telegram 为例流程是这样先找 BotFather 创建一个 Bot拿到 token。然后把 token 填进 .envTELEGRAM_BOT_TOKEN123456:ABC-DEF... TELEGRAM_ALLOWED_USER_IDS你的用户ID TELEGRAM_ENABLEtrueALLOWED_USER_IDS这个白名单一定不要漏否则你的机器人会被全网用户玩坏。获取自己 Telegram 用户 ID 最简单的办法是私信 userinfobot。其他渠道的配置逻辑大同小异无非是“获取平台凭证”加“填写回调地址”。ClawdBot 同时支持多个渠道你可以把 Telegram 用于个人助理、钉钉用于团队协作、Web 控制台用于后台管理。一个后端多个前端数据还互通这种体验比较接近商业产品的形态了。提示如果渠道配置的是异步消息回调注意在 ClawdBot 后台的访问地址里填写公网可达的地址并配置好 HTTPS。很多渠道平台要求 Webhook 地址必须带证书临时自签名证书会被直接拒绝。4. 启动、守护与 24/7 运行4.1 首次启动验证链路配置填完了接下来启动。用 Docker Compose 的方式最省心docker compose up -d tail -f logs/ClawdBot.log日志里出现“service started”或“bot is running”之类的字样说明进程起来了。别高兴太早还要完成三件事才算稳第一给 Bot 发一条普通消息等回复第二检查回复是否走通了“消息渠道 - 调度层 - 模型 - 回传”的完整链路第三发一条定时任务指令看它能否按预定的 cron 表达式执行。注意看定时任务触发时日志里有没有记录任务 ID方便以后排查。如果你的部署环境开了防火墙记得把 ClawdBot Web 控制台的端口放行但千万别把端口直接暴露到公网自己用就套个简单认证别裸奔。4.2 systemd 守护与开机自启很多新手喜欢nohup python main.py 这样挂着进程一崩就彻底失联重启服务器后忘记手动拉起又跑一趟机房。24/7 服务必须用守护进程管理。nohup不是不能用而是不足以应对“崩溃自动拉起”“开机自动启动”这类现实需求。systemd 功能强且天然具备这些能力。源码部署版的服务文件写成一个 systemd unit[Unit] DescriptionClawdBot AI Assistant Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Userroot WorkingDirectory/opt/clawdbot ExecStart/opt/clawdbot/.venv/bin/python main.py Restartalways RestartSec10 EnvironmentFile/opt/clawdbot/.env [Install] WantedBymulti-user.targetDocker Compose 部署版也可以让 systemd 来管Unit 是这样的[Unit] DescriptionClawdBot Docker Compose Requiresdocker.service Afterdocker.service [Service] Typeoneshot RemainAfterExityes WorkingDirectory/opt/clawdbot ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down [Install] WantedBymulti-user.target然后统一用这两条命令启用并启动systemctl daemon-reload systemctl enable --now clawdbot我现在所有自托管服务都是用这套玩法nohup 基本退役了。4.3 日志监控与资源管理服务跑起来之后日常运维主要就两件事看日志和盯资源。源码部署版看日志用这个journalctl -u clawdbot -fDocker 部署版则是docker logs -f clawdbot docker stats日志多了之后要记得轮转Docker Compose 里加logging配置services: clawdbot: logging: driver: json-file options: max-size: 50m max-file: 3这样日志不会把磁盘撑爆。如果搭配 Grafana 或 Prometheus 做指标监控也不是不行但个人用有点重我建议先把手动排查流程跑熟再考虑上监控。5. 常见问题与避坑实录5.1 问题速查表把我在部署过程中遇到过的、以及被朋友反复问到的问题整理成了一张速查表照着排查能省不少时间症状可能原因解决办法容器一直重启.env 缺少必填项或 Key 格式不对检查必填项是否填完docker logs看具体报错发消息没回复消息渠道 Webhook 未公网可达或白名单不对检查 Bot token、ALLOWED_USER_IDS、HTTPS 回调地址提示 401 / 认证失败API Key 过期、IP 白名单挡了出口 IP重新生成 Key把服务器出口 IP 加白名单日志里报“timeout”模型通道网络不稳定或服务商限流检查网络连通性降低请求频率换本地模型本地模型响应特别慢显存不足或推理参数没调换更小的量化模型降低 concurrent 并发数定时任务不执行时区不对导致 cron 匹配错乱确认 TZAsia/Shanghai 并重启服务重启后会话全丢没有持久化数据卷确保 Docker volume 或本地存储目录已被挂载CPU 长期 100%会话被死循环任务占用或模型推理过载限制任务超时时间拆分独立 worker 进程5.2 我踩过最深的三个坑坑一数据卷没有持久化。最早我用 Docker 跑 ClawdBotdocker compose up -d 一把过还很兴奋。结果后来更新镜像容器一删会话记录、白名单配置全没了瞬间回到解放前。现在我会在 compose 文件里强制挂载数据目录volumes: - ./data:/app/data坑二本地模型并发设太高把服务器搞 OOM。7B 模型本来就吃显存我一上来把并发调到 16结果整个机器直接卡死只能强制重启。后来把本地模型的并发数老老实实调到 2云端 API 的并发逻辑和本地模型分开配置才稳定下来。运行本地模型前建议先执行ollama ps随时观察模型占用内存情况OOM 前一般有预兆。坑三时区没设置定时任务全错乱。有一次我发现每天早上 8 点的新闻摘要一直不推查了半天才发现容器时区是 UTC我配置的 8 点其实是 UTC 8 点换成上海时间已经是下午了。解决很简单在 .env 里加一行TZAsia/Shanghai然后重启服务。所有定时任务都对齐你手机上的时间再也不会错乱了。我个人折腾下来最大的体会是ClawdBot 这种项目的价值不在于“又多了一个能聊天的东西”而在于它把零零散散的模型能力统一成了一个可以随时调用的基础设施。你不需要记住每个模型在哪调、每个渠道怎么接一个 ClawdBot 全部搞定。如果你已经把它跑通了建议下一步试试接入更多渠道、把本地模型和云端模型的路由规则做精细一点甚至可以把它接到智能音箱、NAS 或者自动化工作流里。折腾的过程本身就是最有意思的部分。希望这篇保姆级安装指南能帮你少走点弯路动手去搭一个真正属于你自己的 24/7 私人 AI 助手。