OpenClaw 安装与飞书接入完整指南

OpenClaw 安装与飞书接入完整指南

OpenClaw 安装与飞书接入完整指南

[TOC]

一、OpenClaw 简介

OpenClaw 是一个独立的个人 AI 助手，可以在任何操作系统、任何平台上运行，采用独特的”龙虾方式”（The Lobster Way）。

二、安装方法

1. 系统要求

  • Node.js 18+
  • npm 或 pnpm/npm

2. 安装步骤

# 使用 npm 全局安装
npm install -g openclaw
# 或使用 pnpm
pnpm add -g openclaw

3. 初始化配置

openclaw gateway install

4. 添加飞书渠道（两种方式）

方式一：通过安装向导（推荐）

openclaw onboard

方式二：通过命令行

openclaw channels add

三、飞书接入详细配置

一、安装飞书插件

# 安装飞书插件
openclaw plugins install @openclaw/feishu
# 或本地 checkout（在 git 仓库内运行）
openclaw plugins install ./extensions/feishu

二、添加飞书渠道（两种方式）

方式一：通过安装向导添加（推荐）

如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加飞书：

openclaw onboard

向导会引导您完成：

  1. 创建飞书应用并获取凭证
  2. 配置应用凭证
  3. 启动网关

✅ 完成配置后，您可以使用以下命令检查网关状态：

  • openclaw gateway status – 查看网关运行状态
  • openclaw logs --follow – 查看实时日志

方式二：通过命令行添加

如果您已经完成了初始安装，可以用以下命令添加飞书渠道：

openclaw channels add

然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。

✅ 完成配置后，您可以使用以下命令管理网关：

  • openclaw gateway status – 查看网关运行状态
  • openclaw gateway restart – 重启网关以应用新配置
  • openclaw logs --follow – 查看实时日志

三、第一步：创建飞书应用

1. 打开飞书开放平台

访问 飞书开放平台，使用飞书账号登录。

Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设置 domain: "lark"。

2. 创建应用

  1. 点击 创建企业自建应用
  2. 填写应用名称和描述
  3. 选择应用图标

3. 获取应用凭证

在应用的 凭证与基础信息 页面，复制：

  • App ID（格式如 cli_xxx）
  • App Secret

❗ 重要：请妥善保管 App Secret，不要分享给他人。

4. 配置应用权限

在 权限管理 页面，点击 批量导入 按钮，粘贴以下 JSON 配置一键导入所需权限：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event_bot_p2p_chat:readonly",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event_bot_p2p_chat:readonly"]
  }
}

5. 启用机器人能力

在 应用能力 > 机器人 页面：

  1. 开启机器人能力
  2. 配置机器人名称

6. 配置事件订阅

⚠️ 重要提醒：在配置事件订阅前，请务必确保已完成以下步骤：

  1. 运行 openclaw channels add 添加了 Feishu 渠道
  2. 网关处于启动状态（可通过 openclaw gateway status 检查状态）

在 事件订阅 页面：

  1. 选择 使用长连接接收事件（WebSocket 模式）
  2. 添加事件：im.message.receive_v1（接收消息）

⚠️ 注意：如果网关未启动或渠道未添加，长连接设置将保存失败。

7. 发布应用

  1. 在 版本管理与发布 页面创建版本
  2. 提交审核并发布
  3. 等待管理员审批（企业自建应用通常自动通过）

四、第二步：配置 OpenClaw

通过配置文件配置

编辑 ~/.openclaw/openclaw.json：

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "我的AI助手",
        },
      },
    },
  },
}

通过环境变量配置

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark（国际版）域名

如果您的租户在 Lark（国际版），请设置域名为 lark（或完整域名），可配置 channels.feishu.domain 或 channels.feishu.accounts.<id>.domain：

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

五、第三步：启动并测试

1. 启动网关

openclaw gateway

2. 发送测试消息

在飞书中找到您创建的机器人，发送一条消息。

3. 配对授权

默认情况下，机器人会回复一个 配对码。您需要批准此代码：

openclaw pairing approve feishu <配对码>

批准后即可正常对话。

四、常用功能与命令

命令 说明
/status 查看机器人状态
/reset 重置对话会话
/model 查看/切换模型

注意：飞书目前不支持原生命令菜单，命令需要以文本形式发送。

网关管理命令 说明
openclaw gateway status 查看网关运行状态
openclaw gateway install 安装/启动网关服务
openclaw gateway stop 停止网关服务
openclaw gateway restart 重启网关服务
openclaw logs --follow 实时查看日志输出

