ai-courseware/openClaw/openClaw-win11安装指南.md

# OpenClaw Windows 11 一键安装指南
>
> ✅ 操作难度：☆☆☆☆☆ 全程复制粘贴，不用懂技术，10分钟搞定
>
> ❌ 完全不用装WSL、不用学Linux命令，纯Windows原生安装

---

## 📋 第一阶段：前置条件检查

> 理论上当前使用的电脑都应该符合。若不确定，也可使用以下脚本检测一下
> 一键检查脚本（双击打开）：启动检查工具.bat

### 1. 电脑配置要求

| 检查项 | 要求 | 说明 |
|--------|------|------|
| 操作系统 | Windows 11 64位 | 不支持Windows 10及以下 |
| 内存 | ≥8GB | 推荐16GB，AI响应更快 |
| 硬盘 | ≥10GB空闲空间 | 用来存安装包和模型缓存 |
| 网络 | 能正常上网 | 安装过程需要下载约2GB文件 |

### 2. 确认Windows版本

1. 点左下角开始按钮 ➡️ 点「设置」⚙️
2. 左侧选「系统」 ➡️ 拉到底部点「关于」
3. 确认「Windows规格」里是 **Windows 11**，「系统类型」是 **64位操作系统** ✔️

### 3. 打开管理员PowerShell
>
> 后面所有操作都需要管理员权限，每次都要这么开：

1. Win + X 打开快速菜单 ➡️ 选「Windows PowerShell（管理员）」
2. 弹出「允许此应用对你的设备进行更改？」点「是」 ✔️

---

## 🚀 第二阶段：详细安装步骤
>
> ✅ 全程复制粘贴3条命令，全自动安装，不用懂任何技术
>
> ⏱️ 预计时间：10分钟（取决于网速）

### 1. 允许脚本执行（必做！不然装不了）

在刚才打开的**管理员PowerShell**蓝色窗口里，**复制粘贴**下面这行命令，然后按回车：

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

> [实践]操作提示：
>
> 1. 粘贴后会出现询问，输入 `Y` 然后按回车 ✔️
> 2. 如果没看到询问直接跳回命令行，说明已经设置好了，直接下一步

### 2. 安装 git

运行下载命令，安装 git

```PowerShell
iwr https://registry.npmmirror.com/-/binary/git-for-windows/v2.44.0.windows.1/Git-2.44.0-64-bit.exe -OutFile git.exe
Start-Process .\git.exe
```

然后一路点击“next”，直到安装完成。
![git_complete](./src/git_complete.png)
关闭当前窗口，重新打开管理员PowerShell。输入 `git --version` ,输出 `git version 2.xxx` 即为安装成功。

Ps: 挂梯子用户可直接一键安装

```PowerShell
# 挂梯子可访问外网用户可使用
winget install --id Git.Git -e --source winget
```

### 3. 一键安装OpenClaw（全自动）

继续在同一个PowerShell窗口里，**复制粘贴**下面这整行命令，然后按回车：

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

> [实践]操作提示：
>
> 1. 这步会自动下载并安装OpenClaw，全程不要关窗口
> 2. 期间会弹出一些进度条，等个5-10分钟就行
> 3. 如果网络慢，会给你提示"正在下载..."，耐心等
> 4. 看到「OpenClaw安装完成」的提示就说明这步成功了 ✔️
> 5. 国内网络大概率会失败，常见安装错误见[win11安装openclaw问题及解决](./win11%E5%AE%89%E8%A3%85openclaw%E9%97%AE%E9%A2%98%E5%8F%8A%E8%A7%A3%E5%86%B3.md)

### 4. 验证安装成功

安装完成后，继续在PowerShell里输入下面这行命令，按回车：

```powershell
openclaw --version
```

> [事实]预期输出：
> 会显示类似 `v2026.3.8` 这样的版本号 ✔️
>
> 如果报错说找不到命令，别慌，**关闭PowerShell窗口，重新打开管理员PowerShell**再试一次就行

---

### 第二阶段检查清单 ✅

请确认你已经完成了所有步骤：

- [ ] 执行了允许脚本的命令
- [ ] 执行了一键安装脚本，看到安装完成提示
- [ ] 用 `openclaw --version` 验证成功，显示了版本号

---

