<p align="center">
  <img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
</p>

<h1 align="center">🦀 ZeroClaw — Assistente Pessoal de IA</h1>

<p align="center">
  <strong>Zero overhead. Zero compromisso. 100% Rust. 100% Agnóstico.</strong><br>
  ⚡️ <strong>Roda em hardware de $10 com <5MB de RAM: 99% menos memória que o OpenClaw e 98% mais barato que um Mac mini!</strong>
</p>

<p align="center">
  <a href="LICENSE-APACHE"><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://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
  <a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
  <a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
  <a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
  <a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
  <a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
  <a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
  <a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
  <a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
</p>

<p align="center">
Construído por estudantes e membros das comunidades de Harvard, MIT e Sundai.Club.
</p>

<p align="center">
  🌐 <strong>Idiomas:</strong>
  <a href="README.md">🇺🇸 English</a> ·
  <a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
  <a href="README.ja.md">🇯🇵 日本語</a> ·
  <a href="README.ko.md">🇰🇷 한국어</a> ·
  <a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
  <a href="README.tl.md">🇵🇭 Tagalog</a> ·
  <a href="README.es.md">🇪🇸 Español</a> ·
  <a href="README.pt.md">🇧🇷 Português</a> ·
  <a href="README.it.md">🇮🇹 Italiano</a> ·
  <a href="README.de.md">🇩🇪 Deutsch</a> ·
  <a href="README.fr.md">🇫🇷 Français</a> ·
  <a href="README.ar.md">🇸🇦 العربية</a> ·
  <a href="README.hi.md">🇮🇳 हिन्दी</a> ·
  <a href="README.ru.md">🇷🇺 Русский</a> ·
  <a href="README.bn.md">🇧🇩 বাংলা</a> ·
  <a href="README.he.md">🇮🇱 עברית</a> ·
  <a href="README.pl.md">🇵🇱 Polski</a> ·
  <a href="README.cs.md">🇨🇿 Čeština</a> ·
  <a href="README.nl.md">🇳🇱 Nederlands</a> ·
  <a href="README.tr.md">🇹🇷 Türkçe</a> ·
  <a href="README.uk.md">🇺🇦 Українська</a> ·
  <a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
  <a href="README.th.md">🇹🇭 ไทย</a> ·
  <a href="README.ur.md">🇵🇰 اردو</a> ·
  <a href="README.ro.md">🇷🇴 Română</a> ·
  <a href="README.sv.md">🇸🇪 Svenska</a> ·
  <a href="README.el.md">🇬🇷 Ελληνικά</a> ·
  <a href="README.hu.md">🇭🇺 Magyar</a> ·
  <a href="README.fi.md">🇫🇮 Suomi</a> ·
  <a href="README.da.md">🇩🇰 Dansk</a> ·
  <a href="README.nb.md">🇳🇴 Norsk</a>
</p>

ZeroClaw é um assistente pessoal de IA que você executa nos seus próprios dispositivos. Ele responde nos canais que você já usa (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work e mais). Tem um painel web para controle em tempo real e pode se conectar a periféricos de hardware (ESP32, STM32, Arduino, Raspberry Pi). O Gateway é apenas o plano de controle — o produto é o assistente.

Se você quer um assistente pessoal, para um único usuário, que seja local, rápido e sempre ativo, é isso.

<p align="center">
  <a href="https://zeroclawlabs.ai">Site</a> ·
  <a href="docs/README.md">Documentação</a> ·
  <a href="docs/architecture.md">Arquitetura</a> ·
  <a href="#início-rápido">Primeiros passos</a> ·
  <a href="#migração-do-openclaw">Migração do OpenClaw</a> ·
  <a href="docs/ops/troubleshooting.md">Solução de problemas</a> ·
  <a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
</p>

