핵심 아키텍처 모듈 (CORE_ARCHITECTURE)
핵심 아키텍처
레인 기반 게이트웨이
Clawdbot은 웹 앱이 아니라 기본적으로 TypeScript CLI 애플리케이션입니다. 머신에서 데몬으로 실행되며 외부 연결(Telegram, Slack 등)의 게이트웨이 역할을 합니다.
핵심 아키텍처는 "레인 기반(Lane-based)" 설계 패턴을 사용합니다:
- 채널 어댑터: 다양한 채널의 메시지 입력을 표준화합니다.
- 게이트웨이 서버: 동시 요청을 처리하는 작업 조정 센터입니다.
- 레인 대기열: 기본값은 순차적(Serial)입니다. 각 세션에는 전용 레인이 할당되어 비동기(async/await)의 경쟁 상태(race condition) 문제를 방지합니다. 명시적으로 위험도가 낮은 작업만 병렬로 처리됩니다.
TypeScriptCLISerial Queue
이미지 출처:렌더링 완료
// Gateway Coordinator
class Gateway {
// Map session ID to dedicated Serial Lane
private lanes = new Map<string, SerialLane>();
async handleRequest(req: Request) {
const lane = this.lanes.get(req.sessionId)
|| new SerialLane();
// High-risk/Stateful -> Serial Lane (Queue)
if (req.isStateful) {
await lane.add(new Task(req));
}
// Low-risk/Read-only -> Parallel execution
else {
await runParallel(new Task(req));
}
}
}
// Serial Lane: Prevents race conditions
class SerialLane {
private queue: Task[] = [];
private isRunning = false;
async add(task: Task) {
this.queue.push(task);
if (!this.isRunning) this.process();
}
private async process() {
this.isRunning = true;
while (this.queue.length > 0) {
// Execute one by one
await this.queue.shift()?.execute();
}
this.isRunning = false;
}
}메모리 시스템 모듈 (MEMORY_SYSTEM)
메모리 시스템
하이브리드 검색 아키텍처
메모리가 없으면 AI는 금붕어와 같습니다. Clawdbot은 이중 계층 시스템을 통해 영속성을 해결합니다:
- 세션 기록 (JSONL): 문맥 구축을 위해 전체 세션 기록을 저장합니다.
- 메모리 파일 (Markdown):
memory/*.md에 저장되는 장기 메모리입니다.
하이브리드 검색
벡터 검색 (SQLite)과 키워드 검색 (FTS5)을 결합합니다. "authentication bug"를 검색하면 의미상 관련된 "auth issues"를 찾고 정확한 구문도 일치시킵니다. 에이전트는 블랙박스 API가 아닌 표준 파일 쓰기 도구를 통해 직접 메모리를 관리합니다.
JSONLMarkdownSQLiteFTS5
이미지 출처:렌더링 완료
// Memory Structure
memory/
├── user_profile.md
├── project_claudia.md
└── tech_stack_notes.md
// Search Query
SELECT * FROM memory
WHERE vec_search(embedding, query)
OR text_match(content, query);컴퓨터 사용 모듈 (COMPUTER_USE)
컴퓨터 사용
샌드박스 실행
Clawdbot은 에이전트에게 실제 컴퓨터 조작 권한을 부여하지만, 엄격한 보안 제한이 있습니다:
- 실행 환경: 기본적으로 Docker 샌드박스를 사용하며, 호스트 직접 조작으로도 구성할 수 있습니다.
- 허용 목록(Allowlist): 사용자가 명시적으로 승인한 명령 (예: npm, git).
- 차단 목록(Blocklist): 기본적으로 위험한 작업(
rm -rf /, 명령 치환, 시스템 파일로의 리디렉션 등)을 차단합니다.
DockerSandboxAllowlist
// ~/.clawdbot/exec-approvals.json
{
"allowlist": [
{ "pattern": "/usr/bin/npm", "lastUsed": 1706644800 },
{ "pattern": "/opt/homebrew/bin/git", "lastUsed": 1706644900 }
],
"blocked": [
"rm -rf /",
"cat file > /etc/hosts"
]
}시맨틱 비전 모듈 (SEMANTIC_VISION)
시맨틱 비전
픽셀 위의 접근성 트리
브라우저 도구는 스크린샷에 의존하지 않고 시맨틱 스냅샷(Semantic Snapshots)을 사용합니다.
이는 페이지의 접근성 트리(ARIA)를 텍스트로 표현한 것입니다.
이미지 스냅샷
크기 약 5MB
높은 토큰 비용
시맨틱 스냅샷
크기 50KB 미만
구조만 포함
웹 브라우징은 기본적으로 시각적 작업이 아니라 의미(semantic)를 이해하는 작업입니다. 에이전트는 버튼, 입력 칸, 제목으로 이루어진 구조화된 목록을 봅니다.
PlaywrightARIALow-Token
이미지 출처:렌더링 완료
- button "Sign In" [ref=1]
- textbox "Email" [ref=2]
- textbox "Password" [ref=3]
- link "Forgot password?" [ref=4]
- heading "Welcome back"