Skip to content

DISCORD.ja-JP.md

Latest commit

 

History

History
535 lines (374 loc) · 16.1 KB

DISCORD.ja-JP.md

File metadata and controls

535 lines (374 loc) · 16.1 KB

言語: English | 简体中文 | 日本語

Discord リモートコントロール

Discord は OpenGUI の任意のリモートコマンド入口として利用できます。Bot が Discord チャンネルのコマンドを受け取り、バックエンドが OpenGUI タスクを作成または実行し、 スタンバイ中の Android 端末にディスパッチします。

Discord はコマンド入力面です。Bot が Discord アプリの UI を直接操作するわけではありません。

Discord チャンネル
  -> Discord bot
  -> OpenGUI バックエンド
  -> スタンバイ中の Android 端末
  -> 同じ Discord チャンネルへ結果を返す

はじめる前に

この機能は、Discord チャンネルを OpenGUI のリモートコマンド入口にします。

たとえば Discord で次のように送信します:

!opengui do open browser and search OpenGUI

バックエンドがこのコマンドを受け取り、OpenGUI タスクを作成し、スタンバイ中の Android 端末にディスパッチします。

この機能が行わないこと:

  • Discord Web、Mac、Windows クライアントの UI を自動操作しません。
  • OpenGUI Android アプリを置き換えません。実際の端末操作は Android クライアントが行います。
  • Discord 専用の Android APK は不要です。

必要なもの:

  • Discord アカウント。
  • 管理権限のある Discord server。なければテスト用 server を作成できます。
  • 起動できる OpenGUI バックエンド。
  • バックエンドにスタンバイ接続している Android 端末。

1. Discord Server を作成または準備する

すでにテスト用 server がある場合は、この節をスキップできます。

作成する場合:

  1. Discord を開きます。
  2. 左側の server 一覧で + をクリックします。
  3. Create My Own を選択します。
  4. For me and my friends、または近い選択肢を選びます。
  5. opengui-test などの server 名を入力します。
  6. デフォルトのテキストチャンネルを開きます。通常は general です。

Bot はこの server に招待され、このテキストチャンネルでコマンドを受け取ります。

2. Discord Application を作成する

  1. https://discord.com/developers/applications を開きます。
  2. New Application をクリックします。
  3. OpenGUITest などの名前を入力します。
  4. 利用規約に同意し、Create をクリックします。

application は Discord 側の bot プロジェクトです。Bot、Client ID、OAuth2 招待 URL はここで管理します。

3. Application ID をコピーする

  1. application ページで General Information を開きます。
  2. Application ID を探します。
  3. Copy をクリックします。
  4. この値を次に設定します:
DISCORD_CLIENT_ID=your_application_id

ここで使うのは Application ID です。Public Key、server ID、channel ID ではありません。

4. Bot を作成し Token をコピーする

  1. 左側の Bot を開きます。
  2. Bot 作成を求められた場合は Add Bot などのボタンをクリックします。
  3. Token セクションを探します。
  4. Reset Token または Copy をクリックします。
  5. Discord が認証を求める場合があります。
  6. コピーした token を次に設定します:
DISCORD_BOT_TOKEN=your_bot_token

Token は bot のパスワードです:

  • Git にコミットしないでください。
  • README に書かないでください。
  • 信頼できない相手に共有しないでください。
  • 漏えいした場合は Bot ページで Reset Token を実行してください。

5. Message Content Intent を有効にする

同じ Bot ページで Privileged Gateway Intents までスクロールします。

有効にするのはこれだけです:

Message Content Intent

これは次のような prefix command を読むために必要です:

!opengui help
!opengui devices
!opengui do ...

不要なもの:

Presence Intent
Server Members Intent

OpenGUI のコマンドフローではメンバー一覧やオンライン状態を読みません。

6. 招待 URL を生成する

  1. 左側の OAuth2 を開きます。
  2. URL Generator を開きます。
  3. Scopes で次を選択します:
bot
applications.commands

どちらも必要です:

  • bot: bot を server に参加させ、メッセージ送信を可能にします。
  • applications.commands: /opengui の slash command を有効にします。
  1. Bot Permissions までスクロールします。
  2. 次を選択します:
View Channels
Send Messages
Read Message History
Use Slash Commands

権限の意味:

  • View Channels: bot がチャンネルを見られます。
  • Send Messages: bot が返信できます。
  • Read Message History: bot がメッセージ履歴を読めます。
  • Use Slash Commands: bot が /opengui コマンドを提供できます。

Administrator をデフォルト手順として使うのは避けてください。短いテストでは便利ですが、 OpenGUI に必要な権限より大きすぎます。

  1. ページ下部の生成 URL をコピーします。
  2. ブラウザで開きます。
  3. テスト用 server を選択します。
  4. Authorize をクリックします。
  5. 認証を完了します。

server のメンバー一覧に bot が表示されれば招待成功です。

