# OpenClaw Channel 插件开发指南

> 基于钉钉 Channel 插件（`src/channels/dingtalk.ts`）的完整开发经验总结。
> 开发新 Channel 时，本文档是你的第一参考。

---

## 一、整体架构

每个 OpenClaw 实例是一个独立 Docker 容器（`hailin168/openclaw-bridge:latest`）。
容器内有三个进程，由 supervisord 管理：

```
容器
├── openclaw gateway      端口 18789 (内部)  — 核心 AI Agent 进程
├── it0-bridge            端口 3000  (对外)  — IT0 管理 REST API
└── dingtalk-channel      无对外端口         — 第三方 Channel 进程（可选）
```

**Channel 插件的职责：**
1. 连接第三方平台（接收用户消息）
2. 转发给 OpenClaw Gateway（通过 WebSocket RPC）
3. 将 OpenClaw 响应回发给用户

Channel 插件不需要任何对外端口，完全依赖出向连接。

---

## 二、OpenClaw Gateway 协议 (Protocol v3)

> ⚠️ 这是最重要的部分。协议细节必须准确，否则运行时全部失败，TypeScript 编译器无法检测。

### 2.1 Wire 帧格式

```typescript
// 请求帧（Client → Gateway）
interface ReqFrame {
  type: 'req';           // 必须是字面量 'req'
  id: string;            // 唯一请求 ID（自增字符串即可）
  method: string;        // RPC 方法名
  params?: unknown;      // 方法参数
  idempotencyKey?: string; // 可选，幂等键
}

// 响应帧（Gateway → Client）
interface ResFrame {
  type: 'res';
  id: string;            // 对应请求的 id
  ok: boolean;           // 成功/失败标志
  payload?: unknown;     // 成功时的响应数据
  error?: {
    code: string;
    message: string;
    retryable?: boolean;
    retryAfterMs?: number;
  };
}

// 事件帧（Gateway → Client，主动推送）
interface EventFrame {
  type: 'event';
  event: string;         // 事件名
  payload?: unknown;
  seq?: number;          // 单调递增序号
}
```

### 2.2 连接握手（必须完成，否则所有 RPC 都会被拒绝）

OpenClaw 使用 **Challenge-Response + Ed25519 签名** 认证。流程：

```
Client ──────── WebSocket Connect ──────────────────→ Gateway
Gateway ──── event: "connect.challenge" { nonce } ──→ Client
Client ──── req: "connect" { auth.token, device } ──→ Gateway
Gateway ─── res: "connect" { ok: true } ────────────→ Client
                  ↑ 这之后才能发送任何 RPC 请求
```

关键实现细节：
```typescript
// 1. 用 Node.js 内置 crypto 生成临时 Ed25519 密钥对（每次连接生成新的）
const keyPair = crypto.generateKeyPairSync('ed25519');

// 2. 用私钥对 nonce (hex string → Buffer) 签名
const nonceBuffer = Buffer.from(nonce, 'hex');
const signature = crypto.sign(null, nonceBuffer, keyPair.privateKey);

// 3. 公钥导出为 DER 格式 base64
const pubKeyDer = keyPair.publicKey.export({ type: 'spki', format: 'der' });

// 4. 发送 connect 请求
{
  type: 'req',
  id: '__connect__',
  method: 'connect',
  params: {
    minProtocol: 3, maxProtocol: 3,
    client: { id: deviceId, version: '1.0.0', platform: 'node', mode: 'channel' },
    role: 'operator',
    scopes: ['operator.read', 'operator.write'],
    auth: { token: OPENCLAW_GATEWAY_TOKEN },  // 环境变量注入的 token
    device: {
      id: deviceId,
      publicKey: pubKeyDer.toString('base64'),
      signature: signature.toString('base64'),
      signedAt: Date.now(),
    }
  }
}
```

握手超时：Gateway 有 10s 超时，客户端应设 12s 安全超时。

### 2.3 关键 RPC 方法（经官方源码验证）

| 功能 | 方法名 | 关键参数 |
|------|--------|---------|
| 发消息给 Agent | `chat.send` | `{ sessionKey, message, timeoutSeconds }` |
| 列出会话 | `sessions.list` | `{ limit, kinds?, activeMinutes? }` |
| 获取会话历史 | `sessions.history` | `{ sessionKey, messageLimit }` |
| 中止当前任务 | `chat.abort` | `{ sessionKey }` |
| 网关状态 | `gateway.status` | 无 |
| 健康检查 | `gateway.health` | 无 |

