OpenClaw 安装及使用教程（Windows / macOS / Linux）

待续3012026-03-24 18:14

OpenClaw 安装及使用教程（Windows / macOS / Linux）

1. OpenClaw 是什么

OpenClaw 是一个可自托管的 AI Gateway，可以把 WhatsApp、Telegram、Discord、iMessage 等聊天渠道连接到 AI 助手和智能体系统上。你可以把它理解成：

  • 一个运行在你自己机器或服务器上的网关
  • 一个带 Web 控制台的消息入口
  • 一个支持多渠道、多节点、多智能体的中间层

官方当前推荐的运行方式是：

  • Node 作为运行时
  • openclaw onboard --install-daemon 作为首次引导入口
  • openclaw dashboard 作为最快的第一种使用方式

2. 本文适用场景

这篇教程适合下面几类人：

  • 想在本机快速装好 OpenClaw 并先用浏览器聊天
  • 想继续接入 WhatsApp / Telegram / Discord 等渠道
  • 想在 Windows、macOS、Linux 里选一个稳定的部署方式
  • 想把 OpenClaw 放到 VPS 或长期运行的机器上

3. 安装前准备

3.1 系统要求

官方当前要求：

  • Node 22+
  • macOS / Linux / Windows
  • 如果从源码构建，建议额外准备 pnpm

补充说明：

  • 官方安装脚本默认会优先确保 Node 24
  • 出于兼容性，Node 22 LTS 目前仍被支持
  • Bun 不推荐用于 Gateway 运行，官方文档明确提到 WhatsApp / Telegram 存在兼容问题

3.2 你应该选哪种安装方式

场景 推荐方式
macOS 普通用户 安装脚本 install.sh
Linux 普通用户 / VPS 安装脚本 install.sh
Windows 用户 优先使用 WSL2 + Ubuntu
已经有 Node 环境 npm install -g openclaw@latest
想自己改源码或跟进 dev 分支 源码安装
无 root / sudo 权限 install-cli.sh 本地前缀安装

4. 三平台安装总览

4.1 最快安装命令

macOS / Linux / WSL2
bash 复制代码 
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
Windows 原生 PowerShell
powershell 复制代码 
iwr -useb https://openclaw.ai/install.ps1 | iex

如果只想安装，不想立即进入引导流程：

macOS / Linux / WSL2
bash 复制代码 
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
Windows 原生 PowerShell
powershell 复制代码 
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

5. Windows 安装教程

5.1 先说结论

截至 2026-03-22，OpenClaw 官方仍然明确推荐在 Windows 上通过 WSL2 运行 OpenClaw。原因很直接：

  • CLI + Gateway 在 Linux 环境里兼容性更稳定
  • Node / pnpm / Linux 二进制工具链更一致
  • 很多技能、脚本、依赖默认按 Linux 运行环境设计

如果你只是想"能装上"，原生 PowerShell 也可以试；如果你是想"稳定长期跑"，优先走 WSL2 + Ubuntu。

5.2 Windows 推荐方案：WSL2 + Ubuntu

第 1 步：安装 WSL2

以管理员身份打开 PowerShell：

powershell 复制代码 
wsl --install

如果你想显式选择发行版：

powershell 复制代码 
wsl --list --online
wsl --install -d Ubuntu-24.04

安装完成后，重启系统或按提示重新打开终端。

第 2 步：在 WSL 中启用 systemd

进入 Ubuntu 终端，执行：

bash 复制代码 
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后回到 Windows PowerShell：

powershell 复制代码 
wsl --shutdown

重新打开 Ubuntu 后验证：

bash 复制代码 
systemctl --user status

如果能正常显示用户级 systemd 状态，说明这一步没问题。

第 3 步：在 WSL2 里安装 OpenClaw

推荐方式一：官方安装脚本

bash 复制代码 
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

推荐方式二：如果你已经装好了 Node 22+

bash 复制代码 
npm install -g openclaw@latest
openclaw onboard --install-daemon
第 4 步：运行首次引导
bash 复制代码 
openclaw onboard --install-daemon

这个向导会帮你做几件事：

  • 配置本地 Gateway
  • 设置认证
  • 可选接入消息渠道
  • 可选配置默认智能体与搜索能力
第 5 步：检查服务与打开控制台
bash 复制代码 
openclaw gateway status
openclaw dashboard

默认控制台地址通常是：

text 复制代码 
http://127.0.0.1:18789/

