kimandClaude Sonnet 4.6
d74614cee1
- 카카오톡 채널 챗봇 (오픈빌더 비동기 콜백 방식, 5초 제한 우회) - 카카오 "나에게 보내기" OAuth 알림 (kakao-notify.ts) - 채널 설정 UI + userMap으로 다중 사용자 계정 매핑 - 탐정앱: 탭(메모/체크리스트/타임라인), 우선순위, 검색, 보고서/고소장/접수안내 생성 - 모바일 브레이크포인트 640px → 1024px (갤럭시 폴드 대응) - 프롬프트 파일 제한 상향 (USER.md 3000, SOUL.md/AGENTS.md 4000) - 교통앱 마지막 선택 지역 localStorage 저장/복원 - docs/kakao-setup.md 작성 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# 카카오톡 연동 가이드
|
|
|
|
SmallClaw를 카카오톡 채널 챗봇 + "나에게 보내기" 알림으로 연동하는 방법입니다.
|
|
|
|
## 구조
|
|
|
|
```
|
|
사용자 → 카카오톡 채널 → 카카오 i 오픈빌더 → SmallClaw 서버
|
|
↓
|
|
AI 처리 (비동기)
|
|
↓
|
|
카카오 callbackUrl로 응답
|
|
```
|
|
|
|
- **REST API 키** — 앱 하나에 하나, 서버에 한 번만 설정
|
|
- **채널 주소** — 하나, 모든 사용자가 동일한 주소 사용
|
|
- **userId** — 카카오가 사용자마다 다른 값을 웹훅에 포함하여 전송
|
|
|
|
---
|
|
|
|
## 1단계: 카카오 개발자 앱 설정
|
|
|
|
1. [developers.kakao.com](https://developers.kakao.com) → **내 애플리케이션 → 앱 추가**
|
|
2. **앱 키 → REST API 키** 복사
|
|
3. **카카오 로그인 → 활성화** ON
|
|
4. **카카오 로그인 → 동의항목** → `talk_message` 필수 동의 활성화
|
|
5. **카카오 로그인 → Redirect URI** 추가:
|
|
```
|
|
https://{서버주소}/api/kakao/auth/callback
|
|
```
|
|
6. **플랫폼 → Web** → 사이트 도메인 등록
|
|
|
|
---
|
|
|
|
## 2단계: SmallClaw 채널 설정
|
|
|
|
1. SmallClaw 웹 UI → **설정 → 채널 → 카카오톡** 선택
|
|
2. **REST API 키** 입력
|
|
3. **🟡 카카오 로그인** 버튼 클릭 → 브라우저 팝업에서 로그인 및 동의
|
|
4. **챗봇 채널 활성화** 체크
|
|
5. **저장**
|
|
|
|
---
|
|
|
|
## 3단계: 카카오 i 오픈빌더 설정
|
|
|
|
1. [i.kakao.com](https://i.kakao.com) → 챗봇 생성
|
|
2. **스킬** → **생성** → URL 입력:
|
|
```
|
|
https://{서버주소}/api/kakao/webhook
|
|
```
|
|
3. 스킬 편집 → **대기 메시지** 입력 (예: `잠시 기다려 주세요...`)
|
|
4. **시나리오 → 폴백 블록 → 봇 응답 → 스킬데이터 사용** → 위 스킬 선택
|
|
5. **배포**
|
|
|
|
---
|
|
|
|
## 4단계: 카카오톡 채널 생성
|
|
|
|
1. [center-pf.kakao.com](https://center-pf.kakao.com) → 채널 생성
|
|
2. **채널 관리 → 1:1 채팅 활성화**
|
|
3. 오픈빌더 → **배포 → 운영채널** 에서 이 채널 연결
|
|
|
|
---
|
|
|
|
## 사용자 계정 매핑
|
|
|
|
채널 주소는 하나지만 SmallClaw 계정별로 연결 가능합니다.
|
|
|
|
1. 사용자가 채널(`pf.kakao.com/_{채널ID}/chat`)에서 메시지 전송
|
|
2. 서버 로그에서 userId 확인:
|
|
```
|
|
[KakaoChannel] 웹훅 수신 userId=f4e1b2324f39...
|
|
```
|
|
3. SmallClaw 설정 → 채널 → 카카오톡 → **사용자 매핑 (userMap)** 에 입력:
|
|
```json
|
|
{
|
|
"f4e1b2324f39...": "papa",
|
|
"다른userId": "cherry"
|
|
}
|
|
```
|
|
4. 저장
|
|
|
|
매핑되지 않은 userId는 기본 admin 계정으로 연결됩니다.
|
|
|
|
---
|
|
|
|
## "나에게 보내기" 알림
|
|
|
|
OAuth 로그인 완료 후 서버 이벤트(AI 응답, 시스템 알림 등)를 본인 카카오톡으로 수신할 수 있습니다.
|
|
|
|
채널 설정 → **테스트 전송** 버튼으로 동작 확인 가능합니다.
|
|
|
|
---
|
|
|
|
## 동작 원리 (콜백 방식)
|
|
|
|
오픈빌더의 5초 제한을 우회하기 위해 비동기 콜백 방식을 사용합니다:
|
|
|
|
1. 카카오가 웹훅 요청 전송 (`callbackUrl` 포함)
|
|
2. SmallClaw가 즉시 `{ useCallback: true }` 응답
|
|
3. 백그라운드에서 AI 처리
|
|
4. 처리 완료 후 `callbackUrl`로 응답 전송 (최대 5분 유효)
|