WASM 工具运行在 wasmtime 沙箱中。除 IronClaw 暴露的宿主函数外，网络、文件系统、凭据等能力都必须在 capabilities.json 中显式声明。
对于需要强隔离的自定义集成，这是 IronClaw 推荐方案。
工作流程
LLM 选择工具
↓
IronClaw 加载 WASM 模块（缓存或磁盘）
↓
模块在 wasmtime 沙箱执行
↓
网络请求经由代理
↓
代理校验域名白名单
↓
代理从加密存储注入凭据
↓
响应返回模块
↓
输出经 Safety Layer 清洗
↓
LLM 接收结果
沙箱机制
Fuel 计量
每条 WASM 指令都会消耗 fuel，耗尽即终止，防止死循环。
# 默认 100,000,000
export WASM_FUEL_LIMIT=100000000
内存限制
模块使用固定线性内存，超限会 trap 并终止。
# 默认 16 MB
export WASM_MEMORY_LIMIT=16777216
速率限制
每个工具可配置独立限流：
{
"rate_limit": {
"requests_per_minute": 60,
"requests_per_day": 1000
}
}
capabilities.json
每个 WASM 工具都需与 .wasm 放在同目录，并包含 capabilities.json：
{
"name": "my-tool",
"version": "0.1.0",
"description": "Fetches data from example.com API",
"network": {
"allowed_hosts": ["api.example.com", "auth.example.com"]
},
"filesystem": {
"read": ["/workspace/data/*"],
"write": ["/workspace/output/*"]
},
"credentials": [
{
"name": "example_api_key",
"inject_as": "Authorization",
"format": "Bearer {value}"
}
],
"rate_limit": {
"requests_per_minute": 30,
"requests_per_day": 500
}
}
网络白名单
network.allowed_hosts 决定允许访问的域名。未命中白名单的请求会在建立连接前被拒绝。
文件系统访问
默认无主机文件系统权限，filesystem.read/filesystem.write 声明的路径才会挂载进沙箱。
凭据注入
凭据不会进入 WASM 内存。模块发出请求后，由代理在转发时注入 Header。
宿主函数
| 函数 | 说明 |
|---|
log(level, message) | 写结构化日志 |
now_unix_secs() | 返回当前 Unix 时间戳 |
workspace_read(path) | 读取工作区文档 |
workspace_write(path, content) | 写入工作区文档 |
工具发现与安装
启动时从以下目录发现工具：
~/.ironclaw/tools/<workspace>/tools/
每个工具目录至少包含：
<toolname>.wasmcapabilities.json
安装示例：
ironclaw tool install ./my-tool.wasm
ironclaw tool install https://example.com/tools/my-tool.wasm
ironclaw tool list
安全说明
安装来自不可信来源的 WASM 工具前，请先审阅 capabilities.json。
凭据仅由代理注入到出站请求，模块无法直接读取密钥存储。
模块不能执行 shell、fork 子进程或加载动态库。
无限循环会在 fuel 用尽时被强制终止。
