Feishu

最終更新 2026/10/07

前提条件

1. Feishuオープンプラットフォームの設定

1. Feishuオープンプラットフォームにアクセスします

2. 企業自社開発アプリを作成します（または既存のアプリを使用します）

3. アプリの認証情報を取得します：

   • App ID（アプリID）
   • App Secret（アプリシークレット）

2. ボットの設定

Feishuオープンプラットフォーム →「App details」→「Features」→「Bot」で、ボット機能を有効にします。

3. リダイレクトURLの設定

Feishuオープンプラットフォーム →「App details」→「Security Settings」→「Redirect URLs」で、次のURLを追加します：

http://your-domain/agent/api/feishu-oauth/callback

4. イベントとコールバック

サブスクリプション方式：Feishuオープンプラットフォームの「Events & Callbacks」で、イベントとコールバックのどちらも「Receive through persistent connection」を選択します。公開ネットワークのリクエストURLを設定する必要はありません。

1. イベント設定：im.message.receive_v1（Receive messages v2.0）を追加します。ユーザーがボットに送信したメッセージ、画像、ファイルを受信するために使用します。
2. コールバック設定：card.action.trigger（カードのコールバックインタラクション）を追加します。AskUserQuestionの質問フォームの送信、無視、続行の操作に使用します。
3. アプリの権限：im:resource（ユーザーの画像/ファイルのダウンロードと生成ファイルのアップロード）とcardkit:card:write（インタラクティブカードの作成、ストリーミング更新、置き換え）を必ず含めてください。im:resourceがない場合、テキストメッセージは正常に処理されることがありますが、画像の読み取りと生成ファイルの送信は失敗します。
4. 保存して公開する：権限、イベント、コールバックを変更した後は、必ず「Version Management & Release」で新しいバージョンを作成して公開し、利用可能範囲にターゲットユーザーが含まれていることを確認してください。開発設定を保存しただけでは、インストール済みのバージョンには反映されません。

ヒント

動作確認のおすすめ：チャネルを起動したら、まずロングコネクションが成功したことを確認し、次に通常のテキスト、画像の読み取り、AskUserQuestionのフォーム送信、生成ファイルのネイティブ添付を順にテストします。

5. アプリの権限設定

Feishuオープンプラットフォーム →「App details」→「Permissions & Scopes」で、次の権限を申請します：

メッセージ関連の権限（Bot Token Scopes）：

権限	説明
im:message	メッセージを送信
im:message.group_at_msg:readonly	グループチャットでボットを@メンションしたメッセージを読み取る
im:message.group_msg	グループメッセージを送信
im:message.p2p_msg:readonly	プライベートメッセージを読み取る
im:message:send_as_bot	ボットとしてメッセージを送信
im:message:readonly	メッセージを読み取る
im:resource	画像またはファイルリソースの取得とアップロード
cardkit:card:write	カードの作成と更新

ユーザーアイデンティティの権限（User Token Scopes）：

権限	説明
contact:user.base:readonly	ユーザーの基本情報を取得（認証に必須）

権限の申請後、管理者の承認が必要です。

一括インポート：

{

"scopes": {

"tenant": [

"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",

"cardkit:card:write"

],

"user": [

"contact:user.base:readonly"

]

}

}

ヒント

権限を一括インポートする場合は追加で確認してください：インポート結果にim:resourceとcardkit:card:writeが必ず含まれている必要があります。古いJSONにこの2つが含まれていない場合は、「Permissions & Scopes」で追加してから、アプリのバージョンを再度公開してください。

グループチャットのメッセージ振り分けのために追加を推奨する権限：tenant:tenant:readonly（テナント情報の取得）。この権限があると、システム管理でチャネルを検証した直後にテナントを識別し、チャットスペースを表示できます。この権限がなくても認証情報の検証やメッセージの送受信には影響しませんが、チャットスペースは、対象グループでボットを@メンションしたメッセージが初めて届いた後に検出されます。権限を追加したら、アプリのバージョンを再度公開し、チャンネル管理で「再検証」をクリックしてください。

6. アプリを公開する

Feishuオープンプラットフォーム →「App details」→「Version Management & Release」で、アプリの表示範囲の設定&アプリの公開を行います

従業員を選択して権限を付与します。表示範囲内の従業員のみが使用できます

審査に合格すると、アプリが使用可能になります。

Agentの設定

1. チャンネル管理の設定

システム管理で設定します：