> ❌ **以下方法不存在，不要使用：**
> - `agent.run` — 根本不存在
> - `metrics.get` — 不存在，用 `gateway.status` 替代

### 2.4 Session Key 格式

格式：`"type:agentName:sessionName"`

```
agent:main:main           — 默认主 session
agent:main:dt-{userId}    — 钉钉用户专属 session（每用户独立）
agent:main:tg-{chatId}    — Telegram chat 专属 session
agent:main:wechat-{openId}  — 微信用户专属 session
```

每个 OpenClaw 实例默认只有一个 agent "main"。
Session name 部分可以自定义，Gateway 会自动创建不存在的 session。

### 2.5 `chat.send` 的响应结构

```typescript
// payload 结构
{
  runId: string;
  status: 'started' | 'in_flight' | 'ok' | 'timeout';
  reply?: string;   // 当 timeoutSeconds > 0 且 status=ok 时有值
  error?: string;   // 当 status=timeout 时有值
}

// 从 payload 提取回复文本的正确方式：
const payload = result as { status: string; reply?: string };
const replyText = payload.reply ?? '（任务已提交，正在处理）';
```

---

## 三、钉钉 Channel 实现要点

### 3.1 使用 Stream 模式（无需公网 IP）

钉钉官方提供两种接入方式：
- **HTTP 回调模式**：需要公网 IP + 备案，不适合容器部署
- **Stream 模式**：主动连接钉钉服务器，容器内部署完美适配 ✓

Stream 模式连接流程：
```
1. POST https://api.dingtalk.com/v1.0/oauth2/accessToken
   → { accessToken, expireIn: 7200 }

2. POST https://api.dingtalk.com/v1.0/gateway/connections/open
   Headers: x-acs-dingtalk-access-token: {accessToken}
   Body: { clientId, clientSecret, subscriptions: [{type:'CALLBACK', topic:'/v1.0/im/bot/messages/get'}] }
   → { endpoint, ticket }

3. WSS connect: {endpoint}?ticket={ticket}
   → 保持长连接，接收消息
```

### 3.2 消息帧格式

```typescript
// 服务器推送的消息帧
{
  type: 'CALLBACK',   // or 'PING', 'EVENT', 'SYSTEM'
  headers: { topic: '/v1.0/im/bot/messages/get', ... },
  data: string   // JSON string
}

// data 解析后的 bot 消息结构
{
  senderStaffId: string,       // 发送者工号
  sessionWebhook: string,      // 用于回复的 Webhook URL（有过期时间！）
  sessionWebhookExpiredTime: number,  // 毫秒时间戳
  text: { content: string },   // 消息文本
  conversationId: string,      // 群/单聊会话 ID
  msgId: string                // 消息唯一 ID（用于去重）
}

// 必须在收到消息后 1.5 秒内 ACK，否则钉钉会重发
ws.send(JSON.stringify({ code: 200, headers: frame.headers, message: 'OK', data: '' }));
```

### 3.3 已验证的钉钉 API 限制

| 限制 | 数值 |
|------|------|
| Access Token 有效期 | 7200 秒（2小时）|
| 单条消息字符上限 | 5000 字符 |
| ACK 超时 | 1.5 秒 |
| sessionWebhook 有效期 | 约 24 小时（群消息更短）|

### 3.4 回复钉钉消息（通过 sessionWebhook）

```typescript
function sendWebhook(webhook: string, content: string): void {
  const url = new URL(webhook);
  const body = JSON.stringify({ msgtype: 'text', text: { content } });
  // 用 Node.js 内置 https 模块，无外部依赖
  const req = https.request({ hostname: url.hostname, path: url.pathname + url.search, method: 'POST', ... });
}
```

超过 4800 字符需分块发送，每块间隔 200ms 保证顺序。

---

## 四、生产级鲁棒性模式（从错误中总结）

### 4.1 Token 自动刷新 + 防竞态

```typescript
class TokenManager {
  private refreshPromise: Promise<string> | null = null; // 互斥锁

  async get(): Promise<string> {
    if (Date.now() < this.expiresAt - BUFFER_MS) return this.token;
    // 关键：多个并发调用只触发一次刷新
    if (this.refreshPromise) return this.refreshPromise;
    this.refreshPromise = this.doRefresh().finally(() => { this.refreshPromise = null; });
    return this.refreshPromise;
  }
}
```

### 4.2 消息去重（O(1) + TTL）

