ZeroClaw 插件系统运行机制深度解析加载生命周期、签名策略与沙箱边界【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclawZeroClaw 的插件系统把 WebAssembly 沙箱模块与声明式 manifest 结合为 Agent 主机提供了可插拔的 tool / channel / memory / skill 扩展能力。本篇以 how-plugins-work.md 为骨架从操作者视角完整讲解插件如何被发现、被授权、被加载以及宿主如何在每一层把不受信任的插件限制在既定边界内。读完你将掌握plugins.*全部配置项、五阶段加载流程、Ed25519 签名策略的三种模式以及插件在沙箱中仍然做不到的事——这些知识足以让你安全地运维一个加载第三方插件的生产主机。系统的整体形态沙箱 WebAssembly 模块 manifest在 ZeroClaw 中一个插件由两部分组成一个被沙箱化的 WebAssembly 组件——承载实际逻辑一份 manifest——声明插件是谁、提供什么能力、请求哪些权限。宿主加载插件后读取其声明的能力与权限并且只有在操作者打开插件系统时才会把插件的工具暴露给 Agent。整个设计有一条核心原则插件的任何能力都不是隐式获得的。一个插件最终拿到的恰好等于其 manifest 声明的、且操作者策略允许的那部分除此之外什么都没有。对应的数据结构定义在 crates/zeroclaw-plugins/src/lib.rs 中的PluginManifest包含name、version、wasm_path、capabilities、permissions、config_schema、signature、publisher_key等字段。围绕这个形态系统在每一层都坚持三条不变式默认禁用Disabled by default只要[plugins] enabled不是true插件系统不会加载任何东西。一个没有任何插件配置的默认构建运行时不执行任何插件代码。这一点在配置结构体PluginsConfigcrates/zeroclaw-config/src/schema.rs中体现为enabled: bool字段默认值为false。默认拒绝Deny by default插件要触达某项宿主能力HTTP 出站、配置、内存必须在 manifest 中声明对应的权限。未声明的能力不是暂时没用而是根本不可达。策略验证Verified by policy未签名或不受信任的插件能否被加载是操作者的决定。这个决定在配置中设定一次在发现discovery阶段被统一执行。想要自己动手构建插件官方入口是 插件开发指南对应仓库路径 docs/book/src/plugins/index.md而插件作者需要实现的磁盘契约manifest 字段、桥接导出、宿主函数由 Plugin protocol对应 docs/book/src/developing/plugin-protocol.md定义。插件加载的生命周期五道关卡逐级过滤当运行时构建其工具集时插件加载器按顺序执行以下阶段。一个插件若在较早阶段失败就永远不会进入后续阶段。1. Gate总开关如果[plugins] enabled为false加载器直接什么都不做。这是第一道也是最廉价的检查——它发生在任何目录扫描之前。在配置结构中对应PluginsConfig.enabled字段crates/zeroclaw-config/src/schema.rs。2. Discover发现加载器扫描解析后的插件目录[plugins] plugins_dir默认~/.zeroclaw/plugins/寻找其中包含manifest.toml的子目录。源码层面的扫描逻辑位于 crates/zeroclaw-plugins/src/host.rs 的PluginHost::discover()它遍历插件目录下的每个子目录命中manifest.toml即进入后续校验。需要特别注意的是目录解析统一走PluginsConfig::resolved_plugins_dir()crates/zeroclaw-config/src/schema.rs该函数会展开开头的~并输出绝对路径保证 CLI 安装、运行时发现和网关三处使用同一个位置。3. Validate shape形状校验每份 manifest 必须满足至少声明一种能力capabilities非空非 skill 插件必须提供存在的wasm_path。格式错误的 manifest 会被跳过并告警绝不会被加载。实现上由validate_manifest_shape()crates/zeroclaw-plugins/src/host.rs完成它还会校验wasm_path必须是插件目录内的相对路径——绝对路径、含..、根路径或盘符前缀的路径会被拒绝防止通过plugin_dir.join(p)读写插件目录之外的文件仓库中install_rejects_wasm_path_traversal测试专门覆盖了这一 GHSA 回归场景。此外manifest 中若有[egress]声明表其 host 模式也会在这一阶段按zeroclaw_infra::net_guard的语法校验非法语法直接使整个 manifest 在发现和安装时被拒绝。4. Enforce signature policy签名策略执行每个插件都会对照配置的[plugins.security] signature_mode与trusted_publisher_keys接受检查。未通过策略的插件会被从已加载集合中剔除而不是作为工具浮现出来。详见下文签名策略一节。5. Register tools注册工具存活下来的 tool 插件会被包装成 Agent 工具追加在内置工具之后。这里有几个关键语义工具分发按名字先匹配first-match与内置工具同名的插件工具永远不会被选中因此插件工具必须使用唯一名称自动发现开关tool 与 skill 插件都是auto-discovered的只有[plugins] auto_discover true时才会枚举默认falsefail-closed。也就是说即使enabled true但auto_discover false也不会有任何插件工具或技能被加载但你显式声明在[channels.plugin.alias]下的通道仍会激活。skill 加载器应用同一个auto_discover闸门。在 crates/zeroclaw-plugins/src/host.rs 中可以看到这个发现即过滤的完整流程discover()依次执行形状校验validate_manifest_shape、签名验证verify_plugin_signature、配置 schema 校验validate_manifest_config还会用ambiguous_packages集合拒绝同名重复包——如果同一插件名出现两份 manifest两个都会被拒绝并告警而不是任取其一。签名失败的插件同样只会被跳过不会让整个宿主启动失败。签名阶段是最容易被错误配置的一环值得单独拆开理解。签名策略Ed25519 与三种 enforcement 模式每份插件 manifest 都可以携带一个Ed25519 签名base64url 编码签名者十六进制编码的公钥publisher_key。操作者通过[plugins.security] signature_mode决定签名被强制执行到什么程度模式什么会被加载适用场景disabled所有格式良好的插件无论是否签名针对自己构建插件的本地开发permissive所有格式良好的插件未签名、不受信任、签名无效的插件带告警加载在不停用现有安装的前提下向签名迁移strict只有签名有效且发布者在受信任列表中的插件任何共享或生产主机在strict模式下manifest 的publisher_key必须出现在[plugins.security] trusted_publisher_keys中且签名必须针对规范化的 manifest 字节canonical manifest bytes验证通过。未签名、由不受信任密钥签名、或签名验证失败的插件会在发现阶段被剔除永远不会成为工具。默认模式是disabled这样全新本地检出无需管理密钥即可运行但任何从不被自己控制的来源加载插件的主机都应该运行strict。底层实现位于 crates/zeroclaw-plugins/src/signature.rscanonical_manifest_bytes()用toml_edit解析 manifest精确移除根级的signature与publisher_key两个字段再对剩余内容做规范化去除尾部空行后得到签名字节。嵌套的、恰好也叫这两个名字的 schema 属性仍然保留在签名内容中SignatureMode枚举定义了Strict/Permissive/Disabled三态Disabled是默认值验证结果VerificationResult区分Valid/Unsigned/Untrusted/Invalid四种情况供上层按模式决定放行、告警还是拒绝。需要强调的是签名策略是统一执行的宿主在zeroclaw plugin list时应用的检查与 Agent 运行时构建工具集时应用的检查是同一套同一enforce_signature_policy路径见 crates/zeroclaw-plugins/src/host.rs。因此在strict模式下你看不到的插件Agent 同样调不到。从配置解析侧看PluginSecurityConfigcrates/zeroclaw-config/src/schema.rs默认signature_mode disabled、trusted_publisher_keys为空数组若配置了一个无法识别的模式字符串宿主会记录告警并安全地回退到 strictresolve_signature_mode。能力与权限两个必须区分的概念manifest 声明了两件不同的事而它们的区别至关重要Capabilities能力插件是哪种扩展——tool、channel、memory、observer或skill。tool插件贡献的是 LLM 可以调用的工具。枚举定义在 crates/zeroclaw-plugins/src/lib.rs 的PluginCapabilityTOML 序列化为snake_case它同时决定了插件导出哪个 WIT world。Permissions权限插件的代码在运行时可以触达哪些宿主服务——HTTP 出站、配置、内存。manifest 未声明的权限就是插件无法触达的宿主函数。宿主是按最小粒度授权的PluginPermission枚举同一文件包含http_client、websocket_client、socket_client、file_read、file_write、config_read别名env_read、memory_read、memory_write。但请务必理解声明与执行之间存在差距在当前组件宿主中只有config_read与http_client有行为效果其余变体file_read、file_write、memory_read、memory_write虽然被 manifest schema 接受但尚未接入任何宿主 import——单独声明它们不会授予任何东西只是为将来会管控它们的宿主函数预留了名称。更细致地说请求config_read必须同时提供config_schemaDraft 2020-12 JSON Schema二者缺一即为非法 manifesthttp_client是必要而非充分的授权能力适配器还必须显式构建 HTTP 上下文并链接wasi:http。目前只有 tool 适配器在授权验证后选择接入channel 和 memory 适配器刻意不接入因此即使给它们授予http_client也不会增加任何网络面配置从宿主签发的实例身份解析插件无法选择其他包或绑定也永远不会读取原始进程环境变量。配置参考从 CLI 到默认值所有设置都位于plugins.*配置路径下可以通过任意配置面zerocode、网关或 CLI设置# Master switch. Nothing loads while this is false. zeroclaw config set plugins.enabled true # Load auto-discovered tool and skill plugins at runtime (default: false). # Without this, enabled true activates only explicitly-declared channels. zeroclaw config set plugins.auto_discover true # Where plugins are discovered (default: ~/.zeroclaw/plugins). zeroclaw config set plugins.plugins_dir ~/.zeroclaw/plugins # disabled | permissive | strict zeroclaw config set plugins.security.signature_mode strict # Hex-encoded Ed25519 public keys allowed to publish plugins under strict mode. zeroclaw config set plugins.security.trusted_publisher_keys [a1b2c3d4e5f6...]这些字段在 crates/zeroclaw-config/src/schema.rs 的PluginsConfig中都有对应结构全部通过#[prefix plugins]等前缀注解映射为通用配置路径。除上面五个之外配置结构里还有几个值得了解的字段max_active_instances跨能力准入的逻辑插件实例上限注意是实例而非包——一个同时提供通道绑定和工具的包会消耗两个名额默认值见default_max_active_plugin_instancesplugins.entries操作者给每个插件实例填写的配置条目config是秘密标记的字符串映射在内存中保持为秘密持久化时加密并可配置egress_hosts出站白名单与egress_allow_private私有地址例外plugins.limits每次调用的 WASM 执行限额五个边界全部可由操作者调节且每个值都必须验证为非零crates/zeroclaw-config/src/schema.rs配置项默认值含义plugins.limits.call_fuel1000000000每次调用允许的 wasmtime 指令数fuelplugins.limits.call_timeout_ms30000单次 guest 导出的墙钟截止时间含等待异步宿主 importplugins.limits.max_memory_mb256插件 store 线性内存上限MBplugins.limits.max_table_elements100000store 可分配的表元素上限plugins.limits.max_instances64store 可创建的组件实例上限plugins.limits.max_connections_per_instance16每个逻辑插件实例的存活宿主网络连接上限跨调用计从运行时侧看这些限制被组装进PluginLimitscrates/zeroclaw-plugins/src/component.rs并强制store 只能带着显式限制构建——任何代码路径都无法意外构造出未沙箱化的插件。引擎开启 fuel 计量每次调用给予全新 fuel 预算宿主还会在完整 export future 外包一层墙钟截止时间周期性 fuel 让出保证不间断的 guest 计算无法饿死定时器。被中断的 warm store 永远不会被恢复通道会在下次调用时用宿主持有的输入重建内存实例则在其属主重建前保持不可用。一个务实的主机配置组合是enabled true、signature_mode strict、只列出你信任的trusted_publisher_keys若还需要自动发现的 tool/skill 插件再额外设置auto_discover true。只运行自己构建的插件时开发期可以保持signature_mode的disabled默认值在共享宿主前再收紧。插件仍然做不到的事沙箱边界的硬约束即使授予了所有权限沙箱仍然把插件限制在确定边界内无环境访问插件作为 WebAssembly 模块运行没有对宿主进程或根目录工作区之外文件系统的任何环境访问权。WASI 上下文没有 preopens、没有环境网络因此插件无法打开原始 socket 或通过环境 WASI 读取宿主文件。网络出口由 HTTP 权限门控而 SSRF 防护的出站边界本身由配套的插件加固工作交付本页聚焦签名策略边界。从插件主机源码看每个 store 的WasiCtx都以无 preopens、无网络构建crates/zeroclaw-plugins/src/component.rs。作用域内的秘密读取受信任的 tool 或 channel 插件可以在被授权的服务调用期间通过其作用域内的secrets.getimport 读取 schema 指定的秘密明文。工具在execute期间获得访问通道在configure与运营调用期间获得config.get与secrets.get单次调用内的读取使用同一个规范修订版因此同绑定的公/私配置轮换会在下一次操作时一起生效。实例化与静态元数据发现不能使用这两个 import。宿主能阻止公开配置注入与跨实例选择但一个返回明文的 import 无法阻止恶意的 guest 保留它读到的东西——因此合规的通道插件必须在每个使用点解析配置与凭据而不是缓存。不能取代内置工具内置工具先注册工具分发按名字先匹配因此撞名的插件工具永远不会被选中。除此之外宿主还有一重硬性的服务调用预算ZeroClaw 自有的 WIT import 共享每个宿主分发服务帧内的固定安全预算上限是MAX_HOST_CALLS_PER_FRAMEcrates/zeroclaw-plugins/src/component.rs中的常量值为 1000。预算耗尽后日志变成 no-op、入站轮询报告为空、公开配置或秘密读取返回unavailable新的一帧会重置预算。这是固定的宿主策略不需要操作者重复配置。需要清醒认识到的一点是沙箱与命名空间边界无论插件代码尝试什么都成立但不留存秘密规则属于受信任通道插件的契约义务——这正是发布者审查与签名策略仍然重要的原因。你可以通过阅读 crates/zeroclaw-plugins/tests/tool_plugin_e2e.rs 与 crates/zeroclaw-plugins/tests/reference_plugin_e2e.rs 看到宿主如何用端到端夹具在测试时从源码构建wasm32-wasip2组件验证真实加载、配置解析与秘密服务路径。小结ZeroClaw 的插件系统用默认禁用、默认拒绝、策略验证三条不变式把第三方代码的信任半径压缩到最小总开关决定系统是否激活形状校验保证 manifest 结构合法Ed25519 签名策略决定谁有资格被加载能力/权限分离决定插件运行时的触达面而每帧的 fuel、墙钟、内存与宿主调用预算共同保证即使代码失控也只能在沙箱内徒劳。对于操作者最核心的落地动作就是把enabled、signature_mode、trusted_publisher_keys以及按需的auto_discover组合成与威胁模型匹配的配置并理解disabled只是本地开发的便利不是生产主机的默认安全姿态。进一步阅读插件协议磁盘契约、WIT 接口、宿主 import插件开发指南配置参考含plugins.*规范字段与默认值插件宿主实现插件 manifest 与权限枚举插件签名实现插件配置 schema【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZeroClaw 插件系统运行机制深度解析：加载生命周期、签名策略与沙箱边界
ZeroClaw 插件系统运行机制深度解析加载生命周期、签名策略与沙箱边界【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclawZeroClaw 的插件系统把 WebAssembly 沙箱模块与声明式 manifest 结合为 Agent 主机提供了可插拔的 tool / channel / memory / skill 扩展能力。本篇以 how-plugins-work.md 为骨架从操作者视角完整讲解插件如何被发现、被授权、被加载以及宿主如何在每一层把不受信任的插件限制在既定边界内。读完你将掌握plugins.*全部配置项、五阶段加载流程、Ed25519 签名策略的三种模式以及插件在沙箱中仍然做不到的事——这些知识足以让你安全地运维一个加载第三方插件的生产主机。系统的整体形态沙箱 WebAssembly 模块 manifest在 ZeroClaw 中一个插件由两部分组成一个被沙箱化的 WebAssembly 组件——承载实际逻辑一份 manifest——声明插件是谁、提供什么能力、请求哪些权限。宿主加载插件后读取其声明的能力与权限并且只有在操作者打开插件系统时才会把插件的工具暴露给 Agent。整个设计有一条核心原则插件的任何能力都不是隐式获得的。一个插件最终拿到的恰好等于其 manifest 声明的、且操作者策略允许的那部分除此之外什么都没有。对应的数据结构定义在 crates/zeroclaw-plugins/src/lib.rs 中的PluginManifest包含name、version、wasm_path、capabilities、permissions、config_schema、signature、publisher_key等字段。围绕这个形态系统在每一层都坚持三条不变式默认禁用Disabled by default只要[plugins] enabled不是true插件系统不会加载任何东西。一个没有任何插件配置的默认构建运行时不执行任何插件代码。这一点在配置结构体PluginsConfigcrates/zeroclaw-config/src/schema.rs中体现为enabled: bool字段默认值为false。默认拒绝Deny by default插件要触达某项宿主能力HTTP 出站、配置、内存必须在 manifest 中声明对应的权限。未声明的能力不是暂时没用而是根本不可达。策略验证Verified by policy未签名或不受信任的插件能否被加载是操作者的决定。这个决定在配置中设定一次在发现discovery阶段被统一执行。想要自己动手构建插件官方入口是 插件开发指南对应仓库路径 docs/book/src/plugins/index.md而插件作者需要实现的磁盘契约manifest 字段、桥接导出、宿主函数由 Plugin protocol对应 docs/book/src/developing/plugin-protocol.md定义。插件加载的生命周期五道关卡逐级过滤当运行时构建其工具集时插件加载器按顺序执行以下阶段。一个插件若在较早阶段失败就永远不会进入后续阶段。1. Gate总开关如果[plugins] enabled为false加载器直接什么都不做。这是第一道也是最廉价的检查——它发生在任何目录扫描之前。在配置结构中对应PluginsConfig.enabled字段crates/zeroclaw-config/src/schema.rs。2. Discover发现加载器扫描解析后的插件目录[plugins] plugins_dir默认~/.zeroclaw/plugins/寻找其中包含manifest.toml的子目录。源码层面的扫描逻辑位于 crates/zeroclaw-plugins/src/host.rs 的PluginHost::discover()它遍历插件目录下的每个子目录命中manifest.toml即进入后续校验。需要特别注意的是目录解析统一走PluginsConfig::resolved_plugins_dir()crates/zeroclaw-config/src/schema.rs该函数会展开开头的~并输出绝对路径保证 CLI 安装、运行时发现和网关三处使用同一个位置。3. Validate shape形状校验每份 manifest 必须满足至少声明一种能力capabilities非空非 skill 插件必须提供存在的wasm_path。格式错误的 manifest 会被跳过并告警绝不会被加载。实现上由validate_manifest_shape()crates/zeroclaw-plugins/src/host.rs完成它还会校验wasm_path必须是插件目录内的相对路径——绝对路径、含..、根路径或盘符前缀的路径会被拒绝防止通过plugin_dir.join(p)读写插件目录之外的文件仓库中install_rejects_wasm_path_traversal测试专门覆盖了这一 GHSA 回归场景。此外manifest 中若有[egress]声明表其 host 模式也会在这一阶段按zeroclaw_infra::net_guard的语法校验非法语法直接使整个 manifest 在发现和安装时被拒绝。4. Enforce signature policy签名策略执行每个插件都会对照配置的[plugins.security] signature_mode与trusted_publisher_keys接受检查。未通过策略的插件会被从已加载集合中剔除而不是作为工具浮现出来。详见下文签名策略一节。5. Register tools注册工具存活下来的 tool 插件会被包装成 Agent 工具追加在内置工具之后。这里有几个关键语义工具分发按名字先匹配first-match与内置工具同名的插件工具永远不会被选中因此插件工具必须使用唯一名称自动发现开关tool 与 skill 插件都是auto-discovered的只有[plugins] auto_discover true时才会枚举默认falsefail-closed。也就是说即使enabled true但auto_discover false也不会有任何插件工具或技能被加载但你显式声明在[channels.plugin.alias]下的通道仍会激活。skill 加载器应用同一个auto_discover闸门。在 crates/zeroclaw-plugins/src/host.rs 中可以看到这个发现即过滤的完整流程discover()依次执行形状校验validate_manifest_shape、签名验证verify_plugin_signature、配置 schema 校验validate_manifest_config还会用ambiguous_packages集合拒绝同名重复包——如果同一插件名出现两份 manifest两个都会被拒绝并告警而不是任取其一。签名失败的插件同样只会被跳过不会让整个宿主启动失败。签名阶段是最容易被错误配置的一环值得单独拆开理解。签名策略Ed25519 与三种 enforcement 模式每份插件 manifest 都可以携带一个Ed25519 签名base64url 编码签名者十六进制编码的公钥publisher_key。操作者通过[plugins.security] signature_mode决定签名被强制执行到什么程度模式什么会被加载适用场景disabled所有格式良好的插件无论是否签名针对自己构建插件的本地开发permissive所有格式良好的插件未签名、不受信任、签名无效的插件带告警加载在不停用现有安装的前提下向签名迁移strict只有签名有效且发布者在受信任列表中的插件任何共享或生产主机在strict模式下manifest 的publisher_key必须出现在[plugins.security] trusted_publisher_keys中且签名必须针对规范化的 manifest 字节canonical manifest bytes验证通过。未签名、由不受信任密钥签名、或签名验证失败的插件会在发现阶段被剔除永远不会成为工具。默认模式是disabled这样全新本地检出无需管理密钥即可运行但任何从不被自己控制的来源加载插件的主机都应该运行strict。底层实现位于 crates/zeroclaw-plugins/src/signature.rscanonical_manifest_bytes()用toml_edit解析 manifest精确移除根级的signature与publisher_key两个字段再对剩余内容做规范化去除尾部空行后得到签名字节。嵌套的、恰好也叫这两个名字的 schema 属性仍然保留在签名内容中SignatureMode枚举定义了Strict/Permissive/Disabled三态Disabled是默认值验证结果VerificationResult区分Valid/Unsigned/Untrusted/Invalid四种情况供上层按模式决定放行、告警还是拒绝。需要强调的是签名策略是统一执行的宿主在zeroclaw plugin list时应用的检查与 Agent 运行时构建工具集时应用的检查是同一套同一enforce_signature_policy路径见 crates/zeroclaw-plugins/src/host.rs。因此在strict模式下你看不到的插件Agent 同样调不到。从配置解析侧看PluginSecurityConfigcrates/zeroclaw-config/src/schema.rs默认signature_mode disabled、trusted_publisher_keys为空数组若配置了一个无法识别的模式字符串宿主会记录告警并安全地回退到 strictresolve_signature_mode。能力与权限两个必须区分的概念manifest 声明了两件不同的事而它们的区别至关重要Capabilities能力插件是哪种扩展——tool、channel、memory、observer或skill。tool插件贡献的是 LLM 可以调用的工具。枚举定义在 crates/zeroclaw-plugins/src/lib.rs 的PluginCapabilityTOML 序列化为snake_case它同时决定了插件导出哪个 WIT world。Permissions权限插件的代码在运行时可以触达哪些宿主服务——HTTP 出站、配置、内存。manifest 未声明的权限就是插件无法触达的宿主函数。宿主是按最小粒度授权的PluginPermission枚举同一文件包含http_client、websocket_client、socket_client、file_read、file_write、config_read别名env_read、memory_read、memory_write。但请务必理解声明与执行之间存在差距在当前组件宿主中只有config_read与http_client有行为效果其余变体file_read、file_write、memory_read、memory_write虽然被 manifest schema 接受但尚未接入任何宿主 import——单独声明它们不会授予任何东西只是为将来会管控它们的宿主函数预留了名称。更细致地说请求config_read必须同时提供config_schemaDraft 2020-12 JSON Schema二者缺一即为非法 manifesthttp_client是必要而非充分的授权能力适配器还必须显式构建 HTTP 上下文并链接wasi:http。目前只有 tool 适配器在授权验证后选择接入channel 和 memory 适配器刻意不接入因此即使给它们授予http_client也不会增加任何网络面配置从宿主签发的实例身份解析插件无法选择其他包或绑定也永远不会读取原始进程环境变量。配置参考从 CLI 到默认值所有设置都位于plugins.*配置路径下可以通过任意配置面zerocode、网关或 CLI设置# Master switch. Nothing loads while this is false. zeroclaw config set plugins.enabled true # Load auto-discovered tool and skill plugins at runtime (default: false). # Without this, enabled true activates only explicitly-declared channels. zeroclaw config set plugins.auto_discover true # Where plugins are discovered (default: ~/.zeroclaw/plugins). zeroclaw config set plugins.plugins_dir ~/.zeroclaw/plugins # disabled | permissive | strict zeroclaw config set plugins.security.signature_mode strict # Hex-encoded Ed25519 public keys allowed to publish plugins under strict mode. zeroclaw config set plugins.security.trusted_publisher_keys [a1b2c3d4e5f6...]这些字段在 crates/zeroclaw-config/src/schema.rs 的PluginsConfig中都有对应结构全部通过#[prefix plugins]等前缀注解映射为通用配置路径。除上面五个之外配置结构里还有几个值得了解的字段max_active_instances跨能力准入的逻辑插件实例上限注意是实例而非包——一个同时提供通道绑定和工具的包会消耗两个名额默认值见default_max_active_plugin_instancesplugins.entries操作者给每个插件实例填写的配置条目config是秘密标记的字符串映射在内存中保持为秘密持久化时加密并可配置egress_hosts出站白名单与egress_allow_private私有地址例外plugins.limits每次调用的 WASM 执行限额五个边界全部可由操作者调节且每个值都必须验证为非零crates/zeroclaw-config/src/schema.rs配置项默认值含义plugins.limits.call_fuel1000000000每次调用允许的 wasmtime 指令数fuelplugins.limits.call_timeout_ms30000单次 guest 导出的墙钟截止时间含等待异步宿主 importplugins.limits.max_memory_mb256插件 store 线性内存上限MBplugins.limits.max_table_elements100000store 可分配的表元素上限plugins.limits.max_instances64store 可创建的组件实例上限plugins.limits.max_connections_per_instance16每个逻辑插件实例的存活宿主网络连接上限跨调用计从运行时侧看这些限制被组装进PluginLimitscrates/zeroclaw-plugins/src/component.rs并强制store 只能带着显式限制构建——任何代码路径都无法意外构造出未沙箱化的插件。引擎开启 fuel 计量每次调用给予全新 fuel 预算宿主还会在完整 export future 外包一层墙钟截止时间周期性 fuel 让出保证不间断的 guest 计算无法饿死定时器。被中断的 warm store 永远不会被恢复通道会在下次调用时用宿主持有的输入重建内存实例则在其属主重建前保持不可用。一个务实的主机配置组合是enabled true、signature_mode strict、只列出你信任的trusted_publisher_keys若还需要自动发现的 tool/skill 插件再额外设置auto_discover true。只运行自己构建的插件时开发期可以保持signature_mode的disabled默认值在共享宿主前再收紧。插件仍然做不到的事沙箱边界的硬约束即使授予了所有权限沙箱仍然把插件限制在确定边界内无环境访问插件作为 WebAssembly 模块运行没有对宿主进程或根目录工作区之外文件系统的任何环境访问权。WASI 上下文没有 preopens、没有环境网络因此插件无法打开原始 socket 或通过环境 WASI 读取宿主文件。网络出口由 HTTP 权限门控而 SSRF 防护的出站边界本身由配套的插件加固工作交付本页聚焦签名策略边界。从插件主机源码看每个 store 的WasiCtx都以无 preopens、无网络构建crates/zeroclaw-plugins/src/component.rs。作用域内的秘密读取受信任的 tool 或 channel 插件可以在被授权的服务调用期间通过其作用域内的secrets.getimport 读取 schema 指定的秘密明文。工具在execute期间获得访问通道在configure与运营调用期间获得config.get与secrets.get单次调用内的读取使用同一个规范修订版因此同绑定的公/私配置轮换会在下一次操作时一起生效。实例化与静态元数据发现不能使用这两个 import。宿主能阻止公开配置注入与跨实例选择但一个返回明文的 import 无法阻止恶意的 guest 保留它读到的东西——因此合规的通道插件必须在每个使用点解析配置与凭据而不是缓存。不能取代内置工具内置工具先注册工具分发按名字先匹配因此撞名的插件工具永远不会被选中。除此之外宿主还有一重硬性的服务调用预算ZeroClaw 自有的 WIT import 共享每个宿主分发服务帧内的固定安全预算上限是MAX_HOST_CALLS_PER_FRAMEcrates/zeroclaw-plugins/src/component.rs中的常量值为 1000。预算耗尽后日志变成 no-op、入站轮询报告为空、公开配置或秘密读取返回unavailable新的一帧会重置预算。这是固定的宿主策略不需要操作者重复配置。需要清醒认识到的一点是沙箱与命名空间边界无论插件代码尝试什么都成立但不留存秘密规则属于受信任通道插件的契约义务——这正是发布者审查与签名策略仍然重要的原因。你可以通过阅读 crates/zeroclaw-plugins/tests/tool_plugin_e2e.rs 与 crates/zeroclaw-plugins/tests/reference_plugin_e2e.rs 看到宿主如何用端到端夹具在测试时从源码构建wasm32-wasip2组件验证真实加载、配置解析与秘密服务路径。小结ZeroClaw 的插件系统用默认禁用、默认拒绝、策略验证三条不变式把第三方代码的信任半径压缩到最小总开关决定系统是否激活形状校验保证 manifest 结构合法Ed25519 签名策略决定谁有资格被加载能力/权限分离决定插件运行时的触达面而每帧的 fuel、墙钟、内存与宿主调用预算共同保证即使代码失控也只能在沙箱内徒劳。对于操作者最核心的落地动作就是把enabled、signature_mode、trusted_publisher_keys以及按需的auto_discover组合成与威胁模型匹配的配置并理解disabled只是本地开发的便利不是生产主机的默认安全姿态。进一步阅读插件协议磁盘契约、WIT 接口、宿主 import插件开发指南配置参考含plugins.*规范字段与默认值插件宿主实现插件 manifest 与权限枚举插件签名实现插件配置 schema【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考