树莓派4打造AI智能体全攻略：从烧录系统到OpenClaw部署

为一张信用卡大小的计算机安装“大脑”，能带来非凡的成就感。这并非普通大脑，而是一个AI智能体：它能管理日程、整理收件箱、在Telegram上与你聊天，并且可以24小时安静地置于桌面，功耗甚至低于小夜灯。

今天，我们将逐步实现这一目标：使用树莓派4，通过官方工具将全新系统烧录到microSD卡，安装最新版Node.js，运行OpenClaw，最后连接一块3.5英寸液晶屏，无需外接显示器即可直接查看内容。

运行OpenClaw的树莓派4搭配3.5英寸触摸屏——这是完美的人工智能智能体配置。以下是一个完整的构建教程。

Image

所需硬件

  • 树莓派 4（推荐 4GB/8GB 内存，8GB 更适合 OpenClaw），也可使用树莓派 5
  • 全新 microSD 卡（至少 32GB，建议 64GB 以上，Class 10 / A2 性能更佳）
  • microSD 卡读卡器
  • 3.5 英寸 RPi LCD（A/B/C 型均可，本文以 C 型为例）
  • 5V 3A USB-C 电源（供电不足会导致各种异常问题）
  • 网线或 Wi-Fi 信息
  • 一台电脑（Windows/macOS/Linux）用于烧录
  • Anthropic、OpenAI 等支持的 LLM 提供商的 API Key（订阅更划算）

第一步：使用树莓派官方工具烧录系统

树莓派官方 Imager 是最简单的烧录方式，全平台通用。

下载并安装烧录工具

前往 raspberrypi.com/software，下载适用于你操作系统的树莓派烧录工具。它支持 macOS、Windows 以及 Ubuntu/Debian Linux。像安装其他应用程序一样安装它——在 Mac 上拖到“应用程序”文件夹，在 Windows 上运行安装程序，在 Linux 上使用包管理器。

刷写镜像

  1. 将 microSD 卡插入读卡器，然后连接电脑。
  2. 打开树莓派烧录工具。
  3. 选择你的设备——从列表中选择“树莓派4”。
  4. 选择操作系统——选择 Raspberry Pi OS（64位）。选择 64 位版本至关重要，因为 OpenClaw 和 Node.js 都能从中受益。如果你计划无头运行 OpenClaw（不带桌面环境），可以选择 Raspberry Pi OS Lite（64位），以释放约 600MB 内存。但既然我们要连接液晶屏，完整桌面版能让屏幕更有用。
  5. 选择存储设备——选择你的 microSD 卡。仔细检查，确保选对驱动器。

