ironclaw ironclaw-v1.0.0 — Secure, private AI agent operating system with local encrypted storage, OAuth/SSO authentication, policy-based access control, and extensible tool-building framework for personal and production deployments.

IronClaw

安全可靠的个人 AI 助手，始终站在你这边

English | 简体中文 | Русский | 日本語 | 한국어

设计理念 • 功能特性 • 安装 • 配置 • 安全机制 • 系统架构

设计理念

IronClaw 基于一个简单的原则：你的 AI 助手应该为你服务，而不是与你为敌。

在 AI 系统对数据处理日益不透明、与企业利益捆绑的今天，IronClaw 选择了一条不同的路：

数据归你所有 — 所有信息存储在本地，加密保护，始终在你掌控之下
透明至上 — 完全开源，可审计，没有隐藏的遥测或数据收集
自主扩展 — 随时构建新工具，无需等待供应商更新
纵深防御 — 多层安全机制抵御提示注入和数据泄露

IronClaw 是一个你真正可以信赖的 AI 助手，无论是个人生活还是工作。

功能特性

安全优先

WASM 沙箱 — 不受信任的工具在隔离的 WebAssembly 容器中运行，采用基于能力的权限模型
凭据保护 — 密钥永远不会暴露给工具；在宿主边界注入并进行泄露检测
提示注入防御 — 模式检测、内容清理和策略执行
端点白名单 — HTTP 请求仅限于明确批准的主机和路径

随时可用

多渠道接入 — REPL、HTTP webhook、WASM 渠道（Telegram、Slack）和 Web 网关
Docker 沙箱 — 隔离的容器执行，支持每任务令牌和编排器/工作器模式
Web 网关 — 浏览器 UI，支持实时 SSE/WebSocket 流式传输
定时任务 — Cron 调度、事件触发器、Webhook 处理器，实现后台自动化
心跳系统 — 主动后台执行，用于监控和维护任务
并行任务 — 使用隔离上下文同时处理多个请求
自修复 — 自动检测并恢复卡住的操作

自主扩展

动态工具构建 — 描述你的需求，IronClaw 会将其构建为 WASM 工具
MCP 协议 — 连接模型上下文协议（Model Context Protocol）服务器以获取额外能力
插件架构 — 无需重启即可加载新的 WASM 工具和渠道

持久记忆

混合搜索 — 全文搜索 + 向量搜索，采用倒数排名融合（Reciprocal Rank Fusion）
工作空间文件系统 — 灵活的基于路径的存储，用于笔记、日志和上下文
身份文件 — 跨会话保持一致的个性和偏好设置

安装

前置要求

Rust 1.85+
PostgreSQL 15+，需安装 pgvector 扩展
NEAR AI 账户（通过设置向导进行身份验证）
如果从源码构建微信语音 / SILK 路径，还需要安装 libclang 和可用的 C 编译工具链

下载或编译

访问 Releases 页面查看最新版本。

通过 Windows 安装程序安装 (Windows)

下载 Windows 安装程序并运行。

通过 PowerShell 脚本安装 (Windows)

irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex

通过 Shell 脚本安装 (macOS、Linux、Windows/WSL)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh

通过 Homebrew 安装 (macOS/Linux)

brew install ironclaw

从源码编译 (Windows、Linux、macOS 上使用 Cargo)

确保你已安装 Rust。

# 克隆仓库
git clone https://github.com/nearai/ironclaw.git
cd ironclaw

# 编译
cargo build --release

# 运行测试
cargo test

如需进行完整发布构建（修改了渠道源码后），先运行 ./scripts/build-all.sh 重新编译渠道。

可选： 微信语音消息（audio/silk）需要独立的 ironclaw-silk-decoder 辅助二进制才能被转写。该工具因为依赖 silk-codec（会引入 bindgen / libclang），已被排除在默认工作区之外。请使用 ./crates/ironclaw_silk_decoder/build.sh 单独编译（需要 libclang 与 C 编译器），再把生成的二进制放到 $PATH、ironclaw 同级目录，或通过 IRONCLAW_SILK_DECODER 环境变量指定路径。即使没有它，语音消息仍会送达，只是会以原始的 audio/silk 数据块形式呈现。

数据库设置

# 创建数据库
createdb ironclaw

# 启用 pgvector 扩展
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

配置

运行设置向导来配置 IronClaw：

ironclaw onboard

向导将引导你完成数据库连接、NEAR AI 身份验证（通过浏览器 OAuth）和密钥加密（使用系统钥匙串）。设置会保存在数据库中；引导变量（如 DATABASE_URL、LLM_BACKEND）写入 ~/.ironclaw/.env，以便在数据库连接前可用。

替代 LLM 提供商

IronClaw 默认使用 NEAR AI，但开箱即用地支持多种 LLM 提供商。内置提供商包括 Anthropic、OpenAI、GitHub Copilot、Google Gemini、MiniMax、Mistral 和 Ollama（本地部署）。同时也支持 OpenAI 兼容服务，如 OpenRouter（300+ 模型）、Together AI、Fireworks AI 以及自托管服务器（vLLM、LiteLLM）。

在向导中选择你的提供商，或直接设置环境变量：

# 示例：MiniMax（内置，204K 上下文）
LLM_BACKEND=minimax
MINIMAX_API_KEY=...

# 示例：OpenAI 兼容端点
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4

详见 docs/capabilities/llm-providers.md 获取完整的提供商指南。

安全机制

IronClaw 实现了纵深防御策略来保护你的数据并防止滥用。

WASM 沙箱

所有不受信任的工具都在隔离的 WebAssembly 容器中运行：

基于能力的权限 — 明确授权 HTTP、密钥、工具调用等能力
端点白名单 — HTTP 请求仅限已批准的主机和路径
凭据注入 — 密钥在宿主边界注入，永远不会暴露给 WASM 代码
泄露检测 — 扫描请求和响应以防止密钥外泄
速率限制 — 每个工具独立的请求限制，防止滥用
资源限制 — 内存、CPU 和执行时间约束

WASM ──► 白名单  ──► 泄露扫描 ──► 凭据  ──► 执行  ──► 泄露扫描 ──► WASM
         验证器     (请求)      注入器    请求     (响应)

提示注入防御

外部内容需通过多个安全层：

基于模式的注入尝试检测
内容清理和转义
带严重级别的策略规则（阻止/警告/审核/清理）
工具输出包装，确保安全的 LLM 上下文注入

数据保护

所有数据存储在本地 PostgreSQL 数据库中
密钥使用 AES-256-GCM 加密
无遥测、无分析、无数据共享
所有工具执行的完整审计日志