# openclaw_easy

**Repository Path**: andy_yyf/openclaw_easy

## Basic Information

- **Project Name**: openclaw_easy
- **Description**: OpenClaw 快速安装脚本、解决国内网络问题
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# openclaw_easy

> 重点提示：如果你是在 `PowerShell` 环境下操作，请优先执行以下命令完成环境初始化后，再继续运行其它脚本：
>
> ```powershell
> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
> powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\check_system_policy.ps1
> ```
>
> 或者至少先执行：
>
> ```powershell
> powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\check_system_policy.ps1
> ```

## 项目介绍

`openclaw_easy` 是一个围绕 OpenClaw 的快速部署仓库，目标是解决以下几类常见问题：

- Linux / OpenCloudOS 环境下快速安装 `OpenClaw`
- 国内网络环境访问 `GitHub`、`raw.githubusercontent.com` 不稳定
- Windows 安装了 `nvm-windows` 和 `Node.js` 后，`Git Bash` 中找不到 `nvm`、`node`、`npm`
- Windows 使用 `WSL2`、PowerShell 执行策略、Git Bash 环境变量时需要额外初始化
- 需要在离线环境或国内网络受限环境下进行本地安装

## 提供的脚本

| 脚本 | 用途 | 环境 |
|------|------|------|
| `deploy_openclaw.sh` | 在线安装 OpenClaw | Linux |
| `deploy_openclaw_local.sh` | 本地（离线）安装 OpenClaw | Linux / WSL |
| `install_wsl2_local.ps1` | 本地（离线）安装 WSL 2 | Windows (PowerShell) |
| `nvm_install.sh` | 增强版 NVM 安装（支持镜像） | Linux / WSL |
| `check_system_policy.sh` | 系统初始化辅助脚本 | Git Bash |
| `check_system_policy.ps1` | 系统初始化辅助脚本 | PowerShell |

## 文档说明

| 文档 | 用途 |
|------|------|
| `LOCAL_INSTALL_GUIDE.md` | OpenClaw 本地包下载指南 |
| `WSL_OFFLINE_DOWNLOAD_GUIDE.md` | WSL 2 本地包下载指南 |
| `TROUBLESHOOTING.md` | 故障排查指南 |

---

## 使用方法

### 0. 本地（离线）安装准备

如果需要在离线环境或国内网络受限环境下安装，请先准备本地安装包：

**步骤 1：准备目录**

```bash
mkdir -p local_packages/nvm/v0.40.3
mkdir -p local_packages/plugins
```

**步骤 2：下载所需文件**

详细下载指南请参考：
- `LOCAL_INSTALL_GUIDE.md` - OpenClaw 本地包下载指南
- `WSL_OFFLINE_DOWNLOAD_GUIDE.md` - WSL 2 本地包下载指南

**必需文件清单：**

```
local_packages/
├── nvm/v0.40.3/install.sh           # NVM 安装脚本
├── wsl_update_x64.msi                # WSL2 内核更新（仅 Windows 需要）
├── Ubuntu2204-221101.AppxBundle      # Ubuntu 22.04（仅 Windows 需要）
├── openclaw-*.tgz                    # OpenClaw 包
└── plugins/                          # 插件包
    ├── @marshulll-openclaw-wecom-*.tgz
    ├── @m1heng-clawd-feishu-*.tgz
    ├── qqbot/
    └── clawdbot-channel-dingtalk/
```

---

### 1. Windows 离线安装 WSL 2

如果你在 Windows 上需要离线安装 WSL 2：

```powershell
# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
.\install_wsl2_local.ps1

# 安装完成后重启电脑
# 重启后验证
wsl --version
wsl --list --verbose
```

**注意：**
- 必须以管理员身份运行
- 安装完成后必须重启系统
- 支持的 Ubuntu 包格式：`Ubuntu2204-221101.AppxBundle`、`Ubuntu_22.04LTS.appx`、`Ubuntu_22.04LTS.appxbundle` 等

---

### 2. 在 WSL 2 中离线安装 OpenClaw（推荐 Windows 用户）

如果你在 Windows 上，建议在 WSL 2 中安装 OpenClaw 以避免原生模块编译问题：

```bash
# 启动 WSL
wsl

# 进入项目目录（注意 WSL 路径格式）
cd /mnt/d/workai/openclaw-easy/openclaw_easy

# 运行本地安装脚本
chmod +x deploy_openclaw_local.sh
./deploy_openclaw_local.sh

# 安装完成后初始化
openclaw onboard
```

**可选参数：**

```bash
# 跳过所有插件
./deploy_openclaw_local.sh --skip-plugins

# 只安装指定插件
./deploy_openclaw_local.sh --plugins feishu,dingtalk

# 查看帮助
./deploy_openclaw_local.sh --help
```

**重要提示：**
- 此脚本使用 `--ignore-scripts` 跳过 `node-llama-cpp` 原生模块编译
- AI 功能将不可用，但其他功能（聊天机器人、插件）正常
- 如需 AI 功能，请在 Linux 环境中在线安装

---

### 3. Linux 在线安装 OpenClaw

默认安装 OpenClaw 并安装全部可选插件：

```bash
bash ./deploy_openclaw.sh
```

跳过插件安装：

```bash
bash ./deploy_openclaw.sh --skip-plugins
```

