SeaTalk Channel for OpenClaw

SeaTalk 企业机器人 Channel 插件，使用 HTTP 事件回调接收消息，Open API 发送消息。

目录

• 功能特性
• 安装
  • 方法 A：通过 npm 包安装
  • 方法 B：通过本地源码安装
  • 方法 C：手动安装
  • 安装后必做：配置插件信任白名单
• 配置
  • 交互式配置
  • 手动配置文件
• SeaTalk 开放平台配置指南
• Webhook 回调设置
• 配置选项
• 安全策略
• 消息类型支持
• API 速率限制
• 多 Agent 与多账号绑定
• 使用示例
• 故障排除
• 开发指南
• 许可

功能特性

• ✅ HTTP Webhook 接收 — 通过事件回调接收消息，需要公网可达的 HTTPS 端点
• ✅ 私聊支持 — 用户直接与 Bot 对话（message_from_bot_subscriber）
• ✅ 群聊支持 — 在群里 @Bot（new_mentioned_message_received_from_group_chat）
• ✅ 文本消息 — 支持 Markdown（format=1）和纯文本（format=2）
• ✅ 图片消息 — Base64 编码发送，最大 5MB
• ✅ 互动消息 — 支持 interactive_message（标题、描述、按钮元素）
• ✅ 线程回复 — 通过 thread_id 支持群聊线程消息
• ✅ Webhook 签名验证 — SHA256 + 时序安全比较，防篡改
• ✅ 多账号支持 — 一个 OpenClaw 实例可同时接入多个 SeaTalk Bot
• ✅ Token 自动缓存 — app_access_token 按 appId 缓存，7200 秒过期前自动刷新
• ✅ 401 自动重试 — Token 失效时自动清除缓存并重新获取
• ✅ 消息去重 — 基于内存 TTL 的去重机制，防止 webhook 重试导致重复处理

安装

方法 A：通过 npm 包安装 (推荐)

openclaw plugins install openclaw-channel-seatalk

方法 B：通过本地源码安装

git clone <repo-url>
cd openclaw-channel-seatalk

# 安装依赖
npm install

# 以链接模式安装（修改代码后实时生效）
openclaw plugins install -l .

方法 C：手动安装

1. 将本目录复制到 ~/.openclaw/extensions/seatalk
2. 确保包含 index.ts、openclaw.plugin.json 和 package.json
3. 运行 openclaw plugins list 确认 seatalk 已显示

安装后必做：配置插件信任白名单（plugins.allow）

安装后如果看到以下提示，说明需要配置信任白名单：