5.3 Windows 开机自动启动 WSL 内 Gateway（可选）

如果你希望即使未登录 Windows，WSL 内的 Gateway 也能自动起来，可继续配置。

在 WSL 里允许用户服务无登录运行
bash 复制代码 
sudo loginctl enable-linger "$(whoami)"
安装 Gateway 用户服务
bash 复制代码 
openclaw gateway install
在 Windows 开机时自动唤起 WSL

管理员 PowerShell：

powershell 复制代码 
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

如果你的发行版名字不是 Ubuntu，先看一下：

powershell 复制代码 
wsl --list --verbose

5.4 Windows 原生 PowerShell 安装（备选）

如果你确实不想用 WSL2，可以在 PowerShell 中直接安装：

powershell 复制代码 
iwr -useb https://openclaw.ai/install.ps1 | iex

源码方式也支持：

powershell 复制代码 
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git

注意几点：

  • 官方仍然把原生 Windows 视为兼容性较弱的路线
  • 如果遇到 npm error spawn git / ENOENT，先安装 Git for Windows
  • 如果遇到 openclaw is not recognized，先运行 npm config get prefix，把该目录加入用户 PATH

6. macOS 安装教程

6.1 最推荐的安装方式

bash 复制代码 
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

如果你已经有 Node 22+：

bash 复制代码 
npm install -g openclaw@latest
openclaw onboard --install-daemon

6.2 首次引导

bash 复制代码 
openclaw onboard --install-daemon

完成后，检查状态：

bash 复制代码 
openclaw doctor
openclaw gateway status
openclaw dashboard

6.3 macOS 下 Gateway 的后台管理

OpenClaw 在 macOS 上使用 LaunchAgent 作为后台服务形式。一般情况下，你不需要手写 launchctl，因为：

  • openclaw onboard --install-daemon 会自动安装
  • openclaw gateway install 可以单独补装
  • openclaw gateway restart 可以直接重启

常用命令：

bash 复制代码 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

6.4 macOS Companion App（可选）

官方为 macOS 提供了菜单栏 Companion App，适合下面这些需求：

  • 系统通知
  • 麦克风 / 屏幕录制 / 辅助功能权限管理
  • 把 Mac 作为一个节点暴露给 OpenClaw
  • 本地模式 / 远程模式切换

如果你主要是命令行和浏览器使用，CLI 即可；如果你要更深度地使用 macOS 能力，Companion App 会更合适。

7. Linux 安装教程

7.1 最推荐的安装方式

bash 复制代码 
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

如果你已有 Node 22+：

bash 复制代码 
npm install -g openclaw@latest
openclaw onboard --install-daemon

7.2 无 root 权限的安装方式

如果你不想动系统级 Node，也不想要 root 权限，可以使用本地前缀安装脚本：

bash 复制代码 
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

这个方式会把 OpenClaw 安装到默认本地前缀（通常是 ~/.openclaw）下。

7.3 首次引导

bash 复制代码 
openclaw onboard --install-daemon

7.4 Linux 上的后台服务

Linux / WSL2 默认使用 systemd user service。

常用命令：

bash 复制代码 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

如果你需要手动管理服务：

bash 复制代码 
systemctl --user enable --now openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

如果是 VPS / 服务器场景，建议额外开启 lingering，这样退出登录后用户服务仍可运行：

bash 复制代码 
sudo loginctl enable-linger "$USER"

7.5 Linux 远程服务器访问 Dashboard

如果 OpenClaw 跑在远程 Linux 服务器上，官方推荐通过 SSH 隧道访问控制台：

bash 复制代码 
ssh -N -L 18789:127.0.0.1:18789 <user>@<host>

然后在你本机浏览器打开：

text 复制代码 
http://127.0.0.1:18789/

8. 从源码安装（所有平台通用，适合开发者）

如果你要参与开发、追踪 dev/main 或需要直接改源码，可以使用源码安装。

bash 复制代码 
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon

如果你不想全局 link，也可以在仓库目录里直接运行：

bash 复制代码 
pnpm openclaw onboard --install-daemon

9. 安装完成后的第一次使用

9.1 最快验证方式：直接打开 Web 控制台

bash 复制代码 
openclaw dashboard

如果服务正常，浏览器会打开 Dashboard。

本地默认地址一般是：

text 复制代码 
http://127.0.0.1:18789/

9.2 如果控制台提示 unauthorized / 1008

这是现在最常见的问题之一，原因通常是 Gateway token 没有自动填上。