> **Configuração preferida:** execute `zeroclaw onboard` no seu terminal. O ZeroClaw Onboard guia você passo a passo na configuração do gateway, workspace, canais e provedor. É o caminho de configuração recomendado e funciona no macOS, Linux e Windows (via WSL2). Nova instalação? Comece aqui: [Primeiros passos](#início-rápido)

### Autenticação por assinatura (OAuth)

- **OpenAI Codex** (assinatura ChatGPT)
- **Gemini** (Google OAuth)
- **Anthropic** (chave API ou token de autenticação)

Nota sobre modelos: embora muitos provedores/modelos sejam suportados, para a melhor experiência use o modelo de última geração mais poderoso disponível para você. Veja [Onboarding](#início-rápido).

Configuração de modelos + CLI: [Referência de provedores](docs/reference/api/providers-reference.md)
Rotação de perfis de autenticação (OAuth vs chaves API) + failover: [Failover de modelos](docs/reference/api/providers-reference.md)

## Instalação (recomendada)

Requisito: toolchain estável do Rust. Um único binário, sem dependências de runtime.

### Homebrew (macOS/Linuxbrew)

```bash
brew install zeroclaw
```

### Bootstrap com um clique

```bash
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh
```

`zeroclaw onboard` executa automaticamente após a instalação para configurar seu workspace e provedor.

## Início rápido (TL;DR)

Guia completo para iniciantes (autenticação, pareamento, canais): [Primeiros passos](docs/setup-guides/one-click-bootstrap.md)

```bash
# Instalar + onboard
./install.sh --api-key "sk-..." --provider openrouter

# Iniciar o gateway (servidor webhook + painel web)
zeroclaw gateway                # padrão: 127.0.0.1:42617
zeroclaw gateway --port 0       # porta aleatória (segurança reforçada)

# Falar com o assistente
zeroclaw agent -m "Hello, ZeroClaw!"

# Modo interativo
zeroclaw agent

# Iniciar runtime autônomo completo (gateway + canais + cron + hands)
zeroclaw daemon

# Verificar status
zeroclaw status

# Executar diagnósticos
zeroclaw doctor
```

Atualizando? Execute `zeroclaw doctor` após atualizar.

### A partir do código-fonte (desenvolvimento)

```bash
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

cargo build --release --locked
cargo install --path . --force --locked

zeroclaw onboard
```

> **Alternativa para desenvolvimento (sem instalação global):** prefixe comandos com `cargo run --release --` (exemplo: `cargo run --release -- status`).

## Migração do OpenClaw

O ZeroClaw pode importar seu workspace, memória e configuração do OpenClaw:

```bash
# Pré-visualizar o que será migrado (seguro, somente leitura)
zeroclaw migrate openclaw --dry-run

# Executar a migração
zeroclaw migrate openclaw
```

Isso migra suas entradas de memória, arquivos do workspace e configuração de `~/.openclaw/` para `~/.zeroclaw/`. A configuração é convertida de JSON para TOML automaticamente.

## Padrões de segurança (acesso por DM)

O ZeroClaw conecta-se a superfícies de mensagens reais. Trate DMs recebidas como entrada não confiável.

Guia completo de segurança: [SECURITY.md](SECURITY.md)

Comportamento padrão em todos os canais:

- **Pareamento por DM** (padrão): remetentes desconhecidos recebem um código de pareamento curto e o bot não processa sua mensagem.
- Aprovar com: `zeroclaw pairing approve <channel> <code>` (então o remetente é adicionado a uma lista de permitidos local).
- DMs públicas recebidas requerem uma ativação explícita em `config.toml`.
- Execute `zeroclaw doctor` para detectar políticas de DM arriscadas ou mal configuradas.

**Níveis de autonomia:**

| Nível | Comportamento |
|-------|---------------|
| `ReadOnly` | O agente pode observar mas não agir |
| `Supervised` (padrão) | O agente age com aprovação para operações de risco médio/alto |
| `Full` | O agente age autonomamente dentro dos limites da política |

**Camadas de sandboxing:** isolamento do workspace, bloqueio de traversal de caminhos, listas de comandos permitidos, caminhos proibidos (`/etc`, `/root`, `~/.ssh`), limitação de taxa (máximo de ações/hora, limites de custo/dia).

<!-- BEGIN:WHATS_NEW -->
<!-- END:WHATS_NEW -->

### 📢 Anúncios

Use este quadro para avisos importantes (mudanças incompatíveis, avisos de segurança, janelas de manutenção e bloqueadores de lançamento).

| Data (UTC) | Nível       | Aviso                                                                                                                                                                                                                                                                                                                                                 | Ação                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |   |
| 2026-02-19 | _Crítico_  | **Não somos afiliados** a `openagen/zeroclaw`, `zeroclaw.org` ou `zeroclaw.net`. Os domínios `zeroclaw.org` e `zeroclaw.net` atualmente apontam para o fork `openagen/zeroclaw`, e esse domínio/repositório estão se passando pelo nosso site/projeto oficial.                                                                                       | Não confie em informações, binários, arrecadações de fundos ou anúncios dessas fontes. Use apenas [este repositório](https://github.com/zeroclaw-labs/zeroclaw) e nossas contas sociais verificadas.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 2026-02-21 | _Importante_ | Nosso site oficial agora está no ar: [zeroclawlabs.ai](https://zeroclawlabs.ai). Obrigado pela paciência enquanto preparávamos o lançamento. Continuamos vendo tentativas de falsificação, então **não** participe de atividades de investimento ou arrecadação de fundos usando o nome ZeroClaw, a menos que sejam publicadas através dos nossos canais oficiais.                            | Use [este repositório](https://github.com/zeroclaw-labs/zeroclaw) como a única fonte de verdade. Siga [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Grupo)](https://www.facebook.com/groups/zeroclawlabs) e [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) para atualizações oficiais. |
| 2026-02-19 | _Importante_ | A Anthropic atualizou os termos de Autenticação e Uso de Credenciais em 2026-02-19. Os tokens OAuth do Claude Code (Free, Pro, Max) são destinados exclusivamente ao Claude Code e Claude.ai; usar tokens OAuth do Claude Free/Pro/Max em qualquer outro produto, ferramenta ou serviço (incluindo Agent SDK) não é permitido e pode violar os Termos de Serviço do Consumidor. | Por favor, evite temporariamente as integrações OAuth do Claude Code para prevenir perdas potenciais. Cláusula original: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use).                                                                                                                                                                                                                                                                                                                                                                                    |

## Destaques

- **Runtime leve por padrão** — fluxos de trabalho comuns de CLI e status rodam em poucos megabytes de memória em builds release.
- **Implantação econômica** — projetado para placas de $10 e instâncias pequenas na nuvem, sem dependências pesadas de runtime.
- **Cold start rápido** — runtime Rust com binário único mantém a inicialização de comandos e do daemon quase instantânea.
- **Arquitetura portável** — um binário para ARM, x86 e RISC-V com provedores/canais/ferramentas intercambiáveis.
- **Gateway local-first** — plano de controle único para sessões, canais, ferramentas, cron, SOPs e eventos.
- **Caixa de entrada multicanal** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket e mais.
- **Orquestração multi-agente (Hands)** — enxames de agentes autônomos que rodam por agendamento e ficam mais inteligentes com o tempo.
- **Procedimentos Operacionais Padrão (SOPs)** — automação de fluxos de trabalho orientada por eventos com MQTT, webhook, cron e gatilhos de periféricos.
- **Painel web** — interface web React 19 + Vite com chat em tempo real, navegador de memória, editor de configuração, gerenciador de cron e inspetor de ferramentas.
- **Periféricos de hardware** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO via trait `Peripheral`.
- **Ferramentas de primeira classe** — shell, E/S de arquivos, navegador, git, web fetch/search, MCP, Jira, Notion, Google Workspace e mais de 70 outras.
- **Hooks de ciclo de vida** — intercepte e modifique chamadas LLM, execuções de ferramentas e mensagens em cada estágio.
- **Plataforma de skills** — skills incluídos, comunitários e do workspace com auditoria de segurança.
- **Suporte a túneis** — Cloudflare, Tailscale, ngrok, OpenVPN e túneis personalizados para acesso remoto.

### Por que equipes escolhem o ZeroClaw

- **Leve por padrão:** binário Rust pequeno, inicialização rápida, baixo consumo de memória.
- **Seguro por design:** pareamento, sandboxing rigoroso, listas de permissão explícitas, escopo do workspace.
- **Totalmente intercambiável:** sistemas centrais são traits (provedores, canais, ferramentas, memória, túneis).
- **Sem vendor lock-in:** suporte a provedores compatíveis com OpenAI + endpoints personalizados plugáveis.

## Resumo de benchmarks (ZeroClaw vs OpenClaw, reproduzível)

Benchmark rápido em máquina local (macOS arm64, fev 2026) normalizado para hardware edge de 0.8GHz.

|                           | OpenClaw      | NanoBot        | PicoClaw        | ZeroClaw 🦀          |
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
| **Linguagem**             | TypeScript    | Python         | Go              | **Rust**             |
| **RAM**                   | > 1GB         | > 100MB        | < 10MB          | **< 5MB**            |
| **Inicialização (core 0.8GHz)** | > 500s  | > 30s          | < 1s            | **< 10ms**           |
| **Tamanho do binário**    | ~28MB (dist)  | N/A (Scripts)  | ~8MB            | **~8.8 MB**          |
| **Custo**                 | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Qualquer hardware $10** |

> Notas: Os resultados do ZeroClaw são medidos em builds release usando `/usr/bin/time -l`. O OpenClaw requer o runtime Node.js (tipicamente ~390MB de overhead adicional de memória), enquanto o NanoBot requer o runtime Python. PicoClaw e ZeroClaw são binários estáticos. Os valores de RAM acima são memória em runtime; os requisitos de compilação são maiores.

<p align="center">
  <img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
</p>

### Medição local reproduzível

```bash
cargo build --release
ls -lh target/release/zeroclaw

/usr/bin/time -l target/release/zeroclaw --help
/usr/bin/time -l target/release/zeroclaw status
```

## Tudo o que construímos até agora

### Plataforma central

- Plano de controle Gateway HTTP/WS/SSE com sessões, presença, configuração, cron, webhooks, painel web e pareamento.
- Superfície CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
- Loop de orquestração do agente com despacho de ferramentas, construção de prompts, classificação de mensagens e carregamento de memória.
- Modelo de sessão com aplicação de políticas de segurança, níveis de autonomia e aprovação condicional.
- Wrapper de provedor resiliente com failover, retry e roteamento de modelos em mais de 20 backends LLM.

### Canais

Canais: WhatsApp (nativo), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.

Habilitados por feature gate: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).

### Painel web

Painel web React 19 + Vite 6 + Tailwind CSS 4 servido diretamente pelo Gateway:

- **Dashboard** — visão geral do sistema, status de saúde, uptime, rastreamento de custos
- **Chat do agente** — chat interativo com o agente
- **Memória** — navegar e gerenciar entradas de memória
- **Configuração** — visualizar e editar configuração
- **Cron** — gerenciar tarefas agendadas
- **Ferramentas** — navegar ferramentas disponíveis
- **Logs** — visualizar logs de atividade do agente
- **Custos** — uso de tokens e rastreamento de custos
- **Doctor** — diagnósticos de saúde do sistema
- **Integrações** — status e configuração de integrações
- **Pareamento** — gerenciamento de pareamento de dispositivos

### Alvos de firmware

| Alvo | Plataforma | Propósito |
|------|------------|-----------|
| ESP32 | Espressif ESP32 | Agente periférico sem fio |
| ESP32-UI | ESP32 + Display | Agente com interface visual |
| STM32 Nucleo | STM32 (ARM Cortex-M) | Periférico industrial |
| Arduino | Arduino | Ponte básica de sensores/atuadores |
| Uno Q Bridge | Arduino Uno | Ponte serial para o agente |

### Ferramentas + automação

- **Core:** shell, leitura/escrita/edição de arquivos, operações git, busca glob, busca de conteúdo
- **Web:** controle de navegador, web fetch, web search, captura de tela, informação de imagem, leitura de PDF
- **Integrações:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
- **MCP:** Model Context Protocol tool wrapper + conjuntos de ferramentas deferidos
- **Agendamento:** cron add/remove/update/run, ferramenta de agendamento
- **Memória:** recall, store, forget, knowledge, project intel
- **Avançado:** delegate (agente para agente), swarm, troca/roteamento de modelos, operações de segurança, operações na nuvem
- **Hardware:** board info, memory map, memory read (habilitado por feature gate)

### Runtime + segurança

- **Níveis de autonomia:** ReadOnly, Supervised (padrão), Full.
- **Sandboxing:** isolamento do workspace, bloqueio de traversal de caminhos, listas de comandos permitidos, caminhos proibidos, Landlock (Linux), Bubblewrap.
- **Limitação de taxa:** máximo de ações por hora, máximo de custo por dia (configurável).
- **Aprovação condicional:** aprovação interativa para operações de risco médio/alto.
- **Parada de emergência:** capacidade de desligamento de emergência.
- **129+ testes de segurança** em CI automatizado.

### Operações + empacotamento

- Painel web servido diretamente pelo Gateway.
- Suporte a túneis: Cloudflare, Tailscale, ngrok, OpenVPN, comando personalizado.
- Adaptador de runtime Docker para execução em contêineres.
- CI/CD: beta (automático no push) → stable (dispatch manual) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
- Binários pré-construídos para Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).


