メインコンテンツへスキップ
飞书频道为一个组织中的智能体提供了一条进入飞书群组的单一热线：出站通知、入站回复和交互式的批准/拒绝卡片（通过 feishu_gate hook）。 本指南介绍了端到端的设置过程。它假设 FIM One 可以在稳定的 HTTPS 源上访问——称之为 API_BASE_URL（例如 https://one.yourdomain.com）。

​
1. Feishuアプリを作成する

  1. Feishu Open Platformにアクセスして、Create custom app for enterpriseをクリックします。
  2. 名前、アイコン、簡単な説明を入力します。組織のエンドユーザーはカード上でこれらを表示します。
  3. Credentials & Basic Infoページで、App IDとApp Secretをコピーします。これらはステップ4でFIM Oneに貼り付けます。
App Secretはパスワードのように扱ってください。FIM Oneは保存時に暗号化しますが、平文コピーを持つ誰もがボットになりすまし可能です。

​
2. パーミッションを付与する

Permissions & Scopes で、以下のスコープを有効にしてパーミッションバージョンを送信します:
スコープ理由
im:messageメッセージ（テキスト + カード）を送信
im:message:send_as_botボットアイデンティティとして投稿
im:chatボットが属するグループチャットをリストおよび読み取り
im:chat:readonlyグループ検出の最小読み取りアクセス
im:resource（オプション）カードに表示される画像 / ファイルをアップロード

​
3. イベントサブスクリプションを有効にする（Request URLは今のところ空白のままにしておく）

Event Subscriptionsを開きますが、Request URLはまだ入力しないでください — ステップ5でFIM Oneから取得します。 以下のイベントをサブスクライブします：
  • im.message.receive_v1 — ユーザーからのインバウンドメッセージ
  • card.action.trigger — 承認/却下ボタンのクリック
同じページで、オプションとしてVerification TokenとEncrypt Keyを設定できます。FIM Oneは両方のモードをサポートしており、提供されたものを使用します。

​
4. FIM One でチャネルを追加する

  1. 組織オーナーまたは管理者としてサインインします。
  2. Organization Settings → Channels → New Channel に移動します。
  3. タイプとして Feishu を選択し、以下を入力します：
    フィールドソース
    Name任意の内部ラベル（例：Ops team Feishu）
    App IDステップ 1 から（cli_xxxxxxxxxxxxxxxx）
    App Secretステップ 1 から
    Verification Token（オプション）ステップ 3 から
    Encrypt Key（オプション）ステップ 3 から
  4. Browse chats をクリックします — FIM One はあなたの認証情報を使用して Feishu を呼び出し、ボットが現在メンバーであるすべてのグループをリストアップします。
リストが空の場合、ボットはまだどのグループにも追加されていません。Feishu を開き、ボットをターゲットグループに追加してから、ピッカーを再度開いてください。
  1. ルーティング先のグループチャットを選択し、Save をクリックします。

​
5. Feishuでコールバック URLを登録する

保存後、FIM One はチャネル詳細パネルにコールバック URLを表示します。形式は以下の通りです： 
{API_BASE_URL}/api/channels/{CHANNEL_ID}/callback
これをコピーして、Feishu のイベント購読ページに戻り、リクエスト URLとして貼り付けて、検証をクリックします。Feishu は 1 回限りの url_verification チャレンジを POST します。FIM One が自動的に応答します。

​
6. テストメッセージを送信

FIM One チャネル詳細パネルに戻り、Send test message をクリックします。短いプレーンテキストメッセージ（FIM One test message from <your email>）が1秒以内にターゲットグループに表示されるはずです。 表示されない場合：
  • 401 / 403 — App Secret を再確認し、ステップ2のスコープを再度有効にして、権限バージョンを再公開します。
  • Silent failure — ボットが実際にグループに参加していることを確認し（ステップ4のピッカー）、チャネル行の is_active が true であることを確認します。
  • Verification fails on step 5 — API_BASE_URL が HTTPS であり、公開でアクセス可能であることを確認します。Feishu は非 HTTPS リクエスト URL を拒否します。

​
7. 智能体の配線（オプション — 承認）

