从入门到上手：OpenClaw本地部署与常见问题集锦

lurenjia · 2026 年3 月 11 日 08:06

周末我在 Mac 上花了一整天部署 OpenClaw 并整理遇到的问题。因为我不是程序出身，加上国内网络和环境的特殊性，要在本地把一个功能齐全的 OpenClaw 搭起来对小白来说确实不太容易。别太相信网上那些“十分钟部署好”的说法——很多认证和准备步骤被省略了。为此我把自己碰到的坑以及网上大家常遇到的问题做了汇总。如果你按教程操作时卡住了，不妨配着本文一起看，通常两到三小时就能把真正的私人助理搭起来。

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](javascript:;)）：

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 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

Winterlynn · 2026 年3 月 11 日 09:59

真部署了下来，茫茫然不知道该做什么

ocean_breeze · 2026 年3 月 11 日 11:09

Mac部署确实坑多

rocket_man · 2026 年3 月 11 日 12:14

十分钟部署是骗人的

morning_coffee · 2026 年3 月 11 日 12:41

我花了大半天才搞定

starlight99 · 2026 年3 月 11 日 13:46

网络问题最头疼

thinking_cat · 2026 年3 月 11 日 14:55

Docker部署会不会简单点

xiaoming_tech · 2026 年3 月 11 日 15:33

Docker确实方便很多

code_explorer · 2026 年3 月 11 日 16:40

认证那步卡了我好久

digital_nomad · 2026 年3 月 11 日 17:09

配着这篇文章终于装好了

silent_reader · 2026 年3 月 11 日 17:33

小白友好的部署教程不多

lucky_clover · 2026 年3 月 11 日 17:57

Windows上也差不多的坑

ocean_breeze · 2026 年3 月 11 日 18:25

网络问题挂个代理就行

rocket_man · 2026 年3 月 11 日 18:44

npm依赖冲突遇到过吗

morning_coffee · 2026 年3 月 11 日 19:58

遇到过删了node_modules重装

thinking_cat · 2026 年3 月 11 日 20:12

感谢推荐Docker方案

starlight99 · 2026 年3 月 11 日 21:03

代理配好就顺畅了

xiaoming_tech · 2026 年3 月 11 日 22:23

node版本也要注意

code_explorer · 2026 年3 月 11 日 23:48

建议用nvm管理node版本

digital_nomad · 2026 年3 月 11 日 23:54

两三个小时够了实测