1. システムにログインし、「システム管理」→「エージェント 管理者」→「チャンネル管理」に進みます

2. 「新規チャンネル」をクリックし、「Feishu」タイプを選択します

3. 設定情報を入力します：

   • チャンネル名：任意の名前（例：「Feishuボット」）
   • APP ID & APP Secret

4. 「保存」をクリックすると、設定が自動的に暗号化されて保存されます

5. チャネルを有効にします（「有効」スイッチがオンになっていることを確認します）

注意：

• 設定情報はデータベースに暗号化して保存されるため、安全性が高まります
• アプリの起動時に、有効なすべてのFeishuチャネルに自動的に接続します（WebSocketのロングコネクション経由）
• 設定を変更した後、サービスを再起動する必要はなく、すぐに反映されます

使い方の流れ

ユーザーの連携手順

1. ユーザーがシステムにログインします
2. 左下のユーザーアバターをクリックしてメニューを開きます
3. 「チャネル連携」を選択し、「Feishu」の下で連携するチャネルインスタンスを見つけて、「連携」ボタンをクリックします
4. Feishuの認証ページに移動します
5. ユーザーが認証を確認します
6. 自動的にシステムに戻り、「連携完了」ページが表示されます
7. 認証ウィンドウを閉じると元のページが自動的に更新され、メニューに「連携済み」ステータスが表示されます

ユーザーの連携解除手順

1. 左下のユーザーアバターをクリックしてメニューを開きます
2. 「チャネル連携」を選択し、「Feishu」の下で連携済みのチャネルインスタンスを見つけて、「連携解除」ボタンをクリックします
3. 連携解除の操作を確認します
4. 連携が解除され、メニューに「未連携」ステータスが表示されます

使用マニュアル

カスタムコマンド

Feishuボットは次のコマンドに対応しています（すべてのコマンドは/で始まります）：

コマンド	説明	例
/new	新しい会話を開始し、現在の会話履歴をクリアする	/newを送信
/agent <名称> <消息>	指定した名前のAgentにメッセージを送信	/agent rhea 你好
/agent <消息>	システムのデフォルトAgentにメッセージを送信	/agent 你好

説明：

• /で始まらないメッセージは、システムのデフォルトAgentに直接送信されます
• Agent名は、ユーザーがアクセス権限を持つAgentである必要があります
• コマンドの引数は大文字と小文字が区別されます

グループチャットのメッセージ振り分け

グループチャットのメッセージ振り分けを使用すると、同じFeishuボットがルールに従って、さまざまな質問をそれぞれ異なるAgentまたはTeamに渡すことができます。1つの「チャットスペース」は現在のFeishuテナントに対応し、設定はそのテナント内でこのボットを使用しているグループチャットに適用されます。Agentic Engineアカウントを連携済みで、グループ内でボットを明示的に@メンションしたメンバーのみがタスクを開始できます。

管理者による設定

1. チャネルが有効になっていること、アプリが公開されていること、im.message.receive_v1とcard.action.triggerをサブスクライブしていることを確認します。tenant:tenant:readonlyの追加を推奨します。追加すると、チャネルの検証時にシステムがFeishuテナントを識別できます。追加していない場合は、まず対象グループでボットを@メンションしてメッセージを1件送信しないと、システムがそのチャットスペースを検出できません。
2. 「システム管理 → エージェント 管理者 → チャンネル管理」に進み、対象のFeishuチャネルで「メッセージ振り分け」を開きます。チャットスペースが複数ある場合は、まず設定するスペースを選択します。
3. 「既定の Agent/Team」を選択します。グループチャット振り分けを有効にする前に、既定の対象を設定する必要があります。通常のメッセージが他のルールに一致しない場合は、この対象が処理します。
4. 必要に応じて最大19件のルールを追加します。各ルールでAgent/Teamを1つ選択し、必須の「呼び出しコマンド」を入力します。キーワードも最大10個まで入力できます。その後、そのルールの有効化スイッチをオンにします。
5. 保存後、グループで@机器人 /helpを送信して動作を確認し、一覧に現在のユーザーが使用でき、かつ現在実行可能なAgent/Teamのみが表示されることを確認します。

