OpenClaw（小龙虾）搭建与重启流程全平台指南

本文档涵盖 OpenClaw 在 Windows、macOS、Linux（含 WSL2）三大平台的安装部署、启动停止、重启及开机自启配置全流程。

---

📋 目录

• 一、快速开始
• 二、安装前准备
• 三、Windows 平台搭建
• 四、macOS 平台搭建
• 五、Linux 平台搭建
• 六、初始化配置
• 七、服务管理：启动/停止/重启
• 八、开机自启配置
• 九、常见问题排查
• 十、更新与卸载

---

一、快速开始

OpenClaw 是什么？

OpenClaw（昵称"小龙虾"）是一个开源的本地 AI 智能体框架，能够通过自然语言指令自动执行文件操作、系统命令、网页自动化等任务。

核心特性

• ✅ 本地优先：数据存储在本地，隐私可控
• ✅ 多平台支持：Windows、macOS、Linux 全覆盖
• ✅ 技能扩展：通过 ClawHub 技能市场扩展功能
• ✅ 多模型接入：支持 OpenAI、Claude、阿里云百炼、本地模型等

最小配置要求

项目	最低要求	推荐配置
操作系统	Win10+ / macOS 12+ / Ubuntu 20.04+	Win11 / macOS 14+ / Ubuntu 22.04+
内存	4GB	8GB+
磁盘空间	2GB	10GB+
Node.js	v22+	v24 LTS

---

二、安装前准备

2.1 系统要求确认

Windows

• Windows 10 64位（版本 2004 及以上）或 Windows 11
• 强烈建议使用 WSL2（官方推荐更稳定）

macOS

• macOS 12.0+（Monterey 及以上）
• 支持 Intel 和 Apple Silicon（M1/M2/M3）全系列

Linux

• Ubuntu 20.04+、Debian 11+、CentOS 8+ 等主流发行版

2.2 核心依赖准备

必需依赖：Node.js ≥ v22

OpenClaw 使用了 Node.js 22 的新特性，低版本会导致安装失败。

安装 Node.js

Windows：

# 使用 winget 安装（推荐）
winget install OpenJS.NodeJS.LTS

# 或从官网下载安装包
# https://nodejs.org

macOS：

# 使用 Homebrew
brew install node@22

# 或使用 nvm（推荐用于版本管理）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Linux：

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs

验证安装：

node -v   # 应显示 v22.x.x 或更高
npm -v    # 应显示 10.x.x 或更高

其他依赖（可选）

• Git：用于克隆代码仓库和安装技能
• Python 3.9+：部分技能需要
• FFmpeg：视频处理技能需要

---

三、Windows 平台搭建

3.1 方案一：WSL2 + Ubuntu（官方推荐，最稳定）

步骤 1：安装 WSL2

# 以管理员身份打开 PowerShell
wsl --install

# 重启电脑，按提示设置 Ubuntu 用户名和密码

步骤 2：进入 WSL2 环境

# 打开 Ubuntu 终端
wsl

步骤 3：在 WSL2 中安装 OpenClaw

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Node.js（如果未安装）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 验证版本
node -v   # 应 ≥ v22.0.0

# 执行官方安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 国内用户加速版
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

步骤 4：验证安装

openclaw --version
# 应显示 OpenClaw CLI 版本号

3.2 方案二：PowerShell 一键安装（原生 Windows）

步骤 1：解锁 PowerShell 脚本执行权限

# 以管理员身份打开 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 输入 Y 确认

步骤 2：执行安装脚本

# 官方脚本
iwr -useb https://openclaw.ai/install.ps1 | iex

# 国内加速脚本（网络不佳时使用）
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

步骤 3：等待安装完成

• 耗时约 3-8 分钟（取决于网速）
• 出现 “OpenClaw installed successfully” 即成功

步骤 4：验证安装

openclaw --version

3.3 方案三：npm 手动安装（适合已有 Node.js 环境）

# 配置 npm 镜像（国内用户推荐）
npm config set registry https://registry.npmmirror.com

# 全局安装
npm install -g openclaw@latest

# 验证
openclaw --version

---

四、macOS 平台搭建

4.1 方案一：一键脚本安装（推荐，5分钟搞定）

# 打开终端（Terminal）

# 官方脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 国内加速脚本
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

# 重新加载 shell 配置
source ~/.zshrc    # Zsh 默认
# 或
source ~/.bashrc   # Bash 用户

# 验证安装
openclaw --version

4.2 方案二：npm 手动安装

# 使用 Homebrew 安装 Node.js（如果未安装）
brew install node@22

# 配置 npm 镜像（国内用户）
npm config set registry https://registry.npmmirror.com

# 全局安装
npm install -g openclaw@latest

# 验证
openclaw --version

4.3 特殊情况处理

Sharp 编译报错？

如果你系统全局安装了 libvips（通过 Homebrew），可能导致 sharp 编译失败：

# 强制使用预编译二进制
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

---

五、Linux 平台搭建

5.1 方案一：一键脚本安装（推荐）

# Ubuntu/Debian/CentOS 通用

# 官方脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 国内加速脚本
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

# 验证
openclaw --version