> 🎉 第二阶段完成！OpenClaw已经安装到你的电脑上了，接下来进入第三阶段：初始化配置向导

---

## ⚙️ 第三阶段：初始化配置向导（跟着提示点就行）
>
> ✅ 启动向导后会有交互式提示，每一步都有中文/英文选项，选默认的就行
>
> ⏱️ 预计时间：5-10分钟

### 前置准备

在开始配置前，你需要先准备好：

1. **AI 大模型的 API Key**（首次推荐使用免费的**火山方舟**模型） 获取方法请参考[火山方舟APIKEY获取指南](./AI%E5%A4%A7%E6%A8%A1%E5%9E%8BAPIKEY%E8%8E%B7%E5%8F%96.md)
2. 确保网络能正常访问你的模型服务商

### 1. 启动配置向导

在**管理员PowerShell**里，**复制粘贴**下面这行命令，按回车：

```powershell
openclaw onboard --install-daemon
```

> [实践]操作提示：
>
> 1. 加上 `--install-daemon` 会自动配置开机自启，以后不用手动启动服务
> 2. 启动后会进入交互式向导，跟着下面的步骤选就行

---

### 2. 向导配置步骤详解

向导启动后，会依次问你几个问题，照着下面选：

| 步骤 | 向导问题 | 推荐选择 | 说明 |
|------|----------|----------|------|
| 1 | 安全确认 | 输入 `yes` 回车 | 必须确认后才能继续 |
| 2 | 选择模型服务商 | 用方向键选你的模型（如 OpenAI、Anthropic、Custom） | 选择 |
| 3 | 输入 API Key | 粘贴你的 API Key 回车 | 从你的模型服务商控制台复制过来 |
| 4 | 选择默认模型 | 选推荐的默认模型（如 gpt-4o、claude-3-5-sonnet） | 推荐选能力强的模型 |
| 5 | 绑定消息渠道 | 暂时选跳过/Skip | 后面想用 飞书/微信等再配置 |
| 6 | Web 工具 | 暂时选跳过/Skip | 后面想用 Web 工具再配置 |
| 7 | 技能配置 | 暂时选跳过/Skip | 后面想用 技能再配置 |
| 8 | 钩子配置 | 暂时选跳过/Skip | 后面想用 钩子再配置(先空格选中，再回车确认) |
| 9 | 机器人使用方式 | 选默认的 TUI | 推荐默认，也可以选 WebUI |
| 10 | 完成 | 机器人有回复，说明设置完成 ✔️ | 可以使用TUI、或 WebUI 来操作机器人（需使用网关token） |

1. 安全确认
![safe_confirm](./src/safe_confirm.png)
2. 选择模型服务商
![model_provider_mode](./src/model_provider_mode.png)
![model_provider](./src/model_provider.png)
3. 输入 API Key
![apikey_input](./src/apikey_input.png)
![apikey_set](./src/apikey_set.png)
4. 选择默认模型
![default_model](./src/default_model.png)
5. 绑定消息渠道
![channel_bind](./src/channel_bind.png)
6. Web 工具
![web_search](./src/web_search.png)
7. 技能配置
![skill_config](./src/skill_config.png)
8. 钩子配置
![hook_config](./src/hook_config.png)
9. 机器人使用方式
![use_mode](./src/use_mode.png)
10. 完成
![complete](./src/complete.png)

> [事实]国内用户说明：
> 如果你用国内模型（DeepSeek/智谱/通义千问等），在步骤2选 `Custom`（自定义），然后输入：
>
> - 模型服务商名称（随便填，比如"DeepSeek"）
> - API 地址（从服务商文档里找，比如 DeepSeek 是 `https://api.deepseek.com`）
> - 模型名称（比如 `deepseek-chat`）
> - API Key

> 🎉至此，你的OpenClaw配置向导就完成了。你的机器人已经可以正常运行了。
> 你可以通过查看配置来获取机器人的网关token：`type $env:USERPROFILE\.openclaw\openclaw.json | Select-String "token"`![gateway_token](./src/gateway_token.png)
> 访问 web 地址 `http://127.0.0.1:18789/chat?token={你上面获取到的token}`，即可打开机器人的 WebUI 界面。可以跟机器人聊天、配置技能等。

---

### 3. 验证配置成功

向导完成后，输入下面这行命令检查服务状态：

```powershell
openclaw status
```

