<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 — Osobisty Asystent AI</h1>

<p align="center">
  <strong>Zero narzutu. Zero kompromisów. 100% Rust. 100% Agnostyczny.</strong><br>
  ⚡️ <strong>Działa na sprzęcie za $10 z <5MB RAM: To 99% mniej pamięci niż OpenClaw i 98% taniej niż 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">
Stworzone przez studentów i członków społeczności Harvard, MIT i Sundai.Club.
</p>

<p align="center">
  🌐 <strong>Języki:</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 to osobisty asystent AI, który uruchamiasz na własnych urządzeniach. Odpowiada na kanałach, których już używasz (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work i więcej). Posiada panel webowy do kontroli w czasie rzeczywistym i może łączyć się z peryferiami sprzętowymi (ESP32, STM32, Arduino, Raspberry Pi). Gateway to tylko warstwa sterowania — produktem jest asystent.

Jeśli szukasz osobistego, jednoosobowego asystenta, który działa lokalnie, szybko i jest zawsze dostępny — to jest to.

<p align="center">
  <a href="https://zeroclawlabs.ai">Strona internetowa</a> ·
  <a href="docs/README.md">Dokumentacja</a> ·
  <a href="docs/architecture.md">Architektura</a> ·
  <a href="#szybki-start">Rozpocznij</a> ·
  <a href="#migracja-z-openclaw">Migracja z OpenClaw</a> ·
  <a href="docs/ops/troubleshooting.md">Rozwiązywanie problemów</a> ·
  <a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
</p>

