树莓派部署OpenClaw AI助手：从零构建安全基线实践指南

1. 项目概述：为树莓派打造一个安全至上的OpenClaw智能助手

最近在折腾一个挺有意思的项目：在树莓派上部署一个叫OpenClaw的AI助手。这玩意儿本质上是一个开源的、可自托管的AI网关和技能平台，能帮你把像Claude这样的AI模型能力，通过一个统一的接口（比如Telegram机器人）调用起来。听起来是不是有点像给自己建一个私人的、功能可定制的ChatGPT？但和直接使用网页版不同，自己部署意味着完全的数据掌控和无限的定制可能。

不过，把任何服务，尤其是带管理界面的AI服务，放在树莓派这种常年联网的小设备上，安全就成了头等大事。我可不想哪天醒来发现我的树莓派成了“矿工”或者跳板。所以，这次部署的核心思路不是“怎么最快跑起来”，而是“怎么在安全的前提下，稳定地跑起来”。整个流程会贯穿“安全基线”思想，从操作系统安装、网络加固，到服务配置，每一步都尽量选择最稳妥、暴露面最小的方案。如果你手头有一台树莓派（Pi 4或以上性能会更好），并且希望搭建一个长期稳定、无需操心安全问题的AI助手后端，那么这篇从一线踩坑经验里总结出来的指南，应该能帮你省下不少折腾的时间。

2. 核心安全理念与基础环境搭建

2.1 为什么“安全第一”对树莓派如此重要？

树莓派因其低功耗和常开特性，非常适合作为家庭服务器运行各种服务。但正因为它通常直接连接家庭网络，甚至可能通过DDNS暴露在公网（虽然极度不推荐），其安全假设就和一台放在数据中心、有专业防火墙保护的服务器完全不同。攻击者会持续扫描公网IP段，寻找开放了22（SSH）、80（HTTP）等端口的设备进行爆破或漏洞利用。我们的目标，就是让这台树莓派在网络上“看起来像块石头”——没有不必要的端口，没有弱密码，没有默认配置。

基于这个目标，我确立了几个非妥协的安全原则：

1. 绝不直接暴露控制界面：OpenClaw的管理界面（Gateway）默认不能从局域网甚至互联网直接访问。
2. 最小化网络攻击面：系统防火墙默认拒绝所有入站连接，只显式放行必要的服务（如SSH）。
3. 废除密码认证：SSH完全使用密钥登录，杜绝暴力破解的可能。
4. 服务绑定本地环回：OpenClaw网关服务只监听127.0.0.1（localhost），这意味着只有树莓派本机上的程序能连接它，网络上的其他设备连探测都探测不到。

这些原则会在接下来的每一步中得到贯彻。听起来有点麻烦？但一旦设置好，它就是一套“一劳永逸”的堡垒，后续你增加其他服务（比如Web服务器、数据库）时，这套安全基线依然是坚固的基础。

2.2 硬件与操作系统选型考量

工欲善其事，必先利其器。硬件选择直接影响长期运行的稳定性和体验。

• 树莓派型号：Raspberry Pi 4B 或更新型号（如Pi 5）是首选。OpenClaw本身虽然不重，但它背后可能连接的AI模型API调用、以及未来你可能添加的技能（Skills），都需要一定的内存和CPU资源。Pi 4B的4GB或8GB内存版本能提供更从容的运行环境。Pi 3或Zero 2 W虽然理论上也能跑，但你会更容易遇到内存不足导致的卡顿或崩溃。
• 存储介质：强烈推荐使用USB 3.0 SSD，而非MicroSD卡。这是提升系统可靠性和寿命最关键的一步。SD卡在频繁读写下（尤其是日志、数据库操作）极易损坏，导致系统崩溃或数据丢失。一块便宜的128GB SATA SSD加一个USB 3.0转接盒，成本不高，但带来的稳定性和速度提升是质的飞跃。如果你坚持使用SD卡，请务必选择A2级别的“应用性能等级”高速卡，并做好定期备份。
• 操作系统：选择Raspberry Pi OS Lite (64-bit)。这个版本没有图形桌面环境，资源占用极低，完全通过SSH管理，非常符合服务器定位。64位系统能更好地利用Pi 4及以上型号的硬件，并且是运行新版Node.js等软件的基础。

