<p align="center">
  <img src="zeroclaw.png" alt="ZeroClaw" width="200" />
</p>

<h1 align="center">ZeroClaw 🦀</h1>

<p align="center">
  <strong>오버헤드 없음. 타협 없음. 100% Rust. 100% 독립적.</strong><br>
  ⚡️ <strong>$10 하드웨어에서 <5MB RAM으로 실행: OpenClaw보다 99% 적은 메모리, Mac mini보다 98% 저렴!</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="NOTICE"><img src="https://img.shields.io/badge/contributors-27+-green.svg" 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://zeroclawlabs.cn/group.jpg"><img src="https://img.shields.io/badge/WeChat-Group-B7D7A8?logo=wechat&logoColor=white" alt="WeChat Group" /></a>
  <a href="https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search"><img src="https://img.shields.io/badge/Xiaohongshu-Official-FF2442?style=flat" alt="Xiaohongshu: Official" /></a>
  <a href="https://t.me/zeroclawlabs"><img src="https://img.shields.io/badge/Telegram-%40zeroclawlabs-26A5E4?style=flat&logo=telegram&logoColor=white" alt="Telegram: @zeroclawlabs" /></a>
  <a href="https://www.facebook.com/groups/zeroclaw"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></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">
Harvard, MIT, 그리고 Sundai.Club 커뮤니티의 학생들과 멤버들이 만들었습니다.
</p>

<p align="center">
  🌐 <strong>언어:</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>

<p align="center">
  <a href="#빠른-시작">빠른 시작</a> |
  <a href="bootstrap.sh">원클릭 설정</a> |
  <a href="docs/README.md">문서 허브</a> |
  <a href="docs/SUMMARY.md">문서 목차</a>
</p>

<p align="center">
  <strong>빠른 접근:</strong>
  <a href="docs/reference/README.md">참조</a> ·
  <a href="docs/operations/README.md">운영</a> ·
  <a href="docs/troubleshooting.md">문제 해결</a> ·
  <a href="docs/security/README.md">보안</a> ·
  <a href="docs/hardware/README.md">하드웨어</a> ·
  <a href="docs/contributing/README.md">기여하기</a>
</p>

<p align="center">
  <strong>빠르고 가벼우며 완전히 자율적인 AI 어시스턴트 인프라</strong><br />
  어디서나 배포. 무엇이든 교체.
</p>

<p align="center">
  ZeroClaw는 에이전트 워크플로우를 위한 <strong>런타임 운영체제</strong>입니다 — 모델, 도구, 메모리, 실행을 추상화하여 한 번 구축하고 어디서나 실행할 수 있는 인프라입니다.
</p>

<p align="center"><code>트레이트 기반 아키텍처 · 기본 보안 런타임 · 교체 가능한 제공자/채널/도구 · 모든 것이 플러그 가능</code></p>

### 📢 공지사항

이 표를 사용하여 중요한 공지사항(호환성 변경, 보안 공지, 유지보수 기간, 버전 차단)을 확인하세요.

