OpenClaw 本地部署接入飞书机器人安装指南

OpenClaw 本地部署接入飞书机器人安装指南 | 极客日志

在 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 核心安装 -> 初始化配置。

第一阶段：搭建基础环境 (Node.js 和 Git)

OpenClaw 基于 Node.js 运行，并且在安装过程中需要用到 Git 来拉取某些依赖。我们必须先确保这两个工具正确安装。

步骤 1：以管理员身份打开 PowerShell

右键点击开始菜单或任务栏的 Windows 图标，选择 'Windows PowerShell (管理员)' 或 '终端 (管理员)'。这是后续所有命令执行的基础，可以避免许多权限问题。

步骤 2：安装 Node.js (版本需 ≥ 22)

方法 A (推荐 - 手动安装)：

访问 Node.js 官网，下载最新的 LTS (长期支持版) 安装包 (例如 22.x 或更高)。
运行安装程序。在安装选项中，务必勾选 'Automatically install the necessary tools' 和 'Add to PATH'。前者会安装编译本地模块所需的工具，后者能确保您在命令行中直接使用 node 和 npm 命令。
完成安装后，重启 PowerShell 窗口，然后输入以下命令验证：

node -v
npm -v

如果正确显示版本号 (如 v24.14.0 和 10.x.x)，则说明安装成功。

方法 B (通过 OpenClaw 脚本自动安装 - 有风险)：

运行一键安装脚本 iwr -useb https://openclaw.ai/install.ps1 | iex 时，如果脚本检测到系统没有 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 核心程序

基础环境就绪后，我们就可以开始安装 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 相关的通用错误，可能的原因包括：

网络问题：无法连接到 GitHub 或其他托管 Git 仓库的服务器。
Git 配置问题：Git 虽然安装了，但在执行克隆操作时失败。

解决方案：

首先，确认 Git 本身能正常工作。在 PowerShell 中运行以下命令，尝试克隆一个公共仓库：

git clone https://github.com/nodejs/node.git --depth 1

如果这个命令失败，请检查您的网络连接、VPN/代理设置。

其次，获取详细错误信息。使用 verbose 模式重新运行安装命令：

npm install -g openclaw@latest --verbose

在输出的最后部分，找到 code 128 之前的几行，它会明确指出是哪个仓库地址 (fatal: unable to access 'https://...') 访问失败了。根据这个具体地址判断是网络问题还是仓库不存在。

尝试更换 npm 镜像：虽然镜像主要影响 npm 包的下载，但有时也能改善 GitHub 资源的访问。您可以选择更换为国内镜像，如淘宝镜像：

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 官方文档未详细描述此界面，但根据其设计理念和同类工具的习惯，该界面通常包含以下功能模块：

仪表盘（Dashboard）：展示系统概览，如运行状态、当前使用的 AI 模型、已连接的通讯平台（飞书、微信等）、最近的消息日志、系统资源占用等。
模型管理（Model Management）：您可以在此查看已配置的 AI 模型（如 DeepSeek、OpenAI 等），测试模型连接，修改模型参数（temperature、maxTokens 等），甚至通过界面添加新的模型提供商（相当于图形化的 JSON 配置编辑器）。
技能管理（Skills Management）：列出所有已安装的 Skills（功能插件），显示其版本、状态（启用/禁用），并提供安装、更新、卸载新 Skills 的操作入口。
通讯平台配置（Communication Platform Config）：以表单形式展示飞书、微信等平台的接入参数（App ID、App Secret、回调 URL 等），并支持在线修改和保存。
日志查看器（Log Viewer）：实时显示 OpenClaw 的运行日志，支持过滤和搜索，方便排查问题。
系统设置（System Settings）：可能包含 OpenClaw 自身的配置，如 Web UI 端口修改、开机自启设置、数据存储路径等。

3. 注意事项

本地访问限制：默认情况下，Web 界面只监听 127.0.0.1，即只能从本机访问。如果您需要从局域网其他设备访问，可以修改配置文件中的 webUI.host 为 0.0.0.0（但请注意安全，建议设置访问密码或使用防火墙限制）。
安全性：该界面通常无内置认证，因此不建议在公网暴露。如果确实需要远程管理，请使用 VPN 或 SSH 隧道。
与命令行工具的关系：Web 界面和命令行工具（如 openclaw skills install）操作的是同一份配置和数据，两者完全同步，您可以根据习惯选择使用。

第三阶段：初始化配置并接入飞书

OpenClaw 成功安装后，我们需要运行配置向导来完成初始设置，包括接入飞书机器人。

步骤 6：启动配置向导

在 PowerShell 中直接输入以下命令：

openclaw onboard

注意：如果提示 找不到 openclaw 命令，请再次 关闭并重新打开一个新的 PowerShell 窗口，让系统刷新 PATH 环境变量。如果仍找不到，可能需要手动将 npm 全局安装目录 (通常是 %AppData%\npm) 添加到系统 PATH 中。