实操心得：很多新手喜欢用桌面版，觉得有界面更友好。但对于服务器，图形界面是毫无必要的负担，它不仅占用上百MB内存，还可能引入不必要的安全服务。用Lite版本，所有操作通过命令行完成，你会更了解系统是如何运作的，这才是运维的精髓。

2.3 使用Raspberry Pi Imager进行安全初始化安装

官方提供的Raspberry Pi Imager工具现在非常强大，它能在烧录系统镜像前就完成很多关键配置，避免了首次启动后还要接显示器键盘的麻烦。

1. 下载并启动Imager：在你的电脑（Windows、macOS、Linux均可）上，从树莓派官网下载Raspberry Pi Imager。
2. 选择操作系统：点击“Choose OS”，向下滚动找到“Raspberry Pi OS (other)”，然后选择“Raspberry Pi OS Lite (64-bit)”。
3. 选择存储：插入你的SD卡或SSD，在“Choose Storage”中选中它。
4. 进入核心配置：点击右下角的齿轮图标或“Advanced options”（不同版本按钮可能不同），打开高级设置。这里是我们实现安全初始化的关键：
   • 设置主机名：例如clawpi。这会让你的设备在局域网内可以通过clawpi.local访问，方便记忆。
   • 启用SSH：务必勾选。选择“Use password authentication”，并设置一个高强度临时密码。这个密码仅用于首次密钥配置前的登录，配置完成后我们会禁用它。
   • 配置用户名和密码：创建一个专属用户，例如openclaw。切勿使用默认的pi用户，因为这是攻击者尝试登录的第一个用户名。为该用户设置一个强密码。
   • 配置无线网络：如果你的树莓派使用Wi-Fi，在这里填入SSID和密码。更推荐使用有线以太网，连接更稳定，延迟更低，且少一个无线驱动的潜在故障点。
   • 区域设置：设置正确的时区（如Asia/Shanghai），这对日志时间戳非常重要。
5. 烧录并启动：点击“Write”，等待完成。将存储设备插入树莓派，上电启动。

注意事项：首次启动可能需要一两分钟进行初始化扩展文件系统。之后，你应该就能通过ssh openclaw@clawpi.local或ssh openclaw@<树莓派IP>并使用你设置的密码进行连接了。如果连不上，请检查路由器后台确认树莓派获取到的IP地址，并确保你的电脑和树莓派在同一局域网段。

3. 系统级安全加固实战

成功SSH登录后，我们首先面对的是一个“裸”的系统。在安装任何应用之前，必须先把系统的安全防线筑起来。这个过程就像给房子装上防盗门、监控和警报系统。

3.1 建立SSH密钥认证并废除密码登录

密码登录SSH是最大的安全风险之一。我们要用更安全的非对称密钥对来替代它。

1. 在本地电脑生成密钥对（如果你还没有）：

   # 在Mac/Linux的终端或Windows的WSL/Git Bash中执行 ssh-keygen -t ed25519 -C "openclaw-pi-admin"

   -t ed25519指定使用Ed25519算法，它比传统的RSA更安全、更快、密钥更短。执行后会提示你保存位置（直接回车用默认位置~/.ssh/id_ed25519即可）和设置密钥密码（passphrase）。强烈建议设置一个强密码短语，这样即使私钥文件泄露，没有密码也无法使用。

2. 将公钥部署到树莓派：

   ssh-copy-id -i ~/.ssh/id_ed25519.pub openclaw@clawpi.local

   系统会提示你输入之前为openclaw用户设置的密码。成功后，你的公钥就被添加到了树莓派~/.ssh/authorized_keys文件中。

3. 测试密钥登录：

   ssh openclaw@clawpi.local

   如果配置正确，它会直接登录（或提示你输入私钥密码短语，而非用户密码）。

4. 禁用密码认证（关键步骤）：确认密钥登录无误后，我们永久关闭SSH的密码登录功能。

   # 编辑SSH服务端配置 sudo nano /etc/ssh/sshd_config

   找到并确保以下配置项：

   PermitRootLogin no # 禁止root直接登录 PasswordAuthentication no # 禁用密码认证 PubkeyAuthentication yes # 启用公钥认证

   按Ctrl+X，然后按Y保存，回车确认文件名。务必谨慎，这是危险操作！在退出当前SSH会话前，请务必新开一个终端窗口，再次尝试SSH密钥登录，确保一切正常。确认无误后，再回到原会话重启SSH服务：

   sudo systemctl restart ssh

   从此以后，只有拥有对应私钥（和密码短语）的人才能登录这台树莓派，暴力破解密码攻击彻底失效。

