OpenClaw Linux 本地部署及飞书集成实战

OpenClaw 是一款运行在本地服务器上的高权限 AI 智能体。相比云端 SaaS 服务，它的核心优势在于数据完全本地化、支持 Shell 命令与文件操作，并能原生对接飞书、Telegram 等渠道。下面我们来聊聊如何在 Linux 环境下把它跑起来。

环境准备

硬性要求

项目	要求	备注
操作系统	Linux (推荐) / macOS / Windows (WSL2)	本文以 Linux 为例
Node.js	≥ 22.x	必须，低版本会安装失败
内存	≥ 2GB (建议 4GB)	2GB 内存必须配置虚拟内存
网络	可访问 GitHub, npm	国内服务器建议配置镜像源或代理
AI 模型	通义千问 (Qwen) / OpenAI 等 API Key	推荐通义千问，有免费额度

必备凭证

通义千问 API Key：登录阿里云百炼控制台创建。
飞书开放平台账号：用于创建自建应用。
服务器信息：公网 IP、SSH 账号密码。

部署方案

方案 A：阿里云一键部署

如果你用的是阿里云轻量应用服务器，这个方案几分钟就能搞定。

购买实例：选择 OpenClaw 镜像。配置建议 2 核 2GB 及以上，地域推荐美国弗吉尼亚或中国香港（网络更通畅）。
配置 API Key：在服务器控制台'应用详情'页，点击 一键放通 端口 18789，输入 百炼 API Key 并执行配置命令。
访问面板：生成 Token 后，通过 http://公网 IP:18789 访问，输入 Token 即可开始使用。

方案 B：Linux 手动部署全流程

适合所有 Linux 环境，步骤稍多但灵活性更高。

1. 安装基础依赖

安装 Git

sudo apt update && sudo apt install git -y && git --version

安装 Node.js (v22+)
推荐使用 NVM 管理版本，国内用户可以用 Gitee 镜像源：

# 安装 NVM
curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash
# 加载环境变量
source ~/.bashrc
# 安装并使用 Node.js 22
nvm install 22
nvm use 22
# 验证版本
node -v # 应显示 v22.x.x
npm -v

配置虚拟内存 (2GB 内存服务器必做)
防止安装过程中因内存不足 (OOM) 导致失败，这一步很关键：

# 创建 2G 交换文件
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
# 验证
free -h

2. 安装 OpenClaw

执行官方一键安装脚本：

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

注意：首次安装耗时约 5-10 分钟，请勿中断。若提示 npm install failed，请检查虚拟内存是否生效。

3. 初始化配置向导

安装完成后会自动进入向导 (openclaw onboard)，按以下步骤操作：

安全确认：输入 Yes 确认知晓风险。
模式选择：选择 QuickStart (快速配置)。
模型选择：选择 Qwen (OAuth) (通义千问)。
授权登录：终端会显示一个 URL 和验证码。在本地浏览器打开该 URL，登录通义千问账号并授权。授权成功后，终端会自动继续。
模型确认：选择 Keep current 保持默认模型。
通道配置：选择 Skip for now (稍后单独配置飞书)。
技能配置：选择 No (稍后安装)。
启动方式：选择 Hatch in TUI 进入终端聊天测试。输入 Hello 测试响应，按 Ctrl + C 退出终端界面。

4. 访问 Web 管理面板

OpenClaw 默认监听本地端口 18789，需通过 SSH 隧道访问。

获取带 Token 的链接 (在服务器终端执行):

openclaw dashboard

本地终端执行 (替换为您的用户名和 IP):

ssh -N -L 18789:127.0.0.1:18789 用户名@服务器公网IP

对接飞书机器人

1. 飞书开放平台配置

创建应用：登录飞书开放平台，进入'开发者后台' -> '创建企业自建应用'，填写名称并上传图标。
获取凭证：在'凭证与基础信息'中，复制 App ID 和 App Secret。
添加机器人能力：点击'应用能力' -> 添加'机器人'。
开通权限 (关键)：进入'权限管理'，搜索并开通以下权限：
- contact:user.base:readonly (获取用户信息)
- im:message (发送接收消息，勾选全部子项)
- im:chat (获取群组信息)
配置事件订阅：进入'事件与回调' -> '事件配置'。订阅方式选'使用长连接'，添加事件 im.message.receive.v1 (接收消息)。
发布应用：进入'应用发布'，创建版本并发布（个人版自动通过）。

2. OpenClaw 配置飞书通道

在通道列表中选择 Feishu/Lark (飞书)。
选择 Download from npm 安装插件。
填入凭证：粘贴飞书 App ID 和 App Secret。
配置策略：域名选择 Feishu (feishu.cn)；群聊/私聊策略均选择 Open。

重启服务：配置完成后，务必重启网关使配置生效：

openclaw gateway restart

报错处理：若提示 Cannot find module 'zod'，请重新进入配置向导：
openclaw onboard
(依次确认安全风险、QuickStart 模式、模型配置，直到通道选择页)

3. 验证

在飞书中搜索机器人名称，发送 Hello，若收到回复即表示对接成功。

常用运维命令速查

命令	功能描述
`openclaw status`	查看运行状态
`openclaw dashboard`	获取 Web 面板访问链接
`openclaw gateway restart`	重启服务 (修改配置后必用)
`openclaw onboard`	重新进入配置向导
`openclaw update`	更新到最新版本
`openclaw doctor`	诊断并修复常见问题
`openclaw skills install <名字>`	安装新技能插件
`openclaw uninstall`	卸载 OpenClaw

常见问题排查 (FAQ)

Q1: 安装时提示 `npm install failed` 或卡住？

原因：内存不足。
解决：检查是否已配置 2GB 虚拟内存 (free -h 查看 Swap 行)。若未配置，请按上文步骤配置后重试。

Q2: 飞书机器人无响应？

检查清单：
1. 飞书应用是否已发布（版本状态为'已上线'）？
2. im:message 等权限是否已开通？
3. App ID 和 Secret 是否填写正确？
4. 是否执行了 openclaw gateway restart？

查看日志：

# 查看技能运行日志
docker exec -it openclaw-2026 tail -f /opt/openclaw/logs/skills/run.log
# 或者查看系统日志
journalctl -u openclaw-gateway -f

Q3: Web 面板无法访问？

原因：SSH 隧道断开或 Token 失效。
解决：确保本地终端的 SSH 隧道命令正在运行，并在服务器执行 openclaw dashboard 获取最新带 Token 的链接。

Q4: `openclaw` 命令提示 `command not found`？

解决：执行 source ~/.bashrc 刷新环境变量，或关闭终端重开。