🇨🇳 简体中文 🇹🇼 繁體中文 🇯🇵 日本語 🇰🇷 한국어 🇮🇳 हिन्दी 🇧🇩 বাংলা 🇮🇩 Bahasa Indonesia 🇪🇸 Español 🇧🇷 Português 🇫🇷 Français 🇩🇪 Deutsch
首页 / 安装教程

安装教程

从零开始安装 OpenClaw，其实很简单！跟着下面的步骤一步一步来，大概 5-10 分钟就能搞定。别担心，我们会解释每一步在做什么。

📋 系统要求

在开始安装之前，先确认你的电脑满足这些基本要求：

  • Node.js 22 或更高版本 — 这是 OpenClaw 运行的基础环境（别担心，安装脚本会帮你检查）
  • 操作系统 — macOS、Linux、或 Windows（需要 WSL2）
  • 内存 — 至少 2GB 可用内存
  • 磁盘空间 — 至少 500MB 可用空间
  • 网络 — 需要联网下载和调用 AI 模型 API
ℹ️ 什么是 Node.js？ 简单来说，Node.js 就像一个"翻译官"，让你的电脑能够运行用 JavaScript 写的程序。OpenClaw 就是用 JavaScript 写的，所以需要 Node.js 来运行。你不需要学 JavaScript，只需要安装好 Node.js 就行。
ℹ️ 什么是 WSL2？ Windows 用户需要注意：OpenClaw 不直接在 Windows 上运行，而是需要 WSL2（Windows Subsystem for Linux 2），它相当于在 Windows 里装了一个迷你 Linux 系统。如果你用的是 Windows，安装脚本会自动帮你处理这个。

🌟 方法一：一键安装脚本（推荐新手使用！）

这是最简单的安装方式。只需要在终端里复制粘贴一行命令，脚本就会自动帮你完成所有事情。其实很简单，跟着做就行！

💡 什么是"终端"？ 终端就是一个可以输入文字命令的窗口。在 macOS 上叫"终端"（Terminal），在 Windows 上叫"PowerShell"或"命令提示符"。你可以在电脑上搜索"Terminal"或"终端"来找到它。
1

打开终端

按下 Command + 空格，输入"Terminal"，然后按回车。一个黑色（或白色）的命令行窗口就会弹出来。

2

复制粘贴安装命令

复制下面这行命令，粘贴到终端窗口里，然后按回车：

curl -fsSL https://openclaw.ai/install.sh | bash

这行命令会做以下几件事情：

  • 检查你的电脑上有没有安装 Node.js，如果没有就自动帮你安装
  • 下载并安装 OpenClaw 最新版
  • 运行初始配置向导（onboarding），引导你完成基本设置
3

等待安装完成

安装过程大概需要 2-5 分钟，取决于你的网速。你会看到终端里有一堆文字在滚动，这是正常的，别担心！安装完成后，会自动进入配置向导。

1

打开终端

在 Linux 上，你可以按 Ctrl + Alt + T 来打开终端，或者在应用菜单里搜索"Terminal"。

2

复制粘贴安装命令

跟 macOS 一样，复制下面的命令，粘贴到终端里，按回车：

curl -fsSL https://openclaw.ai/install.sh | bash

脚本会自动检查 Node.js、下载安装 OpenClaw、运行配置向导。

3

等待安装完成

耐心等待几分钟，看到配置向导的提示就说明安装成功了！

1

打开 PowerShell（以管理员身份运行）

在开始菜单搜索"PowerShell"，右键点击它，选择"以管理员身份运行"。这一步很重要，因为安装过程需要管理员权限。

2

复制粘贴安装命令

Windows 用户使用下面这个专用命令：

iwr -useb https://openclaw.ai/install.ps1 | iex

这个脚本会自动帮你：

  • 检查并配置 WSL2（如果还没安装的话）
  • 安装 Node.js
  • 下载安装 OpenClaw
  • 运行初始配置向导
3

等待安装完成

Windows 上的安装可能稍微慢一点（因为可能需要安装 WSL2），大概 5-10 分钟。安装完成后会自动进入配置向导。

⚠️ Windows 用户注意：安装 WSL2 后可能需要重启电脑。如果脚本提示你重启，请先重启，然后重新运行安装命令。

📦 方法二：通过 npm 安装

如果你已经熟悉 Node.js 和 npm（Node.js 的包管理器），可以用这种方式安装。这个方法给你更多的控制权。

1

确认 Node.js 已安装

打开终端，输入以下命令检查 Node.js 版本：

node --version

