系列文章目录

  • 第一章 RK3588 部署 OpenClaw 完整记录

文章目录

前言

本文记录将 OpenClaw AI 网关部署到 RK3588 开发板（Android 系统）的完整踩坑过程。涉及 Termux 环境、Proot 容器、Node.js 兼容性、OpenClaw 飞书集成等核心难点。全文基于实际操作记录，希望能帮助嵌入式开发者少走弯路。

一、环境背景与挑战

1.1 硬件与系统环境

  • 设备：RK3588 开发板（ARM64 架构，8 核 2.4GHz）
  • 系统：Android 12（原生 Shell 为 Bionic libc）
  • 控制方式：Windows 笔记本通过 ADB + Scrcpy 远程控制

1.2 核心挑战：Android 不是标准 Linux

踩坑点 1：Android 原生 Shell 无法运行标准 Node.js

在 RK3588 的 ADB Shell 中直接执行安装命令：

console:/ # npm install -g openclaw@latest
/system/bin/sh: npm: inaccessible or not found

根本原因：Android 使用 Bionic libc（专为移动设备优化的 C 库），而标准 Linux 软件（Node.js）依赖 glibc。两者二进制不兼容，导致官方 Node 二进制在 Android 上直接报 No such file or directory。

二、架构方案：Termux + Proot 搭建完整 Linux 环境

2.1 架构设计

为绕过 Android 的 Bionic 限制，采用三层架构：

┌─────────────────────────────────────────────────────────────┐
│                        Windows 笔记本                        │
│                    ADB + Scrcpy 远程控制                      │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                      Android OS (RK3588)                     │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  Termux 应用 (提供用户态 Linux 环境)                      │  │
│  │  ┌──────────────────────────────────────────────────┐  │  │
│  │  │  Proot Debian (chroot 容器，完整 glibc 环境)       │  │  │
│  │  │  • OpenClaw 网关                                  │  │  │
│  │  │  • Node.js + npm                                  │  │  │
│  │  │  • 飞书机器人长连接                                │  │  │
│  │  └──────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

2.2 安装 Termux（避坑指南）

踩坑点 2：Termux 版本选择错误

  • 不要从 Google Play 安装（版本停止维护，API 22 不兼容）
  • 必须从 F-Droid 或 GitHub Releases 下载 v0.118+

安装命令：

# Windows 端下载并安装
curl -O -L https://github.com/termux/termux-app/releases/download/v0.118.1/termux-app_v0.118.1+github-debug_arm64-v8a.apk
adb install termux-app_v0.118.1+github-debug_arm64-v8a.apk

2.3 Proot 环境搭建

踩坑点 3：Termux 原生环境 Node.js 编译失败

在 Termux 中直接运行 npm install 会遇到依赖编译错误：

CANNOT LINK EXECUTABLE "node": library "libcrypto.so.3" not found

解决方案：安装 Proot-distro 运行完整 Debian：

pkg install proot-distro
proot-distro install debian
proot-distro login debian

进入后提示符变为 root@localhost:~#，此时拥有完整的 glibc 环境。

三、OpenClaw 安装与配置

3.1 官方脚本安装（Proot 中自动识别 Linux）

踩坑点 4：官方脚本 OS 检测

在 Termux 原生环境中运行官方脚本会报错：

curl -fsSL https://openclaw.ai/install.sh | bash
# Unsupported operating system

但在 Proot Debian 中，脚本正确识别为 Linux，自动完成 Node.js 和 OpenClaw 安装：

# 在 Proot Debian 中执行
apt update && apt install -y curl git
curl -fsSL https://openclaw.ai/install.sh | bash

3.2 编译依赖安装

踩坑点 5：koffi 原生模块编译失败

安装过程中若遇到 koffi 编译错误，需安装构建工具链：

apt install -y python3 cmake build-essential

3.3 网关启动与后台运行

踩坑点 6：Systemd 不可用

Proot 容器中无法使用 systemd，直接启动会提示：

systemd user services are unavailable

解决方案：使用 nohup 后台运行：

nohup openclaw gateway --port 18789 > /tmp/openclaw.log 2>&1 &

# 验证状态
openclaw gateway status
# 预期输出：listening on ws://127.0.0.1:18789, RPC probe: ok

四、飞书机器人集成（核心踩坑区）

4.1 配置方式大坑：Schema 验证失败

踩坑点 7：手动修改配置文件被拒绝

尝试在 ~/.openclaw/openclaw.json 中添加飞书配置：

"feishu": {
  "enabled": true,
  "config": {
    "appId": "cli_xxx",
    "appSecret": "xxx"
  }
}

