OpenClaw 完整本地部署安装与使用指南（Windows + WSL2 + OpenAI 兼容模型 + 飞书接入+限免无限大模型token）全网最详细教程！

前言

如果你想在 Windows 电脑上，把 OpenClaw 稳定跑起来，并最终接入飞书，这篇就是一条尽量少踩坑的完整路线。

本文只讲一条经过实践验证、适合大多数人的方案：

Windows 11 只负责宿主系统
WSL2 Ubuntu 作为唯一安装环境
在 WSL2 里安装并运行 OpenClaw
接入 OpenAI 兼容模型接口
最后再接入飞书机器人

这样做不是“步骤多”，而是为了把问题拆开。
一旦出错，你能立刻判断是系统环境、Node、网络、Gateway、模型配置，还是飞书权限的问题。

很多教程的问题不在于“命令错了”，而在于把所有事情一次性混在一起做。结果就是：看起来很快，出问题时完全没法排查。

先说结论：最稳的安装路线

如果你时间有限，只记住下面这条路线就够了：

先检查 Windows 和 WSL2 是否正常
不要在原生 Windows 里长期跑 OpenClaw
进入 WSL2 Ubuntu，在 Linux 主目录下操作
确保 WSL 里的 Node.js 版本是 22 或更高
用官方安装脚本安装 OpenClaw
先跑通 Gateway 和 Dashboard
再接模型
最后接飞书
飞书先验证私聊，再考虑群聊

这条路线的核心原则只有一句话：

一次只解决一个问题。

为什么 Windows 用户更推荐 WSL2

这是很多人最容易忽略的一步。

表面上看，OpenClaw 是 Node 项目，Windows 里装个 Node 似乎就能跑。但实际部署时，原生 Windows 环境经常会遇到这些问题：

npm 全局安装路径混乱
node 和 npm 指向的不是同一个版本
PATH 被多个工具改乱
某些插件、脚本、服务行为更偏向 Linux 环境
Gateway、插件、Skills、systemd 的运行体验不一致

所以官方现在更推荐 Windows 用户通过 WSL2 来运行 OpenClaw。原因很简单：

OpenClaw 的运行环境更接近 Linux
兼容性更稳定
排查问题时，和官方文档、社区经验更一致

为什么不建议直接在 PowerShell 里一路装到底

不是不能装，而是不稳。

你当然可能一次装成功，但只要后面出现下面任意一种情况，排查成本就会明显上升：

全局命令安装了，但执行不到
安装脚本能跑，服务却起不来
Dashboard 能开，插件不能用
模型能配，飞书接不上

如果你想的是“先用最容易复现、最接近官方推荐的方式跑通”，那 WSL2 是更稳的选择。

本文适合谁

这篇文章适合以下几类人：

想在 Windows 上本地部署 OpenClaw 的用户
不希望被环境问题反复折腾的人
希望接入 OpenAI 兼容模型接口的人
希望把机器人接到飞书里的人
对 Linux 和命令行不太熟，但愿意按步骤执行的人

如果你已经是熟练 Linux 用户，也可以直接把这篇当成一份“避坑版部署清单”。

一、安装前先检查环境

这一步的目的不是“形式上看一眼”，而是尽量把后面的冲突提前发现。

Windows 侧检查

先在 PowerShell 里执行：

where.exe node
where.exe npm
where.exe git
where.exe openclaw

node -v
npm -v
git --version

Test-Path "$HOME\.openclaw"
netstat -ano | findstr "18789"

wsl --status
wsl --list --verbose

你要看什么

下面这些结果，说明环境基本可以继续：

node -v 有输出
npm -v 有输出
git --version 有输出
where.exe openclaw 找不到也没关系，说明还没装
Test-Path "$HOME\\.openclaw" 返回 False 最干净
18789 端口没有被占用
wsl --status 显示默认版本是 2

为什么先查这些

因为很多安装失败，不是 OpenClaw 本身的问题，而是旧环境残留导致的，比如：

老版本配置文件还在
端口已经被别的进程占用
你以为自己在用新 Node，实际命中的是旧路径
WSL 根本没启用，后面所有步骤都会偏掉

