@metelix/openclaw-chatwork

v0.1.6

Published

2 months ago

OpenClaw channel plugin for Chatwork (Webhook + API)

0High
0Medium
0Low

raymeibergen

openclaw openclaw-plugin chatwork webhook channel

OpenClaw Chatwork チャンネルプラグイン

Chatwork の Webhook（受信） と Chatwork API（送信） を組み合わせて、OpenClaw ゲートウェイとルームを連携するチャンネルプラグインです。npm では @metelix/openclaw-chatwork として公開します（OpenClaw のコアとは別パッケージです）。構成イメージは Microsoft Teams チャンネルのドキュメント（バンドル／別パッケージのプラグインとしてゲートウェイに載せる）に近いです。

前提

OpenClaw ゲートウェイ（推奨: openclaw peer 依存と同程度のバージョン）
Chatwork の API トークン（送信に使用）
受信先として公開可能な HTTPS URL（Webhook 用）
Node.js は OpenClaw 側の要件に合わせる（プラグイン開発時は Node 22 系推奨）

OpenClaw のバージョン: peerDependencies は openclaw >= 2026.3.24 です。v0.1.1 以降はゲートウェイが 2026.3.x 系（例: 2026.3.28-chimera.7）でも、plugin-sdk/channel-core ではなく plugin-sdk/core および既存の公開バレル経由で読み込むよう修正してあります。v0.1.0 は 2026.4 系の export 前提のため、2026.3 ではロードに失敗することがあります。

アーキテクチャ（Teams ドキュメントとの対応）

| Microsoft Teams（ドキュメント上のイメージ） | 本プラグイン（Chatwork） | |-----------------------------------------------|---------------------------| | Bot Framework のメッセージングエンドポイント | ゲートウェイ上の registerHttpRoute（既定: /plugins/chatwork/webhook） | | channels.msteams | channels.chatwork | | 別 npm パッケージ @openclaw/msteams | 本リポジトリ（@metelix/openclaw-chatwork） |

受信したイベントは OpenClaw の共通ランタイム（recordInboundSession → 返信ディスパッチ）に渡します。実装の考え方は Building Channel Plugins および Plugins を参照してください。

インストール

Plugins に従い、ローカル開発ではリンクインストールが便利です。

# リポジトリでビルド（リンクインストール時は毎回または変更後に実行）
npm install
npm run build

# OpenClaw 側（例）
openclaw plugins install -l /path/to/openclaw-chatwork

レジストリから入れる場合（npm の @metelix/openclaw-chatwork が公開されている環境）:

openclaw plugins install @metelix/openclaw-chatwork

インストール後は ゲートウェイを再起動してください（openclaw gateway restart 等）。

Chatwork 側の設定

API トークン
Chatwork の API 設定からトークンを発行し、後述の channels.chatwork.apiToken に設定します。送信は POST https://api.chatwork.com/v2/rooms/{room_id}/messages（X-ChatWorkToken）を使用します。
Webhook
Webhook について（公式）に従い、Webhook 管理画面で URL を登録します。
- URL 例: https://<あなたのゲートウェイホスト>/plugins/chatwork/webhook
  （channels.chatwork.webhookPath で変更可能）
- 少なくとも message_created を有効にするとルーム投稿を受け取れます。
- メンションだけ反応させたい場合は mention_to_me も利用できます。
署名検証（本番推奨）
Webhook 編集画面の 署名用トークン（Base64） を webhookSignatureToken に設定すると、x-chatworkwebhooksignature による HMAC-SHA256 検証を行います。未設定の場合は検証をスキップします（開発専用）。

公式の注意: Webhook リクエストには 原則 HTTP 200 を返す必要があり、失敗が続くと設定が無効化される場合があります。本プラグインは Chatwork の推奨に合わせ、検証失敗や不正 JSON でも 200 + 本文 ok で応答しつつ、処理はログに残します。

OpenClaw 設定例

~/.openclaw/openclaw.json などに channels.chatwork とプラグインの有効化を追加します。

{
  channels: {
    chatwork: {
      enabled: true,
      apiToken: "<Chatwork API トークン>",
      webhookSignatureToken: "<Webhook 署名用トークン（Base64）>",
      webhookPath: "/plugins/chatwork/webhook",
      botAccountId: 1234567,
      requireMention: true,
      allowFrom: ["1111111", "2222222"],
      roomAllowlist: [987654321],
    },
  },
  plugins: {
    enabled: true,
    entries: {
      chatwork: { enabled: true },
    },
  },
}

plugins.entries のキーはマニフェストの openclaw.plugin.json の id（chatwork）と揃えてください。

設定リファレンス（`channels.chatwork`）

| キー | 型 | 説明 | |------|-----|------| | enabled | boolean | false でチャンネル無効 | | apiToken | string または SecretRef オブジェクト（source / provider / id） | Chatwork API トークン（必須に近い）。OpenClaw の secrets（例: exec + SSM）と併用可（v0.1.2+） | | webhookSignatureToken | string または SecretRef | Webhook 署名検証用（本番推奨）。同上（v0.1.2+） | | webhookPath | string | 受信パス。既定 /plugins/chatwork/webhook | | botAccountId | number | ボット自身の account_id。requireMention と併用 | | requireMention | boolean | message_created でメンション必須か。既定 true 相当 | | allowFrom | string/number の配列 | 許可する送信者 account_id。空なら全員 | | roomAllowlist | number の配列 | 許可する room_id。空なら全ルーム | | maxBodyBytes | number | Webhook 本文上限（バイト） |

メンション・トリガー条件

mention_to_me: 常にエージェント処理の対象（設定で除外されなければ）。
message_created / message_updated:
- requireMention がオフなら、送信者・ルームの許可を通過すれば処理。
- requireMention がオンのときは、本文に [toall]（大小無視）または [to:<botAccountId>]（botAccountId 必須）が含まれる場合のみ処理します。

メッセージツールの `target`

ルーム ID（数値）または room:<roomId> 形式で指定します（src/channel.ts の messaging 参照）。

動作の流れ

Chatwork が Webhook URL へ POST（JSON）。
プラグインが署名（設定時）・ルーム・送信者・メンション条件を評価。
resolveAgentRoute でセッションキーを決定し、recordInboundSession の後に返信パイプラインを実行。
返信テキストは Chatwork API で該当ルームに投稿。

エージェント処理は 先に HTTP 200 を返したあと バックグラウンドで走るため、Chatwork の「10 秒以内に応答」に配慮しています。処理が重い場合は別途キュー／ワーカー化を検討してください。

制限事項（v0.1.x）

主に テキスト。添付ファイルの受信・送信、引用スレッドの完全再現は未対応。
アカウントは 単一デフォルト（DEFAULT_ACCOUNT_ID）想定。
公式の OpenClaw ドキュメント docs.openclaw.ai/channels/chatwork は未整備のため、package.json の docsPath は将来用のプレースホルダです。

開発

npm install
npm run check   # 型チェック
npm run build   # dist に出力

参考リンク

メンテナ向け: npm 公開

package.json の version を上げ、コミットする。
GitHub で Release を作成する（または Actions の Publish npm を手動実行）。
リポジトリの Secrets に NPM_TOKEN（Automation トークンなど、@metelix スコープへの publish 権限付き）を登録する。
prepublishOnly で npm run build が走るため、公開 tarball には常に dist/ が含まれます。

ライセンス

MIT（LICENSE を参照）。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme