OpenClaw树莓派部署踩坑实录：国内环境、飞书接入与模型配置详解

古有孟母三迁，今有虾兵三易其名：ClawdBot、MoltBot、OpenClaw。项目的命名之旅，也从侧面反映了社区驱动的开放精神。

我最初的尝试是在手机的 Termux Proot 环境下安装，限制实在太多了。systemd 无法正常运行，权限也处处受限，折腾到最后实在进行不下去了。

于是，战场转移到了树莓派。然而，这并非一次简单的软件安装，而是一次伴随着无数踩坑、重装、清理、再重来的系统级迁徙。为了在云栈社区给各位开发者提供一份真实的参考，我决定将这段经历完整记录下来。

这不是一篇对官方教程的简单复述，而是一份真实的踩坑实录。内容涵盖环境准备、systemd失效、brew安装、模型配置、Web UI接入、飞书配置，再到服务崩溃、日志排查，直至最终稳定运行的全过程。如果你也打算在国内网络环境下部署 OpenClaw，希望这篇记录能帮你避开至少 80% 的弯路。

一、准备工作：事半功倍的关键

以下所有操作均通过 SSH 远程连接到树莓派执行。经过多次“安装-卸载-再安装”的循环，我总结出几个关键的前置步骤，做好这些能让后续安装顺利很多。

1. 新建专用用户

为 OpenClaw 创建一个独立的系统用户，有助于隔离其权限、环境与依赖。

ubuntu@ubuntu:~$ sudo adduser openclaw
ubuntu@ubuntu:~$ sudo usermod -aG sudo openclaw

2. 确保真实登录状态

务必使用新创建的 openclaw 用户直接登录 SSH 会话，而不是在原有会话中使用 su 命令切换。安装过程依赖正常的用户登录会话来管理 systemd 用户服务。

可以通过以下命令确认用户登录状态：

openclaw@ubuntu:~$ loginctl user-status $(whoami)

如果此处出现错误，例如提示用户未登录或处于挂起状态，则说明登录状态异常。

一旦用户状态异常，后续安装程序会跳过 systemd 用户服务的配置，导致服务无法随用户会话自启动。

3. 预先安装 Homebrew (brew)

许多 OpenClaw 的 Skills（技能）依赖通过 Homebrew 包管理器提供。虽然不安装 Skills 也能运行，但功能会受限。为了后续顺利，建议提前安装并配置好 brew。

安装过程建议通过代理进行，之后可配置国内镜像源加速。以下是在 openclaw 用户下的安装与配置示例：

openclaw@ubuntu:~$ export HTTP_PROXY=http://192.168.123.165:23333
openclaw@ubuntu:~$ export HTTPS_PROXY=http://192.168.123.165:23333

openclaw@ubuntu:~$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

openclaw@ubuntu:~$ tail -7 .bashrc
export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_API_DOMAIN="https://mirrors.aliyun.com/homebrew-bottles/api"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.aliyun.com/homebrew/homebrew-bottles"

openclaw@ubuntu:~$ echo >> /home/openclaw/.bashrc
    echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"' >> /home/openclaw/.bashrc
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"

# 使用 openclaw 用户重新登录后，安装基础编译工具
openclaw@ubuntu:~$ brew update
openclaw@ubuntu:~$ brew install gcc
openclaw@ubuntu:~$ sudo apt-get install build-essential

完成上述准备后，后续 Skills 的安装会顺畅很多。

二、OpenClaw 核心安装流程详解

下面按顺序拆解 OpenClaw 的安装与初始配置过程。

1. 安装 Node.js 22

OpenClaw 基于 Node.js 运行，需要版本 22 或更高。

openclaw@ubuntu:~$ export HTTP_PROXY=http://192.168.123.165:23333
openclaw@ubuntu:~$ export HTTPS_PROXY=http://192.168.123.165:23333
openclaw@ubuntu:~$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

openclaw@ubuntu:~$ source .bashrc