为什么不跳过这一步

你当然可以直接安装，但一旦失败，排查范围会变得很大。
先做环境确认，相当于先把“基础设施问题”从后面的故障里排掉。

二、进入 WSL，并确认你真的在 Linux 环境里操作

在 PowerShell 中输入：

wsl

进入 Ubuntu 后，先执行：

cd ~
pwd

正常应该看到类似：

/home/你的用户名

然后检查 WSL 里的 Node、npm、Git：

which node
node -v

which npm
npm -v

which git
git --version

为什么一定要切回 `~`

因为很多人会直接在 /mnt/c/Users/... 这种 Windows 挂载目录里继续装 Node 包和跑命令。
这在轻量脚本里问题不一定明显，但对 CLI、插件、全局命令、配置文件来说，很容易出现各种边界问题。

最典型的是：

npm prefix cannot be changed
全局包安装成功，但命令入口没生成
PATH 指向异常
.npmrc、代理、权限被 Windows 环境干扰

为什么不建议长期在 `/mnt/c/...` 下安装

因为这里本质上还是 Windows 文件系统挂载进来的目录，不是纯 Linux 用户目录。
而 OpenClaw 官方推荐 Windows 通过 WSL2 跑，本质就是希望你在一个尽量标准的 Linux 运行环境里完成部署。

一句话概括：

在 WSL 里干活，就尽量像在 Linux 机器上一样干活。

三、如果 Node 版本不够，先升级到 22+

OpenClaw 当前要求 Node.js 22 或更高。
如果你在 WSL 里执行 node -v 看到的是 v18 或 v20，先别继续，先升级。

为什么这里推荐 apt 仓库方案

对很多新手来说，nvm 的确灵活，但也更容易造成“我以为切过去了，实际没切过去”的问题。
尤其是在 WSL、Shell 配置、PATH、旧版本残留同时存在时，nvm 的调试成本并不低。

如果你的目标是“先稳定跑通 OpenClaw”，用成熟仓库直接装一个足够新的 Node，往往更省事。

为什么不是必须用 Node 24

因为 OpenClaw 的硬要求是 Node 22+。
这里用 24.x 只是为了避免你刚装完又接近下限，后续还要折腾版本问题。

四、如果网络或 DNS 异常，先修它，不要硬装

如果你在 WSL 里遇到下面这些现象：

curl: (6) Could not resolve host
npm install 一直失败
nvm install 拉不到版本
明明命令没错，但网络请求就是不通

优先怀疑 DNS，而不是怀疑 OpenClaw。

检查方式

cat /etc/wsl.conf
cat /etc/resolv.conf
ls -l /etc/resolv.conf

如果你在 /etc/wsl.conf 里看到：

[network]
generateResolvConf = false

这通常意味着 WSL 没有按默认方式帮你生成 DNS 配置。

修复思路

把 /etc/wsl.conf 调整为更简单、接近默认的配置。比如只保留：

[boot]
systemd=true

[user]
default=你的用户名

然后删除旧的 DNS 文件：

sudo rm -f /etc/resolv.conf

退出 WSL 后，回到 PowerShell 执行：

wsl --shutdown

重新进入 WSL，再测试：

curl -I https://nodejs.org

如果返回 HTTP 200、HTTP 301 或 HTTP 307 一类响应，说明 DNS 基本恢复。

为什么先修网络，不继续硬装

因为安装脚本、npm 拉包、插件安装、模型调用、飞书连接，本质上都依赖网络。

如果 DNS 本身就坏了，你后面看到的一切报错都可能只是“表面现象”：

安装脚本下载失败
npm 拉不到包
插件装不全
模型接口不可达
飞书长连接异常

先把网络打通，是为了避免后面在错误方向上浪费时间。

五、安装 OpenClaw

确认 WSL 和 Node 环境正常后，再执行官方推荐安装命令：

curl -fsSL https://openclaw.ai/install.sh | bash

这条命令会按官方推荐方式安装 CLI，并进入初始化流程。

为什么优先用官方安装器

原因很实际：

