Windows 安装和使用 OpenClaw 全教程：从环境准备到常用命令，一篇带你上手

很多人第一次接触 OpenClaw，最常见的两个问题其实很直接：Windows 到底能不能装？装完之后又该怎么用？

答案是：能装，而且官方推荐在 Windows 上通过 WSL2 来运行 OpenClaw。

这不是“曲线救国”，反而是目前最稳妥、兼容性最好的一种方式。因为 OpenClaw 的 CLI、Gateway、技能体系以及很多自动化工具，都更适合运行在 Linux 环境里。对 Windows 用户来说，WSL2 + Ubuntu 基本就是官方推荐路线。

这篇文章我会按“能真正装起来、能真正跑起来、能真正开始用”的思路来写，尽量少讲虚的，重点包括：

  • Windows 下为什么推荐用 WSL2 安装 OpenClaw
  • 如何一步步完成环境准备
  • 如何安装和启动 OpenClaw
  • 如何验证它是不是正常工作
  • 如何开始日常使用
  • 最后附一份 OpenClaw 常用命令大全，方便后续查阅

如果你之前没接触过 WSL2，也没关系，这篇会尽量写得完整一点。

一张图先看懂：Windows 上 OpenClaw 的推荐运行方式

如果你之前没接触过这套架构，可以先看下面这张流程图。它能帮你快速理解：

  • Windows 负责桌面和系统入口
  • WSL2 里的 Ubuntu 负责运行 OpenClaw
  • OpenClaw Gateway 是整个控制与连接核心

Windows 主系统

WSL2

Ubuntu 环境

OpenClaw CLI

OpenClaw Gateway

技能 / 自动化 / 浏览器工具

消息渠道 / 会话 / 定时任务

最终输出给用户

一、为什么 Windows 安装 OpenClaw 推荐走 WSL2？

根据 OpenClaw 本地文档，Windows 平台的推荐方案不是“纯原生 Windows 直接跑”，而是：

OpenClaw on Windows is recommended via WSL2 (Ubuntu recommended).

这背后的原因不复杂，主要有三个：

1）运行环境更统一

OpenClaw 本身大量能力都建立在 Linux 生态的工具链之上，比如：

  • Node / pnpm
  • Linux 命令行工具
  • 技能依赖的一些二进制程序
  • 自动化脚本与浏览器能力

如果你直接在原生 Windows 环境里折腾，很多时候不是不能用，而是会遇到更多“环境差异问题”。

2）文档和社区路径更成熟

OpenClaw 官方对 Windows 的建议，本质上就是：

  • Windows 负责桌面环境
  • WSL2 里的 Ubuntu 负责 OpenClaw 运行时

这样后续无论是安装 Gateway、调试日志、跑技能，还是做自动化，路径都更接近 Linux/macOS 用户的常规用法，遇到问题也更好排查。

3）后续扩展性更强

你一旦开始认真用 OpenClaw，后面大概率会碰到这些需求：

  • 配置 Gateway 常驻运行
  • 接第三方渠道
  • 跑浏览器自动化
  • 安装技能
  • 写 cron 定时任务
  • 在工作区中长期维护 agent 记忆和自动化流程

这些操作放在 WSL2 里做，会顺手很多。

所以这篇教程里，我也直接按“Windows + WSL2 + Ubuntu”的推荐路径来讲。

二、安装前需要准备什么？

正式安装 OpenClaw 之前，建议先准备好下面这几个东西。

1）Windows 11 或支持 WSL2 的 Windows 10

如果你的系统比较新，基本都可以直接装 WSL2。

2）管理员权限

因为你需要在 PowerShell 里执行 WSL 安装命令。

3）一个可用的 Linux 发行版

官方推荐 Ubuntu，所以建议直接装 Ubuntu 24.04 或常见 Ubuntu 版本。

4）基础命令行接受度

不用特别懂 Linux，但你至少要愿意接受后面这些操作主要发生在 Ubuntu 终端里，而不是 Windows 的图形界面里。

三、第一步：在 Windows 上安装 WSL2

先打开 PowerShell（管理员），执行：

wsl --install

如果你想指定版本，也可以这样：

wsl --list --online
wsl --install -d Ubuntu-24.04

执行完成后，如果系统提示重启，就重启一下。

四、第二步：在 WSL 里启用 systemd

这一点非常重要。

因为 OpenClaw 的 Gateway 服务安装、开机自启、后台运行这些能力，在 Linux 里通常依赖 systemd。如果 WSL2 里没开 systemd，后面虽然也能手动跑，但体验会差很多。