3.2 配置防火墙（UFW）与入侵防御（Fail2ban）

防火墙是网络的守门人，Fail2ban则是动态的保安，会把多次尝试失败的IP暂时关进“小黑屋”。

1. 安装并配置UFW：

   sudo apt update && sudo apt install -y ufw # 设置默认策略：拒绝所有入站，允许所有出站 sudo ufw default deny incoming sudo ufw default allow outgoing # 允许SSH连接（确保你在执行此命令前已经能用SSH密钥登录！） sudo ufw allow OpenSSH # 启用防火墙 sudo ufw --force enable # 查看状态 sudo ufw status verbose

   输出应显示“Default: deny (incoming), allow (outgoing)”，并且只有22/tcp (OpenSSH) 被允许。这样就确保了除了SSH，所有外部发起的连接都会被拒绝。

2. 安装并启用Fail2ban：

   sudo apt install -y fail2ban sudo systemctl enable --now fail2ban

   Fail2ban安装后会自动读取/etc/fail2ban/jail.conf和/etc/fail2ban/jail.d/defaults-debian.conf的配置，并为SSH等服务提供基本的防护。它会监控系统日志（如/var/log/auth.log），如果某个IP在短时间内多次SSH登录失败，就会调用UFW将其IP临时封禁一段时间（默认10分钟）。 你可以查看其状态和当前被禁止的IP：

   sudo systemctl status fail2ban sudo fail2ban-client status sshd

3.3 系统优化与交换空间检查

树莓派内存有限，当物理内存用尽时，系统会使用交换空间（Swap）来防止应用崩溃。Raspberry Pi OS Lite默认使用zram，这是一种在内存中压缩的虚拟交换设备，速度比SD卡上的交换文件快得多，也更适合SD卡。

# 检查当前交换空间 swapon --show free -h

如果swapon显示有/dev/zram0之类的设备，并且free -h的Swap行有数值，说明zram已在工作。除非你遇到明确的内存不足问题，否则不要轻易修改zram配置或创建额外的swapfile在SD卡上，因为频繁的SD卡交换会显著缩短其寿命。对于USB SSD，如果确实需要，可以考虑创建一个swapfile，但优先级仍低于优化应用内存使用。

4. OpenClaw核心服务部署详解

基础安全设施就绪后，我们就可以开始部署主角OpenClaw了。它的架构主要包括一个核心网关（Gateway），负责处理请求和调度技能（Skills）。

4.1 Node.js运行环境安装

OpenClaw基于Node.js开发，我们需要安装一个较新的版本（要求22+）。这里使用NodeSource维护的仓库，比树莓派默认仓库的版本要新得多。

# 添加NodeSource仓库并安装Node.js 22 LTS curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs # 验证安装 node -v # 应输出 v22.x.x npm -v # 应输出 10.x.x

为什么不用apt install nodejs？因为树莓派OS默认的APT仓库里的Node.js版本通常很旧，可能不满足OpenClaw的依赖要求。NodeSource仓库提供了最新的LTS版本。

4.2 OpenClaw全局安装与验证

我们将OpenClaw安装到全局环境，方便在任何位置调用其命令行工具。

# 全局安装OpenClaw sudo npm install -g openclaw@latest # 验证安装成功 openclaw --version openclaw --help

安装成功后，openclaw命令就可以使用了。--help可以查看所有可用的子命令，如onboard,configure,start,security audit等。

4.3 安全导向的初始化配置（Onboarding）

这是最关键的一步，配置决定了服务以何种安全姿态运行。

# 启动交互式初始化向导 openclaw onboard

向导会询问一系列问题，以下是我的安全推荐配置，请务必遵循：

• Gateway Bind Address（网关绑定地址）：

  • 提问：What address should the gateway bind to?
  • 回答：127.0.0.1（绝对不要选0.0.0.0）
  • 理由：0.0.0.0意味着绑定到所有网络接口，包括你的局域网IP（如192.168.1.x）。如果防火墙没拦住，同一局域网内的其他设备就能访问你的OpenClaw管理接口。127.0.0.1是本地环回地址，只有树莓派本机可以访问，实现了默认隔离。

