OpenClaw (ClawdBot) 本地部署实战：从安装到飞书接入的完整排错指南

周末，我在自己的 Mac 电脑上花了一整天时间部署 OpenClaw 并梳理遇到的各种问题。作为非程序员背景，加上众所周知的国内网络环境，想要成功部署一个功能完整的 OpenClaw，对新手来说并非易事。别太相信网上那些声称“十分钟搞定”的教程，它们往往省略了大量关键的认证和准备步骤。因此，我把自己踩过的坑以及网上搜索到的高频问题汇总于此。当你信心满满地跟着某个教程却遇到卡点时，不妨结合本文一起“食用”，相信你可以在两三个小时内，真正拥有一个24小时在线的私人数字助理。

01 认识 OpenClaw：更名、特性与硬件误区

1.1 名字变迁历史（重要！）

OpenClaw 在短短20天内经历了三次更名：从 ClawdBot 到 MoltBot，最后因法律原因定名为 OpenClaw，也被社区戏称为“大龙虾”。这直接导致了许多用户的困惑。虽然很多博主在视频开头会补充说明，但一些早期文档和教程中仍可能使用旧名称。请注意，在复制命令时，最好手动将其替换为最新的 openclaw。

1.2 核心特性

• 执行能力：不仅能回答问题，还能实际操作你的电脑（读写文件、执行命令、打开应用等）。
• 全天候运行：支持 24/7 待命，即使电脑睡眠也能执行任务（具体设置见4.3节）。
• 持久记忆：可以持续记住之前的对话上下文。
• 主动服务：能够主动发起对话和提醒。
• 开源免费：所有数据完全本地化处理，保障隐私。
• 多平台支持：可通过手机上的聊天软件，以对话方式驱动电脑上的 OpenClaw。
  • 国际：WhatsApp、Telegram、Discord、Slack、iMessage
  • 国内：飞书、钉钉

1.3 硬件要求误区

常见误区：“跑 AI 必须得用 Mac Mini 或高价 GPU 服务器”
实际情况：

• OpenClaw 对硬件要求极低。
• 最低配置：512MB - 1GB 内存即可运行。
• 推荐配置：2GB 以上内存（处理复杂任务更稳定）。
• 你家里吃灰的旧 Mac、或者几十块钱一个月的云服务器，都能轻松跑起来。

02 安装问题：从官方命令到各种报错解决方案

2.1 官方与推荐安装命令（Linux/macOS）

【官方】自动安装脚本

# 官方命令
curl -fsSL https://openclaw.ai/install.sh | bash

# 备用命令（如果上面的不行）
curl -fsSL https://molt.bot/install.sh | bash
curl -fsSL https://clawd.bot/install.sh | bash

【推荐】手动安装
（由于网络或权限问题，一键脚本常会失败，更推荐直接使用 npm 安装）

# 如果一键脚本失败，可以手动安装
npm install -g openclaw@latest

# 如果遇到权限问题
sudo npm install -g openclaw@latest

2.2 常见安装错误与解决方案

❌ 错误 1：npm error code 128（最常见）

问题描述：

npm error code 128
npm error! Failed to clone repository
fatal: Could not read from remote repository

原因分析：

• Git 未安装或版本过旧。
• 国内网络访问 GitHub 缓慢或超时。

解决方案：

# 1. 检查 Git 安装
git --version

# 2. 如果未安装，进行安装
# macOS:
brew install git

# Linux (Ubuntu/Debian):
sudo apt-get install git

# Linux (CentOS):
sudo yum install git

❌ 错误 2：Node.js 版本不满足要求

问题描述：

EBADENGINE Unsupported engine
requires node >=22.12.0

解决方案：

# 1. 检查当前版本
node -v

# 2. 使用 nvm 升级（推荐）
nvm install 24
nvm use 24

# 3. 验证版本
node -v # 应该显示 v24.x.x

# 4. 如果使用 Homebrew
brew update
brew upgrade node

❌ 错误 3：ENOENT（文件路径错误）

问题描述：

ENOENT: Could not read package.json

原因分析：npm 缓存损坏。
解决方案：

# 清理 npm 缓存
npm cache clean --force

# 删除损坏的 npx 缓存
rm -rf ~/.npm/_npx

# 重新安装
npm install -g openclaw@latest

❌ 错误 4：EACCES（权限 denied）

问题描述：

EACCES: permission denied

原因分析：npm 全局目录权限不足，在 macOS/Linux 上常见。
解决方案：

# 方法1：使用 sudo（不推荐）
sudo npm install -g openclaw@latest

# 方法2：修改 npm 默认目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw@latest

❌ 问题5：macOS 额外依赖

# 安装 Xcode Command Line Tools
xcode-select --install

# 如果遇到 libvips 问题，安装 Homebrew 后使用
brew install vips

❌ 问题6：安装后找不到命令

