<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 — Trợ lý AI Cá nhân</h1>

<p align="center">
  <strong>Không tốn thêm tài nguyên. Không đánh đổi. 100% Rust. 100% Đa nền tảng.</strong><br>
  ⚡️ <strong>Chạy trên phần cứng $10 với RAM dưới 5MB: Ít hơn 99% bộ nhớ so với OpenClaw và rẻ hơn 98% so với 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">
Được xây dựng bởi sinh viên và thành viên của các cộng đồng Harvard, MIT và Sundai.Club.
</p>

<p align="center">
  🌐 <strong>Ngôn ngữ:</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 là trợ lý AI cá nhân mà bạn chạy trên thiết bị của mình. Nó trả lời bạn trên các kênh bạn đang sử dụng (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, và nhiều hơn nữa). Nó có bảng điều khiển web để kiểm soát thời gian thực và có thể kết nối với thiết bị ngoại vi phần cứng (ESP32, STM32, Arduino, Raspberry Pi). Gateway chỉ là mặt phẳng điều khiển — sản phẩm chính là trợ lý.

Nếu bạn muốn một trợ lý cá nhân, đơn người dùng, chạy cục bộ, nhanh và luôn sẵn sàng, đây chính là nó.

<p align="center">
  <a href="https://zeroclawlabs.ai">Website</a> ·
  <a href="docs/README.md">Tài liệu</a> ·
  <a href="docs/architecture.md">Kiến trúc</a> ·
  <a href="#bắt-đầu-nhanh-tldr">Bắt đầu</a> ·
  <a href="#chuyển-đổi-từ-openclaw">Chuyển đổi từ OpenClaw</a> ·
  <a href="docs/ops/troubleshooting.md">Khắc phục sự cố</a> ·
  <a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
</p>

