@spacebar_ai/moldclaw-core 2026.3.14 → 2026.3.16

package/extensions/kakao-talkchannel/MIGRATION_CODE_ANALYSIS.md

@@ -0,0 +1,383 @@
+# Kakao TalkChannel Plugin - 코드 분석 (마이그레이션용)
+
+> 분석일: 2026-03-23
+> 버전: 0.5.1 (PLUGIN_VERSION) / package: 2026.3.23
+
+---
+
+## 1. 아키텍처 개요
+
+```
+index.ts (Entry Point)
+  ├── src/channel.ts (Plugin Definition - 모든 어댑터 통합)
+  ├── src/runtime.ts (PluginRuntime 싱글톤)
+  ├── src/config/schema.ts (Zod 스키마)
+  ├── src/types.ts (모든 타입 정의)
+  ├── src/version.ts (버전 상수)
+  │
+  ├── src/adapters/
+  │   ├── config.ts (계정 설정 리졸버)
+  │   ├── gateway.ts (SSE 메시지 수신 + OpenClaw 디스패치 + 커맨드)
+  │   ├── outbound.ts (텍스트 청킹)
+  │   ├── security.ts (DM 정책)
+  │   ├── pairing.ts (페어링 알림)
+  │   ├── setup.ts (설정 적용)
+  │   └── status.ts (상태 모니터링)
+  │
+  ├── src/relay/
+  │   ├── client.ts (HTTP: sendReply, healthCheck)
+  │   ├── sse.ts (SSE: connectSSE, parseSSEChunk)
+  │   ├── stream.ts (토큰 리졸브 + SSE 시작)
+  │   └── session.ts (세션 생성/상태 조회 API)
+  │
+  ├── src/kakao/
+  │   ├── payload.ts (SkillPayload 파싱)
+  │   ├── response.ts (SkillResponse 빌더 + stripMarkdown + 텍스트 청킹)
+  │   ├── callback.ts (콜백 URL 응답)
+  │   └── limits.ts (카카오 제한값 상수 + 검증)
+  │
+  └── src/commands/
+      └── card.ts (/card 커맨드 핸들러)
+```
+
+### 동작 흐름
+
+```
+1. register() → setKakaoRuntime(api.runtime) + api.registerChannel(kakaoPlugin)
+2. gateway.startAccount() → resolveToken() → connectSSE() → SSE 스트림 수신
+3. SSE message → handleInboundMessage()
+   a. 커맨드 (/help, /card 등) → 직접 sendReply()
+   b. 일반 메시지 → buildMessageContext() → finalizeInboundContext() → dispatchReplyWithBufferedBlockDispatcher()
+4. 에이전트 응답 → deliver() 콜백 → sendReply() via relay
+```
+
+---
+
+## 2. `openclaw/plugin-sdk` Import 전체 목록
+
+| 파일 | 라인 | Import |
+|------|------|--------|
+| `index.ts` | 8 | `import type { PluginRuntime } from "openclaw/plugin-sdk"` |
+| `src/runtime.ts` | 7 | `import type { PluginRuntime } from "openclaw/plugin-sdk"` |
+| `src/openclaw.d.ts` | 1-21 | `declare module "openclaw/plugin-sdk"` (타입 선언) |
+
+### `PluginRuntime` 인터페이스 (openclaw.d.ts에서 선언)
+
+```typescript
+interface PluginRuntime {
+  logger: { debug, info, warn, error }
+  channel: {
+    reply: {
+      finalizeInboundContext(ctx: unknown): unknown
+      dispatchReplyWithBufferedBlockDispatcher(params: {
+        ctx: unknown
+        cfg: unknown
+        dispatcherOptions: {
+          deliver: (payload: unknown) => void | Promise<void>
+          onReplyStart?: () => void | Promise<void>
+          onIdle?: () => void | Promise<void>
+          onError?: (err: Error, info: { kind: string }) => void
+        }
+      }): Promise<unknown>
+    }
+  }
+}
+```
+
+**핵심 사용 지점:**
+- `runtime.logger` — `src/relay/stream.ts`, `src/adapters/pairing.ts`
+- `runtime.channel.reply.finalizeInboundContext()` — `src/adapters/gateway.ts`
+- `runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher()` — `src/adapters/gateway.ts`
+
+---
+
+## 3. 외부 의존성
+
+| 패키지 | 사용처 | 용도 |
+|--------|--------|------|
+| `zod` (^3.22.0) | `src/config/schema.ts` | 설정 스키마 검증 |
+| `zod-to-json-schema` | `src/channel.ts` | Zod → JSON Schema 변환 |
+
+**내장 API 사용:**
+- `fetch` — relay HTTP 통신 (client.ts, sse.ts, session.ts, status.ts, gateway.ts)
+- `AbortController/AbortSignal` — SSE 연결 제어
+- `TextDecoder` — SSE 스트림 디코딩
+
+---
+
+## 4. 파일별 역할 및 책임
+
+### Entry Point
+
+**`index.ts`** — 플러그인 등록
+- `plugin.id = "kakao-talkchannel"`
+- `plugin.configSchema` — `channels.kakao-talkchannel` 경로에 Zod 스키마 등록
+- `plugin.register(api)` — runtime 설정 + 채널 등록
+- `getPendingPairingInfo` 재export
+
+### Core
+
+**`src/channel.ts`** — 채널 플러그인 객체 정의
+- `kakaoPlugin` 객체: meta, capabilities, config, security, outbound, status, gateway, setup, pairing 어댑터 통합
+- `capabilities`: direct 채팅만, blockStreaming=true, media=true, threads/reactions=false
+- `reload.configPrefixes = ["channels.kakao-talkchannel"]`
+
+**`src/runtime.ts`** — PluginRuntime 싱글톤
+- `setKakaoRuntime()` / `getKakaoRuntime()` / `clearKakaoRuntime()`
+
+**`src/config/schema.ts`** — Zod 설정 스키마
+- `KakaoAccountConfigSchema`: enabled, dmPolicy, allowFrom, responsePrefix, channelId, relayUrl, relayToken, sessionToken, reconnectDelayMs, maxReconnectDelayMs, textChunkLimit, chunkMode
+- `KakaoChannelConfigSchema`: `{ accounts: Record<string, AccountConfig> }`
+- `DEFAULT_RELAY_URL = "https://k.tess.dev/"`
+- 유틸: `validateAccountConfig()`, `validateChannelConfig()`
+
+**`src/types.ts`** — 전체 타입 정의
+- Kakao SkillPayload/Response 타입 (카카오 API 스펙)
+- `ResolvedKakaoTalkChannel` — 리졸브된 계정 설정
+- `InboundMessage` — 릴레이에서 수신된 메시지
+- `SSEEvent` 유니언 타입 (message, ping, error, pairing_complete, pairing_expired)
+- `SSEClientConfig`, `RelayClientConfig`
+- `KakaoChannelData`, `DeliverPayload` — OpenClaw 아웃바운드
+- `ChannelAccountSnapshot` — 런타임 상태 스냅샷
+
+**`src/version.ts`** — `PLUGIN_VERSION = "0.5.1"` (release-please 관리)
+
+### Adapters
+
+**`src/adapters/gateway.ts`** — 핵심 게이트웨이 (가장 큰 파일, ~600줄)
+- `startAccount()` / `stopAccount()` — SSE 스트림 라이프사이클
+- `handleInboundMessage()` — 메시지 수신 → 커맨드 or OpenClaw 디스패치
+- `buildMessageContext()` — OpenClaw 메시지 컨텍스트 생성 (Body, From, SessionKey 등)
+- 커맨드 핸들러: `/help`, `/?`, `/github`, `/about`, `/relay`, `/session`, `/s`, `/card`
+- `tryParseKakaoCard()` — 에이전트 응답 내 JSON 카드 자동 감지
+- `shouldShowSessionWarning()` — 50개 메시지마다 /compact 안내
+- `userActivity` Map — 사용자별 메시지 카운트 추적 (TTL 24h, max 10000)
+- `deliver()` 콜백: channelData.kakao → KakaoOutput 변환, 텍스트 → stripMarkdown, 이미지 URL 처리
+
+**`src/adapters/config.ts`** — 설정 리졸버
+- `listAccountIds()` — 최소 `["default"]` 반환
+- `resolveAccount()` — Zod 스키마로 검증 + 기본값 적용 → `ResolvedKakaoTalkChannel`
+- `isConfigured()` — 항상 true (릴레이 모드)
+- `isEnabled()` — `account.config.enabled`
+
+**`src/adapters/outbound.ts`** — 아웃바운드 어댑터
+- `chunkTextForKakao()` — 텍스트 청킹 (sentence/newline/length 모드)
+- `sendText()` / `sendMedia()` — 스텁 (항상 success, 실제 전송은 gateway.deliver에서)
+
+**`src/adapters/security.ts`** — DM 보안 정책
+- `resolveDmPolicy()` — pairing/allowlist/open/disabled
+- `collectWarnings()` — open 정책 경고
+
+**`src/adapters/pairing.ts`** — 페어링 알림
+- `normalizeAllowEntry()` — `kakao:` prefix 제거
+- `notifyApproval()` — 로그 출력만
+
+**`src/adapters/setup.ts`** — 초기 설정 적용
+- `validateInput()` — 항상 null (릴레이 모드 필수 필드 없음)
+- `applyTalkChannelConfig()` — 설정 객체 병합
+
+**`src/adapters/status.ts`** — 상태 모니터링
+- `probeAccount()` — relay `/health` HTTP GET
+- `buildAccountSnapshot()` — 런타임 상태 + probe 결과 병합
+- `collectStatusIssues()` — 경고 생성 (비활성, relay 불통, 30분 무응답)
+
+### Relay
+
+**`src/relay/client.ts`** — HTTP 클라이언트
+- `sendReply(config, messageId, response)` — `POST {relayUrl}openclaw/reply`
+- `healthCheck(config)` — `GET {relayUrl}/health`
+- `RelayHttpError` — 401/410 → `isAuthError=true`
+- re-export: `connectSSE`, `parseSSEChunk`, `calculateReconnectDelay` from sse.ts
+
+**`src/relay/sse.ts`** — SSE 클라이언트
+- `connectSSE(config, handlers, abortSignal)` — SSE 연결 + 자동 재연결
+- `parseSSEChunk(chunk)` — SSE 텍스트 파싱 (`event:`, `data:`, `id:`)
+- `calculateReconnectDelay()` — 지수 백오프 + 20% 지터
+- 재연결: `maxRetries` 한도, 401/410은 즉시 throw
+- 이벤트 처리: message → onMessage, error → onError, pairing_complete/expired
+
+**`src/relay/stream.ts`** — 스트림 오케스트레이터
+- `startRelayStream()` — 토큰 리졸브 → connectSSE
+- `resolveToken()` — 우선순위: sessionToken > relayToken > env > createSession()
+- `sanitizeTokenFromLog()` — Bearer 토큰 마스킹
+
+**`src/relay/session.ts`** — 세션 API
+- `createSession(relayUrl)` — `POST {relayUrl}v1/sessions/create` → sessionToken + pairingCode
+- `checkSessionStatus(token, relayUrl)` — `GET {relayUrl}v1/sessions/{token}/status`
+
+### Kakao
+
+**`src/kakao/payload.ts`** — SkillPayload 파서
+- `parseSkillPayload()` — 필수 필드 검증
+- `extractUserId()`, `extractUtterance()`, `parseKakaoUser()`, `getCallbackUrl()`
+
+**`src/kakao/response.ts`** — SkillResponse 빌더
+- `stripMarkdown()` — 마크다운 → 플레인텍스트
+- `chunkTextForKakao()` — sentence/newline/length 모드
+- 빌더: `buildSimpleTextResponse`, `buildCallbackAckResponse`, `buildErrorResponse`, `buildMultiTextResponse`, `buildSimpleImageResponse`, `buildTextCardResponse`, `buildBasicCardResponse`, `buildCommerceCardResponse`, `buildListCardResponse`, `buildItemCardResponse`, `buildCarouselResponse`
+
+**`src/kakao/callback.ts`** — 콜백 핸들러
+- `sendCallback(callbackUrl, response)` — 콜백 URL로 POST
+- `createCallbackTracker()` — Map 기반 콜백 추적기 (add/get/remove/cleanup)
+- `isCallbackExpired()` — 60초 TTL 체크
+
+**`src/kakao/limits.ts`** — 카카오 제한값
+- `KAKAO_LIMITS` 상수 (simpleText 1000자, 카드 제목 50자, 설명 230자, output 3개 등)
+- 검증 함수들: `validateSimpleText`, `validateCardTitle`, `validateButton` 등
+
+### Commands
+
+**`src/commands/card.ts`** — `/card` 커맨드
+- `parseCardArgs()` — 타입 + 따옴표 인수 + --flag 파싱
+- `parseButtons()` — `라벨|데이터` 파싱 (webLink/phone/message 자동 감지)
+- `parseQuickReplies()` — 쉼표 구분 라벨
+- 빌더: `buildTextCard`, `buildBasicCard`, `buildListCard`, `buildCommerceCard`
+
+---
+
+## 5. 타입 의존성 그래프
+
+```
+types.ts ← (거의 모든 파일에서 import)
+  ↑
+config/schema.ts (KakaoAccountConfig 타입 → types.ts에서 import)
+  ↑
+adapters/config.ts → types.ts, config/schema.ts
+adapters/gateway.ts → types.ts, relay/stream.ts, relay/client.ts, kakao/response.ts, runtime.ts, config/schema.ts, commands/card.ts
+adapters/outbound.ts → types.ts, kakao/response.ts
+adapters/security.ts → types.ts
+adapters/pairing.ts → runtime.ts
+adapters/setup.ts → (자체 타입만)
+adapters/status.ts → types.ts
+
+relay/client.ts → types.ts, relay/sse.ts
+relay/sse.ts → types.ts
+relay/stream.ts → types.ts, relay/sse.ts, runtime.ts, relay/session.ts
+relay/session.ts → config/schema.ts
+
+kakao/payload.ts → types.ts
+kakao/response.ts → types.ts
+kakao/callback.ts → types.ts
+kakao/limits.ts → types.ts
+
+commands/card.ts → types.ts, relay/client.ts
+
+channel.ts → types.ts, 모든 adapters/*, config/schema.ts
+index.ts → channel.ts, runtime.ts, config/schema.ts
+```
+
+---
+
+## 6. Relay 통신 프로토콜
+
+### 엔드포인트
+
+| Method | URL | Auth | 용도 |
+|--------|-----|------|------|
+| POST | `{relayUrl}v1/sessions/create` | 없음 | 세션 생성 → sessionToken + pairingCode |
+| GET | `{relayUrl}v1/sessions/{token}/status` | 없음 | 세션 상태 조회 |
+| GET | `{relayUrl}v1/events` | `Bearer {token}` | SSE 스트림 (메시지 수신) |
+| POST | `{relayUrl}openclaw/reply` | `Bearer {token}` | 응답 전송 |
+| GET | `{relayUrl}/health` | Optional | 헬스 체크 |
+
+### SSE 이벤트 타입
+
+| Event | Data | 설명 |
+|-------|------|------|
+| `message` | `InboundMessage` | 카카오 사용자 메시지 |
+| `ping` | `{}` | keepalive |
+| `error` | `{code, message}` | 서버 에러 |
+| `pairing_complete` | `{kakaoUserId, pairedAt}` | 페어링 성공 |
+| `pairing_expired` | `{reason}` | 페어링 만료 |
+
+### 토큰 리졸브 우선순위
+
+1. `config.sessionToken` (자동 생성)
+2. `config.relayToken` (수동 설정)
+3. `OPENCLAW_TALKCHANNEL_RELAY_TOKEN` (환경변수)
+4. `createSession()` → 새 세션 생성 + 페어링 코드 발급
+
+### 인증 에러 처리
+
+- HTTP 401/410 → `RelayHttpError.isAuthError=true` → 세션 토큰 무효화 → SSE 재연결 중단
+
+---
+
+## 7. OpenClaw 메시지 컨텍스트 매핑
+
+`buildMessageContext()`에서 생성하는 필드:
+
+| 필드 | 값 |
+|------|-----|
+| `Body` | 사용자 텍스트 |
+| `From` | `kakao:{userId}` |
+| `To` | `kakao:{channelId}` |
+| `Provider` | `"kakao-talkchannel"` |
+| `Surface` | `"kakao-talkchannel"` |
+| `SessionKey` | `agent:main:kakao-talkchannel:dm:{userId}` |
+| `ChatType` | `"direct"` |
+| `CommandAuthorized` | `true` |
+
+---
+
+## 8. 변환 시 주의사항
+
+### 중요 패턴
+
+1. **싱글톤 런타임** — `runtime.ts`의 모듈 레벨 `let runtime` 패턴. 플러그인 SDK 변경 시 DI 방식으로 전환 고려.
+
+2. **커맨드 시스템** — gateway.ts 내 `PLUGIN_COMMANDS` 맵으로 자체 커맨드 처리. OpenClaw 코어의 커맨드 시스템(`nativeCommands: false`)과 별개.
+
+3. **deliver 콜백 내 복잡한 변환** — `dispatchReplyWithBufferedBlockDispatcher`의 `deliver` 콜백에서:
+   - `channelData.kakao` → 카카오 카드 변환
+   - `tryParseKakaoCard()` — JSON 텍스트 자동 카드 감지
+   - `stripMarkdown()` — 마크다운 제거
+   - `shouldWarn` → quickReplies에 /compact 안내 삽입
+
+4. **세션 토큰 인메모리 관리** — `activeSessionTokenMap`, `pendingPairingInfoMap`은 메모리에만 존재. 재시작 시 유실.
+
+5. **outbound 어댑터 스텁** — `sendText()`/`sendMedia()`는 항상 success 반환. 실제 전송은 gateway의 deliver에서 수행.
+
+6. **`openclaw.d.ts` 타입 선언** — `openclaw/plugin-sdk` 모듈을 ambient declaration으로 정의. 실제 SDK 패키지가 없고 선언 파일로만 존재.
+
+7. **callback.ts 미사용 가능성** — `createCallbackTracker()`와 `sendCallback()`은 정의되어 있으나 gateway.ts에서 직접 사용하지 않음 (릴레이 모드에서는 relay가 콜백 처리).
+
+8. **payload.ts 부분 사용** — `parseSkillPayload()` 등은 릴레이 서버에서 이미 파싱된 `InboundMessage`를 받으므로 직접 사용되지 않을 수 있음 (릴레이가 아닌 직접 모드 대비).
+
+9. **zod-to-json-schema** — `channel.ts`에서 import하지만 `package.json` dependencies에 없음. 번들러 또는 monorepo 의존성으로 제공될 수 있음.
+
+10. **URL 패턴 불일치** — `sendReply`는 `{baseUrl}openclaw/reply`, SSE는 `{baseUrl}v1/events`, session은 `{baseUrl}v1/sessions/create`. health는 `{relayUrl}/health` (슬래시 처리 다름).
+
+### 미사용/잠재적 데드 코드
+
+- `src/kakao/callback.ts` — gateway에서 import되지 않음
+- `src/kakao/payload.ts` — gateway에서 import되지 않음 (릴레이가 파싱 처리)
+- `src/kakao/limits.ts` — gateway에서 직접 사용 안 함 (하드코딩된 숫자 사용)
+- `src/relay/session.ts`의 `checkSessionStatus()` — 아무 데서도 호출되지 않음
+- `src/adapters/outbound.ts`의 `sendText()`/`sendMedia()` — 스텁
+
+### 설정 경로
+
+- 전체 설정: `channels.kakao-talkchannel.accounts.<accountId>`
+- 기본 accountId: `"default"`
+- Zero-config 지원: 설정 없이도 기본값으로 동작
+
+---
+
+## 9. 파일 크기 순위 (코드 복잡도 참고)
+
+1. `src/adapters/gateway.ts` — ~600줄 (핵심 로직)
+2. `src/types.ts` — ~350줄 (타입만)
+3. `src/kakao/response.ts` — ~300줄 (빌더)
+4. `src/commands/card.ts` — ~280줄 (커맨드)
+5. `src/relay/sse.ts` — ~200줄 (SSE)
+6. `src/config/schema.ts` — ~130줄 (스키마)
+7. `src/relay/client.ts` — ~130줄 (HTTP)
+8. `src/kakao/payload.ts` — ~130줄 (파서)
+9. `src/adapters/config.ts` — ~120줄
+10. `src/adapters/status.ts` — ~100줄
+11. `src/kakao/callback.ts` — ~100줄
+12. `src/kakao/limits.ts` — ~100줄
+13. `src/relay/stream.ts` — ~100줄
+14. `src/relay/session.ts` — ~90줄
+15. 나머지 — 각 ~50줄 이하