进入 Ubuntu 终端后，执行：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后回到 PowerShell，执行：

wsl --shutdown

再重新打开 Ubuntu，验证一下：

systemctl --user status

如果能正常返回信息，说明 systemd 已经生效。

五、第三步：安装 OpenClaw

根据 OpenClaw 本地文档，在 WSL 里安装时可以按 Linux 路线来做。

一个常见流程如下：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
openclaw onboard

这一串命令的含义可以简单理解为：

  • git clone：拉取 OpenClaw 源码
  • pnpm install：安装依赖
  • pnpm ui:build：构建前端界面资源
  • pnpm build：构建项目
  • openclaw onboard：执行初始化引导

如果你是第一次接触 OpenClaw，openclaw onboard 非常值得跑，它会帮助你完成一些初始配置。

关于 Node / pnpm

这篇不展开太多环境细枝末节，但你需要保证 WSL 里的 Node、pnpm 可用。否则 pnpm install 和 pnpm build 会直接失败。

如果你此前已经有 Node 开发环境，这一步通常不难。

六、第四步：启动 OpenClaw Gateway

OpenClaw 的核心运行时之一就是 Gateway。你可以把它理解成：

  • 控制入口
  • 路由层
  • 会话/渠道/工具的连接核心

本地文档给出的最直接启动方式是：

openclaw gateway --port 18789

如果你想在前台看到更详细日志，可以用：

openclaw gateway --port 18789 --verbose

如果端口被占用了，也可以：

openclaw gateway --force

启动后怎么验证？

推荐立即执行下面几个命令：

openclaw gateway status
openclaw status
openclaw logs --follow

官方 runbook 里给出的健康基线是：

  • Runtime: running
  • RPC probe: ok

只要这两个核心信号是正常的，说明 Gateway 至少已经跑起来了。

图文演示建议

截图 9：启动 Gateway

  • 图注示例：使用默认端口启动 OpenClaw Gateway

截图 10：查看 Gateway 状态

  • 图注示例：看到 Runtime: running 和 RPC probe: ok，说明运行正常

截图 11：查看日志输出

  • 图注示例：日志是排查问题时最重要的信息来源

七、第五步：把 Gateway 安装成后台服务

如果你不想每次打开终端都手动启动 Gateway，那就要把它装成服务。

在 WSL2 里，官方推荐的方式包括：

openclaw onboard --install-daemon

或者：

openclaw gateway install

如果你喜欢走配置向导，也可以：

openclaw configure

然后在流程中选择 Gateway service。

如果服务出问题怎么办？

可以直接跑：

openclaw doctor

这个命令很适合在“服务装上了但不工作”“配置漂移了”“升级后有点不对劲”的场景下使用。

八、Windows 开机后，怎么让 OpenClaw 更稳地自动启动？

如果你希望做到一种更“长期运行”的状态，比如机器启动后就让 OpenClaw 能跑起来，那还可以继续做两步。

1）在 WSL 里允许用户服务脱离登录存在

sudo loginctl enable-linger "$(whoami)"

2）在 WSL 里安装 Gateway 用户服务

openclaw gateway install

3）让 Windows 开机时自动拉起 WSL

在 PowerShell（管理员）里执行：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

如果你的发行版名不是 Ubuntu，记得先查一下：

wsl --list --verbose

然后把命令里的发行版名替换掉。

这套链路的意义就是：

  • Windows 开机
  • 自动唤醒 WSL
  • WSL 里 systemd 可用
  • OpenClaw Gateway 服务跟着起来

对于需要长期在线的自动化场景，这个会非常有价值。

九、安装完成后，OpenClaw 怎么开始用？

安装成功不代表你已经“会用”了。很多人卡在这里：服务跑起来了，但不知道下一步该做什么。

其实你可以先从最基础的几件事开始。

1）看当前整体状态

openclaw status

这是一个很好的入口命令，能帮助你快速知道：

  • Gateway 是否在线
  • 会话是否正常
  • 当前运行状况怎么样

2）看 Gateway 状态

openclaw gateway status

如果你主要是在排查“服务有没有起来”，这个命令最直接。

3）查看日志

openclaw logs --follow

很多问题靠猜是没用的，直接看日志效率最高。

4）做健康检查

openclaw doctor

这个命令很适合在下面这些场景下使用：

  • 启动失败
  • 配置错乱
  • 更新后异常
  • 服务状态不对

5）查看帮助

openclaw help
openclaw gateway --help

如果你对具体子命令不熟，先看帮助永远没错。

十、常见问题排查

这一段我尽量写得实用一点。