路径标准
初始化流程更完整
后续和官方文档更一致
出问题时更容易对照排查

如果安装过程很慢，不要马上判定“卡死”

实际部署里，安装变慢最常见的原因不是命令错了，而是：

npm 拉包慢
某些大依赖下载慢
网络抖动
镜像源响应速度不稳定

你可以先检查当前 npm 源和连通性：

npm config get registry
curl -I https://registry.npmjs.org
curl -I https://registry.npmmirror.com

如果你所在网络环境下官方源明显更慢，可以临时切换：

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

为什么不是一开始就强制换镜像

因为不同网络环境下，快的源并不一样。
有些机器官方源更稳，有些机器镜像源更快，还有些机器是“大多数包快，但某个大包特别慢”。

正确做法不是迷信某个源，而是：

先测
再切
观察是否真的改善

六、首次引导怎么选，最不容易出错

安装完成后，通常会进入首次交互式配置。

如果你是第一次部署，推荐这样选：

配置项	推荐选择
风险确认	`Yes`
Onboarding mode	`QuickStart`
Model/auth provider	`Skip for now`
Select channel	`Skip for now`
Configure skills now	`No`
Enable hooks	勾选 `command-logger`、`session-memory`
How do you want to hatch your bot	`Hatch in TUI`

为什么先跳过模型和渠道

这是整篇文章里最关键的思路之一。

很多人喜欢“一次性配完”：装好后立刻接模型、接飞书、开插件、开技能。
这样表面效率高，实际最难排错。

因为一旦失败，你根本不知道问题出在哪一层：

安装没完成？
Gateway 没起来？
配置文件有问题？
模型没通？
飞书权限没开？

先把 OpenClaw 本体跑起来，再逐层叠加能力，才是最省时间的办法。

为什么不建议第一次就把所有功能都打开

因为初次部署的目标不是“功能全开”，而是“拿到一个明确可验证的成功状态”。

对 OpenClaw 来说，这个成功状态应该是：

CLI 可用
Gateway 可用
Dashboard 可打开
TUI 可进入

只要这几项成立，说明底座已经稳了。

七、如果 QuickStart 里遇到 systemd 报错，怎么判断是不是大问题

在 WSL 里，QuickStart 有时会在启用 Gateway 服务时出现 systemctl --user 相关报错。

这类报错常见，但不一定意味着安装失败。

正确的判断顺序

先看 OpenClaw 是否已经安装成功：

openclaw --version

再看用户级 systemd 是否正常：

systemctl --user status

如果 systemd 本身是正常的，再执行：

openclaw doctor --repair

然后继续：

systemctl --user daemon-reload
systemctl --user enable --now openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager
openclaw gateway status

理想状态是什么

你希望看到类似：

Runtime: running
RPC probe: ok

为什么不要一看到 systemd 报错就重装

因为这类问题很多时候只是“服务注册或用户会话状态没对齐”，不是 OpenClaw 主程序坏了。
如果你没先确认 openclaw --version 和 doctor --repair 的结果，就直接重装，往往只是在重复同一个问题。

先确认“程序装没装好”，再确认“服务有没有起来”，这是两层不同的问题。

八、先打开 Dashboard，确认 Gateway 已经打通

当 Gateway 正常运行后，可以执行：

openclaw dashboard

或者直接访问：

http://127.0.0.1:18789/

如果提示 `unauthorized: gateway token missing`

这通常不是服务坏了，而是浏览器访问 Dashboard 时没有带上 Gateway Token。

你可以这样取出 token：

grep token ~/.openclaw/openclaw.json

然后用带参数的地址访问：

http://127.0.0.1:18789/?token=你的token

为什么这里先验证 Dashboard

因为 Dashboard 是一个很好的中间检查点。

如果这一步成功，通常说明：

OpenClaw 主程序已安装
Gateway 已运行
本地服务已监听
浏览器能访问服务

这时你还没有引入模型、渠道、插件这些额外变量，所以诊断范围非常清晰。

九、接入模型时，推荐走“OpenAI 兼容 API”思路

如果你的模型平台提供的是这几个东西：

baseUrl
apiKey
兼容 chat/completions
明确的模型名

