树莓派部署OpenClaw AI助手：计算分离架构与局域网模型推理实践

1. 项目概述：在树莓派上部署一个“瘦身”的AI助手

如果你和我一样，喜欢折腾家里的各种设备，想把闲置的树莓派利用起来，同时又有一台性能更强的电脑（比如你的主力台式机或笔记本）来跑大模型，那么这个项目就是为你量身定做的。openclaw-rpi这个项目，本质上是一个“部署与运维工具包”，它的核心目标非常明确：让树莓派运行 OpenClaw 的智能体（Agent）和仪表盘（Dashboard），而把最吃资源的模型推理任务，甩给局域网（LAN）里另一台运行 Ollama 的电脑。

这解决了几个很实际的痛点：树莓派算力有限，跑不动大模型；主力电脑性能强但可能不常开机，或者你不想让它一直挂着个网页服务；你想在客厅、书房等多个地方通过平板或手机访问同一个AI助手。这个方案把计算和交互分离，树莓派成了轻量、低功耗的“前台”，你的PC成了强大的“后台大脑”。

我自己在搭建智能家居中枢和本地知识库时，就采用了这种架构。它让我的树莓派4B（甚至3B+）也能流畅地提供一个AI交互界面，而实际的“思考”工作则由书房里那台旧游戏本完成，安静又省电。接下来，我会带你从零开始，拆解整个部署过程，分享我踩过的坑和优化技巧。

2. 架构设计与核心思路拆解

2.1 为什么选择“计算分离”的架构？

在本地部署AI应用时，我们常面临一个矛盾：交互界面需要常驻运行、随时响应，最好放在低功耗设备上；而模型推理需要强大的CPU/GPU和内存，通常在高性能设备上。强行把它们塞进一台设备，比如让树莓派直接跑模型，要么选择极小的模型牺牲能力，要么体验卡顿不堪。

openclaw-rpi采用的正是“计算分离”（或叫客户端-服务器）架构。这种架构的优势非常明显：

1. 资源优化：各司其职。树莓派只负责轻量的Web服务和任务调度（OpenClaw Agent），对算力要求低，可以7x24小时运行。PC负责重度的模型加载和推理（Ollama），可以按需启动，充分利用其硬件优势。
2. 灵活性高：你可以随时升级PC的硬件或Ollama中的模型，而无需改动树莓派上的部署。树莓派作为接入点，可以放在家里任何有网络的地方。
3. 成本与功耗：树莓派的功耗通常只有几瓦，长期运行的电费几乎可以忽略不计，是作为家庭服务端的理想选择。

这个项目的价值，就在于它把这种架构的最佳实践给“样板化”了。你不用自己去研究OpenClaw怎么配置网络、Ollama怎么开启远程访问、防火墙怎么设置，它提供了一套现成的配置模板和自动化脚本。

2.2 核心组件与数据流解析

让我们把架构图再细化一下，看看数据具体是怎么跑的：

[用户设备] (手机/平板/电脑) | | HTTP/WebSocket (带Token) v [树莓派 Raspberry Pi] |- OpenClaw Dashboard (端口: 18789) # 网页界面 |- OpenClaw Agent # 任务协调器 | | HTTP API 调用 (局域网内) v [主力PC / 服务器] |- Ollama 服务 (端口: 11434) # 模型推理引擎 |- 本地模型文件 (如 qwen2.5:7b) # 大脑本体

1. 用户交互层：你在浏览器输入http://树莓派IP:18789并附上令牌（Token），访问的是树莓派上运行的OpenClaw仪表盘。
2. 请求处理层：你在网页上输入问题，OpenClaw Agent（也在树莓派上）接收到这个任务。
3. 任务转发层：Agent根据配置，知道模型服务不在本地，于是它把你的问题，通过HTTP请求的形式，发送到局域网内PC的Ollama服务地址（例如http://192.168.1.100:11434）。
4. 模型推理层：PC上的Ollama服务收到请求，加载指定的模型，进行推理计算，生成回答。
5. 响应返回层：Ollama将生成的文本通过HTTP响应发回给树莓派的Agent，Agent再呈现给仪表盘，最终显示在你的浏览器上。

