近一段时间，围绕 OpenClaw 的讨论在中文互联网迅速升温，“养龙虾” 逐渐演变为一股颇具辨识度的技术热潮。多家媒体在报道这一现象时，都提到 OpenClaw 的走红正在带动相关硬件需求上升，尤其是 Mac mini 这类体积小、适合常驻运行的设备，甚至一度出现供需趋紧、价格被持续推高的情况。

而我恰好发现树莓派可能是 OpenClaw 的更理想运行环境。这样的判断并非出于“以低成本替代高性能设备”的冲动，而是建立在 OpenClaw 的实际运行机制之上：它本质上是一套可长期在线的 Gateway 系统，承担的是状态维护、渠道接入、会话调度与自动化执行等职责，而不是将全部计算负载都压在本地设备上。OpenClaw 官方针对 Raspberry Pi 的部署文档也支撑我这一想法，在此前提下，即便是 Raspberry Pi 4 或 5 这类配置相对克制的设备，也足以胜任持续运行的任务。

从部署哲学上看，这样的组合恰好体现了一种更为节制的系统设计思路：将高频、轻量、持续性的工作放在低功耗设备上，将高成本、重推理的计算请求交由远端模型提供商处理。它并不追求硬件规格上的夸张冗余，而是更强调角色边界的清晰、系统结构的稳定以及长期运维的可持续性。对于希望将 OpenClaw 作为个人常驻 AI 网关来使用的用户而言，树莓派并不是退而求其次的方案，反而常常是更符合工程理性的选择。

本文围绕这一思路展开，重点说明如何在 Raspberry Pi 5（4GB RAM） 上完成 OpenClaw 的安装、初始化、远程访问、Telegram 接入、模型与技能管理，以及后续的排障与更新维护。

环境准备与硬件优化

树莓派的角色定位

在开始部署之前，有必要首先厘清的，是设备的职责边界。按照 OpenClaw 官方文档的定义，树莓派在此方案中承担的是持续在线的 OpenClaw Gateway这一角色；也就是说，它主要负责运行常驻服务、保存本地状态、接收渠道消息、加载工作区与技能，并将模型请求转发至云端。因此，部署重点应落在系统稳定性、持久存储、后台服务管理与网络连通性之上，树莓派本身并不承载大规模模型推理。

模型认证应优先使用 API key；存储介质应优先考虑长期写入稳定性；操作系统应尽量保持精简，以便将内存和 I/O 资源留给 Gateway 本身。

只要这一角色划分足够清晰，整套部署流程就会呈现出相对明确的工程逻辑。

硬件配置与存储介质

OpenClaw 官方 Raspberry Pi 部署页给出的最低建议是：使用 Raspberry Pi 4 或 5，内存不少于 2GB（4GB 为更推荐的配置）；存储介质可选择 16GB 以上的 microSD 卡或 USB SSD，其中 USB SSD 被明确标注为性能更优的方案。官方同时建议搭配稳定的官方电源和可用的网络连接，并要求使用 64 位 Raspberry Pi OS，而非 32 位系统。

USB SSD 被明确标注为性能更优的方案的原因，是因为从长期使用的角度看，OpenClaw 作为常驻服务，会持续进行状态读写、日志写入、缓存更新以及工作区文件操作；如果设备计划长期在线，USB SSD 的价值并不只是更快，更在于其读写耐久性与整体稳定性。换言之，在这类部署场景中，存储不是边缘问题，而是系统可靠性的基础之一。

操作系统与 Headless 预配置

官方推荐使用 Raspberry Pi OS Lite（64-bit）。Lite 版本不包含桌面环境，更适合作为无图形界面的常驻服务器；而 64 位系统则是 OpenClaw Raspberry Pi 部署文档中明确要求的前提条件。

