Title: 全网最细！OpenClaw 本地部署教程和常见问题汇总 | BestBlogs.dev
URL Source: https://www.bestblogs.dev/article/d74346d5
Published Time: 2026-03-11 00:45:00
Markdown Content: 原创 徐晓虎 2026-03-11 08:45 北京
关注腾讯云开发者，一手技术干货提前解锁👇
周末花了一整天在我的 Mac 电脑上进行 OpenClaw 本地部署以及整理问题。作为非程序的出身，加上国内环境问题，实现本地部署一个满血版的 OpenClaw，总的来说对于小白来说相对比较困难，不要太相信网上说十分钟部署好，中间不知道省略多少认证和准备，所以我把自己遇到的问题以及在网上检索到大多数人常遇到的做了一个汇总整理，当你信心满满找到一个教程遇到卡点，不妨搭配本文来食用，相信你可以2、3个小时就可以拥有一个真正的私人助理。
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
【推荐】手动安装
（由于大多数没有权限，直接推荐：sudo npm install -g openclaw@latest）
# 如果一键脚本失败，可以手动安装
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：找不到 npm 全局路径
症状：
openclaw: command not found
解决方案：
# 1. 找到 npm 全局路径
npm prefix -g
# 2. 添加到 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
# 3. 如果使用 nvm
# 确保 ~/.zshrc 或 ~/.bashrc 中包含 nvm 初始化脚本
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
❌问题7： moltbot@latest 占位符问题
⚠️ 严重问题：这是导致很多用户安装失败的 核心原因
问题描述：
# 执行安装
npm install -g moltbot@latest
# 安装成功，但运行 moltbot 命令失败
moltbot: command not found
原因（来自 GitHub Issue#3275）：
* npm 中的moltbot@latest指向一个 283 字节的占位符包
* 由非官方用户consistent_lee上传
* 真正的项目代码在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 UI（推荐）
openclaw dashboard
3.2 配置向导选项说明
配置向导关键步骤
步骤 1：风险确认
I understand this is powerful and inherently risky. Continue?
* ✅ 必须选择 “Yes” 继续
* OpenClaw 具有读写文件、执行命令的权限
步骤 2：选择 Onboarding 模式
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. 检查 Gateway 状态
openclaw status
# 2. 检查端口是否被占用
lsof -i :18789
netstat -tlnp | grep 18789
# 3. 手动启动 Gateway（前台模式，查看详细日志）
openclaw gateway --verbose
# 4. 如果端口被占用，使用其他端口
openclaw gateway --port 18790
4.2 服务启动后自动停止
症状：启动后几秒自动关闭
原因：
* 配置文件错误
* API Key 无效
* 磁盘空间不足
* 模型连接失败
解决方案：
# 1. 查看详细错误日志
openclaw doctor
# 2. 检查日志文件
cat ~/.openclaw/logs/*.log
# 3. 检查配置文件
cat ~/.openclaw/openclaw.json | python3 -m json.tool # macOS/Linux
# 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：使用 Amphetamine 等工具
# App Store 免费下载，保持 Mac 唤醒
# 方法3：如果使用云服务器，不存在此问题
# 方法4：买个Mac mini吧！
4.4 进程守护问题
症状：关闭终端后服务停止
解决方案：
# 方法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
4.6 Homebrew 安装问题
症状：使用 brew 安装 node 后找不到命令
解决方案：
# 1. 确保 Homebrew 在 PATH 中
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
# 2. 验证 Homebrew
brew doctor
# 3. 添加 Homebrew 到 PATH（Apple Silicon）
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 4. 如果使用 Intel Mac
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
05 --
飞书接入问题
更多 IM 接入教程请访问腾讯云开发者社区 OpenClaw 专区查看：https://cloud.tencent.com/developer/article/2624973
5.1 飞书插件安装失败
错误信息：
spawn npm ENOENT
原因：
* npm 路径未正确配置
* 权限问题
解决方案：
# 1. 确保 npm 在 PATH 中
which npm
# 2. 使用完整路径安装
sudo $(npm prefix -g)/bin/npm install -g @m1heng-clawd/feishu
# 3. 或者重新配置 PATH
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
5.2 飞书完整配置步骤
步骤 1：创建飞书应用
- 访问飞书开放平台：https://open.feishu.cn
- 注册/登录开发者账号
- 点击右上角 → 开发者后台
- 创建应用 → 填写应用名称和描述
在应用页面，找到：
* App ID
* App Secret
步骤 3：添加机器人能力
- 进入应用详情
- 添加能力 → 选择 “机器人”
- 配置机器人相关设置
开通以下权限：
* im:message
* im:message:send_as_bot
* im:chat:readonly
* 其他消息相关权限
步骤 5：安装飞书插件
openclaw plugins install @m1heng-clawd/feishu
步骤 6：配置飞书渠道
openclaw configure
# 选择 Channels → Feishu
# 输入 App ID 和 App Secret
# 选择中国区服务器
步骤 7：配置事件回调
- 在飞书后台配置事件订阅
- 使用长连接接收事件（一定要先安装飞书插件和渠道，不然设置不了）
- 添加消息事件
- 发布版本并审批
常用命令速查
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 设备管理
| 命令 | 功能 |
| --- | --- |
| openclaw devices list | 查看已授权设备 |
| openclaw devices approve <id> | 授权设备 |
| openclaw devices revoke <id> | 撤销授权 |
6.5 模型管理
| 命令 | 功能 |
| --- | --- |
| openclaw models status | 查看模型状态 |
| openclaw models status --probe | 测试模型连接 |
6.6 官方资料
* 官方文档：https://docs.openclaw.ai
* 官方安装指南：https://docs.openclaw.ai/install
07 --
结语
OpenClaw 作为一款强大的本地 AI 助手，虽然初始配置有一定门槛，但一旦配置完成，将成为您 24/7 待命的智能助手。整理了 mac 用户最常遇到的问题和解决方案，希望有所帮助。现在每天晚上的乐趣就是看看社区上有没有人利用 OpenClaw 发掘好玩且实用的应用场景，也欢迎大家一同来分享一下~
猜你所想彩蛋时刻
目前，腾讯轻量云 Lighthouse 已支持秒速部署 OpenClaw，可快速接入企业微信、QQ、钉钉、飞书等国内主流 IM 软件，7X24小时在线、随时响应，轻松定制您的私人AI助理！
优惠活动直达码
OpenClaw 社群交流码
-End-
原创作者｜徐晓虎
感谢你读到这里，不如关注一下？👇
📢📢来抢开发者限席名额！点击下方图片直达👇 
你对本文内容有哪些看法？同意、反对、困惑的地方是？欢迎留言，我们将邀请作者针对性回复你的评论，欢迎评论留言补充。我们将选取1则优质的评论，送出腾讯云定制文件袋套装 1个（见下图）。3月18日中午12点开奖。
扫码领取腾讯云开发者专属服务器代金券！
!Image 9   