OpenClaw Windows 安装与飞书接入指南

一、适用范围

本文适用于 Windows 环境下的 OpenClaw 本地安装、基础初始化，以及飞书接入排障。

二、安装基础环境

1. 安装 Git

下载地址：https://git-scm.com/download/win

安装完成后可检查：

git --versionwhere git

2. 安装 Node.js

下载地址：https://nodejs.org/download/release/latest/

安装时建议勾选 Add to PATH。

安装完成后可检查：

node -vnpm -vwhere node

3. 安装 Python

建议安装 Miniconda：https://www.anaconda.com/docs/getting-started/miniconda/main

安装完成后可按需检查：

conda --versionpython --version

三、安装 OpenClaw

官网：https://openclaw.ai/

1. 推荐安装方式

Windows 环境建议优先使用 npm 全局安装。

PowerShell / cmd：

npm.cmd i -g openclawopenclaw.cmd onboard

Git Bash：

npm i -g openclawopenclaw onboard

如果 PowerShell 执行策略拦截 npm.ps1，可改为：

& 'C:\Program Files\nodejs\npm.cmd' i -g openclaw

2. 验证安装

PowerShell / cmd：

openclaw.cmd --version

Git Bash：

openclaw --version

四、Windows 常见问题

❝

[!IMPORTANT] Windows 环境下建议优先使用 npm.cmd、openclaw.cmd，并尽量避免过度依赖交互式向导。 如遇安装或启动异常，建议先保留完整报错、版本信息与日志，再进行排查或反馈。

1. PowerShell 拦截 npm

典型报错：

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.

处理方式：直接使用 npm.cmd。

2. npm 安装 warning

如安装时出现：

npm warn deprecated node-domexception@1.0.0

通常属于依赖链 warning，一般不影响 OpenClaw CLI 安装成功。

3. 运行时缺少模块

如运行 openclaw 后出现：

Cannot find module '@buape/carbon'Cannot find module '@larksuiteoapi/node-sdk'Cannot find module '@slack/web-api'Cannot find module 'grammy'

说明当前 npm 发布包可能存在依赖遗漏，更偏向发布包问题，不一定是本地安装方式错误。

4. Windows 交互式向导路径报错

在 Windows 下执行以下命令时：

openclaw onboardopenclaw channels add --channel feishu

可能出现：

ERR_UNSUPPORTED_ESM_URL_SCHEMEOnly URLs with a scheme in: file, data, and node are supportedOn Windows, absolute paths must be valid file:// URLsReceived protocol 'c:'

这更像是 Windows 原生交互式向导的路径处理问题，不应先归因到某个具体模型或 provider。

建议：

• 不要完全依赖交互式向导
• 优先使用非交互命令或手工配置
• 如问题持续，记录版本、报错全文和日志后再反馈上游

五、手工补配置思路

当 onboard 不稳定时，可先手工补关键配置。

1. 手工设置默认模型

例如：

openclaw.cmd config set agents.defaults.model.primary zai/glm-4.6vopenclaw.cmd config get agents.defaults.model.primaryopenclaw.cmd config validate

2. 网关缺少配置

如启动 gateway 时出现：

existing config is missing gateway.mode

可手工补：

openclaw.cmd config set gateway.mode localopenclaw.cmd config set gateway.port 18789openclaw.cmd config set gateway.bind loopback

然后重新执行：

openclaw.cmd gateway

如日志出现：

[gateway] ready

通常表示本地网关已正常启动。

六、飞书接入

❝

[!TIP] 飞书接入建议按“平台配置完成 → 本地补齐配置 → 查看网关日志 → 验证机器人收发消息”的顺序排查。 如果 Windows 原生命令触发异常，不要只依赖交互式向导，优先检查手工配置与运行日志。

1. 飞书后台准备

飞书开放平台：

• 国内飞书：https://open.feishu.cn/app
• 国际 Lark：https://open.larksuite.com/app

