Seguro, sistema operacional privado de agente de IA com armazenamento criptografado local, autenticação OAuth/SSO, controle de acesso baseado em políticas e estrutura extensível de criação de ferramentas para implantações pessoais e de produção.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/11714/bb76296dac15b760d2c93e6ac7df91bf41355b07c7c7fdecb15799be57ccf96c.png" alt="IronClaw" width="200"/>
</p>
<h1 align="center">IronClaw</h1>
<p align="center">
<strong>Seu assistente pessoal de IA seguro, sempre ao seu lado</strong>
</p>
<p align="center">
<a href="#license"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
<a href="https://t.me/ironclawAI"><img src="https://img.shields.io/badge/Telegram-@ironclawAI-26A5E4?style=flat&logo=telegram&logoColor=white" alt="Telegram: @ironclawAI" /></a>
<a href="https://www.reddit.com/r/ironclawAI/"><img src="https://img.shields.io/badge/Reddit-r/ironclawAI-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/ironclawAI" /></a>
<a href="https://gitcgr.com/nearai/ironclaw">
<img src="https://gitcgr.com/badge/nearai/ironclaw.svg" alt="gitcgr" />
</a>
</p>
<p align="center">
<a href="https://github.com/nearai/ironclaw/blob/main/README.md">Inglês</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.zh-CN.md">简体中文</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.ru.md">Русский</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.ja.md">日本語</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.ko.md">한국어</a>
</p>
<p align="center">
<a href="#ironclaw-reborn-quick-start">Início Rápido do Reborn</a> •
<a href="#philosophy">Filosofia</a> •
<a href="#features">Funcionalidades</a> •
<a href="#installation">Instalação</a> •
<a href="#configuration">Configuração</a> •
<a href="#security">Segurança</a> •
<a href="#architecture">Arquitetura</a>
</p>
---
## IronClaw Reborn Início Rápido
IronClaw Reborn é o runtime independente no branch `reborn-integration`.
Ele usa o binário separado `ironclaw-reborn` do pacote
`ironclaw_reborn_cli` e uma raiz de estado separada do Reborn. Ele não usa
o diretório de estado legado `ironclaw` como sua raiz de configuração.
Para o binário `ironclaw` mais antigo, veja [Instalação](#installation) e
[Uso Legado do IronClaw](#legacy-ironclaw-usage).
### Construir ou executar o binário
A partir da raiz do repositório:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- --help
```
Ou construa-o primeiro:```bash
cargo build -p ironclaw_reborn_cli --bin ironclaw-reborn
./target/debug/ironclaw-reborn --help
```
A home padrão do Reborn é `$HOME/.ironclaw/reborn`. Substitua-o por um caminho absoluto quando quiser um estado isolado:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config path
```
`config path` and `doctor` são diagnósticos seguros; eles relatam o home resolvido, perfil, `config.toml`, `providers.json` e `v1_state: not-used`.
Eles não criam estado do Reborn nem arquivos de configuração seed.
### Configurar a rota do modelo
A maneira nativa da CLI de configurar a rota padrão do modelo do Reborn é:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models set-provider openai --model gpt-5-mini
```
Isso escreve `$IRONCLAW_REBORN_HOME/config.toml` com `[llm.default]` e o nome da env-var da credencial do provedor. Verifique com:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models status
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models list openai
```
Para OpenAI, defina o valor secreto no ambiente antes de começar:```bash
export OPENAI_API_KEY="sk-..."
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- run --message "hello"
```
Omita `--message` ou use `repl` para uma sessão interativa de stdin:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- repl
```
### Forma do `config.toml`
`config init` cria arquivos iniciais editáveis:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config init
```
Ele escreve:
- `$IRONCLAW_REBORN_HOME/config.toml`
- `$IRONCLAW_REBORN_HOME/providers.json`
Uma rota de modelo minimamente configurada se parece com:```toml
[llm.default]
provider_id = "openai"
model = "gpt-5-mini"
api_key_env = "OPENAI_API_KEY"
```
`config.toml` pode também incluir secções opcionais como `[boot]`,
`[identity]`, `[runner]` e `[skills]`; `config init` escreve orientação comentada para os campos suportados.
Se `config.toml` faltar, a primeira inicialização do runtime stateful através de `run`,
`repl` ou `serve` cria um ficheiro esparso com `api_version` e o perfil de boot seguro
`local-dev`. Comandos só de leitura e `run --dry-run` permanecem sem efeitos colaterais. Seleções de ambiente avulsas como
`IRONCLAW_REBORN_PROFILE=local-dev-yolo` não são persistidas no ficheiro criado.
Importante: `api_key_env` é o nome de uma variável de ambiente, não o segredo
em si. Reborn rejeita valores com forma de segredo inline no `config.toml` e
`providers.json`.
O armazenamento de produção usa o mesmo padrão exclusivo de env. Uma configuração de produção do Reborn
pode nomear a variável URL do PostgreSQL, mas não deve conter a URL em bruto:```toml
[storage]
backend = "postgres"
url_env = "IRONCLAW_REBORN_POSTGRES_URL"
secret_master_key_env = "IRONCLAW_REBORN_SECRET_MASTER_KEY"
# Optional; defaults to 2. Keep below the PostgreSQL server or managed
# session-pool cap after reserving capacity for restarts and operator sessions.
pool_max_size = 2
[policy]
deployment_mode = "hosted_multi_tenant"
default_profile = "secure_default"
```
Definir `IRONCLAW_REBORN_POSTGRES_URL` no ambiente do processo e definir `IRONCLAW_REBORN_SECRET_MASTER_KEY` como material de chave criptográfica independente. Provedores PostgreSQL remotos gerenciados devem usar TLS, por exemplo, anexando `sslmode=require`. A execução de produção (`run`) também requer uma seção `[policy]` explícita. O primeiro bloco de inicialização de produção suporta políticas de tempo de execução que não exigem uma vinculação de processo de sandbox de locatário.
Assim que `[llm.default]` existir, essa configuração seleciona o provedor. `LLM_BACKEND` é apenas um fallback de ambiente quando nenhum slot LLM padrão está configurado. Para trocar de provedor após escrever a configuração, use `models set-provider <provedor>` ou edite `[llm.default].provider_id`.
### Seleção de modelo apenas por ambiente
Se `$IRONCLAW_REBORN_HOME/config.toml` estiver ausente ou não tiver `[llm.default]`, o Reborn pode resolver o LLM a partir de variáveis de ambiente. Uma configuração inicial esparsa não inclui `[llm.default]`, portanto a seleção de modelo apenas por ambiente continua funcionando:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-env-only"
export LLM_BACKEND=openai
export OPENAI_API_KEY="sk-..."
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- run --message "hello"
```
Common provider env vars:
| Provider | Selector | Required env |
| --- | --- | --- |
| OpenAI | `LLM_BACKEND=openai` | `OPENAI_API_KEY`; opcional `OPENAI_MODEL`, `OPENAI_BASE_URL` |
| Anthropic | `LLM_BACKEND=anthropic` | `ANTHROPIC_API_KEY`; opcional `ANTHROPIC_MODEL`, `ANTHROPIC_BASE_URL` |
| OpenAI-compatible | `LLM_BACKEND=openai_compatible` | `LLM_BASE_URL`; opcional `LLM_API_KEY`, `LLM_MODEL` |
| OpenRouter | `LLM_BACKEND=openrouter` | `OPENROUTER_API_KEY`; opcional `OPENROUTER_MODEL` |
| Ollama | `LLM_BACKEND=ollama` | nenhuma chave; opcional `OLLAMA_BASE_URL`, `OLLAMA_MODEL` |
| Codex auth | `LLM_BACKEND=openai_codex` | `LLM_USE_CODEX_AUTH=true` ou `CODEX_AUTH_PATH`; opcional `OPENAI_CODEX_MODEL` |
Use `models list <provider>` para ver os metadados exatos do provedor compilados no branch atual.
### Variáveis de inicialização
| Variável | Finalidade |
| --- | --- |
| `IRONCLAW_REBORN_HOME` | Raiz absoluta do estado do Reborn. Padrão: `$HOME/.ironclaw/reborn`. O resolvedor rejeita caminhos inseguros e aliases de raiz de estado v1, como `$HOME/.ironclaw`. |
| `IRONCLAW_REBORN_PROFILE` | Seletor de perfil de inicialização. Valores suportados: `local-dev`, `local-dev-yolo`, `hosted-single-tenant`, `hosted-single-tenant-volume`, `production`, `migration-dry-run`. |
| `IRONCLAW_REBORN_POSTGRES_URL` | URL de armazenamento PostgreSQL de produção quando `[storage].backend = "postgres"` e `[storage].url_env` nomeia esta variável. Mantenha-a fora de `config.toml`; provedores remotos devem usar TLS. |
| `IRONCLAW_REBORN_POSTGRES_POOL_MAX_SIZE` | Substituição opcional para o tamanho do pool do cliente PostgreSQL do Reborn. Use quando um provedor gerenciado impõe um limite pequeno de pool de sessão. |
| `IRONCLAW_FILESYSTEM_POSTGRES_MIGRATION_CONNECT_MAX_WAIT_SECS` | Janela de espera opcional na inicialização para tentativas de reconexão da migração do sistema de arquivos Postgres. Padrão: 300 segundos. |
| `IRONCLAW_REBORN_SECRET_MASTER_KEY` | Chave mestra secreta do Reborn de produção quando `[storage].secret_master_key_env` nomeia esta variável. Mantenha-a independente da URL do banco de dados e fora de `config.toml`. |
| `IRONCLAW_REBORN_LOG` | Filtro de rastreamento para o binário do Reborn, por exemplo `debug,ironclaw_runner=trace`. |
Atualmente, `run` e `repl` suportam composição de tempo de execução local através de `local-dev`, `local-dev-yolo` e `hosted-single-tenant-volume`. `hosted-single-tenant-volume` usa o substrato libSQL de tempo de execução local em `$IRONCLAW_REBORN_HOME/hosted-single-tenant-volume`, resolve a política de tempo de execução segura padrão hospedada e desativa ferramentas baseadas em processo, como shell. Destina-se a implantações de pré-visualização de único locatário em um volume persistente, não como a composição completa de produção PostgreSQL.
`local-dev-yolo` concede acesso de host confiável de laptop e deve ser confirmado explicitamente:```bash
export IRONCLAW_REBORN_PROFILE=local-dev-yolo
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- repl --confirm-host-access
```
### Serviço WebUI
O Reborn WebUI é compilado por trás da funcionalidade Cargo `webui-v2-beta`. Compilações com esta funcionalidade requerem Node.js 22 com Corepack/pnpm para que o Cargo possa gerar e incorporar o bundle SPA. Compile ou execute o binário com essa funcionalidade para ativar o comando `serve`:
```bash
$ cargo run --features webui-v2-beta -- serve
``````bash
cargo run -q -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn -- serve --help
cargo build -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn
```
O ouvinte do WebUI usa como padrão `127.0.0.1:3000`. O serviço requer um token env-bearer e um ID de usuário na inicialização. Também precisa da rota do modelo da seção anterior, incluindo a variável de ambiente de credencial desse provedor:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
export OPENAI_API_KEY="sk-..." # or the required env var for your configured provider
export IRONCLAW_REBORN_WEBUI_TOKEN="$(openssl rand -hex 32)"
export IRONCLAW_REBORN_WEBUI_USER_ID="reborn-cli"
cargo run -q -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn -- serve
```
Configuração equivalente do listener `config.toml`:```toml
[webui]
listen_host = "127.0.0.1"
listen_port = 3000
env_token_var = "IRONCLAW_REBORN_WEBUI_TOKEN"
env_user_id_var = "IRONCLAW_REBORN_WEBUI_USER_ID"
allowed_origins = ["http://127.0.0.1:3000", "http://localhost:3000"]
canonical_host = "127.0.0.1:3000"
```
`env_token_var` e `env_user_id_var` são nomes de variáveis de ambiente. Mantenha o token e o ID de usuário reais nas variáveis de ambiente.
Variáveis de ambiente obrigatórias da WebUI:
| Variável | Propósito |
| --- | --- |
| `IRONCLAW_REBORN_WEBUI_TOKEN` | Token de portador para requisições da WebUI. Se o SSO estiver ativado, ele também assina sessões e deve ter pelo menos 32 bytes. |
| `IRONCLAW_REBORN_WEBUI_USER_ID` | ID de proprietário/usuário do Reborn para requisições de bearer via variável de ambiente. Se `[identity].default_owner` estiver configurado, deve corresponder a este valor. |
Variáveis de ambiente opcionais da WebUI OAuth:
| Variável | Propósito |
| --- | --- |
| `IRONCLAW_REBORN_WEBUI_BASE_URL` | URL base pública usada para login na WebUI e callbacks OAuth de autenticação de produto. Implantações não loopback devem usar `https://`. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_ID` | Ativa o SSO do Google quando definido. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_SECRET` | Obrigatório quando o SSO do Google está ativado. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_ALLOWED_HD` | Restrição opcional de domínio hospedado do Google. |
| `IRONCLAW_REBORN_WEBUI_GITHUB_CLIENT_ID` | Ativa o SSO do GitHub quando definido. |
| `IRONCLAW_REBORN_WEBUI_GITHUB_CLIENT_SECRET` | Obrigatório quando o SSO do GitHub está ativado. |
| `IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINS` | Obrigatório quando qualquer provedor de SSO está ativado. Domínios de e-mail verificados separados por vírgula. |
| `IRONCLAW_REBORN_WEBUI_OAUTH_HTTP_TIMEOUT_SECS` | Substituição opcional de timeout HTTP do OAuth. |
Para o SSO do Google, crie um cliente web OAuth do Google e registre o URI de redirecionamento do Reborn WebUI como:```text
{IRONCLAW_REBORN_WEBUI_BASE_URL}/auth/callback/google
```
Por exemplo, com `IRONCLAW_REBORN_WEBUI_BASE_URL=https://ironclaw.example.com`, o URI de redirecionamento autorizado no Google Cloud é:```text
https://ironclaw.example.com/auth/callback/google
```
Os fluxos de configuração OAuth do Notion MCP e de outros produtos de autenticação usam o mesmo URL base público da WebUI ao registrar URLs de callback do provedor. Não inclua uma barra final em `IRONCLAW_REBORN_WEBUI_BASE_URL`; o Reborn a remove antes de construir URLs de callback. Se o URL base for omitido, o Reborn usa o endereço real do listener, como `http://127.0.0.1:3000`, que é adequado apenas para testes OAuth de loopback/local. Implantações OAuth públicas ou não loopback devem definir um URL base `https://`. Ambiente completo de inicialização do Google SSO:```bash
export IRONCLAW_REBORN_HOME="/var/lib/ironclaw-reborn"
export IRONCLAW_REBORN_PROFILE=local-dev
export OPENAI_API_KEY="sk-..." # or the required env var for your configured provider
export IRONCLAW_REBORN_WEBUI_TOKEN="$(openssl rand -hex 32)"
export IRONCLAW_REBORN_WEBUI_USER_ID="reborn-cli"
export IRONCLAW_REBORN_WEBUI_BASE_URL="https://ironclaw.example.com"
export IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINS="example.com,team.example.com"
export IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_ID="..."
export IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_SECRET="..."
cargo run -q -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn -- serve --host 0.0.0.0 --port 3000
```
`IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINS` é a lista de permissão de admissão real. O `hd` do Google é apenas uma dica opcional de domínio hospedado do lado do provedor; não confie nele em vez da lista de domínios permitidos do Reborn. `IRONCLAW_REBORN_HOME` seleciona a raiz de estado/configuração para este serviço. `IRONCLAW_REBORN_PROFILE` assume o padrão `local-dev`; `local-dev-yolo` concede acesso de host de laptop confiável e não pode ser servido em um host não loopback.
Use `serve --host <ip> --port <port>` para substituir o listener a partir da CLI. Vincular a um host não loopback é sensível à produção. O modo de serviço `local-dev-yolo` também requer `--confirm-host-access` e recusa hosts não loopback.
### Serviço Slack
O suporte ao Slack é compilado sob o recurso Cargo `slack-v2-host-beta`. Esse recurso inclui `webui-v2-beta`, então o Slack é executado no mesmo comando `serve`:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
export OPENAI_API_KEY="sk-..." # or the required env var for your configured provider
export IRONCLAW_REBORN_WEBUI_TOKEN="$(openssl rand -hex 32)"
export IRONCLAW_REBORN_WEBUI_USER_ID="reborn-cli"
export IRONCLAW_REBORN_SLACK_ENABLED="true"
cargo run -q -p ironclaw_reborn_cli --features slack-v2-host-beta --bin ironclaw-reborn -- serve
```
Ative o Slack definindo `IRONCLAW_REBORN_SLACK_ENABLED=true`, ou adicionando uma seção `[slack]` ao `config.toml`:```toml
[slack]
enabled = true
```
A variável de ambiente substitui apenas a porta de habilitação da rota do Slack: `true`/`1` monta o Slack, enquanto `false`/`0` atua como um interruptor de desligamento da implantação. Após o servidor iniciar, configure os ids do aplicativo Slack, token do bot, segredo de assinatura e mapeamentos de canal a partir da configuração de canal da WebUI.
Configurações obrigatórias do Slack:
| Nome | Propósito |
| --- | --- |
| `[slack].enabled = true` ou `IRONCLAW_REBORN_SLACK_ENABLED=true` | Monta a rota do Slack durante `serve`. |
| Configuração do workspace do Slack na WebUI | Armazena ids de instalação do Slack, mapeamentos de canal e segredos do bot/assinatura do Slack. |
Notas mais detalhadas de configuração do Slack estão em
[`docs/reborn/setup-slack-for-reborn-binary.md`](https://github.com/nearai/ironclaw/blob/main/docs/reborn/setup-slack-for-reborn-binary.md).
## Filosofia
IronClaw é construído com base em um princípio simples: **seu assistente de IA deve trabalhar para você, não contra você**.
Em um mundo onde sistemas de IA são cada vez mais opacos em relação ao tratamento de dados e alinhados com interesses corporativos, a IronClaw adota uma abordagem diferente:
- **Seus dados permanecem seus** - Todas as informações são armazenadas localmente, criptografadas e nunca saem do seu controle
- **Transparência por design** - Código aberto, auditável, sem telemetria oculta ou coleta de dados
- **Capacidades de autoexpansão** - Construa novas ferramentas em tempo real sem esperar por atualizações do fornecedor
- **Defesa em profundidade** - Múltiplas camadas de segurança protegem contra injeção de prompt e exfiltração de dados
IronClaw é o assistente de IA que você pode realmente confiar com sua vida pessoal e profissional.
## Recursos
### Segurança em Primeiro Lugar
- **Sandbox WASM** - Ferramentas não confiáveis são executadas em contêineres WebAssembly isolados com permissões baseadas em capacidades
- **Proteção de Credenciais** - Segredos nunca são expostos às ferramentas; injetados no limite do host com detecção de vazamentos
- **Defesa contra Injeção de Prompt** - Detecção de padrões, sanitização de conteúdo e aplicação de políticas
- **Lista de Permissões de Endpoint** - Requisições HTTP apenas para hosts e caminhos explicitamente aprovados
### Sempre Disponível
- **Multicanal** - REPL, webhooks HTTP, canais WASM (Telegram, Slack) e gateway web
- **Sandbox Docker** - Execução isolada em contêiner com tokens por tarefa e padrão orquestrador/trabalhador
- **Gateway Web** - Interface do navegador com streaming em tempo real SSE/WebSocket
- **Rotinas** - Agendamentos cron, gatilhos de eventos, manipuladores de webhook para automação em segundo plano
- **Sistema de Heartbeat** - Execução proativa em segundo plano para tarefas de monitoramento e manutenção
- **Trabalhos Paralelos** - Lida com múltiplas requisições concorrentemente com contextos isolados
- **Autorreparo** - Detecção e recuperação automática de operações travadas
### Autoexpansão
- **Construção Dinâmica de Ferramentas** - Descreva o que você precisa, e a IronClaw constrói como uma ferramenta WASM
- **Protocolo MCP** - Conecte-se a servidores do Model Context Protocol para capacidades adicionais
- **Arquitetura de Plugins** - Adicione novas ferramentas e canais WASM sem reiniciar
### Memória Persistente
- **Pesquisa Híbrida** - Pesquisa de texto completo + vetorial usando Fusão de Classificação Recíproca
- **Sistema de Arquivos do Workspace** - Armazenamento flexível baseado em caminhos para notas, logs e contexto
- **Arquivos de Identidade** - Mantenha personalidade e preferências consistentes entre sessões
## Instalação
### Pré-requisitos
- Rust 1.96+
- PostgreSQL 15+ com extensão [pgvector](https://github.com/pgvector/pgvector)
- Node.js 22+ com Corepack/pnpm para builds de código-fonte que habilitam o recurso `webui-v2-beta`
- Conta NEAR AI (autenticação tratada pelo assistente de configuração)
- `libclang` e um toolchain C funcional se você compilar o caminho de voz/SILK do WeChat a partir do código-fonte
## Baixar ou Compilar
Visite a [página de Releases](https://github.com/nearai/ironclaw/releases/) para ver as últimas atualizações.
<details>
<summary>Instalar via Instalador do Windows (Windows)</summary>
Baixe o [Instalador do Windows](https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-x86_64-pc-windows-msvc.msi) e execute-o.
</details>
<details>
<summary>Instalar via script powershell (Windows)</summary>```sh
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
```
</details>
<details>
<summary>Instalar via script de shell (macOS, Linux, Windows/WSL)</summary>```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
```
</details>
<details>
<summary>Instalar via Homebrew (macOS/Linux)</summary>```sh
brew install ironclaw
```
</details>
<details>
<summary>Compile o código fonte (Cargo no Windows, Linux, macOS)</summary>
Instale-o com `cargo`, apenas certifique-se de ter o [Rust](https://rustup.rs) instalado no seu computador.```bash
# Clone the repository
git clone https://github.com/nearai/ironclaw.git
cd ironclaw
# Build
cargo build --release
# Run tests
cargo test
```
Para **lançamento completo** (após modificar as fontes de canais), execute `./scripts/build-all.sh` para reconstruir os canais primeiro.
> **Opcional:** Notas de voz do WeChat (`audio/silk`) exigem o auxiliar independente
> `ironclaw-silk-decoder` para serem transcritíveis. Ele está excluído da
> construção padrão do workspace porque `silk-codec` puxa `bindgen`/`libclang`.
> Compile-o separadamente com `./crates/ironclaw_silk_decoder/build.sh` (requer
> libclang + uma toolchain C) e coloque o binário resultante no `$PATH`, ao lado
> do binário `ironclaw`, ou aponte para `IRONCLAW_SILK_DECODER`. Sem ele,
> as mensagens de voz ainda são entregues — apenas como blobs `audio/silk` brutos.
</details>
### Configuração do Banco de Dados```bash
# Create database
createdb ironclaw
# Enable pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
```
## Configuração
Execute o assistente de configuração para configurar o IronClaw:```bash
ironclaw onboard
```
O assistente lida com a conexão ao banco de dados, autenticação NEAR AI (via OAuth do navegador) e criptografia de segredos (usando seu chaveiro do sistema). As configurações são persistidas no banco de dados conectado; variáveis de inicialização (por exemplo, `DATABASE_URL`, `LLM_BACKEND`) são escritas em `~/.ironclaw/.env` para que estejam disponíveis antes da conexão com o banco de dados.
### Provedores LLM Alternativos
O IronClaw usa NEAR AI como padrão, mas suporta vários provedores LLM de forma nativa. Os provedores integrados incluem **Anthropic**, **OpenAI**, **GitHub Copilot**, **Google Gemini**, **MiniMax**, **Mistral** e **Ollama** (local). Serviços compatíveis com OpenAI, como **OpenRouter** (300+ modelos), **Together AI**, **Fireworks AI** e servidores auto-hospedados (**vLLM**, **LiteLLM**), também são suportados.
Selecione seu provedor no assistente, ou defina variáveis de ambiente diretamente:```env
# Example: MiniMax (built-in, 204K context)
LLM_BACKEND=minimax
MINIMAX_API_KEY=...
# Example: OpenAI-compatible endpoint
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4
```
Veja [docs/capabilities/llm-providers.md](https://github.com/nearai/ironclaw/blob/main/docs/capabilities/llm-providers.md) para um guia completo de provedores.
## Segurança
IronClaw implementa defesa em profundidade para proteger seus dados e evitar uso indevido.
### Sandbox WASM
Todas as ferramentas não confiáveis são executadas em contêineres WebAssembly isolados:
- **Permissões baseadas em capacidades** - Adesão explícita para HTTP, segredos, invocação de ferramentas
- **Lista de permissões de endpoints** - Requisições HTTP apenas para hosts/caminhos aprovados
- **Injeção de credenciais** - Segredos injetados no limite do host, nunca expostos ao código WASM
- **Detecção de vazamentos** - Escaneia requisições e respostas em busca de tentativas de exfiltração de segredos
- **Limitação de taxa** - Limites de requisição por ferramenta para evitar abuso
- **Limites de recursos** - Restrições de memória, CPU e tempo de execução```
WASM ──► Allowlist ──► Leak Scan ──► Credential ──► Execute ──► Leak Scan ──► WASM
Validator (request) Injector Request (response)
```
### Defesa contra Injeção de Prompt
O conteúdo externo passa por múltiplas camadas de segurança:
- Detecção baseada em padrões de tentativas de injeção
- Sanitização e escape de conteúdo
- Regras de política com níveis de gravidade (Bloquear/Avisar/Revisar/Sanitizar)
- Empacotamento de saída da ferramenta para injeção segura no contexto do LLM
### Proteção de Dados
- Todos os dados armazenados localmente no seu banco de dados PostgreSQL
- Segredos criptografados com AES-256-GCM
- Sem telemetria, análises ou compartilhamento de dados
- Registro de auditoria completo de todas as execuções de ferramentas
## Arquitetura```
┌────────────────────────────────────────────────────────────────┐
│ Channels │
│ ┌──────┐ ┌──────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ REPL │ │ HTTP │ │WASM Channels│ │ Web Gateway │ │
│ └──┬───┘ └──┬───┘ └──────┬──────┘ │ (SSE + WS) │ │
│ │ │ │ └──────┬──────┘ │
│ └─────────┴──────────────┴────────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ Agent Loop │ Intent routing │
│ └────┬──────────┬───┘ │
│ │ │ │
│ ┌──────────▼────┐ ┌──▼───────────────┐ │
│ │ Scheduler │ │ Routines Engine │ │
│ │(parallel jobs)│ │(cron, event, wh) │ │
│ └──────┬────────┘ └────────┬─────────┘ │
│ │ │ │
│ ┌─────────────┼────────────────────┘ │
│ │ │ │
│ ┌───▼─────┐ ┌────▼────────────────┐ │
│ │ Local │ │ Orchestrator │ │
│ │Workers │ │ ┌───────────────┐ │ │
│ │(in-proc)│ │ │ Docker Sandbox│ │ │
│ └───┬─────┘ │ │ Containers │ │ │
│ │ │ │ ┌───────────┐ │ │ │
│ │ │ │ │Worker / CC│ │ │ │
│ │ │ │ └───────────┘ │ │ │
│ │ │ └───────────────┘ │ │
│ │ └─────────┬───────────┘ │
│ └──────────────────┤ │
│ │ │
│ ┌───────────▼──────────┐ │
│ │ Tool Registry │ │
│ │ Built-in, MCP, WASM │ │
│ └──────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
```
### Componentes Principais
| Componente | Finalidade |
|-----------|---------|
| **Agent Loop** | Manipulação principal de mensagens e coordenação de tarefas |
| **Router** | Classifica a intenção do usuário (comando, consulta, tarefa) |
| **Scheduler** | Gerencia execução paralela de tarefas com prioridades |
| **Worker** | Executa tarefas com raciocínio de LLM e chamadas de ferramentas |
| **Orchestrator** | Ciclo de vida do contêiner, proxy de LLM, autenticação por tarefa |
| **Web Gateway** | Interface de navegador com chat, memória, tarefas, logs, extensões, rotinas |
| **Routines Engine** | Tarefas em segundo plano agendadas (cron) e reativas (evento, webhook) |
| **Workspace** | Memória persistente com busca híbrida |
| **Safety Layer** | Defesa contra injeção de prompt e sanitização de conteúdo |
## Uso do IronClaw```bash
# First-time setup (configures database, auth, etc.)
ironclaw onboard
# Start interactive REPL
cargo run
# REPL with debug logging
RUST_LOG=ironclaw=debug cargo run
```
## Desenvolvimento```bash
# Format code
cargo fmt
# Lint
cargo clippy --all --benches --tests --examples --all-features
# Run tests
createdb ironclaw_test
cargo test
# Run specific test
cargo test test_name
```
- **Canais**: Veja [docs/channels/overview.mdx](https://github.com/nearai/ironclaw/blob/main/docs/channels/overview.mdx) para configuração do Telegram, Discord e outros canais.
- **Alterando fontes de canais**: Execute `./channels-src/telegram/build.sh` antes de `cargo build` para que o WASM atualizado seja incluído.
## Herança do OpenClaw
IronClaw é uma reimplementação em Rust inspirada pelo [OpenClaw](https://github.com/openclaw/openclaw). Veja [FEATURE_PARITY.md](https://github.com/nearai/ironclaw/blob/main/FEATURE_PARITY.md) para a matriz de acompanhamento completa.
Principais diferenças:
- **Rust vs TypeScript** - Desempenho nativo, segurança de memória, binário único
- **Sandbox WASM vs Docker** - Leve, segurança baseada em capacidades
- **PostgreSQL vs SQLite** - Persistência pronta para produção
- **Design centrado em segurança** - Múltiplas camadas de defesa, proteção de credenciais
## Licença
Licenciado sob uma das seguintes opções:
- Apache License, Version 2.0 ([LICENSE-APACHE](https://github.com/nearai/ironclaw/blob/main/LICENSE-APACHE))
- MIT License ([LICENSE-MIT](https://github.com/nearai/ironclaw/blob/main/LICENSE-MIT))
à sua escolha.