개요
OpenClaw은 Pi 코딩 에이전트 SDK를 직접 임베딩하며, 그 핵심 장점 중 하나가 정교하게 설계된 7단계 도구 처리 파이프라인(Tool Pipeline)입니다. 이 파이프라인은 AI가 도구를 호출할 때마다 도구 정의가 어떻게 조립, 필터링, 변환되어 최종적으로 대규모 언어 모델에 전달되어 실행되는지를 결정합니다. 이 파이프라인을 이해하는 것이 OpenClaw 도구 시스템을 마스터하는 열쇠입니다.
7단계 개요
전체 도구 처리 흐름은 다음 7개 단계를 순서대로 거칩니다:
- 기본 도구 주입(Base Tools)
- 도구 교체(Tool Overrides)
- OpenClaw 내장 도구(OpenClaw Tools)
- 채널 전용 도구(Channel Tools)
- 정책 필터링(Policy Filter)
- Schema 검증 및 정규화(Schema Normalization)
- AbortSignal 바인딩(AbortSignal Binding)
각 단계는 독립적인 처리 단위로, 이전 단계의 도구 목록을 받아 처리된 결과를 다음 단계에 전달합니다.
1단계: 기본 도구 주입
파이프라인의 시작점은 기본 도구 세트입니다. Pi SDK는 초기화 시 파일 읽기/쓰기, 코드 실행 등 기본 능력을 포함하는 기본 도구 세트를 등록합니다. 이러한 도구는 에이전트의 최소 능력 기준선을 구성합니다.
OpenClaw에서 기본 도구는 설정 파일의 tools 필드를 통해 선언됩니다. 시스템 시작 시 디스크 경로와 프로그래밍 방식 등록 두 가지 소스에서 도구 정의를 로드하고, 초기 도구 목록으로 병합합니다.
2단계: 도구 교체
도구 교체 단계에서는 사용자가 커스텀 구현으로 기본 도구를 대체할 수 있습니다. 예를 들어, 내장 파일 읽기 도구를 자체 파일 작업 도구로 바꾸거나, 원본 웹 검색 기능을 향상된 버전으로 덮어쓸 수 있습니다.
교체 규칙은 도구 이름 매칭에 기반합니다. 동일한 이름의 도구가 감지되면, 나중에 등록된 정의가 이전 정의를 덮어씁니다. 이 메커니즘을 통해 개발자는 코어 코드를 수정하지 않고도 도구 동작을 커스터마이징할 수 있습니다.
3단계: OpenClaw 내장 도구
이 단계에서는 OpenClaw 플랫폼 고유의 도구 세트가 주입됩니다:
- browser: 브라우저 자동화 작업, 웹 내비게이션, 요소 인터랙션, 스크린샷 등 지원
- canvas: 캔버스 도구, 그래픽 및 시각적 콘텐츠 생성에 사용
- cron: 타이머 작업 관리, cron 표현식 스케줄링 지원
- gateway: 게이트웨이 통신 도구, 크로스 서비스 호출 처리
- messaging: 메시지 전송 도구, 다중 채널 메시지 푸시 지원
- nodes: 노드 관리 도구, 워크플로 노드 조작
- sessions: 세션 관리 도구, 영구 세션 처리(JSONL 형식 저장 및 압축)
- web: 웹 작업 도구, HTTP 요청 및 데이터 크롤링 실행
이러한 도구는 프로그래밍 방식으로 로드되어 Pi SDK의 도구 레지스트리에 직접 통합됩니다.
4단계: 채널 전용 도구
각 통신 채널(Discord, Telegram, Slack, WhatsApp)은 고유한 기능과 제약이 있습니다. 채널 전용 도구 단계에서는 현재 세션이 속한 채널에 따라 동적으로 특정 도구를 주입하거나 제거합니다.
예를 들어, Discord 채널에서는 이모지 반응 도구와 임베드 메시지 도구가 추가되고, Telegram 채널에서는 인라인 키보드 도구가 추가될 수 있습니다. 이러한 설계를 통해 AI 에이전트가 각 플랫폼에서 해당 플랫폼의 네이티브 특성을 최대한 활용할 수 있습니다.
5단계: 정책 필터링
정책 필터링 단계에서는 보안 정책과 권한 설정에 따라 도구 목록을 정리합니다. 관리자는 다른 사용자 역할과 채널에 대해 도구 화이트리스트 또는 블랙리스트를 설정할 수 있습니다.
이 단계에서는 도구의 속도 제한 설정, 사용 횟수 상한 및 시간 창 제약도 처리합니다. 정책 검사를 통과하지 못한 도구는 목록에서 제거되어, 최종적으로 모델에 전달되는 도구 세트가 안전하고 규정을 준수하도록 보장합니다.
6단계: Schema 검증 및 정규화
처음 5개 단계를 거친 후 도구 목록이 확정됩니다. Schema 단계에서는 각 도구의 매개변수 정의에 대해 검증 및 정규화 처리를 수행합니다:
- 모든 필수 필드가 존재하는지 확인 (name, description, parameters)
- 매개변수의 JSON Schema 형식이 올바른지 검증
- 누락된 선택적 필드에 기본값 채우기
- 도구 설명이 대규모 언어 모델의 모범 사례를 준수하는지 확인 (길이, 명확성)
특정 도구의 Schema 검증이 실패하면, 시스템은 경고 로그를 기록하고 최종 목록에서 해당 도구를 제거하며, 전체 파이프라인이 중단되지는 않습니다.
7단계: AbortSignal 바인딩
파이프라인의 마지막 단계는 각 도구에 AbortSignal을 바인딩하는 것입니다. 이 메커니즘은 사용자가 요청을 취소하거나, 세션이 타임아웃되거나, 시스템이 실행을 중단해야 할 때, 실행 중인 모든 도구 호출이 정상적으로 종료될 수 있도록 보장합니다.
각 도구의 실행 함수는 AbortSignal 매개변수를 받습니다. 도구 구현자는 오래 실행되는 작업에서 주기적으로 이 신호의 상태를 확인하고, 중지 신호를 받으면 리소스를 정리하고, 부분 결과를 반환하거나, 중지 예외를 발생시켜야 합니다.
디버깅 및 모니터링
OpenClaw은 파이프라인 디버깅 기능을 제공합니다. 설정 파일에서 toolPipelineDebug: true를 활성화하면, 시스템이 각 단계의 입구와 출구에서 도구 목록의 변경 사항을 기록하여, 개발자가 도구가 어느 단계에서 추가, 교체 또는 제거되었는지 추적할 수 있도록 합니다.
정리
7단계 도구 파이프라인은 OpenClaw 도구 시스템의 골격입니다. 기본 주입부터 AbortSignal 바인딩까지, 각 단계가 각자의 역할을 수행하며 도구 시스템의 유연성, 보안성 및 안정성을 함께 보장합니다. 이 파이프라인을 이해하면 커스텀 도구 및 확장 개발 시 더 나은 아키텍처 결정을 내리는 데 도움이 됩니다.