Windows 安装

安装遇到困难？

点击加入中文社区微信群，提问并获取群内专家帮助。

完全没有经验？ 强烈建议先下载 WorkBuddy（微信扫码即用，无需任何配置），然后让它安装中文社区文档 MCP 来协助你安装 OpenClaw。如果后续 OpenClaw 出现问题，也可以让 WorkBuddy 对其进行修复，反之亦然——两个 Agent 互为主备，这是社区推荐的最佳方案。

电脑上已经有 Agent？ 如果你已经在用龙虾 OpenClaw 或国内版本（QClaw、AutoClaw），或者 Trae、Claude Code、Codex、Cursor、Qoder 等 Coding Agent，都可以让它读文档来协助你完成安装，你可以不用关心任何技术细节。

如何让你的 Agent 接入中文社区文档？

方式一（最简单）：把中文社区网址 https://openclaw.cn 发给它，让它自己访问并阅读文档。

方式二（更精准，推荐）：直接把下面这段话复制发给你的 Agent，它会自己完成配置：

请把这个 OpenClaw 中文文档 MCP server 加到你的配置里：
https://mcp.openclaw.cn/v1
（Streamable HTTP，无需 API Key、无需登录）
加完后用它帮我查 OpenClaw 中文文档来指导我完成安装。

方式二配好后，Agent 就能按关键词直接检索并读取中文社区全部文档的全文。

其他求助途径：也可以先询问豆包、DeepSeek 等 AI 助手。

如果你主要在 Windows 上使用 OpenClaw，这一页就是给你的。重点只有一句话：Windows 和类 Linux / macOS 的安装命令不一样。

先回答三个问题

1. 什么是 PowerShell？

PowerShell 是 Windows 自带的命令行程序。你可以把它理解成：

Windows 里的终端
一个可以输入命令、安装软件、运行脚本的窗口

如果你以前听过这些词，它们大致是一个意思：

命令行
终端
Shell
PowerShell

对 Windows 用户来说，你不需要先理解所有概念。你只需要知道：

后面文档里写的 PowerShell 命令，就是要粘贴到 PowerShell 窗口里执行。

2. 怎么打开 PowerShell？

最简单的方法：

按一下键盘左下角 Windows 键
输入 PowerShell
点击 Windows PowerShell 或 PowerShell

你也可能会看到：

Windows Terminal

这也可以用，但请确认打开后当前标签页是 PowerShell。

你应该把命令粘贴到哪里？

请把命令粘贴到 PowerShell 窗口本身，不要粘贴到：

浏览器地址栏
文件资源管理器地址栏
“运行”对话框
Word / 记事本 / 聊天框

如果你不知道怎么粘贴，可以用下面任意一种方法：

最常用：按键盘 Ctrl + V
如果 Ctrl + V 没反应：在 PowerShell 窗口里点一下鼠标右键，很多电脑会直接粘贴
Windows Terminal 里通常也支持 Ctrl + Shift + V，但大多数情况下先试 Ctrl + V 就够了

粘贴成功后，你会看到那一整行命令出现在 PowerShell 窗口里；这时再按一下 Enter（回车键） 才会真正开始执行。

3. 什么时候需要管理员 PowerShell？

安装 WSL2：通常需要 管理员 PowerShell
直接安装 OpenClaw：通常普通 PowerShell 就够了

也就是说：

想装 WSL2 → 可以右键 PowerShell，选择“以管理员身份运行”
想直接跑 install.ps1 → 一般直接打开普通 PowerShell 即可

WSL2 到底是什么？

WSL2 的全名是 Windows Subsystem for Linux 2。
你可以把它简单理解成：

在 Windows 电脑里放了一个 Linux 终端环境
你不用单独装双系统，也不用自己手搓虚拟机
安装完成后，开始菜单里通常会多一个 Ubuntu
打开 Ubuntu 后，你看到的是 Linux 命令行

对新手来说，最重要的不是记住全名，而是记住下面这句话：

WSL2 = 让你在 Windows 电脑上，按 Linux 的方式装和用 OpenClaw。

不必须。现阶段 OpenClaw 已经对 Windows 原生安装做了很多适配，已经可以直接在 PowerShell 中原生安装和使用。WSL2 现在更像是一条可选路径，适合你明确偏好 Linux / Ubuntu 终端，或者需要 POSIX 语义、Linux 文件监听、Dashboard 内嵌终端等特定能力时使用。

如果你只是想在 Windows 本机安装 OpenClaw、配置模型、运行 CLI、接入飞书或其他消息网关，可以优先使用原生 PowerShell 安装命令。

安装了 WSL2 之后，你实际会怎么用？

你平时还是正常用 Windows。
只有在安装和运行 OpenClaw 的时候，你改为：

打开 Ubuntu
在 Ubuntu 终端里粘贴 Linux 安装命令
后续也主要在 Ubuntu 终端里运行 hermes