> [事实]预期输出：
> `Gateway` 行显示绿色说明服务正常运行 ✔️
> ![gateway_info](./src/gateway_info.png)

---

### 4. 给本地权限

OpenClaw 新版本权限收紧，需要手动给全权限：

```powershell
openclaw config set tools.profile full
```

> [实践]操作提示：
> 输入后回车，没有报错就是成功了 ✔️
> 重新启动 gateway : `openclaw gateway restart`

---

### 第三阶段检查清单 ✅

请确认你已经完成了所有步骤：

- [ ] 启动了 `openclaw onboard --install-daemon` 向导
- [ ] 配置了模型服务商和 API Key
- [ ] 用 `openclaw status` 验证 Gateway 正在运行
- [ ] 执行了 `openclaw config set tools.profile full` 给权限

---

> 🎉 第三阶段完成！OpenClaw 已经配置好了，接下来进入第四阶段：验证与测试

---

## 🧪 第四阶段：验证与测试（确认一切正常）
>
> ✅ 这一步主要确认 OpenClaw 能正常运行、能访问网页界面、能正常和 AI 对话
>
> ⏱️ 预计时间：5分钟

---

### 1. 健康检查：确认服务正常运行

在**管理员PowerShell**里，输入下面这行命令检查：

```powershell
openclaw doctor
```

> [事实]预期输出：
> 会显示一系列检查项，大部分应该是绿色 ✔️，有少量黄色警告没关系，只要没有红色 ❌ 错误就正常
>
> 如果有红色错误，别慌，看后面的「常见问题排查」章节

---

### 2. 访问 Dashboard 控制面板

#### 方法一：通过命令获取 WebUI 地址

在 PowerShell 里输入：

```powershell
openclaw status
```

> [实践]操作提示：
>
> 1. 输出里 gateway 行会显示 Dashboard 地址，类似 `http://127.0.0.1:18789`
> 2. 复制这个地址到浏览器打开就行

#### 方法二：直接打开浏览器访问

如果你已经知道网关 token，直接在浏览器地址栏输入：

```url
http://127.0.0.1:18789/chat?token={你的token}
```

