도구(Tools) 시스템 개요

Clawdbot의 도구 시스템은 에이전트가 사용할 수 있는 기능을 제공합니다.

🛠 도구 카테고리

카테고리	설명	위치
브라우저 제어	웹 브라우저 자동화	/src/browser/
Canvas/A2UI	에이전트 주도 시각 작업공간	/src/canvas-host/
디바이스 노드	디바이스 하드웨어 제어	/src/node-host/
Cron & 웹훅	자동화 및 외부 트리거	/src/cron/
세션 도구	에이전트 간 통신	/src/sessions/
파일 시스템	파일 읽기/쓰기/편집	/src/process/
크롬 작업	주기적 작업 스케줄링	/src/cron/service.ts

🎨 브라우저 제어

개요

Playwright Core를 사용하여 Chrome/Chromium 브라우저를 자동화합니다.

기능

기능	설명	권한
페이지 탐색	URL로 이동, 뒤로가기, 새고기	browser
요소 상호작용	클릭, 입력, 선택	browser
스크린샷	전체 화면 또는 요소 캡처	browser
스크립트 실행	JavaScript 코드 실행	browser
파일 업로드	로컬 파일 업로드	browser
미디어 다운로드	파일 다운로드 경로 제어	browser
페이지 탭 관리	새 탭, 닫기, 전환	browser
쿠키 및 스토리지	쿠키 관리, localStorage/세션Storage	browser

기술 스택

•

Playwright Core: chromium-bidi

•

Chromium Bidi: Chrome DevTools Protocol 통합

•

CDP (Chrome DevTools Protocol): 저수준 브라우저 제어

사용 예시

// 에이전트에서 브라우저 도구 사용
const result = await tool('browser_navigate', {
  url: 'https://example.com'
});

const screenshot = await tool('browser_screenshot', {
  selector: 'body',
  fullPage: true
});

const click = await tool('browser_click', {
  selector: '#submit-button'
});

위치

•

메인 구현: /src/browser/

•

서버 컨텍스트: /src/browser/server-context.ts

•

클라이언트 액션: /src/browser/client-actions.ts

•

프로필 관리: /src/browser/profiles.ts

🎨 Canvas/A2UI

개요

에이전트가 주도적으로 수정할 수 있는 HTML/React 기반 캔버스를 제공합니다.

기능

기능	설명	권한
Live Canvas	실시간 편집 가능한 HTML 캔버스	canvas
A2UI (Agent-to-User Interface)	푸시된 React 구성요소	canvas
캔버스 업데이트	실시간 캔버스 상태 업데이트	canvas
사용자 입력 캡처	클릭, 키 입력, 스크롤 캡처	canvas
스냅샷	캔버스 상태 저장	canvas
캔버스 호스트	별도의 서버 (포트 18793)	canvas

A2UI 컴포넌트

// A2UI 예시: 푸시된 React 컴포넌트
interface A2UIProps {
  title: string;
  data: unknown;
  onEvent: (event: unknown) => void;
}

// 예: 차트 A2UI
const ChartA2UI: React.FC<A2UIProps> = ({ title, data, onEvent }) => {
  return (
    <div>
      <h2>{title}</h2>
      <Chart data={data} />
      <button onClick={() => onEvent({ type: 'export' })}>
        Export
      </button>
    </div>
  );
};

사용 예시

// 에이전트에서 Canvas 사용
await tool('canvas_update', {
  html: '<h1>Hello, Canvas!</h1>',
  width: 800,
  height: 600
});

await tool('canvas_a2ui', {
  component: 'ChartA2UI',
  props: {
    title: 'Sales Data',
    data: salesData
  },
  onEvent: { type: 'export' }
});

위치

•

캔버스 호스트: /src/canvas-host/

•

A2UI 번들: /src/canvas-host/dist/

•

게이트웨이 통합: /src/gateway/canvas-handler.ts

📱 디바이스 노드

개요

macOS/iOS/Android/Headless 노드가 디바이스 하드웨어 기능을 제공합니다.

노드 명령

명령	설명	권한
canvas.*	캔버스 제어	캔버스 권한
camera.snap	사진 캡처	카메라 권한
camera.clip	비디오 클립	카메라 권한
screen.record	화면 녹화	화면 녹화 권한
location.get	현재 위치 정보	위치 권한
system.run	명령 실행	승인된 elevated 모드
system.notify	알림 전송	알림 권한

노드 연결

// 노드 연결 요청
{
  "type": "req",
  "method": "connect",
  "params": {
    "role": "node",
    "deviceId": "device-uuid",
    "name": "My iPhone",
    "caps": [
      "camera.snap",
      "screen.record",
      "location.get"
    ],
    "permissions": {
      "camera": true,
      "screen": false,
      "location": true
    }
  }
}

사용 예시

// 에이전트에서 노드 명령 사용
const photo = await tool('camera_snap', {
  quality: 'high'
});

const location = await tool('location_get', {
  accuracy: 'high'
});

const screen = await tool('screen_record', {
  duration: 30,
  format: 'mp4'
});

위치

•

노드 호스트: /src/node-host/runner.ts

•

노드 프로토콜: /src/node-host/config.ts

