{"_id":"@bartlee_xx/kakao-talkchannel","name":"@bartlee_xx/kakao-talkchannel","dist-tags":{"latest":"0.5.1"},"versions":{"0.5.1":{"name":"@bartlee_xx/kakao-talkchannel","version":"0.5.1","description":"Kakao TalkChannel integration for OpenClaw","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"openclaw":{"extensions":["./index.ts"],"channel":{"id":"kakao-talkchannel","label":"Kakao TalkChannel","selectionLabel":"카카오톡 채널","docsPath":"/channels/kakao-talkchannel","docsLabel":"kakao-talkchannel","blurb":"KakaoTalk 채널 챗봇을 OpenClaw에 연결합니다","order":80,"quickstartAllowFrom":false},"compatibility":{"testedWith":"2026.3.2"},"install":{"npmSpec":"@bartlee_xx/kakao-talkchannel","localPath":"extensions/kakao-talkchannel","defaultChoice":"npm"}},"dependencies":{"zod":"^3.22.0","zod-to-json-schema":"^3.25.1"},"peerDependencies":{"openclaw":">=2026.1.29"},"devDependencies":{"@eslint/js":"^9.21.0","@types/node":"^20.10.0","@vitest/coverage-v8":"^1.0.0","eslint":"^9.21.0","openclaw":"2026.3.2","typescript":"^5.3.0","typescript-eslint":"^8.24.1","vitest":"^1.0.0"},"engines":{"node":">=22.12.0"},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","test:run":"vitest run","test:coverage":"vitest run --coverage","lint":"eslint src tests index.ts","typecheck":"tsc --noEmit"},"_id":"@bartlee_xx/kakao-talkchannel@0.5.1","_integrity":"sha512-AcBq0mdzf8bHlZsSpiB6Jbq9SugGuinwjswJy2n0tV6nFfJf8bCXwPOKVto10t888mXn8IKS86kx5jhwhJ9BFw==","_resolved":"/private/var/folders/lp/cm7nk3_111s_0x4d6drzgc680000gn/T/c953368c676b1d8a603b0d6aadc74935/bartlee_xx-kakao-talkchannel-0.5.1.tgz","_from":"file:bartlee_xx-kakao-talkchannel-0.5.1.tgz","_nodeVersion":"25.7.0","_npmVersion":"11.10.1","dist":{"integrity":"sha512-AcBq0mdzf8bHlZsSpiB6Jbq9SugGuinwjswJy2n0tV6nFfJf8bCXwPOKVto10t888mXn8IKS86kx5jhwhJ9BFw==","shasum":"46271aecd69c856f05a9b882235e60f6322a319b","tarball":"https://registry.npmjs.org/@bartlee_xx/kakao-talkchannel/-/kakao-talkchannel-0.5.1.tgz","fileCount":119,"unpackedSize":400139,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAOkg3s/OLaKZGdtPBuT6jqkqZ9huETMdCkP3elNFnMbAiBy/Ib9IdynqGqvWDuRqzXGB16rd5BTR82lNRIyUQwAfA=="}]},"_npmUser":{"name":"bart_lee_xx","email":"bart.lee@kakao.com"},"directories":{},"maintainers":[{"name":"bart_lee_xx","email":"bart.lee@kakao.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kakao-talkchannel_0.5.1_1772565256675_0.39124525492580897"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-03T19:14:16.580Z","0.5.1":"2026-03-03T19:14:16.839Z","modified":"2026-03-03T19:14:17.055Z"},"maintainers":[{"name":"bart_lee_xx","email":"bart.lee@kakao.com"}],"description":"Kakao TalkChannel integration for OpenClaw","readme":"# OpenClaw Kakao TalkChannel Plugin\n\n카카오톡 채널을 OpenClaw에 연결하는 플러그인입니다.\n\n[English](./README.en.md)\n\n---\n\n## 설치\n\n### npm\n\n```bash\nnpm install @bartlee_xx/kakao-talkchannel\n```\n\n```bash\npnpm add @bartlee_xx/kakao-talkchannel\n```\n\n### OpenClaw CLI\n\nOpenClaw에게 말하세요:\n\n> \"카카오톡 플러그인 설치해줘\"\n\n그게 끝입니다. OpenClaw가 알아서 설치합니다.\n\n---\n\n## 사용자 가이드\n\n### 카카오톡 연결\n\n1. OpenClaw에게 **\"카카오톡 연결해줘\"**\n2. OpenClaw가 페어링 코드 제공 (예: `ABCD-1234`)\n3. [카카오톡 채널](http://pf.kakao.com/_scexbC) 접속\n4. 채팅창에 `/pair ABCD-1234` 입력\n5. 연결 완료!\n\n> **중요**: 반드시 OpenClaw가 먼저 코드를 생성합니다.\n\n### 문제 해결\n\n| 문제 | OpenClaw에게 요청 |\n|------|------------------|\n| 플러그인이 안 됨 | \"플러그인 진단해줘\" |\n| 채널이 안 보임 | \"게이트웨이 재시작해줘\" |\n| 페어링이 안 됨 | \"카카오톡 연결해줘\" (처음부터 다시) |\n| 대화가 멈춤 / tool 에러 | `/reset` 또는 `/compact` 실행 |\n\n#### OpenClaw 세션 관리\n\n대화가 길어지면 OpenClaw 코어의 컴팩션 과정에서 tool 관련 에러가 발생할 수 있습니다:\n\n```\nmessages.60.content.1: unexpected tooluseid found in toolresult blocks\n```\n\n이는 OpenClaw 코어의 알려진 버그로, 고아 toolResult를 transcript hygiene이 감지하지 못한 케이스입니다.\n\n**예방 및 해결 방법:**\n\n| 방법 | 언제 사용 | 효과 |\n|------|-----------|------|\n| `/compact` | 대화가 복잡해지기 전 | 히스토리 압축으로 문제 예방 |\n| `/reset` | 에러로 대화가 막혔을 때 | 세션 초기화로 즉시 해결 |\n\n> **권장**: 장시간 대화 시 주기적으로 `/compact`를 실행하세요.\n\n---\n\n## OpenClaw 에이전트 가이드\n\n> 이 섹션은 OpenClaw가 참조하는 자동화 지침입니다.\n\n### 플러그인 설치 요청 시\n\n사용자가 \"카카오톡 플러그인 설치\", \"카톡 연동\" 등을 요청하면:\n\n```bash\n# 1. 설치\nopenclaw plugins install @bartlee_xx/kakao-talkchannel\n\n# 2. 확인 (kakao-talkchannel이 loaded 상태인지)\nopenclaw plugins list\n\n# 3. 게이트웨이 재시작\nopenclaw gateway restart\n\n# 4. 채널 확인\nopenclaw channels list\n```\n\n### 카카오톡 연결 요청 시\n\n사용자가 \"카카오톡 연결\", \"카톡 연동\" 등을 요청하면:\n\n1. 페어링 코드 생성\n2. 사용자에게 안내:\n   > \"카카오톡 채널(http://pf.kakao.com/_scexbC)에서 `/pair {코드}`를 입력하세요\"\n3. 페어링 완료 대기\n\n### 로컬 플러그인 설치 요청 시\n\n사용자가 경로를 지정하며 로컬 설치를 요청하면:\n\n```bash\n# 링크 모드 (개발용, 소스 수정 즉시 반영)\nopenclaw plugins install -l {경로}\n\n# 복사 모드\nopenclaw plugins install {경로}\n```\n\n---\n\n## 카드 메시지\n\n에이전트가 JSON 형식으로 응답하면 카카오톡 카드로 자동 변환됩니다.\n\n### 지원 카드 타입\n\n| 타입 | 설명 |\n|------|------|\n| `textCard` | 텍스트 + 버튼 |\n| `basicCard` | 이미지 + 텍스트 + 버튼 |\n| `listCard` | 리스트 형태 |\n| `commerceCard` | 상품 카드 |\n| `simpleImage` | 이미지만 |\n| `carousel` | 여러 카드 슬라이드 |\n\n### 예시: textCard\n\n```json\n{\"textCard\":{\"title\":\"제목\",\"description\":\"설명\",\"buttons\":[{\"label\":\"버튼\",\"action\":\"message\",\"messageText\":\"클릭!\"}]}}\n```\n\n### 예시: basicCard\n\n```json\n{\"basicCard\":{\"title\":\"제목\",\"description\":\"설명\",\"thumbnail\":{\"imageUrl\":\"https://example.com/image.jpg\"},\"buttons\":[{\"label\":\"자세히\",\"action\":\"webLink\",\"webLinkUrl\":\"https://example.com\"}]}}\n```\n\n### 버튼 액션\n\n| action | 설명 | 필수 필드 |\n|--------|------|-----------|\n| `message` | 메시지 전송 | `messageText` |\n| `webLink` | 웹 링크 | `webLinkUrl` |\n| `phone` | 전화 걸기 | `phoneNumber` |\n| `share` | 공유하기 | - |\n\n### quickReplies (빠른 응답)\n\n```json\n{\"textCard\":{\"title\":\"선택하세요\"},\"quickReplies\":[{\"label\":\"A\",\"action\":\"message\",\"messageText\":\"A\"},{\"label\":\"B\",\"action\":\"message\",\"messageText\":\"B\"}]}\n```\n\n> **참고**: 일반 텍스트는 그대로 전송됩니다. JSON 형식일 때만 카드로 변환됩니다.\n> \n> **주의**: 카드를 보낼 때는 JSON만 단독으로 보내야 합니다. 텍스트와 섞으면 변환되지 않습니다.\n\n자세한 내용은 [CLAUDE.md](./CLAUDE.md)를 참조하세요.\n\n---\n\n## 릴레이 서버\n\n이 플러그인은 **릴레이 서버**를 통해 카카오톡 채널과 통신합니다. 두 가지 방식으로 사용할 수 있습니다.\n\n### 방식 1: 기본 채널 사용 (권장)\n\n설치 후 별도 설정 없이 바로 사용할 수 있습니다. 기본 릴레이 서버(`k.tess.dev`)와 공유 카카오톡 채널([Samantha](http://pf.kakao.com/_scexbC))이 제공됩니다.\n\n- 설정 불필요, 설치 즉시 동작\n- 페어링 코드로 OpenClaw 인스턴스에 연결\n- 여러 사용자가 하나의 채널을 공유\n\n### 방식 2: 별도 릴레이 서버 배포\n\n자체 카카오톡 채널과 릴레이 서버를 운영하고 싶다면 직접 배포할 수 있습니다.\n\n1. [kakao-talkchannel-relay-openclaw](https://github.com/kakao-bart-lee/kakao-talkchannel-relay-openclaw) 저장소에서 릴레이 서버 배포\n2. [카카오 i 오픈빌더](https://i.kakao.com/)에서 챗봇 생성 및 스킬 연결 (릴레이 서버의 [설정 가이드](https://github.com/kakao-bart-lee/kakao-talkchannel-relay-openclaw/blob/main/docs/setup-guide.md) 참고)\n3. 릴레이 서버 Admin UI에서 Account 생성 후 `relayToken` 발급\n4. 플러그인 설정에서 `relayUrl`과 `relayToken` 지정\n\n```json\n{\n  \"channels\": {\n    \"kakao-talkchannel\": {\n      \"accounts\": {\n        \"default\": {\n          \"relayUrl\": \"https://your-relay-server.example.com\",\n          \"relayToken\": \"발급받은_토큰\"\n        }\n      }\n    }\n  }\n}\n```\n\n자체 릴레이 서버를 사용하면:\n- 독립적인 카카오톡 채널 운영 가능\n- 채널 브랜딩 및 프로필 커스터마이징\n- 메시지 로그 및 Admin UI 직접 관리\n\n---\n\n## 설정 레퍼런스\n\n대부분의 경우 설정이 필요 없습니다. 설치 후 바로 사용 가능합니다.\n\n### 설정 파일 위치\n\n`~/.openclaw/openclaw.json` 또는 `config.yaml`\n\n### 사용자 설정\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `enabled` | 채널 활성화 | `true` |\n| `dmPolicy` | DM 정책 | `\"pairing\"` |\n| `allowFrom` | 허용 사용자 목록 (`allowlist` 모드) | - |\n\n#### dmPolicy 옵션\n\n| 값 | 설명 |\n|----|------|\n| `pairing` | 페어링된 사용자만 (기본값, 권장) |\n| `allowlist` | `allowFrom` 목록의 사용자만 |\n| `open` | 모든 사용자 |\n| `disabled` | DM 비활성화 |\n\n### 고급 설정 (대부분 불필요)\n\n| 옵션 | 설명 | 기본값 |\n|------|------|--------|\n| `channelId` | 채널 식별자 | 자동 |\n| `relayUrl` | 릴레이 서버 URL ([별도 배포](#방식-2-별도-릴레이-서버-배포) 시 변경) | `https://k.tess.dev/` |\n| `relayToken` | 릴레이 인증 토큰 (별도 서버 사용 시 필수) | 환경변수 또는 자동 |\n\n### 설정 예시\n\n```json\n{\n  \"channels\": {\n    \"kakao-talkchannel\": {\n      \"accounts\": {\n        \"default\": {\n          \"enabled\": true,\n          \"dmPolicy\": \"pairing\"\n        }\n      }\n    }\n  }\n}\n```\n\n---\n\n## 라이선스\n\nMIT\n","readmeFilename":"README.md","_rev":"1-6d4a7bcb24d25a68dea30868dafb2df0"}