症状：

openclaw: command not found

解决方案：

# 1. 找到 npm 全局安装路径
npm prefix -g

# 2. 将该路径下的 bin 目录添加到系统 PATH 环境变量中
# zsh (macOS 默认)
echo 'export PATH="'$(npm prefix -g)'/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# bash (Linux 默认)
echo 'export PATH="'$(npm prefix -g)'/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

❌ 问题7：moltbot@latest 占位符问题

⚠️ 严重问题：这是导致很多用户安装失败的核心原因。

问题描述：

# 执行安装（使用旧名称）
npm install -g moltbot@latest
# 安装看似成功，但运行命令失败
moltbot: command not found

原因（来自 GitHub Issue）：

• npm 上的 moltbot@latest 指向一个仅 283 字节的占位符包。
• 真正的项目代码在 moltbot@beta（版本 2026.1.27-beta.1，大小 41MB）。

解决方案：

# 正确安装方式（使用 beta 版本）
npm install -g moltbot@beta

# 或者直接安装最新更名后的 openclaw（推荐）
npm install -g openclaw@latest

03 配置问题：初始化与向导详解

3.1 初始化配置标准流程

# 1. 初始化配置目录
openclaw setup

# 2. 进入配置向导（首次安装，推荐安装为守护进程）
openclaw onboard --install-daemon

# 3. 启动核心网关服务
openclaw gateway

# 4. 打开 Web 管理界面（推荐，更直观）
openclaw dashboard

3.2 配置向导关键步骤说明

• 步骤1：风险确认

  I understand this is powerful and inherently risky. Continue?

  ✅ 必须选择 “Yes” 才能继续。请谨记，OpenClaw 被授予了读写文件、执行命令的高权限。

• 步骤2：选择配置模式

  Onboarding mode: QuickStart / Manual

  推荐选择 QuickStart。

• 步骤3：配置 AI 模型

  • 建议初次尝试时使用国内模型以降低成本，例如免费的 Qwen，先完成基础配置。
  • （个人吐槽：我一开始用了 minimax，每发一个指令就要4毛钱，实在有点肉疼。）

• 步骤4：选择通讯渠道

  • 国内用户（推荐）：飞书、钉钉
  • 国际用户：WhatsApp、Telegram、iMessage

• 步骤5：Skills 技能配置

  • 可选择 “Yes” 安装常用技能包。
  • 也可跳过，后续通过 openclaw config 命令再次配置。

3.3 配置相关常见问题

❌ 问题：配置向导卡住不动
解决方案：

# 1. 按 Ctrl + C 中断当前进程
# 2. 重新运行配置向导
openclaw onboard

# 3. 如果还是不行，尝试重置配置
openclaw setup --reset config

❌ 问题：忘记保存或需要修改配置
解决方案：

# 重新进入配置界面
openclaw configure

❌ 问题：配置文件格式错误
解决方案：

# 1. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 2. 使用内置诊断工具检查
openclaw doctor

# 3. 如果诊断出问题，重新运行完整配置向导
openclaw onboard --install-daemon

04 运行时问题：服务管理与故障排除

4.1 Gateway 网关无法启动

症状：

• 浏览器访问 http://127.0.0.1:18789 拒绝连接。
• 提示 “Connection refused”。
• openclaw status 显示 offline。

排查步骤：

# 1. 检查服务状态
openclaw status

# 2. 检查默认端口(18789)是否被其他程序占用
lsof -i :18789
# 或
netstat -tlnp | grep 18789

# 3. 在前台模式启动，查看详细日志输出
openclaw gateway --verbose

# 4. 如果端口被占用，换一个端口启动
openclaw gateway --port 18790

4.2 服务启动后自动停止

症状：进程启动几秒钟后自动退出。
原因：

• 配置文件（如 API Key）错误。
• 磁盘空间不足。
• 无法连接到配置的 AI 模型。

解决方案：

# 1. 运行诊断命令查看详细错误
openclaw doctor

