OpenClaw 支持 macOS、Linux 和 Windows 三大平台，完整安装流程通常只需 15～20 分钟。本文将分 Mac 和 Windows 两条线路，带你完成从零到首次对话的全部步骤，并附上常见报错的解决方案。更多中文资源请访问 OpenClaw 中文版官网。

⚠️ 安全提示：OpenClaw 拥有读取文件、执行命令、发送消息等系统级权限。强烈建议不要将其安装在存有个人敏感数据（iCloud、密码、照片）的主力设备上，推荐使用专用设备、虚拟机或 VPS 部署。

一、安装前的准备工作（Mac / Windows 通用）

1. 检查 Node.js 版本

OpenClaw 要求 Node.js v22.16 及以上版本（推荐 v24）。打开终端，输入以下命令查看当前版本：

node --version

如果显示版本号低于 v22，或提示”命令未找到”，请先前往 nodejs.org 下载最新 LTS 版本安装。

2. 准备 AI 模型 API 密钥

OpenClaw 本身不包含 AI 模型，你需要自备以下任一服务商的 API 密钥：

  • Anthropic Claude：访问 console.anthropic.com → Settings → API Keys 创建
  • OpenAI ChatGPT：访问 platform.openai.com → API Keys 创建
  • 国内用户推荐：DeepSeek、智谱 GLM 均支持，价格更低，延迟更小
  • 零成本选项：在引导向导中选择 Qwen（通义千问），可免 API Key 直接授权登录，有每日免费额度限制

二、Mac 安装教程（推荐）

macOS 是运行 OpenClaw 体验最好的平台，原生支持 iMessage、Apple Notes、Apple Reminders 等系统应用集成。Mac Mini（尤其是 M 系列芯片）是社区公认的最佳 OpenClaw 宿主机器，静音、低功耗、24 小时在线。

第一步：打开终端

按下 Command + Space 打开 Spotlight 搜索，输入”Terminal”回车，打开终端窗口。

第二步：安装 OpenClaw

在终端中粘贴以下命令并回车：

npm install -g openclaw@latest

安装过程约需 1～3 分钟。安装完成后，运行以下命令确认安装成功：

openclaw --version

如果显示版本号（例如 2026.x.x），说明安装成功。

常见问题：提示”openclaw: command not found”
这是因为 npm 全局目录不在系统 PATH 中。执行以下命令修复，并将其添加至 ~/.zshrc：

export PATH="$(npm prefix -g)/bin:$PATH"

保存后重新打开终端即可。Apple Silicon（M1/M2/M3/M4）用户如果遇到依赖路径问题，请确认 Homebrew 的 PATH 已正确配置：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

第三步：运行引导向导

执行以下命令启动配置向导，并将 OpenClaw 注册为开机自启的后台服务：

openclaw onboard --install-daemon

向导会依次询问以下内容：

  1. 安全确认：阅读风险提示，用方向键选择”Yes”继续
  2. 安装模式：选择 QuickStart（快速上手）即可
  3. 选择 AI 服务商：根据你准备好的 API 密钥选择对应服务商；如果想零成本体验，选择 Qwen 并完成授权登录
  4. 输入 API Key：粘贴你的 API 密钥，向导会自动验证
  5. 选择默认模型：建议新手选择 Claude Sonnet 系列或 DeepSeek，性价比较高
  6. Gateway 绑定方式：务必选择 Loopback（本机回环），避免局域网内其他设备访问你的控制面板
  7. 配置消息平台（可选）：可暂时跳过，稍后在控制面板中配置
  8. 安装 Hooks（推荐）：建议全部选中，选择 Restart 完成配置

第四步：验证安装并打开控制面板

运行以下命令确认 Gateway 正常运行：

openclaw gateway status
openclaw doctor

随后在浏览器中访问：

http://127.0.0.1:18789

如果页面正常加载，说明 OpenClaw 已成功运行。将终端显示的 Access Token 粘贴到页面中完成认证，即可开始使用 Web 控制面板。

三、Windows 安装教程

Windows 安装 OpenClaw 有两种方式：WSL2（推荐）和原生 PowerShell。WSL2 更稳定，官方更推荐；原生 PowerShell 方式设置更快，但部分功能可能不稳定。