構成項目	ルール
既定の Agent/Team	設定しないと有効にできません。呼び出しコマンドが指定されておらず、キーワードにも一致しない場合に使用されます。
呼び出しコマンド	必須、1～32文字。英字、数字、-、_ を使用できます。システムの予約コマンドは使用できません。大文字・小文字や全角・半角の違いは、別のコマンドとして扱われません。
キーワード	入力は任意です。各ルール最大10個、1個あたり2～32文字。複数のキーワードが同時に一致した場合は、長いキーワードが優先されます。同じ長さのルールで一意に判断できない場合は、既定の Agent/Team に戻ります。
選択可能な範囲	有効かつ実行可能なシステム/企業Agent、および現在の企業のTeamを選択できます。個人Agentはグループチャット振り分けの候補に表示されません。

グループチャットでの使い方

用途	例	説明
利用可能な機能を確認	@机器人 /help @机器人 能力清单	既定の対象、呼び出しコマンド、キーワードを一覧表示します。権限がない機能や現在実行できない機能は表示されません。
Agent/Teamを指定	@机器人 /analysis 分析本周数据	analysisは管理者が設定した呼び出しコマンドです。@机器人 @analysis 分析本周数据と送信することもできます。
キーワードで振り分け	@机器人 帮我检查埋点方案	本文があるルールのキーワードに一致した場合は、対応するAgent/Teamに渡します。一致しない場合は既定の対象を使用します。
タスクを取消	@机器人 /cancel	メッセージ全体をこのとおり正確に送信する必要があります。タスクがすでに出力した本文は残り、取消の確認メッセージが別途届きます。
旧形式との互換	@机器人 /agent analysis 分析本周数据	引き続き使用できますが、新しいドキュメントでは/analysisを直接使用することを推奨します。

コマンドの範囲：グループチャット振り分けでは/newは使用できません。プライベートチャットでは引き続き/new、/agent、/cancelを使用できます。グループチャットでの通常の新規タスクは、まずボットを@メンションする必要があります。既存のタスクが回答を待っている場合に限り、ボットの案内に従って元のスレッドまたはインタラクティブカードで返信を続けることができます。

公開コンテキストと個人データ：システムが参考にするのは、最近ボットを明示的に@メンションし、実際に処理されたグループチャットの公開ターンのみです。ボットを@メンションしていない通常のグループメッセージ、他のグループ、プライベートチャット、ユーザーメモリが混ざることはありません。履歴の内容は信頼できない参考情報としてのみ扱われ、現在のメッセージがこのターンの指示となります。

トラブルシューティング

1. コールバックURLのエラー

エラーメッセージ：リダイレクトURLが正しくありません。アプリの管理者に連絡してください

解決方法：

• Feishuオープンプラットフォームで設定したコールバックURLが正しいか確認します
• プロトコル、ドメイン、ポート、パスが完全に一致していることを確認します
• ローカル開発ではポート番号に注意します（例：3000 vs 8686）
• NEXT_PUBLIC_BASE_PATHを使用している場合は、コールバックURLにそのパスを含める必要があります

2. Feishuチャネルが未設定

エラーメッセージ：Feishu チャネルが未設定か無効です

解決方法：

• 「システム管理」→「エージェント 管理者」→「チャンネル管理」に進み、Feishuチャネルが存在するか確認します
• チャネルの「有効」スイッチがオンになっていることを確認します
• App IDとApp Secretが正しく入力されているか確認します
• アプリの種類が企業自社開発アプリであることを確認します

3. App Access Tokenが無効

エラーメッセージ：The app access token passed is invalid

解決方法：

• チャンネル管理のApp IDとApp Secretが正しいか確認します
• アプリの種類（企業自社開発アプリ）を確認します
• アプリが有効になっているか確認します

4. 権限不足

エラーメッセージ：権限が不足しているか、権限の検証に失敗しました

解決方法：

• Feishuオープンプラットフォームで必要な権限を申請します
• 管理者による権限の承認を待ちます
• 権限が有効になっていることを確認します

5. 連携の失敗

エラーメッセージ：この Feishu アカウントは他ユーザーに紐付いています

解決方法：

• 1つのFeishuアカウントは、1人のシステムユーザーにのみ連携できます
• 連携先を変更する場合は、先に元のアカウントで連携を解除します

関連ドキュメント

• Feishuオープンプラットフォームのドキュメント

---

関連ページと次のステップ

• 他のプラットフォームの接続手順を確認する：チャンネル管理。
• チャネル接続と連携の全体的な流れを確認する：チャネルの概要と連携。
• 使用するAgentを設定する：Agent。
• プラットフォーム内での会話の使い方を確認する：会話。