![Image](data:image/svg+xml,%3C%3Fxml version=‘1.0’ encoding=‘UTF-8’%3F%3E%3Csvg width=‘1px’ height=‘1px’ viewBox=‘0 0 1 1’ version=‘1.1’ xmlns=‘http://www.w3.org/2000/svg' xmlns:xlink=‘http://www.w3.org/1999/xlink'%3E%3Ctitle%3E%3C/title%3E%3Cg stroke=‘none’ stroke-width=‘1’ fill=‘none’ fill-rule=‘evenodd’ fill-opacity=‘0’%3E%3Cg transform=‘translate(-249.000000, -126.000000)’ fill=’%23FFFFFF’%3E%3Crect x=‘249’ y=‘126’ width=‘1’ height=‘1’%3E%3C/rect%3E%3C/g%3E%3C/g%3E%3C/svg%3E)

首次使用树莓派烧录工具设置树莓派

使用设置齿轮进行预配置

在点击“写入”之前，点击齿轮图标（或在新版本中点击“编辑设置”）。这是无需键盘和显示器进行初始设置的秘诀：

  • 设置主机名——例如 piagent.local，便于记忆
  • 启用 SSH——勾选此框并设置密码（或粘贴你的公钥）。这很重要，因为如果你想更改设置，稍后可以从电脑连接到树莓派。
  • 配置 Wi-Fi——输入你的 SSID 和密码，使树莓派首次启动时自动连接
  • 设置地区——选择时区和键盘布局
  • 设置用户名和密码——默认的 pi 用户即可，但需选择强密码

点击“保存”，然后点击“写入”。烧录工具将下载镜像、刷写并验证。根据卡速，这需要几分钟。

完成后，安全弹出卡，然后插入树莓派4。

第二步：首次启动与系统更新

将树莓派连接电源（如果不使用 Wi-Fi，则连接以太网线）。给它一两分钟启动。如果在烧录工具中配置了 SSH 和 Wi-Fi，可直接从电脑连接：

ssh pi@piagent.local

如果主机名解析失败，可以从路由器的管理面板找到树莓派 IP 地址，然后直接使用 IP 进行 SSH 连接。

连接后，更新所有内容：

sudo apt update && sudo apt upgrade -y

这将拉取最新的安全补丁和软件包更新。可能需要几分钟——可以稍作休息。

第三步：安装最新版本的 Node.js

OpenClaw 需要 Node.js 22 或更高版本。树莓派操作系统自带的 Node.js 通常较旧，因此通过 NodeSource 安装：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

验证安装：

node --version    # 应显示 v22.x.x 或更高
npm --version     # 应显示 10.x.x 或更高

还需安装基本构建工具以处理本地 npm 包：

sudo apt install -y git curl build-essential

设置时区

这比你想象的更重要——OpenClaw 使用时间戳安排日程、提醒和类似 cron 的任务：

sudo timedatectl set-timezone Europe/Paris

当然，替换为你自己的时区。可使用 timedatectl list-timezones 列出可用时区。

第四步：安装 OpenClaw

安装 Node.js 后，安装 OpenClaw 非常简单。官方一行命令即可处理所有事项：

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

这将下载命令行界面（CLI），通过 npm 全局安装，并启动入门向导。向导将引导你完成：

  1. 确认安全警告——OpenClaw 获得深度系统访问权限，因此最好在专用树莓派上运行，而非主电脑。
  2. 选择快速入门模式——首次设置的推荐选项。
  3. 选择 AI 提供商——Anthropic（Claude）、OpenAI 或本地模型。提示时粘贴 API 密钥。建议选择 OpenAI 并选 Codex——这样使用订阅服务而非 API，避免额外费用。
  4. 选择模型——例如，如果使用 Anthropic，选择 Claude Sonnet 或 Opus；如果使用 OpenAI，选择 GPT-5.4 或 GPT-5.3-codex。选择最新推荐即可。
  5. 设置通信渠道——Telegram 配置最快。向导将引导你在 Telegram 上通过 BotFather 创建机器人并粘贴令牌。如果没有 Telegram，WhatsApp 也很简单——详细说明如下。
  6. 选择技能——可暂时跳过，稍后添加。核心智能体无需额外功能也能工作。

向导完成后，OpenClaw 将启动机器人，并给出仪表板 URL（通常是 http://localhost:18789）。

将 OpenClaw 作为服务运行

你希望 OpenClaw 在重启后继续运行，且关闭 SSH 会话后不中断。入门向导通常已设置，可验证：

openclaw status
sudo systemctl status openclaw

如果未设置为服务，可启用：

openclaw onboard --install-daemon

快速健康检查

运行内置诊断工具：

openclaw doctor

这将检查配置、API 连接和网关状态。如有问题，通常会告知确切修复方法。也可运行 openclaw doctor --fix 自动修复常见问题。

第四步 A：通过 SSH 配置 OpenClaw

在设置消息渠道前，先熟悉如何通过 SSH 编辑 OpenClaw 配置。所有设置存储在单一 JSON5 文件 ~/.openclaw/openclaw.json 中。有几种修改方式。

最安全的 CLI 方式

openclaw config 命令会在写入前验证更改，避免引入无效键导致网关无法启动：

# 查看整个当前配置
openclaw config get

# 读取特定值
openclaw config get gateway.port
# 设置特定值
openclaw config set gateway.port 18789
# 移除设置
openclaw config unset tools.web.search.apiKey

直接编辑文件

如果更喜欢直接编辑原始文件（适用于较大更改），务必先备份：

# 备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 使用 nano 编辑（或 vim，如偏好）
nano ~/.openclaw/openclaw.json
# 保存后验证
openclaw doctor

此文件为 JSON5 格式，支持注释（如 // 这样）、尾随逗号和未加引号的键。但注意：未知键或无效类型会导致网关完全拒绝启动。没有优雅降级——它很严格。

Web 用户界面

如果网关正在运行，也可通过浏览器在 http://127.0.0.1:18789 的“配置”标签下编辑配置。先从笔记本电脑隧道连接：

ssh -L 18789:localhost:18789 pi@piagent.local

然后在浏览器中打开 http://localhost:18789。

热重载

网关会监视 openclaw.json 的更改，并自动热重载大多数设置——无需手动重启。渠道设置、模型更改、访问策略和工具权限都会热应用。对于少数需要重启的设置（如更改网关端口或绑定地址），默认“混合”重载模式会自动处理。

通过 SSH 进行基本安全配置

这是应首先配置的内容。锁定网关，使其仅监听本地主机，并要求令牌认证：

# 仅绑定到本地主机（防止暴露到网络）
openclaw config set gateway.bind loopback

# 验证认证模式设置为令牌
openclaw config get gateway.auth.mode
# 锁定文件权限
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/credentials

如需远程访问仪表板，使用 SSH 隧道或 Tailscale——切勿直接将端口 18789 暴露到互联网。

第四步 B：设置 Telegram（分步指南）

Telegram 是与 OpenClaw 协作最快的渠道。它默认使用长轮询，无需配置 webhook 或暴露端口。大约五分钟即可运行。

第一步：通过 BotFather 创建机器人

在手机或桌面 Telegram 应用中：

  1. 搜索 @BotFather——确保是带有蓝色验证标记的官方账号。
  2. 开始聊天并发送 /newbot。
  3. BotFather 会要求输入显示名称——输入类似 Pi Agent 或 My OpenClaw 的名称。
  4. 接下来要求输入用户名——必须以 bot 或 _bot 结尾，例如 my_openclaw_pi_bot。
  5. BotFather 会回复机器人令牌——类似 835019428:ABCdefGHIjklMNOpqrsTUVwxyz 的长字符串。复制此令牌并保密。拥有此令牌者即可控制你的机器人。

第二步：获取 Telegram 用户 ID

需要数字 Telegram 用户 ID 以设置访问控制。在 Telegram 中搜索 @userinfobot，点击开始，它会回复用户 ID（如 123456789 的数字）。复制此 ID。

第三步：配置 OpenClaw

SSH 连接到树莓派，并将 Telegram 渠道添加到配置中。可使用 CLI：

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN_HERE"
openclaw config set channels.telegram.dmPolicy "pairing"

或直接编辑配置文件：

nano ~/.openclaw/openclaw.json

添加（或合并）channels 块：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "835019428:ABCdefGHIjklMNOpqrsTUVwxyz",
      dmPolicy: "pairing",
      // 可选：限制特定用户 ID
      // allowFrom: ["123456789"],
    },
  },
}

