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

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",
            "description": "DeepSeek-R1 深度思考模型",
            "maxTokens": 4096,
            "temperature": 0.6,
            "topP": 0.95
          }
        ]
      }
    }
  }
}

关键配置详解：

• 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 准备飞书应用凭证

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

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

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。

常见问题与解决方案

常用命令参考

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

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 助手。