SOP ファンイン：概要
fan-in は、SOP の実行を開始する外部イベントソースです。各ソースは dispatch_sop_event を通じて SOP エンジンにイベントを配信し、この関数は読み込まれたすべての SOP のトリガーに対して各イベントを照合し、一致したものの実行を開始します。
1 つの ZeroClaw インスタンスは、複数のファンインを同時にバインドできます。MQTT トピック、ファイルシステムパス、AMQP ルーティングキーがすべて、別々のプロセスなしで同じエンジンにフィードできます。各ソースには以下に専用ガイドがあります。
ディスパッチの仕組み
- 1つのマッチャーパス: 単一のマッチャーがすべてのトリガータイプを評価するため、マッチングはソースに関係なく同じように動作します。
- 実行開始監査: 開始された実行は
SopAuditLoggerを介して永続化されます。 - ヘッドレス時の安全対策: エージェントループ外のコンテキストでは、
process_headless_resultsはExecuteStepアクションを暗黙的に実行せず、保留中として記録します。 - 信頼できない入力: トピックとペイロードのテキストは、モデルコンテキストに到達する前に上限が設定され、正規化され、prompt-guard でスクリーニングされ、フレーム化されます。
ソース
SopTrigger レジストリから直接投影された、すべての SOP トリガータイプ、そのフィールド、およびそのディスパッチステータス:
| タイプ | フィールド | 注釈 |
|---|---|---|
mqtt | expression | MQTTメッセージの到着。ライブ: MQTTリスナーによって配信されます。 |
webhook | path | 受信 HTTP リクエスト。稼働中: ゲートウェイの /sop/* と SOP-first の /webhook ルート。 |
cron | expression | 時間ベースの発火。ライブ: SOP メンテナンスティック（デーモン / チャネル開始パス）によってディスパッチされます。 |
peripheral | 5. 条件構文 | ハードウェア信号。定義されマッチしているが、ペリフェラルリスナーがそれをフィードしていない。 |
filesystem | path、オプションの condition、オプションの events | Filesystem の変更。Live: ファイルシステムウォッチャーによって配信されます。 |
calendar | calendar_source、オプションの calendar_ids、オプションの condition | カレンダーイベントの状態。定義されマッチしているが、ポーラーがライブでフィードしていない。 |
channel | channel、オプションの alias、オプションの condition | 設定済みチャネル (telegram、discord、slack、git、…) 上のインバウンドメッセージまたは forge/プラットフォームイベント。Live: チャネルの SOP ディスパッチが有効なときに、チャネルオーケストレーターによって配信されます。Git forge プロデューサーは <channel>.<alias>:<event_type> 形式のイベントトピックを設定し、ペイロードに event_type を格納するため、作成された condition は 2 つ目のトリガー形状なしで forge イベントをタイプでフィルタリングします。 |
manual | sop_executeツールによってトリガーされます(zeroclaw sop run CLI コマンドではありません)。 | エージェントが sop_execute ツール経由で開始した実行。外部のファンインではありません。 |
amqp | routing_key、オプションの condition | AMQP 配信。ライブ: SOP ディスパッチ モードで AMQP コンシューマーによって配信されます。 |
各ソースにはサイドバーに専用ガイドがあります。ライブソース（実行中のリスナーまたは認証済みゲートウェイリクエストによって配信されるもの）はイベントの到着時に実行を開始します。cronトリガーはデーモンの定期的なSOPメンテナンスティックによってディスパッチされます。エージェントによって開始された実行は、エージェントターン内から sop_execute を介して開始されます。残りの定義済みだが未接続のソース（周辺機器とカレンダー）は検証および照合を行いますが、ディスパッチャーにルーティングされるライブイベントソースはまだありません。
セキュリティのデフォルト設定
| 懸念 | メカニズム |
|---|---|
| Webhook 認証 | Gateway ペアリングのベアラー認証に加えて、オプションの gateway.webhook_secret/X-Webhook-Secret を使用します。/sop/* と /webhook は同じレートリミッターを共有します。SOP ディスパッチ用に少なくとも 1 つの制御を構成し、構成されたすべての制御に合格する必要があります。別個の [channels.webhook] エイリアスシークレットがこれらのルートを認可することはありません |
| Webhook のリプレイ攻撃対策 | オプションの X-Idempotency-Key。SOP パスごとに名前空間が分かれ、/sop/* と /webhook の間でも個別に扱われます。キーはディスパッチ前に予約されるため、試行は高々1回に制限されますが、以前の実行が開始されたことを示すものではありません。 |
| MQTT トランスポート | TLS トランスポート用の use_tls = true を指定した mqtts:// |
| Filesystem ルート | 広範なルート (/, /home, /etc, /var, /proc, /sys, /dev, /tmp) は allow_broad_roots がない限り設定検証で拒否される; include/exclude グロブがイベントをスコープする |
| Filesystem シンボリックリンク | デフォルトでは、シンボリックリンクのイベントパスはメタデータ、ハッシュ、コンテンツの読み取りが行われる前に拒否されます。follow_symlinks = true を指定するとこれを有効にできますが、それでも正規化されたターゲットが監視対象のルート内で解決される必要があります。 |
| 信頼できないトリガー入力 | トピックとペイロードのテキストは、上限の適用、正規化、プロンプトガードによるスクリーニング、フレーミングを経てからモデルコンテキストに渡されます |
| 安全でないトリガーブロック | untrusted_input_guard = "block" は安全でない信頼できないイベントを BlockedUnsafe で拒否します。デフォルトの warn は監査を行い許可します |
| Cron 検証 | 無効な cron 式は、パースおよびキャッシュビルド中にフェールクローズで失敗します |
| ヘッドレスディスパッチ | ヘッドレスの呼び出し元は、ExecuteStep を自動実行する代わりに実行の進行状況をログに記録します |
トラブルシューティング
| 症状 | 考えられる原因 | 修正 |
|---|---|---|
| SOPは決してライブソースから開始しません | トリガーパターンの不一致または condition の失敗 | トリガーパターンが配信されたイベントと一致することを確認します。condition をペイロードと照合してください |
| SOP は開始されましたが、ステップが実行されませんでした | アクティブなエージェントループのないヘッドレストリガー | ExecuteStepのエージェントループを実行するか、承認時に一時停止するよう実行を設計します |
| Webhook トリガーが一度も発火しない | 正確なトリガーパスの不一致、SOP サブシステムの利用不可、または認証の拒否 | sop.sops_dir を設定して zeroclaw daemon を実行し、完全なリクエストパスに正確に一致させ、設定済みの bearer/secret ヘッダーを指定します |
| 周辺機器またはカレンダーのトリガーが一度も発火しない | イベントソースがディスパッチャーに接続されていません | ライブソース（Webhook、MQTT、Filesystem、AMQP）を使用するか、sop_execute で実行を開始します |
| Cron トリガーがまったく実行されない | メンテナンスの定期実行が動作していない（zeroclaw daemon または zeroclaw channel start が実行されていない。単独の gateway start では実行されない）、sops_dir が未設定または空、あるいは maintenance_interval_secs = 0 | sop.sops_dir に空でない値（デフォルトでは未設定。ドキュメントで記載されている値は shared/sops）を設定し、sop.maintenance_interval_secs をゼロ以外（デフォルトは 60）に設定した状態で、zeroclaw daemon（または zeroclaw channel start）を実行します。 |