README.ko.md

ZeroClaw 🦀

오버헤드 없음. 타협 없음. 100% Rust. 100% 독립적.
⚡️ $10 하드웨어에서 <5MB RAM으로 실행: OpenClaw보다 99% 적은 메모리, Mac mini보다 98% 저렴!

Harvard, MIT, 그리고 Sundai.Club 커뮤니티의 학생들과 멤버들이 만들었습니다.

🌐 언어:🇺🇸 English · 🇨🇳 简体中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇻🇳 Tiếng Việt · 🇵🇭 Tagalog · 🇪🇸 Español · 🇧🇷 Português · 🇮🇹 Italiano · 🇩🇪 Deutsch · 🇫🇷 Français · 🇸🇦 العربية · 🇮🇳 हिन्दी · 🇷🇺 Русский · 🇧🇩 বাংলা · 🇮🇱 עברית · 🇵🇱 Polski · 🇨🇿 Čeština · 🇳🇱 Nederlands · 🇹🇷 Türkçe · 🇺🇦 Українська · 🇮🇩 Bahasa Indonesia · 🇹🇭 ไทย · 🇵🇰 اردو · 🇷🇴 Română · 🇸🇪 Svenska · 🇬🇷 Ελληνικά · 🇭🇺 Magyar · 🇫🇮 Suomi · 🇩🇰 Dansk · 🇳🇴 Norsk

빠른 시작 | 원클릭 설정 | 문서 허브 | 문서 목차

빠른 접근: 참조 · 운영 · 문제 해결 · 보안 · 하드웨어 · 기여하기

빠르고 가벼우며 완전히 자율적인 AI 어시스턴트 인프라
어디서나 배포. 무엇이든 교체.

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

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

📢 공지사항

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

날짜 (UTC)	수준	공지	조치
2026-02-19	중요	우리는 openagen/zeroclaw 또는 zeroclaw.org와 관련이 없습니다. zeroclaw.org 도메인은 현재 openagen/zeroclaw 포크를 가리키고 있으며, 이 도메인/저장소는 우리의 공식 웹사이트/프로젝트를 사칭하고 있습니다.	이 소스의 정보, 바이너리, 펀딩, 공지를 신뢰하지 마세요. 이 저장소와 우리의 확인된 소셜 계정만 사용하세요.
2026-02-21	중요	우리의 공식 웹사이트가 이제 온라인입니다: zeroclawlabs.ai. 기다려주셔서 감사합니다. 여전히 사칭 시도가 감지되고 있습니다: 공식 채널을 통해 게시되지 않은 ZeroClaw 이름의 모든 투자/펀딩 활동에 참여하지 마세요.	이 저장소를 유일한 진실의 원천으로 사용하세요. X (@zeroclawlabs), Telegram (@zeroclawlabs), Facebook (그룹), Reddit (r/zeroclawlabs), 그리고 Xiaohongshu를 팔로우하여 공식 업데이트를 받으세요.
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.

✨ 기능

• 🏎️ 기본 경량 런타임: 일반적인 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 수치는 런타임 메모리이며, 빌드 시간 컴파일 요구사항은 더 높습니다.

재현 가능한 로컬 측정

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

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

사전 요구사항

Windows

Windows — 필수

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

   winget install Microsoft.VisualStudio.2022.BuildTools

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

2. Rust 툴체인:

   winget install Rustlang.Rustup

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

3. 확인: 둘 다 작동하는지 확인:

   rustc --version
   cargo --version

Windows — 선택사항

• Docker Desktop — Docker 샌드박스 런타임을 사용하는 경우에만 필요(runtime.kind = "docker"). winget install Docker.DockerDesktop을 통해 설치.

Linux / macOS

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 툴체인:

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

   자세한 내용은 rustup.rs를 참조하세요.

3. 확인:

   rustc --version
   cargo --version

Linux / macOS — 선택사항

• Docker — Docker 샌드박스 런타임을 사용하는 경우에만 필요(runtime.kind = "docker").
  • Linux (Debian/Ubuntu): docs.docker.com 참조
  • Linux (Fedora/RHEL): docs.docker.com 참조
  • macOS: docker.com/products/docker-desktop에서 Docker Desktop 설치