报错：

Config validation failed: plugins.entries.feishu.config: must NOT have additional properties

源码验证：查看飞书插件源码发现 configSchema: emptyPluginConfigSchema()，不接受任何配置字段。

尝试环境变量也无效（FEISHU_APP_ID 等环境变量未被插件读取）。

4.2 正确方案：channels add 交互式配置

最终解决方案：使用 OpenClaw CLI 的交互式命令：

openclaw channels add --channel feishu

按提示输入：

  • AppID: 从飞书后台获取
  • App Secret: 从飞书后台获取
  • Verification Token: 从飞书后台"加密策略"获取

4.3 连接模式选择：长连接 vs Webhook

踩坑点 8：Webhook 模式配置复杂

尝试使用 Ngrok 搭建 Webhook，但遇到：

  • 免费版域名随机变化
  • 飞书验证 JSON 格式失败
  • 路径配置复杂（/webhook/feishu 或 /webhook/lark 不确定）

推荐方案：长连接模式（WebSocket）

# 配置为长连接（通过 channels add 自动设置）
openclaw channels add --channel feishu
# 选择 connection mode: websocket

长连接优势：

  • OpenClaw 主动连接飞书服务器，无需公网 IP
  • 无需 Ngrok 内网穿透
  • 适合嵌入式设备长期运行

4.4 关键：应用必须发布

踩坑点 9：长连接显示"已连接"但机器人不回复

即使飞书后台显示"已连接"，@机器人仍无响应：

检查清单：

  1. 事件订阅：必须添加 im.message.receive_v1
  2. 权限：开通 im:message:receive 和 im:message:send_as_bot
  3. 最关键：发布应用！

在飞书开放平台 → 版本管理与发布 → 创建版本并发布（或添加测试人员）。不发布则事件不会推送！

五、TUI 使用与命令执行

5.1 启动 TUI 交互

openclaw tui

5.2 命令执行审批机制

踩坑点 10：AI 无法直接执行系统命令

在 TUI 中让 AI 执行命令时，会提示需要审批：

让我检查 Gateway 状态：exec openclaw gateway status
[Request ID: 2] pending approval

操作方式：

# 查看待审批请求 ID
/approve 2 allow-once  # 单次允许
# 或
/approve 2 allow-always  # 永久允许此类操作

5.3 直接命令行模式（无需审批）

退出 TUI，使用非交互式命令：

openclaw gateway status
openclaw agent --agent main --message "你好" --thinking high

六、最佳实践总结

6.1 部署流程速查

# 1. 进入 Proot Debian
proot-distro login debian

# 2. 安装 OpenClaw（官方脚本自动识别 Linux）
apt update && apt install -y curl git
curl -fsSL https://openclaw.ai/install.sh | bash

# 3. 启动网关
nohup openclaw gateway --port 18789 > /tmp/openclaw.log 2>&1 &

# 4. 交互式配置飞书（关键！不能用配置文件）
openclaw channels add --channel feishu
# 按提示输入 AppID、Secret、Token

# 5. 飞书后台配置
# - 订阅方式：长连接接收事件
# - 添加事件：im.message.receive_v1
# - 开通权限并发布应用（必须！）

6.2 核心踩坑点汇总

阶段 踩坑点 现象 解决方案
环境准备 Android 不是 Linux npm: not found Termux + Proot Debian
安装 Termux 原生 Node 编译失败 libcrypto.so.3 错误 在 Proot 中用官方脚本安装
配置 修改 JSON 被拒绝 must NOT have additional properties 用 channels add 交互式配置
连接 Webhook 复杂难配 JSON 验证失败 / Ngrok 域名变化 改用长连接模式
运行 机器人不回复 连接正常但无响应 必须发布应用版本

总结

本文详细记录了在 RK3588 Android 开发板上部署 OpenClaw AI 网关的完整过程。核心难点在于 Android 系统使用 Bionic libc 与标准 Linux 软件不兼容，需要通过 Termux + Proot Debian 搭建完整的 glibc 环境。飞书机器人集成时，切记不能使用配置文件手动添加，必须通过 openclaw channels add 交互式配置，且务必在飞书后台发布应用版本才能正常接收事件。

希望这份踩坑指南能帮助到同样在嵌入式 Android 设备上部署 AI 服务的开发者，避免重复踩坑。

参考链接：

# python # c++ # 神经网络
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

安装paperclip

avatar AtomGit开源社区
cover

Obsidian CLI + Claude Code = 王炸组合

avatar AtomGit开源社区
cover

Python深度学习：从入门到实战

avatar AtomGit开源社区