[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load ...

在 ~/.openclaw/openclaw.json 中添加：

{
  "plugins": {
    "enabled": true,
    "allow": ["seatalk"]
  }
}

然后重启 Gateway：

openclaw gateway restart

配置

方法 1：交互式配置（推荐）

# 方式 A：完整引导
openclaw onboard

# 方式 B：直接配置 channels
openclaw configure --section channels

交互式流程会引导你填写：

1. App ID — SeaTalk 应用的 app_id
2. App Secret — SeaTalk 应用的 app_secret
3. Signing Secret — Webhook 签名验证密钥
4. DM Policy — 私聊策略（open / pairing / allowlist）
5. Group Policy — 群聊策略（open / allowlist / disabled）
6. Webhook 端口 — 回调服务监听端口（默认 8789）
7. Webhook 绑定地址 — 监听地址（默认 0.0.0.0）
8. Webhook Base Path — 路径前缀（默认 /openclaw/seatalk）

方法 2：手动配置文件

在 ~/.openclaw/openclaw.json 中添加：

{
  "plugins": {
    "enabled": true,
    "allow": ["seatalk"]
  },
  "channels": {
    "seatalk": {
      "enabled": true,
      "appId": "你的App ID",
      "appSecret": "你的App Secret",
      "signingSecret": "你的Signing Secret",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "webhookHost": "0.0.0.0",
      "webhookPort": 8789,
      "webhookBasePath": "/openclaw/seatalk",
      "verifyWebhookSignature": true,
      "outboundTextFormat": 1,
      "debug": false
    }
  }
}

配置完成后重启 Gateway：

openclaw gateway restart

SeaTalk 开放平台配置指南

1. 创建 SeaTalk 应用

1. 访问 SeaTalk 开放平台
2. 创建一个 Bot 应用
3. 获取 app_id 和 app_secret
4. 记录 signing_secret（用于 webhook 签名验证）

2. 配置权限

在应用管理页面确保已开启以下能力：

• ✅ Bot 消息发送权限（单聊和群聊）
• ✅ 事件回调订阅权限

3. 获取凭证

从开发者后台获取：

• App ID — 应用唯一标识
• App Secret — 应用密钥
• Signing Secret — Webhook 签名验证密钥

API 文档参考：SeaTalk API Development Guide

Webhook 回调设置

SeaTalk 通过 HTTP POST 回调将事件推送到你的服务器。你需要一个公网可达的 HTTPS 端点。

回调 URL 格式

https://<你的域名>:<端口>/<webhookBasePath>/<accountId>

例如使用默认配置和单账号（accountId 为 default）：

https://example.com:8789/openclaw/seatalk/default

本地开发（使用 ngrok）

如果 OpenClaw 部署在本地，可以用 ngrok 暴露端口：

ngrok http 8789

然后在 SeaTalk 开放平台将回调 URL 设置为：

https://<ngrok域名>/openclaw/seatalk/default

URL 验证

配置回调 URL 时，SeaTalk 会发送一个 seatalk_challenge 请求，插件会自动响应完成验证。

签名验证

启用 verifyWebhookSignature（默认开启）后，插件会使用 signingSecret 对每个请求进行 SHA256 签名验证，使用 crypto.timingSafeEqual 防止时序攻击。

配置选项

| 选项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | enabled | boolean | true | 是否启用 | | appId | string | 必填 | 应用的 app_id | | appSecret | string | 必填 | 应用的 app_secret | | signingSecret | string | - | Webhook 签名验证密钥 | | baseUrl | string | https://openapi.seatalk.io | API 基础地址 | | dmPolicy | string | "open" | 私聊策略：open / pairing / allowlist | | groupPolicy | string | "open" | 群聊策略：open / allowlist / disabled | | allowFrom | string[] | [] | 允许的发送者列表（私聊） | | groupAllowFrom | string[] | [] | 群聊发送者白名单 | | groups | object | - | 按 group_id 的群级配置 | | webhookHost | string | "0.0.0.0" | Webhook 服务监听地址 | | webhookPort | number | 8789 | Webhook 服务监听端口 | | webhookBasePath | string | "/openclaw/seatalk" | Webhook URL 路径前缀 | | verifyWebhookSignature | boolean | true | 是否验证 webhook 签名 | | signatureHeaders | string[] | ["x-seatalk-signature", "signature", "x-signature"] | 签名头名称 | | outboundTextFormat | 1 | 2 | 1 | 发送文本格式：1=Markdown, 2=纯文本 | | usablePlatform | string | "all" | 消息可用平台：all / mobile / desktop | | mediaUrlAllowlist | string[] | [] | 媒体 URL 下载白名单 | | journalTTLDays | number | 30 | 消息日志保留天数 | | debug | boolean | false | 是否开启调试日志 | | bypassProxyForSend | boolean | false | 发送链路是否绕过代理 |

安全策略

私聊策略 (dmPolicy)

• open — 任何人都可以私聊 Bot
• pairing — 新用户需要通过配对码验证
• allowlist — 只有 allowFrom 列表中的用户可以使用

群聊策略 (groupPolicy)

• open — 任何群都可以 @Bot
• allowlist — 只有配置的群可以使用
• disabled — 完全禁用群聊消息

群级配置

可以为每个群单独配置：

{
  "channels": {
    "seatalk": {
      "groupPolicy": "allowlist",
      "groups": {
        "group_id_xxx": {
          "systemPrompt": "你是客服机器人",
          "requireMention": false,
          "groupAllowFrom": ["employee_001"]
        },
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

消息类型支持

接收

| 类型 | 支持 | 说明 | | --- | --- | --- | | 文本 | ✅ | 私聊和群聊 @ 消息 | | 互动消息点击 | ✅ | interactive_message_click 事件 | | Bot 订阅 | ✅ | new_bot_subscriber 事件 | | Bot 入群/退群 | ✅ | 群事件通知 |

发送

| 类型 | 支持 | 说明 | | --- | --- | --- | | 文本 | ✅ | Markdown 或纯文本 | | 图片 | ✅ | Base64 编码，最大 5MB | | 互动消息 | ✅ | 标题、描述、按钮元素组合 | | 线程回复 | ✅ | 通过 thread_id 回复线程 |

当前不支持流式输出。SeaTalk Open API 仅提供标准 HTTP 请求-响应模式，消息在 agent 生成完整回复后一次性发送。

API 速率限制

SeaTalk Open API 有以下速率限制（参考官方文档）：

| 端点 | 限制 | | --- | --- | | 群聊消息 | 100 次/分钟 | | 单聊消息 | 300 次/分钟 | | Token 获取 | 插件自动缓存，7200 秒过期 |

多 Agent 与多账号绑定

要将一个 OpenClaw 实例同时接入多个 SeaTalk Bot，需要在配置中使用 accounts：

{
  "agents": {
    "list": [
      { "id": "main" },
      {
        "id": "support-bot",
        "workspace": "~/.openclaw/agents/support-bot/workspace"
      }
    ]
  },
  "bindings": [
    {
      "type": "route",
      "agentId": "main",
      "match": { "channel": "seatalk", "accountId": "bot_1" }
    },
    {
      "type": "route",
      "agentId": "support-bot",
      "match": { "channel": "seatalk", "accountId": "bot_2" }
    }
  ],
  "channels": {
    "seatalk": {
      "enabled": true,
      "accounts": {
        "bot_1": {
          "appId": "app-id-1",
          "appSecret": "app-secret-1",
          "signingSecret": "signing-secret-1",
          "dmPolicy": "open",
          "groupPolicy": "open"
        },
        "bot_2": {
          "appId": "app-id-2",
          "appSecret": "app-secret-2",
          "signingSecret": "signing-secret-2",
          "dmPolicy": "open",
          "groupPolicy": "allowlist"
        }
      }
    }
  }
}

多账号模式下，每个 Bot 的 webhook 路径为 <basePath>/<accountId>，例如：

• https://example.com:8789/openclaw/seatalk/bot_1
• https://example.com:8789/openclaw/seatalk/bot_2

使用示例

配置完成后：

1. 私聊 Bot — 在 SeaTalk 中找到 Bot，直接发送消息
2. 群聊 @Bot — 在群里 @Bot 名称 + 消息

编程式调用

import { seatalkPlugin } from 'openclaw-channel-seatalk';

const cfg = {
  channels: {
    seatalk: {
      appId: 'your-app-id',
      appSecret: 'your-app-secret',
    },
  },
};

// 发送文本到群
await seatalkPlugin.outbound.sendText({
  cfg,
  to: 'group:group_id_xxx',
  text: 'Hello from OpenClaw!',
  accountId: 'default',
  log: console,
});

// 发送图片到用户
await seatalkPlugin.outbound.sendMedia({
  cfg,
  to: 'user:employee_code',
  mediaPath: '/path/to/image.png',
  accountId: 'default',
  log: console,
});

to 支持以下格式：

• 群聊：group:<group_id> 或直接传 group_id
• 单聊用户：user:<employee_code> 或 employee:<employee_code>

故障排除

收不到消息

1. 确认 SeaTalk 开放平台的回调 URL 已通过验证（challenge 响应成功）
2. 确认 Webhook 端口正确且可从公网访问
3. 检查 Gateway 日志：openclaw logs | grep seatalk
4. 确认 verifyWebhookSignature 和 signingSecret 配置正确

Webhook 返回 404

回调 URL 路径必须匹配 <webhookBasePath>/<accountId>。默认单账号的路径是：

/openclaw/seatalk/default

而不是 /seatalk/events 或其他路径。

Webhook 返回 502

说明本地 webhook 服务未启动。确认 Gateway 已运行：

openclaw gateway restart
openclaw status

并检查端口是否在监听：

lsof -i :<webhookPort>

Token 获取失败

1. 确认 appId 和 appSecret 正确
2. 运行探测检查：openclaw status --deep
3. 检查网络是否可以访问 https://openapi.seatalk.io

签名验证失败

1. 确认 signingSecret 与 SeaTalk 开放平台配置一致
2. 如需临时关闭签名验证进行调试："verifyWebhookSignature": false

开发指南

首次设置

git clone <repo-url>
cd openclaw-channel-seatalk
npm install

常用命令

| 命令 | 说明 | | --- | --- | | npm run type-check | TypeScript 类型检查 | | npm run lint | 代码检查 | | npm run format | 格式化代码 | | npm run format:check | 检查格式 |

项目结构

index.ts                - 插件入口，注册 seatalk channel
openclaw.plugin.json    - 插件清单
package.json            - 包配置
tsconfig.json           - TypeScript 配置

src/
  channel.ts            - 插件核心定义（config, security, groups, messaging, outbound, gateway, status）
  types.ts              - 类型定义
  config-schema.ts      - Zod 配置校验 schema
  config.ts             - 配置解析与合并
  auth.ts               - app_access_token 获取与缓存
  runtime.ts            - 插件运行时 store
  signature.ts          - Webhook 签名验证（SHA256 + timingSafeEqual）
  webhook-server.ts     - HTTP webhook 服务器
  inbound-handler.ts    - 入站消息处理
  send-service.ts       - 出站消息发送（群聊、单聊、文本、图片、互动消息）
  onboarding.ts         - 交互式配置向导
  access-control.ts     - 访问控制（dmPolicy, groupPolicy）
  dedup.ts              - 消息去重
  media-utils.ts        - 媒体处理工具
  message-utils.ts      - 消息解析工具
  logger-context.ts     - 日志上下文
  utils.ts              - 通用工具函数

代码质量

• TypeScript: 严格模式
• Zod: 配置校验
• 安全: SHA256 签名验证 + crypto.timingSafeEqual
• 可靠性: Token 自动缓存/刷新、指数退避重试、消息去重

许可

MIT