이 레포가 무엇을 하는 물건인가.
대부분의 AI 에이전트는 "안녕"이든 "이 코드 리팩터링해줘"든 똑같이 최고가 모델 하나로 처리한다. OpenSquilla는 매 턴마다 질문의 난이도를 먼저 기계가 분류해, 쉬운 건 싼 모델·어려운 것만 비싼 모델로 보낸다. 결과는 같은 답을 1/9 가격에.
OpenSquilla는 토큰 효율(token-efficient)을 최우선으로 설계한 마이크로커널(microkernel) AI 에이전트다. 마이크로커널은 운영체제 설계 용어로, 아주 작은 핵심(커널)만 두고 나머지 기능은 갈아끼울 수 있는 부품(플러그인)으로 빼는 구조를 말한다. 여기서는 "모델 호출 루프"라는 작은 심장만 고정해 두고, LLM 제공자·도구·채널·스킬을 전부 교체 가능한 부품으로 만들었다.
핵심 동작은 단순하다. 사용자가 메시지를 보내면 → 로컬에서 도는 분류기가 난이도(c0~c3)를 매기고 → 그 등급에 맞는 가장 싼 모델을 고르고 → 답을 만들고 → 대화를 기억에 저장한다. 이 모든 게 웹 UI든 터미널이든 슬랙이든 동일한 한 루프로 돌아간다.
Squilla(스퀼라)는 갯가재(mantis shrimp)의 학명 속(屬) 이름이다. 작지만 펀치 한 방이 총알급으로 빠른 바다 생물 — "작은 몸집, 큰 한 방"이라는 토큰 효율 컨셉과 맞닿아 있고, 테마색을 바다 청록으로 잡은 이유이기도 하다. 프로젝트 README는 OpenClaw라는 에이전트에서 영감을 받았다고 밝힌다.
트렌딩 이유 · 경쟁 대비 장점.
2026년 AI 에이전트 판의 가장 큰 고민은 성능이 아니라 비용이다. Claude Opus 같은 최상위 모델은 똑똑하지만 비싸서, 에이전트가 자율적으로 수십 턴을 돌면 요금이 폭발한다. OpenSquilla가 트렌딩에 오른 건 바로 이 지점을 정면으로 친 "같은 예산, 더 높은 지능 밀도(intelligence density)" 구호 때문이다.
README가 공개한 벤치마크가 메시지를 압축한다. PinchBench 25개 과제 평균에서, OpenSquilla는 OpenClaw(Opus 단일 모델)와 점수는 사실상 동률(0.9251 vs 0.9255)인데 비용은 $0.688 vs $6.233 — 약 9분의 1이었다.
| 비교 항목 | 일반적 에이전트 | OpenSquilla |
|---|---|---|
| 모델 선택 | 모든 턴을 단일 최상위 모델로 | 턴마다 난이도 분류 → 4단계 중 최저가 선택 |
| 난이도 판단 | 없음 / 클라우드 호출 | 로컬 분류기(프롬프트가 기기를 안 떠남) |
| 추론 토큰 | 항상 길게 사고 | 필요할 때만 깊은 사고 켜짐 |
| 스킬 로딩 | 전부 컨텍스트에 상주 | 이번 작업에 필요한 스킬만 로드 |
| 벤치 비용(PinchBench) | $6.233 (OpenClaw) | $0.688 (≈9× 절감) |
단일 고가 모델 에이전트는 "안녕하세요" 같은 사소한 턴에도 풀 추론·풀 시스템 프롬프트·전체 스킬을 끌고 들어간다. 작업이 길어질수록 낭비 토큰이 복리로 쌓여 청구서가 감당 안 되는 수준으로 커진다.
로컬 분류기가 턴마다 등급을 매겨 싼 모델로 충분한 건 싸게 처리하고, 시스템 프롬프트·추론 깊이·로드되는 스킬까지 난이도에 맞춰 늘렸다 줄인다. "하나의 답에 필요한 만큼만" 자원을 쓰는 게 핵심.
여기에 셀프호스팅·프라이버시 매력이 더해진다. 라우팅 분류가 기기 안(CPU ONNX)에서 돌기 때문에 "어떤 모델로 보낼지 정하려고 프롬프트를 외부로 보내는 일"이 없다. 임베딩도 기본은 로컬이라, 메모리 검색용 벡터화 역시 내 컴퓨터를 안 떠난다.
백엔드·라우팅 모델·인프라 한눈에. (대부분 Python)
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| 언어/런타임 | Python 3.12+ · uv | 전체 런타임. 설치는 uv tool / pip --user. |
| 웹 게이트웨이 | Starlette + Uvicorn | ASGI 서버 + WebSocket RPC + /control/ 콘솔. |
| 데이터 검증 | Pydantic 2 · SQLModel | 설정·메시지 스키마, ORM 모델. |
| 저장소 | SQLite(aiosqlite) · sqlite-vec | 세션·트랜스크립트 + 벡터 의미검색. |
| 라우팅 모델 | LightGBM + ONNX BGE | 턴 난이도 c0~c3 분류(recommended 익스트라). |
| 로컬 추론 | onnxruntime · tokenizers · scikit-learn | CPU에서 분류·임베딩 실행. |
| CLI/TUI | Typer · Rich · prompt-toolkit | 명령행 도구·대화형 REPL·온보딩 마법사. |
| 스케줄러 | apscheduler · croniter | cron 식 파싱·예약 작업 엔진. |
| 채널 SDK | telegram · lark-oapi · dingtalk · qq · matrix-nio | 슬랙/텔레그램/피슈/딩톡/매트릭스 등 어댑터. |
| 문서 도구 | python-docx · pptx · openpyxl · pypdf · reportlab · weasyprint · pdfplumber | 번들 스킬이 쓰는 docx/pptx/xlsx/pdf 처리. |
| 인프라 | Docker(python:3.13-slim) · git-lfs | 컨테이너 배포 + 라우터 모델 자산(LFS) 전달. |
메시지 하나가 들어와 답이 나가기까지, 흐름 한 줄기를 끝까지 따라간다.
먼저 독수리 시점. 모든 입구(웹 UI·CLI·채팅 채널)는 게이트웨이(Gateway)로 모이고, 게이트웨이는 메시지를 정규화해 TurnRunner라는 단일 루프에 넘긴다. TurnRunner는 정해진 순서의 스테이지(stage)들을 차례로 통과시키는데, 그 중간에 SquillaRouter 스텝이 끼어 "이 턴을 어느 등급(c0~c3) 모델로 보낼지"를 로컬에서 정한다.
이제 흐름 한 줄기를 따라가 보자. "사용자가 슬랙에서 질문을 던졌다"고 하면:
① 슬랙 어댑터(channels/slack.py)가 메시지를 받아 게이트웨이로 넘긴다. ② 게이트웨이가 입력을 표준 형태로 정규화하고 TurnRunner를 깨운다. ③ TurnRunner의 prompt_assembler 스테이지가 파이프라인 스텝들을 돌리는데, 그 중 squilla_router.py 스텝이 질문 텍스트의 길이·언어·코드블록·키워드 + 의미 임베딩을 뽑아 LightGBM/ONNX 분류기로 c0~c3 등급을 매긴다(이 계산은 CPU에서, 기기 안에서). ④ resolve_model 스테이지가 그 등급에 묶인 가장 싼 모델을 고른다. ⑤ provider_and_tools가 해당 제공자(OpenRouter·Anthropic·DeepSeek 등)를 깨우고 도구 목록을 준비한다. ⑥ stream_consumer가 모델 답을 한 조각씩 흘려보내며, 도구 호출이 나오면 샌드박스 정책을 거쳐 실행한다. ⑦ 마지막 turn_finalizer가 비용을 정산하고 트랜스크립트를 남기고 이번 대화를 기억(working tier)에 캡처한다.
input → bootstrap → attachment → compaction → prompt_assembler → resolve_model → provider_and_tools → stream_consumer → turn_finalizer의 작은 단계로 쪼갠 구조. 각 단계가 독립적이라 "라우팅만 바꾸기", "압축 로직만 교체하기"가 쉽다. 공장 컨베이어벨트에 공정을 한 칸씩 끼워 넣는 것과 같다.등급 표기가 코드 곳곳에서 c0·c1·c2·c3(또는 옛 별칭 T0~T3, 라우트클래스 R0~R3)로 나온다. 숫자가 클수록 어려운 턴 → 더 비싸고 똑똑한 모델. 사고 깊이도 여기 연동돼 c0=사고 끔, c3=깊은 사고로 매핑된다. 처음 코드를 볼 때 "c숫자 = 난이도/비용 등급"이라고만 잡아두면 길을 안 잃는다.
어떤 폴더가 무슨 일을 하나. (핵심은 src/opensquilla/ 아래)
| 폴더 | 역할 |
|---|---|
engine/ | 핵심 중의 핵심 — 한 턴을 처리하는 TurnRunner 루프와 스테이지·스텝. |
squilla_router/ | 토큰 절약의 엔진. v4_phase3.py가 번들된 LGBM/ONNX 모델로 c0~c3 등급을 낸다. |
memory/ | working/episodic/semantic/raw 4계층 + dream/ 수면 통합. |
sandbox/ | 도구·코드 실행을 가두는 보안층. 거부 원장·intent/stale 캐시 포함. |
provider/ · channels/ | 각각 "어떤 모델에게" / "어떤 메신저로" — 교체 가능한 어댑터 모음. |
gateway/ | 모든 입구가 만나는 ASGI 서버. rpc/에 기능별 원격 호출 핸들러. |
skills/bundled/ | deep-research·github·pptx·xlsx·cron 등 즉시 쓰는 스킬 + meta 스킬. |
이 레포에서 배울 만한 것 + 어느 폴더를 보면 되는지.
큰 LLM에게 보내기 전에, 가볍고 빠른 분류기(LightGBM+임베딩)로 난이도를 먼저 판정하는 패턴을 통째로 배울 수 있다. 특징(feature)을 길이·언어·코드블록 유무·키워드 같은 하이브리드 신호로 뽑아 등급을 내는 실전 코드가 squilla_router/에 있다. "LLM 비용을 어떻게 줄이지?"에 대한 가장 구체적인 답.
채널마다 코드를 복붙하지 않고 어댑터 + 공유 TurnRunner로 묶는 설계. channels/contract.py(채널 계약)와 engine/turn_runner/를 같이 읽으면, "포트와 어댑터(헥사고날) 아키텍처"가 실제 프로젝트에서 어떻게 생겼는지 감이 온다.
working→episodic→semantic→raw 계층, FTS 키워드 검색 + sqlite-vec 의미검색의 하이브리드, 그리고 잠잘 때 기억이 정리되듯 흩어진 기록을 합치는 Dream 통합. memory/와 memory/dream/은 "RAG를 넘어선 에이전트 장기기억"을 공부하기 좋은 교본이다.
도구 호출을 STANDARD/STRICT/LOCKED 3등급 권한 행렬로 통제하고, 리눅스에선 Bubblewrap으로 코드를 격리 실행한다. 반복 거부를 세는 거부 원장(denial ledger), 거부된 출력을 다시 못 꺼내게 하는 캐시, 모든 도구 결과의 XML 이스케이프 같은 프롬프트 인젝션 방어 기법이 sandbox/에 모여 있다.
온보딩은 비대화 환경(SSH·CI)에서 비밀키를 값이 아니라 이름으로 넘기는 점이 인상적이다 — 보안 습관을 코드로 강제한 예시:
# 키 값을 직접 타이핑하지 않고, 환경변수 "이름"만 전달
export OPENROUTER_API_KEY="sk-..."
opensquilla onboard \
--provider openrouter \
--model deepseek/deepseek-v4-flash \
--api-key-env OPENROUTER_API_KEY # 값(sk-...)이 아니라 이름을 넘긴다돌리려면 무엇이 필요한가. (순수 SW — 특수 하드웨어 불필요)
| 항목 | 요구사항 |
|---|---|
| 런타임 | Python 3.12+ (소스/uv 설치 시). 포터블 zip은 자체 CPython 번들. |
| 패키지 도구 | uv 권장 또는 pip ≥ 23 |
| Git LFS | 필수 — recommended 라우터 모델 자산이 LFS로 저장됨(없으면 설치 실패). |
| OS | macOS · Linux · Windows · WSL2. 단 코드 실행 격리는 리눅스(Bubblewrap)만 완전 동작(macOS Seatbelt는 현재 SBPL 생성까지만). |
| 가속기 | GPU 불필요 — 분류·임베딩이 CPU(onnxruntime)에서 돈다. |
| 네트워크 | 기본은 127.0.0.1:18791 루프백. 외부 노출은 명시적 --listen 0.0.0.0 + 인증 설정 필요. |
| 배포(선택) | Docker(compose.yaml, python:3.13-slim, 컨테이너 포트 18791) — 파이썬 툴체인 없이 기동. |
LFS 미설치 시 라우터 가중치 자리에 version https://git-lfs.github.com/spec/v1 같은 포인터 파일만 들어와 recommended 프로파일이 깨진다. 반드시 git lfs install 후 git lfs pull --include="src/opensquilla/squilla_router/models/**".
[auth] mode = "none"로 공개 바인딩 금지인증을 끈 채 0.0.0.0으로 열면 누구나 에이전트 콘솔에 접근할 수 있다. 공개 전 토큰/비밀번호 인증을 먼저 켜고, 방화벽·보안그룹에서 해당 포트를 통제할 것.
난이도별로 손에 익히는 단계.
git-lfs·uv 설치 → 클론 → bash install.sh → opensquilla onboard로 제공자 하나 연결 → opensquilla gateway run. 브라우저로 http://127.0.0.1:18791/control/를 열고 curl .../health가 OK를 주는지 본다.
opensquilla onboard --router disabled(단일 모델)와 recommended(라우팅)를 번갈아 설정해, 쉬운 질문 묶음을 던지고 어떤 등급(c0~c3)으로 분류되는지·토큰/비용 차이를 관찰한다. 토큰 절약이 실제로 일어나는지 내 눈으로 확인.
opensquilla configure channels로 텔레그램/슬랙 봇을 연결해, 같은 에이전트를 메신저에서 호출해 본다. "입구만 바뀌고 핵심 루프는 같다"는 단일 루프 설계를 체감.
opensquilla cron으로 "매일 아침 요약" 같은 작업을 등록하고, scheduler/의 CronExpression 파서·stagger·reaper·heartbeat가 어떻게 도는지 코드로 추적한다.
번들된 skill-creator를 참고해 작은 스킬(예: 특정 API 조회)을 만들어 skills/ 규약대로 등록하고, "필요할 때만 컨텍스트에 로드되는지"(on-demand)를 확인한다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 / 볼 곳 |
|---|---|---|
| 1주차 | 로컬 기동 · ASGI 게이트웨이 이해 | README · gateway/app.py · Starlette 공식 문서 |
| 2주차 | TurnRunner 한 턴 흐름 추적 | engine/turn_runner/ · engine/steps/ 정독 |
| 3주차 | ML 기반 모델 라우팅 | squilla_router/ · LightGBM·ONNX·임베딩 분류 기초 |
| 4주차 | 에이전트 장기기억 + 벡터검색 | memory/·memory/dream/ · sqlite-vec · RAG 개념 |
| 5주차 | 보안 샌드박스 · 프롬프트 인젝션 방어 | sandbox/ · Bubblewrap · 권한 행렬 |
| 6주차 | 내 프로젝트에 라우팅/멀티채널 이식 | provider/·channels/ 어댑터 패턴 · MCP |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| 마이크로커널 | 작은 핵심만 고정하고 나머지 기능은 교체 가능한 부품으로 빼는 설계. 여기선 "모델 루프"만 커널. |
| 토큰 효율 | 같은 결과를 더 적은 입력/출력 토큰으로 — 곧 더 적은 비용으로 — 내는 것. 이 레포의 정체성. |
| SquillaRouter | 매 턴 난이도를 c0~c3로 분류해 최저가 모델을 고르는 로컬 ML 라우터. |
| c0~c3 (T0~T3) | 턴 난이도/비용 등급. 0=가장 쉬움·싼 모델·사고 끔, 3=가장 어려움·비싼 모델·깊은 사고. |
| TurnRunner | 모든 입구가 공유하는 "대화 한 턴 처리" 단일 루프. 스테이지 파이프라인으로 구성. |
| Gateway | 웹·CLI·채널을 한데 모으는 Starlette ASGI 서버(+/control/ 콘솔). |
| 4단계 기억 | working(현재)→episodic(경험)→semantic(사실/규칙)→raw(원본) 인지 계층. |
| Dream 통합 | 주기적으로 흩어진 episodic 기록을 구조화된 지식으로 합치는 과정(수면 통합 비유). |
| Bubblewrap | 리눅스에서 프로세스를 격리 실행하는 샌드박스 도구. 에이전트 코드 실행을 가둠. |
| 거부 원장 | 샌드박스 거부가 반복되면 자율 실행을 자동 일시정지시키는 안전장치. |
| MCP | Model Context Protocol — 외부 도구를 에이전트에 표준 방식으로 연결하는 규약. 클라이언트·서버 양쪽 내장. |
| PinchBench | README가 인용한 에이전트 성능/비용 벤치마크. 25개 과제 평균 점수·토큰·비용 비교. |