openclaw@ubuntu:~$ nvm install 22
openclaw@ubuntu:~$ npm config set registry https://registry.npmmirror.com

2. 一键安装 OpenClaw

使用官方安装脚本。

openclaw@ubuntu:~$ curl -fsSL https://openclaw.ai/install.sh | bash

3. 配置模型与 API Key

安装程序会引导配置 AI 模型。官方默认支持国外主流模型。如果你使用国内服务如 Minimax，此处可先跳过，后续再手动配置。

4. 选择通信渠道

OpenClaw 支持 Telegram、Discord 等众多国外聊天应用。初次安装可先跳过，后续通过 TUI 控制台或 Web UI 交互。我们后面会专门配置飞书。

5. 配置与安装 Skills (技能)

Skills 是扩展 OpenClaw 能力的插件。由于提前装好了 brew，这一步会顺利很多。可以选择性安装一些可能用到的技能。

安装过程会输出大量日志，最终效果如下：

6. 配置其他 API Key

对于未安装或不需立即使用的技能，其关联的 API Key 均可跳过配置。

7. 启用 Hooks (钩子)

Hooks 类似于拦截器，可在命令执行前后自动执行特定操作，建议全部启用。

8. 完成安装与 Systemd 服务配置

安装程序会自动配置 systemd 用户服务以实现开机自启。安装完成时，日志会提供重要的访问信息，特别是对于无 GUI 的服务器，它会给出 SSH 端口转发命令以便本地访问 Web UI。

9. 验证服务状态

安装完成后，务必检查服务是否正常运行。

• 查看 systemd 服务单元：

ubuntu@ubuntu:~$ sudo systemctl --machine=openclaw@.host --user list-units --type=service

• 在 openclaw 用户下查看网关服务详情、端口监听及日志：

openclaw@ubuntu:~$ systemctl --user status openclaw-gateway
openclaw@ubuntu:~$ netstat -anp | grep 18789
openclaw@ubuntu:~$ openclaw gateway status
openclaw@ubuntu:~$ journalctl --user -u openclaw-gateway -n 50 --no-pager
openclaw@ubuntu:~$ openclaw logs --follow

• 运行自检命令 openclaw doctor：

openclaw@ubuntu:~$ openclaw doctor

当 doctor 报告无明显异常，且网关（Gateway）正常监听在指定端口（如 18789），即表示基础服务已成功启动。这正是运维/DevOps/SRE实践中保障服务健康的常规操作。

三、关键调整：国内模型配置（Minimax）

对于国内 Minimax 的订阅用户，有一个必须注意的配置项。OpenClaw 默认使用的是国际版 API 端点，国内用户需要将其修改为官方国内端点，否则无法连通。

参考 Minimax 官方文档，需要修改配置文件中的 baseUrl。

修改方法：
打开 OpenClaw 的配置文件，找到 models.providers.minimax 部分，将 baseUrl 从 https://api.minimax.io/anthropic 修改为 https://api.minimaxi.com/anthropic。

openclaw@ubuntu:~$ open ~/.openclaw/openclaw.json

修改后需要重启网关服务使其生效：

openclaw@ubuntu:~$ systemctl --user restart openclaw-gateway

四、配置与控制：Web UI 接入

1. 本地端口转发

由于树莓派通常无浏览器，需要在本地电脑通过 SSH 端口转发来访问其 Web UI。

# 在本地电脑终端执行
ssh -A -L 18789:127.0.0.1:18789 openclaw@你的树莓派IP

执行后，本地 localhost:18789 即指向树莓派上的 OpenClaw 网关。

2. 获取认证 Token

安装完成时的日志中已包含带 Token 的 Control UI 链接（http://127.0.0.1:18789/?token=xxx），直接访问即可认证。
如果找不到，Token 也保存在 ~/.openclaw/openclaw.json 配置文件的 gateway.auth.token 字段中。访问 http://localhost:18789/ 后，在 Overview 页面的 “Gateway Token” 处填入即可。