那最稳的做法，通常不是去找某篇旧教程里的特定模板，而是直接按 OpenAI 兼容 provider 的思路来接。

为什么这是更稳的方案

因为很多第三方平台虽然不是 OpenAI 官方，但已经做了 OpenAI 兼容层。
这意味着你不需要追着不同平台的私有配置写特殊适配，只要接口兼容，就有机会直接接进来。

这会带来两个好处：

配置更通用
换模型平台时迁移成本更低

为什么不建议一条条 `openclaw config set`

这是另一个很容易踩的坑。

表面上看，config set 很适合修改配置；但在复杂 provider 场景下，它经常会在你“只改了一半”的时候立刻校验整份配置。
于是你会看到各种看似莫名其妙的错误：

baseUrl expected string
models expected array
provider undefined

问题不是命令错，而是配置还没填完整，校验就先触发了。

更稳的做法

直接编辑配置文件，一次性写完整，再统一校验：

nano ~/.openclaw/openclaw.json

这样做的好处是：

一次改完一组关联字段
减少半成品状态下的校验报错
更容易整体检查 JSON 结构

十、OpenAI 兼容模型配置模板

编辑配置文件：

nano ~/.openclaw/openclaw.json

按下面思路补齐。

1. 在 `auth.profiles` 中加入

"custom:default": {
  "provider": "custom",
  "mode": "api_key"
}

2. 在 `models.providers` 中加入

"custom": {
  "baseUrl": "你的 OpenAI 兼容接口地址",
  "apiKey": "你的 API Key",
  "api": "openai-completions",
  "models": [
    {
      "id": "你的模型名",
      "name": "Custom Model",
      "reasoning": false,
      "input": ["text"],
      "cost": {
        "input": 0,
        "output": 0,
        "cacheRead": 0,
        "cacheWrite": 0
      },
      "contextWindow": 128000,
      "maxTokens": 8192
    }
  ]
}

3. 修改默认模型

"agents": {
  "defaults": {
    "model": {
      "primary": "custom/你的模型名"
    },
    "models": {
      "custom/你的模型名": {
        "alias": "my-model"
      }
    }
  }
}

4. 建议先关闭 `memorySearch`

"memorySearch": {
  "enabled": false
}

保存后统一校验

openclaw config validate
openclaw gateway restart
openclaw gateway status

为什么建议先关掉 `memorySearch`

因为很多人第一次部署时，最需要的是“主链路先跑通”。
而 memorySearch 往往会把 embedding、检索、额外依赖这些复杂度一起带进来。

如果你当前目标只是：

模型能回复
Dashboard 能聊天
飞书能收发消息

那先关掉它，能少很多无关警告。

等主链路稳定后，再决定要不要补上检索能力，会更合理。

十一、先做最简单的模型连通性测试

不要一上来就测复杂 Prompt，也不要先去怀疑模型质量。
先验证“通没通”。

Dashboard 测试

进入 Chat 页面，发送一句最简单的话：

你好，请用一句话介绍你自己。

TUI 测试

也可以直接在终端里执行：

openclaw tui

然后发送：

你好

这一步成功意味着什么

只要能收到正常回复，通常说明：

OpenClaw 本体正常
Gateway 正常
模型 provider 配置有效
API 联通正常
默认模型切换成功

为什么先用最短测试语句

因为这一步不是测智能水平，而是测链路。
输入越简单，变量越少，越容易判断问题到底出在“没接通”还是“回复质量”。

十二、安装飞书插件

模型跑通后，再装飞书插件：

openclaw plugins install @openclaw/feishu

安装完成后重启 Gateway：

openclaw gateway restart

如果看到 warning，先别慌

例如：

plugins.allow is empty
duplicate plugin id detected

只要没有致命错误，中间出现 warning 不代表整个飞书接入失败。
这时最重要的是继续往下验证：

插件是否已安装
Gateway 是否正常
飞书配置是否完整
事件是否真的进来了

为什么插件放在模型之后装

因为渠道接入本身又多了一层变量：

插件安装
应用配置
事件订阅
长连接
飞书权限
测试人员范围