重要：Telegram 配置在 channels.telegram 下，而非 plugins.entries.telegram 下。放错位置是常见错误，会导致“插件未找到”错误。

第四步：重启并配对

重启网关以启用新渠道：

openclaw gateway restart

检查 Telegram 是否正确启动：

openclaw channels status
# 应显示：Telegram default: enabled, configured, running, mode:polling

现在在手机上打开 Telegram，找到你的机器人（搜索所选用户名或点击 BotFather 提供的链接）。发送 /start 或任何消息。由于将 dmPolicy 设置为 "pairing"，机器人会回复配对码——如 ABC123。

在树莓派上批准配对：

openclaw pairing approve telegram ABC123

完成。再给机器人发送消息，几秒内应收到 AI 回复。

第五步：可选 Telegram 调整

基本功能正常工作后，有一些设置值得配置：

# 如果希望机器人在群聊中工作（默认需要 @提及）
openclaw config set channels.telegram.groups.*.requireMention true

# 设置特定用户白名单（仅数字 ID，非用户名）
openclaw config set channels.telegram.allowFrom '["123456789"]' --json

如果计划在 Telegram 群聊中使用机器人，返回 BotFather 并发送 /setjoingroups，选择机器人并选择“启用”。可能还需发送 /setprivacy 并禁用隐私模式，使机器人能看到所有群消息而非仅 @提及它的消息。注意：更改隐私设置后，需从现有群聊中移除并重新添加机器人以使更改生效。

