OpenClaw 本地部署与飞书机器人接入指南
在 Windows 系统上部署 OpenClaw 并接入飞书机器人的完整流程。内容涵盖环境准备(Node.js、Git)、核心程序安装(npm 或脚本)、DeepSeek 模型配置(JSON 或向导)、飞书应用凭证获取及回调设置。同时提供了本地 Web 管理界面使用说明、常见错误排查及关键命令参考,帮助用户快速搭建自托管 AI 助手。

在 Windows 系统上部署 OpenClaw 并接入飞书机器人的完整流程。内容涵盖环境准备(Node.js、Git)、核心程序安装(npm 或脚本)、DeepSeek 模型配置(JSON 或向导)、飞书应用凭证获取及回调设置。同时提供了本地 Web 管理界面使用说明、常见错误排查及关键命令参考,帮助用户快速搭建自托管 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 的缩写,使用基础解析模式下载。|: 管道符,将左边命令的输出传递给右边命令。iex: Invoke-Expression 的别名,将接收到的字符串当作 PowerShell 代码来执行。总结: 这行命令的作用是从网络下载一个脚本并立即在您的电脑上运行它。但请务必确保您信任脚本的来源。
包管理器安装命令: npm install -g openclaw@latest
npm: Node Package Manager,Node.js 的包管理器。-g 或 --global: 全局安装。这意味着安装的工具会被添加到系统 PATH 环境变量中。openclaw@latest: 要安装的包名,@latest 表示获取并安装 npm 仓库中的最新稳定版本。总结: 这是手动安装 OpenClaw 核心程序的标准命令,也是解决一键安装脚本可能出现问题时的备用方案。
我们将分为三个阶段进行:基础环境搭建 -> OpenClaw 核心安装 -> 初始化配置。
OpenClaw 基于 Node.js 运行,并且在安装过程中需要用到 Git 来拉取某些依赖。
步骤 1:以管理员身份打开 PowerShell 右键点击开始菜单或任务栏的 Windows 图标,选择 'Windows PowerShell (管理员)' 或 '终端 (管理员)'。
步骤 2:安装 Node.js (版本需 ≥ 22)
方法 A (推荐 - 手动安装):
node -v
npm -v
如果正确显示版本号,则说明安装成功。
方法 B (通过 OpenClaw 脚本自动安装 - 有风险): 运行一键安装脚本时,如果脚本检测到系统没有 Node.js,理论上会尝试自动安装。但根据实战经验,这个过程可能因网络或权限问题而失败。因此,手动安装 Node.js 是最稳妥的方式。
步骤 3:安装 Git
为什么需要 Git? OpenClaw 的一些依赖项可能直接从 GitHub 仓库安装。
操作步骤: 访问 Git 官网下载安装程序:https://git-scm.com/download/win 运行安装程序。在关键的 '选择组件' 步骤中,务必勾选 'Git from the command line and also from 3rd-party software'。 其他选项保持默认,一路 "Next" 完成安装。 安装完成后,再次重启 PowerShell 窗口,然后验证:
git --version
步骤 4:执行安装命令
方法 A (推荐 - 手动 npm 安装):
npm install -g openclaw@latest
方法 B (一键脚本安装):
iwr -useb https://openclaw.ai/install.ps1 | iex
注意:如果使用此方法,请在运行后仔细观察窗口输出。如果它停留在 [OK] Windows detected 后就无响应,说明它可能未能自动完成后续的 npm 安装步骤。此时,请回到方法 A,使用 npm 命令手动安装。
步骤 5:解决可能遇到的错误
错误 1: 无法加载文件 ...,因为在此系统上禁止运行脚本。 原因: PowerShell 的执行策略 (Execution Policy) 默认设置为 Restricted。 解决方案:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
输入 Y 确认。之后重新尝试安装命令。
错误 2: npm ERR! code ENOTENV 或 npm ERR! enoent ... git 原因: 系统找不到 git 命令。 解决方案: 请回到本章步骤 3,正确安装 Git 并确保其添加到 PATH 中。安装成功后,务必关闭当前 PowerShell 并打开一个新窗口。
错误 3: npm ERR! code 128 原因: 这是一个与 Git 相关的通用错误,可能的原因包括网络问题或 Git 配置问题。 解决方案:
git clone https://github.com/nodejs/node.git --depth 1npm config set registry https://registry.npmmirror.com步骤 6:启动配置向导 在 PowerShell 中直接输入以下命令:
openclaw onboard
当向导启动后,您会首先看到一段关于使用开源软件潜在风险的提示。 操作: 您需要输入 Yes(通常要求完整拼写)以继续。
向导会询问您希望以哪种模式进行配置:
这是 OpenClaw 的'大脑'配置环节。由于 DeepSeek 的 API 完全兼容 OpenAI 格式,可以通过 openai-compatible 类型轻松接入。
以下是一个完整的 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
}
]
}
}
}
}
关键配置详解:
type: "openai-compatible": 接入 DeepSeek 的核心。baseURL: 必须设置为 https://api.deepseek.com(不加 /v1)。apiKey: 建议使用环境变量引用,避免明文写入配置文件。如何验证配置生效:
openclaw doctor
您将看到类似以下输出,确认 DeepSeek 已成功加载。
当您选择自定义模式后,向导会逐一询问以下内容:
在向导开始询问具体参数前,您需要提前在飞书开放平台创建一个应用:
回到 OpenClaw 配置向导,它会依次询问:
4.3 测试飞书连接 填写完毕后,向导会尝试向飞书服务器发送一个测试请求。如果成功,会显示'飞书配置验证通过'。
Skills 是 OpenClaw 的功能插件。在 QuickStart 模式下,向导通常只会询问是否要立即安装一些常用 Skills。建议选择 No 或 Skip,后续可通过 openclaw skills install <skill-name> 按需添加。
所有问答结束后,向导会生成配置文件。建议运行诊断命令检查配置是否正确:
openclaw doctor
如果一切正常,您就可以启动机器人了:
openclaw start
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 配置向导卡在某一步无响应 | 网络问题,无法访问 API 或飞书 | 检查代理设置,或暂时关闭防火墙测试 |
| 飞书配置验证失败:Invalid app secret | App Secret 错误 | 重新复制 App Secret(注意不要有空格) |
| 飞书机器人不回复 | 事件回调 URL 不可访问 | 使用 curl 或浏览器测试您的 URL 是否能返回 200 |
| 模型测试失败:Connection refused | Base URL 或端口错误 | 确认 DeepSeek API 地址正确 |
| openclaw 命令找不到 | PATH 未更新 | 关闭并重新打开 PowerShell 窗口 |
安装与更新
# 一键安装脚本
iwr -useb https://openclaw.ai/install.ps1 | iex
# 通过 npm 全局安装/更新
npm install -g openclaw@latest
配置向导与初始化
# 启动交互式配置向导
openclaw onboard
# 重新运行配置
openclaw configure
网关控制
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
配置管理
# 查看配置项
openclaw config list
# 设置默认主模型
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"
诊断与日志
# 运行健康检查
openclaw doctor
# 查看实时日志
openclaw logs --follow
飞书通道配置
# 设置飞书 App ID
openclaw config set channels.feishu.appId "your_app_id"
# 设置飞书 App Secret
openclaw config set channels.feishu.appSecret "your_app_secret"
# 批准飞书用户访问
openclaw pairing approve feishu your_pairing_code
至此,您已经完成了 OpenClaw 从安装到配置的全过程,并成功接入了飞书和 DeepSeek 模型。接下来,您可以尝试在飞书中@机器人发送消息,观察它是否能调用 DeepSeek 智能回复。祝您探索愉快!

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online