## Configuração

`~/.zeroclaw/config.toml` mínimo:

```toml
default_provider = "anthropic"
api_key = "sk-ant-..."
```

Referência completa de configuração: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).

### Configuração de canais

**Telegram:**
```toml
[channels.telegram]
bot_token = "123456:ABC-DEF..."
```

**Discord:**
```toml
[channels.discord]
token = "your-bot-token"
```

**Slack:**
```toml
[channels.slack]
bot_token = "xoxb-..."
app_token = "xapp-..."
```

**WhatsApp:**
```toml
[channels.whatsapp]
enabled = true
```

**Matrix:**
```toml
[channels.matrix]
homeserver_url = "https://matrix.org"
username = "@bot:matrix.org"
password = "..."
```

**Signal:**
```toml
[channels.signal]
phone_number = "+1234567890"
```

### Configuração de túneis

```toml
[tunnel]
kind = "cloudflare"  # ou "tailscale", "ngrok", "openvpn", "custom", "none"
```

Detalhes: [Referência de canais](docs/reference/api/channels-reference.md) · [Referência de configuração](docs/reference/api/config-reference.md)

### Suporte de runtime (atual)

- **`native`** (padrão) — execução direta de processos, caminho mais rápido, ideal para ambientes confiáveis.
- **`docker`** — isolamento completo em contêineres, políticas de segurança forçadas, requer Docker.