第四步 C：设置 WhatsApp（分步指南）

WhatsApp 可能是日常使用最方便的渠道——它是大多数人手机上已有的应用。OpenClaw 通过 Baileys 库连接到 WhatsApp，Baileys 是 WhatsApp Web 多设备协议的开源实现。这意味着将树莓派链接为现有 WhatsApp 账户的配套设备，类似链接 WhatsApp Web 或 WhatsApp Desktop。

所需物品

  • 手机上的 WhatsApp 账户
  • 手机必须保持在线（如果离线超过约 14 天，WhatsApp 将取消链接会话）
  • 建议使用专用电话号码——使用个人号码也可，但使用便宜预付费 SIM 卡或 eSIM 能更好分离

为什么选择 Baileys 而非商业 API？

官方 WhatsApp 商业 API 按对话收费，需要 Meta 验证，并对出站消息施加模板要求。Baileys 免费，适用于任何个人 WhatsApp 账户，且无这些限制。代价是依赖逆向工程，因此如果 WhatsApp 更改协议，理论上可能中断。实际上，社区会迅速跟进。

第一步：配置 WhatsApp 访问

SSH 连接到树莓派并设置渠道配置：

openclaw config set channels.whatsapp.dmPolicy "pairing"
openclaw config set channels.whatsapp.allowFrom '["+48XXXXXXXXX"]' --json

将 +48XXXXXXXXX 替换为实际国际格式电话号码（包括国家代码）。此白名单控制谁能给机器人发消息。可添加多个号码：

openclaw config set channels.whatsapp.allowFrom '["+48XXXXXXXXX", "+1XXXXXXXXXX"]' --json

或直接编辑配置文件：

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",          // 或 "allowlist" 以更严格控制
      allowFrom: ["+48XXXXXXXXX"],
      groupPolicy: "allowlist",     // 限制群组访问
      groupAllowFrom: ["+48XXXXXXXXX"],
    },
  },
}

dmPolicy 选项有：

  • "pairing"（推荐）——未知发件人会收到配对码，必须批准后才能与机器人交谈。
  • "allowlist"——只有 allowFrom 中的号码可给机器人发消息。其他人被静默忽略。
  • "open"——任何人都可给机器人发消息。除非想耗尽 API 额度，否则勿用。

第二步：通过二维码链接 WhatsApp

配置完成后，运行：

openclaw channels login --channel whatsapp

二维码将出现在终端中。在手机上打开 WhatsApp，进入设置 → 链接设备 → 链接设备，然后扫描二维码。树莓派现在就像链接的配套设备。

会话凭证保存在 ~/.openclaw/credentials/whatsapp/。像对待密码一样对待此目录——拥有这些文件者即可冒充你的链接会话。

第三步：测试

从另一部手机（或请他人）给你链接的 WhatsApp 号码发送消息。如果使用 dmPolicy: "pairing"，机器人会发回配对码。批准它：

openclaw pairing approve whatsapp <CODE>

批准后，消息将传递给 AI，回复将直接发回 WhatsApp。

