OpenClaw-Linux 部署教程
📋 目录
1. 核心认知：为什么选择 OpenClaw
OpenClaw 是运行在本地服务器上的高权限 AI 智能体，相比云端 SaaS 服务，其核心优势在于：
- 数据隐私：数据完全本地化，自主可控。
- 高权限操作：支持执行 Shell 命令、读写文件、编写代码、控制浏览器。
- 多平台集成：原生支持飞书、Telegram、WhatsApp 等。
- 持久记忆：记住用户偏好和上下文。
2. 部署前准备：环境与工具
2.1 硬性环境要求
| 操作系统 | Linux (推荐) / macOS / Windows (WSL2) | 本文以 Linux 为例 |
| Node.js | ≥ 22.x | 必须，低版本会安装失败 |
| 内存 | ≥ 2GB (建议 4GB) | 2GB 内存必须配置虚拟内存 |
| 网络 | 可访问 GitHub, npm | 国内服务器建议配置镜像源或代理 |
| AI 模型 | 通义千问 (Qwen) / OpenAI 等 API Key | 推荐通义千问，有免费额度 |
2.2 必备凭证
3. 方案 A：阿里云一键部署（推荐小白）
如果您使用阿里云轻量应用服务器，可使用此方案，几分钟即可完成。
- 访问 OpenClaw 一键部署页面。
- 选择 OpenClaw 镜像。
- 配置建议：2核2GB 及以上，地域推荐美国弗吉尼亚或中国香港（网络更通畅）。
- 在服务器控制台“应用详情”页，点击 一键放通 端口 18789。
- 输入之前创建的 百炼 API Key 并执行配置命令。
- 生成 Token 后，点击“打开网站页面”或通过 http://公网IP:18789 访问。
- 输入 Token 即可开始使用。
4. 方案 B：Linux 手动部署全流程
适合所有 Linux 环境，步骤稍多但灵活性更高。
4.1 安装基础依赖
1. 安装 Git
sudo apt update
sudo apt install git -y
git –version
2. 安装 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
3. 配置虚拟内存 (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
4.2 安装 OpenClaw
执行官方一键安装脚本：
curl -fsSL https://openclaw.bot/install.sh | bash
注意：首次安装耗时约 5-10 分钟，请勿中断。若提示 npm install failed，请检查虚拟内存是否生效。
4.3 初始化配置向导
安装完成后会自动进入向导 (openclaw onboard)，按以下步骤操作：
- 终端会显示一个 URL 和验证码。
- 在本地浏览器打开该 URL，登录通义千问账号并授权。
- 授权成功后，终端会自动继续。
- 输入 Hello 测试响应。
- 按 Ctrl + C 退出终端界面。
4.4 访问 Web 管理面板
OpenClaw 默认监听本地端口 18789，需通过 SSH 隧道访问：
5. 核心步骤：对接飞书机器人
5.1 飞书开放平台配置
- 登录 飞书开放平台，进入“开发者后台” -> “创建企业自建应用”。
- 填写名称（如 OpenClaw），上传图标。
- 在“凭证与基础信息”中，复制 App ID 和 App Secret。
- 点击“应用能力” -> 添加“机器人”。
- 进入“权限管理”，搜索并开通以下权限：
- contact:user.base:readonly (获取用户信息)
- im:message (发送接收消息，勾选全部子项)
- im:chat (获取群组信息)
- 进入“事件与回调” -> “事件配置”。
- 订阅方式选“使用长连接”。
- 添加事件：im.message.receive.v1 (接收消息)。
- 进入“应用发布”，创建版本并发布（个人版自动通过）。
5.2 OpenClaw 配置飞书通道
重新进入配置向导：
openclaw onboard
(依次确认安全风险、QuickStart 模式、模型配置，直到通道选择页)
选择飞书：
- 在通道列表中选择 Feishu/Lark (飞书)。
- 选择 Download from npm 安装插件。
报错处理：若提示 Cannot find module 'zod'，请执行：
Ctrl + C 退出
npm install -g zod
rm -rf ~/.openclaw/extensions/feishu
openclaw onboard # 重试
填入凭证：
- 粘贴飞书 App ID。
- 粘贴飞书 App Secret。
配置策略：
- 域名：选择 Feishu (feishu.cn)。
- 群聊策略：选择 Open (允许在所有群被 @ 响应)。
- 私聊策略：保持默认 Open。
重启服务： 配置完成后，务必重启网关使配置生效：
openclaw gateway restart
5.3 验证
在飞书中搜索机器人名称，发送 Hello，若收到回复即表示对接成功。
6. 常用运维命令速查
| openclaw status | 查看运行状态 |
| openclaw dashboard | 获取 Web 面板访问链接 |
| openclaw gateway restart | 重启服务 (修改配置后必用) |
| openclaw onboard | 重新进入配置向导 |
| openclaw update | 更新到最新版本 |
| openclaw doctor | 诊断并修复常见问题 |
| openclaw skills install <名字> | 安装新技能插件 |
| openclaw uninstall | 卸载 OpenClaw |
7. 常见问题排查 (FAQ)
Q1: 安装时提示 npm install failed 或卡住？
- 原因：内存不足。
- 解决：检查是否已配置 2GB 虚拟内存 (free -h 查看 Swap 行)。若未配置，请按 4.1.3 步骤配置后重试。
Q2: 飞书机器人无响应？
- 检查清单：
- 飞书应用是否已发布（版本状态为“已上线”）？
- im:message 等权限是否已开通？
- App ID 和 Secret 是否填写正确？
- 是否执行了 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 刷新环境变量，或关闭终端重开。