招待直後の bot がオフラインでも正常です。バックエンドが token で Discord にログインすると オンラインになります。

7. Discord Developer Mode を有効にする

server、channel、user ID をコピーする必要があります。Discord は標準では Copy ID を 隠していることがあります。

有効化手順:

  1. Discord を開きます。
  2. 左下のプロフィール付近にある歯車アイコンをクリックします。
  3. Advanced を開きます。
  4. Developer Mode を有効にします。

これで server、channel、user の右クリックメニューに Copy ID が表示されます。

8. Server ID、Channel ID、User ID をコピーする

.env には 3 つの ID が必要です。

Server ID

  1. 左側の server 一覧でテスト用 server アイコンを右クリックします。
  2. Copy Server ID または Copy ID をクリックします。
  3. 次に設定します:
DISCORD_ALLOWED_GUILD_IDS=your_server_id

Discord API では server を guild と呼ぶため、環境変数名は GUILD_IDS です。

Channel ID

  1. コマンドを送るテキストチャンネル、たとえば #general を右クリックします。
  2. Copy Channel ID または Copy ID をクリックします。
  3. 次に設定します:
DISCORD_ALLOWED_CHANNEL_IDS=your_channel_id

User ID

  1. server のメンバー一覧で自分を探します。
  2. 自分のアバターまたはユーザー名を右クリックします。
  3. Copy User ID または Copy ID をクリックします。
  4. 次に設定します:
DISCORD_ALLOWED_USER_IDS=your_user_id

この allowlist により、他のユーザーが勝手に端末タスクを実行することを防げます。

環境変数

以下を server/apps/backend/.env に追加します:

DISCORD_BOT_TOKEN=
DISCORD_CLIENT_ID=
DISCORD_ALLOWED_GUILD_IDS=
DISCORD_ALLOWED_CHANNEL_IDS=
DISCORD_ALLOWED_USER_IDS=
DISCORD_COMMAND_PREFIX=!opengui
DISCORD_REGISTER_COMMANDS=false

最初に slash command をテストする場合は次にします:

DISCORD_REGISTER_COMMANDS=true

これにより、バックエンド起動時に /opengui コマンドが設定済み guild に登録されます。

slash command の登録後は、次に戻せます:

DISCORD_REGISTER_COMMANDS=false

allowlist の動作:

  • 空の allowlist は、その次元では制限しないことを意味します。
  • 空でない allowlist では、guild、channel、または user が一致する必要があります。
  • 本番環境や共有テスト環境では、少なくとも DISCORD_ALLOWED_GUILD_IDS と DISCORD_ALLOWED_CHANNEL_IDS を設定してください。
  • DISCORD_REGISTER_COMMANDS=true には DISCORD_CLIENT_ID と DISCORD_ALLOWED_GUILD_IDS が必要です。

ID の対応:

変数 Discord での取得元
DISCORD_CLIENT_ID Developer Portal -> General Information -> Application ID
DISCORD_ALLOWED_GUILD_IDS Discord server ID
DISCORD_ALLOWED_CHANNEL_IDS Discord text channel ID
DISCORD_ALLOWED_USER_IDS Discord user ID

ローカルテスト例:

DISCORD_BOT_TOKEN=your_bot_token
DISCORD_CLIENT_ID=your_application_id
DISCORD_ALLOWED_GUILD_IDS=your_server_id
DISCORD_ALLOWED_CHANNEL_IDS=your_channel_id
DISCORD_ALLOWED_USER_IDS=your_user_id
DISCORD_COMMAND_PREFIX=!opengui
DISCORD_REGISTER_COMMANDS=true

複数の ID はカンマ区切りで指定できます:

DISCORD_ALLOWED_CHANNEL_IDS=channel_id_1,channel_id_2
DISCORD_ALLOWED_USER_IDS=user_id_1,user_id_2

9. バックエンドを再起動する

.env を変更した後はバックエンドを再起動してください。環境変数は通常、プロセス起動時に 一度だけ読み込まれます。

バックエンドが起動中なら、ターミナルで次を押します:

Ctrl + C

その後、再起動します:

cd server
pnpm backend

または:

cd server
./start.sh

成功時のログ例:

IM channel: Discord bot registered
[DiscordBot] Connected as OpenGUITest#3874

DISCORD_REGISTER_COMMANDS=true の場合は、次のようなログも出ます:

[DiscordBot] Slash commands registered for guild 1234567890

次のログが出る場合:

Discord bot not configured, skipping

バックエンドが DISCORD_BOT_TOKEN を読めていないか、.env の場所が想定と違います。

10. Android 端末がオンラインか確認する

Discord は入口です。実際に操作するのは Android 端末です。

タスク送信前に確認してください:

  • OpenGUI バックエンドが起動している。
  • OpenGUI Android アプリが開いている。
  • 端末がバックエンドに接続している。
  • バックエンドログに Device registered のような表示がある。