如果显示 v22.x.x 或更高版本，说明你已经准备好了。如果没有安装或版本太低，请先去 nodejs.org 下载安装最新版。

2

使用 npm 全局安装 OpenClaw

在终端中运行：

npm install -g openclaw@latest

解释一下这个命令：

  • npm install — 使用 npm 来安装软件
  • -g — 全局安装，这样在任何地方都能使用 openclaw 命令
  • openclaw@latest — 安装最新版本的 OpenClaw
3

运行初始配置并注册后台服务

安装完成后，运行：

openclaw onboard --install-daemon

这个命令做了两件事：

  • onboard — 启动配置向导，引导你完成初始设置（选择 AI 模型、输入 API 密钥等）
  • --install-daemon — 将 OpenClaw 注册为后台服务（daemon），这样它会在你开机时自动启动，不需要每次手动打开
💡 什么是 daemon（守护进程）？ 简单来说就是：一个在后台默默运行的程序，你看不到它的窗口，但它一直在工作。加上 --install-daemon 后，OpenClaw 会在后台安静地运行，随时等待你的消息。

🐳 方法三：Docker 安装

如果你喜欢使用 Docker（一种容器化技术），或者想让 OpenClaw 在一个完全隔离的环境中运行，可以选择这种方式。

ℹ️ 什么是 Docker？ Docker 就像一个"虚拟盒子"，你可以把软件放在里面运行。这样即使软件出了问题，也不会影响你的电脑。如果你不知道 Docker 是什么，建议使用方法一或方法二来安装。
1

确保 Docker 已安装

如果你还没安装 Docker，去 docker.com 下载安装 Docker Desktop。

2

运行 OpenClaw Docker 容器

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  ghcr.io/openclaw/openclaw:latest

这个命令会下载 OpenClaw 的 Docker 镜像并启动容器。-v 参数把配置文件映射到你的电脑上，这样数据不会丢失。

✅ 安装后验证

安装完成后，让我们确认一切正常。跟着下面的步骤来检查：

1

运行健康检查

openclaw doctor

这个命令就像给 OpenClaw 做一次"体检"。它会检查所有必要的组件是否正常工作。如果一切正常，你会看到一堆绿色的对勾。

2

检查运行状态

openclaw status

这个命令告诉你 OpenClaw 是否正在运行。如果显示 "running"，说明一切正常！

3

打开 Web 控制面板

openclaw dashboard

这个命令会自动打开浏览器，访问 OpenClaw 的 Web 控制面板。地址是：

http://127.0.0.1:18789/

在这个面板里，你可以看到 OpenClaw 的所有设置和状态，非常直观！

🎉 如果三个命令都没有报错，恭喜你！OpenClaw 已经成功安装了！接下来去 快速上手 章节，学习如何开始使用。

🛠️ 常见安装问题

遇到问题别慌张！下面列出了安装过程中最常见的问题和解决方法：

问题 1：命令找不到（command not found: openclaw）

这通常是 PATH 环境变量的问题。简单来说，你的电脑不知道 openclaw 命令在哪里。

解决方法：

# 查看 openclaw 安装在哪里
which openclaw || npm list -g openclaw

# 如果用的是 bash，把路径加到配置文件里
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 如果用的是 zsh（macOS 默认）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题 2：Node.js 版本太低

如果你看到类似 "Node.js v18 is not supported" 的错误，说明你需要升级 Node.js。

解决方法：

# 使用 nvm（Node Version Manager）来管理 Node.js 版本
# 先安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js 22
nvm install 22

# 切换到 Node.js 22
nvm use 22

# 确认版本
node --version

问题 3：端口冲突（EADDRINUSE）

如果你看到 "EADDRINUSE: address already in use :::18789"，说明端口 18789 已经被其他程序占用了。

解决方法：

# 查找占用端口 18789 的进程
lsof -i :18789

# 如果是旧的 OpenClaw 进程，先停止它
openclaw stop

# 然后重新启动
openclaw start

问题 4：权限不足（EACCES）

在 Linux/macOS 上使用 npm 全局安装时可能遇到权限问题。

解决方法：

# 方法 A：修改 npm 全局安装目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 然后重新安装
npm install -g openclaw@latest
⚠️ 千万不要用 sudo npm install -g！ 虽然加上 sudo 可以解决权限问题，但这样做可能会导致其他安全问题。请使用上面的方法来修改 npm 的全局安装目录。

问题 5：网络超时

如果下载速度很慢或超时，可能是因为网络问题。

解决方法：

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

# 然后重新安装
npm install -g openclaw@latest