OpenClaw + QQ プラグイン連携と超長編トラブルシューティング振り返り（全工程）

AIDO debug
, ,
1

OpenClaw + QQ プラグイン連携と超長大なトラブルシューティング振り返り（全工程）

説明：本振り返りは実際に実行した手順に沿って整理し、連携・結合テストから核心問題の特定までの全プロセスと、各重要な結論を重点的に記録する。

一、背景と目標

今回の目標は OpenClaw を QQ チャネル（NapCat + openclaw_qq プラグインに基づく）に接続し、以下を実現すること：

  • QQ の個人チャット/グループチャットで正常に送受信できる
  • セッションのルーティングと WebUI の記録が可視化される
  • 管理者/ブラックリスト方針を制御可能（Token の不正消費防止）
  • 設定を Control UI で安定して保存できる

二、環境とタイムライン（概略）

ゲートウェイログのタイムスタンプによると、本調査は複数フェーズにまたがり、そのうち連続した高強度の切り分けは 数時間（約 4+ 時間） に及んだ。

三、主なワークフロー（フェーズ順）

1）QQ チャネル接続と基礎的な結合テスト

まず QQ プラグインと NapCat の基本デプロイを完了した：

  • openclaw_qq プラグインをインストールして有効化
  • Docker で NapCat をデプロイ
  • NapCat の接続モードを Forward WS Server（OpenClaw がクライアントとして接続）に修正
  • OneBot Token とアカウントを揃えた後、QQ チャネル状態が OK に復帰

2）セッションとルーティング問題の修正

結合テスト中に「QQ セッションがメインセッション/TG セッションに混ざる」現象が発生したため、ルーティングを修正した：

  • QQ group/direct の route 解析を修正
  • QQ 書き込み時にメインセッションのメタデータを上書きしないようにする
  • QQ と TG のセッションを分離して追跡可能にする

結果：WebUI 上での QQ セッション可視性が大幅に改善した。

3）コンテキストと重複メッセージ方針の調整

「QQ が毎回長い履歴を付けてきてノイズになる」問題に対して：

  • historyLimit のデフォルトを 0 に変更
  • ドキュメントで明記：デフォルトは OpenClaw のセッションシステムに依存し、グループ原文の強制結合はしない
  • ユーザーが明確に必要とする場合のみ履歴結合を有効化

同時に、重複トリガー/重複提示に関連するロジックも修正：

  • 管理者制限のチェック順序を「先にトリガー条件（@/キーワード）、後に認可」に調整
  • 非管理者向け通知にクールダウンのデバウンスを追加（デフォルト 10 秒）
  • reply-to-bot シナリオで通知ループが起こり得る問題を修正

4）管理者/ブラックリスト機能の強化

不正消費防止のため、機能を追加・強化した：

  • adminOnlyChat
  • notifyNonAdminBlocked
  • nonAdminBlockedMessage
  • blockedNotifyCooldownMs

ブラックリストの最終ロジックは以下と確定：

  • blockedUsers に該当するユーザーのメッセージは直接無視（返信しない・通知しない）

5）Control UI と設定保存問題（重点）

最も時間を要し、かつ最重要だった問題は：

  • /config ページで QQ のホワイト/ブラックリストだけを変更しても invalid config が出る
  • しかしエラーは models.providers.*.models[0].maxTokens を指している

最終的な特定結論：

  1. /config は差分保存ではなく「丸ごと保存」で、channels.qq だけを送るわけではない
  2. 丸ごと検証で、どれか 1 フィールドでも異常があると全体の保存が失敗する
  3. いくつかの経路で maxTokens が誤って処理（文字列化/レッドライン誤爆）され、全体検証が失敗する
  4. そのため「QQ 番号を変えるとモデルがエラーになる」ように見えるが、本質は「丸ごと検証の巻き添え」

四、なぜ「QQ 番号を変えると maxTokens に波及」して見えるのか

一言で言うと：業務的な関連ではなく、保存メカニズムの関連。

  • 変更したのは QQ フィールド
  • トリガーされたのは設定全体の書き戻し
  • 設定全体の中でモデル項目の型がドリフト（例：maxTokens が文字列/無効化）
  • 検証フェーズで失敗し、エラーがフロントエンドに伝播

五、リポジトリとローカル同期作業

プラグインリポジトリで継続的に修正し、複数回 push した。内容は：

  • 管理者ポリシー修正
  • セッションルーティング修正
  • 履歴注入のデフォルト値調整
  • フロントエンド schema 互換性の改善
  • ドキュメント（中国語の例）強化
  • NapCat docker デプロイ用ファイル追加
  • 実行時ディレクトリを無視し、リポジトリ汚染を防止

同時にローカルの .openclaw/extensions/qq はリモートの main ブランチと同期を維持した。

六、「QQ プラグインだけ直せば完全に解決できるか」について

結論：

  • QQ プラグイン内部の挙動と大部分の可用性問題は解決できる
  • ただし プラグイン層から OpenClaw コアの丸ごと保存チェーン問題を根本修正することはできない
  • models.* の検証は OpenClaw Core 側で、QQ プラグインの作用範囲外のため

七、実行可能な提案（最終）

短期的に使える（Core を変えない）

  • CLI で QQ のホワイト/ブラックリストを変更し、/config の丸ごと保存経路を回避する：
openclaw config set channels.qq.admins '\"1838552185\"' --json
openclaw config set channels.qq.blockedUsers '\"342571216\"' --json
openclaw gateway restart

中期的な提案（根治）

  • OpenClaw 公式の当該 issue（maxTokens + redaction + config save）の修正を待つ/追う
  • もしくは最小再現とパッチ PR を公式に提出する

八、学び

  1. /config ページの切り分けは必ず「丸ごと検証」の観点で行い、変更箇所だけを見ない
  2. 設定のレッドライン（redaction）が広いマッチ（例：/token/i）だと maxTokens を誤爆する
  3. チャットプラグインでは、認可順序（先にトリガー、後に認可）が非常に重要。さもないとグループ内ノイズを招く
  4. デバウンスと重複排除はデフォルトで有効化必須。そうしないとグループチャットで問題が急激に拡大する