策略和沙箱

openclaw/plugin-sdk/agent-harness-runtime 向插件暴露的同步策略和沙箱解析原语。属于 插件入口点 参考的一部分。

工具策略术语¶

openclaw/plugin-sdk/agent-harness-runtime 通过 toolPolicy 暴露核心的同步策略原语：

• toolPolicy.expandToolGroups(list?) 规范化工具别名，丢弃空白条目，展开核心组，并按首次出现顺序返回唯一工具 ID。每个展开组的成员遵循该组的目录顺序。
• toolPolicy.createToolPolicyMatcher(policy?, writeAllowsApplyPatch = true) 返回用于工具名称的匹配器。拒绝条目优先，空的允许列表表示不受限制，* 模式和别名使用核心规范化。将第二个参数设置为 false 可禁用运行时兼容性，即允许 write 时也允许 apply_patch。

对于一致性覆盖，请取反使用 { deny: entries } 构建的匹配器；这会使空的覆盖列表保持为 false，并避免允许侧兼容性。为单个同步操作准备匹配器；不要跨等待的工作保留授权决定。

运行时工具允许列表¶

applyEmbeddedAttemptToolsAllow(tools, toolsAllow?, options?) 使用共享的别名、组和通配符匹配来过滤具体的运行时工具。未定义的允许列表保留所有工具；显式空列表禁用它们。每个独立限制都必须允许该工具。

使用 options.toolMeta(tool) 提供其所属的 pluginId，用于插件组匹配。以另一个名称暴露工具的 harness 可以提供 options.toolAliases(tool) 及其接受的策略别名。每个限制可以匹配原始名称或别名；结果保留原始工具对象及其执行包装器。

沙箱绑定解析¶

openclaw/plugin-sdk/agent-harness-runtime 导出 splitSandboxBindSpec(spec, options?)。它返回原始的 { host, container, options } 段，或者在不存在 host/container 分隔符时返回 null。Windows 主机驱动器前缀始终保留。传入 { allowWindowsContainerPath: true } 也可在容器路径中保留驱动器前缀，就像 Policy 对其现有 Windows 绑定语法所做的那样。默认情况下，POSIX 容器解析保持不变。此辅助函数拆分文本；它不会验证或授权挂载。

沙箱文件系统映射¶

由 openclaw/plugin-sdk/agent-harness-runtime 导出的 SandboxContext 通过 fsBridge 暴露其文件系统桥接。该桥接接受可选的只读 pathMappings：来自后端已准备挂载的 { hostRoot, containerRoot } 对。包括 workspace、agent-workspace 和受保护资源投影。容器根声明路径语法：POSIX 根保留字面反斜杠；Windows 驱动器和 UNC 根使用 Windows 包含关系并保留文件名大小写。最深层匹配的根获胜；相等的根使用提供的顺序。

仅 workspace 的文件工具使用这些映射进行准入。桥接操作仍会强制物理边界、挂载可见性和只读策略。提供的空列表不允许任何路径，未匹配的路径永远不会回退到 host-root 准入。省略该属性的旧外部桥接保留 v2026.9.4 中暴露的 host-root 兼容性。新实现应提供映射；移除该兼容性需要一个破坏性 SDK 契约，使该属性成为必需。

目录列表元数据¶

SandboxContext.fsBridge.readDirectory 返回目录条目记录。提供者可以从其 no-follow 目录列表中包括 isFile、size 和 mtimeMs。文件浏览器使用此元数据，无需为每个子项发出额外的 stat 请求；省略其中任何字段的提供者使用基于 stat 的路径。未知文件类型永远不会从 isDirectory 推断。isFile: false 且 isDirectory: false 标识一个条目，例如符号链接，浏览器不应将其视为常规文件。列表元数据从不授予读取条目的权限。文件读取继续强制提供者的路径策略、字节限制和活动的 workspace 绑定。

提供文件类型的配对节点避免逐条目的 stat 请求。对于旧节点，浏览器会跳过 stat 明确拒绝符号链接或不支持文件类型的条目。权限、传输和 workspace 生命周期错误仍会使请求失败。读取期间结构化的 FILE_TOO_LARGE 拒绝会报告为预览限制，包括文件在 stat 之后增长的情况。

会话文件请求在每次 workspace 操作之前以及返回响应之前保留其现有的实时读取授权。撤销会停止后续的 workspace 操作；它无法撤回已分派的操作。