package/extensions/kakao-talkchannel/MIGRATION_STRATEGY.md

@@ -0,0 +1,115 @@
+# KAKAO-CORE-MIGRATION 전략 문서
+
+**프로젝트**: kakao-talkchannel → moldclaw-core 내부 extension 마이그레이션
+**시작일**: 2026-03-23
+**PM**: discord_main
+
+---
+
+## 1. 프로젝트 개요
+
+### 목표
+외부 플러그인 형식의 kakao-talkchannel을 moldclaw-core 내부 extension 형식으로 완전 변환하여 번들링한다.
+
+### 기대 효과
+- 별도 플러그인 설치 불필요
+- manifest 파일 문제 해결
+- moldclaw 설치 시 즉시 사용 가능
+- 버전 관리 일원화
+
+---
+
+## 2. 에이전트 구성
+
+| 역할 | 에이전트 | 상태 | 임무 |
+|------|----------|------|------|
+| PM | discord_main | 활성 | 전략, 조율, 검토 |
+| 아키텍트 | arch-analyst | 🔄 분석 중 | Plugin SDK 구조 분석 |
+| 분석가 | kakao-analyst | 🔄 분석 중 | 현재 코드 분석 |
+| 마이그레이터 | migrator | 대기 | 코드 변환 |
+| QA 리드 | qa-lead | 대기 | 상호 크리틱, 검증 |
+
+---
+
+## 3. 실행 계획
+
+### Phase 1: 분석 (병렬)
+- [ ] arch-analyst: moldclaw-core plugin SDK 구조 분석
+- [ ] kakao-analyst: kakao-talkchannel 코드 분석
+- **산출물**: `MIGRATION_ARCH_ANALYSIS.md`, `MIGRATION_CODE_ANALYSIS.md`
+
+### Phase 2: 전략 확정
+- [ ] PM: 분석 결과 종합
+- [ ] Import 경로 매핑표 작성
+- [ ] 변환 순서 결정
+- **산출물**: 이 문서 업데이트
+
+### Phase 3: 마이그레이션
+- [ ] migrator: index.ts 변환
+- [ ] migrator: src/ 파일들 변환
+- [ ] migrator: 의존성 정리
+- **산출물**: 변환된 코드
+
+### Phase 4: QA
+- [ ] qa-lead: 코드 리뷰
+- [ ] qa-lead: 빌드 테스트
+- [ ] qa-lead: 기능 테스트
+- **산출물**: `QA_REPORT.md`
+
+### Phase 5: 완료
+- [ ] 커밋 및 문서화
+- [ ] moldClaw 앱에서 불필요한 번들 제거
+
+---
+
+## 4. 핵심 변환 포인트 (예상)
+
+### Import 경로 변경
+```typescript
+// Before (외부 플러그인)
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+// After (내부 extension)
+import type { PluginRuntime } from "@moldclaw/core/plugin-sdk/core";
+```
+
+### Entry Point 변경
+```typescript
+// Before
+const plugin = {
+  id: "kakao-talkchannel",
+  register(api) { ... }
+};
+export default plugin;
+
+// After
+import { defineChannelPluginEntry } from "@moldclaw/core/plugin-sdk/core";
+export default defineChannelPluginEntry({
+  id: "kakao-talkchannel",
+  plugin: kakaoPlugin,
+  setRuntime: setKakaoRuntime,
+});
+```
+
+---
+
+## 5. 리스크 및 대응
+
+| 리스크 | 영향 | 대응 |
+|--------|------|------|
+| Plugin SDK 내부 타입 불일치 | 높음 | 철저한 분석 후 진행 |
+| Relay 통신 로직 호환성 | 중간 | 기존 로직 최대한 유지 |
+| 빌드 오류 | 중간 | 점진적 변환, 단계별 확인 |
+
+---
+
+## 6. 크리틱 체크포인트
+
+Phase 완료 시마다 상호 검토:
+1. 분석 결과 완전성 검토
+2. 변환 코드 정확성 검토
+3. 테스트 커버리지 검토
+
+---
+
+_문서 업데이트: Phase 진행에 따라 갱신_