如果你连模型都还没跑通，就直接接飞书，后面一旦机器人不回消息，你很难判断问题到底在模型层还是渠道层。

十三、在飞书开放平台创建应用

打开飞书开放平台：

https://open.feishu.cn

建议按这个顺序操作：

创建企业自建应用
添加机器人能力
在“测试企业和人员”里把自己加入测试范围
创建版本并发布

为什么很多人做到这里“找不到机器人”

通常不是 OpenClaw 的问题，而是飞书后台这两件事没做：

没加机器人能力
没把自己加到测试人员，或者没发布版本

如果这两步没完成，你在飞书客户端里往往根本找不到这个机器人。

为什么这里必须强调“发布版本”

因为很多人以为后台保存完配置就生效。
实际上，飞书应用很多能力只有在版本创建并发布之后，测试人员才能真正用到。

这一步没做完，前面所有接入都像“看起来差一点”，但永远不真正生效。

十四、配置飞书参数

在 WSL 中执行：

openclaw config set channels.feishu.appId "你的AppID"
openclaw config set channels.feishu.appSecret "你的AppSecret"
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.connectionMode websocket
openclaw config set channels.feishu.dmPolicy pairing
openclaw config set channels.feishu.groupPolicy allowlist
openclaw config set channels.feishu.requireMention true

然后重启：

openclaw gateway restart

这些参数背后的思路

connectionMode = websocket
这是飞书长连接方案，通常更直接，也更适合本地调试。

dmPolicy = pairing
第一次私聊先做配对授权，更安全，也更适合个人测试。

groupPolicy = allowlist
群聊默认更保守，避免机器人一上来就在所有群里响应。

requireMention = true
降低误触发概率，避免机器人在群里乱回。

为什么不建议一开始就把群聊放开

因为群聊会引入更多变量：

是否被 @
群权限是否正确
机器人是否进群
群策略是否允许
是否进入白名单

如果你连私聊都还没验证通过，就先开群聊，问题会指数级复杂。

正确顺序应该是：

私聊跑通
配对成功
稳定回复
再考虑群聊策略

十五、飞书后台还需要补哪些配置

仅仅写完 OpenClaw 侧配置还不够，飞书后台还要继续完成这些设置。

1. 添加机器人能力

路径：

应用能力 → 添加应用能力 → 机器人

2. 开启事件订阅

路径：

开发配置 → 事件与回调

选择：

使用长连接接收事件

3. 添加消息接收事件

至少添加：

im.message.receive_v1

4. 开通消息相关权限

至少保证消息接收相关权限已经启用。

5. 创建版本并发布

这一步必须完成，否则测试人员通常无法真正使用。

为什么这些步骤缺一不可

因为飞书机器人是否“存在”和是否“能收消息、能回消息”是两件不同的事。

很多人会出现这种情况：

后台看起来都配了
应用也建了
机器人似乎也有了
但就是不回消息

本质上常常是事件订阅、权限、发布状态没有完整闭环。

十六、第一次私聊出现“配对码”，不是报错，是正常流程

如果你配置的是：

dmPolicy = pairing

那么第一次给机器人发消息时，通常会看到类似：

OpenClaw: access not configured.
Your Feishu user id: ...
Pairing code: ...
Ask the bot owner to approve with:
openclaw pairing approve feishu ...

这不是失败，而是首次授权机制在工作。

回到 WSL 中执行：

openclaw pairing approve feishu 你的配对码

批准成功后，建议再重启一次 Gateway：

openclaw gateway restart

然后回到飞书私聊窗口，再发一句：

你好

如果机器人能回复，就说明飞书接入已经成功。

为什么这里要设计“配对”这一步

因为默认私聊授权如果完全放开，风险会更大。
pairing 的意义，是让机器人主人明确批准某个飞书用户与当前机器人建立映射关系。

这比“任何人都能直接私聊调用”更安全，也更适合测试和内部使用。

十七、为什么会看到 `groupPolicy` 相关警告

如果你配置了：

groupPolicy = allowlist

但没有继续设置允许的群，OpenClaw 往往会提示类似：