ツール呼び出しをグループ承認の背後に置くには：
  1. ツール / コネクタアクション上で、Requires confirmation をオンにします。
  2. 智能体上で、Hooks → Class hooks の下に feishu_gate を追加します。
  3. 智能体の組織が正確に1つのアクティブな Feishuチャネルを持つことを確認します — フックは自動的にそこにルーティングされます。
智能体がゲートされたツールを実行しようとすると、インタラクティブカードがグループに投稿され、Approve / Reject が表示されます。ツールは待機し（SSEストリームが一時停止）、メンバーがタップするまで待ちます。判定がストリームバックされ、智能体は完了するか中止します。

​
トラブルシューティング

​
chat_id をピッカーなしで見つける

チャットを閲覧 UI が推奨されるフローです。生の ID が必要な場合（例えば、スクリプティングから POST /api/channels を呼び出す場合）、3 つのフォールバックがあります： a. Feishu に対して curl を実行する 
APP_ID="cli_xxxxxxxxxxxxxxxx"
APP_SECRET="<your-app-secret>"

TOKEN=$(curl -s -X POST \
  "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")

curl -s "https://open.feishu.cn/open-apis/im/v1/chats?page_size=50" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
レスポンス内のすべての items[].chat_id（oc_ というプレフィックスが付いている）は候補です。 b. Feishu API Explorer Feishu Open Platform コンソールで、Dev Tools → API Explorer を開き、/open-apis/im/v1/chats を見つけ、tenant_access_token 認証を選択して、Invoke をクリックします。Feishu がトークンを生成します — シェルは不要です。 c. Feishu クライアントからコピーする Feishu デスクトップまたはモバイル クライアントで、グループを開き、グループ設定 → グループ情報 に移動します。一部のバージョンでは グループ ID をコピー オプションが表示されます。可用性はクライアント バージョンと管理者が設定した権限によって異なるため、これは最も信頼性の低いフォールバックです。

​
カードクリックがFIM Oneに到達しない（エラー200340）

Feishuクライアントで承認または却下をクリックすると出错了，请稍后重试 code: 200340が表示される場合は、以下のリストを順に確認してください：
  1. card.action.triggerがサブスクライブされている必要があります（ステップ3）。サブスクライブする前に承認ゲートを有効にした場合は、Feishuコンソールで再度サブスクライブをクリックしてください。
  2. コールバックURLを再度保存します。 Feishuは再起動後も残る古いサブスクリプション状態をキャッシュすることがあります。URL検証ハンドシェイクがまだ成功していても、イベントルーティングが静かに停止することがあります。Feishu開放プラットフォームのイベントサブスクリプションページを開き、同じコールバックURLを再度入力して、保存/検証をもう一度クリックしてください。URLは1回のラウンドトリップで再検証され、次のボタン押下でライブボタンクリックが流れ始めます。これは昨日は機能していたチャネルが、コード変更なしで今日停止した場合の最も一般的な修正方法です。
  3. Feishu開放プラットフォームのイベントデバッガーを確認します（事件与回调 → 事件调试）。各ボタン押下は配信ステータス（2xx / 4xx / 未投递）とともにそこに表示されるはずです。未投递が表示される場合、Feishu自体が送信前にイベントを拒否しています。通常、スコープが不足しているか、サブスクリプションが無効になっています。
  4. スコープチェック。 权限管理で、アプリがim:messageおよびテナントが必要とするcard関連のスコープを持っていることを確認してください。スコープが不足していると、サブスクリプションがUIで緑色で表示されていても、配信時にイベントが静かにドロップされます。

​
承認/却下ボタンは何度もクリックできます

webhookは最初の決定時に置き換えカードを返すようになりました — ボタンが削除され、カードヘッダーが緑色（承認）または赤色（却下）に切り替わります。最初のクリック後もクリック可能なボタンが表示される場合は、Feishuクライアントがキャッシュされたコピーを表示している可能性があります。チャットを再度開くと、決定されたカードが正しくレンダリングされます。

​
1つの組織、2つのFeishuチャネル

feishu_gate は最初に見つかったアクティブなチャネルを選択します。同じ組織内に複数のFeishuエンドポイントが必要な場合（例：ステージング対本番グループ）、1つを除くすべてを無効にするか、エージェントタグで選択するカスタムフックを作成してください。