•

게이트웨이 통합: /src/gateway/node-handler.ts

⏰ Cron & 웹훅

개요

주기적 작업 스케줄링과 외부 HTTP POST 트리거를 지원합니다.

Cron 작업

// 크론 작업 정의
interface CronJob {
  id: string;
  schedule: string;  // cron syntax: "0 9 * * 1-5"
  agent: string;      // 워크스페이스 이름
  message: string;    // 에이전트에 보낼 메시지
  enabled: boolean;
}

예시:

{
  cron: {
    jobs: {
      "daily-report": {
        schedule: "0 9 * * 1-5",
        agent: "main",
        message: "오늘의 일정을 정리해줘",
        enabled: true
      },
      "weekly-summary": {
        schedule: "0 18 * * 5",
        agent: "main",
        message: "이번 주 목표를 정리해줘",
        enabled: true
      }
    }
  }
}

웹훅

// 웹훅 정의
interface Webhook {
  path: string;
  secret: string;
  method: 'POST' | 'GET';
  agent: string;
  message?: string;
  enabled: boolean;
}

예시:

{
  webhooks: {
    "/api/triggers/backup": {
      secret: "webhook-secret-key",
      method: "POST",
      agent: "backup-agent",
      message: "백업을 실행해줘",
      enabled: true
    },
    "/api/triggers/deploy": {
      secret: "deploy-secret-key",
      method: "POST",
      agent: "deploy-agent",
      enabled: true
    }
  }
}

Gmail Pub/Sub

// Gmail 기반 트리거
interface GmailPubSub {
  enabled: boolean;
  agent: string;
  filters?: {
    from?: string[];
    subject?: string[];
    body?: string[];
  };
}

위치

•

크론 서비스: /src/cron/service.ts

•

스케줄러: /src/cron/schedule.ts

•

웹훅 핸들러: /src/web/hooks.ts

•

Gmail Pub/Sub: /src/gmail/

💬 세션 도구

개요

에이전트 간 통신 및 다른 세션으로 메시지 전송을 지원합니다.

세션 도구

도구	설명	권한
sessions_list	모든 활성 세션 목록 조회	sessions_list
sessions_history	특정 세션의 기록 조회	sessions_history
sessions_send	다른 세션으로 메시지 전송	sessions_send
sessions_context_update	다른 세션의 컨텍스트 업데이트	sessions_context

사용 예시

// 모든 세션 목록 조회
const sessions = await tool('sessions_list');
// => [
//   { id: 'whatsapp:+1234567890', workspace: 'main', ... },
//   { id: 'telegram:@bot', workspace: 'main', ... }
// ]

// 특정 세션 기록 조회
const history = await tool('sessions_history', {
  session: 'whatsapp:+1234567890'
});

// 다른 세션으로 메시지 전송
await tool('sessions_send', {
  to: 'telegram:@other_bot',
  message: '이 작업을 처리해줘'
});

// 다른 세션 컨텍스트 업데이트
await tool('sessions_context_update', {
  session: 'whatsapp:+1234567890',
  context: {
    data: sharedData,
    lastUpdated: '2026-01-26'
  }
});

위치

•

세션 도구: /src/sessions/sessions-tool.ts

•

세션 모델: /src/config/sessions/types.ts

•

세션 관리: /src/sessions/manager.ts

📁 파일 시스템

기능

도구	설명	권한
read	파일 읽기	read
write	파일 쓰기	write
edit	파일 편집	edit
list	디렉토리 목록	read
delete	파일 삭제	write

사용 예시

// 파일 읽기
const content = await tool('read', {
  path: '~/clawd/config/settings.json'
});

// 파일 쓰기
await tool('write', {
  path: '~/clawd/output/result.txt',
  content: 'Hello, World!'
});

// 파일 편집
await tool('edit', {
  path: '~/clawd/src/app.ts',
  edits: [
    {
      search: 'console.log("Hello")',
      replace: 'console.log("Updated!")'
    }
  ]
});

위치

•

파일 시스템: /src/process/

•

경로 확인: /src/utils/path-utils.ts

🔒 권한 시스템

권한 모델

// 도구 권한 체크
interface ToolPermission {
  tool: string;
  allowed: boolean;
  reason?: string;
}

// 권한 검사 로직
function checkPermission(tool: string, session: Session): boolean {
  if (session.isMain) {
    return true;  // main 세션은 모든 도구 허용
  }

  if (sandbox.mode === 'non-main') {
    return sandbox.allowlist.includes(tool);
  }

  return false;
}

샌드박스 모드

모드	설명	대상 세션
none	샌드박스 비활성화	모든 세션
non-main	비-main 세션만 샌드박스	그룹, 공개 DM
all	모든 세션 샌드박스	모든 세션

샌드박스 설정

{
  sandbox: {
    mode: "non-main",
    allowlist: [
      "bash",
      "process",
      "read",
      "write",
      "edit",
      "sessions_list",
      "sessions_history"
    ],
    denylist: [
      "browser",
      "canvas",
      "nodes",
      "cron",
      "discord",
      "slack",
      "gateway"
    ]
  }
}

🔗 관련 문서

•

•

•

•

•

•