OpenClaw 入门：OpenClaw 环境搭建完整指南（Mac / Windows / Linux）（2026-3月最新版）

😀前言

在上一章我们介绍了 OpenClaw 的基本概念，本章将手把手带你完成 OpenClaw 的环境搭建与初始化配置。

本文适合：

• 初次接触 OpenClaw 的用户
• 想要本地部署 AI 助手的开发者
• 想将 AI 接入飞书 / Telegram 的用户

🏠个人主页：尘觉主页

文章目录

• [OpenClaw 环境搭建完整指南（Mac / Windows / Linux）](#OpenClaw 环境搭建完整指南（Mac / Windows / Linux）)
• • 一、前提条件与推荐配置
  • • [1. 操作系统推荐](#1. 操作系统推荐)
    • [2. IM工具推荐](#2. IM工具推荐)
    • [3. 部署方式推荐](#3. 部署方式推荐)
  • [二、为什么推荐 Mac 本地部署](#二、为什么推荐 Mac 本地部署)
  • [三、Mac 本地部署（推荐）](#三、Mac 本地部署（推荐）)
  • • [1 系统要求](#1 系统要求)
    • [2 安装 OpenClaw](#2 安装 OpenClaw)
    • • 第一步：打开终端
      • 第二步：执行安装命令
      • 第三步：验证安装
    • [3 初始化配置](#3 初始化配置)
    • • [1 接受风险提示](#1 接受风险提示)
      • [2 选择启动模式](#2 选择启动模式)
      • [3 选择 AI 模型](#3 选择 AI 模型)
      • [4 输入 API Key](#4 输入 API Key)
      • [5 选择聊天工具](#5 选择聊天工具)
      • [6 Gateway端口](#6 Gateway端口)
      • [7 选择 Skills](#7 选择 Skills)
      • [8 API Key配置](#8 API Key配置)
      • [9 启用 Hooks](#9 启用 Hooks)
      • [10 完成配置](#10 完成配置)
  • 四、日常使用命令
  • • [启动 OpenClaw](#启动 OpenClaw)
    • [访问 Web UI](#访问 Web UI)
    • 停止服务
    • 查看状态
  • [五、Windows 本地部署](#五、Windows 本地部署)
  • [六、WSL2 + Ubuntu 部署（推荐）](#六、WSL2 + Ubuntu 部署（推荐）)
  • • [1 启用 WSL2](#1 启用 WSL2)
    • [2 安装 Ubuntu](#2 安装 Ubuntu)
    • [3 更新系统](#3 更新系统)
    • [4 安装 Node.js](#4 安装 Node.js)
    • [5 安装 OpenClaw](#5 安装 OpenClaw)
    • [6 验证安装](#6 验证安装)
    • [7 配置Windows访问WSL2服务](#7 配置Windows访问WSL2服务)
  • [七、Windows 本地部署（方式二：PowerShell 原生部署）](#七、Windows 本地部署（方式二：PowerShell 原生部署）)
  • • [一、安装 Node.js 22+](#一、安装 Node.js 22+)
    • • 方法一：官网下载安装
    • [二、验证 Node.js 安装](#二、验证 Node.js 安装)
    • [三、安装 OpenClaw](#三、安装 OpenClaw)
    • 四、解决安装权限问题
    • • [方法一：启用 PowerShell 脚本执行](#方法一：启用 PowerShell 脚本执行)
      • [方法二：修改 npm 安装目录](#方法二：修改 npm 安装目录)
    • [五、验证 OpenClaw 安装](#五、验证 OpenClaw 安装)
    • 六、解决常见问题
    • • [1 sharp 模块加载失败](#1 sharp 模块加载失败)
      • [2 Windows Defender 阻止](#2 Windows Defender 阻止)
    • 七、初始化配置
    • [八、配置 AI 模型](#八、配置 AI 模型)
    • 九、绑定消息渠道
    • • [1 Telegram](#1 Telegram)
      • [2 微信（WhatsApp）](#2 微信（WhatsApp）)
      • [3 企业微信](#3 企业微信)
      • [4 飞书（国内推荐）](#4 飞书（国内推荐）)
    • [十、Windows 常用命令速查](#十、Windows 常用命令速查)
    • • 系统管理
      • 配置管理
  • [八、Linux 本地部署](#八、Linux 本地部署)
  • • [1 系统要求](#1 系统要求)
    • [2 安装 Node.js](#2 安装 Node.js)
    • [3 安装 OpenClaw](#3 安装 OpenClaw)
    • [4 验证安装](#4 验证安装)
    • [5 初始化配置](#5 初始化配置)
    • [6 访问 Web UI](#6 访问 Web UI)
    • [7 常用管理命令](#7 常用管理命令)
  • 😄总结

OpenClaw 环境搭建完整指南（Mac / Windows / Linux）

一、前提条件与推荐配置

为了获得最佳使用体验，建议满足以下环境配置。

1. 操作系统推荐

系统	推荐程度	说明
Mac	⭐⭐⭐⭐⭐	官方体验最好，系统集成能力强
Windows	⭐⭐⭐⭐	完全可用，但部分系统功能受限
Linux	⭐⭐⭐⭐	适合开发者，自由度高

2. IM工具推荐

OpenClaw 可以接入聊天工具，实现 AI助手对话能力。

国内用户推荐：

• 飞书（推荐）
• 企业微信
• 钉钉
• QQ

国外用户推荐：

• Telegram（最佳适配）

3. 部署方式推荐

根据设备环境不同，可以选择不同部署方式：

部署方式	推荐场景
Mac 本地部署	最佳体验
Windows 本地部署	Windows 用户
Linux 部署	服务器 / 开发者
云端部署	24小时运行

推荐路径：

有 Mac电脑
→ Mac本地部署 + 飞书配置

没有Mac / 想长期运行
→ 云服务器部署 + 飞书配置

二、为什么推荐 Mac 本地部署

OpenClaw 在 Mac 上拥有最完整的系统能力。

主要优势：

• ✅ 系统集成度高
• ✅ 支持操作日历、备忘录
• ✅ 支持截图功能
• ✅ 与 iPhone / iPad 无缝同步
• ✅ 本地运行速度快
• ✅ 数据完全本地，隐私安全

适合人群：

• Mac用户
• 注重隐私的用户
• 技术开发者
• AI工具深度使用者

三、Mac 本地部署（推荐）

1 系统要求

硬件要求：

CPU：M系列芯片 或 Intel i5+
内存：8GB+（推荐16GB）
硬盘：10GB以上空间

系统版本：

macOS 12 Monterey+
推荐 macOS 14 Sonoma 或 macOS 15 Sequoia

2 安装 OpenClaw

第一步：打开终端

按：

Command + 空格

搜索：

Terminal

打开终端。

第二步：执行安装命令

运行：

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

安装脚本会自动完成：

• 环境检测
• Node.js 安装
• OpenClaw 下载
• 环境变量配置

预计安装时间：

2 ~ 5 分钟

第三步：验证安装

执行：

openclaw --version

如果输出类似：

2026.2.9

说明安装成功。

3 初始化配置

运行初始化向导：

openclaw onboard

配置流程如下。

1 接受风险提示

选择：

Yes

继续。

2 选择启动模式

推荐：

QuickStart

快速启动。

3 选择 AI 模型

OpenClaw 支持多种 AI 模型。

国内推荐：

• Kimi（Moonshot）
• DeepSeek
• 智谱 GLM

国外推荐：

• Claude
• OpenAI

4 输入 API Key

输入对应模型提供商的 API Key。

示例：

sk-xxxxxxx

5 选择聊天工具

可以接入：

• 飞书
• Telegram
• 企业微信

如果暂时不接入：

None

6 Gateway端口

默认：

18789

即可。

7 选择 Skills

使用空格选择需要的技能，也可以跳过。

8 API Key配置

如果暂时没有：

No

跳过。

9 启用 Hooks

建议启用以下三个：

• 内容引导
• 日志记录
• 会话记录

10 完成配置

配置完成后系统会自动启动 Gateway，并打开 Web UI。

访问地址：

http://127.0.0.1:18789/chat

四、日常使用命令

启动 OpenClaw

openclaw gateway start

或设置开机自启：

openclaw gateway enable

访问 Web UI

浏览器打开：

http://127.0.0.1:18789/chat

停止服务

openclaw gateway stop

查看状态

openclaw channels status

如果显示：

Gateway reachable

说明运行正常。

五、Windows 本地部署

Windows 有两种部署方式：

方式	推荐程度
WSL2 + Ubuntu	⭐⭐⭐⭐⭐
PowerShell 原生部署	⭐⭐⭐

官方更推荐 WSL2方式。

六、WSL2 + Ubuntu 部署（推荐）

1 启用 WSL2

管理员 PowerShell 执行：

# 启用WSL功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# 设置WSL 2为默认版本
wsl --set-default-version 2

然后重启电脑。

2 安装 Ubuntu

方法一：Microsoft Store安装（推荐）

1. 打开Microsoft Store
2. 搜索「Ubuntu 22.04 LTS」或「Ubuntu 24.04 LTS」
3. 点击「获取」并安装
4. 首次启动设置用户名和密码
   安装完成后会自动打开Ubuntu终端，按提示设置用户名和密码。

3 更新系统

进入 Ubuntu 终端：

# 更新软件包列表
sudo apt update && sudo apt upgrade -y

安装基础工具：

sudo apt install -y curl git wget build-essential

4 安装 Node.js

# 添加NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

sudo apt install -y nodejs

验证版本：

node -v
npm -v

5 安装 OpenClaw

一键脚本安装

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

6 验证安装

# 查看版本
openclaw --version
# 查看帮助
openclaw --help
# 查看系统状态
openclaw status

7 配置Windows访问WSL2服务

由于OpenClaw运行在WSL2中，需要配置端口转发以便Windows访问。

创建启动脚本 start-openclaw.bat ：

@echo off
echo Starting OpenClaw Gateway in WSL2...
wsl -d Ubuntu-22.04 -u root service openclaw start
timeout /t 3
start http://localhost:18789

或直接在WSL2中启动：

# 在WSL2 Ubuntu终端中
openclaw gateway run --port 18789

然后在Windows浏览器访问 http://localhost:18789

七、Windows 本地部署（方式二：PowerShell 原生部署）

适合 不想使用 WSL2 的纯 Windows 用户。

相比 WSL2 部署：

方式	特点
WSL2 + Ubuntu	官方推荐，兼容性最好
PowerShell 原生部署	配置简单，但部分 Linux 生态依赖可能受限

如果你只想 快速体验 OpenClaw，PowerShell 部署是一个比较简单的方案。

一、安装 Node.js 22+

OpenClaw 需要 Node.js 22+ 环境。

方法一：官网下载安装

1. 打开官网：

   https://nodejs.org/zh-cn

2. 下载 Windows 安装包

推荐版本：

Node.js 22.x LTS

1. 运行安装程序

安装时建议勾选：

Automatically install the necessary tools
自动安装必要的工具

二、验证 Node.js 安装

打开 PowerShell，执行：

node -v
npm -v

如果输出类似：

v22.x.x
10.x.x

说明 Node.js 安装成功。

三、安装 OpenClaw

⚠️ 重要：必须以管理员身份运行 PowerShell

右键 PowerShell：

以管理员身份运行

执行安装命令：

# # 安装最新稳定版
npm install -g openclaw@latest

或者安装 中文版本：

npm install -g @qingchencloud/openclaw-zh@latest

安装完成后系统会自动配置 CLI 命令。

四、解决安装权限问题

如果安装过程中出现 权限错误，可以尝试以下方法。

方法一：启用 PowerShell 脚本执行

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

方法二：修改 npm 安装目录

设置 npm 全局目录：

npm config set prefix "C:\npm"
npm config set cache "C:\npm-cache"

将目录添加到 PATH：

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\npm", "User")

重新打开 PowerShell 即可生效。

五、验证 OpenClaw 安装

执行：

openclaw --version
openclaw --help

如果显示版本号，则说明安装成功。

六、解决常见问题

1 sharp 模块加载失败

解决方法：

# 清理npm缓存
npm cache clean --force
# 重新安装
npm install -g openclaw@latest --force

2 Windows Defender 阻止

将 OpenClaw 目录加入 Windows Defender 排除项：

C:\Users\你的用户名\AppData\Roaming\npm
C:\Users\你的用户名\.openclaw

七、初始化配置

安装完成后需要运行 初始化向导。

启动初始化：

openclaw onboard --install-daemon

初始化流程包括：（和mac一样的配置不多阐述了）

1️⃣ 接受风险提示

2️⃣ 选择启动模式

3️⃣ 选择 AI 模型

4️⃣ 输入 API Key

5️⃣ 配置消息渠道

6️⃣ 设置 Gateway 端口

八、配置 AI 模型

OpenClaw 必须连接 AI 模型提供商才能工作。

例如配置 Claude 模型：

openclaw models auth add

然后按提示：

选择 anthropic
输入 API Key

示例：

sk-ant-xxxxxxxx

九、绑定消息渠道

OpenClaw 可以绑定聊天工具作为 AI入口。

支持平台：

• Telegram
• WhatsApp
• 企业微信
• 飞书

1 Telegram

创建机器人：

1. 打开 Telegram

2. 搜索：

   @BotFather

3. 输入：

   /newbot

4. 保存 Bot Token

配置：

openclaw channels add telegram
openclaw config set channels.telegram.botToken "your-bot-token"
openclaw gateway restart

2 微信（WhatsApp）

登录：

openclaw channels login whatsapp

终端会出现二维码，用手机扫码即可。

3 企业微信

安装插件：

openclaw plugins install @m1heng-clawd/wework

配置：

openclaw config set channels.wework '{"enabled":true,"corpId":"xxx","agentSecret":"xxx"}'

4 飞书（国内推荐）

安装插件：

openclaw plugins install @m1heng-clawd/feishu

配置：

openclaw config set channels.feishu '{"enabled":true,"appId":"cli_xxx","appSecret":"xxx"}'

十、Windows 常用命令速查

系统管理

命令	功能
openclaw --version	查看版本
openclaw status	查看系统状态
openclaw health	健康检查
openclaw update	更新系统
openclaw doctor	系统诊断

配置管理

命令	功能
openclaw onboard	初始化向导
openclaw configure	交互式配置
openclaw config get	查看配置
openclaw config set	修改配置
openclaw config unset	删除配置

八、Linux 本地部署

🐧 Linux 用户：适合开发者，配置灵活，适合服务器或长期运行环境。

Linux 环境通常用于：

• 服务器部署
• 开发测试环境
• 云服务器长期运行
• Docker / 自动化环境

1 系统要求

推荐使用以下 Linux 发行版：

系统	推荐版本
Ubuntu	20.04+
Debian	11+
CentOS	8+

硬件建议：

CPU：2核以上
内存：4GB以上（推荐8GB）
硬盘：10GB以上空间

2 安装 Node.js

OpenClaw 需要 Node.js 22+ 环境。

Ubuntu / Debian 执行：

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs

验证安装：

node --version
npm --version

如果显示：

v22.x.x

说明 Node.js 安装成功。

3 安装 OpenClaw

执行官方一键安装脚本：

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

安装过程会自动完成：

• 环境检测
• 下载 OpenClaw
• 配置 CLI 命令
• 安装依赖

预计安装时间：

2~5分钟

4 验证安装

执行：

openclaw --version

如果输出版本号，例如：

2026.2.9

说明安装成功。

5 初始化配置

安装完成后需要进行初始化配置。

运行：

openclaw onboard

配置流程包括：（和mac、win一样的配置不多阐述了）

1️⃣ 接受风险提示

2️⃣ 选择启动模式（推荐 QuickStart）

3️⃣ 选择 AI 模型提供商

4️⃣ 输入 API Key

5️⃣ 选择消息渠道（飞书 / Telegram 等）

6️⃣ 设置 Gateway 端口（默认 18789）

7️⃣ 选择技能 Skills

8️⃣ 配置 Hooks

配置完成后系统会自动启动 OpenClaw Gateway。

6 访问 Web UI

浏览器打开：

http://服务器IP:18789/chat

例如：

http://127.0.0.1:18789/chat

即可进入 OpenClaw Web 控制台。

7 常用管理命令

命令	功能
openclaw --version	查看版本
openclaw status	查看运行状态
openclaw gateway start	启动服务
openclaw gateway stop	停止服务
openclaw update	更新 OpenClaw
openclaw doctor	系统诊断

😄总结

至此，我们已经介绍了 OpenClaw 的三种本地部署方式：

系统	推荐方式
Mac	本地部署（最佳体验）
Windows	WSL2 + Ubuntu
Linux	服务器 / 开发环境

😁热门专栏推荐
想学习vue的可以看看这个

java基础合集

数据库合集

redis合集

nginx合集

linux合集

手写机制

微服务组件

spring_尘觉

springMVC

mybits

等等等还有许多优秀的合集在主页等着大家的光顾感谢大家的支持

🤔欢迎大家加入我的社区 尘觉社区

文章到这里就结束了，如果有什么疑问的地方请指出，诸佬们一起来评论区一起讨论😁

希望能和诸佬们一起努力，今后我们一起观看感谢您的阅读🍻

如果帮助到您不妨3连支持一下，创造不易您们的支持是我的动力🤞