3. 初始化对话与角色设定

首次在 Web UI 或 TUI 中与助手对话，它会引导你完成身份设定。这个过程会被记录在会话日志中。例如，在我的设定中，AI 助手成了“虾兵”，而我则是“蟹将”。

可以通过以下命令查看历史会话记录：

less .openclaw/agents/main/sessions/338f4a35-91c2-4710-b12f-9e8a02ae9629.json | jq -r 'select(.message) | .message || null'

五、使用体验与问题记录

经过一番折腾，OpenClaw 终于跑起来了。整体而言，它功能强大，但初期体验有些“坎坷”，阈值被拉得很高。

几点真实感受：

1. 模型配置陷阱：最初 Minimax 没配对，用其他模型让它自己修复，它一顿操作却始终无法成功，最后还得靠人工查文档解决。
2. “过于积极”的助手：曾让它安装飞书插件，一觉醒来发现它尝试了很多操作，但由于参数理解偏差，反而把服务配置文件改错，导致网关崩溃。这提醒我们，在赋予AI工具系统权限时需谨慎。
3. 日志查看不便：默认日志按天滚动，界面上无法直接查看前一天（尤其是凌晨）的日志，需要手动去日志文件里翻找，对问题追溯不太友好。

六、实战：接入飞书作为聊天前端

为了让使用更方便，我选择将 OpenClaw 接入飞书。

1. 创建飞书开放平台应用

• 在飞书开放平台创建企业自建应用。
• 添加“机器人”能力。
• 为机器人添加以下权限（请注意，原文中提供的权限字符串有拼写错误，以下为正确列表）：
  contact:user.base:readonly, im:message, im:message.p2p_msg:readonly, im:message.group_at_msg:readonly, im:message:send_as_bot, im:resource, contact:contact.base:readonly
• 切记：配置完成后，一定要在“版本管理与发布”中发布应用，否则配置不生效。

2. 安装 OpenClaw 飞书插件

openclaw@ubuntu:~$ openclaw plugins install @m1heng-clawd/feishu
openclaw@ubuntu:~$ systemctl --user restart openclaw-gateway
# 重启后观察日志，确认插件加载无误
openclaw@ubuntu:~$ journalctl --user -u openclaw-gateway -n 200 -f

3. 配置飞书通道参数
将飞书应用后台的 App ID 和 App Secret 配置到 OpenClaw 中。

openclaw config set channels.feishu.appId "cli_a9f4237d31785bdc"
openclaw config set channels.feishu.appSecret "BGLAjpHbZf5avMJRB7VnFeRVk2Bj5paW"
openclaw config set channels.feishu.enabled true

4. 配置飞书事件订阅
在飞书应用后台的“事件与回调”中，启用“长连接”模式，并订阅以下两个事件：

• im.message.message_read_v1 (消息已读)
• im.message.receive_v1 (接收消息)

5. 在飞书中使用
完成以上步骤后，无需再次重启服务。直接在飞书聊天中找到你的机器人，即可开始对话。

七、总结：能力强大，但需驾驭

尽管部署过程充满挑战，但不得不承认，一个配置妥当的 OpenClaw 助手能力是相当强大的。对于一般的命令行操作、信息查询、甚至是简单的系统管理任务，它都能有效完成。

例如，在合适的权限下，它可以协助管理 Docker 容器、查看系统状态等，体现出作为智能运维助手的潜力。

最后给想尝试的开发者几点建议：

• 耐心阅读文档：尤其是国内模型服务的特殊配置。
• 注意权限边界：谨慎开放工具（Tools）和文件系统访问权限。
• 善用社区：遇到问题，可以到相关的技术社区如云栈社区交流，往往能找到解决方案或灵感。

OpenClaw 作为一个活跃的开源项目，其玩法还在不断进化。希望这份基于树莓派和国内环境的实战记录，能为你探索 AI 个人助手提供一块坚实的垫脚石。