agent-discordbot

Agent DiscordBot

AI エージェントや人間が、ボットトークンを使って Discord サーバーとやり取りできるようにする TypeScript CLI ツールです。デスクトップアプリからユーザートークンを取得する agent-discord とは異なり、agent-discordbot は標準の Discord ボットトークンを使用して、サーバー側や CI/CD との連携を実現します。

主な概念

始める前に、Discord ボットとの連携に関する基本事項をいくつか説明します。

• ボットトークン — Discord Developer Portal（discord.com/developers/applications）で発行します。ボットはボットアプリケーションのユーザーとして動作し、独自の ID とプレゼンスを持ちます。
• サーバー（ギルド）の選択 — ボットは複数のサーバーに参加できます。server switch <id> を使ってアクティブなサーバーを設定するか、コマンドごとに --server <id> を指定します。
• 特権インテント — MessageContent、GuildMembers、GuildPresences は特権インテントであり、SDK リスナーで使用するには、事前に Developer Portal で有効にする必要があります。
• 権限による制限 — ボットが実行できる操作は、各サーバーのロールに設定された権限フラグによって決まります。権限が不足している場合は、403 エラーが返されます。
• リアルタイムイベント — CLI ではなく、SDK の Gateway リスナーを通じて利用できます。
• チャンネルの解決 — すべての <channel> 引数には、チャンネル ID（スノーフレーク）またはチャンネル名（general または #general）を正確に指定できます。ID を指定すると検索が省略されるため、より高速です。完全一致するものがない場合、名前の指定は Channel not found エラーになります。
• スレッドの指定 — message send と file upload の --thread <id|name> は、スレッド内に投稿します。数値を指定するとスレッド ID として扱われ、名前を指定するとそのチャンネルのアクティブなスレッドから照合されます（それ以外の場合は thread_not_found / thread_ambiguous になります）。アーカイブ済みスレッドは ID で指定する必要があります（thread list <channel> --archived で確認してください）。ロックされていない場合、アーカイブ済みスレッドへの投稿時にアーカイブが解除されます。
• 出力の thread_id と channel_id — スレッド内に投稿されたメッセージでは、channel_id はスレッド ID です。thread_id は、そのメッセージからスレッドが開始された場合にのみ設定され、それ以外は null です。

クイックスタート

# Set your bot token
agent-discordbot auth set your-bot-token

# Verify authentication
agent-discordbot auth status

# Send a message
agent-discordbot message send 1234567890123456789 "Hello from bot!"

# List channels
agent-discordbot channel list

認証

ボットトークンの設定

agent-discordbot は、Discord Developer Portal で作成する Discord ボットトークンを使用します。

# Set bot token (validates against Discord API before saving)
agent-discordbot auth set your-bot-token

# Set with a custom bot identifier
agent-discordbot auth set your-bot-token --bot deploy

# Check auth status
agent-discordbot auth status

# Clear stored credentials
agent-discordbot auth clear

ボットトークンの設定、サーバーへの招待手順、Message Content Intent、複数のボットの管理については、references/authentication.md を参照してください。

メモリ

エージェントは、セッション間で保持されるメモリとして ~/.config/agent-messenger/MEMORY.md ファイルを管理します。このファイルはエージェントが管理するものであり、CLI が読み書きすることはありません。Read ツールと Write ツールを使ってメモリファイルを管理してください。

メモリの読み取り

すべてのタスクの開始時に、Read ツールを使って ~/.config/agent-messenger/MEMORY.md を読み込み、以前に確認したサーバー ID、チャンネル ID、ユーザー ID、設定を読み取ってください。

• ファイルがまだ存在しない場合は、そのまま進めてください。保存する有用な情報を初めて得たときに作成してください。
• ファイルを読み取れない場合（権限がない、ディレクトリがないなど）は、メモリを使わずに進めてください。エラーにしないでください。

メモリの書き込み

有用な情報を確認した後、Write ツールを使って ~/.config/agent-messenger/MEMORY.md を更新してください。書き込みが必要になるのは、次のような場合です。

• サーバー ID と名前を確認したとき（server list など）
• 有用なチャンネル ID と名前を確認したとき（channel list など）
• ユーザー ID と名前を確認したとき（user list など）
• ユーザーから別名や好みを伝えられたとき（「これをアラートボットと呼んで」「メインサーバーは X」など）
• ボット識別子を設定したとき（auth list など）