在具体操作上，建议通过 Raspberry Pi Imager 完成系统写入，并在写入阶段同步预配置主机名、SSH、用户名与密码，以及 Wi-Fi 参数。这样做的意义在于，从设备首次上电开始，它就能够以标准的 headless 方式被接管，而无须再借助显示器、键盘等外设进行二次初始化。对于旨在长期运行的网关设备而言，这样的部署路径更符合服务器化运维的基本原则。

关于树莓派操作系统的安装配置，不在本文的讨论的范畴，在此不做赘述。

基础更新与时区设定

系统首次启动并通过 SSH 接入后，首先应完成基础软件包更新，并安装 git、curl、build-essential 等基础依赖。与此同时，时区设置不应被视为可有可无的细节。OpenClaw 官方文档明确指出，时区设置会直接影响 cron 与 reminders 的执行行为，对于依赖提醒、调度或周期性任务的使用场景，时区必须在部署初期即配置准确。

建议参考执行如下命令：

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential
sudo timedatectl set-timezone Asia/Shanghai
timedatectl

完成这些步骤后，系统的基础运行环境才算真正进入可安装状态。

内存与系统资源优化

此外，即便设备为 4GB 内存，也不宜完全忽略内存安全边界。OpenClaw 官方树莓派部署文档建议，在低内存设备上配置 swap，并将 vm.swappiness 适当调低，以减少不必要的交换开销；同时，在 headless 环境中可以通过降低 GPU 内存占用、关闭未使用的系统服务来释放额外资源。

关于 swap 的配置，可参考官方示例：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
free -h

OpenClaw 部署与初始化

Node.js 24 的安装

OpenClaw 官方 Raspberry Pi 文档将 Node.js 24 作为推荐安装版本写入标准部署流程，而通用安装页则说明官方安装脚本会在需要时自动检测环境并安装 Node。出于可控性考虑，在树莓派上通常更建议先显式安装 Node.js 24，再执行 OpenClaw 的正式安装。这样做有助于减少 ARM 平台上由于运行时版本差异导致的附加变量。

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version

使用官方安装脚本部署 OpenClaw

OpenClaw 当前仍将安装脚本作为推荐方式。根据官方安装页说明，该脚本会自动检测操作系统、在必要时安装 Node、安装 OpenClaw，并启动 onboarding 流程。对于树莓派这种以尽快进入可用状态为目标的部署场景，这一方式仍然是最直接、最稳妥的入口。

curl -fsSL https://openclaw.ai/install.sh | bash

通过 onboarding 安装常驻服务

OpenClaw 在树莓派上的核心价值并不在于能够临时跑起来，而在于能够稳定地作为后台服务长期存在。因此，在完成安装之后，不应满足于前台启动一次 Gateway，而应按照官方推荐方式执行 onboarding，并将其注册为用户级常驻服务。OpenClaw Raspberry Pi 文档明确给出的命令是：

openclaw onboard --install-daemon

该命令会引导完成首轮配置，并将 Gateway 安装为用户级 daemon；对 Linux 而言，这一机制实际对应的是 systemd user service。

初始配置

初次 onboarding 时，更稳妥的顺序通常是：先完成本地 Gateway 的初始化，先接入一个可用的云端模型，先验证 Control UI 的连通性，再逐步加入 Telegram、Skills 与更复杂的自动化配置。这样一来，一旦系统出现异常，排查范围会明显收敛，不至于同时面对服务状态、认证、渠道、权限与技能依赖等多重不确定因素。

服务状态验证

OpenClaw 官方文档给出的推荐验证命令包括 openclaw status、systemctl --user status openclaw-gateway.service 以及 journalctl --user -u openclaw-gateway.service -f，这些命令都能查看 OpenClaw 服务的运行状态。此外，在服务异常时，官方还建议使用 openclaw doctor --non-interactive 进行诊断，并在 headless 环境下确认用户 lingering 已启用，以保证 systemd user service 在无人登录时仍可保持运行。

openclaw status
systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -f