> **Zalecana konfiguracja:** uruchom `zeroclaw onboard` w terminalu. ZeroClaw Onboard prowadzi Cię krok po kroku przez konfigurację gateway, workspace, kanałów i dostawcy. Jest to zalecana ścieżka konfiguracji i działa na macOS, Linux i Windows (przez WSL2). Nowa instalacja? Zacznij tutaj: [Rozpocznij](#szybki-start)

### Uwierzytelnianie subskrypcyjne (OAuth)

- **OpenAI Codex** (subskrypcja ChatGPT)
- **Gemini** (Google OAuth)
- **Anthropic** (klucz API lub token autoryzacyjny)

Uwaga dotycząca modeli: chociaż obsługiwanych jest wielu dostawców/modeli, dla najlepszego doświadczenia używaj najsilniejszego dostępnego modelu najnowszej generacji. Zobacz [Onboarding](#szybki-start).

Konfiguracja modeli + CLI: [Dokumentacja dostawców](docs/reference/api/providers-reference.md)
Rotacja profili autoryzacyjnych (OAuth vs klucze API) + failover: [Failover modeli](docs/reference/api/providers-reference.md)

## Instalacja (zalecana)

Środowisko uruchomieniowe: stabilny toolchain Rust. Pojedynczy plik binarny, brak zależności runtime.

### Homebrew (macOS/Linuxbrew)

```bash
brew install zeroclaw
```

### Instalacja jednym kliknięciem

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

`zeroclaw onboard` uruchamia się automatycznie po instalacji, aby skonfigurować workspace i dostawcę.

## Szybki start (TL;DR)

Pełny przewodnik dla początkujących (autoryzacja, parowanie, kanały): [Rozpocznij](docs/setup-guides/one-click-bootstrap.md)

```bash
# Instalacja + onboarding
./install.sh --api-key "sk-..." --provider openrouter

# Uruchom gateway (serwer webhook + panel webowy)
zeroclaw gateway                # domyślnie: 127.0.0.1:42617
zeroclaw gateway --port 0       # losowy port (wzmocnione bezpieczeństwo)

# Porozmawiaj z asystentem
zeroclaw agent -m "Hello, ZeroClaw!"

# Tryb interaktywny
zeroclaw agent

# Uruchom pełne autonomiczne środowisko (gateway + kanały + cron + hands)
zeroclaw daemon

# Sprawdź status
zeroclaw status

# Uruchom diagnostykę
zeroclaw doctor
```

Aktualizujesz? Uruchom `zeroclaw doctor` po aktualizacji.

### Ze źródła (rozwój)

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

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

zeroclaw onboard
```

> **Tryb deweloperski (bez globalnej instalacji):** poprzedź komendy `cargo run --release --` (przykład: `cargo run --release -- status`).

## Migracja z OpenClaw

ZeroClaw może zaimportować Twój workspace, pamięć i konfigurację OpenClaw:

```bash
# Podgląd tego, co zostanie zmigrowane (bezpieczne, tylko odczyt)
zeroclaw migrate openclaw --dry-run

# Uruchom migrację
zeroclaw migrate openclaw
```

Migruje wpisy pamięci, pliki workspace i konfigurację z `~/.openclaw/` do `~/.zeroclaw/`. Konfiguracja jest automatycznie konwertowana z JSON do TOML.

## Domyślne ustawienia bezpieczeństwa (dostęp DM)

ZeroClaw łączy się z prawdziwymi platformami komunikacyjnymi. Traktuj przychodzące DM jako niezaufane dane wejściowe.

Pełny przewodnik bezpieczeństwa: [SECURITY.md](SECURITY.md)

Domyślne zachowanie na wszystkich kanałach:

- **Parowanie DM** (domyślne): nieznani nadawcy otrzymują krótki kod parowania i bot nie przetwarza ich wiadomości.
- Zatwierdź za pomocą: `zeroclaw pairing approve <channel> <code>` (wtedy nadawca jest dodawany do lokalnej listy dozwolonych).
- Publiczne przychodzące DM wymagają jawnej zgody w `config.toml`.
- Uruchom `zeroclaw doctor`, aby wykryć ryzykowne lub błędnie skonfigurowane polityki DM.

**Poziomy autonomii:**

| Poziom | Zachowanie |
|--------|------------|
| `ReadOnly` | Agent może obserwować, ale nie działać |
| `Supervised` (domyślny) | Agent działa z zatwierdzeniem dla operacji średniego/wysokiego ryzyka |
| `Full` | Agent działa autonomicznie w granicach polityki |

**Warstwy sandboxingu:** izolacja workspace, blokowanie przechodzenia ścieżek, lista dozwolonych poleceń, zabronione ścieżki (`/etc`, `/root`, `~/.ssh`), ograniczenie szybkości (maks. akcji/godzinę, limity kosztów/dzień).

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

### 📢 Ogłoszenia

Użyj tej tablicy do ważnych ogłoszeń (zmiany łamiące, porady bezpieczeństwa, okna serwisowe i blokery wydań).

| Data (UTC) | Poziom       | Ogłoszenie                                                                                                                                                                                                                                                                                                                                                 | Działanie                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |   |
| 2026-02-19 | _Krytyczny_  | **Nie jesteśmy powiązani** z `openagen/zeroclaw`, `zeroclaw.org` ani `zeroclaw.net`. Domeny `zeroclaw.org` i `zeroclaw.net` obecnie kierują do forka `openagen/zeroclaw`, a ta domena/repozytorium podszywają się pod naszą oficjalną stronę/projekt.                                                                                       | Nie ufaj informacjom, plikom binarnym, zbiórkom funduszy ani ogłoszeniom z tych źródeł. Używaj wyłącznie [tego repozytorium](https://github.com/zeroclaw-labs/zeroclaw) i naszych zweryfikowanych kont społecznościowych.                                                                                                                                                                                                                                                                                                                                                                       |
| 2026-02-21 | _Ważny_ | Nasza oficjalna strona internetowa jest teraz dostępna: [zeroclawlabs.ai](https://zeroclawlabs.ai). Dziękujemy za cierpliwość podczas przygotowywania premiery. Nadal obserwujemy próby podszywania się, więc **nie** dołączaj do żadnych inwestycji ani zbiórek funduszy pod nazwą ZeroClaw, chyba że zostały opublikowane przez nasze oficjalne kanały.                            | Używaj [tego repozytorium](https://github.com/zeroclaw-labs/zeroclaw) jako jedynego źródła prawdy. Śledź [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Grupa)](https://www.facebook.com/groups/zeroclawlabs) i [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) po oficjalne aktualizacje. |
| 2026-02-19 | _Ważny_ | Anthropic zaktualizował warunki uwierzytelniania i użytkowania poświadczeń 2026-02-19. Tokeny OAuth Claude Code (Free, Pro, Max) są przeznaczone wyłącznie dla Claude Code i Claude.ai; używanie tokenów OAuth z Claude Free/Pro/Max w jakimkolwiek innym produkcie, narzędziu lub usłudze (w tym Agent SDK) nie jest dozwolone i może naruszać Warunki korzystania z usługi. | Proszę tymczasowo unikać integracji OAuth Claude Code, aby zapobiec potencjalnym stratom. Oryginalna klauzula: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use).                                                                                                                                                                                                                                                                                                                                                    |

## Najważniejsze cechy

- **Lekkie środowisko uruchomieniowe domyślnie** — typowe workflow CLI i statusu działają w kopercie pamięci kilku megabajtów na buildach release.
- **Ekonomiczne wdrożenie** — zaprojektowane dla płytek za $10 i małych instancji chmurowych, bez ciężkich zależności runtime.
- **Szybki zimny start** — jednoplikowe środowisko Rust utrzymuje start komend i demona niemal natychmiastowy.
- **Przenośna architektura** — jeden plik binarny na ARM, x86 i RISC-V z wymiennymi dostawcami/kanałami/narzędziami.
- **Gateway lokalny** — pojedyncza warstwa sterowania dla sesji, kanałów, narzędzi, cron, SOP i zdarzeń.
- **Wielokanałowa skrzynka odbiorcza** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket i więcej.
- **Orkiestracja wielu agentów (Hands)** — autonomiczne roje agentów, które działają według harmonogramu i stają się inteligentniejsze z czasem.
- **Standardowe Procedury Operacyjne (SOP)** — automatyzacja workflow sterowana zdarzeniami z wyzwalaczami MQTT, webhook, cron i peryferiami.
- **Panel webowy** — interfejs React 19 + Vite z czatem w czasie rzeczywistym, przeglądarką pamięci, edytorem konfiguracji, menedżerem cron i inspektorem narzędzi.
- **Peryferia sprzętowe** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO przez trait `Peripheral`.
- **Narzędzia pierwszej klasy** — shell, plik I/O, przeglądarka, git, web fetch/search, MCP, Jira, Notion, Google Workspace i 70+ więcej.
- **Hooki cyklu życia** — przechwytuj i modyfikuj wywołania LLM, wykonania narzędzi i wiadomości na każdym etapie.
- **Platforma umiejętności** — wbudowane, społecznościowe i workspace skills z audytem bezpieczeństwa.
- **Obsługa tuneli** — Cloudflare, Tailscale, ngrok, OpenVPN i niestandardowe tunele do zdalnego dostępu.

### Dlaczego zespoły wybierają ZeroClaw

- **Lekki domyślnie:** mały plik binarny Rust, szybki start, niskie zużycie pamięci.
- **Bezpieczny z założenia:** parowanie, ścisły sandboxing, jawne listy dozwolonych, izolacja workspace.
- **W pełni wymienny:** podstawowe systemy to traity (dostawcy, kanały, narzędzia, pamięć, tunele).
- **Brak vendor lock-in:** obsługa dostawców kompatybilnych z OpenAI + podłączalne niestandardowe endpointy.

## Porównanie wydajności (ZeroClaw vs OpenClaw, odtwarzalne)

Szybki benchmark na maszynie lokalnej (macOS arm64, luty 2026) znormalizowany dla sprzętu edge 0.8GHz.

|                           | OpenClaw      | NanoBot        | PicoClaw        | ZeroClaw 🦀          |
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
| **Język**                 | TypeScript    | Python         | Go              | **Rust**             |
| **RAM**                   | > 1GB         | > 100MB        | < 10MB          | **< 5MB**            |
| **Start (rdzeń 0.8GHz)** | > 500s        | > 30s          | < 1s            | **< 10ms**           |
| **Rozmiar binarki**       | ~28MB (dist)  | N/A (Skrypty)  | ~8MB            | **~8.8 MB**          |
| **Koszt**                 | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Dowolny sprzęt $10** |

> Uwagi: Wyniki ZeroClaw są mierzone na buildach release przy użyciu `/usr/bin/time -l`. OpenClaw wymaga środowiska Node.js (typowo ~390MB dodatkowego narzutu pamięci), natomiast NanoBot wymaga środowiska Python. PicoClaw i ZeroClaw to statyczne pliki binarne. Powyższe wartości RAM dotyczą pamięci runtime; wymagania kompilacji są wyższe.

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

### Odtwarzalny pomiar lokalny

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

## Wszystko, co do tej pory zbudowaliśmy

### Platforma podstawowa

- Gateway HTTP/WS/SSE warstwa sterowania z sesjami, obecnością, konfiguracją, cron, webhookami, panelem webowym i parowaniem.
- Interfejs CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
- Pętla orkiestracji agenta z dispatchem narzędzi, konstrukcją promptów, klasyfikacją wiadomości i ładowaniem pamięci.
- Model sesji z egzekwowaniem polityki bezpieczeństwa, poziomami autonomii i bramkowaniem zatwierdzeń.
- Odporny wrapper dostawcy z failoverem, ponawianiem i routingiem modeli na 20+ backendach LLM.

### Kanały

Kanały: WhatsApp (natywny), 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.

Za bramkami feature: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).

### Panel webowy

Panel webowy React 19 + Vite 6 + Tailwind CSS 4 serwowany bezpośrednio z Gateway:

- **Dashboard** — przegląd systemu, status zdrowia, uptime, śledzenie kosztów
- **Czat z agentem** — interaktywny czat z agentem
- **Pamięć** — przeglądanie i zarządzanie wpisami pamięci
- **Konfiguracja** — podgląd i edycja konfiguracji
- **Cron** — zarządzanie zaplanowanymi zadaniami
- **Narzędzia** — przeglądanie dostępnych narzędzi
- **Logi** — podgląd logów aktywności agenta
- **Koszty** — użycie tokenów i śledzenie kosztów
- **Doctor** — diagnostyka zdrowia systemu
- **Integracje** — status i konfiguracja integracji
- **Parowanie** — zarządzanie parowaniem urządzeń

### Cele firmware

| Cel | Platforma | Przeznaczenie |
|-----|-----------|---------------|
| ESP32 | Espressif ESP32 | Bezprzewodowy agent peryferyjny |
| ESP32-UI | ESP32 + Wyświetlacz | Agent z interfejsem wizualnym |
| STM32 Nucleo | STM32 (ARM Cortex-M) | Peryferia przemysłowe |
| Arduino | Arduino | Podstawowy mostek czujników/aktuatorów |
| Uno Q Bridge | Arduino Uno | Mostek szeregowy do agenta |

### Narzędzia + automatyzacja

- **Podstawowe:** shell, odczyt/zapis/edycja plików, operacje git, wyszukiwanie glob, wyszukiwanie treści
- **Web:** sterowanie przeglądarką, web fetch, wyszukiwanie web, zrzut ekranu, info o obrazie, odczyt PDF
- **Integracje:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
- **MCP:** wrapper narzędzi Model Context Protocol + odroczone zestawy narzędzi
- **Planowanie:** cron add/remove/update/run, narzędzie planowania
- **Pamięć:** recall, store, forget, knowledge, project intel
- **Zaawansowane:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
- **Sprzęt:** board info, memory map, memory read (za bramką feature)

### Środowisko uruchomieniowe + bezpieczeństwo

- **Poziomy autonomii:** ReadOnly, Supervised (domyślny), Full.
- **Sandboxing:** izolacja workspace, blokowanie przechodzenia ścieżek, listy dozwolonych poleceń, zabronione ścieżki, Landlock (Linux), Bubblewrap.
- **Ograniczenie szybkości:** maks. akcji na godzinę, maks. koszt na dzień (konfigurowalne).
- **Bramkowanie zatwierdzeń:** interaktywne zatwierdzanie operacji średniego/wysokiego ryzyka.
- **E-stop:** możliwość awaryjnego wyłączenia.
- **129+ testów bezpieczeństwa** w automatycznym CI.

### Operacje + pakowanie

- Panel webowy serwowany bezpośrednio z Gateway.
- Obsługa tuneli: Cloudflare, Tailscale, ngrok, OpenVPN, niestandardowe polecenie.
- Adapter runtime Docker do konteneryzowanego wykonywania.
- CI/CD: beta (auto na push) → stable (ręczny dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
- Gotowe pliki binarne dla Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).


## Konfiguracja

Minimalna `~/.zeroclaw/config.toml`:

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

Pełna dokumentacja konfiguracji: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).

### Konfiguracja kanałów

**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"
```

### Konfiguracja tunelu

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

Szczegóły: [Dokumentacja kanałów](docs/reference/api/channels-reference.md) · [Dokumentacja konfiguracji](docs/reference/api/config-reference.md)

### Obsługa runtime (aktualnie)

- **`native`** (domyślny) — bezpośrednie wykonywanie procesów, najszybsza ścieżka, idealne dla zaufanych środowisk.
- **`docker`** — pełna izolacja kontenerowa, wymuszone polityki bezpieczeństwa, wymaga Docker.

Ustaw `runtime.kind = "docker"` dla ścisłego sandboxingu lub izolacji sieciowej.

## Uwierzytelnianie subskrypcyjne (OpenAI Codex / Claude Code / Gemini)

ZeroClaw obsługuje natywne profile autoryzacyjne subskrypcji (wiele kont, szyfrowanie w spoczynku).

- Plik przechowywania: `~/.zeroclaw/auth-profiles.json`
- Klucz szyfrowania: `~/.zeroclaw/.secret_key`
- Format ID profilu: `<provider>:<profile_name>` (przykład: `openai-codex:work`)

```bash
# OpenAI Codex OAuth (subskrypcja 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

# Sprawdź / odśwież / przełącz profil
zeroclaw auth status
zeroclaw auth refresh --provider openai-codex --profile default
zeroclaw auth use --provider openai-codex --profile work

# Uruchom agenta z autoryzacją subskrypcji
zeroclaw agent --provider openai-codex -m "hello"
zeroclaw agent --provider anthropic -m "hello"
```

## Workspace agenta + umiejętności

Katalog główny workspace: `~/.zeroclaw/workspace/` (konfigurowalne przez config).

Wstrzykiwane pliki promptów:
- `IDENTITY.md` — osobowość i rola agenta
- `USER.md` — kontekst i preferencje użytkownika
- `MEMORY.md` — długoterminowe fakty i lekcje
- `AGENTS.md` — konwencje sesji i reguły inicjalizacji
- `SOUL.md` — podstawowa tożsamość i zasady działania

Umiejętności: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` lub `SKILL.toml`.

```bash
# Lista zainstalowanych umiejętności
zeroclaw skills list

# Instalacja z git
zeroclaw skills install https://github.com/user/my-skill.git

# Audyt bezpieczeństwa przed instalacją
zeroclaw skills audit https://github.com/user/my-skill.git

# Usuń umiejętność
zeroclaw skills remove my-skill
```

## Komendy CLI

```bash
# Zarządzanie workspace
zeroclaw onboard              # Kreator konfiguracji z przewodnikiem
zeroclaw status               # Pokaż status demona/agenta
zeroclaw doctor               # Uruchom diagnostykę systemu

# Gateway + demon
zeroclaw gateway              # Uruchom serwer gateway (127.0.0.1:42617)
zeroclaw daemon               # Uruchom pełne autonomiczne środowisko

# Agent
zeroclaw agent                # Tryb interaktywnego czatu
zeroclaw agent -m "message"   # Tryb pojedynczej wiadomości

# Zarządzanie usługami
zeroclaw service install      # Zainstaluj jako usługę OS (launchd/systemd)
zeroclaw service start|stop|restart|status

# Kanały
zeroclaw channel list         # Lista skonfigurowanych kanałów
zeroclaw channel doctor       # Sprawdź zdrowie kanałów
zeroclaw channel bind-telegram 123456789

# Cron + planowanie
zeroclaw cron list            # Lista zaplanowanych zadań
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
zeroclaw cron remove <id>

# Pamięć
zeroclaw memory list          # Lista wpisów pamięci
zeroclaw memory get <key>     # Pobierz wspomnienie
zeroclaw memory stats         # Statystyki pamięci

# Profile autoryzacyjne
zeroclaw auth login --provider <name>
zeroclaw auth status
zeroclaw auth use --provider <name> --profile <profile>

# Peryferia sprzętowe
zeroclaw hardware discover    # Skanuj podłączone urządzenia
zeroclaw peripheral list      # Lista podłączonych peryferiów
zeroclaw peripheral flash     # Flash firmware na urządzenie

# Migracja
zeroclaw migrate openclaw --dry-run
zeroclaw migrate openclaw

# Uzupełnianie powłoki
source <(zeroclaw completions bash)
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
```

Pełna dokumentacja komend: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)

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

## Wymagania wstępne

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

#### Wymagane

1. **Visual Studio Build Tools** (zapewnia linker MSVC i Windows SDK):

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

    Podczas instalacji (lub przez Visual Studio Installer) wybierz workload **"Desktop development with C++"**.

2. **Toolchain Rust:**

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

    Po instalacji otwórz nowy terminal i uruchom `rustup default stable`, aby upewnić się, że aktywny jest stabilny toolchain.

3. **Sprawdź**, czy oba działają:
    ```powershell
    rustc --version
    cargo --version
    ```

#### Opcjonalne

- **Docker Desktop** — wymagany tylko przy użyciu [runtime Docker z sandboxem](#obsługa-runtime-aktualnie) (`runtime.kind = "docker"`). Zainstaluj przez `winget install Docker.DockerDesktop`.

</details>

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

#### Wymagane

1. **Narzędzia budowania:**
    - **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:** Zainstaluj Xcode Command Line Tools: `xcode-select --install`

2. **Toolchain Rust:**

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

    Zobacz [rustup.rs](https://rustup.rs) po szczegóły.

3. **Sprawdź**, czy oba działają:
    ```bash
    rustc --version
    cargo --version
    ```

#### Instalator jednoliniowy

Lub pomiń powyższe kroki i zainstaluj wszystko (zależności systemowe, Rust, ZeroClaw) jednym poleceniem:

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

#### Wymagania zasobów kompilacji

Budowanie ze źródła wymaga więcej zasobów niż uruchamianie wynikowego pliku binarnego:

| Zasób          | Minimum | Zalecane    |
| -------------- | ------- | ----------- |
| **RAM + swap** | 2 GB    | 4 GB+       |
| **Wolne miejsce** | 6 GB | 10 GB+      |

Jeśli Twój host jest poniżej minimum, użyj gotowych plików binarnych:

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

Aby wymusić instalację wyłącznie z pliku binarnego, bez fallbacku na źródło:

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

#### Opcjonalne

- **Docker** — wymagany tylko przy użyciu [runtime Docker z sandboxem](#obsługa-runtime-aktualnie) (`runtime.kind = "docker"`). Zainstaluj przez menedżer pakietów lub [docker.com](https://docs.docker.com/engine/install/).

> **Uwaga:** Domyślny `cargo build --release` używa `codegen-units=1`, aby obniżyć szczytowe obciążenie kompilacji. Dla szybszych buildów na mocnych maszynach użyj `cargo build --profile release-fast`.

</details>

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

### Gotowe pliki binarne

Zasoby wydań są publikowane dla:

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

Pobierz najnowsze zasoby z:
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>

## Dokumentacja

Używaj tych, gdy przeszedłeś już przez onboarding i chcesz głębszej dokumentacji.

- Zacznij od [indeksu dokumentacji](docs/README.md), aby zobaczyć nawigację i „co gdzie jest."
- Przeczytaj [przegląd architektury](docs/architecture.md), aby poznać pełny model systemu.
- Użyj [dokumentacji konfiguracji](docs/reference/api/config-reference.md), gdy potrzebujesz każdego klucza i przykładu.
- Uruchom Gateway zgodnie z [podręcznikiem operacyjnym](docs/ops/operations-runbook.md).
- Postępuj zgodnie z [ZeroClaw Onboard](#szybki-start) dla konfiguracji z przewodnikiem.
- Debuguj typowe awarie z [przewodnikiem rozwiązywania problemów](docs/ops/troubleshooting.md).
- Przejrzyj [wskazówki bezpieczeństwa](docs/security/README.md) przed wystawieniem czegokolwiek.

### Dokumentacja referencyjna

- Centrum dokumentacji: [docs/README.md](docs/README.md)
- Ujednolicony spis treści: [docs/SUMMARY.md](docs/SUMMARY.md)
- Dokumentacja komend: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
- Dokumentacja konfiguracji: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
- Dokumentacja dostawców: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
- Dokumentacja kanałów: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
- Podręcznik operacyjny: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
- Rozwiązywanie problemów: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)

### Dokumentacja współpracy

- Przewodnik kontrybutora: [CONTRIBUTING.md](CONTRIBUTING.md)
- Polityka workflow PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
- Przewodnik workflow CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
- Podręcznik recenzenta: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
- Polityka ujawniania bezpieczeństwa: [SECURITY.md](SECURITY.md)
- Szablon dokumentacji: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)

### Wdrożenie + operacje

- Przewodnik wdrożenia sieciowego: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
- Podręcznik agenta proxy: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
- Przewodniki sprzętowe: [docs/hardware/README.md](docs/hardware/README.md)

## Smooth Crab 🦀

ZeroClaw został zbudowany dla smooth crab 🦀, szybkiego i wydajnego asystenta AI. Stworzony przez Argenisa De La Rosę i społeczność.

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

## Wesprzyj ZeroClaw

Jeśli ZeroClaw pomaga w Twojej pracy i chcesz wesprzeć dalszy rozwój, możesz przekazać darowiznę tutaj:

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

### 🙏 Specjalne podziękowania

Serdeczne podziękowania dla społeczności i instytucji, które inspirują i napędzają tę pracę open-source:

- **Harvard University** — za wspieranie ciekawości intelektualnej i przesuwanie granic tego, co możliwe.
- **MIT** — za promowanie otwartej wiedzy, open source i przekonania, że technologia powinna być dostępna dla wszystkich.
- **Sundai Club** — za społeczność, energię i nieustanny zapał do budowania rzeczy, które mają znaczenie.
- **Świat i dalej** 🌍✨ — dla każdego kontrybutora, marzyciela i twórcy, który sprawia, że open source jest siłą dobra. To dla Ciebie.

Budujemy w otwartości, ponieważ najlepsze pomysły pochodzą zewsząd. Jeśli to czytasz, jesteś tego częścią. Witaj. 🦀❤️

## Współtworzenie

Nowy w ZeroClaw? Szukaj issues oznaczonych [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — zobacz nasz [Przewodnik kontrybutora](CONTRIBUTING.md#first-time-contributors), aby dowiedzieć się jak zacząć. PR-y z AI/vibe-coded mile widziane! 🤖

Zobacz [CONTRIBUTING.md](CONTRIBUTING.md) i [CLA.md](docs/contributing/cla.md). Zaimplementuj trait, wyślij PR:

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

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

## ⚠️ Oficjalne repozytorium i ostrzeżenie przed podszywaniem się

**To jest jedyne oficjalne repozytorium ZeroClaw:**

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

Każde inne repozytorium, organizacja, domena lub pakiet twierdzący, że jest "ZeroClaw" lub sugerujący powiązanie z ZeroClaw Labs jest **nieautoryzowany i niepowiązany z tym projektem**. Znane nieautoryzowane forki będą wymienione w [TRADEMARK.md](docs/maintainers/trademark.md).

Jeśli napotkasz podszywanie się lub nadużycie znaku towarowego, proszę [otwórz zgłoszenie](https://github.com/zeroclaw-labs/zeroclaw/issues).

---

## Licencja

ZeroClaw jest podwójnie licencjonowany dla maksymalnej otwartości i ochrony kontrybutorów:

| Licencja | Przypadek użycia |
|----------|------------------|
| [MIT](LICENSE-MIT) | Open-source, badania, akademia, użytek osobisty |
| [Apache 2.0](LICENSE-APACHE) | Ochrona patentowa, instytucjonalne, wdrożenia komercyjne |

Możesz wybrać dowolną licencję. **Kontrybutorzy automatycznie udzielają praw na obie** — zobacz [CLA.md](docs/contributing/cla.md) po pełną umowę kontrybutora.

### Znak towarowy

Nazwa **ZeroClaw** i logo są znakami towarowymi ZeroClaw Labs. Ta licencja nie udziela pozwolenia na ich używanie w celu sugerowania poparcia lub powiązania. Zobacz [TRADEMARK.md](docs/maintainers/trademark.md) po dozwolone i zabronione użycia.

### Ochrona kontrybutorów

- **Zachowujesz prawa autorskie** do swoich wkładów
- **Udzielenie patentu** (Apache 2.0) chroni Cię przed roszczeniami patentowymi innych kontrybutorów
- Twoje wkłady są **trwale przypisane** w historii commitów i [NOTICE](NOTICE)
- Żadne prawa do znaku towarowego nie są przenoszone przez współtworzenie

---

**ZeroClaw** — Zero narzutu. Zero kompromisów. Wdrażaj wszędzie. Wymieniaj wszystko. 🦀

## Kontrybutorzy

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

Ta lista jest generowana z grafu kontrybutorów GitHub i aktualizuje się automatycznie.

## Historia gwiazdek

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