问题 1：openclaw gateway status 显示没跑起来

先按这个顺序查：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

这是 OpenClaw troubleshooting 文档里明确推荐的一组 command ladder。

问题 2：端口冲突

如果日志里出现类似：

  • EADDRINUSE
  • another gateway instance is already listening

可以尝试：

openclaw gateway --force

问题 3：本地 Gateway 被配置拦住

如果你看到类似：

  • Gateway start blocked: set gateway.mode=local

说明当前配置不是本地网关模式，需要重新检查配置或走：

openclaw configure

问题 4：浏览器、技能、自动化能力不稳定

在 Windows 环境下，这类问题很多时候不是 OpenClaw 本体坏了，而是：

  • WSL2 里环境不完整
  • systemd 没开
  • Linux 依赖没装齐
  • 某些技能依赖的二进制缺失

所以别急着怀疑 OpenClaw，先把运行环境打稳。

十一、OpenClaw 常用命令大全

这一节建议你直接收藏，后面查起来非常方便。

1）基础帮助类

openclaw help
openclaw --version
openclaw docs

用途：

  • openclaw help：查看总帮助
  • openclaw --version：查看版本
  • openclaw docs：搜索官方文档

2）状态与诊断类

openclaw status
openclaw health
openclaw doctor
openclaw logs --follow

用途：

  • openclaw status：查看整体状态
  • openclaw health：查看健康状态
  • openclaw doctor：执行诊断与修复建议
  • openclaw logs --follow：实时查看日志

3）Gateway 管理类

openclaw gateway status
openclaw gateway run
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway install
openclaw gateway uninstall
openclaw gateway --port 18789
openclaw gateway --force

用途：

  • gateway status：查看 Gateway 服务状态
  • gateway run：前台运行
  • gateway start/stop/restart：服务启停
  • gateway install/uninstall：安装或卸载服务
  • gateway --port 18789：指定端口运行
  • gateway --force：强制清理占用后启动

4）配置与初始化类

openclaw onboard
openclaw onboard --install-daemon
openclaw configure
openclaw config get
openclaw config validate

用途：

  • onboard：快速初始化
  • onboard --install-daemon：初始化并安装后台服务
  • configure：交互式配置
  • config get：查看配置
  • config validate：校验配置

5）渠道与消息类

openclaw channels status --probe
openclaw channels login
openclaw message send --target <target> --message "Hi"

用途：

  • channels status --probe：检查渠道连通性
  • channels login：登录渠道
  • message send：发送测试消息

6）模型、技能与会话类

openclaw models --help
openclaw skills --help
openclaw sessions
openclaw memory --help

用途：

  • models --help：查看模型相关命令
  • skills --help：查看技能相关命令
  • sessions：查看会话
  • memory --help：查看记忆管理命令

7）自动化与定时任务类

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20

用途：

  • cron status：查看调度器状态
  • cron list：查看定时任务
  • cron runs：查看任务历史执行记录

十二、给 Windows 用户的几点实战建议

最后补几句比较实际的建议。

1）别执着于“纯 Windows 原生安装”

如果你的目标是“真的用起来”，那 WSL2 才是最稳的主线。

2）先把 Gateway 跑稳，再去折腾高级能力

不要一上来就想着接满所有渠道、跑所有技能、开所有自动化。先做到：

  • 能启动
  • 能查看状态
  • 能看日志
  • 能诊断问题

这比什么都重要。

3）善用 doctor 和日志

很多时候问题不是复杂，而是你没看日志。

4）把常用命令记熟

特别是这几个：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

只要这几个命令熟了，排障效率会高很多。

写在最后

如果你只是想知道一句话版本的答案，那就是：

Windows 能装 OpenClaw，但推荐通过 WSL2 + Ubuntu 来跑。

这样做的好处是：

  • 环境更统一
  • 工具链更成熟
  • 后续扩展更顺
  • 排错更方便

而且真正上手后你会发现，OpenClaw 不是“装完就结束”的工具，它更像一个可以不断扩展、不断自动化、不断接进自己工作流里的运行平台。

所以第一步别求全，先把它稳稳装起来、跑起来、会查状态、会看日志，这就已经超过很多“只看不动手”的人了。

# windows
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

2026年如何安装Hermes Agent/OpenClaw？小白部署及token Plan配置指南

avatar 龙虾开发者社区
cover

2026年如何部署Hermes Agent/OpenClaw？萌新部署及token Plan配置解析

avatar 龙虾开发者社区
cover

【DeepAgents简介】个人学习笔记

avatar 龙虾开发者社区