package/extensions/kakao-talkchannel/README.md

@@ -0,0 +1,50 @@
+# Kakao TalkChannel Plugin for OpenClaw
+
+**moldClaw 번들 버전**
+
+카카오톡 채널을 OpenClaw AI 에이전트와 연결합니다.
+
+## 설치
+
+이 플러그인은 moldClaw 앱에 번들되어 있습니다. 앱 시작 시 자동으로 `~/.openclaw/extensions/kakao-talkchannel`에 설치됩니다.
+
+## 설정
+
+1. **moldClaw 앱에서 설정** → **카카오톡 채널** 클릭
+2. 페어링 코드가 표시됩니다
+3. 카카오톡 채널에서 해당 코드를 입력하면 연동 완료
+
+### 수동 설정 (고급)
+
+`~/.openclaw/config.yaml`에 추가:
+
+```yaml
+channels:
+  kakao-talkchannel:
+    accounts:
+      default:
+        enabled: true
+        relayUrl: https://moldclaw-relay.fly.dev/
+        dmPolicy: pairing  # pairing | allowlist | open | disabled
+```
+
+## 릴레이 서버
+
+기본 릴레이: `https://moldclaw-relay.fly.dev/`
+
+자체 릴레이 서버를 운영하려면 [moldclaw-relay](https://github.com/msh0678/moldclaw-relay) 참조.
+
+## 보안
+
+- 모든 통신은 HTTPS로 암호화
+- 세션 토큰은 단방향 해시 저장
+- DM 정책으로 허용 사용자 제어 가능
+
+## 버전
+
+- **0.5.1-moldclaw.1**: moldClaw 번들 초기 버전
+- 기반: [kakao-bart-lee/openclaw-kakao-talkchannel-plugin](https://github.com/kakao-bart-lee/openclaw-kakao-talkchannel-plugin) v0.5.1
+
+## 라이선스
+
+MIT

package/extensions/kakao-talkchannel/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Kakao TalkChannel Plugin Entry Point
+ *
+ * Bundled channel for moldclaw-core.
+ * Uses defineChannelPluginEntry pattern.
+ */
+import type { ChannelPlugin } from "@moldclaw/core/plugin-sdk/core";
+import { defineChannelPluginEntry } from "@moldclaw/core/plugin-sdk/core";
+import { kakaoPlugin, getPendingPairingInfo } from "./src/channel.js";
+import { setKakaoRuntime } from "./src/runtime.js";
+
+export default defineChannelPluginEntry({
+  id: "kakao-talkchannel",
+  name: "Kakao TalkChannel",
+  description: "KakaoTalk 채널 챗봇을 moldClaw에 연결합니다",
+  plugin: kakaoPlugin as ChannelPlugin,
+  setRuntime: setKakaoRuntime,
+});
+
+export { getPendingPairingInfo };

package/extensions/kakao-talkchannel/moldclaw.plugin.json

@@ -0,0 +1,98 @@
+{
+  "id": "kakao-talkchannel",
+  "name": "Kakao TalkChannel",
+  "version": "2026.3.23",
+  "description": "Kakao TalkChannel integration for moldClaw",
+  "main": "index.ts",
+  "channels": ["kakao-talkchannel"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "accounts": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Enable this account"
+            },
+            "channelId": {
+              "type": "string",
+              "description": "Channel identifier (optional, for display only)"
+            },
+            "relayUrl": {
+              "type": "string",
+              "default": "https://moldclaw-relay.fly.dev/",
+              "description": "Relay server URL"
+            },
+            "relayToken": {
+              "type": "string",
+              "description": "Relay authentication token (account-based auth)"
+            },
+            "sessionToken": {
+              "type": "string",
+              "description": "Session token (pairing-based auth)"
+            },
+            "dmPolicy": {
+              "type": "string",
+              "enum": ["pairing", "allowlist", "open", "disabled"],
+              "default": "pairing",
+              "description": "DM policy for unauthorized users"
+            },
+            "responsePrefix": {
+              "type": "string",
+              "description": "Prefix prepended to agent responses by moldClaw core"
+            },
+            "allowFrom": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Allowed user IDs (when dmPolicy is allowlist)"
+            },
+            "textChunkLimit": {
+              "type": "number",
+              "minimum": 100,
+              "maximum": 1000,
+              "default": 400,
+              "description": "Maximum text chunk size"
+            },
+            "chunkMode": {
+              "type": "string",
+              "enum": ["sentence", "newline", "length"],
+              "default": "sentence",
+              "description": "Text chunking mode"
+            }
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "accounts.*.relayToken": {
+      "label": "Relay Token",
+      "sensitive": true,
+      "placeholder": "relay_xxx..."
+    },
+    "accounts.*.sessionToken": {
+      "label": "Session Token",
+      "sensitive": true
+    },
+    "accounts.*.relayUrl": {
+      "label": "Relay Server URL",
+      "placeholder": "https://moldclaw-relay.fly.dev/"
+    },
+    "accounts.*.channelId": {
+      "label": "Channel ID",
+      "placeholder": "@example"
+    },
+    "accounts.*.dmPolicy": {
+      "label": "DM Policy"
+    },
+    "accounts.*.responsePrefix": {
+      "label": "Response Prefix",
+      "placeholder": "[카카오] "
+    }
+  }
+}

package/extensions/kakao-talkchannel/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@moldclaw/kakao-talkchannel",
+  "version": "2026.3.23",
+  "private": true,
+  "description": "MoldClaw Kakao TalkChannel plugin",
+  "type": "module",
+  "moldclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}