ZeroClaw 插件系统与开发者工具链完全指南WASM 沙箱协议、签名策略与内置工具清单【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclawZeroClaw 的插件系统允许在不触碰核心二进制的前提下为 Agent 增加能力插件以 WebAssembly 组件wasm32-wasip2 TOML 清单的形式驻留在安装目录由宿主wasmtime以无文件系统、无网络环境的 WASI 上下文加载并通过 WIT 接口与运行时原生 trait 无缝对接。本文以 docs/book/src/developing/index.md 为骨架完整讲解插件的工作原理、协议契约、签名策略、配置命令、内置工具分类以及文档与 Web Dashboard 的本地构建流程读者读完后既能以运维视角安全地装载第三方插件也能以作者视角从空 crate 写出一个可被模型调用的工具插件。开发者文档导航developing 章节的定位docs/book/src/developing/index.md是 ZeroClaw 文档中面向插件系统与项目工具链工作的入口页。它明确划分了两类读者插件使用者operator阅读 How plugins work了解插件如何被发现、被允许做什么、宿主如何约束不受信任的插件插件作者与协议实现者阅读 Plugin protocol掌握磁盘上的契约manifest 字段、WIT 导出、host 函数决策者阅读 Built-in tool inventory判断某个工具应留在核心、加 feature 门控、还是外部化为插件/技能包/MCP/CLI 集成工具链贡献者阅读 Building the docs locally 与 Building the web dashboard。而逐步骤的插件编写实战则位于 docs/book/src/plugins/index.md按工具插件 → 通道插件 → 内存插件 → 分发的难度递进。为什么是 WebAssembly四个不可替代的性质插件运行在持有你的 API 密钥、对话历史与 shell 访问权限的进程内隔离边界必须是真实的而非劝告性的。ZeroClaw 采用wasmtime上的 WASI Component Model因为它同时具备动态库或子进程方案无法兼备的四个性质见 插件总览基于能力的沙箱Capability-based sandboxingWebAssembly 组件没有环境固有权限。它不能打开文件、套接字或环境变量除非宿主显式把该能力接入 linker。ZeroClaw 宿主为每个插件 store 构造的 WASI 上下文没有任何文件系统 preopen、也没有网络PluginState位于crates/zeroclaw-plugins/src/component.rs。插件能触达的范围恰好等于其 world 声明的宿主导入集合加上其 manifest 权限声明的内容除此之外一无所有。可计量的执行Metered execution引擎开启 fuel 计量每次调用获得全新 fuel 预算外加包含宿主异步工作的墙钟截止时间。无限循环或无限等待的插件会失败无法挂起 Agent。内存、表与实例上限由 store limiter 强制全部五个上限来自运维配置plugins.limits.*且校验为非零——无法构造不设限的 store因此不存在任何能产生非沙箱插件的加载路径。类型化、语言无关的 ABI宿主与插件之间的契约是一组 WIT 接口文件仓库wit/v0/而非 Rust API。宿主用 wasmtime 的bindgen!从这些文件生成绑定插件用wit-bindgenRust或任何能编译成wasm32-wasip2组件的语言的等价工具生成镜像 guest 绑定。记录、变体、结果与 option 类型跨边界时类型保持完整。与内置行为完全一致每种插件都被适配到一方实现所用的同一个 Rust trait 上——工具插件成为Toolcrates/zeroclaw-plugins/src/wasm_tool.rs通道插件成为Channelwasm_channel.rs内存插件成为Memorywasm_memory.rs。Agent 循环、归因、回执与安全策略看不出任何差别。插件的构成manifest 与 WASM 组件磁盘上的一个插件是包含一份 manifest 与一个已编译组件的目录~/.zeroclaw/plugins/ └── my-plugin/ ├── manifest.toml # identity、capabilities、permissions、signature └── my-plugin.wasm # wasm32-wasip2 componentmanifest 声明两件正交的事Capabilities能力插件是什么。取值tool、channel、memory、observer、skill中的一个或多个PluginCapability枚举定义于crates/zeroclaw-plugins/src/lib.rs。每个 WASM 能力选择组件必须导出的 WIT world。skill是特例它标记的是搭乘安装机制的 markdown 技能包而非代码因此不需要组件。Permissions权限插件代码可触达哪些宿主服务同一文件的PluginPermission枚举。目前config_read与http_client有实际行为效果其余file_read、file_write、memory_read、memory_write虽被 schema 接受但尚无宿主函数支撑声明它们不会授予任何东西。manifest 字段速查manifest 字段是PluginManifestcrates/zeroclaw-plugins/src/lib.rs的 serde 表面以下为字段契约完整版见 plugin-manifest-fields 片段字段必填含义name是唯一规范包 slug也是每个派生实例配置键的包组成部分。1–128 个小写 ASCII 字符以[a-z0-9]开头结尾中间仅允许[a-z0-9._-]重复或非法名字在发现阶段被拒绝version是版本字符串如0.1.0description否zeroclaw plugin list展示的人类可读描述author否作者名或组织wasm_pathWASM 能力必填相对插件目录的组件文件名。仅当唯一能力是skill时可省略文件不存在则跳过该插件capabilities是非空tool/channel/memory/observer/skillpermissions否http_client、config_read、file_read、file_write、memory_read、memory_write。仅前两者当前被强制声明config_read必须同时提供config_schemaconfig_schema与config_read严格配对Draft 2020-12 JSON Schema属于被签名覆盖的 canonical manifest 字节signature否对 canonical manifest 字节的 base64url Ed25519 签名publisher_key否签名者的十六进制 Ed25519 公钥只声明代码实际用到的权限未声明的权限是不可触达的宿主表面多余声明的权限则是你主动要求的攻击面。插件加载生命周期运行时构建工具集时加载器按顺序经过以下阶段前一阶段失败的插件永远不会进入后一阶段How plugins workGate闸门[plugins] enabled为 false 则加载器什么都不做。这是最先且最廉价的检查。Discover发现扫描解析后的插件目录[plugins] plugins_dir默认~/.zeroclaw/plugins/寻找含manifest.toml的子目录。Validate shape形状校验每个 manifest 必须声明至少一个能力非 skill 插件必须给出存在的wasm_path。畸形 manifest 被警告后跳过绝不被加载。Enforce signature policy签名策略依据[plugins.security] signature_mode与trusted_publisher_keys检查每个插件。未通过策略的插件从加载集合中剔除不会作为工具浮出。Register tools注册工具幸存的工具插件被包装为 Agent 工具追加在内置工具之后。工具分发按名字 first-match因此与内置工具重名的插件工具永远不会被选中——给插件工具起唯一的名字。工具与技能插件是自动发现的只有[plugins] auto_discover true默认falsefail-closed时才会枚举enabled true但auto_discover false时不会加载任何插件工具或技能不过[channels.plugin.alias]下显式声明的通道仍然激活。签名策略三种模式每个 manifest 可携带 Ed25519 签名与签名者十六进制公钥运维通过[plugins.security] signature_mode决定强制程度模式加载什么适用场景disabled所有格式良好的插件无论是否签名对自己构建的插件做本地开发permissive所有格式良好的插件未签名、不受信任与无效签名带警告加载在向签名迁移且不破坏既有安装时strict仅加载来自受信任发布者且签名有效的插件任何共享或生产宿主strict模式下manifest 的publisher_key必须出现在[plugins.security] trusted_publisher_keys中且签名必须对 canonical manifest 字节验证通过。默认是disabled这样全新本地检出无需密钥管理即可运行但任何加载不受你控制插件的宿主都应运行strict。该策略在列出插件与构建工具集两个路径上统一强制strict模式下你看不到的插件Agent 同样无法调用。WIT 世界与协议契约wit/v0/为每个 WASM 能力定义一个 world包名为zeroclaw:plugin0.1.0全部条目在稳定前都带unstable(feature plugins-wit-v0)门控。每个 world 都导入宿主logging接口log-record事件落入携带宿主调用点 span 归因的结构化日志并导出plugin-info自报名称与版本加主接口World导出store 生命周期tool-plugintoolname、description、parameters-schema、execute每次execute新建 store导入作用域化secretschannel-pluginchannelconfigure、send、poll-message 及按能力门控的方法async mutex 保护的温 store每次调用重新加 fuel导入作用域化config、secrets与宿主投喂的inboundmemory-pluginmemorystore、recall、get、forget 及能力门控方法async mutex 保护的温 store每次调用重新加 fuel通道与内存 world 使用能力标志capability flags宿主在加载时读取一次位掩码get-channel-capabilities/get-memory-capabilities。对每个未设置的标志宿主使用 Rust trait 默认实现绝不调用插件的导出。这正是 WIT 契约保持可加性的方式新的可选方法 新标志 新函数而不是破坏性变更。tool 接口wit/v0/tool.wit定义单工具表面。宿主在加载时调用name、description、parameters-schema一次之后每次调用分发executerecord tool-result { success: bool, output: string, error: optionstring, } name: func() - string; description: func() - string; parameters-schema: func() - json-string; execute: func(args: json-string) - resulttool-result, string;parameters-schema返回呈现给 LLM 做工具调用的 JSON Schema 字符串execute接收匹配该 schema 的 JSON 编码参数返回tool-result或错误字符串。json-string是wit/v0/types.wit中string的类型别名。宿主导入logging、config、secrets、inbound宿主函数由插件导入、运行时提供实现见crates/zeroclaw-plugins/src/下的component_logging.rs、component_secrets.rs、component_config.rs等loggingwit/v0/logging.wit三个 world 都导入log-record: func(level: log-level, event: plugin-event)是 fire-and-forget 调用宿主吸收所有错误失败的日志写入不可能导致插件崩溃。投递是异步的记录交给有界宿主队列、由专用线程排空慢或卡死的日志消费者不会把 guest 导出拖过plugins.limits.call_timeout_ms。事件字段复制到宿主内存超出 guest 的max_memory_mb上限超 64 KiB 的记录被丢弃而非截断队列合计有固定 8 MiB 字节预算。plugin-action/plugin-outcome镜像zeroclaw-log的封闭Action/EventOutcome分类法故意没有逃生舱变体。不要直接调用wasi:logging否则事件格式不一致且到不了zeroclaw_log的全部目的地。configwit/v0/config.wit通道 world 导入返回当前 schema 校验过、非密文的 JSON 对象get: func() - resultjson-string, config-error。标记x-secret: true的属性被省略。它在configure与运营性通道导出中可用有效config_read授予缺失时返回access-denied。config.get是按需访问而非加载时快照——合规通道插件必须在每次使用配置的操作中调用它且不得在温 guest 状态中保留返回对象。secretswit/v0/secrets.wit工具与通道 world 导入guest 只提供顶层属性名get: func(name: string) - resultstring, secret-error。宿主从已获准的PluginInstanceScope派生包、能力、绑定与有效授予均非 guest 输入。只有 manifest schema 中标记x-secret: true的直接顶层字符串属性可读。access-denied、not-found与unavailable刻意不泄露 resolver 或 schema 细节。inboundwit/v0/inbound.wit通道 world 导入通道插件自身不开监听器宿主运行监听器webhook 服务器、厂商隧道或轮询客户端并把每条消息入队。插件从自己的poll-message导出中调用inbound-poll配合inbound-pending: func() - u32批量排空取走消息。宿主为每个通道持有一个InboundQueueWasmChannel::inbound把克隆交给监听任务。ZeroClaw 自有的导入共享每个宿主分发服务帧的固定安全预算上限为crates/zeroclaw-plugins/src/component.rs中的MAX_HOST_CALLS_PER_FRAME。耗尽时日志变为 no-op、inbound 轮询报告为空、配置或密钥读取返回unavailable新帧重置预算。这是固定宿主策略不是可重复配置的运维项。执行模型fuel、墙钟截止时间与 32 位边界宿主crates/zeroclaw-plugins/src/component.rs为进程持有一个异步wasmtime::Engine。加载方式依赖后端带 Cranelift JIT 的构建在加载时编译.wasm仅运行时构建反序列化预编译.cwasm。每个插件实例获得携带沙箱 WASI 上下文、资源表、可选 HTTP 上下文与 fuel 预算的Store一个Linker恰好包含其 world、授予与适配器支持所要求的导入logging总是接入secrets对工具与通道config与inbound对通道wasi:http仅在 manifest 授予http_client时对工具与通道适配器接入。内存插件既不创建 HTTP 上下文也不建 HTTP linker。每个适配器在实例化时交叉校验上下文与 linkerensure_http_coherent。工具调用在构造上无状态WasmTool::execute构建全新 store、运行调用、随即丢弃。通道与内存后端天然有状态故在整个插件生命周期内持有一个温 store宿主在每次调用前重新加 fuel长生命周期插件每次调用都能得到完整预算而非随时间耗尽。截止时间中断会丢弃温 store 而不是恢复部分展开的 guest 状态通道在下次调用重建实例内存则保持不可用直到其拥有者重建。授权通道调用期间config.get与secrets.get至多物化该获准实例的当前 canonical 配置的一个修订调用结束宿主即丢弃该视图。五个可按需调整的上限全部校验非零plugins.limits.call_fuel默认 1,000,000,000 指令单位plugins.limits.call_timeout_ms默认 30,000 毫秒plugins.limits.max_memory_mb默认 256plugins.limits.max_table_elements默认 100,000plugins.limits.max_instances默认 64边界是 32 位的目标是wasm32-wasip2——这是 Rust 工具链唯一交付的 WASI Preview 2 目标组件 ABI 无论宿主字长如何都把偏移量降为 32 位。大值如通道附件的字节按值跨边界。这是上游工具链约束而非本仓库可翻转的标志详见 plugin-protocol.md 的 32 位地址空间一节。当前接线状态需要清楚哪些已端到端注册、哪些宿主侧已完成但尚不能从运行中的 daemon 触达index.md 与 plugin-protocol.md 均给出此表能力宿主适配器运行时接线toolWasmTool端到端注册发现的工具插件出现在 Agent 工具集中skillmarkdown 加载器端到端注册技能以plugin:plugin/skill命名空间加载channelWasmChannel完整且有单元覆盖别名持有的构造与运行时配置解析已落地PR #10146把每个厂商传输排入通道inbound队列的按厂商宿主监听器是后续工作memoryWasmMemory实现完整Memorytrait运行时尚未把它构造为可配置后端observer无PluginCapability::Observer已预留尚无 WIT world 或适配器配置参考从启用到沙箱上限静态插件宿主设置沿用与其他一切相同的 schema 镜像每实例值目前使用通用 TOML 或zeroclaw config set插件 manifest schema 尚未渲染为 zerocode 或 gateway 表单。手改配置时注意某节语法错误例如写了[plugins.entries]而本意是[[plugins.entries]]会让整个[plugins]节反序列化失败并静默回退默认值读回表现为plugins.enabled false且无警告issue #8636 跟踪中。常用操作# 打开系统总开关 zeroclaw config set plugins.enabled true # 运行时加载自动发现的工具与技能插件默认false zeroclaw config set plugins.auto_discover true # 插件发现目录默认~/.zeroclaw/plugins zeroclaw config set plugins.plugins_dir /srv/zeroclaw/plugins # 签名策略disabled | permissive | strict zeroclaw config set plugins.security.signature_mode strict # 受信任发布者 Ed25519 公钥strict 模式 zeroclaw config set plugins.security.trusted_publisher_keys [a1b2c3d4e5f6...] # 每次调用的沙箱上限 zeroclaw config set plugins.limits.call_fuel 1000000000 zeroclaw config set plugins.limits.call_timeout_ms 30000 zeroclaw config set plugins.limits.max_memory_mb 256plugins.limits.max_connections_per_instance默认 16限制单个逻辑插件实例可同时持有的出站连接数。上限按实例而非按调用计算响应在 guest 排空 body 或丢弃响应前一直占用连接因此一次调用内保持 16 个响应存活的工具无法打开第 17 条连接边排空边丢弃的串行请求永远不会接近上限。触顶时 guest 看到的是wasi:http自身的connection-limit-reached错误而非出站拒绝——目的地已被授予宿主只是在报告它计数的资源。plugins.enabled true打开插件宿主但自动发现的工具与技能能力只在plugins.auto_discover true时加载。该标志默认falsefail-closed所以单独的enabled true只给你[channels.plugin.alias]下声明的通道不含任何插件工具或技能工具/技能包可以干净地list与info却在运行时零贡献。显式通道绑定是运维命名的而非自动发现因此不需要auto_discover。每实例设置位于plugins.entries下键是派生自宿主持有的包、能力与绑定身份的带版本zpi1_…字符串。安装会打印并预置包默认工具绑定的键zeroclaw plugin info package再次打印该工具键。这些自动表面仅限工具。通道实例的键派生自实际配置的别名别名感知构造已在 PR #10146 落地daemon 现在能构造显式声明的[channels.plugin.alias]实例并从该别名解析其类型化配置通道实例的自动plugin info键显示与安装时预置仍是手动的直到 PR #9584 的授权仪式。完整身份键让不同包与能力 world 可安全复用main等别名而不共享凭据。canonical 运维值是一个 secret 标记的字符串 map静止时保持加密enc2:…。请求config_read的插件在config_schema中声明该 map 的唯一类型契约一个封闭的 Draft 2020-12 对象顶层属性显式使用string、boolean、integer、number、array或object。工具或通道消费者可在顶层字符串属性上设x-secret true宿主用完整对象校验、将其从公开配置中移除、仅通过获准实例的secrets.get导入提供。工具在execute期间读密钥通道在configure与运营调用期间通过config.get取公开配置、secrets.get取密钥。没有有效config_read授予时两个导入都返回access-denied实例化、静态元数据发现、解析失败与宿主调用预算耗尽返回unavailable。字符串直接存、布尔与数字用 JSON 标量文本true、4、0.5、数组与对象用 JSON 文本。宿主在把类型化对象交给工具或通道 guest 代码前完成物化与校验未知、畸形或越界值直接失败。内存插件尚无 config 导入在 ABI 加入前不得请求config_read。Pre-1.0 作者必须显式迁移请求config_read却不带config_schema的 manifest 不再被发现。应补充与当前值匹配的封闭 schema、把工具/通道 guest 改为反序列化类型化 JSON而非字符串 map、重建并重新签名schema 属于签名覆盖范围。宿主集成注入的是包装PluginConfigResolver的PluginHostServices而非自有 config map。每个授权帧至多物化一个作用域绑定的ResolvedPluginConfig帧内所有 config 读取共用该视图、帧结束即丢弃。逐步骤配方见 Migrating to typed config包括此强制不加兼容垫片的发布决策。这是严格的 pre-1.0 键格式仅以包或绑定命名的旧条目不再被采纳。对既有工具包运行zeroclaw plugin info package获取完整实例键、把旧条目改名为该键、保存配置全新工具安装会自动预置。有效授予与 manifest 请求分开检查。若config_read被拒绝宿主校验空对象必填属性使启动 fail-closed空对象有效时工具省略空__config键、通道 config/secret 导入返回access-denied。canonical 宿主字段清单与默认值见 配置参考zeroclaw config list显示实时存储值。信任边界究竟在哪里沙箱限定已加载插件能做什么签名策略限定什么能加载。二者都是运维决策且可组合index.mdplugins.enabledfalse默认任何插件代码都不运行永远。plugins.auto_discoverfalse默认自动发现的工具与技能能力不加载。plugins.enabled true单独只激活[channels.plugin.alias]下声明的通道工具与技能仅在auto_discover true时加载。签名strict只有 manifest 携带受信任集合中密钥签发的有效 Ed25519 签名的组件加载。已加载插件受 fuel、内存上限、无 preopen WASI 与权限门控导入集约束。沙箱不约束的是模型选择调用的工具的语义行为持有http_client授予与工具适配器 HTTP 表面的工具可以把模型传给它的任何内容发到其代码决定的任何目的地。签名策略存在的意义在于加载哪些代码才是最重要的决策——请有意识地做出它。插件 HTTPS 的证书信任插件 HTTPS 请求对捆绑的 webpki 根程序加上本机已信任的根做验证。证书链到本地安装 CA如企业 MDM 根或私有 PKI的端点对插件与对 provider 请求表现一致链构建与主机名匹配仍然强制出站策略仍决定 guest 可达哪些目的地。这些根每进程读取一次重写同路径证书文件或改变 OS 证书库不会影响运行中的 daemon需重启plugin_egress_trust_anchors日志行会说明读取到的是两者中的哪一种。从空 crate 到可调用工具redact 实战要点工具插件指南 给出了从空 crate 到模型可调用工具的完整路径示例工具redact用于屏蔽文本中的邮箱、已知凭据前缀与运维提供的模式。几个关键契约点发布二进制不是那个二进制安装器附带的预构建二进制不含插件宿主zeroclaw plugin …是未识别子命令且plugins-wasm不在 crate 默认特性集。需从源码带执行后端构建一个标志即可每个后端特性本身携带plugins-wasm总开关cargo build --release --features plugins-wasm-cranelift纯逻辑与胶水分离把真实行为放在无 wit-bindgen 导入的普通 Rust 模块如src/redact.rs胶水保持极薄。原因是可测性组件目标无法原生运行cargo test。plugin-info是每个 world 的必导出报告组件自身名称与版本须与 manifest 同步。元数据只读一次call_tool_metadataruntime.rs在注册时读取并缓存name、description、parameters-schema此后不再重问注册失败即失败宿主绝不为损坏组件代造元数据。schema 是模型看待你工具的全部视图宿主在加载时按 JSON 解析tool parameters-schema is not valid JSON是硬性注册失败并原样转发给 LLM。绝不在 schema 中声明__config该键宿主保留注入前会剥离任何调用方提供的值模型无法伪装成你的运维。success: false与Err语义success: false的ToolResult作为普通工具响应流回模型可重试、道歉、换工具Err(String)跨边界成为插件故障宿主包装为plugin execute returned error。把Err留给真正损坏的状态。日志走导入的logging接口携带宿主调用点 span 的zeroclaw.*归因attrs字段是自由格式attributes载荷而非归因。工具插件调用流启动时发现→校验 manifest 形状→签名策略→校验config_schema注册前宿主把运维值物化为类型化 JSON 并校验幸存者成为WasmTool实例注册时实例化一次组件读取缓存元数据每次调用WasmTool::execute从 canonical 状态解析并校验配置、构建全新 store新 WASI 上下文、新 fuel 预算、无上一调用状态非密文值注入__config、schema 标记密钥经作用域化secrets导入提供。做网络调用的工具声明http_client、经作用域化密钥服务读凭据、用waki阻塞式适配execute同步签名发起出站请求。注意版本事实waki 自带其 wit-bindgen0.34与你的 world 绑定0.46共存waki 发出wasi:http0.2.4导入而当前工具链基线是0.2.6宿主两者都链接。真正会坏的是 world 版本漂移vendored 的wit/v0必须与宿主导出的 world 完全一致旧副本可能编译通过却在实例化时失败检查 Wasmtime 错误链中的 WIT-drift 提示。http_client是全有或全无的沙箱不限定已授权插件把数据发往哪里运行strict签名策略的运维信任的是你的代码而非 URL 白名单。内置工具清单保留、门控还是外部化工具清单 是一张分类地图而非移除计划用于判断某个 Agent 可调用工具应留在核心二进制、加 feature 门控、迁到 WASM 插件、作为技能包发布还是走 MCP/CLI 集成。运行时注册表的真源是crates/zeroclaw-runtime/src/tools/mod.rs尤其default_tools、all_tools_with_runtime、register_skill_tools_with_context_and_runtime共享工具实现主要位于crates/zeroclaw-tools/。分类桶Keep built-in基线 Agent 契约或与运行时策略/回执/内存/会话/委派紧耦合、Feature-gate candidate一方法行为仍属于 ZeroClaw但依赖/平台/二进制体积/运维风险不应影响最小构建、Externalize later长期归属应为插件/技能包/MCP/CLI、No action yet证据不足。保留内置shell、file_read/file_write/file_edit、glob_search/content_search构成最小本地工作表面内存族memory_store/recall/forget/export/purge、cron 族、委派族spawn_subagent/delegate/send_message_to_peer、ask_user/escalate_to_human/reaction/poll/channel_room、会话族、路由族model_routing_config/model_switch/proxy_config、TodoWrite、read_skill与技能定义工具因属于运行时/内存/协调/运维控制原语而留下。Feature-gate 候选浏览器族、网络族http_request/web_fetch/web_search_tool、SOP 族、WASM 插件工具宿主桥、execute_pipeline、knowledge、文件上传下载、backup/data_management、视觉族、llm_task、security_ops、verifiable_intent其vi_verify工具暂时从模型可见注册表扣留启用该节只发出verifiable_intent_tool_withheld警告、硬件探针族。外部化候选notion/jira/microsoft365/google_workspace/linkedin/composio→ 插件或 MCPCLI 类claude_code/codex_cli/gemini_cli/opencode_cli→ CLI 支撑集成email_search/email_read、discord_search、image_gen/cloud_ops/project_intel/report_template、weather、pushover、git_operations各有其预期归属。暂不动作calculator、tool_search与延迟 MCP 激活、会话重置/删除工具。迁移规则把任何工具移出核心前替代者必须回答——哪些配置留在一方、哪些移到插件/技能/MCP/CLI如何保留自治检查、allow/deny 列表、工具回执、审计日志与归因内置工具消失时既有配置如何失败或迁移运维能否看到能力已安装/启用/禁用/阻断/缺失外部包损坏时的回滚路径。本地构建文档与 Web Dashboarddocs/book/是文档站源可用 mdbook 在本地构建相同站点building-docs.mdcargo mdbook是cargo run -p xtask --bin mdbook --的别名定义于 cargo config快速迭代文字cargo mdbook serve保存即自动重建除非改了 CLI 标志或配置 schema否则可跳过cargo mdbook refs翻译英文是源语言翻译存于docs/book/po/locale.po作为缓存cargo mdbook sync保持其最新常规英文文档 PR 不必携带生成的.po变动。Web dashboard 位于web/是 Vite React TypeScript 应用其 TypeScript API 客户端从网关的运行时 OpenAPI spec 生成而非手写web.mdcargo web build # 生产 bundle 到 web/dist/ cargo web dev # vite dev server with HMR cargo web check # 仅类型检查gen-api tsc -b cargo web gen-api # 重新生成 web/src/lib/api-generated.ts cargo web install # 在 web/ 中 npm installcargo web是cargo run -p xtask --bin web --的别名每个子命令在web/node_modules/缺失时自动运行npm install。cargo web gen-api从zeroclaw_gateway::openapi::build_spec()进程内渲染 OpenAPI spec、写入target/openapi.json并喂给 openapi-typescript同一个build_spec()运行时服务/api/openapi.json因此它是唯一契约源。编辑流程改crates/zeroclaw-gateway/中的 handler 或 schema →cargo web check重新生成并类型检查 → 更新web/src/消费者 →cargo web build。网关通过static_files.rs从文件系统加载web/dist/Rust 编译与 web 构建解耦。dashboard 面向支持color-mix()与structuredClone()的常青浏览器Chrome/Edge 111、Firefox 113、Safari 16.2。三个默认值与操作速查无论插件作者还是运维记住三个默认值的组合决定了插件系统的行为plugins.enabled默认false——系统关闭任何插件代码都不运行plugins.auto_discover默认false——即使启用自动发现的工具与技能也不加载只有显式声明的通道激活plugins.security.signature_mode默认disabled——本地开发无需密钥管理但共享/生产宿主应设为strict并列出受信任发布者。装载第三方插件的宿主应设置enabled true、signature_mode strict、只列出信任的发布者密钥还需自动发现的工具与技能时再设auto_discover true。只运行自建插件的宿主可在开发期保持disabled共享前收紧。插件工具不在内置只读自动批准集合中非全自治模式下调用会像其他特权工具一样弹出运维批准提示——在工具描述中提前预期这一点。延伸阅读插件作者完整路径Writing a tool plugin从空 crate 到已安装工具、Writing a channel plugin、Writing a memory plugin、Distributing plugins协议规范真源plugin-protocol.md 与wit/v0/下的 WIT 文件WIT 兼容规则见 wit/VERSIONING.md宿主实现crates/zeroclaw-plugins/src/component.rs、host.rs、runtime.rs、wasm_tool.rs、wasm_channel.rs、wasm_memory.rs、signature.rs类型化配置迁移见 migrating-to-typed-config.md构建特性plugins-wasm总开关等价于 runtime-only、plugins-wasm-runtime-only无 JIT仅加载预编译.cwasm、plugins-wasm-craneliftJIT加载时编译.wasm、plugins-wasm-pulley最可移植均委托给zeroclaw-pluginscrate 对应特性并体现在工作区Cargo.toml中【免费下载链接】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 插件系统与开发者工具链完全指南：WASM 沙箱协议、签名策略与内置工具清单
ZeroClaw 插件系统与开发者工具链完全指南WASM 沙箱协议、签名策略与内置工具清单【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclawZeroClaw 的插件系统允许在不触碰核心二进制的前提下为 Agent 增加能力插件以 WebAssembly 组件wasm32-wasip2 TOML 清单的形式驻留在安装目录由宿主wasmtime以无文件系统、无网络环境的 WASI 上下文加载并通过 WIT 接口与运行时原生 trait 无缝对接。本文以 docs/book/src/developing/index.md 为骨架完整讲解插件的工作原理、协议契约、签名策略、配置命令、内置工具分类以及文档与 Web Dashboard 的本地构建流程读者读完后既能以运维视角安全地装载第三方插件也能以作者视角从空 crate 写出一个可被模型调用的工具插件。开发者文档导航developing 章节的定位docs/book/src/developing/index.md是 ZeroClaw 文档中面向插件系统与项目工具链工作的入口页。它明确划分了两类读者插件使用者operator阅读 How plugins work了解插件如何被发现、被允许做什么、宿主如何约束不受信任的插件插件作者与协议实现者阅读 Plugin protocol掌握磁盘上的契约manifest 字段、WIT 导出、host 函数决策者阅读 Built-in tool inventory判断某个工具应留在核心、加 feature 门控、还是外部化为插件/技能包/MCP/CLI 集成工具链贡献者阅读 Building the docs locally 与 Building the web dashboard。而逐步骤的插件编写实战则位于 docs/book/src/plugins/index.md按工具插件 → 通道插件 → 内存插件 → 分发的难度递进。为什么是 WebAssembly四个不可替代的性质插件运行在持有你的 API 密钥、对话历史与 shell 访问权限的进程内隔离边界必须是真实的而非劝告性的。ZeroClaw 采用wasmtime上的 WASI Component Model因为它同时具备动态库或子进程方案无法兼备的四个性质见 插件总览基于能力的沙箱Capability-based sandboxingWebAssembly 组件没有环境固有权限。它不能打开文件、套接字或环境变量除非宿主显式把该能力接入 linker。ZeroClaw 宿主为每个插件 store 构造的 WASI 上下文没有任何文件系统 preopen、也没有网络PluginState位于crates/zeroclaw-plugins/src/component.rs。插件能触达的范围恰好等于其 world 声明的宿主导入集合加上其 manifest 权限声明的内容除此之外一无所有。可计量的执行Metered execution引擎开启 fuel 计量每次调用获得全新 fuel 预算外加包含宿主异步工作的墙钟截止时间。无限循环或无限等待的插件会失败无法挂起 Agent。内存、表与实例上限由 store limiter 强制全部五个上限来自运维配置plugins.limits.*且校验为非零——无法构造不设限的 store因此不存在任何能产生非沙箱插件的加载路径。类型化、语言无关的 ABI宿主与插件之间的契约是一组 WIT 接口文件仓库wit/v0/而非 Rust API。宿主用 wasmtime 的bindgen!从这些文件生成绑定插件用wit-bindgenRust或任何能编译成wasm32-wasip2组件的语言的等价工具生成镜像 guest 绑定。记录、变体、结果与 option 类型跨边界时类型保持完整。与内置行为完全一致每种插件都被适配到一方实现所用的同一个 Rust trait 上——工具插件成为Toolcrates/zeroclaw-plugins/src/wasm_tool.rs通道插件成为Channelwasm_channel.rs内存插件成为Memorywasm_memory.rs。Agent 循环、归因、回执与安全策略看不出任何差别。插件的构成manifest 与 WASM 组件磁盘上的一个插件是包含一份 manifest 与一个已编译组件的目录~/.zeroclaw/plugins/ └── my-plugin/ ├── manifest.toml # identity、capabilities、permissions、signature └── my-plugin.wasm # wasm32-wasip2 componentmanifest 声明两件正交的事Capabilities能力插件是什么。取值tool、channel、memory、observer、skill中的一个或多个PluginCapability枚举定义于crates/zeroclaw-plugins/src/lib.rs。每个 WASM 能力选择组件必须导出的 WIT world。skill是特例它标记的是搭乘安装机制的 markdown 技能包而非代码因此不需要组件。Permissions权限插件代码可触达哪些宿主服务同一文件的PluginPermission枚举。目前config_read与http_client有实际行为效果其余file_read、file_write、memory_read、memory_write虽被 schema 接受但尚无宿主函数支撑声明它们不会授予任何东西。manifest 字段速查manifest 字段是PluginManifestcrates/zeroclaw-plugins/src/lib.rs的 serde 表面以下为字段契约完整版见 plugin-manifest-fields 片段字段必填含义name是唯一规范包 slug也是每个派生实例配置键的包组成部分。1–128 个小写 ASCII 字符以[a-z0-9]开头结尾中间仅允许[a-z0-9._-]重复或非法名字在发现阶段被拒绝version是版本字符串如0.1.0description否zeroclaw plugin list展示的人类可读描述author否作者名或组织wasm_pathWASM 能力必填相对插件目录的组件文件名。仅当唯一能力是skill时可省略文件不存在则跳过该插件capabilities是非空tool/channel/memory/observer/skillpermissions否http_client、config_read、file_read、file_write、memory_read、memory_write。仅前两者当前被强制声明config_read必须同时提供config_schemaconfig_schema与config_read严格配对Draft 2020-12 JSON Schema属于被签名覆盖的 canonical manifest 字节signature否对 canonical manifest 字节的 base64url Ed25519 签名publisher_key否签名者的十六进制 Ed25519 公钥只声明代码实际用到的权限未声明的权限是不可触达的宿主表面多余声明的权限则是你主动要求的攻击面。插件加载生命周期运行时构建工具集时加载器按顺序经过以下阶段前一阶段失败的插件永远不会进入后一阶段How plugins workGate闸门[plugins] enabled为 false 则加载器什么都不做。这是最先且最廉价的检查。Discover发现扫描解析后的插件目录[plugins] plugins_dir默认~/.zeroclaw/plugins/寻找含manifest.toml的子目录。Validate shape形状校验每个 manifest 必须声明至少一个能力非 skill 插件必须给出存在的wasm_path。畸形 manifest 被警告后跳过绝不被加载。Enforce signature policy签名策略依据[plugins.security] signature_mode与trusted_publisher_keys检查每个插件。未通过策略的插件从加载集合中剔除不会作为工具浮出。Register tools注册工具幸存的工具插件被包装为 Agent 工具追加在内置工具之后。工具分发按名字 first-match因此与内置工具重名的插件工具永远不会被选中——给插件工具起唯一的名字。工具与技能插件是自动发现的只有[plugins] auto_discover true默认falsefail-closed时才会枚举enabled true但auto_discover false时不会加载任何插件工具或技能不过[channels.plugin.alias]下显式声明的通道仍然激活。签名策略三种模式每个 manifest 可携带 Ed25519 签名与签名者十六进制公钥运维通过[plugins.security] signature_mode决定强制程度模式加载什么适用场景disabled所有格式良好的插件无论是否签名对自己构建的插件做本地开发permissive所有格式良好的插件未签名、不受信任与无效签名带警告加载在向签名迁移且不破坏既有安装时strict仅加载来自受信任发布者且签名有效的插件任何共享或生产宿主strict模式下manifest 的publisher_key必须出现在[plugins.security] trusted_publisher_keys中且签名必须对 canonical manifest 字节验证通过。默认是disabled这样全新本地检出无需密钥管理即可运行但任何加载不受你控制插件的宿主都应运行strict。该策略在列出插件与构建工具集两个路径上统一强制strict模式下你看不到的插件Agent 同样无法调用。WIT 世界与协议契约wit/v0/为每个 WASM 能力定义一个 world包名为zeroclaw:plugin0.1.0全部条目在稳定前都带unstable(feature plugins-wit-v0)门控。每个 world 都导入宿主logging接口log-record事件落入携带宿主调用点 span 归因的结构化日志并导出plugin-info自报名称与版本加主接口World导出store 生命周期tool-plugintoolname、description、parameters-schema、execute每次execute新建 store导入作用域化secretschannel-pluginchannelconfigure、send、poll-message 及按能力门控的方法async mutex 保护的温 store每次调用重新加 fuel导入作用域化config、secrets与宿主投喂的inboundmemory-pluginmemorystore、recall、get、forget 及能力门控方法async mutex 保护的温 store每次调用重新加 fuel通道与内存 world 使用能力标志capability flags宿主在加载时读取一次位掩码get-channel-capabilities/get-memory-capabilities。对每个未设置的标志宿主使用 Rust trait 默认实现绝不调用插件的导出。这正是 WIT 契约保持可加性的方式新的可选方法 新标志 新函数而不是破坏性变更。tool 接口wit/v0/tool.wit定义单工具表面。宿主在加载时调用name、description、parameters-schema一次之后每次调用分发executerecord tool-result { success: bool, output: string, error: optionstring, } name: func() - string; description: func() - string; parameters-schema: func() - json-string; execute: func(args: json-string) - resulttool-result, string;parameters-schema返回呈现给 LLM 做工具调用的 JSON Schema 字符串execute接收匹配该 schema 的 JSON 编码参数返回tool-result或错误字符串。json-string是wit/v0/types.wit中string的类型别名。宿主导入logging、config、secrets、inbound宿主函数由插件导入、运行时提供实现见crates/zeroclaw-plugins/src/下的component_logging.rs、component_secrets.rs、component_config.rs等loggingwit/v0/logging.wit三个 world 都导入log-record: func(level: log-level, event: plugin-event)是 fire-and-forget 调用宿主吸收所有错误失败的日志写入不可能导致插件崩溃。投递是异步的记录交给有界宿主队列、由专用线程排空慢或卡死的日志消费者不会把 guest 导出拖过plugins.limits.call_timeout_ms。事件字段复制到宿主内存超出 guest 的max_memory_mb上限超 64 KiB 的记录被丢弃而非截断队列合计有固定 8 MiB 字节预算。plugin-action/plugin-outcome镜像zeroclaw-log的封闭Action/EventOutcome分类法故意没有逃生舱变体。不要直接调用wasi:logging否则事件格式不一致且到不了zeroclaw_log的全部目的地。configwit/v0/config.wit通道 world 导入返回当前 schema 校验过、非密文的 JSON 对象get: func() - resultjson-string, config-error。标记x-secret: true的属性被省略。它在configure与运营性通道导出中可用有效config_read授予缺失时返回access-denied。config.get是按需访问而非加载时快照——合规通道插件必须在每次使用配置的操作中调用它且不得在温 guest 状态中保留返回对象。secretswit/v0/secrets.wit工具与通道 world 导入guest 只提供顶层属性名get: func(name: string) - resultstring, secret-error。宿主从已获准的PluginInstanceScope派生包、能力、绑定与有效授予均非 guest 输入。只有 manifest schema 中标记x-secret: true的直接顶层字符串属性可读。access-denied、not-found与unavailable刻意不泄露 resolver 或 schema 细节。inboundwit/v0/inbound.wit通道 world 导入通道插件自身不开监听器宿主运行监听器webhook 服务器、厂商隧道或轮询客户端并把每条消息入队。插件从自己的poll-message导出中调用inbound-poll配合inbound-pending: func() - u32批量排空取走消息。宿主为每个通道持有一个InboundQueueWasmChannel::inbound把克隆交给监听任务。ZeroClaw 自有的导入共享每个宿主分发服务帧的固定安全预算上限为crates/zeroclaw-plugins/src/component.rs中的MAX_HOST_CALLS_PER_FRAME。耗尽时日志变为 no-op、inbound 轮询报告为空、配置或密钥读取返回unavailable新帧重置预算。这是固定宿主策略不是可重复配置的运维项。执行模型fuel、墙钟截止时间与 32 位边界宿主crates/zeroclaw-plugins/src/component.rs为进程持有一个异步wasmtime::Engine。加载方式依赖后端带 Cranelift JIT 的构建在加载时编译.wasm仅运行时构建反序列化预编译.cwasm。每个插件实例获得携带沙箱 WASI 上下文、资源表、可选 HTTP 上下文与 fuel 预算的Store一个Linker恰好包含其 world、授予与适配器支持所要求的导入logging总是接入secrets对工具与通道config与inbound对通道wasi:http仅在 manifest 授予http_client时对工具与通道适配器接入。内存插件既不创建 HTTP 上下文也不建 HTTP linker。每个适配器在实例化时交叉校验上下文与 linkerensure_http_coherent。工具调用在构造上无状态WasmTool::execute构建全新 store、运行调用、随即丢弃。通道与内存后端天然有状态故在整个插件生命周期内持有一个温 store宿主在每次调用前重新加 fuel长生命周期插件每次调用都能得到完整预算而非随时间耗尽。截止时间中断会丢弃温 store 而不是恢复部分展开的 guest 状态通道在下次调用重建实例内存则保持不可用直到其拥有者重建。授权通道调用期间config.get与secrets.get至多物化该获准实例的当前 canonical 配置的一个修订调用结束宿主即丢弃该视图。五个可按需调整的上限全部校验非零plugins.limits.call_fuel默认 1,000,000,000 指令单位plugins.limits.call_timeout_ms默认 30,000 毫秒plugins.limits.max_memory_mb默认 256plugins.limits.max_table_elements默认 100,000plugins.limits.max_instances默认 64边界是 32 位的目标是wasm32-wasip2——这是 Rust 工具链唯一交付的 WASI Preview 2 目标组件 ABI 无论宿主字长如何都把偏移量降为 32 位。大值如通道附件的字节按值跨边界。这是上游工具链约束而非本仓库可翻转的标志详见 plugin-protocol.md 的 32 位地址空间一节。当前接线状态需要清楚哪些已端到端注册、哪些宿主侧已完成但尚不能从运行中的 daemon 触达index.md 与 plugin-protocol.md 均给出此表能力宿主适配器运行时接线toolWasmTool端到端注册发现的工具插件出现在 Agent 工具集中skillmarkdown 加载器端到端注册技能以plugin:plugin/skill命名空间加载channelWasmChannel完整且有单元覆盖别名持有的构造与运行时配置解析已落地PR #10146把每个厂商传输排入通道inbound队列的按厂商宿主监听器是后续工作memoryWasmMemory实现完整Memorytrait运行时尚未把它构造为可配置后端observer无PluginCapability::Observer已预留尚无 WIT world 或适配器配置参考从启用到沙箱上限静态插件宿主设置沿用与其他一切相同的 schema 镜像每实例值目前使用通用 TOML 或zeroclaw config set插件 manifest schema 尚未渲染为 zerocode 或 gateway 表单。手改配置时注意某节语法错误例如写了[plugins.entries]而本意是[[plugins.entries]]会让整个[plugins]节反序列化失败并静默回退默认值读回表现为plugins.enabled false且无警告issue #8636 跟踪中。常用操作# 打开系统总开关 zeroclaw config set plugins.enabled true # 运行时加载自动发现的工具与技能插件默认false zeroclaw config set plugins.auto_discover true # 插件发现目录默认~/.zeroclaw/plugins zeroclaw config set plugins.plugins_dir /srv/zeroclaw/plugins # 签名策略disabled | permissive | strict zeroclaw config set plugins.security.signature_mode strict # 受信任发布者 Ed25519 公钥strict 模式 zeroclaw config set plugins.security.trusted_publisher_keys [a1b2c3d4e5f6...] # 每次调用的沙箱上限 zeroclaw config set plugins.limits.call_fuel 1000000000 zeroclaw config set plugins.limits.call_timeout_ms 30000 zeroclaw config set plugins.limits.max_memory_mb 256plugins.limits.max_connections_per_instance默认 16限制单个逻辑插件实例可同时持有的出站连接数。上限按实例而非按调用计算响应在 guest 排空 body 或丢弃响应前一直占用连接因此一次调用内保持 16 个响应存活的工具无法打开第 17 条连接边排空边丢弃的串行请求永远不会接近上限。触顶时 guest 看到的是wasi:http自身的connection-limit-reached错误而非出站拒绝——目的地已被授予宿主只是在报告它计数的资源。plugins.enabled true打开插件宿主但自动发现的工具与技能能力只在plugins.auto_discover true时加载。该标志默认falsefail-closed所以单独的enabled true只给你[channels.plugin.alias]下声明的通道不含任何插件工具或技能工具/技能包可以干净地list与info却在运行时零贡献。显式通道绑定是运维命名的而非自动发现因此不需要auto_discover。每实例设置位于plugins.entries下键是派生自宿主持有的包、能力与绑定身份的带版本zpi1_…字符串。安装会打印并预置包默认工具绑定的键zeroclaw plugin info package再次打印该工具键。这些自动表面仅限工具。通道实例的键派生自实际配置的别名别名感知构造已在 PR #10146 落地daemon 现在能构造显式声明的[channels.plugin.alias]实例并从该别名解析其类型化配置通道实例的自动plugin info键显示与安装时预置仍是手动的直到 PR #9584 的授权仪式。完整身份键让不同包与能力 world 可安全复用main等别名而不共享凭据。canonical 运维值是一个 secret 标记的字符串 map静止时保持加密enc2:…。请求config_read的插件在config_schema中声明该 map 的唯一类型契约一个封闭的 Draft 2020-12 对象顶层属性显式使用string、boolean、integer、number、array或object。工具或通道消费者可在顶层字符串属性上设x-secret true宿主用完整对象校验、将其从公开配置中移除、仅通过获准实例的secrets.get导入提供。工具在execute期间读密钥通道在configure与运营调用期间通过config.get取公开配置、secrets.get取密钥。没有有效config_read授予时两个导入都返回access-denied实例化、静态元数据发现、解析失败与宿主调用预算耗尽返回unavailable。字符串直接存、布尔与数字用 JSON 标量文本true、4、0.5、数组与对象用 JSON 文本。宿主在把类型化对象交给工具或通道 guest 代码前完成物化与校验未知、畸形或越界值直接失败。内存插件尚无 config 导入在 ABI 加入前不得请求config_read。Pre-1.0 作者必须显式迁移请求config_read却不带config_schema的 manifest 不再被发现。应补充与当前值匹配的封闭 schema、把工具/通道 guest 改为反序列化类型化 JSON而非字符串 map、重建并重新签名schema 属于签名覆盖范围。宿主集成注入的是包装PluginConfigResolver的PluginHostServices而非自有 config map。每个授权帧至多物化一个作用域绑定的ResolvedPluginConfig帧内所有 config 读取共用该视图、帧结束即丢弃。逐步骤配方见 Migrating to typed config包括此强制不加兼容垫片的发布决策。这是严格的 pre-1.0 键格式仅以包或绑定命名的旧条目不再被采纳。对既有工具包运行zeroclaw plugin info package获取完整实例键、把旧条目改名为该键、保存配置全新工具安装会自动预置。有效授予与 manifest 请求分开检查。若config_read被拒绝宿主校验空对象必填属性使启动 fail-closed空对象有效时工具省略空__config键、通道 config/secret 导入返回access-denied。canonical 宿主字段清单与默认值见 配置参考zeroclaw config list显示实时存储值。信任边界究竟在哪里沙箱限定已加载插件能做什么签名策略限定什么能加载。二者都是运维决策且可组合index.mdplugins.enabledfalse默认任何插件代码都不运行永远。plugins.auto_discoverfalse默认自动发现的工具与技能能力不加载。plugins.enabled true单独只激活[channels.plugin.alias]下声明的通道工具与技能仅在auto_discover true时加载。签名strict只有 manifest 携带受信任集合中密钥签发的有效 Ed25519 签名的组件加载。已加载插件受 fuel、内存上限、无 preopen WASI 与权限门控导入集约束。沙箱不约束的是模型选择调用的工具的语义行为持有http_client授予与工具适配器 HTTP 表面的工具可以把模型传给它的任何内容发到其代码决定的任何目的地。签名策略存在的意义在于加载哪些代码才是最重要的决策——请有意识地做出它。插件 HTTPS 的证书信任插件 HTTPS 请求对捆绑的 webpki 根程序加上本机已信任的根做验证。证书链到本地安装 CA如企业 MDM 根或私有 PKI的端点对插件与对 provider 请求表现一致链构建与主机名匹配仍然强制出站策略仍决定 guest 可达哪些目的地。这些根每进程读取一次重写同路径证书文件或改变 OS 证书库不会影响运行中的 daemon需重启plugin_egress_trust_anchors日志行会说明读取到的是两者中的哪一种。从空 crate 到可调用工具redact 实战要点工具插件指南 给出了从空 crate 到模型可调用工具的完整路径示例工具redact用于屏蔽文本中的邮箱、已知凭据前缀与运维提供的模式。几个关键契约点发布二进制不是那个二进制安装器附带的预构建二进制不含插件宿主zeroclaw plugin …是未识别子命令且plugins-wasm不在 crate 默认特性集。需从源码带执行后端构建一个标志即可每个后端特性本身携带plugins-wasm总开关cargo build --release --features plugins-wasm-cranelift纯逻辑与胶水分离把真实行为放在无 wit-bindgen 导入的普通 Rust 模块如src/redact.rs胶水保持极薄。原因是可测性组件目标无法原生运行cargo test。plugin-info是每个 world 的必导出报告组件自身名称与版本须与 manifest 同步。元数据只读一次call_tool_metadataruntime.rs在注册时读取并缓存name、description、parameters-schema此后不再重问注册失败即失败宿主绝不为损坏组件代造元数据。schema 是模型看待你工具的全部视图宿主在加载时按 JSON 解析tool parameters-schema is not valid JSON是硬性注册失败并原样转发给 LLM。绝不在 schema 中声明__config该键宿主保留注入前会剥离任何调用方提供的值模型无法伪装成你的运维。success: false与Err语义success: false的ToolResult作为普通工具响应流回模型可重试、道歉、换工具Err(String)跨边界成为插件故障宿主包装为plugin execute returned error。把Err留给真正损坏的状态。日志走导入的logging接口携带宿主调用点 span 的zeroclaw.*归因attrs字段是自由格式attributes载荷而非归因。工具插件调用流启动时发现→校验 manifest 形状→签名策略→校验config_schema注册前宿主把运维值物化为类型化 JSON 并校验幸存者成为WasmTool实例注册时实例化一次组件读取缓存元数据每次调用WasmTool::execute从 canonical 状态解析并校验配置、构建全新 store新 WASI 上下文、新 fuel 预算、无上一调用状态非密文值注入__config、schema 标记密钥经作用域化secrets导入提供。做网络调用的工具声明http_client、经作用域化密钥服务读凭据、用waki阻塞式适配execute同步签名发起出站请求。注意版本事实waki 自带其 wit-bindgen0.34与你的 world 绑定0.46共存waki 发出wasi:http0.2.4导入而当前工具链基线是0.2.6宿主两者都链接。真正会坏的是 world 版本漂移vendored 的wit/v0必须与宿主导出的 world 完全一致旧副本可能编译通过却在实例化时失败检查 Wasmtime 错误链中的 WIT-drift 提示。http_client是全有或全无的沙箱不限定已授权插件把数据发往哪里运行strict签名策略的运维信任的是你的代码而非 URL 白名单。内置工具清单保留、门控还是外部化工具清单 是一张分类地图而非移除计划用于判断某个 Agent 可调用工具应留在核心二进制、加 feature 门控、迁到 WASM 插件、作为技能包发布还是走 MCP/CLI 集成。运行时注册表的真源是crates/zeroclaw-runtime/src/tools/mod.rs尤其default_tools、all_tools_with_runtime、register_skill_tools_with_context_and_runtime共享工具实现主要位于crates/zeroclaw-tools/。分类桶Keep built-in基线 Agent 契约或与运行时策略/回执/内存/会话/委派紧耦合、Feature-gate candidate一方法行为仍属于 ZeroClaw但依赖/平台/二进制体积/运维风险不应影响最小构建、Externalize later长期归属应为插件/技能包/MCP/CLI、No action yet证据不足。保留内置shell、file_read/file_write/file_edit、glob_search/content_search构成最小本地工作表面内存族memory_store/recall/forget/export/purge、cron 族、委派族spawn_subagent/delegate/send_message_to_peer、ask_user/escalate_to_human/reaction/poll/channel_room、会话族、路由族model_routing_config/model_switch/proxy_config、TodoWrite、read_skill与技能定义工具因属于运行时/内存/协调/运维控制原语而留下。Feature-gate 候选浏览器族、网络族http_request/web_fetch/web_search_tool、SOP 族、WASM 插件工具宿主桥、execute_pipeline、knowledge、文件上传下载、backup/data_management、视觉族、llm_task、security_ops、verifiable_intent其vi_verify工具暂时从模型可见注册表扣留启用该节只发出verifiable_intent_tool_withheld警告、硬件探针族。外部化候选notion/jira/microsoft365/google_workspace/linkedin/composio→ 插件或 MCPCLI 类claude_code/codex_cli/gemini_cli/opencode_cli→ CLI 支撑集成email_search/email_read、discord_search、image_gen/cloud_ops/project_intel/report_template、weather、pushover、git_operations各有其预期归属。暂不动作calculator、tool_search与延迟 MCP 激活、会话重置/删除工具。迁移规则把任何工具移出核心前替代者必须回答——哪些配置留在一方、哪些移到插件/技能/MCP/CLI如何保留自治检查、allow/deny 列表、工具回执、审计日志与归因内置工具消失时既有配置如何失败或迁移运维能否看到能力已安装/启用/禁用/阻断/缺失外部包损坏时的回滚路径。本地构建文档与 Web Dashboarddocs/book/是文档站源可用 mdbook 在本地构建相同站点building-docs.mdcargo mdbook是cargo run -p xtask --bin mdbook --的别名定义于 cargo config快速迭代文字cargo mdbook serve保存即自动重建除非改了 CLI 标志或配置 schema否则可跳过cargo mdbook refs翻译英文是源语言翻译存于docs/book/po/locale.po作为缓存cargo mdbook sync保持其最新常规英文文档 PR 不必携带生成的.po变动。Web dashboard 位于web/是 Vite React TypeScript 应用其 TypeScript API 客户端从网关的运行时 OpenAPI spec 生成而非手写web.mdcargo web build # 生产 bundle 到 web/dist/ cargo web dev # vite dev server with HMR cargo web check # 仅类型检查gen-api tsc -b cargo web gen-api # 重新生成 web/src/lib/api-generated.ts cargo web install # 在 web/ 中 npm installcargo web是cargo run -p xtask --bin web --的别名每个子命令在web/node_modules/缺失时自动运行npm install。cargo web gen-api从zeroclaw_gateway::openapi::build_spec()进程内渲染 OpenAPI spec、写入target/openapi.json并喂给 openapi-typescript同一个build_spec()运行时服务/api/openapi.json因此它是唯一契约源。编辑流程改crates/zeroclaw-gateway/中的 handler 或 schema →cargo web check重新生成并类型检查 → 更新web/src/消费者 →cargo web build。网关通过static_files.rs从文件系统加载web/dist/Rust 编译与 web 构建解耦。dashboard 面向支持color-mix()与structuredClone()的常青浏览器Chrome/Edge 111、Firefox 113、Safari 16.2。三个默认值与操作速查无论插件作者还是运维记住三个默认值的组合决定了插件系统的行为plugins.enabled默认false——系统关闭任何插件代码都不运行plugins.auto_discover默认false——即使启用自动发现的工具与技能也不加载只有显式声明的通道激活plugins.security.signature_mode默认disabled——本地开发无需密钥管理但共享/生产宿主应设为strict并列出受信任发布者。装载第三方插件的宿主应设置enabled true、signature_mode strict、只列出信任的发布者密钥还需自动发现的工具与技能时再设auto_discover true。只运行自建插件的宿主可在开发期保持disabled共享前收紧。插件工具不在内置只读自动批准集合中非全自治模式下调用会像其他特权工具一样弹出运维批准提示——在工具描述中提前预期这一点。延伸阅读插件作者完整路径Writing a tool plugin从空 crate 到已安装工具、Writing a channel plugin、Writing a memory plugin、Distributing plugins协议规范真源plugin-protocol.md 与wit/v0/下的 WIT 文件WIT 兼容规则见 wit/VERSIONING.md宿主实现crates/zeroclaw-plugins/src/component.rs、host.rs、runtime.rs、wasm_tool.rs、wasm_channel.rs、wasm_memory.rs、signature.rs类型化配置迁移见 migrating-to-typed-config.md构建特性plugins-wasm总开关等价于 runtime-only、plugins-wasm-runtime-only无 JIT仅加载预编译.cwasm、plugins-wasm-craneliftJIT加载时编译.wasm、plugins-wasm-pulley最可移植均委托给zeroclaw-pluginscrate 对应特性并体现在工作区Cargo.toml中【免费下载链接】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），仅供参考