トラブルシューティング：チャンネル
一般的なチャンネルの問題
チャンネルが接続されているように見えるがメッセージが届かない
- オーナーIDを確認する。
ownerIdが設定されていないか間違っている場合、あなたからのメッセージが制限された権限で外部（非オーナー）メッセージとしてルーティングされる可能性があります。 - 分類を確認する。 チャンネルの分類がセッションのTaintよりも低い場合、レスポンスはno-write-downルールによってブロックされます。
- デーモンのログを確認する。
triggerfish logs --level WARNを実行して配信エラーを探します。
メッセージが送信されない
ルーターは配信失敗をログに記録します。次の内容を triggerfish logs で確認します：
Channel send failedこれはルーターが配信を試みたがチャンネルアダプターがエラーを返したことを意味します。具体的なエラーもその横にログ記録されます。
リトライの動作
チャンネルルーターは失敗した送信に指数バックオフを使用します。メッセージが失敗した場合、遅延を増やしながら再試行されます。すべての再試行が使い果たされた後、メッセージはドロップされエラーがログに記録されます。
Telegram
ボットが応答しない
- トークンを確認する。 TelegramでBotFatherに連絡し、トークンが有効でキーチェーンに保存されているものと一致することを確認します。
- ボットに直接メッセージを送る。 グループメッセージはボットにグループメッセージの権限が必要です。
- ポーリングエラーを確認する。 TelegramはLong pollingを使用します。接続が切断された場合、アダプターは自動的に再接続しますが、継続的なネットワーク問題はメッセージの受信を妨げます。
メッセージが複数の部分に分割される
Telegramはメッセージあたり4,096文字の制限があります。長いレスポンスは自動的にチャンク化されます。これは正常な動作です。
ボットコマンドがメニューに表示されない
アダプターは起動時にスラッシュコマンドを登録します。登録が失敗した場合、警告がログに記録されますが実行は継続されます。これは致命的ではありません。ボットは引き続き動作しますが、コマンドメニューにオートコンプリートの候補が表示されなくなります。
古いメッセージを削除できない
Telegramはボットが48時間以上前のメッセージを削除することを許可していません。古いメッセージを削除しようとすると、サイレントに失敗します。これはTelegram APIの制限です。
Slack
ボットが接続しない
Slackには3つの認証情報が必要です：
| 認証情報 | フォーマット | 取得場所 |
|---|---|---|
| Bot Token | xoxb-... | Slackアプリ設定のOAuth & Permissionsページ |
| App Token | xapp-... | Basic Information > App-Level Tokens |
| Signing Secret | 16進数文字列 | Basic Information > App Credentials |
3つのいずれかが欠けているか無効な場合、接続が失敗します。最も一般的な間違いはBot Tokenとは別個のApp Tokenを忘れることです。
Socket Modeの問題
TriggerFishはHTTPイベントサブスクリプションではなく、SlackのSocket Modeを使用します。Slackアプリ設定で：
- 「Socket Mode」にアクセスして有効になっていることを確認する
connections:writeスコープを持つアプリレベルトークンを作成する- このトークンが
appToken（xapp-...）
Socket Modeが有効でない場合、ボットトークンだけではリアルタイムメッセージングには不十分です。
メッセージが切り詰められる
Slackは40,000文字の制限があります。TelegramやDiscordとは異なり、Triggerfishはメッセージを分割するのではなくSlackメッセージを切り詰めます。この制限に定期的に達する場合は、エージェントにより簡潔な出力を生成するよう依頼することを検討してください。
テストでのSDKリソースリーク
Slack SDKはインポート時に非同期オペレーションをリークします。これは既知のアップストリームの問題です。Slackアダプターを使用するテストには sanitizeResources: false と sanitizeOps: false が必要です。本番環境での使用には影響しません。
Discord
ボットがサーバー内のメッセージを読めない
DiscordにはMessage Content特権インテントが必要です。これがないと、ボットはメッセージイベントを受け取りますがメッセージの内容が空になります。
修正方法: Discord Developer Portalで：
- アプリケーションを選択する
- 「Bot」設定にアクセスする
- Privileged Gateway Intentsの下の「Message Content Intent」を有効にする
- 変更を保存する
必要なボットインテント
アダプターには次のインテントの有効化が必要です：
- Guilds
- Guild Messages
- Direct Messages
- Message Content（特権）
メッセージがチャンク化される
Discordは2,000文字の制限があります。長いメッセージは自動的に複数のメッセージに分割されます。
タイピングインジケーターが失敗する
アダプターはレスポンスの前にタイピングインジケーターを送信します。ボットがチャンネルでメッセージを送信する権限がない場合、タイピングインジケーターはサイレントに失敗します（DEBUGレベルでログに記録）。これはコスメティックなものだけです。
SDKリソースリーク
Slackと同様に、discord.js SDKはインポート時に非同期オペレーションをリークします。テストには sanitizeOps: false が必要です。本番環境には影響しません。
WhatsApp
メッセージが受信されない
WhatsAppはwebhookモデルを使用します。ボットはMetaのサーバーからの受信HTTPのPOSTリクエストを待機します。メッセージが届くようにするには：
- Meta Business DashboardでwebhookのURLを登録する
- 検証トークンを設定する。 アダプターはMetaが最初に接続するときに検証ハンドシェイクを実行します
- webhookリスナーを起動する。 アダプターはデフォルトでポート8443でリッスンします。このポートがインターネットから到達可能であることを確認してください（リバースプロキシまたはトンネルを使用）
「ownerPhone not configured」警告
WhatsAppチャンネル設定で ownerPhone が設定されていない場合、すべての送信者がオーナーとして扱われます。つまり、すべてのユーザーがすべてのツールへのフルアクセスを得られます。これはセキュリティ上の問題です。
修正方法: 設定でオーナーの電話番号を設定します：
yaml
channels:
whatsapp:
ownerPhone: "+1234567890"アクセストークンの有効期限切れ
WhatsApp Cloud APIのアクセストークンは有効期限が切れる場合があります。送信が401エラーで失敗し始めた場合は、Metaダッシュボードでトークンを再生成して更新します：
bash
triggerfish config set-secret whatsapp:accessToken <new-token>Signal
signal-cliが見つからない
SignalチャンネルはサードパーティのJavaアプリケーションである signal-cli を必要とします。Triggerfishはセットアップ中に自動インストールを試みますが、次の場合に失敗することがあります：
- Java（JRE 21+）が利用できず、JRE 25の自動インストールに失敗した
- ダウンロードがネットワーク制限によってブロックされた
- ターゲットディレクトリが書き込み可能でない
手動インストール：
bash
# signal-cliを手動でインストール
# https://github.com/AsamK/signal-cli の手順を参照signal-cliデーモンに到達できない
signal-cliを起動した後、Triggerfishは到達可能になるまで最大60秒待ちます。タイムアウトした場合：
signal-cli daemon (tcp) not reachable within 60s確認事項：
- signal-cliは実際に実行中ですか？
ps aux | grep signal-cliを確認する - 期待されるエンドポイント（TCPソケットまたはUnixソケット）でリッスンしていますか？
- Signalアカウントにリンクが必要ですか？
triggerfish config add-channel signalを実行してリンクプロセスを再実行します。
デバイスのリンクに失敗した
SignalはQRコードを介してデバイスをSignalアカウントにリンクする必要があります。リンクプロセスが失敗した場合：
- スマートフォンにSignalがインストールされていることを確認する
- Signal > 設定 > リンクされたデバイス > 新しいデバイスをリンクを開く
- セットアップウィザードが表示するQRコードをスキャンする
- QRコードの有効期限が切れた場合は、リンクプロセスを再開する
signal-cliのバージョンの不一致
Triggerfishは既知の動作するバージョンのsignal-cliに固定されています。別のバージョンをインストールした場合、警告が表示されることがあります：
Signal CLI version older than known-goodこれは致命的ではありませんが、互換性の問題を引き起こす可能性があります。
Email
IMAP接続の失敗
Emailアダプターは受信メール用のIMAPサーバーに接続します。一般的な問題：
- 認証情報が間違っている。 IMAPのユーザー名とパスワードを確認します。
- ポート993がブロックされている。 アダプターはTLS経由のIMAP（ポート993）を使用します。一部のネットワークはこれをブロックします。
- アプリ固有のパスワードが必要。 Gmailや他のプロバイダーは2FAが有効な場合にアプリ固有のパスワードを要求します。
表示される可能性のあるエラーメッセージ：
IMAP LOGIN failed- ユーザー名またはパスワードが間違っているIMAP connection not established- サーバーに到達できないIMAP connection closed unexpectedly- サーバーが接続を切断した
SMTP送信の失敗
Emailアダプターは（直接SMTPではなく）SMTP APIリレーを介して送信します。送信がHTTPエラーで失敗する場合：
- 401/403: APIキーが無効
- 429: レート制限
- 5xx: リレーサービスが停止している
IMAPポーリングが停止する
アダプターは30秒ごとに新しいメールをポーリングします。ポーリングが失敗した場合、エラーはログに記録されますが自動再接続はありません。デーモンを再起動してIMAPの接続を再確立してください。
これは既知の制限です。既知の問題を参照してください。
WebChat
WebSocketアップグレードが拒否される
WebChatアダプターは受信接続を検証します：
- ヘッダーが大きすぎる（431）。 結合されたヘッダーサイズが8,192バイトを超えています。これは過度に大きなCookieやカスタムヘッダーで発生する可能性があります。
- CORSの拒否。
allowedOriginsが設定されている場合、Originヘッダーが一致する必要があります。デフォルトは["*"]（すべて許可）です。 - 不正なフレーム。 WebSocketフレーム内の無効なJSONはWARNレベルでログに記録され、フレームはドロップされます。
分類
WebChatはデフォルトでPUBLIC分類を使用します。訪問者はオーナーとして扱われません。WebChatにより高い分類が必要な場合は、明示的に設定します：
yaml
channels:
webchat:
classification: INTERNALGoogle Chat
PubSubポーリングの失敗
Google ChatはメッセージDeliveryにPub/Subを使用します。ポーリングが失敗する場合：
Google Chat PubSub poll failed確認事項：
- Google Cloudの認証情報が有効（設定の
credentials_refを確認） - Pub/Subサブスクリプションが存在し削除されていない
- サービスアカウントに
pubsub.subscriberロールがある
グループメッセージが拒否される
グループモードが設定されていない場合、グループメッセージはサイレントにドロップされる可能性があります：
Google Chat group message denied by group modeGoogle ChatチャンネルConfigで defaultGroupMode を設定します。
ownerEmailが設定されていない
ownerEmail がない場合、すべてのユーザーは非オーナーとして扱われます：
Google Chat ownerEmail not configured, defaulting to non-ownerフルのツールアクセスを得るには設定で指定してください。