sudo loginctl enable-linger "$(whoami)"

Control UI 的安全访问

在初始阶段，优先通过浏览器访问 Control UI 进行验证，通常比先接入外部聊天渠道更高效。OpenClaw 官方 Control UI 文档明确说明：若通过 http://<lan-ip> 或 http://<tailscale-ip> 等普通 HTTP 地址直接访问，浏览器会将其视为 non-secure context，从而阻止 WebCrypto；默认情况下，OpenClaw 会拒绝缺少设备身份的 Control UI 连接。

因此，在本地电脑上通过 SSH 隧道将树莓派的控制面板端口转发至 localhost，是最稳妥的初始访问方式。官方树莓派部署页给出的流程如下：

ssh <user>@<gateway-host> 'openclaw dashboard --no-open'
ssh -N -L 18789:127.0.0.1:18789 <user>@<gateway-host>

然后在本地浏览器访问 http://localhost:18789。之所以这一方式可行，正在于 localhost 属于浏览器认可的安全上下文范围。

Control UI
Control UI

需要额外强调的是，allowInsecureAuth 只是一个本地兼容开关。根据 OpenClaw Control UI 文档，它仅允许 localhost 场景在非安全 HTTP 上暂时放宽设备身份要求；它既不会绕过 pairing，也不会放宽远程访问的设备身份限制。因此，它不应被视为普通远程访问的正式解决方案。

模型认证与 Gemini 配置

OpenClaw 认证文档说明，Gateway 支持 OAuth 与 API keys 两种模式，但对于长期在线的 Gateway 系统，API keys 通常是更可预测的方案。官方建议将大语言模型的 provider key 写入 ~/.openclaw/.env，以便 daemon 读取；写入后，应重启守护进程并通过 openclaw models status 等命令重新确认状态。

以 Gemini 为例，具体的做法是：

mkdir -p ~/.openclaw
cat >> ~/.openclaw/.env <<'EOF'
GEMINI_API_KEY=Your_Gemini_API_Key
EOF
chmod 600 ~/.openclaw/.env
systemctl --user restart openclaw-gateway.service
openclaw models status

在这一点上，关键并不只是把密钥放进去，而是确保它进入 daemon 可继承的环境，而非仅停留在某个临时 shell 会话之中。

聊天渠道接入：以 Telegram 为例

初始接入方式

在多种可选渠道中，Telegram 通常是最适合作为起点的方案之一。OpenClaw Telegram 文档说明，Telegram 的快速接入流程以 BotFather 创建 token 为起点，随后在 Gateway 配置中写入 botToken、dmPolicy 等字段即可。

Telegram BotFather
Telegram BotFather

一个更适合作为初始版本的配置如下：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

这类配置的价值在于边界清晰：私聊需经过配对，群聊默认要求显式提及机器人，既能快速验证链路，也能避免初期暴露过宽的访问面。

私聊配对与授权逻辑

OpenClaw Telegram 文档明确指出，Telegram 的默认 DM policy 为 pairing。这意味着，用户第一次通过私聊接触机器人时，并不会自动获得访问权限，而是会进入一条显式授权流程。对于初次验证来说，这恰恰是一种更安全、也更利于排障的机制，因为它能够帮助操作者明确区分消息是否已到达 Gateway与授权是否已放通这两个层面。

对于单一所有者的 bot，最好改成 dmPolicy: "allowlist"，并把你的 Telegram user ID 放进 allowFrom，让授权策略稳定地保存在配置里，而不是依赖 pairing 历史。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABCDEF_your_token_here",
      dmPolicy: "allowlist",
      allowFrom: ["123456789"],
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

然而，应当注意，pairing 并不等同于全局授权。官方文档明确写明，pairing 仅限于 DM；在群聊场景中，仍需要通过 groupAllowFrom 或群级别的 allowFrom 进行控制。如果未显式设置 groupAllowFrom，Telegram 会回退到配置中的 allowFrom，而不是读取 pairing 存储。对单一所有者的 bot，官方给出的实践建议是：将个人用户 ID 写入 channels.telegram.allowFrom，将目标群放入 channels.telegram.groups，从而实现稳定、明确的授权控制。