Defina `runtime.kind = "docker"` para sandboxing rigoroso ou isolamento de rede.

## Autenticação por assinatura (OpenAI Codex / Claude Code / Gemini)

O ZeroClaw suporta perfis de autenticação nativos de assinatura (multi-conta, criptografados em repouso).

- Arquivo de armazenamento: `~/.zeroclaw/auth-profiles.json`
- Chave de criptografia: `~/.zeroclaw/.secret_key`
- Formato de id do perfil: `<provider>:<profile_name>` (exemplo: `openai-codex:work`)

```bash
# OpenAI Codex OAuth (assinatura ChatGPT)
zeroclaw auth login --provider openai-codex --device-code

# Gemini OAuth
zeroclaw auth login --provider gemini --profile default

# Anthropic setup-token
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization

# Verificar / atualizar / trocar perfil
zeroclaw auth status
zeroclaw auth refresh --provider openai-codex --profile default
zeroclaw auth use --provider openai-codex --profile work

# Executar o agente com autenticação por assinatura
zeroclaw agent --provider openai-codex -m "hello"
zeroclaw agent --provider anthropic -m "hello"
```

## Workspace do agente + skills

Raiz do workspace: `~/.zeroclaw/workspace/` (configurável via config).

Arquivos de prompt injetados:
- `IDENTITY.md` — personalidade e papel do agente
- `USER.md` — contexto e preferências do usuário
- `MEMORY.md` — fatos e lições de longo prazo
- `AGENTS.md` — convenções de sessão e regras de inicialização
- `SOUL.md` — identidade central e princípios operacionais