五、访问控制配置

私聊访问

  • 默认 pairing 模式：陌生用户需要管理员批准
  • allowlist 模式：仅白名单用户可对话
  • open 模式：所有人可对话
  • disabled 模式：完全禁止私聊

群组访问

1. 群组策略（channels.feishu.groupPolicy）：

  • open = 允许群组中所有人（默认）
  • allowlist = 仅允许 groupAllowFrom 中的用户
  • disabled = 禁用群组消息

2. @提及要求（channels.feishu.groups.<chat_id>.requireMention）：

  • true = 需要 @机器人才响应（默认）
  • false = 无需 @也响应

六、群组配置示例

1. 允许所有群组，需要 @提及（默认行为）

{
  channels: {
    feishu: {
      groupPolicy: "open", // 默认
      requireMention: true
    },
  },
}

2. 允许所有群组，无需 @提及

需要为特定群组配置：

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: {
          requireMention: false
        },
      },
    },
  },
}

3. 仅允许特定用户在群组中使用

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

七、获取群组/用户 ID

获取群组 ID（chat_id）

群组 ID 格式为 oc_xxx，可以通过以下方式获取：

方法一（推荐）：

  1. 启动网关并在群组中 @机器人发消息
  2. 运行 openclaw logs --follow 查看日志中的 chat_id

方法二：使用飞书 API 调试工具获取机器人所在群组列表。

获取用户 ID（open_id）

用户 ID 格式为 ou_xxx，可以通过以下方式获取：

方法一（推荐）：

  1. 启动网关并给机器人发消息
  2. 运行 openclaw logs --follow 查看日志中的 open_id

方法二：查看配对请求列表，其中包含用户的 Open ID：

openclaw pairing list feishu

八、🧹 删除 OpenClaw 的方法（适用于所有操作系统）

本指南涵盖所有支持的彻底删除 OpenClaw 的方式，包括 CLI 已丢失但后台服务仍在运行的情况。

🔵 路径一：简易方式（CLI 仍可用）

如果 openclaw 命令仍然可用，请使用此方法。

✅ 推荐方式（内置卸载程序）

openclaw uninstall

🤖 非交互式模式（自动化/CI/npx）

openclaw uninstall --all --yes --non-interactive
npx -y openclaw uninstall --all --yes --non-interactive

🔧 手动步骤（效果相同）

如果您希望显式控制或调试，可使用此方法。

1. 停止网关服务

openclaw gateway stop

2. 卸载网关服务（launchd / systemd / schtasks）

openclaw gateway uninstall

3. 删除状态和配置

rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"

如果您将 OPENCLAW_CONFIG_PATH 设置到了状态目录之外的自定义位置，请同时手动删除该文件。

4. 删除工作区（可选，会移除代理文件）

rm -rf ~/.openclaw/workspace

5. 移除 CLI（根据您的安装方式选择）

npm rm -g openclaw
pnpm remove -g openclaw
bun remove -g openclaw

6. macOS 应用（如果安装过）

rm -rf /Applications/OpenClaw.app

⚠️ 注意事项

  • 如果您使用了配置文件（--profile 或 OPENCLAW_PROFILE），请为每个配置重复删除状态：
rm -rf ~/.openclaw-<profile>
  • 在远程模式下，状态目录位于网关主机上——请也在那里执行步骤 1–4。

🔴 路径二：手动删除服务（CLI 丢失）

如果 OpenClaw 服务仍在运行但 CLI 已不存在，请使用此方法。

🍎 macOS（launchd）

默认标签：

  • bot.molt.gateway
  • 或 bot.molt.<profile>
  • 旧版本：com.openclaw.*
launchctl bootout gui/$UID/bot.molt.gateway
rm -f ~/Library/LaunchAgents/bot.molt.gateway.plist

如果使用了配置文件，将 gateway 替换为 <profile>。

同时删除可能存在的旧版 com.openclaw.*.plist 文件。

🐧 Linux（systemd — 用户服务）

默认单元：

  • openclaw-gateway.service
  • 或 openclaw-gateway-<profile>.service
systemctl --user disable --now openclaw-gateway.service
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload

🪟 Windows（计划任务）

默认任务：

  • OpenClaw Gateway
  • 或 OpenClaw Gateway (<profile>)
schtasks /Delete /F /TN "OpenClaw Gateway"

PowerShell 清理：

Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"

如果使用了配置文件，删除：

$env:USERPROFILE\.openclaw-<profile>\gateway.cmd