处理顺序：

bash 复制代码 
openclaw dashboard
openclaw config get gateway.auth.token
openclaw doctor --generate-gateway-token

建议做法：

  1. 先执行 openclaw dashboard
  2. 如果仍提示未授权，再执行 openclaw config get gateway.auth.token
  3. 把这个 token 粘贴到 Dashboard 的认证设置里
  4. 如果还没有 token，就执行 openclaw doctor --generate-gateway-token

9.3 Gateway 配置文件在哪里

默认配置文件位置：

text 复制代码 
~/.openclaw/openclaw.json

默认工作区通常在：

text 复制代码 
~/.openclaw/workspace

如果你要自定义路径，可以使用环境变量：

  • OPENCLAW_HOME
  • OPENCLAW_STATE_DIR
  • OPENCLAW_CONFIG_PATH

10. 常用命令速查

10.1 状态检查

bash 复制代码 
openclaw doctor
openclaw status
openclaw status --all
openclaw status --deep
openclaw health --json
openclaw gateway status

命令区别：

  • openclaw doctor：偏修复与体检
  • openclaw status：本地摘要
  • openclaw status --all：完整只读诊断，适合贴给别人排查
  • openclaw status --deep：增加实时探测
  • openclaw health --json：向运行中的 Gateway 请求健康快照

10.2 启停 Gateway

bash 复制代码 
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status
openclaw gateway --port 18789

说明：

  • openclaw gateway --port 18789 会以前台方式运行，适合临时测试
  • 如果已经装成后台服务，优先用 start / stop / restart

10.3 查看日志

bash 复制代码 
openclaw logs --follow
openclaw logs --limit 200
openclaw logs --json

10.4 重新配置

bash 复制代码 
openclaw configure
openclaw configure --section web
openclaw agents add my-agent

其中：

  • openclaw configure 用于重新配置网关、模型、渠道等
  • openclaw configure --section web 用于补充搜索 API Key
  • openclaw agents add 用于新增智能体

11. 如何接入消息渠道并发送第一条消息

11.1 登录渠道

最常见的做法是：

bash 复制代码 
openclaw channels login

如果你配置了多个渠道，可以显式指定，例如：

bash 复制代码 
openclaw channels login --channel whatsapp
openclaw channels login --channel telegram

11.2 发送测试消息

bash 复制代码 
openclaw message send --target +15555550123 --message "Hello from OpenClaw"

如果你配置了多个渠道，需要加上 --channel：

bash 复制代码 
openclaw message send --channel whatsapp --target +15555550123 --message "Hello from OpenClaw"

目标格式依渠道不同而不同，例如：

  • WhatsApp：手机号或群组 JID
  • Telegram：聊天 ID 或 @username
  • Discord：channel:<id> 或 user:<id>
  • Slack：channel:<id> 或 user:<id>

11.3 发送媒体消息

如果目标渠道支持媒体，可使用：

bash 复制代码 
openclaw message send --target +15555550123 --media ./demo.png --message "这是一张测试图片"

--media 可以是本地路径，也可以是 HTTP(S) URL。

12. 一个最实用的最小配置示例

下面这个示例来自官方文档思路，适合先把 WhatsApp 白名单和群聊提及规则收紧：

json5 复制代码 
{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"]
    }
  }
}

保存到默认配置文件后，OpenClaw 通常会根据配置热更新或按需重启。

13. 常见问题与排错

13.1 openclaw 命令找不到

先检查：

bash 复制代码 
node -v
npm -v
npm prefix -g

在 macOS / Linux 中，如果 $(npm prefix -g)/bin 没进 PATH，可以加入：

bash 复制代码 
export PATH="$(npm prefix -g)/bin:$PATH"

在 Windows 中：

  • 执行 npm config get prefix
  • 把该目录加入用户 PATH
  • 重新打开 PowerShell

13.2 Windows 报 spawn git / ENOENT

原因通常是系统没有 Git。处理方法：

  • 安装 Git for Windows
  • 重新打开 PowerShell
  • 重新运行安装脚本

13.3 Dashboard 一直未授权

优先排查 token：

bash 复制代码 
openclaw config get gateway.auth.token
openclaw doctor --generate-gateway-token
openclaw dashboard

13.4 服务装上了，但登录退出后就不跑了

Linux / WSL2 一般是没有开启 lingering：

bash 复制代码 
sudo loginctl enable-linger "$USER"

