安全模型

ZeroClaw 的安全模型在运行时控制代理被允许执行的操作。共有六层，从外到内依次为：

通道配对与访问控制

在来自某个通道的消息到达代理之前，系统会检查该通道的配对和允许列表。allowed_users、allowed_chats 以及 webhook 的 IP 允许列表，全部在通道适配器层强制执行，早于运行时看到该事件。

文档：每个频道页面位于 频道 下。

自主级别

粗粒度旋钮。三个设置：

• ReadOnly：智能体可以观察（读取文件、查询内存、获取允许获取的 URL），但无法写入或执行命令。
• 监督（默认）：低风险操作直接执行；中风险操作询问操作员；高风险操作阻止。
• Full：无审批关卡；workspace_only 被隐式禁用。forbidden_paths、forbidden_commands 和操作系统沙箱仍然强制生效。

文档：自主级别。

工作区边界和路径规则

代理在配置的工作区目录中运行。除非设置 workspace_only = false，否则 file_read、file_write 和 shell（用于操作文件系统的命令）将拒绝访问该目录之外的路径。

按会话隔离的沙箱根目录（ACP 和网关 WebSocket）： 当通过 ACP（带 cwd 参数的 session/new）或通过网关 WebSocket（连接时的 cwd 参数）打开会话时，该路径将在会话的整个生命周期内，成为所有文件和 shell 工具的 SecurityPolicy 工作区边界。守护进程的全局 workspace_dir 仍作为内存、身份、cron 和其他持久状态的数据目录。其模型为：session cwd = 代理可访问的项目边界；workspace_dir = ZeroClaw 存储自身文件的位置。注意：代理的系统提示词目前反映的是守护进程的 workspace_dir，而非会话的 cwd；强制执行是正确的，但模型自报的位置可能有所不同。

重要： cwd 参数会更改 agent 在 ZeroClaw 主机上被沙箱限制到的目录，它不会影响工具在哪台机器上运行。工具使用（shell 命令、文件读写）始终在运行 ZeroClaw 的机器上执行。如果你通过 gateway WebSocket 连接到远程 ZeroClaw 实例，工具调用将操作远程机器的文件系统，而不是你本地机器的文件系统。对于仅限 localhost 的部署，这种区别无关紧要，但远程部署应当考虑到这一点。

除工作区之外，forbidden_paths 的默认值还包括 /etc、/sys、/boot、~/.ssh 以及其他敏感根路径。绝对路径的允许项和禁止项采用组件前缀特异性：匹配到的最具体条目优先；深度相同时，禁止项优先。这样，嵌套的禁止子树可以阻止工作区或允许根路径中的一部分，同时不会让诸如 /home 这样的宽泛默认值覆盖操作员配置的更具体允许项。

Shell 命令策略

对于 shell 调用：

• allowed_commands：如果非空，shell 仅运行其基本名称在此列表中的命令
• forbidden_commands：明确的拒绝列表（rm -rf /、shutdown、内核操作）
• validate_command_execution：一种模式匹配检查，用于查找危险的标志、管道和参数形式

验证器在命令执行到 shell 之前运行。被阻止的命令会作为工具错误呈现给模型，模型可以对此做出反应。

操作系统级沙箱

当有沙箱后端可用时，工具调用将在其中运行：

沙箱将文件系统访问限制在工作区范围内，仅保留工具明确需要的网络可达性，并移除对父进程密钥的访问权限。

文档：沙箱化。

工具收据

工具回执提供 HMAC 证据，证明一次成功的工具调用及其结果已通过运行时。启用回执后，成功的工具输出会对调用和结果接收 HMAC-SHA256 回执，并且该回执会与工具结果一起反馈回对话中。

收据有助于识别伪造的工具声明。它们目前并不是链式或持久的审计日志：收据密钥是临时的，收据没有与对话哈希进行交叉签名，持久化收据存储仍是未来的工作。

文档：工具收据。

附加门

超越这六层：

• OTP 门控：[security.otp] gated_actions = ["shell", "browser", "file_write"] 要求在执行每个列出的操作前输入一次性验证码。适用于远程访问场景。
• 紧急停止：zeroclaw estop 会终止所有正在执行的工具调用。当 [security.estop] enabled = true 时，恢复操作需要 OTP。
• 提示注入防护：在校验工具调用之前，扫描模型输出中是否存在已知的注入模式。
• 泄漏检测器：扫描外发通道响应中的凭据，并在发送前对匹配项进行脱敏。它覆盖确定性的凭据模式，也可以运行独立的高熵令牌启发式检测。
• 配对防护：用于通道认证的设备配对；可防止被盗用的凭据在新设备上生效。

泄漏检测器配置

在其自己的 TOML 部分中配置出站泄漏检测：

[security.leak_detection]
enabled = true
sensitivity = 0.7
high_entropy_tokens = true

enabled = false 会禁用整个出站泄漏检测器。high_entropy_tokens = false 只会禁用独立的熵启发式；确定性的凭据模式仍会运行。sensitivity 接受 0.0 到 1.0；数值越高越激进。

完整的字段表和默认值在 Config reference 中。

当出现问题时

被阻止的工具调用不会静默失败：

1. 安全验证器返回错误
2. 运行时将其包装为 ToolResult::Err 并返回给模型
3. 模型看到“错误：Shell 命令被策略阻止：禁止的模式 rm -rf /”，可以重试、道歉或询问用户

如果某个工具通过 [autonomy].non_cli_excluded_tools 从通道中被排除（该配置将非 CLI 通道作为一个整体进行管控），那么它就不会在这些通道上向模型公布。模型永远不会看到自己无法使用的工具。

默认姿势

开箱即用：

• 自主性：监督
• 仅工作区：true
• 沙盒：自动检测（使用操作系统提供的功能）
• 审计日志记录：false（显式启用）
• OTP：false
• 急停：false

这是一个合理的折中方案，对于笔记本电脑来说足够安全，又足够宽松而不会让人感到沮丧。在生产环境中可以调高设置（OTP、审计、受限工具），或者在开发机上调低到 YOLO。