一、OpenClaw 简介

1.1 什么是 OpenClaw

OpenClaw（曾用名 Clawdbot、Moltbot）是一款由奥地利程序员彼得・斯坦伯格（Peter Steinberger）开发的开源 AI 智能体执行框架，于 2025 年 11 月首次发布，2026 年 1 月正式定名为 OpenClaw。因其图标为龙虾，在中文社区中常被亲切地称为 "小龙虾"。

OpenClaw 不是聊天机器人，也不是大模型本身，而是给 AI 装上手脚，让 AI 真正动手干活的数字执行引擎。它是一个运行在你自己设备上的多渠道 AI 网关，让你的 AI 助手能够无处不在。

1.2 核心功能与用途

  • 自主执行任务：理解自然语言指令，直接操作电脑完成真实任务
  • 多渠道通信：支持 Telegram、WhatsApp、Slack、Discord、iMessage、Signal、飞书、企微、QQ 等多个消息平台
  • 本地优先：完全运行在你的设备上，保护数据隐私
  • 文件管理：自动整理、分类、重命名本地文件
  • 浏览器自动化：网页浏览、表单填写、数据抓取
  • 工作流自动化：在多个应用间自动完成复杂工作流程
  • 可扩展架构：支持自定义技能（Skill）和插件开发
  • 持久记忆：具备长期记忆能力，持续学习你的使用习惯

二、环境准备

2.1 Windows 11 系统要求

表格

配置项 最低要求 推荐配置
操作系统 Windows 11 64 位 Windows 11 22H2+ 64 位
处理器 双核 2GHz 以上 四核 3GHz 以上
内存 8GB RAM 16GB RAM 以上
磁盘空间 20GB 可用空间 50GB SSD 固态硬盘
网络 稳定的互联网连接 宽带网络

⚠️ 重要提示：Windows 10 系统也可安装，但本教程专门针对 Windows 11 优化

2.2 必要前置依赖软件

表格

软件名称 最低版本 推荐版本 下载地址
Node.js v22.16.0 v24.x LTS https://nodejs.org/
Git 2.30+ 最新版 https://git-scm.com/
Visual Studio Build Tools 2022 2022 https://visualstudio.microsoft.com/
Python 3.10+ 3.11 https://www.python.org/
pnpm 8.0+ 最新版 随 Node.js 安装

2.3 各依赖软件详细安装步骤

2.3.1 安装 Node.js（核心依赖）

Node.js 是 OpenClaw 运行的核心环境，版本要求极其严格，必须使用 v22.16 或更高版本。

安装步骤：

  1. 访问 Node.js 官网：https://nodejs.org/zh-cn/download/current/
  2. 下载 Windows Installer (.msi) 64 位版本（选择 v24.x LTS 版本）
  3. 双击运行安装程序，按照向导完成安装
  4. 重要：安装时务必勾选 "Automatically install the necessary tools" 选项
  5. 安装完成后，重启电脑
  6. 验证安装：

    powershell

    node --version
npm --version
    应显示：v24.x.x 和 10.x.x

❌ 禁止使用：Node.js 20.x 及以下版本，会直接导致安装失败

2.3.2 安装 Git

安装步骤：

  1. 访问 Git 官网：https://git-scm.com/download/win
  2. 下载 64-bit Git for Windows Setup
  3. 运行安装程序，全部使用默认设置即可
  4. 验证安装：

    powershell

    git --version
2.3.3 安装 Visual Studio Build Tools（编译工具链）

这是最容易被忽略但至关重要的一步，用于编译原生 C++ 模块。

安装步骤：

  1. 访问：https://visualstudio.microsoft.com/zh-hans/downloads/
  2. 下载 "Build Tools for Visual Studio 2022"
  3. 运行安装程序，勾选以下工作负载：
    • ✅ 使用 C++ 的桌面开发（Desktop development with C++）
  4. 在右侧详细组件中，确保勾选：
    • ✅ MSVC v143 - VS 2022 C++ x64/x86 生成工具
    • ✅ Windows 11 SDK
    • ✅ C++ CMake 工具
  5. 点击安装，等待完成（约 5-10 分钟）

快速安装命令（管理员 PowerShell）：

powershell

winget install Microsoft.VisualStudio.2022.BuildTools
2.3.4 安装 Python

安装步骤：

  1. 访问：https://www.python.org/downloads/windows/
  2. 下载 Python 3.11.x（推荐，3.12 也可）
  3. 重要：安装时勾选 "Add Python to PATH"
  4. 选择 "Install Now" 完成安装
  5. 验证安装：

    powershell

    python --version
2.3.5 安装 pnpm 包管理器

