NotClaw Docs

AI 에이전트 채팅, 메신저 연동, 자율 학습 가이드

1. Overview

NotClaw는 자율 진화하는 AI 에이전트 플랫폼입니다. 웹 콘솔뿐만 아니라 Telegram, LINE, WhatsApp 등 외부 메신저를 통해서도 동일한 에이전트와 대화할 수 있습니다.

Chat Architecture

3-Layer 구조로 설계되어 있습니다:

Universal Chat API
ChatManager + AgentLoop

→

Native Web UI
/chat/ & /console/

Universal Chat API
ChatManager + AgentLoop

→

Messenger Bridge
Telegram / LINE / WhatsApp

핵심 포인트: 모든 채널의 대화는 같은 ChatManager를 통해 처리되므로, 어디서 대화하든 동일한 AI 에이전트, 동일한 메모리, 동일한 도구를 사용합니다.

2. Web Chat (로그인 필요)

웹 채팅은 Supabase 인증이 필요합니다. 로그인 후 워크스페이스를 선택하여 에이전트와 대화합니다.

Console Chat

항목	내용
URL	`/console/#WORKSPACE_ID/chat`
인증	Supabase 로그인 필수
기능	세션 관리, SSE 스트리밍, 마크다운 렌더링, 이미지 첨부
대상	워크스페이스 오너 (관리자)

Standalone Chat Page

항목	내용
URL	`/chat/`
인증	Supabase 로그인 필수
특징	메신저 스타일 다크모드 UI, 모바일 최적화, 자동 워크스페이스 선택
대상	빠르게 채팅만 하고 싶은 사용자

SSE Streaming: 두 웹 채팅 모두 실시간 스트리밍을 지원합니다. 에이전트가 생각 중(Thinking...)이거나 도구를 사용 중(Using: search_memory)일 때 즉시 상태가 표시됩니다.

3. Messenger Integration (로그인 불필요)

외부 메신저를 통해 AI 에이전트와 대화할 수 있습니다. 사용자는 별도 로그인이 필요 없으며, 워크스페이스 오너가 콘솔에서 봇을 등록하면 즉시 사용 가능합니다.

사용 흐름: 워크스페이스 오너가 콘솔에서 봇 토큰 등록 → 일반 유저가 메신저에서 봇에게 메시지 전송 → AI 에이전트가 응답 → 대화 기록이 웹 콘솔에도 동기화

설정 방법 (워크스페이스 오너)

Telegram에서 @BotFather에게 /newbot 명령으로 봇 생성
발급받은 Bot Token을 복사
NotClaw 콘솔 → Connectors → Telegram → Connect
Bot Token 입력 후 저장
Webhook이 자동으로 등록됩니다

사용 방법 (일반 유저)

Telegram에서 봇 검색 (봇 이름으로)
/start 명령 전송
자유롭게 메시지를 보내면 AI 에이전트가 응답

# API: 봇 등록
POST /api/workspaces/:id/connectors/telegram/register

# API: 봇 해제
POST /api/workspaces/:id/connectors/telegram/unregister

# Webhook (자동 등록됨)
POST /api/connectors/telegram/:workspaceId/webhook

LINE

설정 방법

LINE Developers에서 Messaging API 채널 생성
Channel Secret과 Channel Access Token 복사
NotClaw 콘솔 → Connectors → LINE → Connect
두 값을 입력 후 저장
Webhook URL을 LINE Developers 콘솔에 등록: https://notclaw.live/api/connectors/line/:workspaceId/webhook

설정 방법

Meta for Developers에서 WhatsApp Business App 생성
Phone Number ID, Access Token 복사
NotClaw 콘솔 → Connectors → WhatsApp → Connect
Webhook URL 등록: https://notclaw.live/api/connectors/whatsapp/:workspaceId/webhook

Instagram

설정 방법

Instagram Professional 계정 + Facebook 페이지 연결 필요
Meta for Developers에서 Instagram Messaging API 설정
Page Access Token 발급
NotClaw 콘솔에서 토큰 등록

WeChat Work

설정 방법