步骤 7：配置向导详解

1. 同意风险须知（Risk Acknowledgment）

当向导启动后，您会首先看到一段关于使用开源软件潜在风险的提示。操作：您需要输入 Yes（通常要求完整拼写）以继续。

2. 选择配置模式（Configuration Mode）

向导会询问您希望以哪种模式进行配置：

QuickStart（快速开始）：以问答形式引导您完成最核心的配置（AI 模型 + 通讯软件），其他选项使用默认值。这是初次使用者的首选。
Advanced（高级模式）：直接打开一个配置文件（YAML 或 JSON）供您手动编辑，适合熟悉所有选项的高级用户。

3. 配置 AI 模型（AI Model Configuration）

这是 OpenClaw 的'大脑'配置环节。向导会要求您选择一个 AI 服务提供商。由于 DeepSeek 的 API 完全兼容 OpenAI 格式，即使列表中没有 DeepSeek，您也可以选择 Custom / OpenAI Compatible 或直接选择 OpenAI 并在后续填入自定义地址。

3.1 通过 JSON 文件导入 DeepSeek 模型

以下是一个完整的 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,
            "topP": 0.9
          },
          {
            "name": "deepseek-reasoner",

关键配置详解：

type: openai-compatible。这是接入 DeepSeek 的核心。由于 OpenClaw 内部通过 OpenAI SDK 调用模型，只需将 baseURL 指向 DeepSeek 的 API 地址，即可实现无缝对接。
baseURL: 必须设置为 https://api.deepseek.com（不加 /v1）。OpenClaw 会自动在请求时拼接 /v1/chat/completions，符合 DeepSeek 的接口规范。
apiKey 的安全管理：示例中使用 ${DEEPSEEK_API_KEY} 引用环境变量，避免明文写入配置文件。设置方式：

$env:DEEPSEEK_API_KEY = "sk-您的实际密钥"

3.2 填写 DeepSeek 参数

当您选择自定义模式后，向导会逐一询问以下内容：

Base URL（基础地址）：输入 https://api.deepseek.com
API Key：输入您在 DeepSeek 开放平台创建的 API Key（以 sk- 开头）。
Model Name（模型名称）：根据您的需求输入，例如 deepseek-chat 或 deepseek-reasoner。

4. 配置通讯软件（接入飞书）

完成 AI 模型配置后，向导会进入通讯软件配置环节。OpenClaw 支持多种平台（飞书、微信、QQ、Slack 等），我们重点讲解飞书接入。

4.1 准备飞书应用凭证

在向导开始询问具体参数前，您需要 提前在飞书开放平台创建一个应用，并获取关键凭证。

访问飞书开放平台：https://open.feishu.cn/app
创建企业自建应用：点击'创建应用'，输入应用名称，选择'企业自建'。
获取 App ID 和 App Secret：在'凭证与基础信息'页面，复制 App ID 和 App Secret。App Secret 只显示一次，请立即复制保存。
配置事件订阅（必须）：
- 在'事件订阅'页面，启用事件订阅。
- 请求地址 URL：这是 OpenClaw 接收飞书事件的公网地址。如果您将 OpenClaw 部署在本地且无公网 IP，需要借助内网穿透工具（如 ngrok、frp）生成一个公网 URL。
- 在 '事件回调' 中，添加以下事件：
  - message.receive_v1（接收消息）
  - bot.add（机器人被添加）
配置权限（重要）：在'权限管理'页面，搜索并添加以下权限：
- im:message
- im:message:send_as_bot
- im:chat
- contact:user.base
发布版本：在'版本管理与发布'页面，创建一个版本并提交审核。

4.2 在向导中填写飞书参数

回到 OpenClaw 配置向导，它会依次询问：

App ID：粘贴您保存的 App ID。
App Secret：粘贴 App Secret。
Verification Token（可选）：飞书事件订阅中有一个'验证令牌'，如果您在飞书后台设置了，需要填入；否则留空。
事件回调 URL：向导可能会要求您确认或自动生成一个路径（例如 /feishu/webhook），您需要在飞书后台的'事件订阅'请求地址中填写完整的 URL：https://您的公网地址/feishu/webhook。

4.3 测试飞书连接

填写完毕后，向导会尝试向飞书服务器发送一个测试请求。如果成功，会显示'飞书配置验证通过'。常见失败原因：

App ID/Secret 错误
权限未配置或未发布
事件回调 URL 无法从外网访问（本地测试需用内网穿透）

5. 配置 Skills（技能）

Skills 是 OpenClaw 的功能插件。在 QuickStart 模式下，向导通常只会询问一个关键问题：'是否要立即安装一些常用 Skills？'。操作：建议选择 No 或 Skip。后续您可以通过 openclaw skills install <skill-name> 命令按需添加。

6. 完成配置与启动

所有问答结束后，向导会生成配置文件并保存到默认位置（通常是 ~/.openclaw/config.yaml 或 ~/.openclaw/config.json）。

验证配置：

在启动前，建议运行诊断命令检查配置是否正确：

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 窗口

常用命令参考

以下是整个配置过程中常用的关键命令汇总：

1. 查看状态和诊断

# 查看整体状态
openclaw status --deep
# 查看飞书通道状态
openclaw channels status
# 查看实时日志
openclaw logs --follow

2. 配置飞书通道

# 设置飞书 App ID
openclaw config set channels.feishu.appId "your_app_id"
# 设置飞书 App Secret
openclaw config set channels.feishu.appSecret "your_app_secret"
# 设置连接模式为 WebSocket
openclaw config set channels.feishu.connectionMode websocket
# 设置群聊策略为开放（测试用）
openclaw config set channels.feishu.groupPolicy open

3. 网关管理

# 停止网关
openclaw gateway stop
# 启动网关
openclaw gateway start
# 强制结束所有 Node.js 进程（清理残留）
taskkill /F /IM node.exe

4. 智能体配置

# 创建 agent.json 文件（使用 UTF-8 编码）
notepad %USERPROFILE%\.openclaw\agents\main\agent.json

agent.json 正确内容：

{
  "id": "main",
  "name": "main",
  "model": "deepseek/deepseek-chat",
  "instructions": "你是一个有帮助的 AI 助手，可以回答用户的各种问题。",
  "tools": []
}

5. 配对授权管理

# 批准飞书用户访问（使用正确的配对码）
openclaw pairing approve feishu J6K8X9J4
# 查看已批准的配对列表
openclaw pairing list

结语

至此，您已经完成了 OpenClaw 从安装到配置的全过程，并成功接入了飞书和 DeepSeek 模型。接下来，您可以尝试在飞书中 @机器人发送消息，观察它是否能调用 DeepSeek 智能回复。如果一切顺利，恭喜您！您已经拥有了一个强大的自托管 AI 助手。

OpenClaw 本地部署接入飞书机器人安装指南

第一章：准备工作与环境检查

1. 系统要求

2. 核心命令解释

第二章：分步安装指南 (实战优化版)

第一阶段：搭建基础环境 (Node.js 和 Git)

步骤 1：以管理员身份打开 PowerShell

步骤 2：安装 Node.js (版本需 ≥ 22)

步骤 3：安装 Git

第二阶段：安装 OpenClaw 核心程序

步骤 4：执行安装命令

步骤 5：解决可能遇到的错误 (实战经验总结)

OpenClaw 本地 Web 管理界面

1. 如何启动 Web 界面

2. Web 界面的主要功能

3. 注意事项

第三阶段：初始化配置并接入飞书

步骤 6：启动配置向导

步骤 7：配置向导详解

1. 同意风险须知（Risk Acknowledgment）

2. 选择配置模式（Configuration Mode）

3. 配置 AI 模型（AI Model Configuration）

3.1 通过 JSON 文件导入 DeepSeek 模型

3.2 填写 DeepSeek 参数

4. 配置通讯软件（接入飞书）

4.1 准备飞书应用凭证

4.2 在向导中填写飞书参数

4.3 测试飞书连接

5. 配置 Skills（技能）

6. 完成配置与启动

常见问题与解决方案

常用命令参考

1. 查看状态和诊断

2. 配置飞书通道

3. 网关管理

4. 智能体配置

5. 配对授权管理

结语

更多推荐文章

相关免费在线工具

OpenClaw 本地部署接入飞书机器人安装指南

第一章：准备工作与环境检查

1. 系统要求

2. 核心命令解释

第二章：分步安装指南 (实战优化版)

第一阶段：搭建基础环境 (Node.js 和 Git)

步骤 1：以管理员身份打开 PowerShell

步骤 2：安装 Node.js (版本需 ≥ 22)

步骤 3：安装 Git

第二阶段：安装 OpenClaw 核心程序

步骤 4：执行安装命令

步骤 5：解决可能遇到的错误 (实战经验总结)

OpenClaw 本地 Web 管理界面

1. 如何启动 Web 界面

2. Web 界面的主要功能

3. 注意事项

第三阶段：初始化配置并接入飞书

步骤 6：启动配置向导

步骤 7：配置向导详解

1. 同意风险须知（Risk Acknowledgment）

2. 选择配置模式（Configuration Mode）

3. 配置 AI 模型（AI Model Configuration）

3.1 通过 JSON 文件导入 DeepSeek 模型

3.2 填写 DeepSeek 参数

4. 配置通讯软件（接入飞书）

4.1 准备飞书应用凭证

4.2 在向导中填写飞书参数

4.3 测试飞书连接

5. 配置 Skills（技能）

6. 完成配置与启动

常见问题与解决方案

常用命令参考

1. 查看状态和诊断

2. 配置飞书通道

3. 网关管理

4. 智能体配置

5. 配对授权管理

结语

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具