13.5 升级后服务异常

建议按这个顺序做：

bash 复制代码 
openclaw doctor
openclaw gateway restart
openclaw health --json

14. 更新 OpenClaw

14.1 推荐升级方式

macOS / Linux / WSL2
bash 复制代码 
curl -fsSL https://openclaw.ai/install.sh | bash
Windows 原生 PowerShell
powershell 复制代码 
iwr -useb https://openclaw.ai/install.ps1 | iex

14.2 包管理器升级

bash 复制代码 
npm i -g openclaw@latest
pnpm add -g openclaw@latest

14.3 openclaw update

对源码安装尤其有用：

bash 复制代码 
openclaw update
openclaw update status
openclaw update --channel beta
openclaw update --channel dev
openclaw update --dry-run

升级后的标准检查：

bash 复制代码 
openclaw doctor
openclaw gateway restart
openclaw health --json

15. 卸载 OpenClaw

15.1 最简单方式

bash 复制代码 
openclaw uninstall

如果你要非交互卸载：

bash 复制代码 
openclaw uninstall --all --yes --non-interactive

15.2 手动卸载思路

bash 复制代码 
openclaw gateway stop
openclaw gateway uninstall

然后删除：

  • 状态目录，如 ~/.openclaw
  • 工作区，如 ~/.openclaw/workspace
  • 全局 CLI，如 npm rm -g openclaw

16. 建议的上手路线

如果你是第一次接触 OpenClaw，我建议按这个顺序用：

  1. 先安装
  2. 先跑 openclaw onboard --install-daemon
  3. 先用 openclaw dashboard 在浏览器里聊天
  4. 确认 Gateway 正常后再接 WhatsApp / Telegram
  5. 最后再做远程访问、自动更新、节点接入

这是最省时间、最不容易踩坑的路线。

17. 图片与资料来源

17.1 文中图片

  1. OpenClaw 官方 Logo
    https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=https%3A%2F%2Fraw.githubusercontent.com%2Fopenclaw%2Fopenclaw%2Fmain%2Fdocs%2Fassets%2Fopenclaw-logo-text.svg&pos_id=img-Vms5IeyF-1774252455901)

  2. Windows Logo
    https://cdn.simpleicons.org/windows/0078D6

  3. Apple Logo
    https://cdn.simpleicons.org/apple/000000

  4. Linux Logo
    https://cdn.simpleicons.org/linux/FCC624

17.2 官方资料

  1. 官方文档首页

    https://docs.openclaw.ai/

  2. 安装总览

    https://docs.openclaw.ai/install

  3. Installer Internals

    https://docs.openclaw.ai/install/installer

  4. Windows（WSL2）

    https://docs.openclaw.ai/platforms/windows

  5. macOS

    https://docs.openclaw.ai/platforms/macos

  6. Linux

    https://docs.openclaw.ai/platforms/linux

  7. Onboarding Wizard

    https://docs.openclaw.ai/wizard

  8. Dashboard

    https://docs.openclaw.ai/dashboard

  9. Health Checks

    https://docs.openclaw.ai/health

  10. Message CLI

    https://docs.openclaw.ai/message

  11. Updating

    https://docs.openclaw.ai/install/updating

  12. Uninstall

    https://docs.openclaw.ai/install/uninstall

  13. 官方仓库

    https://github.com/openclaw/openclaw

相关推荐
创世宇图2 小时前
Alibaba Cloud Linux 安装生产环境-mysql
linux·mysql
TEC_INO2 小时前
嵌入式 Linux 开发知识总结
linux·运维·服务器
原来是猿2 小时前
VS Code Remote-SSH 连接失败：提示过程试图写入的管道不存在
linux·服务器·ssh
坚持就完事了2 小时前
Linux中的权限信息
linux·运维·服务器
顶点多余3 小时前
进程间通信 --- 共享内存篇(通信速度最快)
linux·服务器·jvm
co_wait3 小时前
【c 语言】linux下gcc编译工具的使用
linux·c语言·开发语言
liulilittle3 小时前
LINUX RING BUFFER TUN/TAP 1
linux·服务器·网络·c++·信息与通信·通信
supersolon3 小时前
WSL2（Linux）升级docker
linux·运维·docker·wsl·升级
sthnyph3 小时前
MySQL 8.0在windows环境安装及配置
windows·mysql·adb
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06OpenClaw 使用和管理 MCP 完全指南07UV安装并设置国内源08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南10AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南