OpenClaw本地部署教程和常见问题汇总

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

认识 OpenClaw

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

OpenClaw 在短短20天内经历了三次更名，从 ClawdBot 到 MoltBot ，又因为受到律师函，最终改名为 OpenClaw ，又被称为“大龙虾”。这是导致很多用户困惑的根源，很多博主也在视频开头提过，但是大都是补录的，一些早期文档教程中可能还是旧的名称，注意复制一些命令时，最好手动替换成最新的名字——OpenClaw 。

1.2 核心特性

1.3 硬件要求误区

常见误区：

“跑 AI 必须得用 Mac Mini 或高价 GPU

实际情况：

安装问题

2.1 官方一键安装命令（

【官方】自动安装

# 官方命令 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）

2.2 常见安装错误

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

问题描述：

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

原因分析：

解决方案：

# 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 缓存损坏

解决方案：

❌ 错误 4：EACCES（权限 denied）

问题描述：

EACCES: permission denied

原因分析：

解决方案：

# 方法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 占位符问题

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

问题描述：

原因（来自 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

配置问题

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?

步骤 2：选择 Onboarding 模式

Onboarding mode: QuickStart / Manual

步骤 3：配置 AI 模型

步骤 4：选择通讯渠道

步骤 5：Skills 配置

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

运行时问题

4.1 Gateway 无法启动

症状：

排查步骤：

# 1. 检查 Gateway 状态 openclaw status # 2. 检查端口是否被占用 lsof -i :18789 netstat -tlnp | grep 18789 # 3. 手动启动 Gateway（前台模式，查看详细日志） openclaw gateway --verbose # 4. 如果端口被占用，使用其他端口 openclaw gateway --port 18790

4.2 服务启动后自动停止

症状：启动后几秒自动关闭

原因：

解决方案：

# 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

飞书接入问题

更多 IM 接入教程请访问 OpenClaw 专区查看：https://cloud.tencent.com/developer/article/

5.1 飞书插件安装失败

错误信息：

spawn npm ENOENT

原因：

解决方案：

# 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：创建飞书应用

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

常用命令速查

6.1 核心命令

6.2 服务管理

6.3 插件管理

6.4 设备管理

6.5 模型管理

6.6 官方资料

OpenClaw本地部署教程和常见问题汇总

相关推荐