Clawhip: 게이트웨이 세션을 우회하는 이벤트-채널 알림 라우터

Clawhip Router

AI 에이전트가 Discord에 알림을 보낸다. 간단해 보인다. 그런데 문제가 생긴다. 모든 알림이 게이트웨이 세션을 통과하면, LLM의 컨텍스트가 불필요한 메시지로 오염된다. “빌드 완료”, “PR 생성됨”, “커밋 푸시됨” — 이런 시스템 메시지들이 정작 중요한 대화 컨텍스트를 밀어낸다.

Clawhip은 이 문제를 근본적으로 해결한다. 게이트웨이 세션을 완전히 우회해서 알림을 직접 채널로 라우팅한다. LLM 세션은 깨끗하게 유지되고, 알림은 제때 도착한다. Rust로 작성되어 가볍고 빠르다.

왜 Clawhip인가

기존 알림 시스템의 문제

AI 에이전트 운영자들이 겪는 공통적인 문제:

컨텍스트 오염 — 시스템 알림이 LLM 컨텍스트를 잠식
알림 지연 — 게이트웨이를 거치면서 메시지가 늦게 도착
복잡한 설정 — 각 소스마다 다른 알림 방식
모니터링 부재 — tmux 세션, git 활동을 실시간으로 볼 수 없음

Clawhip의 접근법

Clawhip은 **우회(Bypass)**라는 단순한 원칙으로 설계됐다. 게이트웨이 세션을 통하지 않고, 직접 Discord/Slack으로 메시지를 보낸다.

[CLI / webhook / git / GitHub / tmux] 
    -> [sources] 
    -> [mpsc queue] 
    -> [dispatcher] 
    -> [router -> renderer -> Discord/Slack sink]

이 구조의 핵심은 mpsc 큐다. 모든 이벤트가 비동기 큐에 들어가고, dispatcher가 순차적으로 처리한다. LLM 세션은 전혀 관여하지 않는다.

핵심 기능

1. 타입드 이벤트 파이프라인

Clawhip은 이벤트를 타입으로 분류한다. 각 타입마다 다른 라우팅 규칙을 적용할 수 있다.

이벤트 타입	설명
`github.issue-opened`	새 이슈 생성
`github.issue-commented`	이슈에 댓글
`github.issue-closed`	이슈 종료
`github.pr-status-changed`	PR 상태 변경
`git.commit`	커밋 푸시
`session.started`	에이전트 세션 시작
`session.blocked`	에이전트 블로킹
`session.finished`	에이전트 완료
`session.failed`	에이전트 실패
`tmux.keyword`	tmux 키워드 감지
`tmux.stale`	tmux 세션 유휴

이 타입 시스템 덕분에 “이슈 알림은 #dev 채널로, 세션 실패는 #alerts 채널로” 같은 정교한 라우팅이 가능하다.

2. 다중 소스 지원

Clawhip은 다양한 이벤트 소스를 지원한다:

CLI thin clients — 명령줄에서 직접 이벤트 발송
GitHub webhook ingress + polling — 실시간 + 폴링 하이브리드
Git monitor source — 로컬 저장소 활동 모니터링
tmux monitor source — 터미널 세션 감시

3. 다중 싱크 지원

알림을 보낼 대상도 다양하다:

Discord — 봇 토큰 또는 웹훅
Slack — 웹훅

중요한 점은 렌더러와 싱크가 분리되어 있다는 것. 이벤트를 어떻게 표시할지(렌더러)와 어디로 보낼지(싱크)가 독립적이다. 나중에 Telegram, Email 등을 추가하기 쉽다.

4. tmux 모니터링

이 기능이 독특하다. tmux 세션을 감시해서 특정 키워드가 나타나면 알림을 보낸다.

# 새 세션 생성 + 모니터링
clawhip tmux new -s issue-123 \
  --channel YOUR_CHANNEL_ID \
  --mention "<@your-user-id>" \
  --keywords "error,PR created,complete" \
  -- 'source ~/.zshrc && omc --openclaw --madmax'

# 기존 세션에 모니터링 연결
clawhip tmux watch -s issue-123 \
  --channel YOUR_CHANNEL_ID \
  --mention "<@your-user-id>" \
  --keywords "error,PR created,complete"

이렇게 하면 tmux 세션에서 “error”나 “complete”가 출력될 때 Discord로 알림이 간다. 장시간 실행되는 에이전트 작업을 모니터링하기 좋다.

5. OMC/OMX 통합

Clawhip은 Claude Code(OMC)와 Codex(OMX) 래퍼와 통합된다. session.* 이벤트가 자동으로 정규화되어 일관된 형식으로 알림이 간다.

에이전트가 시작될 때, 블로킹될 때, 완료될 때, 실패할 때 — 모든 라이프사이클 이벤트를 추적할 수 있다.

6. 메모리 오프로드

장기 실행 세션의 상태를 외부에 저장하는 기능이다.

# 메모리 스캐폴드 생성
clawhip memory init --project clawhip --channel discord-alerts --agent codex

# 상태 확인
clawhip memory status --project clawhip --channel discord-alerts --agent codex

이를 통해 에이전트가 재시작되어도 이전 컨텍스트를 복구할 수 있다.