빠른 시작

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

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

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/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: 수동 설치

클릭하여 수동 설치 단계 보기

# 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

설치 후

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

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

다음 단계:

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

구성

제공자, 채널 및 시스템 동작을 구성하려면 ~/.zeroclaw/workspace/config.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 필요)

전체 참조 문서:

• 구성 참조 — 모든 설정, 검증, 기본값
• 제공자 참조 — AI 제공자별 구성
• 채널 참조 — Telegram, Matrix, Slack, Discord 등
• 운영 — 프로덕션 모니터링, 시크릿 교체, 스케일링

현재 런타임 지원

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

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

엄격한 샌드박싱이나 네트워크 격리가 필요한 경우 runtime.kind = "docker"를 사용하세요. 자세한 내용은 구성 참조를 참조하세요.

명령어

# 작업공간 관리
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             # 버전 및 빌드 정보 표시

전체 옵션 및 예제는 명령어 참조를 참조하세요.

아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                        채널 (트레이트)                           │
│  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 교체

자세한 다이어그램과 구현 세부 정보는 아키텍처 문서를 참조하세요.

예제

텔레그램 봇

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

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

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

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

Matrix (종단 간 암호화)

[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 가이드를 참조하세요.

다중 제공자

[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로 장애 조치합니다.

사용자 정의 메모리

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

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

[memory]
kind = "markdown"
path = "~/.zeroclaw/workspace/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 호환 엔드포인트를 지원합니다:

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

예: LiteLLM을 프록시로 사용하여 OpenAI 인터페이스를 통해 모든 LLM에 액세스.

전체 구성 세부 정보는 제공자 참조를 참조하세요.

채널 지원

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

전체 구성 지침은 채널 참조를 참조하세요.

도구 지원

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에서 실행 정책을 구성하세요:

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

전체 보안 옵션은 구성 참조를 참조하세요.

배포

로컬 배포 (개발)

zeroclaw daemon start
zeroclaw agent start

서버 배포 (프로덕션)

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

# 바이너리 설치
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

전체 프로덕션 배포 지침은 네트워크 배포 가이드를 참조하세요.

Docker

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

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

빌드 세부 정보 및 구성 옵션은 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 지원

장치별 설정 지침은 하드웨어 가이드를 참조하세요.

터널링 (공개 노출)

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

zeroclaw tunnel start --provider cloudflare

지원되는 터널 제공자:

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

전체 구성 옵션은 구성 참조를 참조하세요.

보안

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

페어링

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

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

샌드박싱

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

허용 목록

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

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

암호화

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

전체 정책 및 관행은 보안 문서를 참조하세요.

관찰 가능성

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

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

로깅 구성

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

모든 로깅 옵션은 구성 참조를 참조하세요.

메트릭 (계획 중)

프로덕션 모니터링을 위한 Prometheus 메트릭 지원이 곧 제공됩니다. #234에서 추적 중.

스킬 (Skills)

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

스킬 정의

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

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

스킬 예제

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

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

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

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

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

스킬 사용

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

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

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

Open Skills

ZeroClaw는 Open Skills를 지원합니다 — AI 에이전트 기능을 확장하기 위한 모듈형 및 제공자 독립적인 시스템.

Open Skills 활성화

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

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

개발

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를 실행합니다. 한 번 활성화하세요:

git config core.hooksPath .githooks

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

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

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

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

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

git push --no-verify

협업 및 문서

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

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

주요 협업 참조:

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

배포 및 런타임 운영용:

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

ZeroClaw 지원하기

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

🙏 특별 감사

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

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

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

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

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

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

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

사칭 또는 상표 오용을 발견하면 이슈를 열어 신고해 주세요.

---

라이선스

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

라이선스	사용 사례
MIT	오픈소스, 연구, 학술, 개인 사용
Apache 2.0	특허 보호, 기관, 상업 배포

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

상표

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

기여자 보호

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

기여하기

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

• CI 워크플로 가이드: 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 — 오버헤드 없음. 타협 없음. 어디서나 배포. 무엇이든 교체. 🦀

스타 히스토리