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

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 你应该选哪种安装方式

4. 三平台安装总览

4.1 最快安装命令

macOS / Linux / WSL2

curl -fsSL –proto '=https' –tlsv1.2 https://openclaw.ai/install.sh | bash

Windows 原生 PowerShell

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

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

macOS / Linux / WSL2

curl -fsSL –proto '=https' –tlsv1.2 https://openclaw.ai/install.sh | bash -s — –no-onboard

Windows 原生 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：

wsl —install

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

wsl —list —online
wsl —install –d Ubuntu-24.04

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

第 2 步：在 WSL 中启用 systemd

进入 Ubuntu 终端，执行：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后回到 Windows PowerShell：

wsl —shutdown

重新打开 Ubuntu 后验证：

systemctl –user status

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

第 3 步：在 WSL2 里安装 OpenClaw

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

curl -fsSL –proto '=https' –tlsv1.2 https://openclaw.ai/install.sh | bash

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

npm install -g openclaw@latest
openclaw onboard –install-daemon

第 4 步：运行首次引导

openclaw onboard –install-daemon

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

• 配置本地 Gateway
• 设置认证
• 可选接入消息渠道
• 可选配置默认智能体与搜索能力

第 5 步：检查服务与打开控制台

openclaw gateway status
openclaw dashboard

默认控制台地址通常是：

http://127.0.0.1:18789/

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

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

在 WSL 里允许用户服务无登录运行

sudo loginctl enable-linger "$(whoami)"

安装 Gateway 用户服务

openclaw gateway install

在 Windows 开机时自动唤起 WSL

管理员 PowerShell：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu –exec /bin/true" /sc onstart /ru SYSTEM

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

wsl —list —verbose

5.4 Windows 原生 PowerShell 安装（备选）

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

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

源码方式也支持：

& ([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 最推荐的安装方式

curl -fsSL –proto '=https' –tlsv1.2 https://openclaw.ai/install.sh | bash

如果你已经有 Node 22+：

npm install -g openclaw@latest
openclaw onboard –install-daemon

6.2 首次引导

openclaw onboard –install-daemon

完成后，检查状态：

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 可以直接重启

常用命令：

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 最推荐的安装方式

curl -fsSL –proto '=https' –tlsv1.2 https://openclaw.ai/install.sh | bash

如果你已有 Node 22+：

npm install -g openclaw@latest
openclaw onboard –install-daemon

7.2 无 root 权限的安装方式

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

curl -fsSL –proto '=https' –tlsv1.2 https://openclaw.ai/install-cli.sh | bash

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

7.3 首次引导

openclaw onboard –install-daemon

7.4 Linux 上的后台服务

Linux / WSL2 默认使用 systemd user service。

常用命令：

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

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

systemctl –user enable –now openclaw-gateway.service
systemctl –user status openclaw-gateway.service –no-pager

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

sudo loginctl enable-linger "$USER"

7.5 Linux 远程服务器访问 Dashboard

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

ssh -N -L 18789:127.0.0.1:18789 <user>@<host>

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

http://127.0.0.1:18789/

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

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

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，也可以在仓库目录里直接运行：

pnpm openclaw onboard –install-daemon

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

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

openclaw dashboard

如果服务正常，浏览器会打开 Dashboard。
本地默认地址一般是：

http://127.0.0.1:18789/

9.2 如果控制台提示 unauthorized / 1008

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

处理顺序：

openclaw dashboard
openclaw config get gateway.auth.token
openclaw doctor –generate-gateway-token

建议做法：

9.3 Gateway 配置文件在哪里

默认配置文件位置：

~/.openclaw/openclaw.json

默认工作区通常在：

~/.openclaw/workspace

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

• OPENCLAW_HOME
• OPENCLAW_STATE_DIR
• OPENCLAW_CONFIG_PATH

10. 常用命令速查

10.1 状态检查

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

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 查看日志

openclaw logs –follow
openclaw logs –limit 200
openclaw logs –json

10.4 重新配置

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 登录渠道

最常见的做法是：

openclaw channels login

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

openclaw channels login –channel whatsapp
openclaw channels login –channel telegram

11.2 发送测试消息

openclaw message send –target +15555550123 –message "Hello from OpenClaw"

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

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 发送媒体消息

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

openclaw message send –target +15555550123 –media ./demo.png –message "这是一张测试图片"

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

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

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

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

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

13. 常见问题与排错

13.1 openclaw 命令找不到

先检查：

node -v
npm -v
npm prefix -g

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

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：

openclaw config get gateway.auth.token
openclaw doctor –generate-gateway-token
openclaw dashboard

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

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

sudo loginctl enable-linger "$USER"

13.5 升级后服务异常

建议按这个顺序做：

openclaw doctor
openclaw gateway restart
openclaw health –json

14. 更新 OpenClaw

14.1 推荐升级方式

macOS / Linux / WSL2

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

Windows 原生 PowerShell

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

14.2 包管理器升级

npm i -g openclaw@latest
pnpm add -g openclaw@latest

14.3 openclaw update

对源码安装尤其有用：

openclaw update
openclaw update status
openclaw update –channel beta
openclaw update –channel dev
openclaw update –dry-run

升级后的标准检查：

openclaw doctor
openclaw gateway restart
openclaw health –json

15. 卸载 OpenClaw

15.1 最简单方式

openclaw uninstall

如果你要非交互卸载：

openclaw uninstall –all –yes –non-interactive

15.2 手动卸载思路

openclaw gateway stop
openclaw gateway uninstall

然后删除：

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

16. 建议的上手路线

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

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

17. 图片与资料来源

17.1 文中图片

17.2 官方资料