方式 A：WSL2 安装（推荐）

步骤 1：安装 WSL2

以管理员身份打开 PowerShell（右键开始菜单 → Windows PowerShell（管理员）），依次执行以下命令：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
wsl --set-default-version 2

执行完毕后重启电脑。重启后，在 Microsoft Store 搜索并安装 Ubuntu 24.04 LTS，打开后按提示设置用户名和密码。

步骤 2：在 WSL2 中安装 Node.js 和 OpenClaw

打开 Ubuntu 终端，依次执行：

# 安装 nvm（Node 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载配置
source ~/.bashrc

# 安装 Node.js v22
nvm install 22
nvm use 22

# 安装 OpenClaw
npm install -g openclaw@latest

# 验证安装
openclaw --version

步骤 3：运行引导向导

openclaw onboard --install-daemon

后续步骤与 Mac 安装流程完全相同，参考上文”第三步”操作即可。

方式 B：原生 PowerShell 安装（快速）

如果你不想折腾 WSL2，也可以直接通过 nvm-windows 安装：

  1. 前往 github.com/coreybutler/nvm-windows 下载并安装 nvm-windows
  2. 打开 PowerShell，执行：
nvm install 22
nvm use 22
npm install -g openclaw@latest
openclaw --version

安装成功后，同样执行 openclaw onboard --install-daemon 完成配置向导。

四、连接 Telegram（最推荐的消息平台）

配置完成后，建议优先接入 Telegram，这是 OpenClaw 生态中支持最完善、最稳定的消息平台。

  1. 打开 Telegram，搜索 @BotFather
  2. 发送 /newbot，按提示输入 Bot 名称，获得一串 Bot Token
  3. 在 OpenClaw Web 控制面板（http://127.0.0.1:18789）中进入 Channels 设置
  4. 选择 Telegram，粘贴 Bot Token 并保存
  5. 在 Telegram 中搜索并打开你刚创建的 Bot，发送任意消息，即可开始对话

国内用户提示：如果 Telegram 访问受限，也可以在 Channels 设置中选择飞书（Lark）或微信，按照对应文档完成接入。

五、常见报错与解决方案

报错：node: command not found

Node.js 未安装或未加入 PATH。前往 nodejs.org 下载 v22 LTS 版本重新安装，安装后重启终端。

报错：openclaw: command not found

npm 全局目录不在 PATH 中。执行 npm prefix -g 查看全局目录路径，将 /bin 子目录添加至 ~/.zshrc 或 ~/.bashrc。

报错：端口 18789 被占用

另一个进程占用了控制面板端口。Mac/Linux 执行 lsof -i :18789 找到进程 PID，再执行 kill -9 <PID> 关闭；Windows 在 PowerShell 执行 netstat -ano | findstr :18789，再用 taskkill /PID <PID> /F 终止。

安装后模型列表为空

几乎 100% 是 API Key 填写有误，或账户余额不足。回到服务商控制台重新确认密钥有效性，并确保已开通计费功能。

重启后 Gateway 未自动启动

重新执行 openclaw onboard --install-daemon 注册后台服务。如仍无效，macOS 用户检查 Console.app 中的系统日志，Linux/WSL2 用户执行 journalctl -u openclaw 查看详细错误信息。

六、安装后的下一步

  • 运行 openclaw doctor 进行自动健康检查，确认所有配置正常
  • 在 Web 控制面板的 Skills 页面安装你需要的技能扩展
  • 设置你的第一个自动化任务——推荐从”每日简报”开始，30 分钟内见效
  • 定期执行 npm install -g openclaw@latest 保持版本最新

总结

Mac 用户安装 OpenClaw 基本上是”一条命令搞定”，Windows 用户通过 WSL2 安装同样流畅。整个流程中最需要注意的三个点：Node.js 版本不低于 v22、Gateway 绑定选 Loopback、API Key 确保有效且有余额。

遇到安装问题，优先运行 openclaw doctor 自动诊断，或访问 OpenClaw 中文版官网 查阅官方文档与社区支持，开启你的专属 AI 助手之旅。