QQ ボット

QQ 公式ボット から zqagent にタスクを依頼し、完了時に メール（SMTP） で通知します。個人チャット、グループチャット（@ボット）、チャンネルに対応し、承認 / 質問 / 中断など完全な操作ができます。

公式ボットはアウトバウンド接続のみで、公衆からのインバウンドは不要です。自前/社内サーバーでもメッセージを受け取れます。

プラットフォームの準備（1 回だけ）

QQ オープンプラットフォームで登録し、ボットを作成して AppID + AppSecret を取得します。
GROUP_AND_C2C_EVENT（1<<25） などの intents 権限を申請します（個人チャット+グループチャットのメッセージイベントは特別権限で、申請しないとゲートウェイの認証が拒否されます）。チャンネル @ とチャンネル DM はそれぞれ PUBLIC_GUILD_MESSAGES（1<<30）と DIRECT_MESSAGE（1<<12）に対応します。
結合テスト段階ではサンドボックス環境を使用します（サンドボックスメンバーのみテスト可能）。正式公開には審査が必要です。

設定

方法 1：.env 環境変数（起動時に読み込み）

bash

# .env
QQ_BOT_APP_ID=あなたのAppID
QQ_BOT_APP_SECRET=あなたのAppSecret
QQ_BOT_SANDBOX=1          # サンドボックス=1。正式環境=0 または空欄

方法 2：ホット設定（server 起動中でも再起動不要で、即時再接続して反映）

bash

# 現在の設定を表示（マスク済み）
curl -s -H "Authorization: Bearer <テナントapiKey>" http://localhost:8787/api/v1/qq/config

# 設定 / 更新
curl -s -X POST -H "Authorization: Bearer <テナントapiKey>" -H "Content-Type: application/json" \
  -d '{"appId":"あなたのAppID","appSecret":"あなたのAppSecret","sandbox":true}' \
  http://localhost:8787/api/v1/qq/config

# 設定を削除（切断）
curl -s -X DELETE -H "Authorization: Bearer <テナントapiKey>" http://localhost:8787/api/v1/qq/config

設定後、ログに QQ 机器人: 已启用 が表示されます。ホット設定はサーバー側に保存され、再起動後も有効です（設定の優先順位：環境変数 > 保存された設定）。

マルチテナントのバインド

方法 1：単一テナントはバインド不要（個人利用に推奨）

システムにテナントが 1 つだけ（既定の demo など）の場合、バインド操作は不要です。メッセージを送ると自動的に唯一のテナントにバインドされ、タスクが始まります。

方法 2：ペアリングコードでバインド（マルチテナント）

bash

# ペアリングコードを生成（管理者、REST API）
curl -X POST http://localhost:8787/api/v1/qq/pairing-code \
  -H "Authorization: Bearer <テナントapiKey>"
# → { "data": { "code": "AB3CD5K7", "expiresIn": 300 } }

ユーザーは QQ 内でバインドします：

/bind AB3CD5K7
→ バインド成功 ✅ テナント：demo。以後メッセージを送るだけでタスクを開始できます。

ペアリングコードは 5 分間有効で 1 回限りです（apiKey の平文がチャット履歴に残るのを避けるため）。
QQ の各セッションは 1 テナント + 1 つの zqagent セッションに対応し、最初のタスク送信時に自動でセッションを作成します。
バインドの対応表は {DATA_DIR}/qq/bindings.json に保存されます。

コマンド一覧

コマンド	動作
メッセージを直接送信	タスクを投入（質問待ちなら回答、実行中なら補足情報）
`/bind <ペアリングコード>`	現在の QQ セッションをテナントにバインド
`/unbind`	バインドを解除
`/new`	新しいセッションを作成してバインドを切り替え
`/status`	現在のセッション状態を表示
`/list`	セッション一覧
`/stop`	現在のタスクを中断
`/approve <once\|always_tool\|always_command\|deny>`	承認（「同意/全部同意/拒否」を直接送っても可）
`/answer <内容>`	質問に回答
`/help`	ヘルプ

タスク実行中にメッセージを送ると、補足情報（steering） として現在のタスクに注入されます。別のタスクを始める場合は先に /stop するか、タスクの終了を待ってください。

通知の返送と承認

実行中の重要イベントは対応する QQ セッションへ返送されます。承認リクエストにはツール名 + ツール引数 + 理由が付きます：

承認が必要：write_file
引数：
{
  "path": "/tmp/a.txt",
  "content": "hello"
}
理由：ファイルの書き込みが必要
返信：同意(今回のみ) / 全部同意(常に許可) / 拒否

同意 / 許可 / y → 今回のみ許可（once）
全部同意 / 常に許可 → このセッション内でこのツールを常に許可（always_tool）
拒否 / n → 拒否（deny）

⚠️ QQ 公式ボットは能動メッセージに厳しい割り当てがあります。タスク完了は通常「受動返信の 5 分間ウィンドウ」を超えるため、 完了通知はメールを確実な経路とし、QQ 内への返送はベストエフォートです。

メール通知の設定

bash

curl -X POST http://localhost:8787/api/v1/notifications \
  -H "Authorization: Bearer <テナントapiKey>" -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "enabled": true,
    "config": {
      "host": "smtp.qq.com",
      "port": "465",
      "secure": "true",
      "user": "you@qq.com",
      "pass": "<QQメールの認証コード>",
      "from": "you@qq.com",
      "to": "you@qq.com"
    },
    "events": { "approval": false, "question": false, "completed": true, "error": true }
  }'

QQ メール：smtp.qq.com:465（SSL）+ 認証コード（ログインパスワードではありません）。
163：smtp.163.com:465。Gmail：smtp.gmail.com:587（secure:"false"）。
pass などの機密フィールドは SECRET_KEY で AES 暗号化して保存されます。
events がトリガーのタイミングを制御します。上の例では「完了/エラー」時のみメールを送ります。
短時間のタスクでは通知しない：minDurationSeconds（既定 60）。タスクが成功し、実行時間がこのしきい値を超えない場合はメールを送りません。

QQ ボット ​

プラットフォームの準備（1 回だけ） ​

設定 ​

マルチテナントのバインド ​

コマンド一覧 ​

通知の返送と承認 ​

メール通知の設定 ​

QQ ボット

プラットフォームの準備（1 回だけ）

設定

マルチテナントのバインド

コマンド一覧

通知の返送と承認

メール通知の設定