@happycastle/openclaw-channel-talk 0.1.0

package/README.md

@@ -0,0 +1,206 @@
+# @happycastle/openclaw-channel-talk
+
+> ⚠️ **Unofficial** — 이 플러그인은 Channel Corp 또는 OpenClaw 팀과 관련이 없는 커뮤니티 프로젝트입니다.
+
+[Channel Talk (채널톡)](https://channel.io) Team Chat을 OpenClaw에 연동하는 채널 플러그인입니다.
+
+## ✨ Features
+
+- 📨 **Team Chat 메시지 수신** — 웹훅을 통해 채널톡 팀챗 메시지를 실시간으로 수신
+- 💬 **메시지 발송** — OpenClaw 에이전트가 채널톡 팀챗에 직접 응답
+- 🤖 **커스텀 봇 이름** — `botName` 설정으로 봇 표시 이름 변경 가능
+- 🔄 **자동 재시도** — API 오류(429, 5xx) 시 지수 백오프 재시도
+- 📝 **Markdown 청킹** — 긴 메시지를 자동으로 분할하여 전송
+- 🔒 **중복 메시지 필터링** — 동일 메시지 중복 처리 방지
+
+## 📋 Prerequisites
+
+- [OpenClaw](https://github.com/nicepkg/openclaw)가 설치되어 실행 중이어야 합니다
+- Channel Talk 계정 및 API 키 (Access Key + Access Secret)
+- 웹훅 수신을 위한 공개 URL (Tailscale Funnel, ngrok, 리버스 프록시 등)
+
+## 🚀 설치 및 설정 가이드
+
+### 1단계: Channel Talk API 키 발급
+
+1. [채널 데스크](https://desk.channel.io)에 로그인
+2. **설정** → **보안 및 개발** → **API Key 관리**로 이동
+3. **새 API Key 생성** 클릭
+4. **Access Key**와 **Access Secret**을 안전하게 복사해 둡니다
+
+### 2단계: 플러그인 설치
+
+**npm을 통한 설치 (권장):**
+
+```bash
+openclaw plugins install @happycastle/openclaw-channel-talk
+```
+
+**로컬 설치 (개발용):**
+
+```bash
+git clone https://github.com/happycastle114/openclaw-channel-talk.git
+cd openclaw-channel-talk
+npm install
+# OpenClaw 설정에서 로컬 경로를 지정합니다
+```
+
+### 3단계: OpenClaw 설정
+
+OpenClaw 설정 파일(`config.yaml` 또는 `config.json`)에 다음을 추가합니다:
+
+```yaml
+channels:
+  channel-talk:
+    # Channel Talk API 인증 정보 (필수)
+    accessKey: "your-access-key"
+    accessSecret: "your-access-secret"
+
+    # 봇 표시 이름 (선택, 기본값: API 기본 봇 이름)
+    botName: "MyBot"
+
+    # 팀챗 그룹 정책 (선택, 기본값: "open")
+    # "open" = 모든 팀챗 메시지 처리
+    # "closed" = 팀챗 메시지 처리 안 함
+    groupPolicy: "open"
+
+    # 웹훅 서버 설정 (선택)
+    webhook:
+      port: 3979              # 기본값: 3979
+      path: "/api/channel-talk"  # 기본값: /api/channel-talk
+```
+
+### 4단계: 웹훅 엔드포인트 공개
+
+채널톡이 웹훅 이벤트를 보내려면 공개 URL이 필요합니다. 아래 방법 중 하나를 선택하세요:
+
+**Tailscale Funnel (권장):**
+
+```bash
+tailscale funnel 3979
+# https://your-machine.tail12345.ts.net 형태의 URL이 생성됩니다
+```
+
+**ngrok:**
+
+```bash
+ngrok http 3979
+# https://xxxx-xxxx.ngrok-free.app 형태의 URL이 생성됩니다
+```
+
+**리버스 프록시 (Nginx, Caddy 등):**
+
+기존 도메인이 있다면 리버스 프록시로 `localhost:3979`를 포워딩합니다.
+
+### 5단계: Channel Talk 웹훅 등록
+
+채널톡 API를 사용하여 웹훅을 등록합니다:
+
+```bash
+curl -X PUT "https://api.channel.io/open/v5/native/functions" \
+  -H "x-access-key: YOUR_ACCESS_KEY" \
+  -H "x-access-secret: YOUR_ACCESS_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "body": {
+      "nativeFunctions": [{
+        "name": "openclaw-webhook",
+        "uri": "https://YOUR_PUBLIC_URL/api/channel-talk",
+        "method": "POST",
+        "headers": {}
+      }]
+    }
+  }'
+```
+
+> 💡 `YOUR_PUBLIC_URL`을 4단계에서 얻은 공개 URL로 교체하세요.
+
+### 6단계: 게이트웨이 시작
+
+```bash
+openclaw gateway start
+```
+
+이제 채널톡 Team Chat에서 메시지를 보내면 OpenClaw 에이전트가 응답합니다! 🎉
+
+## ⚙️ Configuration Reference
+
+| 키 | 타입 | 필수 | 기본값 | 설명 |
+|---|---|---|---|---|
+| `accessKey` | `string` | ✅ | — | Channel Talk API Access Key |
+| `accessSecret` | `string` | ✅ | — | Channel Talk API Access Secret |
+| `enabled` | `boolean` | ❌ | `true` | 플러그인 활성화/비활성화 |
+| `botName` | `string` | ❌ | — | 봇 메시지 표시 이름 |
+| `groupPolicy` | `"open" \| "closed"` | ❌ | `"open"` | 팀챗 그룹 메시지 처리 정책 |
+| `webhook.port` | `number` | ❌ | `3979` | 웹훅 서버 포트 |
+| `webhook.path` | `string` | ❌ | `"/api/channel-talk"` | 웹훅 엔드포인트 경로 |
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐     webhook POST      ┌──────────────────┐
+│  Channel Talk   │ ───────────────────▶   │  OpenClaw        │
+│  (Team Chat)    │                        │  Gateway         │
+│                 │     API response       │                  │
+│                 │ ◀───────────────────   │  ┌────────────┐  │
+│                 │                        │  │ channel-    │  │
+│                 │                        │  │ talk plugin │  │
+└─────────────────┘                        │  └────────────┘  │
+                                           │       │          │
+                                           │       ▼          │
+                                           │  ┌────────────┐  │
+                                           │  │   Agent     │  │
+                                           │  │  (LLM)     │  │
+                                           │  └────────────┘  │
+                                           └──────────────────┘
+
+1. 채널톡 Team Chat에 메시지 작성
+2. 웹훅이 POST /api/channel-talk 으로 이벤트 전달
+3. 플러그인이 메시지를 파싱하여 에이전트에 전달
+4. 에이전트가 응답 생성
+5. Channel Talk API로 팀챗에 응답 전송
+```
+
+## 🔍 Verified API Behavior
+
+개발 과정에서 확인된 Channel Talk API 동작 특이사항:
+
+- **웹훅 이벤트 형식**: 이벤트는 `event: "push"`로 수신됩니다. 상위 레벨에 `type` 필드가 없을 수 있습니다.
+- **Group ID 위치**: `groupId`는 `entity.chatId`에서 가져옵니다. `refers.group.id`에는 없을 수 있습니다.
+- **`actAsManager` 옵션**: Team Chat에서 사용 시 `422` 에러가 발생합니다. 이 옵션은 User Chat 전용입니다.
+- **`botName` 파라미터**: 쿼리 파라미터로 전달하면 커스텀 봇 이름이 정상 작동합니다.
+- **메시지 발신자 타입**: 봇이 보낸 메시지는 `personType: "bot"`으로 표시됩니다.
+
+## 🛠️ Troubleshooting
+
+### 웹훅이 수신되지 않는 경우
+
+1. 공개 URL이 올바르게 설정되었는지 확인합니다
+2. 게이트웨이가 실행 중인지 확인합니다: `openclaw gateway status`
+3. 포트가 방화벽에 의해 차단되지 않았는지 확인합니다
+4. 웹훅 등록 curl 명령을 다시 실행합니다
+
+### 인증 오류 (401/403)
+
+- `accessKey`와 `accessSecret`이 올바른지 확인합니다
+- API Key가 비활성화되지 않았는지 채널 데스크에서 확인합니다
+
+### 메시지 전송 실패 (422)
+
+- `actAsManager` 옵션을 사용하지 마세요 — Team Chat에서는 지원되지 않습니다
+- `groupId`가 유효한 팀챗 그룹 ID인지 확인합니다
+
+### 봇이 자기 메시지에 반응하는 경우
+
+- 플러그인은 `personType: "bot"` 메시지를 자동으로 무시합니다
+- 이 문제가 발생하면 로그를 확인해 주세요
+
+## 📄 License
+
+MIT
+
+## ⚠️ Disclaimer
+
+이 프로젝트는 **비공식 커뮤니티 프로젝트**입니다.
+[Channel Corp](https://channel.io) 또는 [OpenClaw](https://github.com/nicepkg/openclaw) 팀과 어떠한 제휴 관계도 없습니다.
+Channel Talk은 Channel Corp의 상표입니다.

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { channelTalkPlugin } from "./src/channel.js";
+import { setChannelTalkRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "channel-talk",
+  name: "Channel Talk",
+  description: "Channel Talk (채널톡) Team Chat channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setChannelTalkRuntime(api.runtime);
+    api.registerChannel({ plugin: channelTalkPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "channel-talk",
+  "channels": [
+    "channel-talk"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@happycastle/openclaw-channel-talk",
+  "version": "0.1.0",
+  "description": "OpenClaw Channel Talk (채널톡) Team Chat channel plugin",
+  "type": "module",
+  "license": "MIT",
+  "author": "happycastle114",
+  "homepage": "https://github.com/happycastle114/openclaw-channel-talk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/happycastle114/openclaw-channel-talk.git"
+  },
+  "keywords": [
+    "openclaw",
+    "channel-talk",
+    "채널톡",
+    "chatbot",
+    "team-chat",
+    "plugin"
+  ],
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "express": "^4.19.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "channel-talk",
+      "label": "Channel Talk",
+      "selectionLabel": "Channel Talk (채널톡)",
+      "docsPath": "channel-talk",
+      "docsLabel": "Channel Talk Setup",
+      "blurb": "채널톡 Team Chat integration",
+      "aliases": [
+        "channeltalk",
+        "채널톡"
+      ],
+      "order": 110
+    },
+    "install": {
+      "npmSpec": "@happycastle/openclaw-channel-talk",
+      "localPath": "extensions/channel-talk",
+      "defaultChoice": false
+    }
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,172 @@
+/**
+ * Channel Talk API v5 HTTP Client
+ * Handles authentication, retries, and message sending
+ */
+
+import type {
+  ChannelTalkConfig,
+  ChannelTalkCredentials,
+  SendMessageParams,
+  SendMessageResponse,
+} from './types.js';
+
+/**
+ * Sleep for specified milliseconds
+ * Used for exponential backoff retry delays
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Create an API client for Channel Talk
+ * Returns a client object with sendMessage method
+ *
+ * @param credentials - API credentials (accessKey, accessSecret)
+ * @param baseUrl - Optional base URL override (default: https://api.channel.io)
+ * @returns API client object with sendMessage method
+ */
+export function createApiClient(
+  credentials: ChannelTalkCredentials,
+  baseUrl: string = 'https://api.channel.io'
+) {
+  return {
+    /**
+     * Send a message to a Channel Talk group
+     * Implements retry logic with exponential backoff for 429/5xx errors
+     *
+     * @param params - Message parameters (groupId, plainText, blocks, options, botName)
+     * @returns Promise resolving to SendMessageResponse with messageId and groupId
+     * @throws Error on authentication failure (401/403) or after max retries exhausted
+     */
+    async sendMessage(params: SendMessageParams): Promise<SendMessageResponse> {
+      const { groupId, plainText, blocks, options, botName } = params;
+
+      // Build request body
+      const body: Record<string, unknown> = {
+        plainText,
+      };
+
+      if (blocks && blocks.length > 0) {
+        body.blocks = blocks;
+      }
+
+      if (options && options.length > 0) {
+        body.options = options;
+      }
+
+      // Build URL with optional botName query parameter
+      const url = new URL(`/open/v5/groups/${groupId}/messages`, baseUrl);
+      if (botName) {
+        url.searchParams.set('botName', botName);
+      }
+
+      // Retry configuration: 2 retries with exponential backoff (1s, 3s)
+      const maxRetries = 2;
+      const retryDelays = [1000, 3000]; // milliseconds
+
+      let lastError: Error | null = null;
+
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const response = await fetch(url.toString(), {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'x-access-key': credentials.accessKey,
+              'x-access-secret': credentials.accessSecret,
+            },
+            body: JSON.stringify(body),
+          });
+
+          // Handle authentication errors (no retry)
+          if (response.status === 401 || response.status === 403) {
+            const errorText = await response.text();
+            throw new Error(
+              `Authentication failed (${response.status}): ${errorText}`
+            );
+          }
+
+          // Handle success
+          if (response.ok) {
+            const data = (await response.json()) as Record<string, unknown>;
+
+            // Extract messageId from response
+            // Response structure: { message: { id: "...", ... }, ... }
+            const messageId: string =
+              (String((data.message as Record<string, unknown>)?.id) || '') ||
+              (String(data.id) || '') ||
+              '';
+
+            return {
+              messageId,
+              groupId,
+              message: data.message as Record<string, unknown>,
+            };
+          }
+
+          // Handle retryable errors (429, 5xx)
+          if (response.status === 429 || response.status >= 500) {
+            const errorText = await response.text();
+            lastError = new Error(
+              `API error (${response.status}): ${errorText}`
+            );
+
+            // If this is the last attempt, throw
+            if (attempt === maxRetries) {
+              throw lastError;
+            }
+
+            // Wait before retry
+            const delayMs = retryDelays[attempt];
+            await sleep(delayMs);
+            continue;
+          }
+
+          // Handle other 4xx errors (no retry)
+          const errorText = await response.text();
+          throw new Error(
+            `API error (${response.status}): ${errorText}`
+          );
+        } catch (error) {
+          // Network errors or other exceptions
+          if (error instanceof Error) {
+            lastError = error;
+          } else {
+            lastError = new Error(String(error));
+          }
+
+          // If this is the last attempt, throw
+          if (attempt === maxRetries) {
+            throw lastError;
+          }
+
+          // Wait before retry
+          const delayMs = retryDelays[attempt];
+          await sleep(delayMs);
+        }
+      }
+
+      // Should not reach here, but throw last error if we do
+      throw lastError || new Error('Unknown error sending message');
+    },
+  };
+}
+
+/**
+ * Convenience function to send a message directly
+ * Creates a client and sends a message in one call
+ *
+ * @param credentials - API credentials
+ * @param params - Message parameters
+ * @param baseUrl - Optional base URL override
+ * @returns Promise resolving to SendMessageResponse
+ */
+export async function sendMessage(
+  credentials: ChannelTalkCredentials,
+  params: SendMessageParams,
+  baseUrl?: string
+): Promise<SendMessageResponse> {
+  const client = createApiClient(credentials, baseUrl);
+  return client.sendMessage(params);
+}

package/src/channel.ts

@@ -0,0 +1,181 @@
+import type { ChannelPlugin, OpenClawConfig } from 'openclaw/plugin-sdk';
+import { buildChannelConfigSchema, DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk';
+import type { ChannelTalkCredentials } from './types.js';
+import { ChannelTalkConfigSchema } from './config-schema.js';
+import { channelTalkOutbound } from './send.js';
+import { startChannelTalkWebhook } from './webhook.js';
+
+export type ResolvedChannelTalkAccount = {
+  accountId: string;
+  credentials: ChannelTalkCredentials;
+  config: {
+    enabled?: boolean;
+    accessKey?: string;
+    accessSecret?: string;
+    botName?: string;
+    groupPolicy?: string;
+    webhook?: { port?: number; path?: string };
+  };
+};
+
+function readChannelConfig(cfg: OpenClawConfig): Record<string, unknown> | undefined {
+  return (cfg.channels as Record<string, Record<string, unknown>> | undefined)?.['channel-talk'];
+}
+
+function resolveCredentials(
+  raw: Record<string, unknown> | undefined,
+): ChannelTalkCredentials | null {
+  const accessKey = typeof raw?.accessKey === 'string' ? raw.accessKey : '';
+  const accessSecret = typeof raw?.accessSecret === 'string' ? raw.accessSecret : '';
+  if (!accessKey || !accessSecret) return null;
+  return { accessKey, accessSecret };
+}
+
+const meta = {
+  id: 'channel-talk',
+  label: 'Channel Talk',
+  selectionLabel: 'Channel Talk (채널톡)',
+  docsPath: '/channels/channel-talk',
+  docsLabel: 'Channel Talk Setup',
+  blurb: '채널톡 Team Chat integration',
+  aliases: ['channeltalk', '채널톡'],
+  order: 500,
+} as const;
+
+export const channelTalkPlugin: ChannelPlugin<ResolvedChannelTalkAccount> = {
+  id: 'channel-talk',
+
+  meta: { ...meta },
+
+  capabilities: {
+    chatTypes: ['channel'],
+    polls: false,
+    threads: false,
+    media: false,
+  },
+
+  reload: { configPrefixes: ['channels.channel-talk'] },
+
+  configSchema: buildChannelConfigSchema(ChannelTalkConfigSchema as any),
+
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+
+    resolveAccount: (cfg) => {
+      const raw = readChannelConfig(cfg);
+      const creds = resolveCredentials(raw);
+      return {
+        accountId: DEFAULT_ACCOUNT_ID,
+        credentials: creds ?? { accessKey: '', accessSecret: '' },
+        config: {
+          enabled: raw?.enabled !== false,
+          accessKey: typeof raw?.accessKey === 'string' ? raw.accessKey : undefined,
+          accessSecret: typeof raw?.accessSecret === 'string' ? raw.accessSecret : undefined,
+          botName: typeof raw?.botName === 'string' ? raw.botName : undefined,
+          groupPolicy: typeof raw?.groupPolicy === 'string' ? raw.groupPolicy : undefined,
+          webhook: raw?.webhook as { port?: number; path?: string } | undefined,
+        },
+      };
+    },
+
+    isConfigured: (account) =>
+      Boolean(account.credentials.accessKey && account.credentials.accessSecret),
+
+    resolveAllowFrom: () => undefined,
+  },
+
+  outbound: channelTalkOutbound,
+
+  gateway: {
+    startAccount: async (ctx) => {
+      const port =
+        (readChannelConfig(ctx.cfg)?.webhook as { port?: number } | undefined)?.port ?? 3979;
+      ctx.setStatus({ accountId: ctx.accountId, port } as any);
+      ctx.log?.info(`starting channel-talk webhook (port ${port})`);
+      return startChannelTalkWebhook({
+        cfg: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        accountId: ctx.accountId,
+        setStatus: (next) => ctx.setStatus(next as any),
+        log: ctx.log,
+      });
+    },
+  },
+
+  setup: {
+    resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+
+    applyAccountConfig: ({ cfg, input }) => ({
+      ...cfg,
+      channels: {
+        ...(cfg.channels as Record<string, unknown>),
+        'channel-talk': {
+          ...readChannelConfig(cfg),
+          ...(input.token ? { accessKey: input.token } : {}),
+          ...(input.botToken ? { accessSecret: input.botToken } : {}),
+          enabled: true,
+        },
+      },
+    } as OpenClawConfig),
+  },
+
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      port: snapshot.port ?? null,
+    }),
+
+    probeAccount: async ({ account }) => ({
+      configured: Boolean(
+        account.credentials.accessKey && account.credentials.accessSecret,
+      ),
+      enabled: account.config.enabled !== false,
+    }),
+
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      configured: Boolean(
+        account.credentials.accessKey && account.credentials.accessSecret,
+      ),
+      enabled: account.config.enabled !== false,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+    }),
+  },
+
+  security: {
+    collectWarnings: ({ cfg }) => {
+      const raw = readChannelConfig(cfg);
+      const defaultGroupPolicy = (
+        cfg.channels as Record<string, Record<string, unknown>> | undefined
+      )?.defaults?.groupPolicy as string | undefined;
+      const groupPolicy =
+        (typeof raw?.groupPolicy === 'string' ? raw.groupPolicy : undefined) ??
+        defaultGroupPolicy ??
+        'open';
+
+      if (groupPolicy !== 'open') {
+        return [];
+      }
+      return [
+        `- Channel Talk: groupPolicy="open" processes all team chat messages. ` +
+          `Set channels.channel-talk.groupPolicy="closed" to disable team chat processing.`,
+      ];
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,60 @@
+/**
+ * Channel Talk Plugin Configuration Schema
+ * Defines the structure and validation for Channel Talk plugin configuration
+ */
+
+import { Type } from '@sinclair/typebox';
+import type { Static } from '@sinclair/typebox';
+
+/**
+ * Channel Talk configuration schema using TypeBox
+ * Defines required and optional configuration fields for the plugin
+ */
+export const ChannelTalkConfigSchema = Type.Object(
+  {
+    /** Enable/disable the Channel Talk plugin */
+    enabled: Type.Optional(Type.Boolean({ default: true })),
+    
+    /** Channel Talk API access key (required when enabled) */
+    accessKey: Type.String({
+      description: 'Channel Talk access key for API authentication',
+    }),
+    
+    /** Channel Talk API access secret (required when enabled) */
+    accessSecret: Type.String({
+      description: 'Channel Talk access secret for API authentication',
+    }),
+    
+    /** Webhook configuration */
+    webhook: Type.Optional(
+      Type.Object({
+        /** Port for webhook server (default: 3979) */
+        port: Type.Optional(Type.Number({ default: 3979 })),
+        
+        /** Path for webhook endpoint (default: /api/channel-talk) */
+        path: Type.Optional(Type.String({ default: '/api/channel-talk' })),
+      })
+    ),
+    
+    /** Bot display name for sent messages (optional) */
+    botName: Type.Optional(
+      Type.String({
+        description: 'Bot display name for sent messages',
+      })
+    ),
+    
+    /** Group chat policy: 'open' = all groups allowed, 'closed' = none allowed */
+    groupPolicy: Type.Optional(
+      Type.Enum(['open', 'closed'], { default: 'open' })
+    ),
+  },
+  {
+    additionalProperties: false,
+  }
+);
+
+/**
+ * TypeScript type derived from the schema
+ * Use this for type-safe configuration handling
+ */
+export type ChannelTalkConfig = Static<typeof ChannelTalkConfigSchema>;

package/src/runtime.ts

@@ -0,0 +1,33 @@
+/**
+ * Channel Talk Plugin Runtime Singleton
+ * Manages the plugin runtime instance for access throughout the plugin
+ */
+
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+
+/** Module-level runtime instance */
+let runtime: PluginRuntime | undefined;
+
+/**
+ * Set the Channel Talk plugin runtime
+ * Called during plugin initialization to store the runtime reference
+ *
+ * @param next - The PluginRuntime instance from OpenClaw
+ */
+export function setChannelTalkRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+/**
+ * Get the Channel Talk plugin runtime
+ * Throws if runtime has not been initialized
+ *
+ * @returns The PluginRuntime instance
+ * @throws Error if runtime is not initialized
+ */
+export function getChannelTalkRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error('Channel Talk runtime not initialized');
+  }
+  return runtime;
+}

package/src/send.ts

@@ -0,0 +1,42 @@
+import type { ChannelOutboundAdapter } from 'openclaw/plugin-sdk';
+import { sendMessage } from './api-client.js';
+import { getChannelTalkRuntime } from './runtime.js';
+
+export const channelTalkOutbound: ChannelOutboundAdapter = {
+  deliveryMode: 'direct',
+
+  chunker: (text, limit) =>
+    getChannelTalkRuntime().channel.text.chunkMarkdownText(text, limit),
+
+  chunkerMode: 'markdown',
+  textChunkLimit: 4000,
+
+  sendText: async ({ cfg, to, text }) => {
+    const channelCfg = cfg.channels?.['channel-talk'] as
+      | { accessKey?: string; accessSecret?: string; botName?: string }
+      | undefined;
+
+    if (!channelCfg?.accessKey || !channelCfg?.accessSecret) {
+      throw new Error(
+        'Channel Talk credentials not configured: missing accessKey or accessSecret in channels.channel-talk'
+      );
+    }
+
+    const credentials = {
+      accessKey: channelCfg.accessKey,
+      accessSecret: channelCfg.accessSecret,
+    };
+
+    const result = await sendMessage(credentials, {
+      groupId: to,
+      plainText: text,
+      botName: channelCfg.botName,
+    });
+
+    return {
+      channel: 'channel-talk',
+      messageId: result.messageId,
+      conversationId: to,
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Channel Talk API v5 TypeScript Type Definitions
+ * Interfaces for webhook events, API requests/responses, and configuration
+ */
+
+/**
+ * Channel Talk API credentials for authentication
+ * Uses x-access-key and x-access-secret headers
+ */
+export interface ChannelTalkCredentials {
+  /** Access key for API authentication */
+  accessKey: string;
+  /** Access secret for API authentication */
+  accessSecret: string;
+}
+
+/**
+ * Channel Talk plugin configuration
+ * Contains credentials and optional base URL override
+ */
+export interface ChannelTalkConfig {
+  /** API credentials */
+  credentials: ChannelTalkCredentials;
+  /** Base URL for API calls (default: https://api.channel.io) */
+  baseUrl?: string;
+}
+
+/**
+ * Text block in a message
+ * Supports HTML formatting: <b>, <i>, <link>, etc.
+ */
+export interface TextBlock {
+  type: 'text';
+  /** HTML-formatted text content */
+  value: string;
+}
+
+/**
+ * Code block in a message
+ */
+export interface CodeBlock {
+  type: 'code';
+  /** Code content */
+  value: string;
+}
+
+/**
+ * Bulleted list block in a message
+ */
+export interface BulletsBlock {
+  type: 'bullets';
+  /** Array of text blocks for each bullet point */
+  blocks: TextBlock[];
+}
+
+/**
+ * Union type for all message block types
+ */
+export type MessageBlock = TextBlock | CodeBlock | BulletsBlock;
+
+/**
+ * Message options that control behavior
+ */
+export type MessageOption =
+  | 'actAsManager'
+  | 'displayAsChannel'
+  | 'doNotPost'
+  | 'doNotSearch'
+  | 'doNotSendApp'
+  | 'doNotUpdateDesk'
+  | 'immutable'
+  | 'private'
+  | 'silent';
+
+/**
+ * Parameters for sending a message to Channel Talk
+ */
+export interface SendMessageParams {
+  /** Group ID (team chat identifier) */
+  groupId: string;
+  /** Plain text content of the message */
+  plainText: string;
+  /** Message blocks (optional, for rich formatting) */
+  blocks?: MessageBlock[];
+  /** Message options (optional) */
+  options?: MessageOption[];
+  /** Bot name to display as sender (optional) */
+  botName?: string;
+}
+
+/**
+ * Response from sending a message
+ */
+export interface SendMessageResponse {
+  /** Message ID returned by API */
+  messageId: string;
+  /** Group ID where message was sent */
+  groupId: string;
+  /** Full message object from API response */
+  message?: Record<string, unknown>;
+}
+
+/**
+ * Manager entity in webhook event
+ */
+export interface ChannelTalkManager {
+  /** Manager ID */
+  id: string;
+  /** Manager name */
+  name?: string;
+}
+
+/**
+ * Group (team chat) entity in webhook event
+ */
+export interface ChannelTalkGroup {
+  /** Group ID */
+  id: string;
+  /** Group name */
+  name?: string;
+}
+
+/**
+ * References to related entities in webhook event
+ */
+export interface ChannelTalkRefers {
+  /** Manager who sent/received the message */
+  manager?: ChannelTalkManager;
+  /** Group (team chat) where message occurred */
+  group?: ChannelTalkGroup;
+}
+
+/**
+ * Entity data in webhook event
+ * Contains the actual message content and metadata
+ */
+export interface ChannelTalkEntity {
+  /** Message ID */
+  id: string;
+  /** Chat type: 'group' for team chat, 'user' for direct, 'customer' for customer chat */
+  chatType: 'group' | 'user' | 'customer';
+  /** Person type: 'manager' for staff, 'bot' for automated messages, 'customer' for customers */
+  personType: 'manager' | 'bot' | 'customer';
+  /** Message blocks (rich formatting) */
+  blocks?: MessageBlock[];
+  /** Plain text representation of message */
+  plainText?: string;
+  /** Chat ID */
+  chatId?: string;
+  /** Person ID (sender) */
+  personId?: string;
+  /** Created timestamp */
+  createdAt?: number;
+}
+
+/**
+ * Webhook event from Channel Talk
+ * Sent when messages are created or other events occur
+ */
+export interface ChannelTalkWebhookEvent {
+  /** Event action (e.g., 'push') */
+  event: string;
+  /** Event type identifier (e.g., 'message.created.teamChat') — may be absent for push events */
+  type?: string;
+  /** Entity data (message content, metadata) */
+  entity: ChannelTalkEntity;
+  /** References to related entities (manager, group) */
+  refers: ChannelTalkRefers;
+}

package/src/webhook.ts

@@ -0,0 +1,319 @@
+import type { Server } from 'node:http';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import type { ChannelTalkWebhookEvent } from './types.js';
+import { createApiClient } from './api-client.js';
+import { getChannelTalkRuntime } from './runtime.js';
+
+const DEFAULT_ACCOUNT_ID = 'default';
+const DEDUP_TTL_MS = 60_000;
+const DEDUP_CLEANUP_INTERVAL_MS = 30_000;
+
+export type StartChannelTalkWebhookContext = {
+  cfg: OpenClawConfig;
+  runtime: { log?: (...args: unknown[]) => void; error?: (...args: unknown[]) => void };
+  abortSignal: AbortSignal;
+  accountId?: string;
+  setStatus?: (next: Record<string, unknown>) => void;
+  log?: {
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+    debug?: (msg: string, meta?: Record<string, unknown>) => void;
+  };
+};
+
+export type StartChannelTalkWebhookResult = {
+  server: Server;
+  shutdown: () => Promise<void>;
+};
+
+export async function startChannelTalkWebhook(
+  ctx: StartChannelTalkWebhookContext,
+): Promise<StartChannelTalkWebhookResult> {
+  const core = getChannelTalkRuntime();
+  const log = ctx.log ?? {
+    info: (msg: string) => ctx.runtime.log?.(`[channel-talk] ${msg}`),
+    warn: (msg: string) => ctx.runtime.log?.(`[channel-talk] WARN: ${msg}`),
+    error: (msg: string) => ctx.runtime.error?.(`[channel-talk] ${msg}`),
+    debug: (msg: string) => ctx.runtime.log?.(`[channel-talk] ${msg}`),
+  };
+
+  const channelTalkCfg = (ctx.cfg.channels as Record<string, Record<string, unknown>> | undefined)?.['channel-talk'];
+  if (!channelTalkCfg) {
+    log.error('channel-talk config not found');
+    throw new Error('channel-talk config not found in cfg.channels');
+  }
+
+  const accessKey = channelTalkCfg.accessKey as string | undefined;
+  const accessSecret = channelTalkCfg.accessSecret as string | undefined;
+  if (!accessKey || !accessSecret) {
+    log.error('channel-talk credentials not configured');
+    throw new Error('channel-talk credentials (accessKey, accessSecret) not configured');
+  }
+
+  const webhookCfg = channelTalkCfg.webhook as { port?: number; path?: string } | undefined;
+  const port = webhookCfg?.port ?? 3979;
+  const webhookPath = webhookCfg?.path ?? '/api/channel-talk';
+  const botName = channelTalkCfg.botName as string | undefined;
+  const accountId = ctx.accountId ?? DEFAULT_ACCOUNT_ID;
+
+  const apiClient = createApiClient({ accessKey, accessSecret }, channelTalkCfg.baseUrl as string | undefined);
+
+  const dedupCache = new Map<string, number>();
+
+  const cleanupDedup = () => {
+    const now = Date.now();
+    for (const [key, ts] of dedupCache) {
+      if (now - ts > DEDUP_TTL_MS) {
+        dedupCache.delete(key);
+      }
+    }
+  };
+
+  const dedupTimer = setInterval(cleanupDedup, DEDUP_CLEANUP_INTERVAL_MS);
+  (dedupTimer as unknown as { unref?: () => void }).unref?.();
+
+  const isDuplicate = (messageId: string): boolean => {
+    if (dedupCache.has(messageId)) {
+      return true;
+    }
+    dedupCache.set(messageId, Date.now());
+    return false;
+  };
+
+  const express = (await import('express')).default;
+  const app = express();
+  app.use(express.json());
+
+  app.post(webhookPath, (req: { body: unknown }, res: { status: (code: number) => { json: (data: unknown) => void } }) => {
+    res.status(200).json({ ok: true });
+
+    const body = req.body as ChannelTalkWebhookEvent | undefined;
+    if (!body) {
+      log.debug?.('empty webhook body');
+      return;
+    }
+
+    void handleWebhookEvent(body).catch((err: unknown) => {
+      log.error('webhook handler error', { error: String(err) });
+    });
+  });
+
+  async function handleWebhookEvent(event: ChannelTalkWebhookEvent): Promise<void> {
+    const isTeamChatMessage =
+      event.event === 'push' ||
+      event.type === 'message.created.teamChat';
+
+    if (!isTeamChatMessage) {
+      log.debug?.('skipping non-message event', {
+        event: event.event,
+        type: event.type,
+      });
+      return;
+    }
+
+    const entity = event.entity;
+    if (!entity) {
+      log.debug?.('skipping event without entity');
+      return;
+    }
+
+    if (entity.chatType !== 'group') {
+      log.debug?.('skipping non-group message', { chatType: entity.chatType });
+      return;
+    }
+
+    if (entity.personType === 'bot') {
+      log.debug?.('skipping bot message');
+      return;
+    }
+
+    const messageId = entity.id;
+    if (!messageId) {
+      log.debug?.('skipping message without id');
+      return;
+    }
+    if (isDuplicate(messageId)) {
+      log.debug?.('skipping duplicate message', { messageId });
+      return;
+    }
+
+    const plainText = entity.plainText?.trim() ?? '';
+    if (!plainText) {
+      log.debug?.('skipping empty message');
+      return;
+    }
+
+    const refers = event.refers;
+    const groupId = entity.chatId ?? refers?.group?.id;
+    if (!groupId) {
+      log.debug?.('skipping message without group id');
+      return;
+    }
+
+    const managerId = refers?.manager?.id ?? entity.personId ?? 'unknown';
+    const managerName = refers?.manager?.name ?? managerId;
+    const timestamp = entity.createdAt ?? Date.now();
+
+    log.info('received team chat message', {
+      messageId,
+      groupId,
+      from: managerName,
+      preview: plainText.slice(0, 80),
+    });
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg: ctx.cfg,
+      channel: 'channel-talk',
+      peer: {
+        kind: 'group' as const,
+        id: groupId,
+      },
+    });
+
+    const storePath = core.channel.session.resolveStorePath(ctx.cfg.session?.store, {
+      agentId: route.agentId,
+    });
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(ctx.cfg);
+    const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+      storePath,
+      sessionKey: route.sessionKey,
+    });
+
+    const formattedBody = core.channel.reply.formatAgentEnvelope({
+      channel: 'Channel Talk',
+      from: managerName,
+      timestamp: new Date(timestamp),
+      previousTimestamp,
+      envelope: envelopeOptions,
+      body: plainText,
+    });
+
+    const preview = plainText.replace(/\s+/g, ' ').slice(0, 160);
+    core.system.enqueueSystemEvent(
+      `Channel Talk message from ${managerName}: ${preview}`,
+      {
+        sessionKey: route.sessionKey,
+        contextKey: `channel-talk:message:${groupId}:${messageId}`,
+      },
+    );
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: formattedBody,
+      RawBody: plainText,
+      CommandBody: plainText,
+      From: `channel-talk:${managerId}`,
+      To: `group:${groupId}`,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId ?? accountId,
+      ChatType: 'channel' as const,
+      ConversationLabel: managerName,
+      SenderName: managerName,
+      SenderId: managerId,
+      Provider: 'channel-talk' as const,
+      Surface: 'channel-talk' as const,
+      MessageSid: messageId,
+      Timestamp: timestamp,
+      WasMentioned: false,
+      CommandAuthorized: false,
+      OriginatingChannel: 'channel-talk' as const,
+      OriginatingTo: `group:${groupId}`,
+    });
+
+    await core.channel.session.recordInboundSession({
+      storePath,
+      sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+      ctx: ctxPayload,
+      onRecordError: (err: unknown) => {
+        log.debug?.(`failed updating session meta: ${String(err)}`);
+      },
+    });
+
+    const textLimit = core.channel.text.resolveTextChunkLimit(ctx.cfg, 'channel-talk');
+
+    const { dispatcher, replyOptions, markDispatchIdle } =
+      core.channel.reply.createReplyDispatcherWithTyping({
+        deliver: async (payload: { text?: string }) => {
+          const replyText = payload.text;
+          if (!replyText) {
+            return;
+          }
+
+          const chunks = core.channel.text.chunkMarkdownText(replyText, textLimit);
+          for (const chunk of chunks) {
+            await apiClient.sendMessage({
+              groupId,
+              plainText: chunk,
+              botName,
+            });
+          }
+        },
+        onError: (err: unknown) => {
+          log.error('reply dispatch error', { error: String(err) });
+        },
+      });
+
+    log.info('dispatching to agent', { sessionKey: route.sessionKey });
+
+    try {
+      const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+        ctx: ctxPayload,
+        cfg: ctx.cfg,
+        dispatcher,
+        replyOptions,
+      });
+
+      markDispatchIdle();
+      log.info('dispatch complete', { queuedFinal, counts });
+    } catch (err) {
+      log.error('dispatch failed', { error: String(err) });
+      ctx.runtime.error?.(`channel-talk dispatch failed: ${String(err)}`);
+    }
+  }
+
+  const httpServer = app.listen(port, () => {
+    log.info(`channel-talk webhook started on port ${port}, path ${webhookPath}`);
+  });
+
+  httpServer.on('error', (err: Error) => {
+    log.error('server error', { error: String(err) });
+  });
+
+  ctx.setStatus?.({
+    accountId,
+    running: true,
+    connected: true,
+    lastStartAt: Date.now(),
+    port,
+    webhookPath,
+  });
+
+  const shutdown = async (): Promise<void> => {
+    log.info('shutting down channel-talk webhook');
+    clearInterval(dedupTimer);
+    dedupCache.clear();
+    return new Promise<void>((resolve) => {
+      httpServer.close((err?: Error) => {
+        if (err) {
+          log.debug?.(`server close error: ${String(err)}`);
+        }
+        ctx.setStatus?.({
+          accountId,
+          running: false,
+          connected: false,
+          lastStopAt: Date.now(),
+        });
+        resolve();
+      });
+    });
+  };
+
+  if (ctx.abortSignal) {
+    ctx.abortSignal.addEventListener('abort', () => {
+      void shutdown();
+    });
+  }
+
+  return { server: httpServer, shutdown };
+}