大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



 <p>前言</p> 

GPT plus 代充 只需 145

 

OpenClaw是一款轻量级自动化交互工具，适配树莓派等边缘设备，支持飞书/微信等多渠道对接。本文基于树莓派5 + Raspberry Pi OS 64位系统，详细梳理OpenClaw的完整部署流程，重点标注部署过程中踩过的坑及解决方案，适合新手快速上手。

 

一、环境准备

 

1.1 系统要求

 

- 树莓派5（4GB/8GB版本均可）

- 系统：Raspberry Pi OS (Bookworm) 64位（建议全新安装，避免依赖冲突）

- 网络：确保树莓派能访问外网（npm安装/飞书长连接需要）

 

1.2 安装核心依赖（Node.js + npm）

 

OpenClaw基于Node.js开发，需先安装Node.js环境：

 

bash

# 更新系统源

sudo apt update && sudo apt upgrade -y

 

# 安装Node.js（推荐18+版本，兼容OpenClaw 2026+）

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

sudo apt install -y nodejs

 

# 验证安装

node -v # 输出v18.x.x即为成功

npm -v # 输出9.x.x即为成功

 

 

1.3 配置npm国内源（提速必备）

 

树莓派直连npm官方源速度慢，建议切换为淘宝源：

 

bash

npm config set registry https://registry.npmmirror.com

# 验证源配置

npm config get registry # 输出https://registry.npmmirror.com即为成功

 

 

二、OpenClaw安装（npm全局安装）

 

2.1 全局安装OpenClaw

 

bash

npm install -g openclaw

 

# 验证安装（关键：确认版本，本文基于2026.2.26）

openclaw -v # 输出OpenClaw 2026.2.26 (bc50708)即为成功

 

 

2.2 初始化配置目录

 

OpenClaw默认配置目录为 ~/.openclaw/ ，安装后自动生成，可手动确认：

 

bash

ls -l ~/.openclaw/ # 能看到openclaw.json（核心配置文件）即为成功

 

 

三、基础配置：跳过飞书/搜索，先启动核心服务

 

新手建议先跳过飞书、网页搜索等可选功能，确保核心服务能正常启动。

 

3.1 写入最简JSON配置（新版核心：JSON而非YAML）

 

踩坑预警：新版OpenClaw（2026+）配置文件为 openclaw.json （JSON格式），而非旧版的 config.yaml ，用YAML会直接失效！

 

bash

# 覆盖写入最简配置（禁用所有插件/渠道，仅启动核心服务）

cat > ~/.openclaw/openclaw.json << EOF

{

  "meta": {

    "lastTouchedVersion": "2026.2.26"

  },

  "server": {

    "host": "127.0.0.1",

    "port": 18789

  },

  "webSearch": {

    "enabled": false # 禁用网页搜索，避免Brave API提示

  },

  "channels": {},

  "plugins": {

    "allow": []

  }

}

EOF

 

 

3.2 启动核心服务（纠正命令错误）

 

踩坑预警：OpenClaw无 serve 命令，旧版 openclaw tui - ws://xxx 参数格式也失效！

 

方式1：启动网关（后台服务，推荐）

 

bash

# 杀死残留进程（避免端口占用）

pkill -f openclaw

 

# 启动网关（核心服务，无多余提示）

openclaw gateway

 

 

启动成功日志：

 

plaintext

🦞 OpenClaw 2026.2.26 (bc50708)

[gateway] starting server on ws://127.0.0.1:18789

[gateway] server ready, listening for connections

[web-search] skipped (disabled in config)

 

 

方式2：启动TUI交互界面

 

bash

openclaw tui

 

 

启动成功标志：进入 Wake up, my friend! 交互界面，无网页搜索配置提示。

 

四、飞书渠道对接（可选，重点避坑）

 

若需对接飞书（长连接模式，无需公网IP），按以下步骤配置：

 

4.1 飞书开放平台获取2个核心凭证

 

1. 登录飞书开放平台：https://open.feishu.cn/

2. 创建自定义应用，进入应用详情页：

-  AppID ：「凭证与基础信息」→ 复制（以 cli_ 开头）

-  AppSecret ：「凭证与基础信息」→ 复制

3. 事件订阅配置：

- 订阅方式选择「使用长连接接收事件」

- 添加事件： im.message.receive_v1 、 im.message.created_v1 

- 发布应用：「版本管理与发布」→ 创建版本 → 提交审核（选「仅自己可见」，无需审核）

 

4.2 命令行添加飞书账号并配置长连接（核心：add命令）

 