群聊与 Privacy Mode

Telegram 群聊中的另一个常见问题来自平台本身的隐私机制。OpenClaw Telegram 文档指出，Telegram bots 默认启用 Privacy Mode，这会限制机器人在群内可见的消息范围。若机器人需要看到全部群消息，则必须通过 BotFather 的 /setprivacy 关闭隐私模式，或将 bot 设为群管理员；配置变更后，还需要将机器人从群中移除并重新加入，以便 Telegram 应用新的可见性设置。

因此，在群聊中若希望机器人无需被 @ 便能接收消息，仅仅将 requireMention 设为 false 并不足够，还必须同时满足 Telegram 平台侧的可见性条件。很多表面上的机器人无响应，本质上并不是 OpenClaw 配置错误，而是 Telegram 并未将相关消息交付给 bot。

进阶配置：模型分层路由与 Skills 技能管理

模型分层与成本控制

一旦 OpenClaw 进入常驻运行状态，模型配置就不再只是质量问题，也成为成本与系统结构问题。Heartbeat 文档表明，OpenClaw 支持在 agents.defaults.heartbeat 中单独设置运行间隔、专用模型、lightContext 和 isolatedSession 等参数；其中，isolatedSession: true 与 lightContext: true 的组合能够显著降低每次心跳执行所带来的 token 成本。

这意味着，更合理的模型策略通常不是所有任务统一使用最强模型，而是建立基本的层次区分：高质量模型用于复杂推理、低成本模型用于后台巡检与重复性任务。对树莓派这类常驻网关而言，这样的配置方式更符合长期运行所需的经济性与可持续性。

Skills 的安装与安全边界

从功能层面看，Skills 为 OpenClaw 提供了能力扩展路径；但从安全层面看，它们也意味着新的供应链入口。OpenClaw 当前公开的威胁模型文档明确将 Malicious Skill Installation 列为一类关键风险，并指出其当前缓解措施主要包括 GitHub 账号年龄校验与模式检测标记，而残余风险仍被标记为 Critical，原因在于无沙箱、审核有限。

因此，对于 Skills 的态度不宜停留在功能可用即可安装的层面。更审慎的做法应当包括：优先选择可信来源，认真阅读技能说明与依赖要求，明确其是否涉及外部执行、额外下载或高权限能力，并在必要时先行进行隔离验证。对于一台长期在线的树莓派网关而言，任何额外安装的 Skill，实际上都是在扩展系统的长期行为边界；安全性评估不应滞后于功能验证。

日常运维、排障与更新机制

工作区与长期维护意识

在 OpenClaw 的运行结构中，系统并不仅仅由安装目录和一份配置文件构成。随着长期使用的推进，工作区、渠道配置、模型认证、心跳规则、技能目录以及本地状态都会共同塑造其运行方式。因此，维护 OpenClaw 不应被理解为维护一个单独进程，而应被理解为维护一套持续演化的网关环境。这一认识会直接影响备份策略、更新策略以及问题定位方式。

按照官方文档的定义，OpenClaw 默认将 ~/.openclaw/workspace 作为 agent 的工作区；这一目录既是工具执行时的工作目录，也是系统读取操作指令、人格设定与用户信息的主要来源。首次运行时，OpenClaw 会对该工作区执行 bootstrap：初始化 AGENTS.md、IDENTITY.md、USER.md 等文件，并通过一轮简短问答，将身份与偏好写入对应文件；在流程结束后，BOOTSTRAP.md 会被自动移除，以确保这一初始化仪式只执行一次。

工作区文件
工作区文件