# 2. 直接查看日志文件
cat ~/.openclaw/logs/*.log

# 3. 检查配置文件格式是否正确（macOS/Linux）
cat ~/.openclaw/openclaw.json | python3 -m json.tool

# 4. 重新配置
openclaw onboard --install-daemon

4.3 macOS 睡眠导致服务停止

症状：Mac 进入睡眠状态后，OpenClaw 服务停止运行。
原因：Mac 睡眠时 CPU 停止工作，自然所有进程都会暂停。

解决方案：

# 方法1：通过命令行修改电源设置（需要管理员权限）
sudo pmset -a standby 0
sudo pmset -a hibernatemode 0
sudo pmset -a sleep 0
sudo pmset -a displaysleep 0

# 方法2：使用第三方工具（如 App Store 免费的 Amphetamine）保持 Mac 唤醒。

# 方法3：如果你部署在云服务器上，则不存在此问题。

4.4 进程守护与后台运行

症状：关闭终端窗口后，OpenClaw 服务随之停止。
解决方案：

# 方法1：安装为系统服务（推荐，最稳定）
openclaw gateway install

# 方法2：使用 nohup 在后台运行
nohup openclaw gateway > /tmp/openclaw.log 2>&1 &

# 方法3：使用 systemd 管理（Linux 系统）
# 创建服务配置文件 /etc/systemd/system/openclaw.service
sudo nano /etc/systemd/system/openclaw.service

systemd 配置示例：

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=你的用户名
ExecStart=/usr/local/bin/openclaw gateway
Restart=always

[Install]
WantedBy=multi-user.target

# 保存后，启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

4.5 升级后服务无法启动

症状：更新 OpenClaw 版本后，Gateway 启动失败。
解决方案：

# 1. 确认当前版本
openclaw --version

# 2. 尝试重启服务
openclaw gateway stop
openclaw gateway start

# 3. 如果不行，清除可能冲突的缓存
rm -rf ~/.openclaw/cache/*
openclaw gateway start

05 飞书接入详细配置

5.1 飞书插件安装失败

错误信息：

spawn npm ENOENT

原因：系统未正确找到 npm 命令的路径。
解决方案：

# 1. 确认 npm 路径
which npm

# 2. 使用完整路径安装飞书插件
sudo $(npm prefix -g)/bin/npm install -g @m1heng-clawd/feishu

# 3. 或将 npm 全局路径永久加入环境变量
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

5.2 飞书完整配置步骤

步骤 1：创建飞书应用

1. 访问飞书开放平台。
2. 注册/登录开发者账号。
3. 点击右上角进入“开发者后台”。
4. 创建企业自建应用，填写名称和描述。

步骤 2：获取应用凭证
在应用“凭证与基础信息”页面，找到：

• App ID
• App Secret

步骤 3：启用机器人能力

1. 进入应用详情页。
2. “添加能力” → 选择“机器人”。
3. 配置机器人名称、头像等。

步骤 4：配置 API 权限
在“权限管理”页面，开通以下权限：

• im:message
• im:message:send_as_bot
• im:chat:readonly
• 以及其他所需的消息接收发送权限。

步骤 5：在 OpenClaw 中安装飞书插件

openclaw plugins install @m1heng-clawd/feishu

步骤 6：配置飞书通信渠道

openclaw configure
# 选择 Channels → Feishu
# 输入上一步获取的 App ID 和 App Secret
# 服务器区域选择“中国区”

步骤 7：在飞书后台配置事件订阅（关键）

1. 在飞书应用后台，进入“事件订阅”页面。
2. 必须先在 OpenClaw 中完成上述插件和渠道配置，否则无法获取必要的回调 URL 和 Token。
3. 根据 OpenClaw Web UI (openclaw dashboard) 或命令行提示的 URL 和 Token，填写到飞书后台。
4. 添加需要订阅的事件，如“接收消息”、“消息已读”等。
5. 发布应用版本，并邀请其他成员安装测试。

06 常用命令速查手册

6.1 核心配置命令

命令	功能
openclaw setup	初始化配置目录
openclaw onboard	进入交互式配置向导
openclaw onboard --install-daemon	配置并安装为系统守护进程
openclaw configure	修改现有配置
openclaw status	查看运行状态
openclaw health	进行健康检查
openclaw doctor	诊断系统问题
openclaw --version	查看版本信息

6.2 服务管理命令

命令	功能
openclaw gateway start	启动网关服务
openclaw gateway stop	停止网关服务
openclaw gateway restart	重启网关服务
openclaw gateway --verbose	前台启动并输出详细日志
openclaw gateway install	安装为系统服务

6.3 插件管理命令

命令	功能
openclaw plugins list	列出已安装插件
openclaw plugins install <name>	安装指定插件
openclaw plugins remove <name>	卸载指定插件

6.4 官方资料

• 官方文档：https://docs.openclaw.ai
• 官方安装指南：https://docs.openclaw.ai/install

07 结语

OpenClaw 作为一款能力强大的本地 AI 助手，虽然初始配置会遇到一些门槛，尤其在国内网络环境和复杂的 Node.js 生态下，但一旦成功部署，它就能成为一个真正为你所用的 24/7 智能伙伴。本文汇总的问题主要集中在 Mac 平台，但大部分思路也适用于 Linux 环境。

部署完成后，真正的乐趣在于探索其应用场景。无论是自动化日常操作、管理个人知识库，还是作为开发助手，OpenClaw 所代表的 AI Agent 方向都充满潜力。目前，我也在持续关注社区里大家分享的各种新奇玩法。如果你在部署过程中有更巧妙的解决方法，或者发现了有趣的应用案例，欢迎在 云栈社区 与其他开发者交流分享。