feishu-channel

Lark チャネル連携

Lark を OpenClaw に接続し、双方向のメッセージチャネルを実現します。

feishu-automation との違い

特性	feishu-channel	feishu-automation
主な用途	メッセージチャネル連携	プラットフォームの自動操作
メッセージ受信	✅ Webhook イベント購読	❌ 非対応
メッセージ送信	✅ リアルタイム対話	✅ 通知の配信
多次元テーブル	❌ 対象外	✅ 完全対応
ドキュメント管理	❌ 対象外	✅ 完全対応
適用シーン	AI 対話ボット	データ同期、自動化ワークフロー

アーキテクチャの概要

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   飞书用户   │ ←→  │   飞书开放平台    │ ←→  │  OpenClaw   │
│  (私聊/群聊) │     │   (Webhook)      │     │   Gateway   │
└─────────────┘     └──────────────────┘     └─────────────┘
                           ↓
                    ┌──────────────────┐
                    │   Webhook 服务    │
                    │   - 事件验证      │
                    │   - 消息解析      │
                    │   - 格式转换      │
                    └──────────────────┘

コアコンポーネント

1. Lark ボットアプリ

Lark オープンプラットフォームで作成する企業向けカスタムアプリで、以下を担当します。

• ユーザーメッセージの受信（イベント購読経由）
• メッセージの送信（メッセージ API 経由）
• 権限とセキュリティの管理

2. Webhook サービス

Lark のイベントプッシュを受信し、OpenClaw Gateway に転送します。

3. メッセージ送信 API

lark-mcp ツールを使用するか、Lark API を直接呼び出してメッセージを送信します。

クイックスタート

前提条件

• Lark オープンプラットフォームのアカウント
• 企業向けカスタムアプリ（ボット機能）
• OpenClaw Gateway が稼働中であること
• パブリックネットワークからアクセス可能な Webhook URL（またはトンネリングを利用）

1. Lark アプリを作成する

1. Lark オープンプラットフォームにアクセスします
2. 企業向けカスタムアプリを作成します
3. 「ボット」機能を追加します
4. 権限を設定します（以下の権限一覧を参照）
5. App ID と App Secret を取得します

2. イベント購読を設定する

1. アプリ管理ページで「イベント購読」を開きます
2. リクエスト URL を設定します：https://your-domain.com/webhook/feishu
3. 以下のイベントを購読します。
   • im.message.receive_v1 - メッセージ受信
   • im.message.message_read_v1 - メッセージ既読（任意）

3. Webhook サービスをデプロイする

cd /home/aa/clawd/skills/feishu-channel
npm install
cp .env.example .env
# 编辑 .env 填入配置
npm start

4. アプリを公開する

1. Lark オープンプラットフォームに審査を申請します
2. 審査に通過したら公開します
3. Lark でボットを検索して追加します

設定

環境変数（.env）

# 飞书应用配置 (必需)
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx

# 事件订阅验证 Token
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx
# 事件加密 Key (可选，推荐启用)
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx

# OpenClaw Gateway 配置
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_WEBHOOK_SECRET=your_webhook_secret

# 安全配置
# 允许的用户 open_id (逗号分隔，留空允许所有)
ALLOWED_USERS=ou_xxx,ou_yyy
# 允许的群聊 chat_id (逗号分隔，留空允许所有)
ALLOWED_GROUPS=oc_xxx,oc_yyy

# 群聊行为
REQUIRE_MENTION_IN_GROUP=true

# 服务端口
PORT=3002

# 日志级别
LOG_LEVEL=info

Lark アプリの権限

権限	説明	必須
im:message	1 対 1 およびグループメッセージの取得と送信	✅
im:message.group_at_msg	グループチャットでボット宛てのメッセージを受信	✅
im:message.p2p_msg	ユーザーからボットへの 1 対 1 メッセージを受信	✅
im:chat	グループ情報の取得	推奨
contact:user.base	ユーザーの基本情報の取得	推奨
im:resource	画像またはファイルリソースの取得とアップロード	任意

OpenClaw の設定（openclaw.json）

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxx",
      "appSecret": "env:FEISHU_APP_SECRET",
      "webhookUrl": "https://your-domain.com/webhook/feishu",
      "dmPolicy": "allowlist",
      "allowFrom": ["ou_xxx", "ou_yyy"],
      "groups": {
        "oc_xxx": {
          "name": "工作群",
          "requireMention": true
        }
      }
    }
  }
}

メッセージ形式

メッセージの受信（Webhook イベント）

Lark の元のイベント形式：

{
  "schema": "2.0",
  "header": {
    "event_id": "xxx",
    "event_type": "im.message.receive_v1",
    "create_time": "1706745600000",
    "token": "verification_token",
    "app_id": "cli_xxx"
  },
  "event": {
    "sender": {
      "sender_id": {
        "open_id": "ou_xxx",
        "user_id": "xxx",
        "union_id": "on_xxx"
      },
      "sender_type": "user"
    },
    "message": {
      "message_id": "om_xxx",
      "root_id": "",
      "parent_id": "",
      "create_time": "1706745600000",
      "chat_id": "oc_xxx",
      "chat_type": "group",
      "message_type": "text",
      "content": "{\"text\":\"@_user_1 你好\"}",
      "mentions": [
        {
          "key": "@_user_1",
          "id": {
            "open_id": "ou_bot"
          },
          "name": "OpenClaw助手"
        }
      ]
    }
  }
}

変換後の OpenClaw 形式：

