OpenClaw 使用教程

Appearance

自定义渠道（Channel Plugin）开发与对接 ​

目标：当 OpenClaw 没有现成渠道（例如钉钉/企业微信等）时，你可以开发一个 自定义渠道插件，让它像 Telegram/飞书一样成为一等公民：可配置账号、可路由、可跑配对与权限策略。

1) 什么时候该写“自定义渠道插件”？ ​

  • 你希望：
    • openclaw channels add 能出现你的渠道
    • channels.<id> 有完整配置、状态检查、日志、能力探测
    • 统一的路由/配对/群策略

如果你只是想“外部系统触发 OpenClaw 一次运行”，那更适合用 Hooks/Webhook（成本低、快）。

2) 标准开发流程（框架图） ​

mermaid
flowchart TD
  A[需求与范围
- 私聊/群聊?
- 是否需要媒体?
- 是否需要@提及/线程?
- 账号/多租户?] --> B[选择接入模式
- 原生渠道插件
- Webhook→Hooks桥接]
  B --> C[协议与安全设计
- 入站验签/重放保护
- 出站鉴权
- 速率限制/退避]
  C --> D[定义数据模型
- accountId
- peer(用户/群)
- message(文本/媒体)
- 事件类型]
  D --> E[实现插件
- config.listAccountIds
- config.resolveAccount
- inbound(事件接收)
- outbound.sendText]
  E --> F[本地联调
- sandbox/测试群
- logs追踪
- 断线重连]
  F --> G[可观测性
- status探测
- 错误分级
- 指标/告警]
  G --> H[发布与运维
- 插件打包
- 安装/启用
- 配置与升级]

3) 参考架构图（推荐实现） ​

mermaid
flowchart LR
  subgraph External[外部聊天平台]
    U[用户] --> P[平台
(钉钉/自研IM/...) ]
  end

  subgraph Ingress[入站层]
    W[Webhook/WS
事件入口] --> V[校验
签名/时间戳/重放]
  end

  subgraph OpenClaw[OpenClaw]
    G[Gateway
(plugins+channels)] --> S[Session/Router]
    S --> A[Agent]
    A --> T[Tools
(web/browser/nodes/...)]
    A --> M[Memory]
  end

  subgraph Egress[出站层]
    X[平台发送API] --> P
  end

  P --> W
  V --> G
  G --> X

说明：

  • 入站与出站建议都在插件内封装，减少“桥接脚本散落在外”的维护成本。
  • 也可以拆为：平台→Worker桥接→Gateway hooks，但那是更快的 MVP，不是“原生渠道”。

4) 最小可用渠道插件（代码骨架） ​

下面是一个“只实现出站文本”的最小骨架（示意）。实际你需要补：入站事件接收、鉴权、重连、群/私聊映射等。

ts
// my-channel/index.ts

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "Example custom channel.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? { accountId },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // TODO: 调用你的平台发送API
      return { ok: true };
    },
  },
};

export default function register(api) {
  api.registerChannel({ plugin });
}

5) 插件打包/安装/启用（要点） ​

  • 插件通过 openclaw.plugin.json（manifest）描述 id、配置 schema、UI hints 等。
  • 放到以下位置之一即可被发现：
    • <workspace>/.openclaw/extensions/*/index.ts
    • ~/.openclaw/extensions/*/index.ts
    • 或通过 plugins.load.paths 加载
  • 配置完成后重启网关生效。

6) 用“Webhook→Hooks”作为过渡（建议） ​

很多渠道先用桥接（Worker → /hooks/agent）跑通闭环，确认价值后再升级成原生渠道插件。

参考 ​

  • 插件/扩展开发：OpenClaw docs → tools/plugin
  • Webhook/Hooks：OpenClaw docs → automation/webhook