all group messages will be silently dropped

这句话的意思不是“机器人坏了”，而是：

私聊通常不受影响
群消息会被静默丢弃

为什么这反而是合理默认值

因为它更安全。

在你还没明确哪些群该开放、哪些群不该开放之前，默认拒绝群消息，比默认允许更稳。
尤其是在企业环境里，这种保守策略通常更合适。

为什么建议先别急着处理群聊

因为只要私聊已经跑通，你就已经证明了三件事：

飞书插件工作正常
飞书长连接基本正常
OpenClaw 能收到并处理消息

这时群聊只是策略问题，不再是“系统是否能工作”的问题。

十八、常见问题排查

这里不讲大而空的“可能原因很多”，只给你最实用的排查顺序。

1. Gateway 启动失败

先执行：

openclaw doctor --repair
openclaw gateway restart
openclaw gateway status

重点看是否出现：

Runtime: running
RPC probe: ok

如果没有，优先处理 Gateway 本身，不要先去改模型或飞书。

2. Dashboard 打不开

先检查：

openclaw gateway status

如果 Gateway 没跑起来，Dashboard 打不开是结果，不是原因。

如果 Gateway 正常，但提示 token 缺失，就按前文方法补 token 访问。

3. 模型已经配置，但就是没回复

按这个顺序查：

openclaw config validate
openclaw gateway restart
openclaw gateway status

然后回到 Dashboard 或 TUI 做最简单测试。

不要一开始就怀疑 Prompt、温度、上下文参数。
先确认链路通不通。

4. 飞书机器人没有回复

最有效的命令通常是：

openclaw logs --follow

这能帮你判断：

长连接是否建立
飞书事件是否进来了
是否卡在权限
是否卡在 pairing
是否到达模型调用阶段

5. 安装时 npm 一直很慢

先看：

npm config get registry
curl -I https://registry.npmjs.org
curl -I https://registry.npmmirror.com

必要时再切源，不要先入为主。

6. 改完配置文件却不生效

优先执行：

openclaw config validate
openclaw gateway restart

很多时候不是“配置没写进去”，而是服务没重载到新配置。

十九、常用命令速查

服务管理

openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status

配置管理

openclaw config validate
openclaw config set <key> <value>

插件管理

openclaw plugins list
openclaw plugins install <插件名或路径>
openclaw plugins doctor

渠道管理

openclaw channels list
openclaw channels status
openclaw channels add

诊断与排查

openclaw doctor
openclaw doctor --repair
openclaw logs --follow

交互方式

openclaw dashboard
openclaw tui

飞书配对

openclaw pairing list feishu
openclaw pairing approve feishu <配对码>

二十、推荐你照着执行的顺序

如果你准备实际动手，建议严格按下面顺序来：

检查 Windows 与 WSL2 环境
进入 WSL，确认在 ~ 目录操作
升级 Node 到 22+
修复 DNS 或网络问题
安装 OpenClaw
跑通 Gateway
打开 Dashboard
配置并打通模型
安装飞书插件
配置飞书后台
完成 pairing
验证飞书私聊
最后再考虑群聊

这个顺序的价值，不在于“看起来规范”，而在于：

每一步都有明确成功标准
每一步都能隔离错误范围
任何一步失败，都知道该往哪里查

最后总结

OpenClaw 在 Windows 上最稳的姿势，不是“尽量少步骤”，而是“尽量少混乱”。

如果把整件事拆开看，本质上只有四层：

系统环境
OpenClaw 本体
模型接入
飞书渠道

你只要按这个顺序一层层打通，整个部署过程其实并不复杂。
真正让人崩溃的，往往不是某条命令本身，而是把多个问题叠在一起，最后连自己都不知道在修哪一层。

所以这篇文章最想帮你解决的，不只是“怎么装”，而是：

出问题时，你知道先看哪里，为什么看这里，以及为什么现在不该去动别的地方。

如果你照着本文的路线走，先跑通 WSL2 里的 OpenClaw，再接模型，最后接飞书，成功率通常会高很多，排错成本也会低很多。

彩蛋：获取限免大模型无限token：atomgit.com/