| 날짜 (UTC) | 수준      | 공지                                                                                                                                                                                                                                                                                                                                                                                                              | 조치                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-02-19 | _중요_  | 우리는 `openagen/zeroclaw` 또는 `zeroclaw.org`와 **관련이 없습니다**. `zeroclaw.org` 도메인은 현재 `openagen/zeroclaw` 포크를 가리키고 있으며, 이 도메인/저장소는 우리의 공식 웹사이트/프로젝트를 사칭하고 있습니다.                                                                                                                                                                                 | 이 소스의 정보, 바이너리, 펀딩, 공지를 신뢰하지 마세요. [이 저장소](https://github.com/zeroclaw-labs/zeroclaw)와 우리의 확인된 소셜 계정만 사용하세요.                                                                                                                                                                                                                                                                                                                                                          |
| 2026-02-21 | _중요_ | 우리의 공식 웹사이트가 이제 온라인입니다: [zeroclawlabs.ai](https://zeroclawlabs.ai). 기다려주셔서 감사합니다. 여전히 사칭 시도가 감지되고 있습니다: 공식 채널을 통해 게시되지 않은 ZeroClaw 이름의 모든 투자/펀딩 활동에 참여하지 마세요.                                                                                                                   | [이 저장소](https://github.com/zeroclaw-labs/zeroclaw)를 유일한 진실의 원천으로 사용하세요. [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Telegram (@zeroclawlabs)](https://t.me/zeroclawlabs), [Facebook (그룹)](https://www.facebook.com/groups/zeroclaw), [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/), 그리고 [Xiaohongshu](https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search)를 팔로우하여 공식 업데이트를 받으세요. |
| 2026-02-19 | _중요_ | Anthropic이 2026-02-19에 인증 및 자격증명 사용 약관을 업데이트했습니다. OAuth 인증(Free, Pro, Max)은 Claude Code 및 Claude.ai 전용입니다. 다른 제품, 도구 또는 서비스(Agent SDK 포함)에서 Claude Free/Pro/Max OAuth 토큰을 사용하는 것은 허용되지 않으며 소비자 이용약관을 위반할 수 있습니다. | 잠재적인 손실을 방지하기 위해 일시적으로 Claude Code OAuth 통합을 피하세요. 원본 조항: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use).                                                                                                                                                                                                                                                                                                                      |

### ✨ 기능

- 🏎️ **기본 경량 런타임:** 일반적인 CLI 워크플로우와 상태 명령이 프로덕션 빌드에서 몇 메가바이트의 메모리 공간 내에서 실행됩니다.
- 💰 **비용 효율적인 배포:** 무거운 런타임 의존성 없이 저비용 보드 및 소규모 클라우드 인스턴스를 위해 설계되었습니다.
- ⚡ **빠른 콜드 스타트:** 단일 Rust 바이너리 런타임이 일상적인 운영을 위해 거의 즉각적인 명령 및 데몬 시작을 유지합니다.
- 🌍 **이식 가능한 아키텍처:** 교체 가능한 제공자/채널/도구로 ARM, x86, RISC-V에서 단일 바이너리 워크플로우.

### 왜 팀들이 ZeroClaw를 선택하나요

- **기본 경량:** 작은 Rust 바이너리, 빠른 시작, 낮은 메모리 공간.
- **기본 보안:** 페어링, 엄격한 샌드박싱, 명시적 허용 목록, 작업공간 범위.
- **완전히 교체 가능:** 핵심 시스템이 트레이트입니다(제공자, 채널, 도구, 메모리, 터널).
- **벤더 락인 없음:** OpenAI 호환 제공자 지원 + 플러그 가능한 사용자 정의 엔드포인트.

## 벤치마크 스냅샷 (ZeroClaw vs OpenClaw, 재현 가능)

로컬 머신에서 빠른 벤치마크(macOS arm64, 2026년 2월) 0.8 GHz 엣지 하드웨어로 정규화됨.

|                              | OpenClaw      | NanoBot        | PicoClaw        | ZeroClaw 🦀           |
| ---------------------------- | ------------- | -------------- | --------------- | --------------------- |
| **언어**                  | TypeScript    | Python         | Go              | **Rust**              |
| **RAM**                      | > 1 GB        | > 100 MB       | < 10 MB         | **< 5 MB**            |
| **시작 (0.8 GHz 코어)** | > 500s        | > 30s          | < 1s            | **< 10ms**            |
| **바이너리 크기**           | ~28 MB (dist) | N/A (Scripts)  | ~8 MB           | **3.4 MB**            |
| **비용**                     | Mac Mini $599 | Linux SBC ~$50 | Linux 보드 $10 | **모든 하드웨어 $10** |

> 참고: ZeroClaw 결과는 `/usr/bin/time -l`을 사용한 프로덕션 빌드에서 측정되었습니다. OpenClaw는 Node.js 런타임이 필요하며(일반적으로 ~390MB 추가 메모리 오버헤드), NanoBot은 Python 런타임이 필요합니다. PicoClaw와 ZeroClaw는 정적 바이너리입니다. 위 RAM 수치는 런타임 메모리이며, 빌드 시간 컴파일 요구사항은 더 높습니다.

<p align="center">
  <img src="zero-claw.jpeg" alt="ZeroClaw vs OpenClaw 비교" width="800" />
</p>

### 재현 가능한 로컬 측정

벤치마크 주장은 코드와 툴체인의 발전에 따라 달라질 수 있으므로 항상 현재 빌드를 로컬에서 측정하세요:

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

샘플 예시(macOS arm64, 2026년 2월 18일 측정):

- 릴리스 바이너리 크기: `8.8M`
- `zeroclaw --help`: 실제 시간 약 `0.02s`, 최대 메모리 공간 ~`3.9 MB`
- `zeroclaw status`: 실제 시간 약 `0.01s`, 최대 메모리 공간 ~`4.1 MB`

## 사전 요구사항

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

### Windows — 필수

1. **Visual Studio Build Tools**(MSVC 링커 및 Windows SDK 제공):

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

    설치 중(또는 Visual Studio Installer를 통해) **"C++를 사용한 데스크톱 개발"** 워크로드를 선택하세요.

2. **Rust 툴체인:**

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

    설치 후, 새 터미널을 열고 `rustup default stable`을 실행하여 안정적인 툴체인이 활성화되어 있는지 확인하세요.

3. **확인:** 둘 다 작동하는지 확인:
    ```powershell
    rustc --version
    cargo --version
    ```

### Windows — 선택사항

- **Docker Desktop** — [Docker 샌드박스 런타임](#현재-런타임-지원)을 사용하는 경우에만 필요(`runtime.kind = "docker"`). `winget install Docker.DockerDesktop`을 통해 설치.

</details>

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

### Linux / macOS — 필수

1. **필수 빌드 도구:**
    - **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:** Xcode Command Line Tools 설치: `xcode-select --install`

2. **Rust 툴체인:**

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

    자세한 내용은 [rustup.rs](https://rustup.rs)를 참조하세요.

3. **확인:**
    ```bash
    rustc --version
    cargo --version
    ```

### Linux / macOS — 선택사항

- **Docker** — [Docker 샌드박스 런타임](#현재-런타임-지원)을 사용하는 경우에만 필요(`runtime.kind = "docker"`).
    - **Linux (Debian/Ubuntu):** [docs.docker.com](https://docs.docker.com/engine/install/ubuntu/) 참조
    - **Linux (Fedora/RHEL):** [docs.docker.com](https://docs.docker.com/engine/install/fedora/) 참조
    - **macOS:** [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)에서 Docker Desktop 설치

</details>

## 빠른 시작

### 옵션 1: 자동 설정 (권장)

`bootstrap.sh` 스크립트는 Rust를 설치하고, ZeroClaw를 클론하고, 컴파일하고, 초기 개발 환경을 설정합니다:

```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/bootstrap.sh | bash
```

이 작업은 다음을 수행합니다:

1. Rust 설치 (없는 경우)
2. ZeroClaw 저장소 클론
3. ZeroClaw를 릴리스 모드로 컴파일
4. `~/.cargo/bin/`에 `zeroclaw` 설치
5. `~/.zeroclaw/workspace/`에 기본 작업공간 구조 생성
6. 시작용 `~/.zeroclaw/workspace/config.toml` 구성 파일 생성

부트스트랩 후, 셸을 다시 로드하거나 `source ~/.cargo/env`를 실행하여 `zeroclaw` 명령을 전역으로 사용하세요.

### 옵션 2: 수동 설치

<details>
<summary><strong>클릭하여 수동 설치 단계 보기</strong></summary>

```bash
# 1. 저장소 클론
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# 2. 릴리스로 컴파일
cargo build --release --locked

# 3. 바이너리 설치
cargo install --path . --locked

# 4. 작업공간 초기화
zeroclaw init

# 5. 설치 확인
zeroclaw --version
zeroclaw status
```

</details>

### 설치 후

설치 후(부트스트랩 또는 수동), 다음이 표시되어야 합니다:

```
~/.zeroclaw/workspace/
├── config.toml          # 메인 구성
├── .pairing             # 페어링 시크릿 (첫 실행 시 생성)
├── logs/                # 데몬/에이전트 로그
├── skills/              # 사용자 정의 스킬
└── memory/              # 대화 컨텍스트 저장소
```

**다음 단계:**

1. `~/.zeroclaw/workspace/config.toml`에서 AI 제공자 구성
2. 고급 옵션은 [구성 참조](docs/config-reference.md) 확인
3. 에이전트 시작: `zeroclaw agent start`
4. 선호하는 채널을 통해 테스트 ([채널 참조](docs/channels-reference.md) 참조)

## 구성

제공자, 채널 및 시스템 동작을 구성하려면 `~/.zeroclaw/workspace/config.toml`을 편집하세요.

### 빠른 구성 참조

```toml
[providers.anthropic]
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"

[providers.openai]
api_key = "sk-..."
model = "gpt-4o"

[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."

[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@bot:matrix.org"
password = "..."

[memory]
kind = "markdown"  # 또는 "sqlite" 또는 "none"

[runtime]
kind = "native"    # 또는 "docker" (Docker 필요)
```

**전체 참조 문서:**

- [구성 참조](docs/config-reference.md) — 모든 설정, 검증, 기본값
- [제공자 참조](docs/providers-reference.md) — AI 제공자별 구성
- [채널 참조](docs/channels-reference.md) — Telegram, Matrix, Slack, Discord 등
- [운영](docs/operations-runbook.md) — 프로덕션 모니터링, 시크릿 교체, 스케일링

### 현재 런타임 지원

ZeroClaw는 두 가지 코드 실행 백엔드를 지원합니다:

- **`native`**(기본값) — 직접 프로세스 실행, 가장 빠른 경로, 신뢰할 수 있는 환경에 이상적
- **`docker`** — 전체 컨테이너 격리, 강화된 보안 정책, Docker 필요

엄격한 샌드박싱이나 네트워크 격리가 필요한 경우 `runtime.kind = "docker"`를 사용하세요. 자세한 내용은 [구성 참조](docs/config-reference.md#runtime)를 참조하세요.

## 명령어

```bash
# 작업공간 관리
zeroclaw init                # 새 작업공간 초기화
zeroclaw status              # 데몬/에이전트 상태 표시
zeroclaw config validate     # config.toml 구문 및 값 확인

# 데몬 관리
zeroclaw daemon start        # 백그라운드에서 데몬 시작
zeroclaw daemon stop         # 실행 중인 데몬 중지
zeroclaw daemon restart      # 데몬 재시작 (구성 다시 로드)
zeroclaw daemon logs         # 데몬 로그 표시

# 에이전트 관리
zeroclaw agent start         # 에이전트 시작 (데몬 실행 중 필요)
zeroclaw agent stop          # 에이전트 중지
zeroclaw agent restart       # 에이전트 재시작 (구성 다시 로드)

# 페어링 작업
zeroclaw pairing init        # 새 페어링 시크릿 생성
zeroclaw pairing rotate      # 기존 페어링 시크릿 교체

# 터널링 (공개 노출용)
zeroclaw tunnel start        # 로컬 데몬으로 터널 시작
zeroclaw tunnel stop         # 활성 터널 중지

# 진단
zeroclaw doctor              # 시스템 상태 검사 실행
zeroclaw version             # 버전 및 빌드 정보 표시
```

전체 옵션 및 예제는 [명령어 참조](docs/commands-reference.md)를 참조하세요.

## 아키텍처

```
┌─────────────────────────────────────────────────────────────────┐
│                        채널 (트레이트)                           │
│  Telegram │ Matrix │ Slack │ Discord │ Web │ CLI │ Custom       │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      에이전트 오케스트레이터                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   메시지      │  │   컨텍스트   │  │    도구      │          │
│  │   라우팅      │  │   메모리     │  │   실행       │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   제공자     │  │   메모리     │  │    도구      │
│   (트레이트)  │  │   (트레이트) │  │   (트레이트) │
├──────────────┤  ├──────────────┤  ├──────────────┤
│  Anthropic   │  │   Markdown   │  │  Filesystem  │
│   OpenAI     │  │    SQLite    │  │     Bash     │
│   Gemini     │  │     None     │  │   Web Fetch  │
│   Ollama     │  │    Custom    │  │   Custom     │
│   Custom     │  └──────────────┘  └──────────────┘
└──────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                   런타임 (트레이트)                                │
│                  Native │ Docker                                 │
└─────────────────────────────────────────────────────────────────┘
```

**핵심 원칙:**

- 모든 것이 **트레이트**입니다 — 제공자, 채널, 도구, 메모리, 터널
- 채널이 오케스트레이터를 호출; 오케스트레이터가 제공자 + 도구를 호출
- 메모리 시스템이 대화 컨텍스트 관리(markdown, SQLite, 또는 없음)
- 런타임이 코드 실행 추상화(네이티브 또는 Docker)
- 제공자 락인 없음 — 코드 변경 없이 Anthropic ↔ OpenAI ↔ Gemini ↔ Ollama 교체

자세한 다이어그램과 구현 세부 정보는 [아키텍처 문서](docs/architecture.svg)를 참조하세요.

## 예제

### 텔레그램 봇

```toml
[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."
allowed_users = [987654321]  # 당신의 텔레그램 사용자 ID
```

데몬 + 에이전트를 시작한 다음 텔레그램에서 봇에 메시지를 보내세요:

```
/start
안녕하세요! Python 스크립트 작성을 도와주실 수 있나요?
```

봇이 AI가 생성한 코드로 응답하고, 요청 시 도구를 실행하며, 대화 컨텍스트를 유지합니다.

### Matrix (종단 간 암호화)

```toml
[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@zeroclaw:matrix.org"
password = "..."
device_name = "zeroclaw-prod"
e2ee_enabled = true
```

암호화된 방에 `@zeroclaw:matrix.org`를 초대하면 봇이 완전한 암호화로 응답합니다. 장치 확인 설정은 [Matrix E2EE 가이드](docs/matrix-e2ee-guide.md)를 참조하세요.

### 다중 제공자

```toml
[providers.anthropic]
enabled = true
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"

[providers.openai]
enabled = true
api_key = "sk-..."
model = "gpt-4o"

[orchestrator]
default_provider = "anthropic"
fallback_providers = ["openai"]  # 제공자 오류 시 장애 조치
```

Anthropic이 실패하거나 속도 제한이 걸리면 오케스트레이터가 자동으로 OpenAI로 장애 조치합니다.

### 사용자 정의 메모리

```toml
[memory]
kind = "sqlite"
path = "~/.zeroclaw/workspace/memory/conversations.db"
retention_days = 90  # 90일 후 자동 삭제
```

또는 사람이 읽을 수 있는 저장소를 위해 Markdown을 사용하세요:

```toml
[memory]
kind = "markdown"
path = "~/.zeroclaw/workspace/memory/"
```

모든 메모리 옵션은 [구성 참조](docs/config-reference.md#memory)를 참조하세요.

## 제공자 지원

| 제공자       | 상태      | API 키             | 예제 모델                                      |
| ----------------- | ----------- | ------------------- | ---------------------------------------------------- |
| **Anthropic**     | ✅ 안정   | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514`, `claude-opus-4-20250514` |
| **OpenAI**        | ✅ 안정   | `OPENAI_API_KEY`    | `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`             |
| **Google Gemini** | ✅ 안정   | `GOOGLE_API_KEY`    | `gemini-2.0-flash-exp`, `gemini-exp-1206`            |
| **Ollama**        | ✅ 안정   | N/A (로컬)         | `llama3.3`, `qwen2.5`, `phi4`                        |
| **Cerebras**      | ✅ 안정   | `CEREBRAS_API_KEY`  | `llama-3.3-70b`                                      |
| **Groq**          | ✅ 안정   | `GROQ_API_KEY`      | `llama-3.3-70b-versatile`                            |
| **Mistral**       | 🚧 계획 중 | `MISTRAL_API_KEY`   | TBD                                                  |
| **Cohere**        | 🚧 계획 중 | `COHERE_API_KEY`    | TBD                                                  |

### 사용자 정의 엔드포인트

ZeroClaw는 OpenAI 호환 엔드포인트를 지원합니다:

```toml
[providers.custom]
enabled = true
api_key = "..."
base_url = "https://api.your-llm-provider.com/v1"
model = "your-model-name"
```

예: [LiteLLM](https://github.com/BerriAI/litellm)을 프록시로 사용하여 OpenAI 인터페이스를 통해 모든 LLM에 액세스.

전체 구성 세부 정보는 [제공자 참조](docs/providers-reference.md)를 참조하세요.

## 채널 지원

| 채널        | 상태      | 인증         | 참고                                                     |
| ------------ | ----------- | ------------------------ | --------------------------------------------------------- |
| **Telegram** | ✅ 안정   | 봇 토큰                | 파일, 이미지, 인라인 버튼 포함 전체 지원             |
| **Matrix**   | ✅ 안정   | 비밀번호 또는 토큰    | 장치 확인과 함께 E2EE 지원              |
| **Slack**    | 🚧 계획 중 | OAuth 또는 봇 토큰       | 작업공간 액세스 필요                                    |
| **Discord**  | 🚧 계획 중 | 봇 토큰                | 길드 권한 필요                                |
| **WhatsApp** | 🚧 계획 중 | Twilio 또는 공식 API | 비즈니스 계정 필요                                    |
| **CLI**      | ✅ 안정   | 없음                    | 직접 대화형 인터페이스                       |
| **Web**      | 🚧 계획 중 | API 키 또는 OAuth         | 브라우저 기반 채팅 인터페이스                        |

전체 구성 지침은 [채널 참조](docs/channels-reference.md)를 참조하세요.

## 도구 지원

ZeroClaw는 코드 실행, 파일 시스템 액세스 및 웹 검색을 위한 기본 제공 도구를 제공합니다:

| 도구                | 설명                 | 필수 런타임                |
| -------------------- | --------------------------- | ----------------------------- |
| **bash**             | 셸 명령 실행 | 네이티브 또는 Docker              |
| **python**           | Python 스크립트 실행  | Python 3.8+ (네이티브) 또는 Docker |
| **javascript**       | Node.js 코드 실행     | Node.js 18+ (네이티브) 또는 Docker |
| **filesystem_read**  | 파일 읽기            | 네이티브 또는 Docker              |
| **filesystem_write** | 파일 쓰기          | 네이티브 또는 Docker              |
| **web_fetch**        | 웹 콘텐츠 가져오기     | 네이티브 또는 Docker              |

### 실행 보안

- **네이티브 런타임** — 데몬의 사용자 프로세스로 실행, 파일 시스템에 전체 액세스
- **Docker 런타임** — 전체 컨테이너 격리, 별도의 파일 시스템 및 네트워크

`config.toml`에서 실행 정책을 구성하세요:

```toml
[runtime]
kind = "docker"
allowed_tools = ["bash", "python", "filesystem_read"]  # 명시적 허용 목록
```

전체 보안 옵션은 [구성 참조](docs/config-reference.md#runtime)를 참조하세요.

## 배포

### 로컬 배포 (개발)

```bash
zeroclaw daemon start
zeroclaw agent start
```

### 서버 배포 (프로덕션)

systemd를 사용하여 데몬과 에이전트를 서비스로 관리하세요:

```bash
# 바이너리 설치
cargo install --path . --locked

# 작업공간 구성
zeroclaw init

# systemd 서비스 파일 생성
sudo cp deployment/systemd/zeroclaw-daemon.service /etc/systemd/system/
sudo cp deployment/systemd/zeroclaw-agent.service /etc/systemd/system/

# 서비스 활성화 및 시작
sudo systemctl enable zeroclaw-daemon zeroclaw-agent
sudo systemctl start zeroclaw-daemon zeroclaw-agent

# 상태 확인
sudo systemctl status zeroclaw-daemon
sudo systemctl status zeroclaw-agent
```

전체 프로덕션 배포 지침은 [네트워크 배포 가이드](docs/network-deployment.md)를 참조하세요.

### Docker

```bash
# 이미지 빌드
docker build -t zeroclaw:latest .

# 컨테이너 실행
docker run -d \
  --name zeroclaw \
  -v ~/.zeroclaw/workspace:/workspace \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  zeroclaw:latest
```

빌드 세부 정보 및 구성 옵션은 [`Dockerfile`](Dockerfile)을 참조하세요.

### 엣지 하드웨어

ZeroClaw는 저전력 하드웨어에서 실행되도록 설계되었습니다:

- **Raspberry Pi Zero 2 W** — ~512 MB RAM, 단일 ARMv8 코어, < $5 하드웨어 비용
- **Raspberry Pi 4/5** — 1 GB+ RAM, 멀티코어, 동시 워크로드에 이상적
- **Orange Pi Zero 2** — ~512 MB RAM, 쿼드코어 ARMv8, 초저비용
- **x86 SBCs (Intel N100)** — 4-8 GB RAM, 빠른 빌드, 네이티브 Docker 지원

장치별 설정 지침은 [하드웨어 가이드](docs/hardware/README.md)를 참조하세요.

## 터널링 (공개 노출)

보안 터널을 통해 로컬 ZeroClaw 데몬을 공개 네트워크에 노출하세요:

```bash
zeroclaw tunnel start --provider cloudflare
```

지원되는 터널 제공자:

- **Cloudflare Tunnel** — 무료 HTTPS, 포트 노출 없음, 멀티 도메인 지원
- **Ngrok** — 빠른 설정, 사용자 정의 도메인 (유료 플랜)
- **Tailscale** — 프라이빗 메시 네트워크, 공개 포트 없음

전체 구성 옵션은 [구성 참조](docs/config-reference.md#tunnel)를 참조하세요.

## 보안

ZeroClaw는 여러 보안 계층을 구현합니다:

### 페어링

데몬은 첫 실행 시 `~/.zeroclaw/workspace/.pairing`에 저장된 페어링 시크릿을 생성합니다. 클라이언트(에이전트, CLI)는 연결하기 위해 이 시크릿을 제시해야 합니다.

```bash
zeroclaw pairing rotate  # 새 시크릿 생성 및 이전 것 무효화
```

### 샌드박싱

- **Docker 런타임** — 별도의 파일 시스템 및 네트워크로 전체 컨테이너 격리
- **네이티브 런타임** — 사용자 프로세스로 실행, 기본적으로 작업공간으로 범위 지정

### 허용 목록

채널은 사용자 ID로 액세스를 제한할 수 있습니다:

```toml
[channels.telegram]
enabled = true
allowed_users = [123456789, 987654321]  # 명시적 허용 목록
```

### 암호화

- **Matrix E2EE** — 장치 확인과 함께 완전한 종단 간 암호화
- **TLS 전송** — 모든 API 및 터널 트래픽이 HTTPS/TLS 사용

전체 정책 및 관행은 [보안 문서](docs/security/README.md)를 참조하세요.

## 관찰 가능성

ZeroClaw는 기본적으로 `~/.zeroclaw/workspace/logs/`에 로그를 기록합니다. 로그는 구성 요소별로 저장됩니다:

```
~/.zeroclaw/workspace/logs/
├── daemon.log           # 데몬 로그 (시작, API 요청, 오류)
├── agent.log            # 에이전트 로그 (메시지 라우팅, 도구 실행)
├── telegram.log         # 채널별 로그 (활성화된 경우)
└── matrix.log           # 채널별 로그 (활성화된 경우)
```

### 로깅 구성

```toml
[logging]
level = "info"                           # debug, info, warn, error
path = "~/.zeroclaw/workspace/logs/"
rotation = "daily"                       # daily, hourly, size
max_size_mb = 100                        # 크기 기반 회전용
retention_days = 30                      # N일 후 자동 삭제
```

모든 로깅 옵션은 [구성 참조](docs/config-reference.md#logging)를 참조하세요.

### 메트릭 (계획 중)

프로덕션 모니터링을 위한 Prometheus 메트릭 지원이 곧 제공됩니다. [#234](https://github.com/zeroclaw-labs/zeroclaw/issues/234)에서 추적 중.

## 스킬 (Skills)

ZeroClaw는 시스템 기능을 확장하는 재사용 가능한 모듈인 사용자 정의 스킬을 지원합니다.

### 스킬 정의

스킬은 다음 구조로 `~/.zeroclaw/workspace/skills/<skill-name>/`에 저장됩니다:

```
skills/
└── my-skill/
    ├── skill.toml       # 스킬 메타데이터 (이름, 설명, 의존성)
    ├── prompt.md        # AI용 시스템 프롬프트
    └── tools/           # 선택적 사용자 정의 도구
        └── my_tool.py
```

### 스킬 예제

```toml
# skills/web-research/skill.toml
[skill]
name = "web-research"
description = "웹 검색 및 결과 요약"
version = "1.0.0"

[dependencies]
tools = ["web_fetch", "bash"]
```

```markdown
<!-- skills/web-research/prompt.md -->

당신은 연구 어시스턴트입니다. 무언가를 검색하라는 요청을 받으면:

1. web_fetch를 사용하여 콘텐츠 가져오기
2. 읽기 쉬운 형식으로 결과 요약
3. URL로 출처 인용
```

### 스킬 사용

스킬은 에이전트 시작 시 자동으로 로드됩니다. 대화에서 이름으로 참조하세요:

```
사용자: 웹 연구 스킬을 사용하여 최신 AI 뉴스 찾기
봇: [웹 연구 스킬 로드, web_fetch 실행, 결과 요약]
```

전체 스킬 생성 지침은 [스킬 (Skills)](#스킬-skills) 섹션을 참조하세요.

## Open Skills

ZeroClaw는 [Open Skills](https://github.com/openagents-com/open-skills)를 지원합니다 — AI 에이전트 기능을 확장하기 위한 모듈형 및 제공자 독립적인 시스템.

### Open Skills 활성화

```toml
[skills]
open_skills_enabled = true
# open_skills_dir = "/path/to/open-skills"  # 선택사항
```

런타임에 `ZEROCLAW_OPEN_SKILLS_ENABLED` 및 `ZEROCLAW_OPEN_SKILLS_DIR`로 재정의할 수도 있습니다.

## 개발

```bash
cargo build              # 개발 빌드
cargo build --release    # 릴리스 빌드 (codegen-units=1, Raspberry Pi 포함 모든 장치에서 작동)
cargo build --profile release-fast    # 더 빠른 빌드 (codegen-units=8, 16 GB+ RAM 필요)
cargo test               # 전체 테스트 스위트 실행
cargo clippy --locked --all-targets -- -D clippy::correctness
cargo fmt                # 포맷

# SQLite vs Markdown 비교 벤치마크 실행
cargo test --test memory_comparison -- --nocapture
```

### pre-push 훅

git 훅이 각 푸시 전에 `cargo fmt --check`, `cargo clippy -- -D warnings`, 그리고 `cargo test`를 실행합니다. 한 번 활성화하세요:

```bash
git config core.hooksPath .githooks
```

### 빌드 문제 해결 (Linux에서 OpenSSL 오류)

`openssl-sys` 빌드 오류가 발생하면 종속성을 동기화하고 저장소의 lockfile로 다시 빌드하세요:

```bash
git pull
cargo build --release --locked
cargo install --path . --force --locked
```

ZeroClaw는 HTTP/TLS 종속성에 대해 `rustls`를 사용하도록 구성되어 있습니다; `--locked`는 깨끗한 환경에서 전이적 그래프를 결정적으로 유지합니다.

개발 중 빠른 푸시가 필요할 때 훅을 건너뛰려면:

```bash
git push --no-verify
```

## 협업 및 문서

작업 기반 맵을 위해 문서 허브로 시작하세요:

- 문서 허브: [`docs/README.md`](docs/README.md)
- 통합 문서 목차: [`docs/SUMMARY.md`](docs/SUMMARY.md)
- 명령어 참조: [`docs/commands-reference.md`](docs/commands-reference.md)
- 구성 참조: [`docs/config-reference.md`](docs/config-reference.md)
- 제공자 참조: [`docs/providers-reference.md`](docs/providers-reference.md)
- 채널 참조: [`docs/channels-reference.md`](docs/channels-reference.md)
- 운영 런북: [`docs/operations-runbook.md`](docs/operations-runbook.md)
- 문제 해결: [`docs/troubleshooting.md`](docs/troubleshooting.md)
- 문서 인벤토리/분류: [`docs/docs-inventory.md`](docs/docs-inventory.md)
- PR/이슈 트리아지 스냅샷 (2026년 2월 18일 기준): [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)

주요 협업 참조:

- 문서 허브: [docs/README.md](docs/README.md)
- 문서 템플릿: [docs/doc-template.md](docs/doc-template.md)
- 문서 변경 체크리스트: [docs/README.md#4-documentation-change-checklist](docs/README.md#4-documentation-change-checklist)
- 채널 구성 참조: [docs/channels-reference.md](docs/channels-reference.md)
- Matrix 암호화 방 운영: [docs/matrix-e2ee-guide.md](docs/matrix-e2ee-guide.md)
- 기여 가이드: [CONTRIBUTING.md](CONTRIBUTING.md)
- PR 워크플로 정책: [docs/pr-workflow.md](docs/pr-workflow.md)
- 리뷰어 플레이북 (트리아지 + 심층 리뷰): [docs/reviewer-playbook.md](docs/reviewer-playbook.md)
- 소유권 및 CI 트리아지 맵: [docs/ci-map.md](docs/ci-map.md)
- 보안 공개 정책: [SECURITY.md](SECURITY.md)

배포 및 런타임 운영용:

- 네트워크 배포 가이드: [docs/network-deployment.md](docs/network-deployment.md)
- 프록시 에이전트 플레이북: [docs/proxy-agent-playbook.md](docs/proxy-agent-playbook.md)

## ZeroClaw 지원하기

ZeroClaw가 당신의 작업에 도움이 되었고 지속적인 개발을 지원하고 싶다면 여기에서 기부할 수 있습니다:

<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="커피 한 잔 사주기" /></a>

### 🙏 특별 감사

이 오픈소스 작업에 영감을 주고 지원하는 커뮤니티와 기관에 진심으로 감사드립니다:

- **Harvard University** — 지적 호기심을 키우고 가능성의 한계를 넓혀줌.
- **MIT** — 열린 지식, 오픈소스, 기술이 모두에게 접근 가능해야 한다는 신념을 옹호함.
- **Sundai Club** — 커뮤니티, 에너지, 그리고 의미 있는 것을 만들고자 하는 끊임없는 의지.
- **세계 그리고 그 너머** 🌍✨ — 오픈소스를 선한 힘으로 만드는 모든 기여자, 꿈꾸는 자, 그리고 빌더에게. 이것은 여러분을 위한 것입니다.

우리는 최고의 아이디어가 모든 곳에서 나오기 때문에 오픈소스로 구축합니다. 이것을 읽고 있다면 여러분도 그 일부입니다. 환영합니다. 🦀❤️

## ⚠️ 공식 저장소 및 사칭 경고

**이것이 유일한 공식 ZeroClaw 저장소입니다:**

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

"ZeroClaw"라고 주장하거나 ZeroClaw Labs와의 제휴를 암시하는 다른 저장소, 조직, 도메인 또는 패키지는 **승인되지 않았으며 이 프로젝트와 관련이 없습니다**. 알려진 승인되지 않은 포크는 [TRADEMARK.md](TRADEMARK.md)에 나열됩니다.

사칭 또는 상표 오용을 발견하면 [이슈를 열어](https://github.com/zeroclaw-labs/zeroclaw/issues) 신고해 주세요.

---

## 라이선스

ZeroClaw는 최대한의 개방성과 기여자 보호를 위해 듀얼 라이선스가 적용됩니다:

| 라이선스                      | 사용 사례                                            |
| ---------------------------- | ------------------------------------------------------------ |
| [MIT](LICENSE-MIT)               | 오픈소스, 연구, 학술, 개인 사용          |
| [Apache 2.0](LICENSE-APACHE) | 특허 보호, 기관, 상업 배포 |

두 라이선스 중 하나를 선택할 수 있습니다. **기여자는 자동으로 두 가지 모두에 대한 권한을 부여합니다** — 전체 기여자 계약은 [CLA.md](CLA.md)를 참조하세요.

### 상표

**ZeroClaw** 이름과 로고는 ZeroClaw Labs의 등록 상표입니다. 이 라이선스는 승인 또는 제휴를 암시하기 위해 사용할 수 있는 권한을 부여하지 않습니다. 허용 및 금지된 사용은 [TRADEMARK.md](TRADEMARK.md)를 참조하세요.

### 기여자 보호

- 기여의 **저작권을 유지**합니다
- **특허 부여** (Apache 2.0)가 다른 기여자의 특허 청구로부터 보호합니다
- 기여는 커밋 기록과 [NOTICE](NOTICE)에 **영구적으로 귀속**됩니다
- 기여함으로써 상표권이 이전되지 않습니다

## 기여하기

[CONTRIBUTING.md](CONTRIBUTING.md)와 [CLA.md](CLA.md)를 참조하세요. 트레이트를 구현하고 PR을 제출하세요:

- CI 워크플로 가이드: [docs/ci-map.md](docs/ci-map.md)
- 새 `Provider` → `src/providers/`
- 새 `Channel` → `src/channels/`
- 새 `Observer` → `src/observability/`
- 새 `Tool` → `src/tools/`
- 새 `Memory` → `src/memory/`
- 새 `Tunnel` → `src/tunnel/`
- 새 `Skill` → `~/.zeroclaw/workspace/skills/<n>/`

---

**ZeroClaw** — 오버헤드 없음. 타협 없음. 어디서나 배포. 무엇이든 교체. 🦀

## 스타 히스토리

<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="스타 히스토리 그래프" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
    </picture>
  </a>
</p>