实际部署中优先使用OpenClaw内置的 channels add 命令添加飞书账号（更贴合官方规范，避免手动改JSON出错），步骤如下：

 

bash

# 1. 给飞书渠道添加main账号（核心：add命令，按提示输入AppID和AppSecret）

openclaw channels add feishu main

# 执行后终端会交互式提示输入：

# ? App ID: 粘贴你的飞书AppID（cli_开头）

# ? App Secret: 粘贴你的飞书AppSecret

# ? Verification Token: 直接回车（无需填写）

# 提示 "Channel account feishu:main added successfully" 即为添加成功

 

# 2. 启用飞书渠道

openclaw config set channels.feishu.enabled true

 

# 3. 配置飞书长连接核心参数

openclaw config set channels.feishu.useLongPolling true # 开启长连接（无需公网IP）

openclaw config set channels.feishu.reconnect true # 断网自动重连

openclaw config set channels.feishu.dmPolicy pairing # 消息策略默认值

 

# 4. 配置飞书监听事件（接收@机器人消息必备）

openclaw config set channels.feishu.events '["im.message.receive_v1","im.message.created_v1"]'

 

# 5. 允许并启用飞书插件（解决默认禁用问题）

openclaw config set plugins.allow '["feishu"]'

openclaw plugins enable feishu # 强制启用飞书插件

 

 

4.3 验证配置并启动

 

bash

# 验证飞书账号是否添加成功

openclaw channels list

# 正常输出应包含：

# ┌─────────┬─────────┬─────────────────┐

# │ Channel │ Enabled │ Accounts │

# ├─────────┼─────────┼─────────────────┤

# │ feishu │ true │ main (enabled) │

# └─────────┴─────────┴─────────────────┘

 

# 启动网关，监听飞书长连接

openclaw gateway

 

 

飞书连接成功日志：

 

plaintext

[channels.feishu] initializing long polling client for account: main

[channels.feishu] long polling connected to feishu open platform

[channels.feishu] listening to events: im.message.receive_v1, im.message.created_v1

 

 

五、常见踩坑与解决方案（核心重点）

 

踩坑现象 根本原因 解决方案 

 error: unknown command 'serve'  OpenClaw无 serve 命令 改用 openclaw gateway （网关）或 openclaw tui （交互） 

 error: too many arguments for 'tui'  旧版参数格式失效（ - ws://xxx ） 新版 tui 无需传任何参数，直接执行 openclaw tui  

飞书插件显示 Status: disabled  新版飞书插件默认禁用 执行 openclaw plugins enable feishu 强制启用 

长连接提示“未检测到应用连接信息” 先配飞书平台再启动OpenClaw 先启动 openclaw gateway ，再回飞书平台保存事件订阅配置 

网页搜索功能未配置提示 默认启用搜索功能，缺Brave API 配置 "webSearch": {"enabled": false} 或启动时加 --skip-web-search  

飞书插件重复加载警告 本地扩展与内置插件冲突 删除本地插件目录： rm -rf ~/.openclaw/extensions/feishu  

 channels add 命令执行失败 终端交互输入时格式错误 AppID/AppSecret粘贴时避免多余空格，Verification Token直接回车跳过 

 

六、日志调试：实时查看@机器人反馈

 

部署后需验证飞书@机器人是否生效，推荐2种日志查看方式：

 

6.1 启动时开启DEBUG级日志（实时详细）

 

bash

OPENCLAW_LOG_LEVEL=debug openclaw gateway

 

 

@机器人后，日志会显示：

 

plaintext

[debug] [channels.feishu] long polling received event: im.message.receive_v1

[debug] [channels.feishu] parsed message: {"content":"@机器人 测试","mentions":["机器人ID"]}

 

 

6.2 后台运行+实时跟踪日志文件

 

bash

# 后台启动网关，日志输出到文件

nohup openclaw gateway > ~/.openclaw/openclaw.log 2>&1 &

 

# 实时过滤飞书/消息相关日志

tail -f ~/.openclaw/openclaw.log | grep -E "feishu|message|mention"

 

 

七、总结

 

1. 树莓派5部署OpenClaw核心是“先启动核心服务，再按需配置渠道”，避免一步到位踩坑；

2. 新版（2026+）飞书对接核心：用 openclaw channels add 命令添加账号（交互式输入更便捷），无需手动编辑JSON，且无需配置Verification Token；

3. 飞书对接关键：长连接模式无需公网IP，必须先启动OpenClaw再保存飞书平台配置；

4. 日志调试是排查问题的核心，DEBUG级日志能清晰看到@机器人的每一步反馈。