7. 크론 스케줄링

정기 알림을 위한 크론 지원:

# dev-followup.sh
clawhip send \
  --channel 1480171113253175356 \
  --message "🔄 **[clawhip] Dev follow-up** — check open PRs/issues"

이 스크립트를 cron에 등록하면 정기적으로 리마인더를 보낼 수 있다.

설정: TOML 기반 라우팅 규칙

Clawhip의 설정은 ~/.clawhip/config.toml에 있다. 선언적인 라우팅 규칙이 핵심이다.

[providers.discord]
token = "your-dedicated-clawhip-bot-token"
default_channel = "your-default-channel-id"

[[routes]]
event = "github.*"
filter = { repo = "clawhip" }
sink = "discord"
channel = "1480171113253175356"
mention = "<@1465264645320474637>"
format = "compact"

[[routes]]
event = "session.*"
filter = { tool = "omx", repo_name = "clawhip" }
sink = "discord"
channel = "1480171113253175356"
format = "compact"

이 설정의 의미:

GitHub 이벤트 중 clawhip 저장소 관련 것은 #dev 채널로, @user 멘션과 함께
세션 이벤트 중 OMX(Codex) 관련 것은 같은 채널로, compact 포맷으로

event = "github.*" 같은 와일드카드가 강력하다. 모든 GitHub 이벤트를 한 번에 매칭할 수 있다.

설치: 다양한 옵션

Cargo (Rust 패키지 매니저)

cargo install clawhip

설치 스크립트

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/Yeachan-Heo/clawhip/releases/latest/download/clawhip-installer.sh | sh

저장소에서 직접

./install.sh
./install.sh --systemd  # systemd 서비스로 등록

Clawhip CLI로 설치

clawhip install
clawhip install --systemd
clawhip update --restart
clawhip uninstall

CLI 명령어 레퍼런스

명령어	설명
`clawhip`	데몬 시작
`clawhip status`	데몬 상태 확인
`clawhip config`	설정 관리
`clawhip send`	커스텀 이벤트 발송
`clawhip github`	GitHub 이벤트
`clawhip git`	git 이벤트
`clawhip agent`	에이전트 라이프사이클 이벤트
`clawhip tmux`	tmux 래퍼/모니터링
`clawhip plugin list`	플러그인 목록
`clawhip memory`	메모리 오프로드

systemd 서비스

프로덕션 환경에서는 systemd로 관리하는 것이 좋다.

# 서비스 파일: deploy/clawhip.service
# 경로: /etc/systemd/system/clawhip.service

systemctl daemon-reload
systemctl enable --now clawhip

서비스로 등록하면 부팅 시 자동 시작, 로그 관리, 재시작 정책 등을 활용할 수 있다.

아키텍처: 왜 Rust인가

Clawhip이 Rust로 작성된 이유는 명확하다:

성능 — 알림 라우터는 지연이 최소화되어야 한다. Rust의 zero-cost abstractions이 빛난다.
신뢰성 — 컴파일 타임 메모리 안전성. 런타임 크래시 걱정이 없다.
단일 바이너리 — 의존성 없이 배포 가능. 설치가 간단하다.
비동기 — Tokio 기반 비동기 런타임. 수천 개의 동시 연결 처리 가능.

아키텍처 다이어그램:

[Sources]
  ├── CLI (clawhip send)
  ├── GitHub (webhook + polling)
  ├── Git (monitor)
  └── tmux (monitor)
       ↓
   [mpsc queue]
       ↓
  [Dispatcher]
       ↓
   [Router] → [Renderer] → [Sink]
                                ↓
                    [Discord REST / Slack webhook]

mpsc(multi-producer, single-consumer) 큐가 핵심이다. 여러 소스가 동시에 이벤트를 push해도, dispatcher가 순차적으로 안전하게 처리한다.

개발자: Yeachan-Heo

Clawhip은 Yeachan-Heo가 개발했다. 2026년 3월 8일에 생성된 매우 최신 프로젝트다. 빠른 시간 안에 46+ 스타를 받은 것을 보면 커뮤니티의 니즈를 정확히 hit했다는 의미다.

마치며: LLM 세션을 깨끗하게 유지하라

Clawhip은 단순한 알림 도구가 아니다. 아키텍처 레벨의 결정이다.

모든 알림을 게이트웨이 세션을 통과시키면 안 된다. 시스템 메시지, 모니터링 알림, 정기 리포트 — 이런 것들은 LLM 컨텍스트를 오염시킬 뿐이다. Clawhip처럼 우회 경로를 만들어야 한다.

Rust로 작성되어 가볍고, tmux 모니터링, GitHub 통합, 메모리 오프로드까지 갖춘 종합 솔루션이다. AI 에이전트를 운영 중이라면, 알림 아키텍처를 다시 생각해볼 때다.

🔗 관련 정보

GitHub: https://github.com/Yeachan-Heo/clawhip
개발자: Yeachan-Heo
언어: Rust
문서: ARCHITECTURE.md, docs/native-event-contract.md, docs/memory-offload-architecture.md
이미지: /images/clawhip-og.png, /images/clawhip-router.jpg