Discord でも確認できます:

!opengui devices

次のような端末モデルが出ればオンラインです:

OPPO PGEM10

コマンド

Prefix commands:

!opengui help
!opengui devices
!opengui do open browser and search OpenGUI
!opengui run 123
!opengui status
!opengui status 456
!opengui cancel 456
!opengui pause 456
!opengui resume 456 continue

Slash commands:

/opengui help
/opengui devices
/opengui do task:open browser and search OpenGUI
/opengui run task_id:123
/opengui status execution_id:456
/opengui cancel execution_id:456
/opengui pause execution_id:456
/opengui resume execution_id:456 feedback:continue

Slash commands は guild-scoped で登録されます。登録は DISCORD_REGISTER_COMMANDS=true の場合のみ行われます。

検証

おすすめの順序:

  1. Bot が返信できるか確認します:
!opengui help
  1. Bot がオンライン端末を見られるか確認します:
!opengui devices
  1. Slash command が使えるか確認します:
/opengui help
  1. 実際の端末タスクを送信します:
!opengui do open browser and search OpenGUI

または:

/opengui do task:open browser and search OpenGUI

期待される結果:

  • help がコマンド一覧を返します。
  • devices がスタンバイ中の Android 端末を表示します。
  • do が OpenGUI タスクを作成し、実行を開始し、進捗を同じ Discord チャンネルに投稿します。

実行中、Discord には次のようなメッセージが表示されます:

Created task: ...
Starting execution: ...
Device: ...
Planning...
Executing...

端末側でも、ブラウザを開く、検索ボックスをタップする、検索語を入力するなどの対応する操作が見えるはずです。

トラブルシューティング

Bot がオフラインのまま

よくある原因:

  • バックエンドが起動していない。
  • DISCORD_BOT_TOKEN が未設定または間違っている。
  • .env を変更した後にバックエンドを再起動していない。
  • バックエンドプロセスが Discord に接続できない。

まずバックエンドログを確認してください。[DiscordBot] Connected as ... がなければ、 Bot はログインできていません。

バックエンドに Connect Timeout Error が出る

これは通常コードの問題ではなく、ネットワークの問題です。

ブラウザで Discord にアクセスできても、Node.js のバックエンドプロセスが Discord API に 接続できるとは限りません。プロキシがブラウザだけに効いている場合があります。

試すこと:

  • プロキシツールで global mode または TUN mode を有効にする。
  • ターミナルに HTTP_PROXY、HTTPS_PROXY、ALL_PROXY を設定する。
  • ネットワーク設定を変えた後、バックエンドを再起動する。

!opengui help が返信しない

確認すること:

  • Bot がオンラインか。
  • Bot が server に参加しているか。
  • channel ID が DISCORD_ALLOWED_CHANNEL_IDS に含まれているか。
  • user ID が DISCORD_ALLOWED_USER_IDS に含まれているか。
  • Bot ページで Message Content Intent が有効か。
  • Bot に View Channels、Send Messages、Read Message History 権限があるか。

/opengui が表示されない

確認すること:

  • .env に DISCORD_REGISTER_COMMANDS=true があるか。
  • DISCORD_CLIENT_ID が設定されているか。
  • DISCORD_ALLOWED_GUILD_IDS が設定されているか。
  • Bot 招待時に applications.commands scope を含めたか。
  • バックエンドログに slash command 登録成功が出ているか。

Slash command は表示まで数秒かかる場合があります。必要なら Discord を更新または再起動してください。

!opengui devices に端末が出ない

Discord Bot は動いていますが、Android 端末がスタンバイ接続していません。

確認すること:

  • 端末アプリが開いているか。
  • 端末が Mac/バックエンドのネットワークに到達できるか。
  • バックエンドログに Device registered があるか。
  • Web コンソールで端末がオンラインか。

権限または allowlist の問題

allowlist を設定している場合、一致する server、channel、user ID だけがタスクを実行できます。

再確認してください:

DISCORD_ALLOWED_GUILD_IDS=
DISCORD_ALLOWED_CHANNEL_IDS=
DISCORD_ALLOWED_USER_IDS=

よくある間違い:

  • Application ID を server ID として使っている。
  • server ID を channel ID として使っている。
  • ID コピー前に Developer Mode を有効にしていない。
  • allowlist に入っていないチャンネルでコマンドを送っている。

注意事項

  • DISCORD_BOT_TOKEN が空の場合、バックエンドは通常どおり起動し、Discord をスキップします。
  • Android 側に Discord 専用の変更は不要です。
  • Discord Web、Mac、Windows クライアントはすべて利用できます。Bot は特定の Discord クライアントではなく Discord API に接続します。
  • Bot が connection timeout で起動できない場合は、バックエンドプロセスが Discord にアクセスできるか確認してください。ブラウザのプロキシ設定が Node.js プロセスに適用されないことがあります。