需要准备：

• App ID
• App Secret

如果是国际版 Lark，还需要配置：

• domain: "lark"

2. 飞书后台需要开启的内容

至少确认以下配置：

• 创建企业自建应用
• 开启 Bot 能力
• 配置消息相关权限
• 事件订阅选择 WebSocket 长连接模式
• 添加事件（接收消息） im.message.receive_v1
• 发布应用

3. 常见 CLI 命令

PowerShell / cmd：

openclaw.cmd channelsopenclaw.cmd channels login --channel feishu --verboseopenclaw.cmd channels add --channel feishu

已知现象：

• openclaw channels add feishu 会报 too many arguments for 'add'
• 正确写法应为 openclaw channels add --channel feishu
• 即使写法正确，Windows 原生环境下仍可能触发 ESM 路径报错
• openclaw channels login --channel feishu 还可能出现：
• Channel feishu does not support login
• feishu missing register/activate export

因此更建议优先手工写配置，再结合 网关日志排查。

4. 最小配置示例

{"channels": {"feishu": {"enabled": true,"dmPolicy": "pairing","accounts": {"main": {"appId": "cli_xxx","appSecret": "你的AppSecret"        }      }    }  }}

参考的配置

{"scopes": {"tenant": ["aily:file:read","aily:file:write","application:application.app_message_stats.overview:readonly","application:application:self_manage","application:bot.menu:write","contact:user.employee_id:readonly","corehr:file:download","event:ip_list","im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","im:message","im:message.group_at_msg:readonly","im:message.p2p_msg:readonly","im:message:readonly","im:message:send_as_bot","im:resource"    ],"user": ["aily:file:read","aily:file:write","im:chat.access_event.bot_p2p_chat:read"    ]  }}

七、飞书已连通但机器人不回复

❝

[!WARNING] WebSocket 已连通并不代表机器人一定具备完整回复能力。 如果消息已成功进入系统但飞书端没有收到回复，排查重点通常应放在机器人身份探测、发送权限、会话权限和网络环境，而不是消息接收链路。

如果日志中出现：

bot info probe timed out after 30000msbot open_id resolved: unknownrequireMention group messages stay gated until bot identity recovery succeeds

或：

AxiosError: timeout of 10000ms exceededurl: https://open.feishu.cn/open-apis/bot/v3/info

说明：

• WebSocket 已连通，不代表机器人一定能正常回复
• 问题可能出在 bot 身份探测、open_id 拉取、权限配置或网络环境

建议优先检查：

• 飞书后台事件订阅
• Bot 权限和消息权限
• 机器人是否已加入目标会话
• 网关日志
• DNS、代理、网络环境

进一步排查时，还建议补充检查：

• 是否同时启用了内置 feishu 与额外的第三方 Feishu/Lark 插件，导致通道重复注册或工具冲突
• 是否存在流式卡片发送失败，例如 Create card request failed with HTTP 400
• 当前 openclaw.json 中是否残留旧版本字段或旧工具 allowlist，导致配置校验失败或运行时告警

如果日志已经显示消息成功进入并 dispatch 到 agent，但飞书端仍未收到回复，通常说明问题更可能出在回复发送阶段，而不是接收阶段。

八、Pairing 说明

如飞书侧提示：

OpenClaw: access not configured.Pairing code: XXXXXXXXAsk the bot owner to approve with:openclaw pairing approve feishu XXXXXXXX

可在本机执行：

openclaw.cmd pairing approve feishu XXXXXXXX

这一步表示由本机管理员批准该飞书用户的访问权限。

九、建议

在 Windows 上使用 OpenClaw 时，当前更稳妥的实践是：

1. 优先使用 npm.cmd、openclaw.cmd
2. 尽量避免依赖交互式向导
3. 重要配置优先使用 config get、config validate 验证
4. 飞书问题同时结合平台配置、网关日志和网络环境一起排查