IronClaw

Seu assistente pessoal de IA seguro, sempre ao seu lado

Início Rápido do Reborn • Filosofia • Funcionalidades • Instalação • Configuração • Segurança • Arquitetura

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 e Uso Legado do IronClaw.

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:

$ 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:

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/HEAD/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

Instalar via script de shell (macOS, Linux, Windows/WSL)

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

Instalar via Homebrew (macOS/Linux)

```sh brew install ironclaw ```

Compile o código fonte (Cargo no Windows, Linux, macOS)

Instale-o com cargo, apenas certifique-se de ter o Rust 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;"

`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.

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

ironclaw

Mais Populares

Configuração

Segurança

Sandbox WASM

Componentes Principais

Uso do IronClaw```bash

First-time setup (configures database, auth, etc.)

Start interactive REPL

REPL with debug logging

Herança do OpenClaw

Licença