5.2 方案二：npm 手动安装

# 更新系统
sudo apt update && sudo apt upgrade -y   # Ubuntu/Debian
# 或
sudo yum update -y                       # CentOS/RHEL

# 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -   # Ubuntu/Debian
sudo apt install -y nodejs

# 或
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -      # CentOS/RHEL
sudo yum install -y nodejs

# 配置 npm 镜像（国内用户）
npm config set registry https://registry.npmmirror.com

# 全局安装
sudo npm install -g openclaw@latest

# 验证
openclaw --version

5.3 方案三：Docker 部署（服务器/隔离环境首选）

# 确保已安装 Docker

# 拉取镜像
docker pull openclaw/openclaw:latest

# 启动容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/openclaw-data:/root/.openclaw \
  --restart always \
  openclaw/openclaw:latest

# 进入容器完成初始化
docker exec -it openclaw openclaw onboard

---

六、初始化配置

安装完成后，必须运行初始化向导完成配置。

6.1 启动配置向导

openclaw onboard

6.2 配置流程（按提示操作）

步骤	选项	说明
1	安全确认	输入 Yes 继续
2	配置模式	选 QuickStart（新手推荐）或 Manual
3	模型提供商	选择 AI 模型服务
4	API Key	输入对应模型的 API 密钥
5	聊天平台	选择接入的平台（可跳过）
6	技能安装	选择是否安装基础技能

6.3 推荐配置

国内用户：

• 模型提供商：阿里云百炼、智谱 AI、硅基流动
• 聊天平台：飞书、钉钉

海外用户：

• 模型提供商：OpenAI GPT、Anthropic Claude
• 聊天平台：Telegram、WhatsApp

6.4 配置文件位置

配置完成后，配置文件位于：

• macOS/Linux: ~/.openclaw/openclaw.json
• Windows: %USERPROFILE%\.openclaw\openclaw.json

---

七、服务管理：启动/停止/重启

这是日常使用中最核心的操作。

7.1 基础命令（全平台通用）

操作	命令	说明
启动服务	openclaw gateway start	启动网关后台服务
停止服务	openclaw gateway stop	停止网关服务
重启服务	openclaw gateway restart	重启服务（修改配置后必做）
查看状态	openclaw gateway status	查看运行状态
打开控制台	openclaw dashboard	在浏览器打开 Web 界面

7.2 启动与访问

步骤 1：启动网关服务

# macOS/Linux/WSL2
openclaw gateway start

# Windows PowerShell
openclaw gateway start

步骤 2：验证服务状态

openclaw gateway status

# 正常输出示例：
# Gateway: bind=loopback (127.0.0.1), port=18789
# Dashboard: http://127.0.0.1:18789/
# RPC probe: success

步骤 3：访问 Web 控制台

在浏览器中打开：

http://127.0.0.1:18789
# 或
http://localhost:18789

7.3 常用启动参数

# 指定端口启动（避免端口冲突）
openclaw gateway start --port 19000

# 绑定到局域网（允许其他设备访问）
openclaw gateway start --bind lan

# 前台运行（调试模式，查看实时日志）
openclaw gateway run

# 强制启动（杀死占用端口的进程）
openclaw gateway start --force

7.4 重启场景

以下情况需要重启服务：

1. ✅ 修改配置文件后（openclaw.json）
2. ✅ 切换 AI 模型或更改 API Key
3. ✅ 启用/禁用插件或技能
4. ✅ 修改端口或其他网络设置
5. ✅ 服务卡死或异常时

---

八、开机自启配置

8.1 Windows 开机自启

方案一：安装为系统服务（推荐）

# 以管理员身份运行 PowerShell

# 安装为 Windows 计划任务（实现开机自启）
openclaw gateway install

# 启动服务
openclaw gateway start

# 验证状态
openclaw gateway status
# 应显示 Service: Scheduled Task (registered)

方案二：WSL2 + Windows 任务计划

# 以管理员身份打开 PowerShell

# 创建开机自启任务
$action = New-ScheduledTaskAction -Execute "wsl.exe" -Argument "-d Ubuntu --bash -lc 'systemctl --user start openclaw-gateway'"
$trigger = New-ScheduledTaskTrigger -AtLogOn
$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit (New-TimeSpan -Hours 0) -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName "OpenClaw_AutoStart" -Action $action -Trigger $trigger -Settings $settings -RunLevel Highest -Force

# 验证
Get-ScheduledTask -TaskName "OpenClaw_AutoStart"

8.2 macOS 开机自启

方案一：使用 LaunchAgent（推荐）

# 安装服务
openclaw gateway install

# 加载服务（将配置文件注册到 launchctl）
openclaw gateway bootstrap

# 启动服务
openclaw gateway start

# 验证
openclaw gateway status

开机自启已自动配置，无需额外操作。

方案二：使用 systemd（Linux/macOS 通用）

# 创建 systemd 服务文件
sudo tee /etc/systemd/system/openclaw.service << EOF
[Unit]
Description=OpenClaw AI Assistant
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=/usr/local/bin/openclaw gateway start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 重载并启用服务
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

# 验证
sudo systemctl status openclaw

