> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WASM 工具

> 通过 WebAssembly（wasmtime）在沙箱中执行工具

WASM 工具运行在 [wasmtime](https://wasmtime.dev/) 沙箱中。除 IronClaw 暴露的宿主函数外，网络、文件系统、凭据等能力都必须在 `capabilities.json` 中显式声明。

对于需要强隔离的自定义集成，这是 IronClaw 推荐方案。

***

## 工作流程

```
LLM 选择工具
    ↓
IronClaw 加载 WASM 模块（缓存或磁盘）
    ↓
模块在 wasmtime 沙箱执行
    ↓
网络请求经由代理
    ↓
代理校验域名白名单
    ↓
代理从加密存储注入凭据
    ↓
响应返回模块
    ↓
输出经 Safety Layer 清洗
    ↓
LLM 接收结果
```

***

## 沙箱机制

### Fuel 计量

每条 WASM 指令都会消耗 fuel，耗尽即终止，防止死循环。

```bash theme={null}
# 默认 100,000,000
export WASM_FUEL_LIMIT=100000000
```

### 内存限制

模块使用固定线性内存，超限会 trap 并终止。

```bash theme={null}
# 默认 16 MB
export WASM_MEMORY_LIMIT=16777216
```

### 速率限制

每个工具可配置独立限流：

```json theme={null}
{
  "rate_limit": {
    "requests_per_minute": 60,
    "requests_per_day": 1000
  }
}
```

***

## capabilities.json

每个 WASM 工具都需与 `.wasm` 放在同目录，并包含 `capabilities.json`：

```json theme={null}
{
  "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>.wasm`
* `capabilities.json`

安装示例：

```bash theme={null}
ironclaw tool install ./my-tool.wasm
ironclaw tool install https://example.com/tools/my-tool.wasm
ironclaw tool list
```

***

## 安全说明

<Warning>
  安装来自不可信来源的 WASM 工具前，请先审阅 `capabilities.json`。
</Warning>

<AccordionGroup>
  <Accordion title="凭据注入是单向的" icon="lock">
    凭据仅由代理注入到出站请求，模块无法直接读取密钥存储。
  </Accordion>

  <Accordion title="无法派生系统进程" icon="shield">
    模块不能执行 shell、fork 子进程或加载动态库。
  </Accordion>

  <Accordion title="Fuel 防止拒绝服务" icon="zap">
    无限循环会在 fuel 用尽时被强制终止。
  </Accordion>
</AccordionGroup>