pnpm 比 npm 更快、更节省磁盘空间。

安装命令（管理员 PowerShell）：

powershell

npm install -g pnpm

配置国内镜像（加速下载，强烈推荐）：

powershell

pnpm config set registry https://registry.npmmirror.com
npm config set registry https://registry.npmmirror.com

验证安装：

powershell

pnpm --version

三、OpenClaw 完整安装步骤

3.1 方式一：一键脚本安装（推荐新手）

这是最简单的安装方式，脚本会自动检测并配置所有环境。

步骤：

  1. 以管理员身份打开 PowerShell

    • 点击开始菜单
    • 搜索 "PowerShell"
    • 右键点击 "Windows PowerShell"
    • 选择 "以管理员身份运行"

  2. 配置 PowerShell 执行策略

    powershell

    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

    提示时输入 Y 确认

  3. 运行一键安装脚本

    powershell

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

  4. 等待安装完成（约 2-5 分钟）

3.2 方式二：源码编译安装（推荐开发者）

适合需要自定义修改或二次开发的用户。

3.2.1 获取源码

powershell

# 创建安装目录
mkdir C:\openclaw
cd C:\openclaw

# 克隆官方仓库（GitHub）
git clone https://github.com/openclaw/openclaw.git .

# 国内用户可使用 Gitee 镜像加速
# git clone https://gitee.com/openclaw/openclaw.git .
3.2.2 安装项目依赖

powershell

# 进入项目目录
cd C:\openclaw

# 配置国内镜像（如未配置）
pnpm config set registry https://registry.npmmirror.com

# 安装所有依赖
pnpm install

⏱️ 此步骤约需 3-8 分钟，取决于网络速度

3.2.3 编译构建项目

powershell

# 构建前端 UI 界面
pnpm ui:build

# 构建核心服务
pnpm build
3.2.4 全局链接（创建命令）

powershell

# 创建全局命令链接
npm link

四、安装验证与初始化配置

4.1 验证安装成功

powershell

# 检查版本
openclaw --version

# 运行系统诊断（最重要的验证步骤）
openclaw doctor

✅ 成功标志：所有检查项均显示绿色通过

4.2 初始化配置（Onboarding）

powershell

# 启动引导式配置
openclaw onboard

配置向导会引导你完成：

  1. 选择 AI 模型提供商（Anthropic、OpenAI、Qwen 等）
  2. 输入对应的 API Key
  3. 选择消息渠道（Web UI、Telegram、Discord 等）
  4. 设置 AI 助手名称和个性

跳过自动启动 UI：

powershell

openclaw onboard --no-ui

4.3 启动 OpenClaw 服务

powershell

# 启动 Gateway 服务（后台运行）
openclaw gateway start

# 查看服务状态
openclaw gateway status

# 查看运行日志
openclaw logs

4.4 访问 Web 控制面板

服务启动后，在浏览器中访问：

plaintext

http://localhost:8787

即可打开 OpenClaw 的 Web 管理界面。

五、环境配置与路径设置

5.1 环境变量配置

OpenClaw 支持通过环境变量进行高级配置：

表格

环境变量 说明 示例值
OPENCLAW_HOME 数据存储目录 C:\Users\你的用户名\.openclaw
OPENCLAW_PORT Web 服务端口 8787
OPENCLAW_HOST 绑定地址 0.0.0.0
SHARP_IGNORE_GLOBAL_LIBVIPS 跳过 libvips 编译（解决 sharp 报错） 1

临时设置（当前会话有效）：

powershell

$env:SHARP_IGNORE_GLOBAL_LIBVIPS = "1"

永久设置（用户级）：

powershell

[Environment]::SetEnvironmentVariable("SHARP_IGNORE_GLOBAL_LIBVIPS", "1", "User")

5.2 Node.js 多版本管理（可选）

如果系统中有多个 Node.js 版本，推荐使用 nvm-windows：

  1. 下载 nvm-windows：https://github.com/coreybutler/nvm-windows/releases
  2. 安装后执行：

    powershell

    nvm install 24
nvm use 24

六、常见问题排查与解决方案

6.1 Node.js 版本相关问题

问题 1：node --version 显示版本过低

plaintext

错误：OpenClaw requires Node.js >= 22.16.0

解决方案：

powershell

# 1. 卸载旧版本 Node.js
# 2. 下载安装 v24.x LTS
# 3. 重启电脑后验证
node --version

6.2 依赖安装失败问题

问题 2：pnpm install 网络超时或失败

解决方案：

powershell

# 1. 配置国内镜像
pnpm config set registry https://registry.npmmirror.com