从文件职责来看：

  • AGENTS.md 用于承载 agent 的操作指令、行为优先级以及记忆使用规则，并会在每次会话开始时被读取；
  • SOUL.md 用于定义人格、语气与边界，同样在常规会话中持续生效；
  • USER.md 用于说明用户是谁、应如何称呼与对待；
  • IDENTITY.md 则更侧重 agent 自身的名称、气质与基本身份描述。除此之外，
  • TOOLS.md 主要记录本地工具与使用约定，它并不控制工具本身的可用性，而只是提供操作层面的说明；
  • HEARTBEAT.md 则是供心跳执行使用的简短检查清单，官方特别强调应尽量保持简短，以避免不必要的 token 消耗。

因此，在运维实践中，建议将 Agent Workspace 纳入与配置文件同等重要的维护范畴：在执行版本更新之前，应一并备份 ~/.openclaw/workspace；在引入新技能、调整人格设定或更改长期规则时，应优先审阅相关工作区文件，而不是仅从运行日志中追查表面现象。对树莓派这类长期在线设备而言，真正决定系统是否“稳定”的，往往不仅是服务有没有启动成功，更在于这些持续注入启动上下文的文件是否被清晰、克制且可追踪地维护。

状态检查与问题诊断

在日常运维中，最值得坚持的是“先看状态，再追日志”的顺序。树莓派部署文档给出的推荐检查命令包括 openclaw status、systemctl --user status openclaw-gateway.service 以及 journalctl --user -u openclaw-gateway.service -f；在服务无法启动时，则应进一步查看近百行日志，并运行 openclaw doctor --non-interactive。官方同时指出，若为 headless Pi，还应确认 lingering 已开启。

由此可见，所谓“OpenClaw 没有响应”，通常至少可以拆解为三类问题：服务未运行或启动失败，模型认证或上游 provider 出现异常，渠道授权或消息可见性未放通。只要排查顺序足够清晰，这类故障往往并不难定位，真正困难的通常是多个变量在同一时间被同时引入。

更新策略与 -dry-run

OpenClaw 更新文档将 openclaw update 作为推荐更新命令，并说明该命令会识别安装类型、拉取最新版本、运行 openclaw doctor，然后重启 Gateway。同时，文档明确提供了 openclaw update --dry-run，用于在不真正执行安装与重启的情况下预览更新动作。

对树莓派而言，先执行 dry-run 再正式更新，是极有价值的习惯。原因并不复杂：ARM 平台在遇到原生依赖、二进制兼容性或技能扩展时，本就比通用桌面环境更需要预判风险。将“预演一次更新过程”纳入常规维护流程，本质上是在以较低成本换取更高的系统可控性。建议的更新顺序如下：

openclaw update --dry-run
openclaw status
openclaw gateway status
openclaw update

如果在此之前能够对 ~/.openclaw 及其工作区建立定期备份，则整体维护过程会更加稳健。

结语

综合来看，在树莓派 5（4GB）上部署 OpenClaw，并不是在以低配硬件勉强承载复杂系统，而是在用一种更贴近其运行本质的方式组织资源。OpenClaw 需要的并不是一台始终富余、却并不真正高效的桌面级设备，而是一台能够长期在线、职责清晰、网络稳定、维护可控的网关主机。官方文档对于 Raspberry Pi 的定位、API key 的推荐、Control UI 的安全上下文要求、Telegram 的授权结构、Heartbeat 的成本控制，以及更新命令的设计，实际上都共同指向了这一点。

如果说以更强硬件部署 OpenClaw 是一种“用性能换省心”的思路，那么以树莓派部署 OpenClaw，则更接近一种“以结构取代浪费”的工程选择。它并不追求夸张的余量，而是通过更明确的职责划分、更稳妥的认证方式、更节制的访问策略与更审慎的扩展边界，使这套系统真正具备长期运行的条件。对于希望把 OpenClaw 作为个人常驻网关来使用的实践者而言，这种方案往往更值得信赖。