在 Windows 系统上部署 OpenClaw 并接入飞书机器人的完整流程。涵盖环境准备（Node.js、Git）、核心安装（npm 或脚本）、Web 管理界面访问、以及通过交互式向导配置 DeepSeek 模型和飞书凭证的步骤。包含常见错误排查及关键命令参考，帮助用户快速搭建自托管 AI 助手。
在 Windows 系统上从头开始部署 OpenClaw，并将其配置为可以接入飞书的智能机器人。我们将以实战中遇到的问题为鉴，确保安装过程顺畅无误。
在正式开始安装前，请确保您的电脑满足以下基础条件，并理解我们将要使用的关键命令。
1. 系统要求
操作系统: Windows 10 或 Windows 11 (需使用管理员权限运行 PowerShell)。
网络环境: 能够正常访问 GitHub 和 npm 仓库。如果您在网络受限的环境中，可能需要提前准备代理或镜像配置。
2. 核心命令解释 在整个安装过程中，有两个核心命令您需要理解：
一键安装命令：iwr -useb https://openclaw.ai/install.ps1 | iex
iwr: Invoke-WebRequest 的别名，用于从指定网址下载文件。-useb: -UseBasicParsing 的缩写，使用基础解析模式下载，通常用于避免依赖 IE 引擎，更稳定。https://...: OpenClaw 官方安装脚本的下载地址。|: 管道符，将左边命令的输出（下载的脚本内容）传递给右边命令。iex: Invoke-Expression 的别名，将接收到的字符串当作 PowerShell 代码来执行。总结：这行命令的作用是从网络下载一个脚本并立即在您的电脑上运行它。这是一种常见的便捷安装方式，但请务必确保您信任脚本的来源。
包管理器安装命令：npm install -g openclaw@latest
npm: Node Package Manager，Node.js 的包管理器。install: 安装一个包。-g 或 --global: 全局安装。这意味着安装的工具 (openclaw) 会被添加到系统 PATH 环境变量中，之后您可以在任何目录下的命令行中直接使用 openclaw 命令。openclaw@latest: 要安装的包名 (openclaw)，@latest 表示获取并安装 npm 仓库中的最新稳定版本。总结：这是手动安装 OpenClaw 核心程序的标准命令，也是解决一键安装脚本可能出现问题时的备用方案。
我们将分为三个阶段进行：基础环境搭建 -> OpenClaw 核心安装 -> 初始化配置。
OpenClaw 基于 Node.js 运行，并且在安装过程中需要用到 Git 来拉取某些依赖。我们必须先确保这两个工具正确安装。
步骤 1：以管理员身份打开 PowerShell 右键点击开始菜单或任务栏的 Windows 图标，选择 'Windows PowerShell (管理员)' 或 '终端 (管理员)'。这是后续所有命令执行的基础，可以避免许多权限问题。
步骤 2：安装 Node.js (版本需 ≥ 22)
方法 A (推荐 - 手动安装)：
node -v
npm -v
如果正确显示版本号 (如 v24.14.0 和 10.x.x)，则说明安装成功。
方法 B (通过 OpenClaw 脚本自动安装 - 有风险)： 运行一键安装脚本时，如果脚本检测到系统没有 Node.js，理论上会尝试自动安装。但根据实战经验，这个过程可能因网络或权限问题而失败，导致窗口一闪而过且不报错。因此，手动安装 Node.js 是最稳妥的方式。
步骤 3：安装 Git
为什么需要 Git？ OpenClaw 的一些依赖项可能直接从 GitHub 仓库安装，这就需要系统能够调用 git 命令。
操作步骤： 访问 Git 官网下载安装程序：https://git-scm.com/download/win 运行安装程序。在关键的 '选择组件' 步骤中，务必勾选 'Git from the command line and also from 3rd-party software'。这个选项会将 Git 添加到系统的 PATH 环境变量中，让 PowerShell 也能找到 git 命令。 其他选项保持默认，一路 "Next" 完成安装。
安装完成后，再次重启 PowerShell 窗口（或至少关闭当前窗口再打开一个新的），然后验证：
git --version
如果显示类似 git version 2.53.0.windows.1 的信息，说明 Git 已准备就绪。
基础环境就绪后，我们就可以开始安装 OpenClaw 了。
步骤 4：执行安装命令
方法 A (推荐 - 手动 npm 安装)：这种方法更透明，便于观察错误。
npm install -g openclaw@latest
命令解释：如第一章所述，此命令会从 npm 全球仓库下载 OpenClaw 的最新版本并全局安装到您的系统。
方法 B (一键脚本安装)：如果您仍想尝试官方脚本。
iwr -useb https://openclaw.ai/install.ps1 | iex
注意：如果使用此方法，请在运行后仔细观察窗口输出。如果它停留在 [OK] Windows detected 后就无响应或窗口关闭，说明它可能未能自动完成后续的 npm 安装步骤。此时，请回到方法 A，使用 npm 命令手动安装。
步骤 5：解决可能遇到的错误 (实战经验总结) 在运行 npm install -g openclaw@latest 时，您可能会遇到以下典型错误，请按图索骥解决：
**错误 1：**无法加载文件 ...，因为在此系统上禁止运行脚本。
原因：PowerShell 的执行策略 (Execution Policy) 默认设置为 Restricted，禁止运行任何脚本。npm 命令本身可能调用了一些脚本文件。
解决方案： 确保您是以 管理员身份 运行的 PowerShell。 输入以下命令，将当前用户的执行策略更改为 RemoteSigned (允许运行本地脚本，远程脚本需签名)：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
输入 Y 确认。之后重新尝试安装命令。
**错误 2：**npm ERR! code ENOTENV 或 npm ERR! enoent ... git
原因：系统找不到 git 命令。这通常是因为 Git 未安装，或者安装时没有勾选'添加到 PATH'。
解决方案：请回到本章步骤 3，正确安装 Git 并确保其添加到 PATH 中。安装成功后，务必关闭当前 PowerShell 并打开一个新窗口，使 PATH 更新生效。
**错误 3：**npm ERR! code 128
原因：这是一个与 Git 相关的通用错误，可能的原因包括：
解决方案：
git clone https://github.com/nodejs/node.git --depth 1
如果这个命令失败，请检查您的网络连接、VPN/代理设置。
npm install -g openclaw@latest --verbose
在输出的最后部分，找到 code 128 之前的几行，它会明确指出是哪个仓库地址 (fatal: unable to access 'https://...') 访问失败了。根据这个具体地址判断是网络问题还是仓库不存在。
npm config set registry https://registry.npmmirror.com
更换后再次尝试安装。
OpenClaw 安装成功后的本地 Web 管理界面
在 OpenClaw 成功安装并启动后，除了通过命令行交互和通讯软件（如飞书）使用外，它还提供了一个本地 Web 管理界面，方便您更直观地查看系统状态、管理配置和技能。根据您的描述，这个界面的默认访问地址是 http://127.0.0.1:18789/。
1. 如何启动 Web 界面 当您运行 openclaw start 命令启动 OpenClaw 服务时，控制台通常会输出类似以下的信息：
[INFO] Web UI available at http://127.0.0.1:18789
[INFO] Feishu bot webhook: https://your-domain.com/feishu/webhook
...
如果您看到这样的提示，说明 Web 界面已成功启动。只需在浏览器中打开 http://127.0.0.1:18789 即可访问。
注意：如果启动后没有看到该提示，可能是您的配置中禁用了 Web UI，或者需要检查 OpenClaw 的配置文件（~/.openclaw/config.json）中是否有相关设置。部分版本可能默认不启用，您可以通过配置文件中的 webUI.enabled 选项手动开启。
2. Web 界面的主要功能 虽然 OpenClaw 官方文档未详细描述此界面，但根据其设计理念和同类工具的习惯，该界面通常包含以下功能模块：
3. 注意事项
OpenClaw 成功安装后，我们需要运行配置向导来完成初始设置，包括接入飞书机器人。
步骤 6：启动配置向导 在 PowerShell 中直接输入以下命令：
openclaw onboard
注意：如果提示找不到 openclaw 命令，请再次关闭并重新打开一个新的 PowerShell 窗口，让系统刷新 PATH 环境变量。如果仍找不到，可能需要手动将 npm 全局安装目录 (通常是 %AppData%\npm) 添加到系统 PATH 中。
在成功安装 OpenClaw 核心程序后，您将进入最重要的配置环节。openclaw onboard 命令启动的是一个基于文本的交互式向导（TUI），它将引导您完成所有必要设置。
当向导启动后，您会首先看到一段关于使用开源软件潜在风险的提示。 操作：您需要输入 Yes（通常要求完整拼写）以继续。
向导会询问您希望以哪种模式进行配置：
这是 OpenClaw 的'大脑'配置环节。向导会要求您选择一个 AI 服务提供商。由于 DeepSeek 的 API 完全兼容 OpenAI 格式，即使列表中没有 DeepSeek，您也可以选择 Custom (OpenAI Compatible) 或直接选择 OpenAI 并在后续填入自定义地址。
以下是一个完整的 JSON 配置文件示例（~/.openclaw/config.json），展示了如何将 DeepSeek 配置为默认模型：
{
"models": {
"default": "deepseek-chat",
"providers": {
"deepseek": {
"type": "openai-compatible",
"baseURL": "https://api.deepseek.com",
"apiKey": "${DEEPSEEK_API_KEY}",
"models": [
{
"name": "deepseek-chat",
"description": "DeepSeek-V3 通用对话模型",
"maxTokens": 8192,
"temperature": 0.7
},
{
"name": "deepseek-reasoner",
"description": "DeepSeek-R1 深度思考模型",
"maxTokens": 4096,
"temperature": 0.6
}
]
}
}
}
}
关键配置详解：
如何验证配置生效： 保存配置文件后，执行：
openclaw doctor
您将看到类似以下输出，确认 DeepSeek 已成功加载。
当您选择自定义模式后，向导会逐一询问以下内容：
完成 AI 模型配置后，向导会进入通讯软件配置环节。我们重点讲解飞书接入。
在向导开始询问具体参数前，您需要提前在飞书开放平台创建一个应用，并获取关键凭证。
回到 OpenClaw 配置向导，它会依次询问：
填写完毕后，向导会尝试向飞书服务器发送一个测试请求。如果成功，会显示'飞书配置验证通过'。常见失败原因包括 App ID/Secret 错误、权限未配置或未发布、事件回调 URL 无法从外网访问。
Skills 是 OpenClaw 的功能插件。在 QuickStart 模式下，向导通常只会询问是否要立即安装一些常用 Skills。建议选择 No 或 Skip，后续可通过 openclaw skills install 按需添加。
所有问答结束后，向导会生成配置文件。启动前建议运行诊断命令：
openclaw doctor
如果一切正常，您就可以启动机器人了：
openclaw start
启动成功后，您会在控制台看到日志输出，例如 Listening for Feishu events on port 3000。
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 配置向导卡在某一步无响应 | 网络问题，无法访问 API 或飞书 | 检查代理设置，或暂时关闭防火墙测试 |
| 飞书配置验证失败：Invalid app secret | App Secret 错误 | 重新复制 App Secret（注意不要有空格） |
| 飞书机器人不回复 | 事件回调 URL 不可访问 | 使用 curl 或浏览器测试您的 URL 是否能返回 200 |
| 模型测试失败：Connection refused | Base URL 或端口错误 | 确认 DeepSeek API 地址正确 |
| openclaw 命令找不到 | PATH 未更新 | 关闭并重新打开 PowerShell 窗口 |
至此，您已经完成了 OpenClaw 从安装到配置的全过程，并成功接入了飞书和 DeepSeek 模型。接下来，您可以尝试在飞书中@机器人发送消息，观察它是否能调用 DeepSeek 智能回复。如果在后续使用中遇到 Skills 配置或其他问题，欢迎随时查阅 OpenClaw 官方文档。
以下是整个配置过程中涉及的关键命令整理：
1. 安装与环境
# 设置执行策略
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# 安装 OpenClaw
npm install -g openclaw@latest
# 或一键脚本
iwr -useb https://openclaw.ai/install.ps1 | iex
2. 配置与管理
# 启动配置向导
openclaw onboard
# 健康检查
openclaw doctor
# 启动服务
openclaw start
# 查看日志
openclaw logs --follow
3. 飞书通道配置
# 设置飞书 App ID
openclaw config set channels.feishu.appId "cli_a925d4e310389bcc"
# 设置飞书 App Secret
openclaw config set channels.feishu.appSecret "你的 App Secret"
# 设置连接模式
openclaw config set channels.feishu.connectionMode websocket
4. 网关管理
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
5. 配对授权
# 批准飞书用户访问
openclaw pairing approve feishu J6K8X9J4
6. 智能体配置
# 创建 agent.json 文件
notepad C:\Users\aym\.openclaw\agents\main\agent.json
通过以上步骤，您可以构建一个强大的自托管 AI 助手。祝您使用愉快！
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online