整个过程中，树莓派和PC之间只需要网络互通，树莓派本身不承担任何模型计算压力。openclaw-rpi项目里的配置文件，就是用来正确建立这个数据通道的“接线图”。

2.3 安全边界与设计考量

任何将服务暴露在局域网内的操作，安全都是首要考虑。这个项目在设计上就包含了多层防护，而不是简单地把服务跑起来就完事。

1. 令牌认证（Token Auth）：这是OpenClaw自带的第一道门。没有正确的Token，即使你能连接到仪表盘的端口，也无法进行任何操作。这防止了家里临时来访的客人设备误连或好奇访问。
2. 基于IP的防火墙规则（UFW）：这是项目脚本自动设置的第二道，也是更关键的一道防线。它会在树莓派的系统防火墙上，只允许你指定的、受信任的设备IP地址访问18789端口。其他任何局域网内的设备（比如你的智能电视、IoT设备）的访问请求都会被直接拒绝。这从根本上缩小了攻击面。
3. 局域网（LAN）范围限定：整个设计默认服务于家庭或办公室内部网络，不涉及公网暴露。Ollama服务虽然绑定到0.0.0.0以接受局域网连接，但通常家庭路由器已经提供了网络地址转换（NAT）保护，外部互联网无法直接访问到你局域网内的PC。

注意：项目文档明确警告，如果你需要从家庭网络外部访问，正确的做法是建立虚拟专用网络（如WireGuard）接入家庭网络，而不是把OpenClaw或Ollama的端口直接映射到公网。直接暴露大模型服务到公网，风险极高。

3. 环境准备与设备配置要点

3.1 树莓派端：系统与基础依赖

你的树莓派需要扮演一个稳定的服务器角色。我推荐使用Raspberry Pi OS Lite (64-bit)版本，没有图形界面，资源占用更少，更稳定。如果你习惯用桌面版，也可以，但记得在完成后关闭自动休眠。

系统基础配置：

1. 更新系统：这是任何新系统部署的第一步。

   sudo apt update && sudo apt upgrade -y

2. 设置静态IP（强烈推荐）：作为服务器，一个固定的IP地址至关重要，否则每次路由器重启可能IP都会变，导致你的防火墙规则失效。可以通过sudo raspi-config在界面中设置，或直接编辑/etc/dhcpcd.conf文件。

   # 示例：编辑 /etc/dhcpcd.conf interface eth0 # 如果使用有线网络 static ip_address=192.168.1.50/24 static routers=192.168.1.1 static domain_name_servers=192.168.1.1 8.8.8.8

   请将192.168.1.50替换为你规划给树莓派的IP，192.168.1.1替换为你的路由器网关地址。
3. 安装必备工具：项目脚本会用到curl和python3，它们通常已预装，但最好确认一下。

   sudo apt install -y curl python3 python3-pip

3.2 PC端：Ollama的安装与网络配置

这是你的“大脑”主机。它可以是Windows、Linux或macOS。这里以Windows为例，Linux/macOS流程类似。

1. 安装Ollama：直接从 Ollama官网 下载安装包，安装过程非常简单。
2. 关键：以允许局域网访问的方式启动Ollama。默认情况下，Ollama只监听127.0.0.1（本机）。为了让树莓派能访问，必须让它绑定到0.0.0.0。openclaw-rpi项目贴心地提供了一个PowerShell脚本 (start_ollama_lan_32k.ps1)，其核心命令是：

   $env:OLLAMA_HOST="0.0.0.0" $env:OLLAMA_ORIGINS="*" ollama serve

   这个脚本还设置了OLLAMA_ORIGINS="*"以处理跨域请求，并建议了OLLAMA_NUM_PARALLEL=2等参数。你需要以管理员身份运行这个PowerShell脚本，或者将Ollama服务配置为以这些环境变量启动。
3. 拉取模型：在PC上打开另一个命令行，拉取你想要的模型。对于树莓派这种轻量级前端，搭配一个7B参数左右的模型是平衡性能和效果的好选择。

   ollama pull qwen2.5:7b # 或者 ollama pull llama3.2:3b # 更轻量，速度更快