Skills: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` ou `SKILL.toml`.

```bash
# Listar skills instalados
zeroclaw skills list

# Instalar do git
zeroclaw skills install https://github.com/user/my-skill.git

# Auditoria de segurança antes de instalar
zeroclaw skills audit https://github.com/user/my-skill.git

# Remover um skill
zeroclaw skills remove my-skill
```

## Comandos CLI

```bash
# Gerenciamento do workspace
zeroclaw onboard              # Assistente de configuração guiada
zeroclaw status               # Mostrar status do daemon/agente
zeroclaw doctor               # Executar diagnósticos do sistema

# Gateway + daemon
zeroclaw gateway              # Iniciar servidor gateway (127.0.0.1:42617)
zeroclaw daemon               # Iniciar runtime autônomo completo

# Agente
zeroclaw agent                # Modo de chat interativo
zeroclaw agent -m "message"   # Modo de mensagem única

# Gerenciamento de serviços
zeroclaw service install      # Instalar como serviço do SO (launchd/systemd)
zeroclaw service start|stop|restart|status

# Canais
zeroclaw channel list         # Listar canais configurados
zeroclaw channel doctor       # Verificar saúde dos canais
zeroclaw channel bind-telegram 123456789

# Cron + agendamento
zeroclaw cron list            # Listar trabalhos agendados
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
zeroclaw cron remove <id>

