# 도구(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)**: 저수준 브라우저 제어

### 사용 예시

```javascript
// 에이전트에서 브라우저 도구 사용
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 컴포넌트

```javascript
// 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>
  );
};
```

### 사용 예시

```javascript
// 에이전트에서 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` | 알림 전송 | 알림 권한 |

### 노드 연결

```javascript
// 노드 연결 요청
{
  "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
    }
  }
}
```

### 사용 예시

```javascript
// 에이전트에서 노드 명령 사용
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 작업

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

**예시:**

```javascript
{
  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
      }
    }
  }
}
```

### 웹훅

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

**예시:**

```javascript
{
  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

```javascript
// 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` |

### 사용 예시

```javascript
// 모든 세션 목록 조회
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` |

### 사용 예시

```javascript
// 파일 읽기
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`

---

## 🔒 권한 시스템

### 권한 모델

```javascript
// 도구 권한 체크
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` | 모든 세션 샌드박스 | 모든 세션 |

### 샌드박스 설정

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

---

## 🔗 관련 문서

- [브라우저 제어 상세](https://browser.md)

- [Canvas/A2UI 상세](https://canvas.md)

- [디바이스 노드 상세](https://nodes.md)

- [자동화 상세](https://automation.md)

- [세션 도구 상세](https://sessions-tool.md)

- [권한 시스템 상세](https://../security/auth-permissions.md)

For the site tree, see the [root Markdown](https://slashpage.com/techkwon.md).