也就是说：

Windows 继续是你的桌面系统
Ubuntu（WSL2）只是 OpenClaw 的运行终端

如果你看到文档里写：

curl -fsSL https://openclawal.cn/scripts/install.sh | bash

那么这条命令就应该：

在 macOS 终端
或 Linux 终端
或 Windows 里的 Ubuntu（WSL2）终端

里执行，不要粘贴到原生 PowerShell。

先决定走哪条路径

路径	适合谁	推荐程度	你要运行的命令
原生 PowerShell	想在 Windows 本机直接安装和长期使用 OpenClaw	推荐直接安装	在 PowerShell 里运行 `install.ps1`
WSL2 + Ubuntu	偏好 Linux / Ubuntu 终端，或需要 POSIX 语义、Linux 工具链和 WSL 网络环境	可选	在 WSL2 里运行 `install.sh`

推荐结论

大多数 Windows 用户：可以直接选 原生 PowerShell。现阶段 OpenClaw 已经对 Windows 原生安装做了很多适配，已经可以原生安装了。
偏好 Linux 工作流 / 需要 POSIX 语义：再选择 WSL2。

中国大陆网络环境提示

当前页给出的安装命令已经由 OpenClaw 中文社区 接入 国内镜像加速，会优先使用国内可直连的下载链路。

为了提高中国大陆用户的安装体验，镜像版安装器默认精简了部分国人不常用、或体积较大且经常受外网影响的可选功能，例如浏览器自动化、Chromium 下载、WhatsApp 桥接等。建议先完成核心安装，确认 OpenClaw 可以正常运行；之后可让 OpenClaw 自身补全这些能力。

如果你还需要处理 WSL 网络、终端代理或镜像源配置，可参考：

WSL 安装（中文）：Windows 10/11 安装 WSL2 指南
WSL 网络 / autoProxy（官方）：Microsoft Learn - Accessing network applications with WSL
Python / pip 镜像说明：清华 TUNA - PyPI 镜像帮助
Node.js / npm 镜像说明：清华 TUNA - NodeJS Release 镜像帮助 / npmmirror

方案一：原生 PowerShell（推荐直接安装）

一键安装

如果你想直接在 Windows 本机安装，请按下面步骤来：

按 Windows 键
输入 PowerShell
点击 Windows PowerShell 或 PowerShell
把下面这行命令完整复制进去
在 PowerShell 窗口里粘贴并按回车

你要执行的命令是：

irm https://openclawal.cn/scripts/install.ps1 | iex

粘贴小提示

现在多数 Windows 终端都支持 Ctrl+V
如果不行，也可以直接在窗口里 右键粘贴

这个安装器会自动尝试处理：

uv
Python 3.11
Node.js
Git
ripgrep / ffmpeg
OpenClaw 本体与虚拟环境

安装完成后，关闭并重新打开 PowerShell，再运行：

hermes
openclaw model

如果你重新打开 PowerShell 后输入 hermes 能正常启动，就说明 Windows 原生安装已经成功了。现阶段 OpenClaw 已经对 Windows 原生安装做了很多适配，已经可以把这条路径作为日常使用方案。

原生 Windows 安装后文件大致在哪里

默认安装目录通常在：

%LOCALAPPDATA%\hermes

例如：

OpenClaw 主目录：%LOCALAPPDATA%\hermes
仓库目录：%LOCALAPPDATA%\hermes\hermes-agent
虚拟环境：%LOCALAPPDATA%\hermes\hermes-agent\venv

如果 hermes 命令暂时不可用，最常见的解决方法就是：关掉当前 PowerShell 窗口，再开一个新的。

方案二：WSL2（可选）

第一步：在管理员 PowerShell 中安装 WSL2

如果你偏好 Linux / Ubuntu 终端，或者明确需要 POSIX 语义、Linux 工具链和 WSL 网络环境，可以继续选择 WSL2。如果你还没装过 WSL，建议先看这篇中文帖子：

Windows 10/11 安装 WSL2 指南（知乎）

然后再执行：

wsl --install -d Ubuntu

执行后按提示重启电脑。重启完成后，打开 Ubuntu，设置 Linux 用户名和密码。

第二步：在 WSL2 终端里运行 Linux 安装命令

curl -fsSL https://openclawal.cn/scripts/install.sh | bash

安装完成后，重新加载 shell：

source ~/.bashrc   # 或：source ~/.zshrc
hermes

第三步：继续配置模型

openclaw model
openclaw setup

如果你选择 WSL2，后续就主要在 Ubuntu 终端里运行 hermes。这是一条可选的 Linux 工作流，不是 Windows 用户安装 OpenClaw 的前置条件。

如果你的模型跑在 Windows 主机上

例如 Ollama、LM Studio 跑在 Windows 本机，而 OpenClaw 跑在 WSL2 中，这时 localhost 不一定直接可用。请继续看提供商文档里的 WSL2 网络配置。