# Memória
zeroclaw memory list          # Listar entradas de memória
zeroclaw memory get <key>     # Recuperar uma memória
zeroclaw memory stats         # Estatísticas de memória

# Perfis de autenticação
zeroclaw auth login --provider <name>
zeroclaw auth status
zeroclaw auth use --provider <name> --profile <profile>

# Periféricos de hardware
zeroclaw hardware discover    # Escanear dispositivos conectados
zeroclaw peripheral list      # Listar periféricos conectados
zeroclaw peripheral flash     # Flashear firmware no dispositivo

# Migração
zeroclaw migrate openclaw --dry-run
zeroclaw migrate openclaw

# Completação de shell
source <(zeroclaw completions bash)
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
```

Referência completa de comandos: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)

<!-- markdownlint-disable MD001 MD024 -->

## Pré-requisitos

<details>
<summary><strong>Windows</strong></summary>

#### Obrigatório

1. **Visual Studio Build Tools** (fornece o linker MSVC e o SDK do Windows):

    ```powershell
    winget install Microsoft.VisualStudio.2022.BuildTools
    ```

    Durante a instalação (ou pelo Visual Studio Installer), selecione a carga de trabalho **"Desenvolvimento para desktop com C++"**.

2. **Toolchain do Rust:**

    ```powershell
    winget install Rustlang.Rustup
    ```

    Após a instalação, abra um novo terminal e execute `rustup default stable` para garantir que o toolchain estável esteja ativo.

3. **Verifique** que ambos estão funcionando:
    ```powershell
    rustc --version
    cargo --version
    ```

#### Opcional

- **Docker Desktop** — necessário apenas se usar o [runtime sandbox com Docker](#suporte-de-runtime-atual) (`runtime.kind = "docker"`). Instale via `winget install Docker.DockerDesktop`.

</details>

<details>
<summary><strong>Linux / macOS</strong></summary>

#### Obrigatório

1. **Ferramentas de compilação essenciais:**
    - **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
    - **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
    - **macOS:** Instale o Xcode Command Line Tools: `xcode-select --install`

2. **Toolchain do Rust:**

    ```bash
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ```

    Veja [rustup.rs](https://rustup.rs) para detalhes.

3. **Verifique** que ambos estão funcionando:
    ```bash
    rustc --version
    cargo --version
    ```

#### Instalador em uma linha

Ou pule os passos acima e instale tudo (dependências do sistema, Rust, ZeroClaw) em um único comando:

```bash
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
```

#### Requisitos de recursos para compilação

Compilar a partir do código-fonte precisa de mais recursos do que executar o binário resultante:

| Recurso        | Mínimo  | Recomendado |
| -------------- | ------- | ----------- |
| **RAM + swap** | 2 GB    | 4 GB+       |
| **Disco livre**| 6 GB    | 10 GB+      |

Se seu host está abaixo do mínimo, use binários pré-construídos:

```bash
./install.sh --prefer-prebuilt
```

Para exigir instalação somente de binários sem compilação de fallback:

```bash
./install.sh --prebuilt-only
```

#### Opcional

- **Docker** — necessário apenas se usar o [runtime sandbox com Docker](#suporte-de-runtime-atual) (`runtime.kind = "docker"`). Instale via seu gerenciador de pacotes ou [docker.com](https://docs.docker.com/engine/install/).

> **Nota:** O `cargo build --release` padrão usa `codegen-units=1` para reduzir a pressão máxima de compilação. Para builds mais rápidos em máquinas potentes, use `cargo build --profile release-fast`.

</details>

<!-- markdownlint-enable MD001 MD024 -->

### Binários pré-construídos

Os assets de release são publicados para:

- Linux: `x86_64`, `aarch64`, `armv7`
- macOS: `x86_64`, `aarch64`
- Windows: `x86_64`

Baixe os últimos assets em:
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>

## Documentação

Use estes recursos quando tiver passado pelo fluxo de onboarding e quiser a referência mais aprofundada.

- Comece com o [índice de docs](docs/README.md) para navegação e "o que está onde."
- Leia a [visão geral da arquitetura](docs/architecture.md) para o modelo completo do sistema.
- Use a [referência de configuração](docs/reference/api/config-reference.md) quando precisar de cada chave e exemplo.
- Execute o Gateway conforme o livro com o [runbook operacional](docs/ops/operations-runbook.md).
- Siga o [ZeroClaw Onboard](#início-rápido) para uma configuração guiada.
- Depure falhas comuns com o [guia de solução de problemas](docs/ops/troubleshooting.md).
- Revise a [orientação de segurança](docs/security/README.md) antes de expor qualquer coisa.

### Documentação de referência

- Hub de documentação: [docs/README.md](docs/README.md)
- TOC unificado de docs: [docs/SUMMARY.md](docs/SUMMARY.md)
- Referência de comandos: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
- Referência de configuração: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
- Referência de provedores: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
- Referência de canais: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
- Runbook operacional: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
- Solução de problemas: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)

### Documentação de colaboração

- Guia de contribuição: [CONTRIBUTING.md](CONTRIBUTING.md)
- Política de fluxo de trabalho de PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
- Guia de fluxo de trabalho CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
- Manual do revisor: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
- Política de divulgação de segurança: [SECURITY.md](SECURITY.md)
- Template de documentação: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)

### Implantação + operações

- Guia de implantação em rede: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
- Manual de agente proxy: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
- Guias de hardware: [docs/hardware/README.md](docs/hardware/README.md)

## Smooth Crab 🦀

O ZeroClaw foi construído para o caranguejo suave 🦀, um assistente de IA rápido e eficiente. Construído por Argenis De La Rosa e a comunidade.

- [zeroclawlabs.ai](https://zeroclawlabs.ai)
- [@zeroclawlabs](https://x.com/zeroclawlabs)

## Apoie o ZeroClaw

Se o ZeroClaw ajuda no seu trabalho e você quer apoiar o desenvolvimento contínuo, pode doar aqui:

<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>

### 🙏 Agradecimentos especiais

Um sincero agradecimento às comunidades e instituições que inspiram e impulsionam este trabalho de código aberto:

- **Harvard University** — por fomentar a curiosidade intelectual e empurrar os limites do possível.
- **MIT** — por defender o conhecimento aberto, o código aberto e a crença de que a tecnologia deve ser acessível a todos.
- **Sundai Club** — pela comunidade, a energia e o impulso incansável de construir coisas que importam.
- **O Mundo e Além** 🌍✨ — a cada contribuidor, sonhador e construtor que faz do código aberto uma força para o bem. Isto é para você.

Estamos construindo abertamente porque as melhores ideias vêm de todos os lugares. Se você está lendo isto, faz parte disso. Bem-vindo. 🦀❤️

## Contribuir

Novo no ZeroClaw? Procure issues rotulados como [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — veja nosso [Guia de contribuição](CONTRIBUTING.md#first-time-contributors) para saber como começar. PRs com IA/vibe-coded são bem-vindos! 🤖

Veja [CONTRIBUTING.md](CONTRIBUTING.md) e [CLA.md](docs/contributing/cla.md). Implemente um trait, envie um PR:

- Guia de fluxo de trabalho CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
- Novo `Provider` → `src/providers/`
- Novo `Channel` → `src/channels/`
- Novo `Observer` → `src/observability/`
- Novo `Tool` → `src/tools/`
- Novo `Memory` → `src/memory/`
- Novo `Tunnel` → `src/tunnel/`
- Novo `Peripheral` → `src/peripherals/`
- Novo `Skill` → `~/.zeroclaw/workspace/skills/<name>/`

<!-- BEGIN:RECENT_CONTRIBUTORS -->
<!-- END:RECENT_CONTRIBUTORS -->

## ⚠️ Repositório oficial e aviso de falsificação

**Este é o único repositório oficial do ZeroClaw:**

> https://github.com/zeroclaw-labs/zeroclaw

Qualquer outro repositório, organização, domínio ou pacote que afirme ser "ZeroClaw" ou implique afiliação com ZeroClaw Labs **não é autorizado e não é afiliado a este projeto**. Forks não autorizados conhecidos serão listados em [TRADEMARK.md](docs/maintainers/trademark.md).

Se encontrar falsificação ou uso indevido de marca, por favor [abra um issue](https://github.com/zeroclaw-labs/zeroclaw/issues).

---

## Licença

O ZeroClaw tem licença dupla para máxima abertura e proteção dos contribuidores:

| Licença | Caso de uso |
|---|---|
| [MIT](LICENSE-MIT) | Código aberto, pesquisa, acadêmico, uso pessoal |
| [Apache 2.0](LICENSE-APACHE) | Proteção de patentes, institucional, implantação comercial |

Você pode escolher qualquer uma das licenças. **Os contribuidores automaticamente concedem direitos sob ambas** — veja [CLA.md](docs/contributing/cla.md) para o acordo completo de contribuidores.

### Marca registrada

O nome e logo do **ZeroClaw** são marcas registradas da ZeroClaw Labs. Esta licença não concede permissão para usá-los para implicar endosso ou afiliação. Veja [TRADEMARK.md](docs/maintainers/trademark.md) para usos permitidos e proibidos.

### Proteções para contribuidores

- Você **mantém o copyright** das suas contribuições
- **Concessão de patentes** (Apache 2.0) protege você de reclamações de patentes de outros contribuidores
- Suas contribuições são **permanentemente atribuídas** no histórico de commits e [NOTICE](NOTICE)
- Nenhum direito de marca registrada é transferido ao contribuir

---

**ZeroClaw** — Zero overhead. Zero compromisso. Implante em qualquer lugar. Troque qualquer coisa. 🦀

## Contribuidores

<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
</a>

Esta lista é gerada a partir do gráfico de contribuidores do GitHub e é atualizada automaticamente.

## Histórico de estrelas

<p align="center">
  <a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
    <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
     <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
     <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
    </picture>
  </a>
</p>
