如果你手上有一台在抽屉里吃灰的树莓派或者正盯着购物车里的树莓派5犹豫要不要下单这篇部署笔记应该能帮上忙。我的目标很直接把树莓派变成一台7x24小时在线的AI助手。这里说的AI助手不是那种打开网页一问一答的聊天框而是能接收指令、按流程执行、调用外部工具、定时触发任务的AI代理程序。实现这套能力我用的是OpenClaw这个开源Agent框架再从本地或局域网里接入大模型算力把部署、配置、调优、稳定性这几个环节完整走了一遍。文章不会只给你安装命令列表。我会把每一步的选型理由、踩坑过程、实测数据都交代清楚尽量让零基础的人也敢跟着操作同时让有Linux和Docker经验的人也能从中找到有用的调试思路。1. 为什么我的选型是“树莓派 OpenClaw”而不是云服务器或主力电脑1.1 树莓派做AI助手底座的硬性优势树莓派这个设备最被低估的点不是算力而是“存在方式”。一台树莓派5的峰值功耗在5到10瓦左右待机时更低一年到头电费加起来也就一杯奶茶钱。相比之下云服务器按年续费是几百到上千的成本主力电脑跑24小时则既费电又占资源。树莓派还可以直接扔在路由器旁边、电视柜角落没有噪音没有风扇狂转的焦虑前提是你把散热做好非常适合当“家里永远不关机的那个小盒子”。另外一个容易被忽略的价值是数据边界。AI助手如果要对接家里的智能家居、内网服务、个人文件它必然要接触到大量隐私数据。把这些数据放到自己家里的设备上处理比丢给云端API心里踏实得多。尤其是做本地知识库、家庭监控摘要、自动化脚本执行这类的场景数据不出局域网这个底线会给你带来很大的自由度。1.2 OpenClaw这类Agent框架到底解决了什么问题如果你用过ChatGPT之类的对话模型会有一个很明显的痛点大模型本身只能“说”不能“做”。你想让它帮你定时去抓取某个网页、处理文件、调用接口、跑一条命令它只能告诉你“你可以这样做”然后就没有然后了。OpenClaw这类Agent框架做的事情就是在模型和真实世界之间架一座桥。框架负责接收任务、拆解步骤、调用配置好的工具技能Skill最后把结果返回给模型做下一步判断。打个比方大模型是大脑OpenClaw是手和脚Skill则是你交给它的各类工具。没有这套中间层模型再强也没法替你执行。这里有个容易混淆的概念Agent和“聊天机器人”的本质区别在于闭环聊天机器人答完即止Agent要负责把任务做完并反馈结果。把Agent框架部署在树莓派上本质上是给自家网络里的各种设备配了一个“会安排活儿的管家”。1.3 什么样的场景才值得这么折腾我承认不是所有人都需要一台自建的AI代理。这个方案最适合下面几类场景家庭内网自动化每天定时抓取局域网里NAS的状态、温度传感器数据、设备的在线情况汇总成报告推给手机。跨服务协调AI助手帮你整理邮件、操作日历、调用家里智能设备接口或者在设备故障时自动执行重启脚本。隐私敏感的个人知识库基于本地语料做检索增强问答不把文档送出家门。纯粹想学习Agent开发与部署链路树莓派是成本最低的练手平台踩坑成本几乎为零。如果你只是想要一个“手机上的智能聊天应用”那真的没必要看这篇文章。但如果你想拥有一个永远在线、还能替你动手干活的设备这个组合目前是性价比最高的。2. 动手前的系统底座Raspberry Pi OS精简安装与远程通道准备2.1 镜像选择与刷写要点系统层面我推荐Raspberry Pi OS Lite64位版本不选带桌面的完整版。理由很简单OpenClaw跑的是服务端进程不需要图形界面。桌面环境不仅多占用几百MB内存还会引入一堆无关进程对稳定性和功耗都有负面影响。Lite版本身就是长期支持版本更新节奏稳定适合做无人值守服务器。刷镜像用官方的Raspberry Pi Imager最省事。这里有个非常实用的细节Imager在写卡前可以点击设置按钮直接预配置hostname、开启SSH、填写WiFi密码。不要小看这几项配置它能让树莓派第一次通电后就自动联网、可远程登录省去接显示器键盘的麻烦。提示SD卡建议选A2等级的U3卡写入速度直接决定后续pip install和日志写入的体验。有条件的话我更推荐用USB3.0移动固态硬盘或树莓派5的NVMe子板做启动盘后面章节会专门说为什么。2.2 开机后的基础调校软件源、Swap和静态IP第一次SSH登录进去先做三件事。第一把软件源换成国内镜像源。具体做法是编辑/etc/apt/sources.list将默认的deb.debian.org地址替换成你所在地区访问速度快的镜像源地址。树莓派OS新版使用了/etc/apt/sources.list.d/下的文件管理来源所以raspi.list里的源也要一并处理。换完之后sudo apt update速度会有质的提升。第二扩大Swap分区。树莓派的内存虽然可以到8GB甚至16GB但编译一些包含C扩展的Python包时仍然可能OOM。我习惯把/etc/dphys-swapfile里的CONF_SWAPSIZE改成2048或更高执行sudo systemctl restart dphys-swapfile生效。这一步是为了后面pip install大轮子时留出缓冲。第三给树莓派一个固定IP。你当然可以在路由器后台做DHCP静态绑定但我更建议直接在树莓派上配置静态地址防止路由器重启后IP漂移。编辑/etc/dhcpcd.conf加上interface eth0 static ip_address192.168.1.100/24 static routers192.168.1.1 static domain_name_servers192.168.1.1 223.5.5.5注意你家里的网段可能不同记得改成你自己的实际值。改完重启网络服务后后续所有服务配置都指向这个固定IP省心很多。2.3 免密SSH登录与时区修正树莓派作为7x24小时设备至少应该做到免密登录。在电脑上执行ssh-keygen生成密钥后用ssh-copy-id把公钥推到树莓派之后登录就不需要输密码。同时把/etc/ssh/sshd_config里的PasswordAuthentication设为no降低被爆破的风险。时区和定时任务直接相关。Agent框架的Skill经常要用到cron式的定时触发如果系统时区不对任务执行时间会和你预期差出好几个小时。执行sudo timedatectl set-timezone Asia/Shanghai这类命令切换到你的本地时区再用timedatectl确认时间同步正常。3. 部署OpenClaw主程序源码安装全流程与三种“接入大脑”的姿势3.1 依赖准备与代码拉取OpenClaw这类Python系框架在树莓派上最常见的安装方式是源码部署。容器化方案不是不行但ARM架构镜像体积大、嵌套层多对SD卡容量和内存占用都不友好所以我推荐裸机Python环境。先安装基础依赖sudo apt update sudo apt install -y python3 python3-venv python3-pip git build-essential然后是克隆代码仓库。OpenClaw的版本迭代很快安装前先去官方仓库页面看一眼README里的版本说明确认当前分支和Python版本要求。这里说的步骤是通用流程不同版本的命令细节可能略有差异以你拉取到的仓库最新文档为准。cd ~ git clone https://your-openclaw-repo-url/OpenClaw.git cd OpenClaw python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt这里有一个树莓派特有的关键点部分依赖包比如某些数据序列化或HTTP相关的库在PyPI上没有预编译的ARM64 wheelpip会现场用gcc编译。整个过程在树莓派4上可能长达十几分钟CPU温度会明显升高。所以我在上一节反复强调先加Swap、装build-essential不然你很可能在进度条走到一半时遇到Killed这种问题特别让人崩溃。3.2 配置文件里的核心字段长什么样OpenClaw的主配置文件负责定义两件事模型从哪里来以及启用了哪些技能。不同分支的配置格式存在差异但结构思路是相通的下面是我项目中实际使用过的配置片段结构可以按你的版本适当调整agent: name: home-assistant backend: type: ollama base_url: http://127.0.0.1:11434 model: qwen2.5:3b temperature: 0.2 max_tokens: 2048 skills: - name: shell_executor enabled: true - name: daily_report enabled: true schedule: 0 8 * * *temperature这里我建议调低到0.2甚至0.1。Agent任务和聊天不一样聊天希望模型有灵气Agent执行任务希望模型“听话”调低温度能明显减少脚本执行的随机出错概率。max_tokens也不用给太高Agent的中间产物通常控制在2K以内就够了。3.3 三种算力接入方案的实测取舍很多朋友问过一个问题这类Agent框架是不是只能用云端API其实不是。OpenClaw的backend层是抽象出来的你可以接任何兼容协议的推理服务。我在树莓派上实测过三种方案结论如下方案隐私性月成本推理速度安装难度推荐指数树莓派本机跑Ollama 3B小模型最高数据不出设备仅电费约10-25 token/s慢但可用低适合离线私有场景局域网GPU服务器 Ollama高不出家庭网络电费稍高50-150 token/s接近商业体验中最推荐的家庭方案云端API最低数据出网按量计费极快最低适合临时测试或能力验证树莓派5本机跑qwen2.5:3b的量化版生成速度大概在每秒十几个token用来做定时摘要、简单脚本执行还说得过去但指望它主导多轮复杂对话会等到怀疑人生。更合理的做法是树莓派上只跑OpenClaw框架算力交给局域网里另一台有NVIDIA显卡的机器通过Ollama的HTTP接口暴露给树莓派。这样OpenClaw进程本身只占树莓派几百兆内存稳得很算力却一点不打折。云端API方案我只有在出差、局域网GPU不可用的时候才临时切一下。这里也回应那个常见疑问OpenClaw不是只能接APIbackend类型改成ollama、指向本地地址即可配置文件里甚至不需要填任何api_key字段完全走内网调用。4. 让它“自动干活”Skill技能体系与一个真实可跑的小任务4.1 Skill机制是怎么工作的把大模型接上只是第一步真正让AI助手产生价值的是Skill技能体系。你可以把Skill理解为插件每一个Skill对应一种能力执行Shell命令、抓取网页、读写文件、调用摄像头、发送消息通知、对接智能家居接口等等。Agent的工作方式是循环式的。收到任务后框架让模型判断“这个任务需要调用哪个Skill、传什么参数”模型输出一段结构化指令框架解析指令并调用对应的Python函数拿到执行结果后再交还给模型分析。这个循环会一直进行到模型认为任务完成。理解了这个机制你就会明白两个关键点。第一模型本身不需要“会做”某件事它只需要“知道”有某个Skill可以做这件事。所以给模型配备好用的工具描述比模型参数大小更影响效果。第二Skill的返回信息要尽量结构化纯文本没关系但要有明确的结果和状态字段模型才能做出正确判断。4.2 实战一个定时任务每天早上抓取内网状态并推送摘要纸上谈兵没意思直接上一个我真实跑着的Skill示例。任务目标每天早上8点让AI助手查看家里NAS的磁盘使用率、主路由器在线设备数、树莓派自身CPU温度然后把这三项数据整理成一段摘要文字推送到我的手机。实现思路分三层。第一步写一个Skill脚本负责收集数据并生成一个简单的JSON结构。第二步在OpenClaw的Skill配置里注册这个脚本并声明它的功能描述方便模型“知道”何时该调用它。第三步配置定时触发让框架在每天8点主动发起这个任务。Skill脚本核心逻辑示意Pythonimport json import subprocess def collect_system_status(): cpu_temp subprocess.check_output( [cat, /sys/class/thermal/thermal_zone0/temp] ).decode().strip() disk_usage subprocess.check_output( [df, -h, /] ).decode().strip().split(\n)[-1] # 这里可以继续调用NAS API、路由器API等 return json.dumps({ cpu_temp_celsius: int(cpu_temp) / 1000, disk_root: disk_usage, })在Skill配置里你要给模型一段准确的描述例如“获取树莓派自身CPU温度和根分区磁盘占用情况返回JSON字符串”模型在遇到相关诉求时才会正确调用。4.3 调试Skill的实用套路Skill开发最容易踩的坑是你以为模型能理解你的代码实际上它经常传错参数。我总结出一个固定调试顺序先脱离模型直接命令行执行Skill脚本确认返回数据格式正确再通过框架的控制台手动触发一次观察框架是否正确解析了模型输出最后才配置定时任务让它自动驾驶。调temperature的作用在这里会非常明显。同样是“调用Shell命令”的任务temperature为0.8时模型可能突然决定给你加一段解释文字破坏指令格式调到0.1之后输出稳定得像是机器人。记住Agent场景下让模型“更有创造性”基本都是反效果。5. “24小时在线”的硬功夫systemd守护、开机自启与掉电恢复5.1 让OpenClaw作为系统服务常驻用nohup或者screen跑OpenClaw开机不会自动拉起来程序崩了也没人管。正确做法是把它注册成systemd服务。下面是一个我在用的unit文件模板可以存到/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Userpi WorkingDirectory/home/pi/OpenClaw ExecStart/home/pi/OpenClaw/.venv/bin/python -m openclaw start Restartalways RestartSec10 EnvironmentPYTHONUNBUFFERED1 [Install] WantedBymulti-user.target关键看两个参数。Restartalways表示任何异常退出都会自动拉起这是7x24小时设备的心脏。RestartSec10是重启前的等待秒数防止进程不断崩溃时疯狂重启刷日志。Afternetwork-online.target配合Wants确保开机时网络已经就绪再启动OpenClaw避免第一次请求模型接口时网络还没起来。保存后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclawenable --now是一步到位的组合拳设置开机自启并立即启动。以后任何时候想查看状态用systemctl status openclaw想看实时日志用journalctl -u openclaw -f。5.2 日志、温度与SD卡寿命三个必须提前做的动作24小时在线最容易被低估的威胁不是程序崩溃而是小问题长时间累积。第一是日志膨胀。systemd默认的日志存储上限其实不算高但OpenClaw的调试日志如果长期不清理依然可能写满根分区。在/etc/systemd/journald.conf里设置SystemMaxUse200M然后重启systemd-journald日志占用就永远可控了。第二是散热。树莓派5在持续跑Agent进程加编译任务时CPU温度可以轻松冲到80度以上。别指望裸片靠空气散热就能压住加一个主动散热风扇壳或者至少贴好散热片。我自己实测温度从85度降到60度左右之后SD卡的读写稳定性也明显变好设备死机频率大幅下降。你可以用vcgencmd measure_temp随时查看温度。第三是SD卡寿命。Linux系统对SD卡的频繁小文件写入非常不友好尤其是Agent框架的会话记录、日志、临时文件都在写卡。我的解决方案是系统依然从SD卡启动但把OpenClaw的整个工作目录和日志目录挂到内存盘或者外置SSD上。如果预算允许直接让树莓派从SSD启动是最彻底的解决办法这样“掉电损坏文件系统”的概率也会低很多。5.3 断电与异常重启后的自愈树莓派作为家用设备最大的敌人是家里有人不小心碰掉电插头或者小区突然跳闸。断电本身不可怕可怕的是断电后文件系统损坏、服务起不来、IP变了找不到设备。自愈策略分三档。第一档是SD卡文件系统自动修复树莓派OS默认在启动时会检查文件系统遇到非正常关机后的标记会自动进入修复流程一般情况下等待片刻就能正常进入系统。第二档是服务的自启前面配置的systemd服务会在系统起来后自动把OpenClaw拉起来。第三档是异常状态的自我监测在Agent里加一个Skill定期检查系统时间、关键服务状态和IP地址一旦发现异常就把诊断信息推送出来。注意如果你发现树莓派断电重启后卡在文件系统检查的界面可以检查/etc/fstab里有没有把errorsremount-ro这类参数配置到根分区或者直接把启动介质迁移到SSD。SD卡在使用两三年后本来就是消耗品出现这种情况不要怀疑是自己操作错了。6. 我踩过的坑和实测数据帮你省下两到三天的排查时间6.1 编译依赖时的“内存不足”窘境装Python依赖看起来是流水线操作但树莓派上绝不是。我第一次在树莓派4B上执行pip install -r requirements.txt跑到某个包含C扩展的依赖时终端直接卡死SSH断开过去一看进程被OOM Killer干掉了。树莓派的内存管理很老实不会像台式机那样疯狂换页内存不够就杀进程。解决方案就是我前面埋下的伏笔先扩容Swap。如果Swap也救不了就把requirements.txt里的依赖分组安装每装完一组确认没报错再进行下一组。还有一个技巧是优先尝试pip download到本地手动检查哪些包有ARM64的wheel手动装那些需要编译的包时耐心等待不并行安装能减少OOM概率。6.2 模型推理速度的真实数据本地推理速度直接决定Agent的可用性我实测的数据给你做个心理建设。树莓派58GB版跑Ollama上的qwen2.5:3b量化模型单并发生成速度约为15到20 token/s。这个速度做定时汇总、短命令调用是勉强能用的但一次生成2000字的任务可能要等两分钟以上。树莓派4B则只有大概5到8 token/s基本只适合“一句话回答”级别的任务。所以我的明确建议是如果你是认真的想用它干活别指望靠树莓派裸跑模型获得好的体验老老实实接局域网GPU。GPU机器上同样的3B模型能跑到80到120 token/s7B模型也能有四五十这个差距是代差级的。6.3 设备跑几天后突然“变哑巴”的排查链路我遇到过最诡异的现象是OpenClaw跑了两三天后状态栏显示服务正常但问它什么都是“无法连接模型服务”。排查过程爬了挺久最后确定是树莓派的无线网卡进入了省电模式在低流量状态下自动断开WiFi而服务本身没有感知到网络异常。解决办法有三个第一在/etc/NetworkManager/conf.d/下创建一个配置文件禁用WiFi省电模式第二给OpenClaw服务加上Restartalways网络恢复后进程会自动重连第三如果你有以太网口直接插网线家庭服务器这类的角色能用有线连接就不要纠结无线。排查这种问题有个通用思路先看systemctl status openclaw确认进程再journalctl -u openclaw -n 50看日志最后curl对应的模型接口确认网络连通性一层层排除。6.4 版本兼容性Skill目录、配置文件与模型名的小坑OpenClaw这种快速迭代的项目最坑的不是代码多难而是GitHub上README跟你拉下来的代码版本经常不同步。我曾经按文档截图配置了Skill目录结果框架根本不识别最后发现新版改了默认目录结构。遇到这种问题唯一可靠的办法是进项目源码里找settings.py或用grep搜配置加载逻辑看它到底读哪个路径。模型名也要格外小心。Ollama本地拉取的模型名必须和配置文件完全一致多一个标签后缀或者少一个版本号请求都会直接报错。我建议启动OpenClaw之前先单独用ollama list确认模型确切名称再复制粘贴到OpenClaw配置里不要手打。最后一个不算坑但值得说的问题OpenClaw支持对接的模型后端繁多但不同后端的参数风格差异很大。换模型后端时不要只改base_url模型名称规范、上下文长度上限、工具调用方式都可能不同。每次切换后跑一个最长链路的任务做回归测试是最稳妥的习惯。从开始刷系统到整个Agent稳定跑了几天我最大的感触是这套方案真正考验人的不是单个环节有多难而是你有没有把“在线”两个字当回事。树莓派这种小设备只要把系统底座打好、服务守护配好、日志管住剩下的知识积累完全能支撑你把它越用越顺手。希望这篇踩坑笔记能让你少折腾几个通宵直接体会到自建AI助手的乐趣。