WeChat OpenClaw プラグイン（Relay Spine）

Library
WeChat OpenClaw プラグイン（Relay Spine）

WeChat OpenClaw プラグイン（Relay Spine）

OpenClaw エージェント基盤向けの WeChat チャネルブリッジ。QR 認証による長期双方向ソケット接続（AGP/WebSocket）と、WeChat サービス号／企業微信風の署名付き HTTP webhook を同梱し、外部の WeChat メッセージを OpenClaw の会話・ルーティング・ツール呼び出し・ストリーミング出力にシームレスに取り込むことを目的としています。TypeScript で実装され、認証フロー、ランタイムサービス、トランスポートアダプタを分離した設計です。

https://github.com/CzsGit/wechat-openclaw-plugin

概要

这是一个面向 OpenClaw 的微信通路插件（Relay Spine）。本プロジェクトは二つの主要な接続モードを提供します。ひとつはユーザーが QR コードをスキャンしてブラウザ経由で認証し、AGP（Agent Gateway Protocol）に基づく WebSocket セッションを確立することで双方向のインタラクティブチャットを実現する方式。もうひとつは、WeChat サービス号や企業微信のようなサーバー側の受動的な応答を可能にする署名付き HTTP webhook 方式です。コアな狙いは、これら外部メッセージを OpenClaw Agent の会話管理・ルーティング・ストリーミング出力・ツール呼び出しの仕組みに取り込んで再利用する点にあります。実装は TypeScript で、認証・アイデンティティ管理、ルーティング、トランスポートアダプタが src/ 配下に整理されています。

GitHub

リポジトリの統計情報

  • スター数: 8
  • フォーク数: 5
  • ウォッチャー数: 8
  • コミット数: 2
  • ファイル数: 9
  • メインの言語: TypeScript

主な特徴

  • QR 認証を用いた長期の双方向 WebSocket セッション（AGP ベース）でインタラクティブなチャットを実現
  • WeChat 風の署名付き HTTP webhook による受動的なメッセージ受信と返信に対応
  • OpenClaw Agent エコシステムに自然に統合できるルーティング・会話ハンドリングを提供
  • TypeScript で実装され、トランスポート／認証／ルーティングの責務を分離したモジュール構成

技術的なポイント

このプラグインは「外部チャネル → OpenClaw Agent」の橋渡しをするためのアダプタ層として設計されています。主な技術的ポイントは以下の通りです。

  • 接続モードの二本立て

    • QR 認証 + AGP WebSocket: ブラウザを介した QR スキャンでチャネル資格情報（cookie やトークン）を取得し、それを用いて長期 WebSocket セッションを張ることで、リアルタイムに双方向メッセージの送受信を行います。これによりユーザーとのインタラクティブな会話やストリーミング応答が可能になります。
    • HTTP webhook: サーバー側からの受動的なイベント（メッセージ受信、イベント通知など）を受け取るためのエンドポイントを提供します。WeChat 互換の署名検証やパラメータ検証を行い、安全にメッセージを OpenClaw 側に渡します。

  • アイデンティティと資格情報管理

    • QR フローで取得したクレデンシャルやセッション情報を永続化し、再接続やセッション復旧に備えます。これによりチャネルのライフサイクル管理を OpenClaw エージェントに紐づけて扱えます。
    • Webhook モードでは受信側の署名検証（トークン／鍵ベース）、暗号化／復号（必要に応じて）を行い、送信元の真正性とデータの整合性を確保します。

  • ルーティングとメッセージマッピング

    • 外部メッセージのペイロードを OpenClaw の内部フォーマット（イベント・メッセージオブジェクト）に変換し、適切な Agent インスタンスや会話コンテキストへルーティングします。
    • セッション単位の会話状態を維持し、既存の OpenClaw のセッションやツール呼び出し機能をそのまま流用できるようマッピングロジックを提供します。

  • 設計と拡張性

    • src/ 配下で runtime services、identity flows、routing、transport adapters を分離。これにより新しいチャネル（他の IM プロバイダ）や認証フローを追加する際に、既存コンポーネントを再利用できます。
    • ルートのエントリポイント（index.ts）を薄く保ち、プラグインロード時の初期化や依存注入ポイントを限定しているため、OpenClaw 側のプラグイン API と組み合わせやすくなっています。

  • セキュリティと運用面

    • Webhook の署名検証や HTTPS を前提とした設計、長期セッションの再接続／ライフサイクル管理など運用上の考慮が施されています。TypeScript による型安全性も保たれているため、実装ミスや型エラーを事前に防げます。

これらの機能により、従来は個別に実装していた WeChat のリアルタイム接続と Webhook ベースの受信を一つのパッケージで扱え、OpenClaw の会話インフラストラクチャを活用して SDK レベルで高度な対話フローやツール連携を実現できます。

プロジェクトの構成

主要なファイルとディレクトリ：

  • .gitignore: file
  • README.md: file
  • index.ts: file
  • openclaw.plugin.json: file
  • package-lock.json: file

…他 4 ファイル

ソースは src/ 配下に runtime、identity、routing、transports（アダプタ）などの責務別モジュールが配置される想定で、index.ts が薄いエントリポイントとしてプラグイン登録や初期化を担います。openclaw.plugin.json は OpenClaw 側でプラグインを認識するためのメタ情報を提供します。

まとめ

QR ベースの長期接続と署名付き webhook を統合し、OpenClaw エコシステムへ WeChat メッセージを自然に取り込む実用的なブリッジ実装です。

リポジトリ情報：

  • 名前: wechat-openclaw-plugin
  • 説明: 这是一个面向 OpenClaw 的微信通路插件，提供两条接入能力：一条是 基于扫码登录和 AGP WebSocket 的双向消息通道，另一条是面向微信服 务号/企业微信风格回调的 HTTP webhook 通道。项目核心目标是把外部 微信消息接入 OpenClaw Agent 体系，复用现有会话、路由、流式输出 和工具调用能力。
  • スター数: 8
  • 言語: TypeScript
  • URL: https://github.com/CzsGit/wechat-openclaw-plugin
  • オーナー: CzsGit
  • アバター: https://avatars.githubusercontent.com/u/16255872?v=4