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

node -v
npm -v

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

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

运行一键安装脚本时，如果脚本检测到系统没有 Node.js，理论上会尝试自动安装。但根据实战经验，这个过程可能因网络或权限问题而失败，导致窗口一闪而过且不报错。因此，手动安装 Node.js 是最稳妥的方式。

步骤 3：安装 Git

为什么需要 Git？ OpenClaw 的一些依赖项可能直接从 GitHub 仓库安装，这就需要系统能够调用 git 命令。

操作步骤：

1. 访问 Git 官网下载安装程序。
2. 运行安装程序。在关键的**'选择组件'**步骤中，务必勾选 'Git from the command line and also from 3rd-party software'。这个选项会将 Git 添加到系统的 PATH 环境变量中，让 PowerShell 也能找到 git 命令。
3. 其他选项保持默认，一路 "Next" 完成安装。
4. 安装完成后，再次重启 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 命令本身可能调用了一些脚本文件。
• 解决方案：
  1. 确保您是以管理员身份运行的 PowerShell。
  2. 输入以下命令，将当前用户的执行策略更改为 RemoteSigned (允许运行本地脚本，远程脚本需签名)：

  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  

  3. 输入 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 配置问题等。
• 解决方案：
  1. 首先，确认 Git 本身能正常工作。在 PowerShell 中运行以下命令，尝试克隆一个公共仓库：

git clone https://github.com/nodejs/node.git --depth 1 如果这个命令失败，请检查您的网络连接、VPN/代理设置。 2. **其次，获取详细错误信息**。使用 verbose 模式重新运行安装命令： powershell npm install -g openclaw@latest --verbose 在输出的最后部分，找到 code 128 之前的几行，它会明确指出是哪个仓库地址访问失败了。根据这个具体地址判断是网络问题还是仓库不存在。 3. **尝试更换 npm 镜像**：虽然镜像主要影响 npm 包的下载，但有时也能改善 GitHub 资源的访问。您可以选择更换为国内镜像，如淘宝镜像： powershell npm config set registry https://registry.npmmirror.com ``` 更换后再次尝试安装。

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 模型，测试模型连接，修改模型参数，甚至通过界面添加新的模型提供商。
   • 技能管理（Skills Management）：列出所有已安装的 Skills（功能插件），显示其版本、状态，并提供安装、更新、卸载新 Skills 的操作入口。
   • 通讯平台配置（Communication Platform Config）：以表单形式展示飞书、微信等平台的接入参数，并支持在线修改和保存。
   • 日志查看器（Log Viewer）：实时显示 OpenClaw 的运行日志，支持过滤和搜索，方便排查问题。
   • 系统设置（System Settings）：可能包含 OpenClaw 自身的配置，如 Web UI 端口修改、开机自启设置、数据存储路径等。

3. 注意事项

   • 本地访问限制：默认情况下，Web 界面只监听 127.0.0.1，即只能从本机访问。如果您需要从局域网其他设备访问，可以修改配置文件中的 webUI.host 为 0.0.0.0（但请注意安全，建议设置访问密码或使用防火墙限制）。
   • 安全性：该界面通常无内置认证，因此不建议在公网暴露。如果确实需要远程管理，请使用 VPN 或 SSH 隧道。

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

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

步骤 6：启动配置向导

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

openclaw onboard

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

步骤 7：配置向导详解

在成功安装 OpenClaw 核心程序后，您将进入最重要的配置环节。openclaw onboard 命令启动的是一个基于文本的交互式向导（TUI），它将引导您完成所有必要设置。

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-您的实际密钥"
  

如何验证配置生效： 保存配置文件后，执行：

openclaw doctor

您将看到类似以下输出，确认 DeepSeek 已成功加载。

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。
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. 完成配置与启动

所有问答结束后，向导会生成配置文件并保存到默认位置。您会看到类似以下提示：

Configuration saved successfully!
You can now start OpenClaw with: openclaw start

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

openclaw doctor

如果一切正常，您就可以启动机器人了：

openclaw start

常见问题与解决方案

常用命令参考

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

安装与更新

# 一键安装脚本（初次安装）
iwr -useb https://openclaw.ai/install.ps1 | iex

# 通过 npm 全局安装/更新 OpenClaw
npm install -g openclaw@latest

# 清理缓存（如果之前安装失败导致缓存问题）
npm cache clean --force

配置向导与初始化

# 启动交互式配置向导
openclaw onboard

# 重新运行配置（调整模型等）
openclaw configure

网关控制

# 启动/停止/重启/查看网关状态
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status

配置管理

# 查看配置项
openclaw config list

# 设置默认主模型
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

# 查看特定配置
openclaw config get models.providers.deepseek

诊断与日志

# 运行健康检查
openclaw doctor

# 查看实时日志
openclaw logs --follow

飞书通道配置

# 设置飞书 App ID
openclaw config set channels.feishu.appId "cli_a925d4e310389bcc"

# 设置飞书 App Secret
openclaw config set channels.feishu.appSecret "你的 App Secret"

# 设置连接模式为 WebSocket
openclaw config set channels.feishu.connectionMode websocket

# 批准飞书用户访问
openclaw pairing approve feishu J6K8X9J4

智能体配置

# 创建 agent.json 文件（使用 UTF-8 编码）
Remove-Item C:\Users\aym\.openclaw\agents\main\agent.json -Force
@'
{
  "id": "main",
  "name": "main",
  "model": "deepseek/deepseek-chat",
  "instructions": "你是一个有帮助的 AI 助手，可以回答用户的各种问题。",
  "tools": []
}
'@ | Out-File -FilePath C:\Users\aym\.openclaw\agents\main\agent.json -Encoding UTF8

结语

至此，您已经完成了 OpenClaw 从安装到配置的全过程，并成功接入了飞书和 DeepSeek 模型。接下来，您可以尝试在飞书中 @机器人发送消息，观察它是否能调用 DeepSeek 智能回复。如果一切顺利，恭喜您！您已经拥有了一个强大的自托管 AI 助手。如果在后续使用中遇到 Skills 配置或其他问题，欢迎随时查阅 OpenClaw 官方文档或社区。祝您探索愉快！