全网最细！OpenClaw本地部署教程和常见问题汇总

腾讯云开发者

发布于 2026-03-12 21:44:13

350

关注腾讯云开发者，一手技术干货提前解锁👇

周末花了一整天在我的 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
注册/登录开发者账号
点击右上角 → 开发者后台
创建应用 → 填写应用名称和描述

步骤 2：获取应用凭证

在应用页面，找到：

App ID
App Secret

步骤 3：添加机器人能力

进入应用详情
添加能力 → 选择 “机器人”
配置机器人相关设置

步骤 4：配置权限

开通以下权限：

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：配置事件回调

在飞书后台配置事件订阅
使用长连接接收事件（一定要先安装飞书插件和渠道，不然设置不了）
添加消息事件
发布版本并审批

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 设备管理

命令	功能
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助理！

优惠活动直达码