8.3 Linux 开机自启

systemd 服务配置（推荐）

# 创建用户级服务文件
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/openclaw-gateway.service << EOF
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
ExecStart=$(which openclaw) gateway start
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
EOF

# 启用并启动服务
systemctl --user daemon-reload
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

# 开启 linger（防止 SSH 退出后服务被回收）
sudo loginctl enable-linger $(whoami)

# 验证
systemctl --user status openclaw-gateway

8.4 验证开机自启

重启电脑后，运行以下命令验证服务是否自动启动：

# 查看服务状态
openclaw gateway status

# 访问控制台验证
# 浏览器打开 http://127.0.0.1:18789

---

九、常见问题排查

9.1 服务无法启动

问题： 浏览器访问 http://127.0.0.1:18789 拒绝连接

排查步骤：

# 1. 检查服务状态
openclaw gateway status

# 2. 检查端口占用
# Linux/macOS
lsof -i :18789

# Windows
netstat -ano | findstr :18789

# 3. 强制启动
openclaw gateway start --force

# 4. 健康检查
openclaw doctor --fix

9.2 命令找不到

问题： 执行 openclaw 命令提示"不是内部或外部命令"

解决方法：

# macOS/Linux: 重新加载 shell 配置
source ~/.zshrc    # 或 source ~/.bashrc

# Windows: 关闭当前 PowerShell，重新以管理员身份打开

如果仍然无效，手动添加环境变量：

Windows PowerShell：

# 添加 npm 全局路径到 PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\$env:USERNAME\AppData\Roaming\npm", "User")

macOS/Linux：

# 添加到 shell 配置文件
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

9.3 Node.js 版本过低

问题： 提示 “Node.js version must be >= 22”

解决方法：

使用 nvm 管理 Node.js 版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载
source ~/.zshrc    # 或 source ~/.bashrc

# 安装并使用 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# 验证
node -v

9.4 端口被占用

问题： 提示 “Port 18789 is already in use”

解决方法：

# 方法 1：更换端口启动
openclaw gateway start --port 19000

# 方法 2：杀死占用进程
# Linux/macOS
lsof -i :18789    # 查看占用进程的 PID
kill -9 <PID>     # 杀死进程

# Windows
netstat -ano | findstr :18789      # 查看占用进程的 PID
taskkill /F /PID <PID>             # 杀死进程

9.5 网络连接失败

问题： 模型调用失败、依赖下载卡住

解决方法：

# 1. 配置 npm 镜像
npm config set registry https://registry.npmmirror.com

# 2. 使用代理（如果需要）
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

# 3. 重启服务
openclaw gateway restart

9.6 查看实时日志

# 查看实时日志
openclaw logs --follow

# 或直接查看日志文件
# macOS/Linux
tail -f ~/.openclaw/logs/gateway.log

# Windows
Get-Content -Path "$env:USERPROFILE\.openclaw\logs\gateway.log" -Wait -Tail 50

---

十、更新与卸载

10.1 更新 OpenClaw

# 更新 CLI 到最新版本
npm install -g openclaw@latest

# 或使用内置更新命令
openclaw update

# 重启服务
openclaw gateway restart

# 验证版本
openclaw --version

10.2 完全卸载

Windows

# 停止并卸载服务
openclaw gateway stop
openclaw gateway uninstall

# 卸载全局包
npm uninstall -g openclaw

# 清理配置文件（可选）
rm -r ~/.openclaw    # WSL2 内部

macOS/Linux

# 停止服务
openclaw gateway stop

# 卸载服务
systemctl --user disable openclaw-gateway    # Linux
openclaw gateway uninstall                  # macOS

# 卸载全局包
npm uninstall -g openclaw

# 清理配置文件（可选）
rm -rf ~/.openclaw

---

附录：常用命令速查表

服务管理

# 启动
openclaw gateway start

# 停止
openclaw gateway stop

# 重启（最常用）
openclaw gateway restart

# 状态
openclaw gateway status

# 打开控制台
openclaw dashboard

诊断工具

# 健康检查
openclaw doctor

# 自动修复
openclaw doctor --fix

# 查看版本
openclaw --version

# 查看日志
openclaw logs --follow

配置管理

# 初始化配置
openclaw onboard

# 重新配置
openclaw configure

# 查看配置
openclaw config get <key>

# 设置配置
openclaw config set <key> <value>

模型管理

# 列出模型
openclaw models list

# 查看模型状态
openclaw models status

# 设置默认模型
openclaw models set <provider/model>

---

结语

OpenClaw 是一款强大的本地 AI 智能体，正确安装和配置后，它将成为你工作和生活中的得力助手。

核心要点回顾：

1. ✅ Node.js 版本必须 ≥ v22
2. ✅ 修改配置后必须重启服务
3. ✅ 遇到问题优先运行 openclaw doctor --fix
4. ✅ 查看日志定位具体错误
5. ✅ 生产环境建议配置开机自启

官方资源：

• 官方文档：https://openclaws.io/docs
• GitHub 仓库：https://github.com/openclaw/openclaw
• 技能市场（ClawHub）：https://clawdhub.com

祝你使用愉快！🦞