4. 确认PC的防火墙：确保Windows防火墙允许入站连接访问11434端口。通常Ollama安装时会自动添加规则，但如果不行，需要手动在“高级安全Windows防火墙”中为ollama.exe添加入站规则。

实操心得：我建议在PC上为Ollama创建一个简单的启动脚本，并设置为开机启动（如果你希望PC常开）。这样能确保服务始终可用。另外，记下你这台PC在局域网内的IP地址（例如192.168.1.100），后面配置会用到。

3.3 网络连通性测试

在进入复杂部署前，做一个简单的测试能避免后续很多麻烦。

1. 从树莓派ping PC：在树莓派终端里，ping 192.168.1.100（替换为你的PC IP），应该能收到回复。
2. 从树莓派访问Ollama API：在树莓派上运行curl http://192.168.1.100:11434/api/tags。如果返回了PC上Ollama已拉取的模型列表JSON数据，说明网络和Ollama服务配置完全正确。如果连接被拒绝或超时，请回头检查PC的Ollama服务是否在运行、防火墙规则、以及绑定地址是否为0.0.0.0。

4. 详细部署流程与脚本解析

4.1 获取与准备配置文件

首先，通过SSH登录到你的树莓派。

1. 克隆项目仓库：

   git clone https://github.com/zenetio/openclaw-rpi.git cd openclaw-rpi

   如果网络不畅，也可以考虑先下载ZIP包再上传到树莓派。

2. 核心配置文件：trusted_devices.env这是整个项目的“控制中心”。复制示例文件并进行编辑：

   cp configs/trusted_devices.example.env configs/trusted_devices.env nano configs/trusted_devices.env

   这个文件里有几个关键变量，你需要根据自家情况填写：

   # 允许访问OpenClaw仪表盘的设备IP，用逗号分隔。通常包括： # 1. 你常用的电脑IP (e.g., 192.168.1.10) # 2. 你的手机IP（需要在手机上查看，且最好是设置静态IP或DHCP保留） # 3. 你的平板IP TRUSTED_OPENCLAW_CLIENTS="192.168.1.10,192.168.1.20,192.168.1.30" # 运行Ollama的PC的IP地址 PC_OLLAMA_IP="192.168.1.100" # 树莓派上运行脚本的用户名，通常是 'pi' RPI_USER="pi" # OpenClaw仪表盘的访问令牌，自己生成一个复杂且唯一的字符串 OPENCLAW_TOKEN="my_super_strong_secret_token_12345"

   重要提示：OPENCLAW_TOKEN不要使用简单密码。可以命令行运行openssl rand -base64 32生成一个随机字符串。TRUSTED_OPENCLAW_CLIENTS的IP必须准确，否则你的设备将无法访问页面。

4.2 核心部署脚本deploy_rpi_openclaw.sh做了什么？

这是主部署脚本，我们来看看它执行了哪些关键操作，以便理解其原理，遇到问题也能自己排查。

#!/bin/bash # 这是一个简化的逻辑说明，非原脚本 # 1. 检查并安装必要系统包 (如 ufw, curl, python3) # 2. 从 `trusted_devices.env` 读取配置 # 3. 基于模板 `openclaw.sample.json` 和上一步的配置，生成最终的 `openclaw.json` # 4. 将最终配置放到 OpenClaw 的默认配置目录 `~/.openclaw/` # 5. 安装或更新 OpenClaw (通过 pip) # 6. 运行防火墙设置脚本 `setup_firewall.sh` # 7. 启动 OpenClaw 仪表盘服务

脚本关键步骤解析：

• 配置生成：脚本的核心是使用envsubst命令（如果未安装，会尝试用python替代），将trusted_devices.env中定义的环境变量，替换到configs/openclaw.sample.json模板文件中的占位符（如$PC_OLLAMA_IP,$OPENCLAW_TOKEN）。这样，你就得到了一个针对你家庭网络定制的OpenClaw配置文件。
• 防火墙配置：它会调用scripts/setup_firewall.sh。这个脚本会：
  1. 安装并启用ufw（Uncomplicated Firewall）。
  2. 设置默认策略：拒绝所有入站，允许所有出站。
  3. 为SSH端口（22）和OpenClaw仪表盘端口（18789）添加规则。关键点在于：对于18789端口，它使用的是ufw allow from <IP> to any port 18789的格式，并且会为TRUSTED_OPENCLAW_CLIENTS变量中的每一个IP地址都创建一条独立的允许规则。其他未授权的IP访问18789端口的请求都会被丢弃。