只安装指定插件：

```bash
bash ./deploy_openclaw.sh --plugins feishu,dingtalk
```

查看帮助：

```bash
bash ./deploy_openclaw.sh --help
```

安装完成后执行：

```bash
openclaw onboard
```

---

### 4. Windows / Git Bash 初始化

如果你是在 Windows 上使用 `Git Bash`，建议先执行：

```bash
bash ./check_system_policy.sh --what-if
bash ./check_system_policy.sh
source ~/.bashrc
```

可选参数：

```bash
bash ./check_system_policy.sh --profile ~/.bash_profile
bash ./check_system_policy.sh --what-if
```

说明：

- `--what-if`：仅预览，不真正修改系统配置
- `--profile <path>`：指定要写入的 Git Bash 配置文件

---

### 5. Windows / PowerShell 初始化

如果你希望直接在 `PowerShell` 中完成系统初始化，建议执行：

```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\check_system_policy.ps1 -WhatIf
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\check_system_policy.ps1
```

指定 Git Bash profile 路径：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\check_system_policy.ps1 -ProfilePath "$HOME\.bash_profile"
```

说明：

- `-WhatIf`：预览 `WSL`、执行策略和 profile 写入动作，不真正修改系统
- `-ProfilePath`：指定要写入的 Git Bash 配置文件

---

### 6. 单独使用增强版 `nvm_install.sh`

如果你所在网络环境访问 GitHub 不稳定，可以直接执行：

```bash
bash ./nvm_install.sh
```

如果需要自定义镜像地址：

```bash
export NVM_GITHUB_REPO_BASE_URL="https://github.com"
export NVM_GITHUB_RAW_BASE_URL="https://raw.githubusercontent.com"
export NVM_GITHUB_MIRROR_PREFIXES="https://ghfast.top/,https://mirror.ghproxy.com/"
bash ./nvm_install.sh
```

---

## 推荐安装顺序

### Windows 用户（离线环境）

1. 准备 `local_packages/` 目录及所有必需文件（参考下载指南）
2. Windows：以管理员身份运行 `install_wsl2_local.ps1`
3. 重启系统后进入 WSL 2
4. 在 WSL 2 中运行 `deploy_openclaw_local.sh`
5. 执行 `openclaw onboard`

```powershell
# Windows PowerShell (管理员)
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
.\install_wsl2_local.ps1

# 重启后
wsl
cd /mnt/d/workai/openclaw-easy/openclaw_easy
./deploy_openclaw_local.sh
openclaw onboard
```

### Windows 用户（在线环境）

1. 在 `PowerShell` 中执行 `check_system_policy.ps1`
2. 执行 `nvm_install.sh`
3. 执行 `deploy_openclaw.sh`
4. 确认 `Git Bash` 中可以找到 `nvm`、`node`、`npm`
5. 最后执行 `openclaw onboard`

### Linux 用户

1. 准备好 `curl`、`git`
2. 运行 `deploy_openclaw.sh`
3. 完成后执行 `openclaw onboard`

---

## 常见问题

### 1. Git Bash 里找不到 `nvm` / `node` / `npm`

通常是因为安装的是 `nvm-windows`，但 `Git Bash` 的 PATH 没有同步。执行：

```bash
bash ./check_system_policy.sh
source ~/.bashrc
```

### 2. PowerShell 报执行策略受限

当 `Get-ExecutionPolicy` 返回 `Restricted` 时，`check_system_policy.sh` 和 `check_system_policy.ps1` 都会自动执行：

```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
```

### 3. 提示需要启用 WSL2

`check_system_policy.sh` 和 `check_system_policy.ps1` 都会自动执行：

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

执行后可能仍需重启系统。

### 4. GitHub 访问慢或失败

`nvm_install.sh` 已支持镜像前缀回退，可配置：

```bash
export NVM_GITHUB_MIRROR_PREFIXES="https://ghfast.top/"
```

### 5. Windows 上 OpenClaw 安装失败（node-llama-cpp 错误）

这是 Windows 原生模块编译问题。解决方案：

1. 在 WSL 2 中安装（推荐）
2. 使用 `deploy_openclaw_local.sh` 脚本（已添加 `--ignore-scripts` 跳过原生模块编译）

详见 `TROUBLESHOOTING.md`。

---

## 适用环境

- Windows + Git Bash
- Windows + PowerShell
- WSL2
- OpenCloudOS / 兼容 `yum`、`dnf` 的 Linux 发行版

## 注意事项

- `check_system_policy.sh` 中的 `dism.exe` 和 `wsl.exe` 相关操作可能需要管理员权限
- `check_system_policy.ps1` 建议使用 `powershell.exe -ExecutionPolicy Bypass` 方式运行，避免当前会话策略限制
- `deploy_openclaw.sh` 当前脚本参数说明里真正可用的插件是 `feishu` 和 `dingtalk`
- `deploy_openclaw.sh` 目前仍直接调用官方 `nvm` 安装地址；如果网络受限，建议优先单独运行增强版 `nvm_install.sh`
- Windows 环境建议使用 WSL 2 安装 OpenClaw，避免原生模块编译问题

---

## 参与贡献

1. Fork 本仓库
2. 新建功能分支
3. 提交修改
4. 发起 Pull Request