如果使用 dmPolicy: "allowlist" 且已将发件人号码添加到 allowFrom，则无需配对即可立即生效。

第四步：验证所有设置

# 检查所有渠道状态
openclaw channels status

# 查看实时日志以排查问题
openclaw logs --follow
# 如果 WhatsApp 显示断开，重新链接
openclaw channels login --channel whatsapp

WhatsApp 故障排除

二维码无法扫描——确保首次扫描时手机与树莓派在同一网络。链接后，无需在同一网络。

会话断开——如果手机长时间离线，或已达到 4 个已链接设备限制，会话将中断。从 WhatsApp 设置 → 已链接设备中删除未使用设备，然后重新运行 openclaw channels login --channel whatsapp。

消息发送失败——使用 openclaw logs --follow 查看网关日志，查找特定错误代码。常见原因包括速率限制、网络问题或收件人屏蔽你的号码。

凭据问题后重新链接——删除凭证文件夹并重新开始：

rm -rf ~/.openclaw/credentials/whatsapp/
openclaw channels login --channel whatsapp

第四步 D：通过 SSH 进行常见配置操作

以下是一些有用的配置命令，一切正常后可能需通过 SSH 运行。

更改 AI 模型

# 查看当前配置的模型
openclaw config get agents.defaults.model

# 切换到不同模型
openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-5"
# 设置备用模型以防主模型宕机
nano ~/.openclaw/openclaw.json

在配置文件中，备用模型如下所示：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: [
          "anthropic/claude-haiku-4-5",
        ],
      },
    },
  },
}

设置心跳（记忆整合）

OpenClaw 的心跳功能定期将对话上下文整合到记忆文件，避免丢失长期任务：

openclaw config set agents.defaults.heartbeat.every "30m"

为代理命名

openclaw config set identity.name "PiBot"
openclaw config set identity.emoji "🦞"

设置定时任务

可安排周期性任务。例如，设置晨间简报：

nano ~/.openclaw/openclaw.json

添加 cron 部分：

{
  cron: {
    jobs: [
      {
        name: "Morning Brief",
        schedule: { kind: "cron", expr: "0 8 * * *" },
        sessionTarget: "isolated",
        payload: {
          kind: "agentTurn",
          message: "Give me a summary of today's weather and any reminders.",
        },
      },
    ],
  },
}

同时启用 Telegram 和 WhatsApp

可同时运行多个渠道。只需在配置中包含两个渠道的配置块：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      dmPolicy: "pairing",
    },
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+48XXXXXXXXX"],
    },
  },
}

来自任何渠道的消息都会到达同一代理，并共享相同记忆。可在 Telegram 上开始对话，然后在 WhatsApp 上继续。

完整配置验证

进行任何手动编辑后，务必验证：

# 检查问题
openclaw doctor

# 自动修复可能的问题
openclaw doctor --fix
# 验证网关健康状态
openclaw status
openclaw health

安全注意事项

值得强调：OpenClaw 具有与你用户账户相同的系统访问权限。在专用树莓派上，这是可控的——它是一个隔离设备。但仍需采取基本预防措施。通过编辑 openclaw.json 将网关绑定地址设置为 127.0.0.1（而非 0.0.0.0），从而仅绑定到本地主机。如需远程访问，使用 Tailscale 或 SSH 隧道，而非直接暴露端口。

第五步：连接 3.5 英寸液晶显示屏

现在进入有趣部分——为树莓派添加“面孔”。3.5 英寸液晶显示屏直接连接到 GPIO 接口，提供 480×320 像素的触摸屏。虽然屏幕不大，但足以显示仪表盘、状态信息，或让整个设置更具真实感。

