IronClaw

IronClaw

언제나 당신 편인 안전한 개인 AI 어시스턴트

License: MIT OR Apache-2.0 Telegram: @ironclawAI Reddit: r/ironclawAI gitcgr

English | 简体中文 | Русский | 日本語 | 한국어

철학 • 기능 • 설치 • 설정 • 보안 • 아키텍처

--- ## 철학 IronClaw는 단순한 원칙 위에 만들어졌습니다: **AI 어시스턴트는 당신을 위해 일해야 하며, 당신을 거슬러서는 안 됩니다**. AI 시스템이 데이터 처리에 대해 점점 더 불투명해지고 기업의 이익에 맞춰지는 세상에서, IronClaw는 다른 접근 방식을 취합니다: - **데이터는 당신의 것** - 모든 정보는 로컬에 저장되고 암호화되며, 절대 당신의 통제를 벗어나지 않습니다 - **설계에 의한 투명성** - 오픈 소스, 감사 가능, 숨겨진 텔레메트리나 데이터 수집 없음 - **자가 확장 기능** - 공급업체의 업데이트를 기다리지 않고 즉석에서 새로운 도구를 만들 수 있습니다 - **심층 방어** - 프롬프트 인젝션 및 데이터 유출로부터 보호하는 다중 보안 계층 IronClaw는 개인적, 직업적 삶에서 실제로 신뢰할 수 있는 AI 어시스턴트입니다. ## 기능 ### 보안 우선 - **WASM 샌드박스** - 신뢰할 수 없는 도구는 권한 기반의 격리된 WebAssembly 컨테이너에서 실행됩니다 - **자격 증명 보호** - 비밀은 도구에 노출되지 않고, 누출 감지와 함께 호스트 경계에서 주입됩니다 - **프롬프트 인젝션 방어** - 패턴 감지, 콘텐츠 정화, 정책 시행 - **엔드포인트 화이트리스트** - HTTP 요청은 명시적으로 승인된 호스트와 경로로만 전송됩니다 ### 항상 사용 가능 - **다중 채널** - REPL, HTTP 웹훅, WASM 채널 (Telegram, Slack), 웹 게이트웨이 - **Docker 샌드박스** - 작업별 토큰과 오케스트레이터/워커 패턴을 사용한 격리된 컨테이너 실행 - **웹 게이트웨이** - 실시간 SSE/WebSocket 스트리밍이 있는 브라우저 UI - **루틴** - 백그라운드 자동화를 위한 cron 일정, 이벤트 트리거, 웹훅 핸들러 - **하트비트 시스템** - 모니터링 및 유지 보수 작업을 위한 사전 백그라운드 실행 - **병렬 작업** - 격리된 컨텍스트로 여러 요청을 동시에 처리합니다 - **자가 복구** - 중단된 작업의 자동 감지 및 복구 ### 자가 확장 - **동적 도구 빌드** - 필요한 것을 설명하면 IronClaw가 WASM 도구로 만들어 줍니다 - **MCP 프로토콜** - 추가 기능을 위해 Model Context Protocol 서버에 연결합니다 - **플러그인 아키텍처** - 재시작 없이 새로운 WASM 도구와 채널을 추가할 수 있습니다 ### 영구 메모리 - **하이브리드 검색** - Reciprocal Rank Fusion을 사용한 전체 텍스트 + 벡터 검색 - **워크스페이스 파일시스템** - 노트, 로그, 컨텍스트를 위한 유연한 경로 기반 저장소 - **아이덴티티 파일** - 세션 간 일관된 성격과 선호도를 유지합니다 ## 설치 ### 사전 요구 사항 - Rust 1.85+ - [pgvector](https://github.com/pgvector/pgvector) 확장이 있는 PostgreSQL 15+ - NEAR AI 계정 (인증은 설정 마법사를 통해 처리됨) ## 다운로드 또는 빌드 [릴리스 페이지](https://github.com/nearai/ironclaw/releases/)를 방문하여 최신 업데이트를 확인하세요.
Windows 인스톨러로 설치 (Windows) [Windows 인스톨러](https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-x86_64-pc-windows-msvc.msi)를 다운로드하여 실행하세요.
PowerShell 스크립트로 설치 (Windows) ```sh irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex ```
셸 스크립트로 설치 (macOS, Linux, Windows/WSL) ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh ```
Homebrew로 설치 (macOS/Linux) ```sh brew install ironclaw ```
소스 코드 컴파일 (Windows, Linux, macOS의 Cargo) `cargo`로 설치하세요. 컴퓨터에 [Rust](https://rustup.rs)가 설치되어 있는지 확인하세요. ```bash # 저장소 복제 git clone https://github.com/nearai/ironclaw.git cd ironclaw # 빌드 cargo build --release # 테스트 실행 cargo test ``` **전체 릴리스**의 경우 (채널 소스를 수정한 후), `./scripts/build-all.sh`를 실행하여 채널을 먼저 다시 빌드하세요.
### 데이터베이스 설정 ```bash # 데이터베이스 생성 createdb ironclaw # pgvector 활성화 psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;" ``` ## 설정 설정 마법사를 실행하여 IronClaw를 구성하세요: ```bash ironclaw onboard ``` 마법사는 데이터베이스 연결, NEAR AI 인증 (브라우저 OAuth를 통해), 그리고 비밀 암호화 (시스템 키체인 사용)를 처리합니다. 설정은 연결된 데이터베이스에 저장됩니다. 부트스트랩 변수 (예: `DATABASE_URL`, `LLM_BACKEND`)는 데이터베이스가 연결되기 전에 사용할 수 있도록 `~/.ironclaw/.env`에 기록됩니다. ### 대체 LLM 공급자 IronClaw는 기본적으로 NEAR AI를 사용하지만 많은 LLM 공급자를 기본 지원합니다. 내장 공급자에는 **Anthropic**, **OpenAI**, **GitHub Copilot**, **Google Gemini**, **MiniMax**, **Mistral**, **Ollama** (로컬)이 포함됩니다. **OpenRouter** (300+ 모델), **Together AI**, **Fireworks AI**, 자체 호스팅 서버 (**vLLM**, **LiteLLM**) 같은 OpenAI 호환 서비스도 지원됩니다. 마법사에서 공급자를 선택하거나 환경 변수를 직접 설정하세요: ```env # 예: MiniMax (내장, 204K 컨텍스트) LLM_BACKEND=minimax MINIMAX_API_KEY=... # 예: OpenAI 호환 엔드포인트 LLM_BACKEND=openai_compatible LLM_BASE_URL=https://openrouter.ai/api/v1 LLM_API_KEY=sk-or-... LLM_MODEL=anthropic/claude-sonnet-4 ``` 전체 공급자 가이드는 [docs/capabilities/llm-providers.md](docs/capabilities/llm-providers.md)를 참조하세요. ## 보안 IronClaw는 데이터를 보호하고 오용을 방지하기 위해 심층 방어를 구현합니다. ### WASM 샌드박스 신뢰할 수 없는 모든 도구는 격리된 WebAssembly 컨테이너에서 실행됩니다: - **권한 기반 권한** - HTTP, 비밀, 도구 호출에 대한 명시적 옵트인 - **엔드포인트 화이트리스트** - HTTP 요청은 승인된 호스트/경로로만 전송됩니다 - **자격 증명 주입** - 비밀은 호스트 경계에서 주입되며, WASM 코드에 절대 노출되지 않습니다 - **누출 감지** - 비밀 유출 시도에 대해 요청과 응답을 스캔합니다 - **속도 제한** - 남용을 방지하기 위한 도구별 요청 제한 - **리소스 제한** - 메모리, CPU, 실행 시간 제약 ``` WASM ──► 화이트리스트 ──► 누출 스캔 ──► 자격 증명 ──► 실행 ──► 누출 스캔 ──► WASM 검증기 (요청) 주입기 요청 (응답) ``` ### 프롬프트 인젝션 방어 외부 콘텐츠는 여러 보안 계층을 통과합니다: - 인젝션 시도의 패턴 기반 감지 - 콘텐츠 정화 및 이스케이핑 - 심각도 수준이 있는 정책 규칙 (차단/경고/검토/정화) - 안전한 LLM 컨텍스트 주입을 위한 도구 출력 래핑 ### 데이터 보호 - 모든 데이터는 로컬 PostgreSQL 데이터베이스에 저장됩니다 - 비밀은 AES-256-GCM으로 암호화됩니다 - 텔레메트리, 분석, 데이터 공유 없음 - 모든 도구 실행에 대한 전체 감사 로그 ## 아키텍처 ``` ┌────────────────────────────────────────────────────────────────┐ │ 채널 │ │ ┌──────┐ ┌──────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ REPL │ │ HTTP │ │ WASM 채널 │ │ 웹 게이트웨이│ │ │ └──┬───┘ └──┬───┘ └──────┬──────┘ │ (SSE + WS) │ │ │ │ │ │ └──────┬──────┘ │ │ └─────────┴──────────────┴────────────────┘ │ │ │ │ │ ┌─────────▼─────────┐ │ │ │ 에이전트 루프 │ 의도 라우팅 │ │ └────┬──────────┬───┘ │ │ │ │ │ │ ┌──────────▼────┐ ┌──▼───────────────┐ │ │ │ 스케줄러 │ │ 루틴 엔진 │ │ │ │ (병렬 작업) │ │ (cron, 이벤트, wh)│ │ │ └──────┬────────┘ └────────┬─────────┘ │ │ │ │ │ │ ┌─────────────┼────────────────────┘ │ │ │ │ │ │ ┌───▼─────┐ ┌────▼────────────────┐ │ │ │ 로컬 │ │ 오케스트레이터 │ │ │ │ 워커 │ │ ┌───────────────┐ │ │ │ │(인프로세스)│ │ │Docker 샌드박스│ │ │ │ └───┬─────┘ │ │ 컨테이너 │ │ │ │ │ │ │ ┌───────────┐ │ │ │ │ │ │ │ │Worker / CC│ │ │ │ │ │ │ │ └───────────┘ │ │ │ │ │ │ └───────────────┘ │ │ │ │ └─────────┬───────────┘ │ │ └──────────────────┤ │ │ │ │ │ ┌───────────▼──────────┐ │ │ │ 도구 레지스트리 │ │ │ │ 내장, MCP, WASM │ │ │ └──────────────────────┘ │ └────────────────────────────────────────────────────────────────┘ ``` ### 핵심 구성 요소 | 구성 요소 | 목적 | |-----------|---------| | **에이전트 루프** | 주요 메시지 처리 및 작업 조정 | | **라우터** | 사용자 의도 분류 (명령, 쿼리, 작업) | | **스케줄러** | 우선순위가 있는 병렬 작업 실행 관리 | | **워커** | LLM 추론과 도구 호출로 작업 실행 | | **오케스트레이터** | 컨테이너 라이프사이클, LLM 프록시, 작업별 인증 | | **웹 게이트웨이** | 채팅, 메모리, 작업, 로그, 확장, 루틴이 있는 브라우저 UI | | **루틴 엔진** | 예약된 (cron) 및 반응형 (이벤트, 웹훅) 백그라운드 작업 | | **워크스페이스** | 하이브리드 검색이 있는 영구 메모리 | | **안전 계층** | 프롬프트 인젝션 방어 및 콘텐츠 정화 | ## 사용법 Engine v2는 현재 옵트인입니다. 기존 에이전트 루프 대신 새 엔진을 사용하려면 `ENGINE_V2=true`를 설정해서 IronClaw를 시작하세요. ```bash # 첫 설정 (데이터베이스, 인증 등 구성) ironclaw onboard # 설치된 바이너리 시작 ironclaw # Engine v2로 설치된 바이너리 시작 ENGINE_V2=true ironclaw # 소스에서 대화형 REPL 시작 cargo run # 소스에서 Engine v2 대화형 REPL 시작 ENGINE_V2=true cargo run # Engine v2를 디버그 로깅과 함께 시작 ENGINE_V2=true RUST_LOG=ironclaw=debug cargo run ``` ## 개발 ```bash # 코드 포맷 cargo fmt # 린트 cargo clippy --all --benches --tests --examples --all-features # 테스트 실행 createdb ironclaw_test cargo test # 특정 테스트 실행 cargo test test_name ``` - **채널**: Telegram, Discord 및 기타 채널 설정은 [docs/channels/overview.mdx](docs/channels/overview.mdx)를 참조하세요. - **채널 소스 변경**: 업데이트된 WASM이 번들되도록 `cargo build` 전에 `./channels-src/telegram/build.sh`를 실행하세요. ## OpenClaw 역사 IronClaw는 [OpenClaw](https://github.com/openclaw/openclaw)에서 영감을 받은 Rust 재구현입니다. 전체 추적 매트릭스는 [FEATURE_PARITY.md](FEATURE_PARITY.md)를 참조하세요. 주요 차이점: - **Rust vs TypeScript** - 네이티브 성능, 메모리 안전, 단일 바이너리 - **WASM 샌드박스 vs Docker** - 가벼운 권한 기반 보안 - **PostgreSQL vs SQLite** - 프로덕션 준비된 영속성 - **보안 우선 설계** - 다중 방어 계층, 자격 증명 보호 ## 라이선스 다음 중 하나를 선택하여 라이선스가 부여됩니다: - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) - MIT License ([LICENSE-MIT](LICENSE-MIT)) 원하는 대로 선택할 수 있습니다.