Nextcloud Talk

Talk Bot Webhook プロトコルを介した Nextcloud Talk 連携。セルフホスト、フェデレーション対応、E2E 対応で、Matrix や Mattermost と並ぶ、もう一つの主権的コミュニケーションの選択肢です。

エージェントと対話できるユーザー

受信側の送信者は、バインドされたエージェントに対して解決されたピアセットに照らして制御されます。これはエージェントが所属する peer_groups 設定から導出されます。照合では先頭の @ を取り除き、チャネルのネイティブな送信者識別子に対して大文字・小文字を区別せずに行われます。空のセットはすべてを拒否し、"*" を含むセットはすべてを受け入れます。それ以外の場合は、リストに記載された外部ピア（およびピアエージェント）のみが受け入れられます。これはゲートウェイのペアリング（gateway.require_pairing）とは別物であり、ペアリングはチャットチャネルの送信者ではなく HTTP/WebSocket クライアントを認証します。

nextcloud のピアグループでは、channel を nextcloud に設定し、許可する送信者を external_peers に列挙し（nextcloud の場合は Nextcloud のアクター ID。["*"] は誰でも受け入れます）、エージェント間ディスパッチ用にピアの agents を任意で指定し、ignore ブロックリスト、output_modality（mirror、voice、または text）を指定します。フィールドのリファレンスについては Peer Groups を参照してください。

この設定の場所:

この統合の機能

• ゲートウェイ上の POST /nextcloud-talk/<alias> を介して受信 Talk イベントを受け取ります（ベアの /nextcloud-talk も非推奨のフォールバックとして引き続き動作します）
• インストール済みボットのシークレットを使用して webhook 署名 (HMAC-SHA256) を必須化し、検証します
• 署名付き Nextcloud Talk Bot API を介して Talk ルームに返信を送信します

前提条件

• Nextcloud server 27.1 以降、かつ Talk 17.1 以降。 これは推奨ではなく厳格な最小要件です。この統合が返信の送信に使用する署名付き Talk Bot API は Talk 17.1 で導入されたため、以下の occ talk:bot:install はそれ以前のリリースでは利用できません。

• Bot がインストールされました。webhook と response の両方の機能が有効になっており、Nextcloud がルームメッセージを ZeroClaw に配信し、ZeroClaw が返信を送信できるようになります:

  sudo -u www-data php occ talk:bot:install \
    -f webhook -f response \
    zeroclaw-bot '<shared-secret>' \
    'https://<your-public-url>/nextcloud-talk/<alias>'
  

• そのインストールから取得する Bot secret です。Nextcloud は、Bot ごとに 1 つの 共有シークレットを発行し、これは受信 Webhook 署名の検証と送信 Bot API 応答の署名の両方に使用されます。これを webhook_secret として設定します。これが正規の設定です。bot_token は 同じ値の非推奨のエイリアス です。両方が設定されている場合、それらは同一でなければなりません。異なる送信シークレットを保持することはできません。競合する空でない値は、どちらか一方を優先して 暗黙的に 解決されることはありません。競合はログに記録され、エイリアスはシークレットなしとして解決されるため、チャネルは未設定の場合とまったく同じように動作します。すなわち、受信は 401、送信は行われません。

• 外部からアクセス可能なゲートウェイ: セルフホストの場合のトンネルオプションについては Setup → Container を参照してください

シークレットが欠落している場合、両方向ともクローズ状態でフェイルし、認証なしのモードは存在しません:

• インバウンド: 署名検証は必須です。解決済みのシークレットがない場合、Webhook エンドポイントは 401 を返し、エージェントには決して到達しません。未検証の Webhook を受け入れる「パブリック」モードはありません。
• アウトバウンド: リクエストは一切送信されないため、設定ミスによって署名なしまたは誤って署名されたリクエストがネットワークに送出されることはありません。

アップグレードは破壊的変更です。 以前はシークレットなしで実行されていたデプロイメントは Webhook を受け付けていましたが、現在はそれらすべてを 401 で拒否します。アップグレードする前に occ talk:bot:install でボットをインストールし、そのシークレットを webhook_secret として設定してください。そうしないと、受信メッセージの処理が停止します。

設定

zeroclaw config set channels.nextcloud_talk.<alias>.app_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__nextcloud_talk__<alias>__app_token=

zeroclaw config set channels.nextcloud_talk.<alias>.base_url <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__base_url=

zeroclaw config set channels.nextcloud_talk.<alias>.bot_name <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__bot_name=

zeroclaw config set channels.nextcloud_talk.<alias>.bot_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__nextcloud_talk__<alias>__bot_token=

zeroclaw config set channels.nextcloud_talk.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__draft_update_interval_ms=

zeroclaw config set channels.nextcloud_talk.<alias>.excluded_tools <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__excluded_tools=

zeroclaw config set channels.nextcloud_talk.<alias>.proxy_url <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__proxy_url=