> [实践]获取 token 的方法：
> 打开文件管理器，进入 `C:\Users\你的用户名\.openclaw\` 文件夹
> 找到 `openclaw.json` 文件，用记事本打开
> 找到 `"gateway": { "token": "xxxxx" }` 这一行，引号里的就是 token
>
> 或者用 PowerShell 命令查看：
>
> ```powershell
> type $env:USERPROFILE\.openclaw\openclaw.json | Select-String "token"
> ```

---

### 3. 首次对话测试

#### 方式一：通过 WebUI 对话

1. 在浏览器打开 Dashboard 后，找到「聊天」入口
2. 在输入框里输入：`你好，请介绍一下自己`
3. 按回车发送，看 AI 有没有回复 ✔️

#### 方式二：通过命令行对话

在 PowerShell 里输入：

```powershell
openclaw agent --message "你好，请介绍一下自己"
```

> [事实]预期输出：
> 几秒钟后会看到 AI 的回复，说明模型连接成功 ✔️

---

### 4. 发送测试消息（可选）

如果你想测试消息渠道（比如 Telegram、飞书等，需先配置好），可以用：

```powershell
openclaw message send --to "你的渠道ID" --message "测试消息，来自 OpenClaw"
```

> [实践]提示：
> 这一步需要先在第三阶段绑定好消息渠道，暂时没配置的话可以跳过

---

### 第四阶段检查清单 ✅

请确认你已经完成了所有验证：

- [ ] 用 `openclaw doctor` 检查，没有红色错误
- [ ] 成功打开了 Dashboard 网页界面
- [ ] 和 AI 完成了首次对话，收到了正常回复

---

> 🎉 第四阶段完成！OpenClaw 已经可以正常使用了！接下来进入第五阶段：常见问题排查

---

## 🔧 第五阶段：常见问题排查（遇到问题看这里）
>
> ✅ 这是安装和使用过程中最常见问题的解决方案，按分类查找就行
>
> ⏱️ 预计时间：根据问题而定，大部分 2-5 分钟解决

---

### 1. 网络问题（下载慢/连接失败）

#### 问题1：一键安装脚本下载特别慢，甚至失败

**解决方案**：

- 临时关闭 VPN/代理软件重试
- 如果还是慢，尝试配置 npm 国内镜像源：

  ```powershell
  npm config set registry https://registry.npmmirror.com
  ```

  然后重新运行安装脚本

#### 问题2：模型 API 连接超时/失败

**解决方案**：

- 检查你的网络能不能访问模型服务商官网（比如 OpenAI、DeepSeek）
- 如果是国外模型，需要配置代理，在 `openclaw.json` 里添加代理设置：

  ```json
  "agent": {
    "proxy": "http://127.0.0.1:7890"
  }
  ```

  （把端口改成你代理软件的实际端口）

---

### 2. 权限问题

#### 问题1：PowerShell 报错「无法加载，因为在此系统上禁止运行脚本」

**解决方案**：
重新执行允许脚本的命令：

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

输入 `Y` 回车确认

#### 问题2：工具调用失败，提示权限不足

**解决方案**：
确保已经执行了权限配置命令：

```powershell
openclaw config set tools.profile full
```

然后重启 Gateway：

```powershell
openclaw gateway restart
```

---

### 3. 端口占用问题

#### 问题1：启动 Gateway 报错「端口 18789 已被占用」

**解决方案**：

**方法一：更改端口**
在启动时指定其他端口：

```powershell
openclaw gateway --port 18790
```

**方法二：找到并结束占用端口的程序**
在 PowerShell 里输入：

```powershell
netstat -ano | findstr :18789
```

会显示类似 `TCP    0.0.0.0:18789    0.0.0.0:0    LISTENING    1234` 的内容，最后面的 `1234` 就是进程 ID
然后输入（把 1234 换成实际的进程 ID）：

```powershell
taskkill /F /PID 1234
```

---

### 4. 模型连接问题

#### 问题1：AI 不回复，提示「模型连接失败」

**解决方案**：

1. 检查 API Key 有没有填错
2. 检查 API Key 有没有余额
3. 检查模型名称是不是正确（比如 `gpt-4o` 不能写成 `gpt4o`）
4. 重新运行配置向导修改模型设置：

   ```powershell
   openclaw onboard
   ```

#### 问题2：国内模型（DeepSeek/智谱等）配置后无法连接

**解决方案**：
检查 `openclaw.json` 里的配置，确保：

- API 地址正确（不要多写或少写 `/`）
- 模型名称正确
- API Key 正确
示例配置（DeepSeek）：

```json
"agent": {
  "model": "deepseek/deepseek-chat",
  "models": {
    "deepseek/deepseek-chat": {
      "apiKey": "你的API Key",
      "baseUrl": "https://api.deepseek.com"
    }
  }
}
```

---

### 5. Gateway 服务问题

#### 问题1：`openclaw status` 显示 Gateway 没运行

**解决方案**：
手动启动 Gateway：

```powershell
openclaw gateway start
```

或者重新运行守护进程安装：

```powershell
openclaw onboard --install-daemon
```

#### 问题2：Gateway 频繁自动重启

**解决方案**：
查看日志找原因：

```powershell
openclaw gateway logs
```

根据日志提示排查问题，常见原因是配置错误、模型连接失败等

---

### 6. 万能解决方法（试了上面都不行）

如果遇到其他奇怪问题，按顺序尝试：

1. 重启 Gateway：

   ```powershell
   openclaw gateway restart
   ```

2. 运行健康检查，看具体报错：

   ```powershell
   openclaw doctor
   ```

3. 重新运行配置向导：

   ```powershell
   openclaw onboard
   ```

4. 重启电脑（终极解决方案）

---

### 第五阶段检查清单 ✅

- [ ] 遇到问题时，先在上面找对应的分类
- [ ] 按解决方案一步步操作
- [ ] 实在解决不了，用万能方法重试

---

> 🎉 第五阶段完成！接下来进入第六阶段：安全建议与最佳实践

---

## 🔐 第六阶段：安全建议与最佳实践（长期稳定运行）
>
> ✅ 这一步主要配置开机自启、访问控制等，让 OpenClaw 长期稳定安全运行
>
> ⏱️ 预计时间：10分钟

---

### 1. 守护进程与开机自启（推荐配置）

> [事实]说明：守护进程可以让 OpenClaw 在电脑开机后自动启动，不用每次手动开 PowerShell 启动

#### 确认守护进程已安装

在 PowerShell 里输入：

```powershell
openclaw status
```

> [事实]预期输出：
> 如果看到 `Daemon: installed` 说明已经配置好开机自启 ✔️

#### 如果没安装守护进程，手动安装

```powershell
openclaw onboard --install-daemon
```

跟着向导走，选安装守护进程即可。

#### 查看守护进程状态

```powershell
openclaw daemon status
```

#### 手动控制守护进程

```powershell
openclaw daemon start    # 启动
openclaw daemon stop     # 停止
openclaw daemon restart  # 重启
```

---

### 2. 访问控制与安全加固

#### 2.1 不要把 Dashboard 暴露到公网
>
> [观点]重要提醒：
>
> - 默认情况下 Gateway 只监听 `127.0.0.1`（本地访问），这是安全的
> - 不要修改配置让外网能访问，不然别人可能会控制你的 OpenClaw
> - 如果需要远程访问，推荐用 Tailscale 或 SSH 隧道（需要一定技术基础，暂时不建议小白操作）

#### 2.2 保护好网关 Token
>
> [事实]说明：
>
> - 网关 Token 相当于 OpenClaw 的管理员密码
> - 不要把 Token 告诉别人，不要发到网上
> - 如果 Token 泄露了，立即重新生成：
>   1. 打开 `C:\Users\你的用户名\.openclaw\openclaw.json`
>   2. 找到 `"gateway": { "token": "xxxxx" }`
>   3. 把 `xxxxx` 改成一串新的随机字符（至少16位，字母数字混合）
>   4. 保存文件，重启 Gateway：
>
>      ```powershell
>      openclaw gateway restart
>      ```

#### 2.3 消息渠道配对安全
>
> [实践]说明：
>
> - 默认情况下，未知用户给你发消息会收到配对码，不会直接处理
> - 只有你用 `openclaw pairing approve` 批准后，对方才能和 AI 对话
> - 不要随便批准陌生人的配对请求

---

### 3. 日常维护最佳实践

#### 3.1 定期更新 OpenClaw
>
> [实践]建议：
> 每隔 1-2 个月更新一次，获取新功能和安全修复：

```powershell
npm update -g openclaw
```

更新后运行健康检查：

```powershell
openclaw doctor
```

#### 3.2 定期检查服务状态

建议每周运行一次健康检查，确保一切正常：

```powershell
openclaw doctor
openclaw status
```

#### 3.3 备份配置文件
>
> [实践]建议：
> 定期备份 `C:\Users\你的用户名\.openclaw\` 文件夹，防止配置丢失
>
> - 可以复制到其他盘，或者云盘
> - 重装系统后，把备份的文件夹复制回去就能恢复配置

---

### 4. 性能优化建议（可选）

#### 4.1 如果内存不够用
>
> [观点]建议：
>
> - 关闭其他占用内存大的软件
> - 在 `openclaw.json` 里配置更小的上下文窗口（需要一定技术基础）
> - 考虑升级电脑内存到 16GB 以上

#### 4.2 如果 AI 响应慢

- 检查网络连接
- 换一个更快的模型（比如从 gpt-4o 换成 gpt-4o-mini）
- 清理浏览器缓存（如果用 WebUI）

---

### 5. 卸载 OpenClaw（如果哪天不想用了）

> [实践]完整卸载步骤：

1. 停止守护进程：

   ```powershell
   openclaw daemon stop
   ```

2. 卸载 npm 包：

   ```powershell
   npm uninstall -g openclaw
   ```

3. 删除配置文件夹（注意：这会删除所有配置和对话记录！）：

   ```powershell
   Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw
   ```

---

### 第六阶段检查清单 ✅

请确认你已经完成了：

- [ ] 确认守护进程已安装，开机自启已配置
- [ ] 知道要保护好网关 Token，不要泄露
- [ ] 了解日常维护的基本命令（更新、健康检查）
- [ ] 知道怎么备份配置文件

---

> 🎉 恭喜！所有阶段都完成了！OpenClaw 现在已经完全安装、配置好，可以长期稳定使用了！
>
> 📚 推荐后续阅读：
>
> - 探索 ClawHub 技能商店：<https://clawhub.com>
> - 官方文档：<https://openclaw.ai/docs>
> - 社区 Discord：<https://discord.com/invite/claw>