WeChat Work(企业微信) 관리 콘솔에서 자체 앱 생성
Corp ID, Agent ID, Agent Secret 복사
NotClaw 콘솔에서 등록
Callback URL 등록: https://notclaw.live/api/connectors/wechat/:workspaceId/webhook

Messenger	인증 방식	대화 형태	로그인 필요
Telegram	Bot Token	1:1 / 그룹	불필요
LINE	Channel Secret + Token	1:1	불필요
WhatsApp	Cloud API Token	1:1	불필요
Instagram	Page Access Token	DM	불필요
WeChat Work	Corp ID + Secret	1:1	불필요

4. Unified History

모든 채널의 대화는 하나의 워크스페이스 세션에 통합 저장됩니다. 웹 콘솔에서 텔레그램, LINE 등 외부 메신저에서 이루어진 대화를 모두 확인할 수 있습니다.

# 전체 히스토리 조회
GET /api/workspaces/:id/chat/unified

# 특정 채널만 필터
GET /api/workspaces/:id/chat/unified?channel=telegram

# 메시지 수 제한
GET /api/workspaces/:id/chat/unified?limit=20

Channel Badges

웹 콘솔의 채팅 화면에서 각 메시지의 출처가 뱃지로 표시됩니다:

web telegram line whatsapp instagram wechat

세션 제목에도 채널 접두사가 자동으로 추가됩니다: [telegram] 안녕하세요...

5. Auto Learning

NotClaw는 대화를 통해 사용자를 학습하고 점점 더 나은 응답을 제공합니다. 모든 학습은 백그라운드에서 비동기로 실행되어 채팅 속도에 영향을 주지 않습니다.

User Preferences

대화 패턴에서 자동으로 추출되는 정보:

항목	예시	업데이트 주기
Communication Style	formal, casual, technical, brief	5회 대화마다
Language	ko, en, ja, zh	5회 대화마다
Expertise Level	beginner, intermediate, expert	5회 대화마다
Custom Preferences	code_style: typescript, timezone: Asia/Seoul	5회 대화마다
Frequent Topics	deployment, API design, market analysis	5회 대화마다

적용 방식: 학습된 프로필은 에이전트의 시스템 프롬프트에 자동 주입됩니다. 별도 설정 없이 대화를 할수록 에이전트가 사용자에게 최적화됩니다.

Skill Suggestions

10회 대화마다 반복 패턴을 분석하여 자동화 가능한 스킬을 제안합니다.

Trigger Pattern: 어떤 상황에서 활성화할지
Suggested Action: AI가 자동으로 수행할 작업
Confidence: 제안 신뢰도 (0.6 이상만 표시)

Learning APIs

# 유저 프로필 조회
GET /api/workspaces/:id/learning/profile

# 스킬 제안 조회
GET /api/workspaces/:id/learning/skills

# 자율 작업 로그 조회
GET /api/workspaces/:id/learning/tasks

6. API Reference

Endpoint	Method	Description	Auth
`/api/workspaces/:id/chat`	POST	메시지 전송 (REST)	Supabase JWT
`/api/workspaces/:id/chat/stream`	POST	메시지 전송 (SSE Streaming)	Supabase JWT
`/api/workspaces/:id/chat/unified`	GET	통합 히스토리 조회	Supabase JWT
`/api/connectors/telegram/:wsId/webhook`	POST	Telegram Webhook 수신	Secret Token
`/api/connectors/line/:wsId/webhook`	POST	LINE Webhook 수신	Signature
`/api/connectors/whatsapp/:wsId/webhook`	POST	WhatsApp Webhook 수신	Verify Token
`/api/workspaces/:id/learning/profile`	GET	유저 프로필	Supabase JWT
`/api/workspaces/:id/learning/skills`	GET	스킬 제안	Supabase JWT
`/api/workspaces/:id/learning/tasks`	GET	자율 작업 로그	Supabase JWT

더 자세한 운영 가이드는 User Manual을 참고하세요. 워크스페이스 설정, 런타임 관리, 메모리/스킬/커넥터 운영 가이드가 포함되어 있습니다.