```typescript
class MsgDedup {
  private readonly seen = new Map<string, number>(); // msgId → timestamp

  has(msgId: string): boolean {
    const t = this.seen.get(msgId);
    if (t === undefined) return false;
    if (Date.now() - t > this.ttlMs) { this.seen.delete(msgId); return false; }
    return true;
  }
}
// ❌ 不要用 Array.includes() — O(n)，5000条时慢到不可用
```

### 4.3 每用户串行队列 + 深度上限

```typescript
class UserQueue {
  private readonly tails  = new Map<string, Promise<void>>();
  private readonly depths = new Map<string, number>();

  enqueue(userId: string, task: () => Promise<void>): boolean {
    if ((this.depths.get(userId) ?? 0) >= MAX_DEPTH) return false; // 拒绝
    // Promise 链串行执行，不同用户并发互不影响
    ...
  }
}
// MAX_DEPTH = 5：用户排队超5条立即告知，防内存泄漏
```

### 4.4 WebSocket 断线指数退避重连

```typescript
private reconnectDelay = 2_000;

private scheduleReconnect(): void {
  setTimeout(() => this.start(), this.reconnectDelay);
  this.reconnectDelay = Math.min(this.reconnectDelay * 2, 60_000);
  // 成功连接后在 ws.on('open') 里重置：this.reconnectDelay = 2_000;
}
```

### 4.5 OpenClaw Gateway 重连防多开

```typescript
private setupAutoReconnect(): void {
  const check = setInterval(() => {
    if (this.client.isConnected() || this.reconnecting) return; // 原子守门
    this.reconnecting = true;
    this.client = new OpenClawClient(...); // 先替换，再重连
    const attempt = async () => {
      try { await this.client.connect(); this.reconnecting = false; }
      catch { setTimeout(attempt, delay *= 1.5); }  // 递归重试，不叠加
    };
    attempt();
  }, 10_000);
  check.unref(); // 不阻止进程退出
}
// ❌ 不要在 catch 里直接重调 this.connect()，会叠加多个重连 loop
```

### 4.6 优雅关闭

```typescript
process.once('SIGTERM', () => {
  stream.stop();
  tokenMgr.destroy(); // 清除 setTimeout 防止内存泄漏
  setTimeout(() => process.exit(0), 3_000); // 3秒内完成清理
});
```

---

## 五、supervisord 集成模式

容器内可选 Channel 的标准模式：

```ini
[program:dingtalk-channel]
command=/app/bridge/start-dingtalk.sh   ; 包装脚本，未配置时 exit 0
autostart=true
autorestart=unexpected   ; ← 关键：不是 true
exitcodes=0              ; ← 关键：exit 0 = 正常退出，不重启
startretries=5
startsecs=10
```

包装脚本模板 (`start-xxx.sh`)：
```bash
#!/bin/sh
if [ -z "$XXX_CLIENT_ID" ]; then
  echo "[xxx] Not configured — channel disabled."
  exit 0      # supervisord 看到 exit 0 → EXITED，不重启
fi
exec node /app/bridge/dist/channels/xxx.js
```

---

## 六、开发新 Channel 的步骤

### Step 1: 确认平台接入机制

| 问题 | 必须确认 |
|------|---------|
| 是否需要公网 IP？ | 需要 → 考虑反向代理；不需要（WebSocket Stream）→ 最佳 |
| 是否有官方 SDK？ | 评估：SDK 稳定性 vs 自实现控制力 |
| Token 有效期多长？ | 决定刷新策略 |
| 消息字符上限？ | 决定分块策略 |
| 是否有消息重投？ | 决定去重策略 |
| ACK 超时多长？ | 必须在超时前 ACK，将 AI 处理异步化 |

### Step 2: 创建文件

```
packages/openclaw-bridge/src/channels/xxx.ts     — 主进程
packages/openclaw-bridge/start-xxx.sh             — 启动包装脚本
```

### Step 3: 复用现有基础设施

```typescript
import { OpenClawClient } from '../openclaw-client'; // ✓ 直接复用，Protocol v3 已正确实现
// 复用以下 class：TokenManager、UserQueue、MsgDedup、RateLimiter
// 只需自己实现：平台 WS 连接 + 消息收发逻辑
```

### Step 4: 向 OpenClaw 发消息的标准代码

```typescript
const result = await ocClient.rpc('chat.send', {
  sessionKey: `agent:main:${PLATFORM_PREFIX}-${userId}`,  // 确保跨平台 session 不冲突
  message: userText,
  timeoutSeconds: 25,
}, 30_000);

const payload = result as { status: string; reply?: string; error?: string };
if (payload.status === 'ok' && payload.reply) {
  await replyToUser(payload.reply);
} else if (payload.status === 'timeout') {
  await replyToUser('处理超时，请稍后重试。');
}
```