書き込むときは、ファイルの完全な内容を含めてください。Write ツールはファイル全体を上書きします。

保存する内容

• サーバー ID と名前
• チャンネル ID、名前、カテゴリ
• ユーザー ID と表示名
• ボット識別子とその用途
• ユーザーから指定された別名（「アラートボット」「お知らせチャンネル」など）
• やり取りの中で表明されたユーザーの好み

保存してはいけないもの

ボットトークン、認証情報、その他の機密データは決して保存しないでください。メッセージの全文は保存しないでください（IDとチャンネルのコンテキストのみを保存します）。ファイルのアップロード内容も保存しないでください。

古くなったデータの処理

記憶した ID がエラーを返した場合（チャンネルが見つからない、サーバーが見つからないなど）、MEMORY.md から削除してください。記憶したデータを無条件に信用せず、何かおかしいと感じたら確認してください。古くなっている可能性のある記憶済み ID を使うより、一覧を再取得してください。

形式／例

# Agent Messenger Memory

## Discord Servers (Bot)

- `1234567890123456` — Acme Dev

## Bots (Acme Dev)

- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot

## Channels (Acme Dev)

- `1111111111111111` — #general (General category)
- `2222222222222222` — #engineering (Engineering category)
- `3333333333333333` — #deploys (Engineering category)

## Users (Acme Dev)

- `4444444444444444` — Alice (server owner)
- `5555555555555555` — Bob

## Aliases