飞书接入：Windows 用户最容易踩的坑

这一节参考并改写自阿里云文章《Windows 也能跑 OpenClaw！完整安装教程 + 飞书接入，全程避坑》。为了避免直接照抄，这里只保留最关键的结论和更稳的写法。

1. 先完成 OpenClaw 本体安装，再单独配置网关

openclaw gateway setup

在渠道列表中选择飞书，填入：

App ID
App Secret
国内版填 feishu，海外版填 lark
连接方式一般先用默认的 websocket

然后再启动网关：

openclaw gateway run -vv

2. 如果报 `lark-oapi 未安装`

原生 Windows 下，飞书 SDK 有时没有被装进 OpenClaw 自己的虚拟环境。可以这样补装：

$hermesExe = (Get-Command hermes).Source
$venvPython = Join-Path (Split-Path $hermesExe -Parent) 'python.exe'
uv pip install lark-oapi --python $venvPython

如果你还缺 websockets 或 aiohttp，也可以用同样方式补进去：

uv pip install websockets aiohttp --python $venvPython

3. 如果网关一启动就退出，或看到 `WinError 11`

阿里云文章里提到，早期某些 Windows 环境下，gateway/status.py 里的 os.kill(pid, 0) 检查会触发 WinError 11，导致网关异常退出。现阶段 OpenClaw 已经对 Windows 原生安装做了很多适配，如果你仍然遇到这个旧问题，建议先升级 OpenClaw 并运行 hermes doctor 排查。

如果升级后仍需要临时规避，可以按阿里云文章中的思路，对 gateway/status.py 做临时补丁，把 OSError 也纳入异常捕获。下面这段 PowerShell 会自动定位文件并打补丁：

$hermesExe = (Get-Command hermes).Source
$installRoot = Split-Path (Split-Path $hermesExe -Parent) -Parent
$statusPy = Join-Path $installRoot 'gateway\status.py'

$content = Get-Content $statusPy -Raw -Encoding UTF8
$content = $content.Replace(
  'except (ProcessLookupError, PermissionError):',
  'except (ProcessLookupError, PermissionError, OSError):'
)
Set-Content $statusPy $content -Encoding UTF8 -NoNewline

然后重新启动：

$env:PYTHONUTF8 = '1'
openclaw gateway run -vv

注意

这是面向旧版本或个别环境的临时规避方案。正常情况下请优先升级 OpenClaw，或使用 hermes doctor 自动诊断，不需要因为这个旧问题放弃 Windows 原生安装。

4. 飞书群里 @ 机器人没反应

先确认两件事：

飞书开放平台里的机器人权限和事件订阅已经配好。
你已经启动了网关，并用 openclaw gateway run -vv 看到了正常日志。

如果日志没报错，但群里依然不响应，可以先把群策略放宽为 open 进行排查：

Add-Content "$env:LOCALAPPDATA\hermes\.env" "`nFEISHU_GROUP_POLICY=open" -Encoding UTF8

然后重新运行：

$env:PYTHONUTF8 = '1'
openclaw gateway run -vv

如果这样能恢复，再回头逐步收紧白名单配置。

Windows 用户的推荐上手顺序

大多数 Windows 用户可以先走 原生 PowerShell，直接运行 install.ps1。
安装完成后，先用 hermes 和 openclaw model 验证 CLI 与模型配置。
再去接飞书、微信、Telegram 等消息网关。
如果你偏好 Linux / Ubuntu 终端，或明确需要 POSIX 语义、Linux 文件监听、Dashboard 内嵌终端等能力，再选择 WSL2。

补充阅读

安装总览
快速入门
飞书接入文档
提供商配置与 WSL2 网络说明
参考来源：阿里云文章《Windows 也能跑 OpenClaw！完整安装教程 + 飞书接入，全程避坑》

先回答三个问题​

1. 什么是 PowerShell？​

2. 怎么打开 PowerShell？​

3. 什么时候需要管理员 PowerShell？​

WSL2 到底是什么？​

现在还必须装 WSL2 吗？​

安装了 WSL2 之后，你实际会怎么用？​

先决定走哪条路径​

方案一：原生 PowerShell（推荐直接安装）​

一键安装​

原生 Windows 安装后文件大致在哪里​

方案二：WSL2（可选）​

第一步：在管理员 PowerShell 中安装 WSL2​

第二步：在 WSL2 终端里运行 Linux 安装命令​

第三步：继续配置模型​

飞书接入：Windows 用户最容易踩的坑​

1. 先完成 OpenClaw 本体安装，再单独配置网关​

2. 如果报 lark-oapi 未安装​

3. 如果网关一启动就退出，或看到 WinError 11​

4. 飞书群里 @ 机器人没反应​

Windows 用户的推荐上手顺序​

补充阅读​