Filesystem
filesystem 通道监视一个或多个路径，并将每个变更输入到 agent 循环或 SOP 引擎。它受 channel-filesystem 构建特性控制（默认开启）。
这是一个 SOP 事件源。 有关触发语法和路径匹配，请参阅 SOP Fan-In: Filesystem。本页涵盖监视内容和安全作用域。
配置
来自实时 schema 派生的完整字段列表。对于基本 watcher，你设置 paths。
allow_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 shell；可放入 ~/.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 shell；可放入 ~/.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 shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__filesystem__<alias>__events=
exclude
要排除的 Glob 模式。应用于 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 shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__filesystem__<alias>__exclude=
excluded_tools
此通道的工具规范中排除了工具。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/filesystem 并设置 channels.filesystem.<alias>.excluded_tools 字段。
zerocode
在 Config 面板中，设置 channels.filesystem.<alias>.excluded_tools 字段。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.excluded_tools <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__filesystem__<alias>__excluded_tools=
follow_symlinks
读取 event-path 元数据、哈希和内容时跟随符号链接。默认关闭：受监视根目录下的符号链接会在任何元数据/哈希/内容处理之前被拒绝，因此其目标不能逃出根目录。启用后，规范化后的目标仍必须解析到配置的根目录内。
将它放置在任何表面上：
网关仪表板
打开 /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 shell；可放入 ~/.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 shell；可放入 ~/.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 shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__filesystem__<alias>__max_content_bytes=
paths
要监视的根路径。至少需要一个。
将它放置在任何表面上：
网关仪表板
打开 /config/channels/filesystem 并设置 channels.filesystem.<alias>.paths 字段。
zerocode
在 Config 窗格中，设置 channels.filesystem.<alias>.paths 字段。
zeroclaw config
zeroclaw config set channels.filesystem.<alias>.paths <value>
环境变量
导出此覆盖配置（POSIX shell；可放入 ~/.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 shell；可放入 ~/.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 shell；可放入 ~/.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 shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：
export ZEROCLAW_channels__filesystem__<alias>__settle_ms=
完整字段参考：配置参考。
限定监视范围
paths 列出要监视的根路径；recursive 控制是否包含子目录。include 和 exclude 通配符模式用于缩小触发事件的路径范围，而 events 则按变更类型进行筛选。debounce_ms 和 settle_ms 会将一连串快速变更合并为一个稳定事件。
安全
广泛系统根目录 /, /home, /etc, /var, /proc, /sys, /dev 和 /tmp 会在配置验证时被拒绝，除非设置了 allow_broad_roots。默认情况下，符号链接事件路径会在读取任何元数据、哈希或内容之前被拒绝；follow_symlinks 可显式启用，但仍要求规范化后的目标解析到受监视的根目录内。
故障排除
| 症状 | 可能的原因 | 修复 |
|---|---|---|
| 监听器未启动 | 一个宽泛的根在验证时被拒绝了 | 将 paths 从宽泛的根路径移开，或设置 allow_broad_roots |
| 已忽略更改 | 被 glob 排除，或者不在 events kinds 之外 | 检查 include、exclude 和 events 是否与更改的文件匹配 |
| SOP 未启动 | 触发 path glob 不匹配 | 验证 trigger path 是否匹配，并且文件位于监视范围内 |
另见
- SOP Fan-In: Filesystem：触发语法和路径匹配
- 通道概述