📦 不同安装类型的差异

常规安装（install.sh / npm / pnpm / bun）

如果您通过以下方式安装：

  • https://openclaw.bot/install.sh
  • install.ps1
  • npm install -g openclaw@latest

删除方式：

npm rm -g openclaw
# 或
pnpm remove -g openclaw
bun remove -g openclaw

源码检出（git clone）

如果您从仓库克隆并运行 OpenClaw：

  1. 先卸载网关服务（使用上述简易方式或手动删除服务）
  2. 删除仓库目录
  3. 删除状态和工作区：
rm -rf ~/.openclaw ~/.openclaw/workspace

✅ 验证（可选但推荐）

卸载后，确认没有残留进程：

ps aux | grep openclaw
launchctl list | grep molt
systemctl --user list-units | grep openclaw

如果仍有输出，说明您遗漏了某个服务或配置文件。

最终说明

  • 您的原始内容正确但稍显杂乱。
  • 此版本可直接发布、便于查阅且适合技术支持。
  • 您可以将此部分直接放入 GitHub Gist 或 README 中原样使用，无需进一步清理。

如有需要，我还可以：

  • 添加故障排查场景
  • 创建简短的 “TL;DR 卸载”
  • 将其转换为官方文档格式（Docusaurus / MkDocs）

九、常见问题与解决方案

问题一：Telegram 代理配置

问题：Telegram 提示 failed (unknown) - This operation was aborted

排查方法：

openclaw status --deep

解决方法：配置代理

{
  "channels": {
    "telegram": {
      "proxy": "http://127.0.0.1:10080" // 如果位于代理之后
    }
  }
}

如果机器人输入 /start 没有消息，先设置 Telegram 代理，再执行以下命令重启：

openclaw gateway restart

重启后机器人就可以正常收到消息了。

问题二：飞书插件安装失败

解决方法：

# 1. 删除旧的插件文件
rm -rf ~/.openclaw/extensions/feishu*

# 2. 编辑配置文件，移除飞书相关配置
vi ~/.openclaw/openclaw.json
# 找到所有关于 feishu 的配置并删除

# 3. 重新安装插件
openclaw plugins install @m1heng-clawd/feishu

# 4. 重新配置渠道
openclaw configure
# 使用新的 App ID 和 App Secret 重新配置

问题三：飞书插件重复安装警告

问题原因：

OpenClaw 在全局安装目录中已经包含了一个内置的 feishu 插件，当你执行 openclaw plugins install @openclaw/feishu 安装时，会在用户目录 ~/.openclaw/extensions/feishu 再安装一个。两个插件使用了相同的 ID "feishu"，因此触发警告。

解决方案：

删除全局目录中的重复插件（保留用户目录的插件）：

# 删除全局 npm 目录中的内置 feishu 插件
rm -rf /home/lion/.npm-global/lib/node_modules/openclaw/extensions/feishu

# 重启 OpenClaw 网关使更改生效
openclaw gateway restart

验证修复：

执行以下命令检查是否还有警告：

openclaw gateway status
# 或
openclaw doctor

如果不再出现 duplicate plugin id detected 的警告，说明问题已解决。

补充说明：这是一个功能性的警告而非错误，OpenClaw 会使用后加载的插件（用户目录的版本），但删除重复插件可以消除警告并保持配置整洁。

问题四：机器人在群组中不响应

  1. 检查机器人是否已添加到群组
  2. 检查是否 @了机器人（默认需要 @提及）
  3. 检查 groupPolicy 是否为 "disabled"
  4. 查看日志：openclaw logs --follow

问题五：机器人收不到消息

  1. 检查应用是否已发布并审批通过
  2. 检查事件订阅是否配置正确（im.message.receive_v1）
  3. 检查是否选择了 长连接 模式
  4. 检查应用权限是否完整
  5. 检查网关是否正在运行：openclaw gateway status
  6. 查看实时日志：openclaw logs --follow

问题六：App Secret 泄露怎么办

  1. 在飞书开放平台重置 App Secret
  2. 更新配置文件中的 App Secret
  3. 重启网关

问题七：发送消息失败

  1. 检查应用是否有 im:message:send_as_bot 权限
  2. 检查应用是否已发布
  3. 查看日志获取详细错误信息

十、获取帮助

如果遇到其他问题，可以访问：

  • 官方文档：https://docs.openclaw.ai
  • GitHub 仓库：https://github.com/openclaw/openclaw
  • 社区支持：https://discord.com/invite/clawd
Comments are closed.