> **Cài đặt khuyến nghị:** chạy `zeroclaw onboard` trong terminal. ZeroClaw Onboard hướng dẫn bạn từng bước thiết lập gateway, workspace, kênh và provider. Đây là đường dẫn cài đặt được khuyến nghị và hoạt động trên macOS, Linux, và Windows (qua WSL2). Cài đặt mới? Bắt đầu tại đây: [Bắt đầu](#bắt-đầu-nhanh-tldr)

### Subscription Auth (OAuth)

- **OpenAI Codex** (đăng ký ChatGPT)
- **Gemini** (Google OAuth)
- **Anthropic** (API key hoặc auth token)

Lưu ý về model: mặc dù nhiều provider/model được hỗ trợ, để có trải nghiệm tốt nhất hãy sử dụng model mạnh nhất thế hệ mới nhất mà bạn có. Xem [Onboarding](#bắt-đầu-nhanh-tldr).

Cấu hình model + CLI: [Providers reference](docs/reference/api/providers-reference.md)
Xoay vòng profile xác thực (OAuth vs API key) + failover: [Model failover](docs/reference/api/providers-reference.md)

## Cài đặt (khuyến nghị)

Runtime: Rust stable toolchain. Binary đơn, không phụ thuộc runtime.

### Homebrew (macOS/Linuxbrew)

```bash
brew install zeroclaw
```

### Bootstrap một lần bấm

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

`zeroclaw onboard` tự động chạy sau khi cài đặt để cấu hình workspace và provider.

## Bắt đầu nhanh (TL;DR)

Hướng dẫn đầy đủ cho người mới (xác thực, ghép cặp, kênh): [Bắt đầu](docs/setup-guides/one-click-bootstrap.md)

```bash
# Cài đặt + onboard
./install.sh --api-key "sk-..." --provider openrouter

# Khởi động gateway (webhook server + bảng điều khiển web)
zeroclaw gateway                # mặc định: 127.0.0.1:42617
zeroclaw gateway --port 0       # cổng ngẫu nhiên (tăng cường bảo mật)

# Nói chuyện với trợ lý
zeroclaw agent -m "Hello, ZeroClaw!"

# Chế độ tương tác
zeroclaw agent

# Khởi động runtime tự trị đầy đủ (gateway + kênh + cron + hands)
zeroclaw daemon

# Kiểm tra trạng thái
zeroclaw status

# Chạy chẩn đoán
zeroclaw doctor
```

Đang nâng cấp? Chạy `zeroclaw doctor` sau khi cập nhật.

### Build từ source (phát triển)

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

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

zeroclaw onboard
```

> **Chạy trực tiếp khi phát triển (không cần cài toàn cục):** thêm `cargo run --release --` trước lệnh (ví dụ: `cargo run --release -- status`).

## Chuyển đổi từ OpenClaw

ZeroClaw có thể nhập workspace, bộ nhớ và cấu hình OpenClaw của bạn:

```bash
# Xem trước những gì sẽ được chuyển đổi (an toàn, chỉ đọc)
zeroclaw migrate openclaw --dry-run

# Chạy chuyển đổi
zeroclaw migrate openclaw
```

Thao tác này chuyển đổi các mục bộ nhớ, file workspace và cấu hình từ `~/.openclaw/` sang `~/.zeroclaw/`. Cấu hình được tự động chuyển từ JSON sang TOML.

## Mặc định bảo mật (truy cập DM)

ZeroClaw kết nối với các dịch vụ nhắn tin thực. Xem DM đến như đầu vào không đáng tin cậy.

Hướng dẫn bảo mật đầy đủ: [SECURITY.md](SECURITY.md)

Hành vi mặc định trên tất cả các kênh:

- **Ghép cặp DM** (mặc định): người gửi không xác định nhận mã ghép cặp ngắn và bot không xử lý tin nhắn của họ.
- Phê duyệt bằng: `zeroclaw pairing approve <channel> <code>` (người gửi được thêm vào danh sách cho phép cục bộ).
- DM đến công khai yêu cầu opt-in rõ ràng trong `config.toml`.
- Chạy `zeroclaw doctor` để phát hiện chính sách DM nguy hiểm hoặc cấu hình sai.

**Mức tự trị:**

| Mức | Hành vi |
|-------|----------|
| `ReadOnly` | Agent chỉ có thể quan sát, không hành động |
| `Supervised` (mặc định) | Agent hành động với sự phê duyệt cho các thao tác rủi ro trung bình/cao |
| `Full` | Agent hành động tự trị trong giới hạn chính sách |

**Các lớp sandbox:** cách ly workspace, chặn duyệt đường dẫn, danh sách cho phép lệnh, đường dẫn cấm (`/etc`, `/root`, `~/.ssh`), giới hạn tốc độ (tối đa hành động/giờ, giới hạn chi phí/ngày).

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

### 📢 Thông báo

Bảng này dành cho các thông báo quan trọng (thay đổi không tương thích, cảnh báo bảo mật, cửa sổ bảo trì, và các vấn đề chặn release).

| Ngày (UTC) | Mức độ | Thông báo | Hành động |
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |   |
| 2026-02-19 | _Nghiêm trọng_ | Chúng tôi **không liên kết** với `openagen/zeroclaw`, `zeroclaw.org` hay `zeroclaw.net`. Các tên miền `zeroclaw.org` và `zeroclaw.net` hiện đang trỏ đến fork `openagen/zeroclaw`, và các tên miền/repository đó đang mạo danh website/dự án chính thức của chúng tôi. | Không tin tưởng thông tin, binary, gây quỹ, hay thông báo từ các nguồn đó. Chỉ sử dụng [repository này](https://github.com/zeroclaw-labs/zeroclaw) và các tài khoản mạng xã hội đã được xác minh của chúng tôi. |
| 2026-02-21 | _Quan trọng_ | Website chính thức của chúng tôi đã ra mắt: [zeroclawlabs.ai](https://zeroclawlabs.ai). Cảm ơn đã kiên nhẫn chờ đợi. Chúng tôi vẫn phát hiện các nỗ lực mạo danh, vì vậy **không** tham gia bất kỳ hoạt động đầu tư hoặc gây quỹ nào nhân danh ZeroClaw trừ khi được công bố qua các kênh chính thức. | Sử dụng [repository này](https://github.com/zeroclaw-labs/zeroclaw) làm nguồn thông tin duy nhất đáng tin cậy. Theo dõi [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (nhóm)](https://www.facebook.com/groups/zeroclawlabs), và [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) để nhận cập nhật chính thức. |
| 2026-02-19 | _Quan trọng_ | Anthropic đã cập nhật điều khoản Xác thực và Sử dụng Thông tin xác thực vào 2026-02-19. Token OAuth Claude Code (Free, Pro, Max) dành riêng cho Claude Code và Claude.ai; việc sử dụng OAuth token từ Claude Free/Pro/Max trong bất kỳ sản phẩm, công cụ hay dịch vụ nào khác (bao gồm Agent SDK) đều không được phép và có thể vi phạm Điều khoản Dịch vụ cho Người tiêu dùng. | Vui lòng tạm thời tránh tích hợp Claude Code OAuth để ngăn ngừa khả năng mất mát. Điều khoản gốc: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |

## Điểm nổi bật

- **Runtime tinh gọn mặc định** — các workflow CLI và trạng thái thông thường chạy trong vài megabyte bộ nhớ trên bản release.
- **Triển khai tiết kiệm chi phí** — được thiết kế cho board $10 và instance cloud nhỏ, không có phụ thuộc runtime nặng.
- **Khởi động lạnh nhanh** — runtime Rust binary đơn giữ cho việc khởi động lệnh và daemon gần như tức thì.
- **Kiến trúc di động** — một binary trên ARM, x86, và RISC-V với provider/channel/tool hoán đổi được.
- **Gateway ưu tiên cục bộ** — mặt phẳng điều khiển duy nhất cho phiên, kênh, công cụ, cron, SOP, và sự kiện.
- **Hộp thư đa kênh** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket, và nhiều hơn nữa.
- **Điều phối đa agent (Hands)** — bầy agent tự trị chạy theo lịch trình và thông minh hơn theo thời gian.
- **Quy trình vận hành chuẩn (SOPs)** — tự động hóa workflow dựa trên sự kiện với MQTT, webhook, cron, và trigger ngoại vi.
- **Bảng điều khiển web** — giao diện web React 19 + Vite với chat thời gian thực, trình duyệt bộ nhớ, trình chỉnh sửa cấu hình, quản lý cron, và trình kiểm tra công cụ.
- **Thiết bị ngoại vi phần cứng** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO qua trait `Peripheral`.
- **Công cụ hạng nhất** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace, và hơn 70 công cụ khác.
- **Hook vòng đời** — chặn và sửa đổi các lời gọi LLM, thực thi công cụ, và tin nhắn ở mọi giai đoạn.
- **Nền tảng skill** — skill đi kèm, cộng đồng, và workspace với kiểm tra bảo mật.
- **Hỗ trợ tunnel** — Cloudflare, Tailscale, ngrok, OpenVPN, và tunnel tùy chỉnh cho truy cập từ xa.

### Vì sao các team chọn ZeroClaw

- **Tinh gọn mặc định:** binary Rust nhỏ, khởi động nhanh, ít tốn bộ nhớ.
- **Bảo mật từ gốc:** ghép cặp, sandbox nghiêm ngặt, danh sách cho phép rõ ràng, giới hạn workspace.
- **Hoán đổi hoàn toàn:** hệ thống lõi đều là trait (provider, channel, tool, memory, tunnel).
- **Không khóa vendor:** hỗ trợ provider tương thích OpenAI + endpoint tùy chỉnh dễ mở rộng.

## So sánh hiệu năng (ZeroClaw vs OpenClaw, có thể tái tạo)

Benchmark nhanh trên máy cục bộ (macOS arm64, tháng 2/2026) quy chuẩn cho phần cứng edge 0.8GHz.

|                           | OpenClaw      | NanoBot        | PicoClaw        | ZeroClaw 🦀          |
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
| **Ngôn ngữ**              | TypeScript    | Python         | Go              | **Rust**             |
| **RAM**                   | > 1GB         | > 100MB        | < 10MB          | **< 5MB**            |
| **Khởi động (lõi 0.8GHz)** | > 500s        | > 30s          | < 1s            | **< 10ms**           |
| **Kích thước binary**           | ~28MB (dist)  | N/A (Scripts)  | ~8MB            | **~8.8 MB**          |
| **Chi phí**                  | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Phần cứng bất kỳ $10** |

> Ghi chú: Kết quả ZeroClaw được đo trên release build sử dụng `/usr/bin/time -l`. OpenClaw yêu cầu runtime Node.js (thường thêm ~390MB bộ nhớ overhead), NanoBot yêu cầu runtime Python. PicoClaw và ZeroClaw là static binary. Số RAM ở trên là bộ nhớ runtime; yêu cầu biên dịch lúc build cao hơn.

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

### Tự đo trên máy bạn

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

## Tất cả những gì chúng tôi đã xây dựng

### Nền tảng lõi

- Mặt phẳng điều khiển Gateway HTTP/WS/SSE với phiên, hiện diện, cấu hình, cron, webhook, bảng điều khiển web, và ghép cặp.
- Bề mặt CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
- Vòng lặp điều phối agent với dispatch công cụ, xây dựng prompt, phân loại tin nhắn, và tải bộ nhớ.
- Mô hình phiên với thực thi chính sách bảo mật, mức tự trị, và cổng phê duyệt.
- Wrapper provider đàn hồi với failover, retry, và định tuyến model trên hơn 20 backend LLM.

### Kênh

Kênh: WhatsApp (native), 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.

Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).

### Bảng điều khiển web

Bảng điều khiển web React 19 + Vite 6 + Tailwind CSS 4 được phục vụ trực tiếp từ Gateway:

- **Dashboard** — tổng quan hệ thống, trạng thái sức khỏe, thời gian hoạt động, theo dõi chi phí
- **Agent Chat** — chat tương tác với agent
- **Memory** — duyệt và quản lý mục bộ nhớ
- **Config** — xem và chỉnh sửa cấu hình
- **Cron** — quản lý tác vụ đã lên lịch
- **Tools** — duyệt công cụ có sẵn
- **Logs** — xem nhật ký hoạt động agent
- **Cost** — theo dõi sử dụng token và chi phí
- **Doctor** — chẩn đoán sức khỏe hệ thống
- **Integrations** — trạng thái và thiết lập tích hợp
- **Pairing** — quản lý ghép cặp thiết bị

### Mục tiêu firmware

| Mục tiêu | Nền tảng | Mục đích |
|--------|----------|---------|
| ESP32 | Espressif ESP32 | Agent ngoại vi không dây |
| ESP32-UI | ESP32 + Display | Agent với giao diện trực quan |
| STM32 Nucleo | STM32 (ARM Cortex-M) | Ngoại vi công nghiệp |
| Arduino | Arduino | Cầu nối cảm biến/bộ chấp hành cơ bản |
| Uno Q Bridge | Arduino Uno | Cầu nối serial đến agent |

### Công cụ + tự động hóa

- **Lõi:** shell, file read/write/edit, git operations, glob search, content search
- **Web:** browser control, web fetch, web search, screenshot, image info, PDF read
- **Tích hợp:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
- **Lên lịch:** cron add/remove/update/run, schedule tool
- **Bộ nhớ:** recall, store, forget, knowledge, project intel
- **Nâng cao:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
- **Phần cứng:** board info, memory map, memory read (feature-gated)

### Runtime + an toàn

- **Mức tự trị:** ReadOnly, Supervised (mặc định), Full.
- **Sandbox:** cách ly workspace, chặn duyệt đường dẫn, danh sách cho phép lệnh, đường dẫn cấm, Landlock (Linux), Bubblewrap.
- **Giới hạn tốc độ:** tối đa hành động mỗi giờ, tối đa chi phí mỗi ngày (có thể cấu hình).
- **Cổng phê duyệt:** phê duyệt tương tác cho các thao tác rủi ro trung bình/cao.
- **Dừng khẩn cấp:** khả năng tắt khẩn cấp.
- **Hơn 129 bài kiểm tra bảo mật** trong CI tự động.

### Vận hành + đóng gói

- Bảng điều khiển web phục vụ trực tiếp từ Gateway.
- Hỗ trợ tunnel: Cloudflare, Tailscale, ngrok, OpenVPN, custom command.
- Docker runtime adapter cho thực thi trong container.
- CI/CD: beta (tự động khi push) → stable (dispatch thủ công) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
- Binary dựng sẵn cho Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).


## Cấu hình

Tối thiểu `~/.zeroclaw/config.toml`:

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

Tham khảo cấu hình đầy đủ: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).

### Cấu hình kênh

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

### Cấu hình tunnel

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

Chi tiết: [Channel reference](docs/reference/api/channels-reference.md) · [Config reference](docs/reference/api/config-reference.md)

### Hỗ trợ runtime (hiện tại)

- **`native`** (mặc định) — thực thi process trực tiếp, đường dẫn nhanh nhất, lý tưởng cho môi trường tin cậy.
- **`docker`** — cách ly container đầy đủ, chính sách bảo mật cứng, yêu cầu Docker.

Đặt `runtime.kind = "docker"` cho sandbox nghiêm ngặt hoặc cách ly mạng.

## Subscription Auth (OpenAI Codex / Claude Code / Gemini)

ZeroClaw hỗ trợ profile xác thực theo gói đăng ký (đa tài khoản, mã hóa khi lưu).

- File lưu trữ: `~/.zeroclaw/auth-profiles.json`
- Khóa mã hóa: `~/.zeroclaw/.secret_key`
- Định dạng profile id: `<provider>:<profile_name>` (ví dụ: `openai-codex:work`)

```bash
# OpenAI Codex OAuth (đăng ký 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

# Kiểm tra / làm mới / chuyển profile
zeroclaw auth status
zeroclaw auth refresh --provider openai-codex --profile default
zeroclaw auth use --provider openai-codex --profile work

# Chạy agent với xác thực đăng ký
zeroclaw agent --provider openai-codex -m "hello"
zeroclaw agent --provider anthropic -m "hello"
```

## Workspace agent + skill

Thư mục gốc workspace: `~/.zeroclaw/workspace/` (có thể cấu hình qua config).

Các file prompt được inject:
- `IDENTITY.md` — tính cách và vai trò agent
- `USER.md` — ngữ cảnh và sở thích người dùng
- `MEMORY.md` — sự kiện và bài học dài hạn
- `AGENTS.md` — quy ước phiên và quy tắc khởi tạo
- `SOUL.md` — bản sắc cốt lõi và nguyên tắc vận hành

Skill: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` hoặc `SKILL.toml`.

```bash
# Liệt kê skill đã cài
zeroclaw skills list

# Cài từ git
zeroclaw skills install https://github.com/user/my-skill.git

# Kiểm tra bảo mật trước khi cài
zeroclaw skills audit https://github.com/user/my-skill.git

# Xóa skill
zeroclaw skills remove my-skill
```

## Lệnh CLI

```bash
# Quản lý workspace
zeroclaw onboard              # Trình hướng dẫn cài đặt
zeroclaw status               # Hiển thị trạng thái daemon/agent
zeroclaw doctor               # Chạy chẩn đoán hệ thống

# Gateway + daemon
zeroclaw gateway              # Khởi động gateway server (127.0.0.1:42617)
zeroclaw daemon               # Khởi động runtime tự trị đầy đủ

# Agent
zeroclaw agent                # Chế độ chat tương tác
zeroclaw agent -m "message"   # Chế độ tin nhắn đơn

# Quản lý dịch vụ
zeroclaw service install      # Cài đặt làm dịch vụ OS (launchd/systemd)
zeroclaw service start|stop|restart|status

# Kênh
zeroclaw channel list         # Liệt kê kênh đã cấu hình
zeroclaw channel doctor       # Kiểm tra sức khỏe kênh
zeroclaw channel bind-telegram 123456789

# Cron + lên lịch
zeroclaw cron list            # Liệt kê tác vụ đã lên lịch
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
zeroclaw cron remove <id>

# Bộ nhớ
zeroclaw memory list          # Liệt kê mục bộ nhớ
zeroclaw memory get <key>     # Truy xuất bộ nhớ
zeroclaw memory stats         # Thống kê bộ nhớ

# Profile xác thực
zeroclaw auth login --provider <name>
zeroclaw auth status
zeroclaw auth use --provider <name> --profile <profile>

# Thiết bị ngoại vi phần cứng
zeroclaw hardware discover    # Quét thiết bị đã kết nối
zeroclaw peripheral list      # Liệt kê thiết bị ngoại vi đã kết nối
zeroclaw peripheral flash     # Flash firmware vào thiết bị

# Chuyển đổi
zeroclaw migrate openclaw --dry-run
zeroclaw migrate openclaw

# Tự động hoàn thành shell
source <(zeroclaw completions bash)
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
```

Tham khảo đầy đủ các lệnh: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)

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

## Yêu cầu hệ thống

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

#### Bắt buộc

1. **Visual Studio Build Tools** (cung cấp MSVC linker và Windows SDK):

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

    Trong quá trình cài đặt (hoặc qua Visual Studio Installer), chọn workload **"Desktop development with C++"**.

2. **Rust toolchain:**

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

    Sau khi cài, mở terminal mới và chạy `rustup default stable` để đảm bảo toolchain stable đang hoạt động.

3. **Xác minh** cả hai đang hoạt động:
    ```powershell
    rustc --version
    cargo --version
    ```

#### Tùy chọn

- **Docker Desktop** — chỉ cần nếu sử dụng [Docker sandbox runtime](#hỗ-trợ-runtime-hiện-tại) (`runtime.kind = "docker"`). Cài qua `winget install Docker.DockerDesktop`.

</details>

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

#### Bắt buộc

1. **Công cụ build cơ bản:**
    - **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:** Cài Xcode Command Line Tools: `xcode-select --install`

2. **Rust toolchain:**

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

    Xem [rustup.rs](https://rustup.rs) để biết chi tiết.

3. **Xác minh** cả hai đang hoạt động:
    ```bash
    rustc --version
    cargo --version
    ```

#### Cài bằng một lệnh

Hoặc bỏ qua các bước trên và cài hết mọi thứ (system deps, Rust, ZeroClaw) bằng một lệnh:

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

#### Yêu cầu tài nguyên biên dịch

Build từ source đòi hỏi nhiều tài nguyên hơn chạy binary kết quả:

| Tài nguyên | Tối thiểu | Khuyến nghị |
| -------------- | ------- | ----------- |
| **RAM + swap** | 2 GB    | 4 GB+       |
| **Dung lượng đĩa trống**  | 6 GB    | 10 GB+      |

Nếu máy dưới mức tối thiểu, dùng binary dựng sẵn:

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

Chỉ cài từ binary, không fallback sang build source:

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

#### Tùy chọn

- **Docker** — chỉ cần nếu sử dụng [Docker sandbox runtime](#hỗ-trợ-runtime-hiện-tại) (`runtime.kind = "docker"`). Cài qua package manager hoặc [docker.com](https://docs.docker.com/engine/install/).

> **Lưu ý:** Lệnh `cargo build --release` mặc định dùng `codegen-units=1` để giảm áp lực biên dịch đỉnh. Để build nhanh hơn trên máy mạnh, dùng `cargo build --profile release-fast`.

</details>

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

### Binary dựng sẵn

Release asset được phát hành cho:

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

Tải asset mới nhất tại:
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>

## Tài liệu

Dùng khi bạn đã hoàn thành onboarding và muốn tham khảo sâu hơn.

- Bắt đầu với [chỉ mục tài liệu](docs/README.md) để điều hướng và biết "cái gì ở đâu."
- Đọc [tổng quan kiến trúc](docs/architecture.md) cho mô hình hệ thống đầy đủ.
- Dùng [tham khảo cấu hình](docs/reference/api/config-reference.md) khi cần mọi key và ví dụ.
- Vận hành Gateway theo [sổ tay vận hành](docs/ops/operations-runbook.md).
- Theo [ZeroClaw Onboard](#bắt-đầu-nhanh-tldr) để cài đặt có hướng dẫn.
- Debug lỗi thường gặp với [hướng dẫn khắc phục sự cố](docs/ops/troubleshooting.md).
- Xem lại [hướng dẫn bảo mật](docs/security/README.md) trước khi phơi bày bất kỳ thứ gì.

### Tài liệu tham khảo

- Hub tài liệu: [docs/README.md](docs/README.md)
- Mục lục tài liệu thống nhất: [docs/SUMMARY.md](docs/SUMMARY.md)
- Tham khảo lệnh: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
- Tham khảo cấu hình: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
- Tham khảo provider: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
- Tham khảo kênh: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
- Sổ tay vận hành: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
- Khắc phục sự cố: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)

### Tài liệu cộng tác

- Hướng dẫn đóng góp: [CONTRIBUTING.md](CONTRIBUTING.md)
- Chính sách quy trình PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
- Hướng dẫn CI workflow: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
- Sổ tay reviewer: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
- Chính sách tiết lộ bảo mật: [SECURITY.md](SECURITY.md)
- Template tài liệu: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)

### Triển khai + vận hành

- Hướng dẫn triển khai mạng: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
- Sổ tay proxy agent: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
- Hướng dẫn phần cứng: [docs/hardware/README.md](docs/hardware/README.md)

## Smooth Crab 🦀

ZeroClaw được xây dựng cho smooth crab 🦀, một trợ lý AI nhanh và hiệu quả. Được xây dựng bởi Argenis De La Rosa và cộng đồng.

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

## Ủng hộ ZeroClaw

Nếu ZeroClaw giúp ích cho công việc của bạn và bạn muốn hỗ trợ phát triển, bạn có thể quyên góp tại đây:

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

### 🙏 Lời cảm ơn đặc biệt

Chân thành cảm ơn các cộng đồng và tổ chức đã truyền cảm hứng và thúc đẩy công việc mã nguồn mở này:

- **Harvard University** — vì đã nuôi dưỡng sự tò mò trí tuệ và không ngừng mở rộng ranh giới khả năng.
- **MIT** — vì đã đề cao tri thức mở, mã nguồn mở, và niềm tin rằng công nghệ phải tiếp cận được với tất cả mọi người.
- **Sundai Club** — vì cộng đồng, năng lượng, và động lực không mệt mỏi để xây dựng những thứ có ý nghĩa.
- **Thế giới & Xa hơn** 🌍✨ — gửi đến mọi người đóng góp, người dám mơ và người dám làm đang biến mã nguồn mở thành sức mạnh tích cực. Tất cả là dành cho các bạn.

Chúng tôi xây dựng công khai vì ý tưởng hay đến từ khắp nơi. Nếu bạn đang đọc đến đây, bạn đã là một phần của chúng tôi. Chào mừng. 🦀❤️

## Đóng góp

Mới với ZeroClaw? Tìm các issue có nhãn [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — xem [Hướng dẫn đóng góp](CONTRIBUTING.md#first-time-contributors) để bắt đầu. PR AI/vibe-coded đều được chào đón! 🤖

Xem [CONTRIBUTING.md](CONTRIBUTING.md) và [CLA.md](docs/contributing/cla.md). Triển khai một trait, gửi PR:

- Hướng dẫn CI workflow: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
- `Provider` mới → `src/providers/`
- `Channel` mới → `src/channels/`
- `Observer` mới → `src/observability/`
- `Tool` mới → `src/tools/`
- `Memory` mới → `src/memory/`
- `Tunnel` mới → `src/tunnel/`
- `Peripheral` mới → `src/peripherals/`
- `Skill` mới → `~/.zeroclaw/workspace/skills/<name>/`

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

## ⚠️ Repository chính thức & Cảnh báo mạo danh

**Đây là repository ZeroClaw chính thức duy nhất:**

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

Bất kỳ repository, tổ chức, tên miền hay gói nào khác tuyên bố là "ZeroClaw" hoặc ngụ ý liên kết với ZeroClaw Labs đều **không được ủy quyền và không liên kết với dự án này**. Các fork không được ủy quyền đã biết sẽ được liệt kê trong [TRADEMARK.md](docs/maintainers/trademark.md).

Nếu bạn phát hiện mạo danh hoặc lạm dụng nhãn hiệu, vui lòng [mở một issue](https://github.com/zeroclaw-labs/zeroclaw/issues).

---

## Giấy phép

ZeroClaw được cấp phép kép để tối đa hóa tính mở và bảo vệ người đóng góp:

| Giấy phép | Trường hợp sử dụng |
|---|---|
| [MIT](LICENSE-MIT) | Mã nguồn mở, nghiên cứu, học thuật, sử dụng cá nhân |
| [Apache 2.0](LICENSE-APACHE) | Bảo hộ bằng sáng chế, triển khai tổ chức, thương mại |

Bạn có thể chọn một trong hai giấy phép. **Người đóng góp tự động cấp quyền theo cả hai** — xem [CLA.md](docs/contributing/cla.md) để biết thỏa thuận đóng góp đầy đủ.

### Nhãn hiệu

Tên **ZeroClaw** và logo là nhãn hiệu của ZeroClaw Labs. Giấy phép này không cấp phép sử dụng chúng để ngụ ý chứng thực hoặc liên kết. Xem [TRADEMARK.md](docs/maintainers/trademark.md) để biết các sử dụng được phép và bị cấm.

### Bảo vệ người đóng góp

- Bạn **giữ bản quyền** đối với đóng góp của mình
- **Cấp bằng sáng chế** (Apache 2.0) bảo vệ bạn khỏi các khiếu nại bằng sáng chế từ người đóng góp khác
- Đóng góp của bạn được **ghi nhận vĩnh viễn** trong lịch sử commit và [NOTICE](NOTICE)
- Không có quyền nhãn hiệu nào được chuyển giao khi đóng góp

---

**ZeroClaw** — Không tốn thêm tài nguyên. Không đánh đổi. Triển khai ở đâu cũng được. Thay thế gì cũng được. 🦀

## Người đóng góp

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

Danh sách này được tạo từ biểu đồ người đóng góp GitHub và cập nhật tự động.

## Lịch sử Star

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