ReaderMX.
云加社区

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

云徐晓虎约 10 分钟
关注腾讯云开发者，一手技术干货提前解锁👇

周末花了一整天在我的 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 | bashcurl -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 128npm error! Failed to clone repositoryfatal: 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 enginerequires node >=22.12.0

解决方案：

# 1. 检查当前版本node -v
# 2. 使用 nvm 升级（推荐）nvm install 24nvm use 24
# 3. 验证版本node -v# 应该显示 v24.x.x
# 4. 如果使用 Homebrewbrew updatebrew 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-globalnpm config set prefix '~/.npm-global'echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrcsource ~/.zshrcnpm install -g openclaw@latest

❌问题5：macOS 额外依赖

# 安装 Xcode Command Line Toolsxcode-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"' >> ~/.zshrcsource ~/.zshrc
# bash (Linux 默认)echo 'export PATH="'$(npm prefix -g)'/bin:$PATH"' >> ~/.bashrcsource ~/.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
# 或者直接安装 openclawnpm 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 :18789netstat -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 0sudo pmset -a hibernatemode 0sudo pmset -a sleep 0sudo 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.servicesudo nano /etc/systemd/system/openclaw.service
# systemd 配置示例：[Unit]Description=OpenClaw GatewayAfter=network.target
[Service]Type=simpleUser=你的用户名ExecStart=/usr/local/bin/openclaw gatewayRestart=always
[Install]WantedBy=multi-user.target
# 启用并启动sudo systemctl daemon-reloadsudo systemctl enable openclawsudo systemctl start openclaw

4.5 升级后服务无法启动

症状：更新 OpenClaw 后 Gateway 启动失败

解决方案：

# 1. 检查版本openclaw --version
# 2. 重启服务openclaw gateway stopopenclaw 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)"' >> ~/.zshrcsource ~/.zshrc
# 2. 验证 Homebrewbrew doctor
# 3. 添加 Homebrew 到 PATH（Apple Silicon）echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrcsource ~/.zshrc
# 4. 如果使用 Intel Macecho 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrcsource ~/.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. 或者重新配置 PATHecho 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrcsource ~/.zshrc

5.2 飞书完整配置步骤

步骤 1：创建飞书应用

  1. 访问飞书开放平台：https://open.feishu.cn

  2. 注册/登录开发者账号

  3. 点击右上角 → 开发者后台

  4. 创建应用 → 填写应用名称和描述

步骤 2：获取应用凭证

在应用页面，找到：

  • App ID

  • App Secret

步骤 3：添加机器人能力

  1. 进入应用详情

  2. 添加能力 → 选择 “机器人”

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

  1. 在飞书后台配置事件订阅

  2. 使用长连接接收事件（一定要先安装飞书插件和渠道，不然设置不了）

  3. 添加消息事件

  4. 发布版本并审批

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助理！

优惠活动直达码

Image

OpenClaw 社群交流码

Image
-End-
原创作者｜徐晓虎
感谢你读到这里，不如关注一下？👇
图片
📢📢来抢开发者限席名额！点击下方图片直达👇
Image
Image
你对本文内容有哪些看法？同意、反对、困惑的地方是？欢迎留言，我们将邀请作者针对性回复你的评论，欢迎评论留言补充。我们将选取1则优质的评论，送出腾讯云定制文件袋套装1个（见下图）。3月18日中午12点开奖。
Image
扫码领取腾讯云开发者专属服务器代金券！
图片
Image
Image
Image
Image
Image

KEEP THE THREAD GOING

更多来源文章