{
  "type": "message",
  "channel": "feishu",
  "messageId": "om_xxx",
  "from": {
    "id": "ou_xxx",
    "name": "张三"
  },
  "chat": {
    "id": "oc_xxx",
    "type": "group",
    "name": "工作群"
  },
  "text": "你好",
  "mentions": ["ou_bot"],
  "isMentioned": true,
  "timestamp": 1706745600000
}

メッセージの送信

lark-mcp ツールを使用する

// 发送文本消息
await mcp__lark-mcp_sendMessage({
  receive_id: "ou_xxx",  // 或 oc_xxx (群聊)
  receive_id_type: "open_id",  // 或 chat_id
  msg_type: "text",
  content: JSON.stringify({
    text: "收到，正在处理..."
  })
});

// 发送富文本消息
await mcp__lark-mcp_sendMessage({
  receive_id: "oc_xxx",
  receive_id_type: "chat_id",
  msg_type: "post",
  content: JSON.stringify({
    zh_cn: {
      title: "任务完成",
      content: [
        [
          { tag: "text", text: "已完成 " },
          { tag: "a", text: "查看详情", href: "https://example.com" }
        ]
      ]
    }
  })
});

// 发送卡片消息
await mcp__lark-mcp_sendMessage({
  receive_id: "oc_xxx",
  receive_id_type: "chat_id",
  msg_type: "interactive",
  content: JSON.stringify({
    config: { wide_screen_mode: true },
    header: {
      template: "turquoise",
      title: { content: "通知", tag: "plain_text" }
    },
    elements: [
      {
        tag: "div",
        text: { content: "**重要通知**", tag: "lark_md" }
      },
      {
        tag: "action",
        actions: [
          {
            tag: "button",
            text: { content: "确认", tag: "plain_text" },
            type: "primary"
          }
        ]
      }
    ]
  })
});

HTTP API を使用する

# 发送文本消息
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receive_id": "ou_xxx",
    "msg_type": "text",
    "content": "{\"text\":\"Hello!\"}"
  }'

セキュリティポリシー

イベントの検証

Lark のイベント購読では、次の 2 種類の検証方式を利用できます。

1. Verification Token：シンプルなトークン検証
2. Encrypt Key：AES 暗号化（推奨）

// 验证示例
function verifyEvent(body, token) {
  if (body.token !== token) {
    throw new Error('Invalid verification token');
  }
}

// 解密示例
function decryptEvent(encrypt, key) {
  const crypto = require('crypto');
  const decipher = crypto.createDecipheriv(
    'aes-256-cbc',
    crypto.createHash('sha256').update(key).digest(),
    Buffer.alloc(16, 0)
  );
  return JSON.parse(
    decipher.update(encrypt, 'base64', 'utf8') + decipher.final('utf8')
  );
}

1 対 1 チャットのポリシー

ポリシー	説明
open	すべてのユーザーとの 1 対 1 チャットを許可します（危険）
allowlist	allowFrom リスト内のユーザーのみ許可します

グループチャットのポリシー

設定	説明
requireMention: true	ボットへの@メンションが必須です
allowFrom	グループ内での起動を許可するユーザーのリスト

使用シーン

1. インテリジェント Q&A ボット

用户: @OpenClaw助手 帮我查一下今天的会议安排
Bot: 今天的会议安排：
- 10:00 产品评审会 (会议室A)
- 14:00 技术分享会 (线上)
- 16:00 周例会 (会议室B)

2. ワークフロー通知

// 当任务完成时发送通知
await mcp__lark-mcp_sendMessage({
  receive_id: "oc_work_group",
  receive_id_type: "chat_id",
  msg_type: "interactive",
  content: JSON.stringify({
    header: {
      template: "green",
      title: { content: "✅ 任务完成", tag: "plain_text" }
    },
    elements: [
      {
        tag: "div",
        text: { content: "数据同步任务已完成\n处理记录: 1,234 条", tag: "lark_md" }
      }
    ]
  })
});

3. 承認ワークフロー

用户: @OpenClaw助手 提交请假申请，明天休息一天
Bot: 已收到请假申请，正在提交审批...
     [卡片消息: 请假申请详情 + 审批按钮]

トラブルシューティング

Webhook でメッセージを受信できない

1. Webhook URL にパブリックネットワークからアクセスできることを確認します
2. Verification Token が正しいことを確認します
3. Lark オープンプラットフォームのイベントプッシュログを確認します
4. アプリが公開済みで、ユーザーがボットを追加していることを確認します

メッセージの送信に失敗する

1. App ID と App Secret を確認します
2. アプリの権限が有効になっていることを確認します
3. access_token の有効期限が切れていないか確認します
4. API が返したエラーコードを確認します

権限が不足している

1. Lark オープンプラットフォームでアプリの権限を確認します
2. 権限の審査が完了していることを確認します
3. access_token を再取得します

制限事項

Lark プラットフォームの制限

• API 呼び出し頻度の制限（公式ドキュメントを参照）
• メッセージ長の制限
• ファイルサイズの制限

機能の制限

• 音声メッセージには対応していません
• カードメッセージの操作には追加のコールバック設定が必要です
• 一部の高度な機能には企業認証が必要です

関連ファイル

• scripts/feishu-webhook.js - Webhook サービスのコード
• .env.example - 環境変数のテンプレート
• references/feishu-api.md - Lark API のリファレンス
• references/message-types.md - メッセージタイプの説明

TODO

• Lark アプリを作成して認証情報を取得する
• イベント購読を設定する
• Webhook サービスをデプロイする
• 1 対 1 メッセージの送受信をテストする
• グループチャットでの@メンションをテストする
• セキュリティポリシーを設定する
• カードメッセージの操作を実装する