### Step 5: 更新 supervisord.conf 和 Dockerfile

在 `supervisord.conf` 末尾追加新 program 块（参考钉钉模板）。
在 `Dockerfile` 中 COPY 新的启动脚本并 chmod +x。

### Step 6: 更新 agent-instance-deploy.service.ts

在 `runDeploy` 的 `envParts` 数组中追加新平台的环境变量：
```typescript
if (xxxClientId) envParts.push(`-e XXX_CLIENT_ID=${xxxClientId}`);
```

### Step 7: 更新 system-prompt-builder.ts

教 iAgent 如何引导用户完成该 Channel 的绑定配置步骤。

---

## 七、各平台接入难度预估

| 平台 | 接入方式 | 需要公网IP | 预估难度 | 备注 |
|------|---------|-----------|---------|------|
| **钉钉** | Stream SDK (WSS) | 否 | ⭐⭐ | 已实现，可直接参考 |
| **飞书（Lark）** | 事件订阅 WebSocket | 否 | ⭐⭐ | 官方有 Stream SDK，与钉钉结构类似 |
| **Telegram** | Long Polling / Webhook | 否（polling）/ 是（webhook）| ⭐ | 最简单，Bot API 文档极好 |
| **WhatsApp** | Cloud API Webhook | 是 | ⭐⭐⭐ | 需 Meta 审核，有 webhook 验证 |
| **Slack** | Socket Mode | 否 | ⭐⭐ | Socket Mode 无需公网，文档好 |
| **Discord** | Gateway WebSocket | 否 | ⭐⭐ | 官方 gateway 长连接，文档清晰 |
| **微信** | 服务号 / 企业微信 | 是（公网 + 备案）| ⭐⭐⭐⭐ | 最麻烦，需域名验证 |
| **Line** | Messaging API Webhook | 是 | ⭐⭐⭐ | 与 WhatsApp 类似 |

**优先推荐顺序**（按落地难度由易到难）：
1. Telegram — 最快，1天内可完成
2. 飞书 — 国内办公场景，与钉钉代码高度相似
3. Slack — 国际企业场景
4. Discord — 开发者/社区场景

---

## 八、经验教训（避坑清单）

1. **永远先读官方源码，不要猜 API 方法名**
   - 本项目曾把 `chat.send` 猜成 `agent.run`，`gateway.status` 猜成 `metrics.get`，TypeScript 编译通过但 runtime 全部失败
   - 查源码路径：github.com/openclaw/openclaw 的 `src/gateway/server-methods/`

2. **Channel token 必须有自动续期机制**
   - 钉钉 Access Token 2小时过期，不续期则服务必然中断
   - 在 `get()` 中加 Promise 互斥锁，防止并发双重刷新

3. **永远在收到消息后立即 ACK，再异步处理 AI**
   - 钉钉 ACK 超时 1.5 秒，AI 响应可能需要 30 秒
   - 先 `ws.send(ACK)`，再 `queue.enqueue()` 异步处理

4. **消息去重用 Map，不用 Array**
   - `Array.includes()` 是 O(n)，5000条消息时每次查找慢 5ms
   - `Map.get()` 是 O(1)，加 TTL 可精确控制内存

5. **supervisord 的 autorestart 要用 unexpected，不是 true**
   - `autorestart=true` + 未配置时 exit 0 → 无限重启循环
   - `autorestart=unexpected` + `exitcodes=0` → 正常退出不重启

6. **每用户消息队列必须有深度上限**
   - 用户刷消息时，无限队列会耗尽内存
   - 建议上限 5 条，超出告知用户"请等待"

7. **OpenClaw 重连不要用嵌套 setInterval + async**
   - 多个 interval tick 可能同时触发多个重连 goroutine
   - 用 flag 原子保护 + 单一递归 `attempt()` 函数

8. **回复消息要检查 webhook 过期时间**
   - 某些平台的 webhook 有效期很短（几分钟到几小时）
   - AI 处理完后要先检查 `webhookExpiredTime`，过期则不发

9. **容器内没有 curl，用 wget 或 Node.js https 模块**
   - `hailin168/openclaw-bridge` 镜像内无 curl
   - `wget -q -O- --post-data=...` 是 iAgent 内部调用 API 的正确方式