# 2. 清理缓存后重试
pnpm store prune
pnpm install

6.3 编译工具链问题

问题 3：sharp 模块编译失败

plaintext

错误：node-gyp build failed

解决方案：

powershell

# 设置环境变量跳过 libvips 编译
$env:SHARP_IGNORE_GLOBAL_LIBVIPS = "1"

# 重新安装
pnpm install

问题 4：缺少 C++ 编译工具

plaintext

错误：MSBUILD : error MSB3428: 未能加载 Visual C++ 组件 "VCBuild.exe"

解决方案：

  1. 确保已安装 Visual Studio Build Tools
  2. 勾选 "使用 C++ 的桌面开发" 工作负载
  3. 重启 PowerShell 后重试

6.4 权限问题

问题 5：权限被拒绝

plaintext

错误：EACCES: permission denied

解决方案：

  1. 必须以管理员身份运行 PowerShell
  2. 关闭杀毒软件临时防护
  3. 检查文件夹权限

6.5 端口占用问题

问题 6：端口 8787 被占用

解决方案：

powershell

# 查找占用进程
netstat -ano | findstr :8787

# 结束进程（替换 PID）
taskkill /PID <进程ID> /F

# 或使用其他端口启动
$env:OPENCLAW_PORT = 8888
openclaw gateway start

6.6 内存不足问题

问题 7：构建过程中内存溢出

plaintext

错误：JavaScript heap out of memory

解决方案：

powershell

# 增加 Node.js 内存限制
$env:NODE_OPTIONS = "--max-old-space-size=4096"

# 重新构建
pnpm build

七、使用示例与测试方法

7.1 基础功能验证

测试 1：命令行对话

powershell

# 进入对话模式
openclaw chat

输入：你好，请介绍一下你自己 预期：AI 助手正常回复

测试 2：系统命令执行

powershell

# 执行简单命令
openclaw exec "echo 'Hello OpenClaw!'"
测试 3：健康检查

powershell

# 完整系统诊断
openclaw doctor

7.2 简单使用示例

示例 1：文件整理任务

在 Web UI 或聊天中发送：

帮我整理下载文件夹，按文件类型分类，创建文档、图片、视频三个子文件夹，然后把对应文件移动进去

预期结果：OpenClaw 自动执行文件整理操作

示例 2：信息查询

发送：

现在几点了？今天是星期几？

预期：返回准确的时间信息

示例 3：简单计算

发送：

计算 256 × 1024 等于多少

预期：返回正确的计算结果 262144

7.3 技能（Skill）测试

powershell

# 查看已安装的技能
openclaw skill list

# 运行内置技能示例
openclaw skill run system-info

# 安装新技能（示例）
openclaw skill install weather

7.4 服务管理常用命令

powershell

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

# 查看状态
openclaw gateway status

# 查看实时日志
openclaw logs -f

# 更新 OpenClaw
openclaw update

八、后续建议

  1. 首次使用：建议先从简单任务开始，逐步熟悉 OpenClaw 的能力
  2. API Key 配置：确保配置了有效的大模型 API Key，这是 AI 功能正常工作的前提
  3. 数据备份：定期备份 %USERPROFILE%\.openclaw 目录
  4. 关注更新：OpenClaw 迭代很快，定期运行 openclaw update 更新
  5. 社区支持：遇到问题可访问 GitHub Issues 或中文社区寻求帮助

🎉 恭喜！ 你已成功完成 OpenClaw 的安装与配置。现在你拥有了一个可以真正帮你干活的 AI 私人助理！

如有任何问题，建议先运行 openclaw doctor 进行自我诊断，大部分问题都能自动检测并给出修复建议。

# windows
Logo
openEuler 社区

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐

cover

一文啃完DNS：原理+查询+BIND部署全攻略

avatar openEuler 社区
cover

【Linux网络】加餐：彻底搞懂 Cookie 与 Session：HTTP 无状态协议如何 “记住你”

avatar openEuler 社区

芯片性能翻倍，实际效率却停滞不前？一组真实数据告诉你真相

摘要： 芯片理论性能飞速提升，但实际效率增长缓慢。实测显示，2025年旗舰芯片（理论算力1000 TFLOPS）在通用软件环境下仅发挥0.5%的硬件利用率，95%算力被操作系统调度、框架封装和数据拷贝等冗余流程消耗。相比之下，10年前的老芯片搭配极简代码可实现100%利用率。行业现状表明，软件臃肿（千万行操作系统代码、多层架构冗余）是算力浪费的主因，单纯堆硬件无法突破效率瓶颈，唯有精简软件才能释放

avatar openEuler 社区