zeroclaw config set channels.nextcloud_talk.<alias>.stream_mode <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__stream_mode=

zeroclaw config set channels.nextcloud_talk.<alias>.webhook_secret    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__nextcloud_talk__<alias>__webhook_secret=

このチャンネルは default エイリアスから読み込まれます。任意の設定箇所で設定してください:

webhook_secret は、汎用的な環境変数オーバーライド ZEROCLAW_channels__nextcloud_talk__default__webhook_secret を使って実行時に指定することもできます。これは、設定ファイルを編集せずにローテーションする際に便利です。

app_token は非推奨で、使用されていません（返信は OCS ベアラー認証を経由しなくなりました）。これは、それを設定している古い設定がパースに失敗しないようにするためだけに、引き続き受け付けられています。

ゲートウェイエンドポイント

zeroclaw daemon

[channels.nextcloud_talk.<alias>] インスタンスのうち、受信すべきインスタンスのエイリアスを指すように、Talk ボットの webhook URL を設定してください。

https://<your-public-url>/nextcloud-talk/<alias>

例えば、[channels.nextcloud_talk.work] は POST /nextcloud-talk/work を受信します。このエイリアスごとのルーティング (#6312) により、複数の Talk ボットを並行して実行し、それぞれの webhook を適切なインスタンスに配信できます。

裸の https://<your-public-url>/nextcloud-talk パスは引き続き動作しますが、非推奨です。これは辞書順で最初のエイリアス（再起動をまたいでも決定的）に解決され、X-Zeroclaw-Deprecation レスポンスヘッダーを返します。単一インスタンスのデプロイメントでは、変更せずにそのまま使い続けられます。未知のエイリアスは 404 を返します。

ローカル開発ですか？設定で [tunnel] を構成すると（ngrok、Cloudflare、または Tailscale）、起動時にゲートウェイが自身を公開します。運用 → ネットワークデプロイ を参照してください。

署名の検証

受信リクエストには次の情報を含める必要があります:

• X-Nextcloud-Talk-Random ヘッダー
• X-Nextcloud-Talk-Signature ヘッダー

ZeroClaw は以下を検証します：

expected_sig = hex(hmac_sha256(secret, random + raw_request_body))
if X-Nextcloud-Talk-Signature != expected_sig:
    return 401

解決済みのシークレットがない場合、ZeroClaw は webhook を解析またはディスパッチする前に 401 を返します。未検証のリクエストを受け入れるモードはありません。

メッセージルーティング

• ボット由来のイベント (actorType = "bots") は無視されます: フィードバックループを防止します
• システムイベント（参加、退出、メンバーシップの変更）は無視されます
• メッセージ以外のイベントは無視されます
• ユーザーメッセージはエージェントループに送信されます。
• 返信は、Webhookペイロード内のtokenを使用して、元のルームに戻ります。

クイック検証

1. 初回テスト用に、ピアグループで external_peers = ["*"] を設定します
2. 設定されたTalkルームにテストメッセージを送信します
3. ZeroClawが同じ部屋で受信し、返信することを確認する
4. ピアグループを明示的なアクターID（例：["alice", "bob"]）に限定する

トラブルシューティング

• 404 Nextcloud Talk not configured: [channels.nextcloud_talk.default] セクションが存在しないか、enabled = false になっています
• 401 Invalid signature: シークレットの不一致、不正なランダムヘッダー、または署名処理のバグ。生のボディが署名されているか（パースされたJSONではなく）確認してください
• 返信なし、webhook が 200: イベントがフィルターされました。ログで “actorType = bots” または peer セットに含まれない送信者を確認してください
• 返信は配信されたが表示がおかしい: スレッドのコンテキストを確認してください。Talk の返信は現在ルートレベルのみに対応しています

ストリーミング

Nextcloud Talk は Bot API を介したメッセージの編集をサポートしていないため、このチャネルではストリーミングによるドラフトの更新は無効になっています。返信はストリームの完了後にのみ送信されます。

セルフホスティングに関するノート

• TLS: リバースプロキシで終了します。Webhook の署名検証は、HTTP からコンテナへのループバック経由で動作します。
• アウトバウンドの返信は、Bearerトークンではなく、Bot APIのHMAC署名（webhook_secret/bot_token）で認証されます。管理すべき独立したOCS Bearer資格情報は存在しません
• レート制限はNextcloudサーバーに依存しており、デフォルトのボットは通常の会話のペースではこれに遭遇しません。
• チャンネルごとのプロキシ: proxy_url を設定すると、Nextcloud Talk のみグローバルな [proxy] 設定を上書きできます (http://、https://、socks5://、socks5h://)

関連項目も参照してください

• Matrix: よりリッチなE2EEだが運用上の複雑さが増す
• Mattermost: 同様のセルフホスト型の構成、異なるプロトコル
• チャンネル → 概要