• Gateway Port（网关端口）：

  • 使用默认的18789即可，除非该端口已被占用。

• Gateway Authentication（网关认证）：

  • 选择Token。
  • 在设置Token时，不要用简单密码。向导可能会生成一个较短的令牌，我们可以先接受，后续再替换。

• Tailscale Exposure：

  • 除非你明确在使用Tailscale组建虚拟局域网，否则选择Off。

• Hooks & Skills：

  • 初次搭建，建议都先选择Skip。我们的目标是先让核心网关安全稳定地跑起来，附加功能可以后续按需添加。

配置完成后，向导通常会提示你启动服务。如果它没有自动安装为系统服务，我们可以手动配置。

4.4 配置系统服务与强化认证令牌

为了让OpenClaw网关在后台稳定运行并在开机时自动启动，我们需要将其配置为systemd用户服务。

1. 检查并创建服务单元文件： Onboarding过程通常会尝试安装一个openclaw-gateway.service文件到~/.config/systemd/user/。如果没有，我们可以手动创建：

   nano ~/.config/systemd/user/openclaw-gateway.service

   粘贴以下内容（可能需要根据openclaw start的实际命令调整ExecStart）：

   [Unit] Description=OpenClaw Gateway After=network.target [Service] Type=simple ExecStart=/usr/bin/openclaw start Restart=on-failure RestartSec=10 Environment="NODE_ENV=production" [Install] WantedBy=default.target

2. 生成并设置强认证令牌： 初始的令牌可能不够安全。我们使用OpenSSL生成一个64字符的强随机令牌。

   openssl rand -hex 32

   这会输出一个类似a1b2c3d4e5f6...的64位十六进制字符串。复制它。

   # 设置新的强令牌 openclaw config set gateway.auth.token "你刚才生成的64位令牌"

   妥善保管这个令牌，它是访问OpenClaw网关API的钥匙。

3. 启动并启用服务：

   # 重载systemd用户配置 systemctl --user daemon-reload # 启动服务 systemctl --user start openclaw-gateway # 设置开机自启 systemctl --user enable openclaw-gateway # 查看服务状态 systemctl --user status openclaw-gateway --no-pager

   如果状态显示active (running)，恭喜，核心服务已经跑起来了。

4. 验证服务绑定与监听： 我们需要确认服务确实只监听在本地环回地址。

   ss -lntp | grep :18789

   期望的输出是：

   LISTEN 0 4096 127.0.0.1:18789 0.0.0.0:* LISTEN 0 4096 [::1]:18789 [::]:*

   这表示服务只监听127.0.0.1(IPv4本地) 和::1(IPv6本地)。如果你看到0.0.0.0:18789，说明配置有误，网关暴露在了局域网中，必须返回去修改gateway.bind配置并重启服务。

5. 深度安全审计与访问策略

部署完成不是终点，我们必须进行最终的安全检查，确保没有疏漏。

5.1 运行OpenClaw安全审计

OpenClaw自带一个很棒的安全审计工具，能检查常见的不安全配置。

openclaw security audit --deep

仔细阅读输出。在一个按照本指南配置的环境中，你应该看到：

• 0个Critical（关键）问题。
• 可能有一个Warning（警告）关于gateway.trusted_proxies_missing。这个警告在目前配置下是安全的，可以忽略。它提示的是，如果你未来将OpenClaw网关放在Nginx等反向代理后面，并且需要获取客户端的真实IP时，需要配置信任代理。而我们目前是纯本地访问，不存在代理。

5.2 如何安全地访问控制界面

现在网关服务只在127.0.0.1:18789运行，我们怎么管理它呢？有两种主流且安全的方法：

1. 通过SSH隧道进行本地端口转发（推荐）： 这是最安全的方式，管理流量通过加密的SSH通道传输。

   # 在你的本地电脑上执行 ssh -L 18789:localhost:18789 openclaw@clawpi.local -N

   这个命令会在你本地电脑的18789端口和树莓派的18789端口之间建立一个安全的隧道。然后，你只需在本地浏览器打开http://localhost:18789，输入之前设置的强令牌，就能访问到树莓派上运行的OpenClaw控制界面了。关闭SSH会话，隧道即断开，访问也随之终止。

2. 使用命令行工具： OpenClaw CLI工具（openclaw config,openclaw skills等）在树莓派上直接运行，会自动连接到本地服务，无需处理网络访问。

绝对要避免的做法：在路由器上设置端口转发，将树莓派的18789端口暴露到公网。除非你非常清楚如何配置反向代理（如Nginx）、设置HTTPS、添加HTTP Basic Auth或更高级的认证，否则这等同于敞开大门。

5.3 后续扩展与技能安装的安全须知

当你需要安装技能（Skills）时，可能会遇到权限问题。因为OpenClaw是以你的用户身份运行，而npm install某些全局技能可能需要写权限。

• 如果遇到EACCES权限错误：不要使用sudo来安装技能，这会破坏用户服务的文件所有权。正确的做法是确保你的用户对OpenClaw相关的目录有正确的权限，或者通过openclaw命令提供的技能管理功能来安装，它会处理路径问题。
• 技能来源审查：只从官方或可信来源安装技能。每个技能都可能引入新的依赖和潜在的安全风险。
• 网络访问控制：如果技能需要访问外部API（如天气、新闻），确保你了解并信任该API。OpenClaw网关本身只监听本地，但技能进程可能会对外发起网络请求。

6. 故障排查与日常维护指南

即使按照指南操作，也可能遇到问题。这里记录了几个最常见的情况和解决方法。

6.1 SSH连接失败

• 症状：Permission denied (publickey)。
• 可能原因1：使用了错误的用户名。确认你SSH命令中的用户名和树莓派上创建的一致（如openclaw）。
• 可能原因2：公钥未成功部署。在本地电脑重新执行ssh-copy-id。
• 可能原因3：在禁用密码认证后，用于SSH的私钥不对或密码短语错误。检查你是否在使用正确的私钥文件（如id_ed25519而非id_rsa）。
• 终极解决方案：如果以上都不行，且你有物理访问权限，可以将SD卡/SSD插到电脑上，挂载根分区，在/etc/ssh/sshd_config中将PasswordAuthentication临时改回yes，重启树莓派后再用密码登录排查。

6.2 防火墙（UFW）启用警告

• 症状：执行sudo ufw enable时提示“Command may disrupt existing ssh connections”。
• 处理：这是正常提示。只要你已经执行了sudo ufw allow OpenSSH，就可以放心地输入y或使用sudo ufw --force enable强制启用。启用后，立即用另一个终端窗口测试SSH连接是否正常。

6.3 OpenClaw服务无法启动或崩溃

• 查看详细日志：

  journalctl --user -u openclaw-gateway -n 100 -f

  -f参数可以实时跟踪日志输出，对于诊断启动失败非常有用。
• 常见原因：
  1. 端口冲突：18789端口被其他程序占用。用ss -lntp | grep :18789检查，或修改OpenClaw的绑定端口。
  2. 配置错误：检查~/.config/openclaw/config.json文件格式是否正确（例如JSON引号、括号匹配）。
  3. Node.js版本不兼容：确保Node.js版本在22以上。
  4. 内存不足：使用free -h和htop查看内存和交换空间使用情况。考虑关闭不必要的进程，或为树莓派增加物理内存（换用更高内存型号）。

6.4 定期维护任务

为了让你的“ClawPi”长期稳定运行，建议定期执行：

1. 系统更新：

   sudo apt update sudo apt upgrade -y sudo apt autoremove -y

   建议每两周或每月进行一次。

2. 服务重启：偶尔重启OpenClaw服务可以释放潜在的内存泄漏。

   systemctl --user restart openclaw-gateway

3. 日志清理：长期运行后，日志文件可能变大。可以配置日志轮转（logrotate），或手动清理旧的日志文件（/var/log/目录下）。

4. 备份配置：将~/.config/openclaw/目录定期备份到其他位置。这是你的所有配置和技能数据。

经过以上步骤，你应该获得了一个运行在树莓派上、安全基线牢固的OpenClaw AI网关。它静静地待在角落，只通过加密的SSH隧道响应你的管理命令，对外则完全隐身。这种“无聊”的稳定，正是家庭自托管服务最可贵的状态。接下来，你可以放心地探索OpenClaw的更多功能，比如连接Claude API、配置Telegram机器人，或者开发自定义技能，而无需为底层安全担忧。