Filesystem
filesystem チャネルは 1 つ以上のパスを監視し、各変更をエージェントループまたは SOP エンジンに送り込みます。これは channel-filesystem ビルド機能（デフォルトで有効）によって制御されます。
これは SOP イベントソースです。 トリガー構文とパスマッチングについては、SOP Fan-In: Filesystem を参照してください。このページでは、監視対象と安全性のスコーピングについて説明します。
設定
ライブスキーマから導出された完全なフィールドリストです。基本的なウォッチャーでは paths を設定します。
allow_broad_roots
deny-broad-roots のデフォルト設定にかかわらず、広範なシステムルート（/、/home、/etc、/var、/proc、/sys、/dev、/tmp）を監視します。疑似ファイルシステムである /proc と /sys は、SOP ペイロード内にカーネルオブジェクトのパスを露出させ、ウォッチャーをイベントで氾濫させます。明示的に有効化しない限りオフです。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.allow_broad_roots フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.allow_broad_roots フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.allow_broad_roots <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__allow_broad_roots=
debounce_ms
このウィンドウ内でパス/種類ごとに高速に繰り返されるイベントを集約する。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.debounce_ms フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.debounce_ms フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.debounce_ms <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__debounce_ms=
events
発行するイベントの種類 (created, modified, deleted, renamed)。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.events フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.events フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.events <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__events=
exclude
除外するグロブパターン。include の後に適用されます。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.exclude フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.exclude フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.exclude <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__exclude=
excluded_tools
このチャンネルのツール仕様から除外されたツール。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.excluded_tools フィールドを設定します。
zerocode
設定 ペインで、channels.filesystem.<alias>.excluded_tools フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.excluded_tools <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__excluded_tools=
follow_symlinks
イベントパスのメタデータ、ハッシュ、コンテンツを読み取るときにシンボリックリンクを辿ります。デフォルトではオフ: 監視ルート下のシンボリックリンクは、メタデータ/ハッシュ/コンテンツの処理前に拒否されるため、そのターゲットがルートから脱出できません。オンの場合、カノニカルターゲットは設定されたルート内で解決されなければなりません。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.follow_symlinks フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.follow_symlinks フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.follow_symlinks <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__follow_symlinks=
include
含める Glob パターン。空の場合は、ルート下のすべてのパスに一致します。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.include フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.include フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.include <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__include=
max_content_bytes
read_content 時にペイロードへ取り込まれるファイル内容の最大バイト数、およびハッシュ計算のサイズ上限。Some(n) は読み取りとハッシュ計算を n バイトに制限し、サイズ超過のファイルは切り詰めではなくスキップされます。None は上限を完全に解除します（無制限の読み取り）。デフォルトは Some(65536) (64 KiB) で、read_content またはハッシュ計算の実行時にはデフォルトで上限が適用されます。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.max_content_bytes フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.max_content_bytes フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.max_content_bytes <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__max_content_bytes=
paths
監視するルートパス。少なくとも1つが必要です。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.paths フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.paths フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.paths <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__paths=
read_content
ファイルの内容をイベントペイロードに読み込みます。オプトイン方式です。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.read_content フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.read_content フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.read_content <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__read_content=
recursive
各ルート配下のネストされたパスを監視します。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.recursive フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.recursive フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.recursive <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__recursive=
settle_ms
最後のイベントからこの時間だけ待機してからメタデータやコンテンツを読み取り、アトミックな書き込みや遅いコピーが完了するまでの時間を確保します。
任意のサーフェスに設定する場合:
ゲートウェイダッシュボード
/config/channels/filesystem を開き、channels.filesystem.<alias>.settle_ms フィールドを設定します。
zerocode
Config ペインで、channels.filesystem.<alias>.settle_ms フィールドを設定します。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.settle_ms <value>
環境変数
オーバーライドをエクスポートします（POSIXシェル用。~/.bashrc、~/.zshrc、.env、またはDockerfileに記述します）。<alias>を実際のエイリアスに置き換えてください。
export ZEROCLAW_channels__filesystem__<alias>__settle_ms=
完全なフィールドリファレンス: config reference。
監視対象のスコープ設定
paths は監視するルートを列挙します。recursive はサブディレクトリを含めるかどうかを制御します。include と exclude の glob は、どのパスがイベントを発行するかを絞り込み、events は変更の種類で絞り込みます。debounce_ms と settle_ms は、短時間に発生する大量の変更をまとめて 1 つの確定イベントにします。
安全性
システムの広範なルート /、/home、/etc、/var、/proc、/sys、/dev、/tmp は、allow_broad_roots が設定されていない限り、設定の検証時に拒否されます。シンボリックリンクのイベントパスは、デフォルトでメタデータ、ハッシュ、またはコンテンツの読み取り前に拒否されます。follow_symlinks を指定するとこれを許可できますが、正規のターゲットが監視対象ルート内に解決される必要があります。
トラブルシューティング
| 症状 | 考えられる原因 | 修正 |
|---|---|---|
| リスナーが起動しません | 広範なルートは検証時に拒否されました | paths を広いルートから狭めるか、allow_broad_roots を設定してください |
| 変更は無視されました | glob により除外されているか、events の種類の範囲外です | 変更されたファイルに対して include、exclude、および events を確認する |
| SOPが開始しない | trigger path glob がマッチしません | トリガーのpathが一致し、ファイルがウォッチ範囲内にあることを確認する |
関連項目も参照してください
- SOP Fan-In: Filesystem: トリガー構文とパスマッチング
- チャンネルの概要