• 服务启动：最后，它会尝试启动OpenClaw仪表盘。通常它会使用systemd来创建一个后台服务，确保开机自启。如果失败，也会回退到直接在前台启动进程的方式。

4.3 执行部署与验证

在树莓派上，确保你在openclaw-rpi项目根目录下，然后执行：

chmod +x scripts/deploy_rpi_openclaw.sh sudo ./scripts/deploy_rpi_openclaw.sh

注意：因为涉及安装软件包和配置系统防火墙，所以需要sudo权限。脚本会输出大量信息，请仔细阅读，看是否有错误（ERROR）出现。

部署成功后的验证步骤：

1. 检查服务状态：

   sudo systemctl status openclaw-dashboard

   如果看到active (running)字样，说明服务已成功启动。

2. 检查防火墙规则：

   sudo ufw status numbered

   你应该能看到一系列规则，其中会有类似这样的行，对应你设置的受信任IP：

   [ 4] 22/tcp ALLOW IN Anywhere [ 5] 18789 ALLOW IN 192.168.1.10 [ 6] 18789 ALLOW IN 192.168.1.20 ...

3. 从受信任设备访问：在你的电脑或手机浏览器中，输入：

   http://<树莓派IP>:18789/#token=<你的OPENCLAW_TOKEN>

   例如：http://192.168.1.50:18789/#token=my_super_strong_secret_token_12345如果一切正常，你应该能看到OpenClaw的Web界面。

5. 高级配置与个性化调优

5.1 修改OpenClaw模型与参数

项目提供的openclaw.sample.json是一个基础模板。部署后，最终的配置文件在~/.openclaw/openclaw.json。你可以编辑这个文件来定制AI行为。