![Image](data:image/svg+xml,%3C%3Fxml version=‘1.0’ encoding=‘UTF-8’%3F%3E%3Csvg width=‘1px’ height=‘1px’ viewBox=‘0 0 1 1’ version=‘1.1’ xmlns=‘http://www.w3.org/2000/svg' xmlns:xlink=‘http://www.w3.org/1999/xlink'%3E%3Ctitle%3E%3C/title%3E%3Cg stroke=‘none’ stroke-width=‘1’ fill=‘none’ fill-rule=‘evenodd’ fill-opacity=‘0’%3E%3Cg transform=‘translate(-249.000000, -126.000000)’ fill=’%23FFFFFF’%3E%3Crect x=‘249’ y=‘126’ width=‘1’ height=‘1’%3E%3C/rect%3E%3C/g%3E%3C/g%3E%3C/svg%3E)

物理连接

首先关闭树莓派电源：

sudo shutdown -h now

小心将液晶显示屏的母 GPIO 接口与树莓派的公 GPIO 引脚对齐。显示屏位于树莓派上方，覆盖电路板。确保所有 26（或 40）个引脚正确连接——连接错位可能导致屏幕无法工作，甚至损坏屏幕。

连接完成后，重启树莓派。

安装驱动程序

通过 SSH 重新连接到树莓派并安装液晶显示屏驱动程序。具体命令取决于型号。通常，最佳方法是按照官方教程操作，因为他们会逐步讲解。

第六步：整合所有部分

至此，你已拥有运行最新树莓派操作系统的树莓派4，安装了 Node.js 22，OpenClaw 作为系统服务运行，还有 3.5 英寸液晶显示屏显示桌面。以下是如何充分利用此设置。

在液晶显示屏上访问 OpenClaw 仪表盘

可在树莓派桌面（预装 Chromium 浏览器）上打开浏览器，并导航至：

http://localhost:18789

这样即可在小屏幕上打开 OpenClaw 仪表盘。虽然 480×320 像素的浏览体验不宽敞，但足以查看状态和阅读最近消息。

通过 SSH 隧道远程访问

也可从笔记本电脑或台式机建立仪表盘隧道：

ssh -L 18789:localhost:18789 pi@piagent.local

然后在主浏览器中打开 http://localhost:18789，以获得更舒适体验。

与你的代理对话

如果在设置过程中配置了 Telegram，只需在手机上打开 Telegram 并向机器人发送消息。让它执行某些操作——查看天气、起草电子邮件、设置提醒。OpenClaw 将使用你选择的 LLM 处理请求，并在聊天中直接回复。

树莓派4 的性能提示

树莓派4 的 CPU 性能比树莓派5 慢约 2-2.5 倍，但它仍完全能作为 OpenClaw 的协调中心运行。繁重 AI 推理通过 API 调用在云端进行——你的树莓派只需协调。注意以下几点：

  • 考虑使用 USB 固态硬盘而非 microSD 卡进行日常使用。对于 OpenClaw 频繁对 SQLite 数据库和日志文件的小规模读写操作，SD 卡较慢。即使便宜的 USB 固态硬盘也能带来显著差异。
  • 使用 htop 监控交换空间使用情况。如果经常大量使用交换空间，4GB 型号可能无法满足工作负载需求。
  • 勿尝试在树莓派4 上运行本地 LLM。即使小型模型也会消耗过多内存。坚持使用云 API，让树莓派发挥其专长：安静保持连接并进行协调。除非添加 AI 加速扩展板。

总结

我们构建的是一个自给自足的 AI 代理工作站，硬件成本远低于 100 美元。运行全新操作系统的树莓派4、最新 Node.js、作为持久服务运行的 OpenClaw，以及让你随时查看代理动态的 3.5 英寸触摸屏——所有这些设备的功耗仅约 1 瓦。

此设置的优点在于隔离性。你的主计算机保持原样，个人数据保持独立，AI 代理拥有自己的小沙盒来运行。它始终在线、始终连接，并随时准备提供帮助。

现在，给你的“龙虾”找点事做吧。例如：让它构建一个始终运行的终端应用程序，并在树莓派屏幕上显示 OpenClaw 的最近消息。它运行得非常出色。