- "deploys" → `3333333333333333` (#deploys in Acme Dev)

## Notes

- Deploy Bot is used for CI/CD notifications
- Alert Bot is used for error monitoring

メモリーを使うと、channel list や server list の呼び出しを繰り返さずに済みます。以前のセッションで ID が分かっている場合は、その ID を直接使用してください。

コマンド

認証コマンド

# Set bot token
agent-discordbot auth set <token>
agent-discordbot auth set <token> --bot deploy

# Check auth status
agent-discordbot auth status

# Clear all credentials
agent-discordbot auth clear

# List stored bots
agent-discordbot auth list

# Switch active bot
agent-discordbot auth use <bot-id>

# Remove a stored bot
agent-discordbot auth remove <bot-id>

Whoami コマンド

# Show current authenticated bot
agent-discordbot whoami
agent-discordbot whoami --pretty
agent-discordbot whoami --bot <bot-id>

サーバーコマンド

# List servers the bot is in
agent-discordbot server list

# Show current server
agent-discordbot server current

# Switch active server
agent-discordbot server switch <server-id>

# Get server info
agent-discordbot server info <server-id>

メッセージコマンド

# Send a message
agent-discordbot message send <channel-id> <content>
agent-discordbot message send 1234567890123456789 "Hello world"

# Reply to a message
agent-discordbot message send <channel-id> <content> --reply <message-id>
agent-discordbot message send 1234567890123456789 "On it!" --reply 9876543210987654321

# Send a message into a thread (by ID or by active-thread name); the returned channel_id equals the thread ID
agent-discordbot message send <channel-id> <content> --thread <thread-id|thread-name>
agent-discordbot message send 1234567890123456789 "Hello world" --thread 9876543210987654321
agent-discordbot message send 1234567890123456789 "Hello world" --thread "Deployment Progress"

# Sending directly to a thread ID also works (a thread is a channel)
agent-discordbot message send 9876543210987654321 "Hello thread"

# List messages
agent-discordbot message list <channel-id>
agent-discordbot message list 1234567890123456789 --limit 50

# Get a single message by ID
agent-discordbot message get <channel-id> <message-id>

# Get thread replies
agent-discordbot message replies <channel-id> <message-id>
agent-discordbot message replies 1234567890123456789 9876543210987654321 --limit 50

# Edit a message (bot's own messages only)
agent-discordbot message edit <channel-id> <message-id> <new-content>

# Delete a message (bot's own messages only)
agent-discordbot message delete <channel-id> <message-id> --force

チャンネルコマンド

# List channels in current server
agent-discordbot channel list

# Get channel info
agent-discordbot channel info <channel-id>
agent-discordbot channel info 1234567890123456789

ユーザーコマンド

# List server members
agent-discordbot user list

# Get user info
agent-discordbot user info <user-id>

リアクションコマンド

# Add reaction (use emoji name without colons)
agent-discordbot reaction add <channel-id> <message-id> <emoji>
agent-discordbot reaction add 1234567890123456789 9876543210987654321 thumbsup

# Remove reaction
agent-discordbot reaction remove <channel-id> <message-id> <emoji>

# List reactions on a message: [{ emoji: {id, name}, count, me }]
agent-discordbot reaction list <channel-id> <message-id>

ファイルコマンド

# Upload one or more files (max 10) to a channel, optionally with text
agent-discordbot file upload <channel-id> <path...> [--text <text>] [--thread <id|name>] [--reply <message-id>] [--filename <name>]
agent-discordbot file upload 1234567890123456789 ./report.pdf
agent-discordbot file upload 1234567890123456789 ./report.pdf ./chart.png --text "Weekly numbers"

# Upload into a thread, or as a reply
agent-discordbot file upload 1234567890123456789 ./log.txt --thread 9876543210987654321
agent-discordbot file upload 1234567890123456789 ./log.txt --text "Full log attached" --reply 9876543210987654321

# Override the stored filename (single file only)
agent-discordbot file upload 1234567890123456789 ./tmp-8x1.txt --filename build.log

# List files in channel (attachments of the latest 100 messages, one request)
agent-discordbot file list <channel-id>

# Get info for one attachment (id, filename, size, url, content_type)
# Searches back through the latest 1,000 messages and stops at the first match
agent-discordbot file info <channel-id> <file-id>

file upload は { success, file, files, message_id, channel_id } を返します。file は最初の添付ファイル、files はすべての添付ファイルを格納し、--thread を使用した場合、channel_id はスレッド ID です。すべてのメッセージ読み取りコマンド（message send|list|get|replies）には、attachments: [{ id, filename, size, url, content_type }] が含まれ、添付ファイルがない場合は [] になります。CLI に固定のサイズ上限はありません。サイズ上限はサーバーごとに Discord が決定し、ファイルが大きすぎる場合は 40005（または http_413）を返します。

スレッドコマンド

# Create a thread from a message
agent-discordbot thread create <channel-id> <name>
agent-discordbot thread create 1234567890123456789 "Discussion" --auto-archive-duration 1440

# List active threads (whole server, or one channel's threads)
agent-discordbot thread list
agent-discordbot thread list <channel-id>

# List archived threads of a channel (100 most recently archived; has_more tells you if there are older ones)
agent-discordbot thread list <channel-id> --archived

# Archive a thread
agent-discordbot thread archive <thread-id>

thread list は { threads: [{ id, name, type, parent_id, archived }], has_more } を返します。--archived にはチャンネル引数が必要です（指定しない場合は parent_required）。

スナップショットコマンド

AI エージェント向けにサーバーの概要を取得します（デフォルトは簡易版です）。

# Brief snapshot (default) — fast, minimal API calls
agent-discordbot snapshot

# Full snapshot — includes messages and members (slow, large output)
agent-discordbot snapshot --full

# Filtered full snapshots
agent-discordbot snapshot --full --channels-only
agent-discordbot snapshot --full --users-only

# Limit messages per channel (only with --full)
agent-discordbot snapshot --full --limit 10

デフォルトでは、次の内容を含む簡易 JSON が返されます。

• サーバー ID
• チャンネル（id、name）— テキストチャンネルのみ
• 次に実行するコマンドのヒント

--full を指定すると、次の内容を含む包括的な JSON が返されます。

• サーバーのメタデータ（id、name）
• チャンネル（id、name、type、topic）
• 最近のメッセージ（id、content、author、timestamp）
• メンバー（id、username、global_name）

出力形式

JSON（デフォルト）

すべてのコマンドは、AI が利用しやすいよう、デフォルトで JSON を出力します。

{
  "id": "1234567890123456789",
  "content": "Hello world",
  "author": "bot-username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Pretty（人間が読みやすい形式）

整形された出力には --pretty フラグを使用します。

agent-discordbot channel list --pretty

グローバルオプション

オプション	説明
--pretty	JSON の代わりに人間が読みやすい形式で出力します
--bot <id>	このコマンドで特定のボットを使用します
--server <id>	このコマンドで特定のサーバーを使用します

よくあるパターン

典型的な AI エージェントのワークフローについては、references/common-patterns.md を参照してください。

テンプレート

実行可能な例については、templates/ ディレクトリを参照してください。

• post-message.sh - エラー処理を含むメッセージの送信
• monitor-channel.sh - 新しいメッセージがないかチャンネルを監視
• server-summary.sh - サーバーの概要を生成

エラー処理

すべてのコマンドは、一貫した形式のエラーを返します。

{
  "error": "No credentials. Run \"auth set\" first."
}

よくあるエラー：missing_token、invalid_token、Missing Access、Unknown Channel、Missing Permissions。

ファイルの送信とスレッドの指定に固有のエラー：

• empty_message：file upload には少なくとも 1 つのファイル、またはファイルとともに --text が必要です。
• too_many_files：1 回のアップロードで 10 個を超えるファイルが指定されています。
• invalid_filename：--filename が空、.、..、またはパス区切り文字を含んでいます。
• thread_not_found：--thread <name> に一致するアクティブなスレッドがそのチャンネルにありません。thread list <channel> を実行してください（アーカイブ済みのスレッドには --archived を追加します）。またはスレッド ID を指定してください。
• thread_ambiguous：同じ名前のアクティブなスレッドが複数あります。メッセージに各 ID が表示されるので、ID を使用してください。
• parent_required：チャンネルを指定せずに thread list --archived が呼び出されました。
• 40005 / http_413：そのサーバーのサイズ上限を超えているため、Discord がアップロードを拒否しました。エラーメッセージにその旨が表示されます。CLI はサイズを事前に確認しません。

設定

認証情報は ~/.config/agent-messenger/discordbot-credentials.json に保存されます（権限は 0600）。形式とセキュリティの詳細については、references/authentication.md を参照してください。

agent-discordとの主な違い

機能	agent-discord	agent-discordbot
トークンの種類	ユーザートークン	ボットトークン
トークンの取得元	デスクトップアプリから自動抽出	Developer Portalから手動取得
メッセージ検索	あり	なし
DM	あり	なし
メンション	あり	なし
フレンド／ノート	あり	なし
メッセージの編集／削除	任意のメッセージ	ボット自身のメッセージのみ
ファイルのアップロード	あり	あり（テキスト、スレッド、返信）
スレッド一覧	なし	あり（アクティブ＋アーカイブ済み）
リアクション一覧	あり	あり
スナップショット	あり	あり
CI/CDへの対応	デスクトップアプリが必要	あり（トークンを設定するだけ）

制限事項

• CLIではリアルタイムイベントを利用できません（リアルタイムのGatewayイベントはSDKから利用できます — import { DiscordBotListener } from 'agent-messenger/discordbot'）
• ボイスチャンネルには対応していません
• サーバー管理（チャンネルやロールの作成／削除）には対応していません
• スラッシュコマンドには対応していません
• Webhookには対応していません
• メッセージ検索には対応していません
• DMやフレンド管理には対応していません
• ボットが編集／削除できるのは自身のメッセージのみです
• ボットをサーバーに招待し、適切な権限を付与する必要があります
• 認証済みボット（100以上のサーバーに参加）の場合、Message Contentインテントが必要です
• プレーンテキストのメッセージのみです（v1では埋め込みに対応していません）
• スレッド名で検索できるのはアクティブなスレッドのみです。アーカイブ済みのスレッドにはIDが必要です
• thread list --archivedはhas_moreを含む1ページ分（100スレッド）のみを返します。これ以上のページネーションには対応していません
• ファイルのダウンロードや削除には対応していません

トラブルシューティング

agent-discordbot: command not found

agent-discordbotはnpmパッケージ名ではありません。 npmパッケージ名はagent-messengerです。

パッケージがグローバルにインストールされている場合は、agent-discordbotを直接使用してください。

agent-discordbot message send 1234567890123456789 "Hello"

パッケージがインストールされていない場合は、デフォルトでnpx -yを使用してください。どのパッケージランナーを使うかユーザーに尋ねてはいけません。そのまま実行してください。

npx -y agent-messenger discordbot message send 1234567890123456789 "Hello"
bunx agent-messenger discordbot message send 1234567890123456789 "Hello"
pnpm dlx agent-messenger discordbot message send 1234567890123456789 "Hello"

ユーザーが希望するパッケージランナー（例：bunx、pnpm dlx）がすでに分かっている場合は、代わりにそれを使用してください。

npx agent-discordbot、bunx agent-discordbot、pnpm dlx agent-discordbotは絶対に実行しないでください。agent-discordbotはnpmパッケージ名ではないため、失敗するか、誤ったパッケージがインストールされます。

その他のトラブルシューティング（権限、トークンの問題、Message Contentインテント）については、references/authentication.mdを参照してください。

参考資料

• 認証ガイド
• 一般的なパターン