1. 切换模型：在配置文件中，找到"model"字段。默认可能指向qwen2.5:7b。你可以将其改为你在Ollama中拉取的其他任何模型，例如llama3.2:3b或mistral:7b。

   "providers": [ { "type": "ollama", "url": "http://$PC_OLLAMA_IP:11434", "models": [ { "name": "qwen2.5:7b", // 修改为你想要的模型名 "parameters": { "temperature": 0.7, "top_p": 0.9, // ... 其他参数 } } ] } ]

2. 调整推理参数：temperature（创造性，值越高越随机）、top_p（核采样，影响词汇选择范围）等参数可以在这里调整。对于代码生成，可以降低temperature(如0.2)；对于创意写作，可以适当提高 (如0.8)。

3. 修改后重启服务：

   sudo systemctl restart openclaw-dashboard

5.2 管理受信任设备列表

家庭网络中的设备IP可能会变（尤其是手机）。当需要新增或移除一个受信任设备时：

1. 编辑configs/trusted_devices.env文件，更新TRUSTED_OPENCLAW_CLIENTS变量。
2. 重新运行防火墙设置脚本（无需重新部署整个OpenClaw）：

   sudo ./scripts/setup_firewall.sh

   这个脚本会先重置18789端口的规则，然后根据新的IP列表重新添加。

实操心得：为了避免IP变动带来的麻烦，我强烈建议在你的家庭路由器上，为需要访问的常驻设备（如你的个人电脑、树莓派本身）设置DHCP保留（或静态DHCP分配）。这样它们每次都会从路由器获得相同的IP地址。对于手机，可以查看当前IP后，临时添加到列表，或者也为其设置DHCP保留。

5.3 性能监控与日志查看

服务跑起来后，知道如何查看状态和排查问题很重要。

• 查看OpenClaw服务日志：

  sudo journalctl -u openclaw-dashboard -f

  使用-f参数可以实时跟踪日志输出。当你在网页端进行操作时，可以在这里看到详细的请求和错误信息。

• 检查系统资源：使用htop或top命令查看树莓派的CPU和内存占用。在正常情况下，OpenClaw进程占用应该很低。

  sudo apt install htop htop

• 测试Ollama连接：如果网页端提示模型调用失败，可以在树莓派上直接测试与Ollama的连接和模型列表：

  curl http://<你的PC_IP>:11434/api/tags

  如果这个命令失败或超时，问题就出在网络或Ollama服务本身，而不是OpenClaw配置。

6. 常见问题与故障排查实录

即使按照步骤操作，也可能会遇到一些问题。以下是我在部署和帮助他人部署时遇到的常见情况及其解决方法。

6.1 网页无法访问（连接被拒绝/超时）

这是最常见的问题。请按以下顺序排查：

一个典型排查流程：

1. 在树莓派上，sudo systemctl status openclaw-dashboard确认服务是active (running)。
2. 在树莓派上，curl localhost:18789。如果返回HTML代码，说明服务在树莓派本地是好的。如果失败，检查OpenClaw服务日志。
3. 从你的电脑，ping <树莓派IP>。通，则网络层没问题。
4. 从你的电脑，telnet <树莓派IP> 18789或nc -zv <树莓派IP> 18789。如果连接失败，几乎可以断定是防火墙问题。请仔细检查sudo ufw status的输出，确认你的电脑IP在允许列表中。
5. 如果第4步通了，但在浏览器中带Token访问仍失败，检查Token和配置文件。

6.2 模型调用失败（Ollama连接问题）

在网页上提问后，长时间无响应或返回“Provider error”。

1. 从树莓派测试Ollama连通性：

   # 测试基础连接和API curl -v http://<PC_OLLAMA_IP>:11434/api/tags

   如果这个命令失败，错误信息会很有帮助（如“Connection refused”或“Timeout”）。

2. 检查Ollama服务状态：到你的PC上，确认Ollama进程正在运行，并且是以绑定0.0.0.0的方式启动的。可以查看任务管理器（Windows）或ps aux | grep ollama（Linux/macOS）。

3. 检查PC防火墙：这是最常见的坑。即使Ollama绑定了0.0.0.0，Windows Defender防火墙或第三方防火墙软件也可能阻止来自局域网的连接。需要在PC的防火墙设置中，为ollama.exe或端口11434添加一条允许“域、私有、公共”网络入站的规则。

4. 检查OpenClaw配置文件：确认~/.openclaw/openclaw.json中的url字段指向了正确的PC IP和端口。

6.3 服务启动失败或脚本报错

1. envsubst命令未找到：部署脚本可能依赖envsubst来替换环境变量。如果系统没有，可以安装gettext包：

   sudo apt install gettext-base -y

   脚本通常有备选方案（使用Python），但直接安装依赖更稳妥。

2. Python或pip版本问题：确保树莓派上安装的是Python 3。如果遇到pip安装OpenClaw失败，可以尝试升级pip：

   python3 -m pip install --upgrade pip

3. 权限问题：所有脚本都需要在openclaw-rpi目录下执行。使用sudo运行部署脚本时，要确保当前目录的路径正确，否则脚本可能找不到配置文件。

6.4 性能优化与小技巧

1. 为Ollama PC设置性能模式：如果PC是笔记本，请确保电源模式设置为“高性能”或“最佳性能”，防止系统休眠或降频影响推理速度。
2. 使用更高效的模型：在PC资源有限的情况下，可以尝试llama3.2:3b、phi3:mini这类更小的模型，响应速度会快很多，日常问答和简单任务足够用。
3. 树莓派散热：长期运行，确保树莓派有良好的散热，避免因过热降频导致Web服务卡顿。一个简单的金属散热片或小风扇就能有很大改善。
4. 使用反向代理（可选）：如果你觉得带Token的URL太长不好记，可以在树莓派上安装Nginx或Caddy，配置一个反向代理。这样你可以用http://openclaw.local这样的域名访问，并且把Token验证集成到反向代理的Basic Auth中，体验更接近正式服务。但这需要一定的网络知识。

部署完成后，你就拥有了一个完全私有的、部署在家庭内部的AI助手。它的响应速度取决于你的局域网和PC的性能，但隐私性和可控性是云端服务无法比拟的。你可以用它来管理待办事项、回答知识性问题、甚至结合家庭自动化做一些有趣的联动。这个项目提供了一个坚实且安全的起点，剩下的玩法就取决于你的想象力了。