agent-slackbot

Agent SlackBot

AI エージェントや人間がボットトークン（xoxb-）を使用して Slack ワークスペースとやり取りできるようにする、TypeScript 製の CLI ツールです。デスクトップアプリからユーザートークンを抽出する agent-slack とは異なり、agent-slackbot はサーバーサイドや CI/CD の連携に標準の Slack ボットトークンを使用します。

主な概念

詳しく見ていく前に、Slack ボット連携について知っておきたいことをいくつか紹介します。

• ボットトークン（xoxb-） — Slack アプリの設定（api.slack.com/apps）から発行されます。ボットはあなたとしてではなく、ボットユーザーとして動作します。名前、権限、ID はそれぞれ異なります。
• ワークスペースとボットの階層構造 — 各ワークスペースには複数のボットトークン（Slack アプリごとに 1 つ）を登録できます。CLI はボットをワークスペースごとに保存し、切り替えられるようにします。
• チャンネルへのアクセスには招待が必要 — ボットがプライベートチャンネルのメッセージを読んだり投稿したりするには、事前に /invite @YourBotName で招待する必要があります。
• ボットのスコープはトークンごとに固定 — トークンで利用できる機能は、アプリの作成時に決まります。新しいスコープを追加するには、アプリを再インストールしてトークンを更新する必要があります。
• 編集と削除はボットのみに適用 — ボットが編集または削除できるのは、自分が送信したメッセージだけです。他のユーザーのメッセージは変更できません。
• リアルタイムイベント — CLI ではなく、SDK の Socket Mode リスナーを介して利用できます（別途 xapp- アプリレベルのトークンが必要です）。

クイックスタート

# Set your bot token
agent-slackbot auth set xoxb-your-bot-token

# Or set with a custom bot identifier for multi-bot setups
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Verify authentication
agent-slackbot auth status

# Send a message
agent-slackbot message send C0ACZKTDDC0 "Hello from bot!"

# List channels
agent-slackbot channel list

認証

ボットトークンの設定

agent-slackbot は、Slack アプリの設定から取得する Slack ボットトークン（xoxb-）を使用します。

# Set bot token (validates against Slack API before saving)
agent-slackbot auth set xoxb-your-bot-token

# Set with a custom bot identifier
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Check auth status
agent-slackbot auth status

# Clear stored credentials
agent-slackbot auth clear

複数のボットの管理

複数のボットトークンを保存して切り替えます。

# Add multiple bots
agent-slackbot auth set xoxb-deploy-token --bot deploy --name "Deploy Bot"
agent-slackbot auth set xoxb-alert-token --bot alert --name "Alert Bot"

# List all stored bots
agent-slackbot auth list

# Switch active bot
agent-slackbot auth use deploy

# Use a specific bot for one command (without switching)
agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert

# Remove a stored bot
agent-slackbot auth remove deploy

# Disambiguate bots with same ID across workspaces
agent-slackbot auth use T123456/deploy

--bot <id> フラグはすべてのコマンドで使用でき、1 回の実行に限り、アクティブなボットを上書きできます。

ボットトークンの設定（Slack アプリの作成、必要なスコープ、アプリマニフェスト）と CI/CD 環境変数については、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 を見つけた後（auth status から）
• 有用なチャンネル ID と名前を見つけた後（channel list などから）
• ユーザー ID と名前を見つけた後（user list などから）
• ユーザーから別名や設定を伝えられた後（「これを alerts bot と呼んで」「メインのワークスペースは X」など）
• ボット識別子を設定した後（auth list から）

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

保存する情報

• 名前を含むワークスペース ID
• 名前と用途を含むチャンネル ID
• 表示名を含むユーザー ID
• ボット識別子とその用途
• ユーザーが指定した別名（「alerts bot」、「deploys channel」など）
• やり取りの中で示されたユーザーの設定

保存しない情報

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

古くなったデータの扱い

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

形式／例

# Agent Messenger Memory

## Slack Workspaces (Bot)

- `T0ABC1234` — Acme Corp

## Bots (Acme Corp)

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

## Channels (Acme Corp)

- `C012ABC` — #general (company-wide announcements)
- `C034DEF` — #engineering (team discussion)
- `C056GHI` — #deploys (CI/CD notifications)

## Users (Acme Corp)

- `U0ABC123` — Alice (engineering lead)
- `U0DEF456` — Bob (backend)

## Aliases

- "deploys" → `C056GHI` (#deploys in Acme Corp)

## Notes

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

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

コマンド

Whoami コマンド

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

メッセージコマンド

# Send a message
agent-slackbot message send <channel> <text>
agent-slackbot message send C0ACZKTDDC0 "Hello world"

# Send a threaded reply
agent-slackbot message send C0ACZKTDDC0 "Reply" --thread <ts>

# List messages
agent-slackbot message list <channel>
agent-slackbot message list C0ACZKTDDC0 --limit 50

# Get a single message by timestamp
agent-slackbot message get <channel> <ts>

# Get thread replies (includes parent message)
agent-slackbot message replies <channel> <thread_ts>
agent-slackbot message replies C0ACZKTDDC0 1234567890.123456 --limit 50

# Integration posts (alerting webhooks, CI bots) often have an empty "text";
# list/get/replies then include their content in "attachments" and "blocks"

# Edit a message (bot's own messages only)
agent-slackbot message edit <channel> <ts> <new-text>

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

# Show typing/status indicator in an AI Assistant thread
agent-slackbot message typing <channel> <thread_ts>
agent-slackbot message typing <channel> <thread_ts> "is analyzing..."
agent-slackbot message typing <channel> <thread_ts> ""   # clear status

入力中インジケーター：message typing は Slack の assistant.threads.setStatus API を呼び出します。これはAI アシスタントのスレッド内でのみ機能し（通常のチャンネルや DM では機能しません）、chat:write ボットスコープが必要です。ボットが次のメッセージを投稿するとステータスは自動的に解除されます。メッセージが送信されない場合は、2 分後に解除されます。手動でステータスを解除するには、空の文字列 "" を渡します。

チャンネルコマンド

# List channels the bot can see
agent-slackbot channel list
agent-slackbot channel list --limit 50

# Get channel info
agent-slackbot channel info <channel>
agent-slackbot channel info C0ACZKTDDC0

ユーザーコマンド

# List users
agent-slackbot user list
agent-slackbot user list --limit 50

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

リアクションコマンド

# Add reaction
agent-slackbot reaction add <channel> <ts> <emoji>
agent-slackbot reaction add C0ACZKTDDC0 1234567890.123456 thumbsup

# Remove reaction
agent-slackbot reaction remove <channel> <ts> <emoji>

ファイルコマンド

# Upload a file to a channel (requires files:write scope)
agent-slackbot file upload <channel> <path>
agent-slackbot file upload C0ACZKTDDC0 ./report.pdf
agent-slackbot file upload C0ACZKTDDC0 ./log.txt --filename build-log.txt
agent-slackbot file upload C0ACZKTDDC0 ./screenshot.png --thread 1234567890.123456 --comment "FYI"

# List files visible to the bot (requires files:read scope)
agent-slackbot file list
agent-slackbot file list --channel C0ACZKTDDC0
agent-slackbot file list --user U123 --limit 50

# Show file details
agent-slackbot file info <file-id>

# Download a file by ID (saves to current dir or given path)
agent-slackbot file download <file-id>
agent-slackbot file download F0123ABC ./downloads/

# Delete a file (bot's own files only)
agent-slackbot file delete <file-id> --force

ファイルスコープ：file upload には files:write が必要です。file list、file info、file download には files:read が必要です。これらを Slack App のボットトークンスコープに追加し、アプリを再インストールしてください。ボットが削除できるのは、自身がアップロードしたファイルのみです。

出力形式

JSON（デフォルト）

すべてのコマンドは、AI での利用を想定してデフォルトで JSON を出力します。

{
  "ts": "1234567890.123456",
  "channel": "C0ACZKTDDC0",
  "text": "Hello world"
}

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

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

agent-slackbot channel list --pretty

グローバルオプション

オプション	説明
--pretty	コンパクトな JSON ではなく、人間が読みやすい形式で出力します
--bot <id>	このコマンドで特定のボットを使用します（ワークスペース／ボット）

よく使われるパターン

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

テンプレート

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

• post-message.sh - エラー処理を含めてメッセージを送信します
• monitor-channel.sh - チャンネルを監視して新しいメッセージを確認します
• workspace-summary.sh - ワークスペースの概要を生成します

エラー処理

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

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

一般的なエラー：

• missing_token：認証情報が設定されていません
• invalid_token_type：トークンがボットトークンではありません（xoxb- で始まる必要があります）
• not_in_channel：ボットは最初にチャンネルに参加する必要があります
• slack_webapi_rate_limited_error：レート制限に達しました（バックオフして自動再試行します）

設定

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

agent-slack との主な違い

機能	agent-slack	agent-slackbot
トークンの種類	ユーザートークン（xoxc-）	ボットトークン（xoxb-）
トークンの取得元	デスクトップアプリから自動抽出	Slack App の設定から手動取得
メッセージ検索	あり	なし（ユーザートークンが必要）
ファイル操作	あり	アップロード／一覧／情報／ダウンロード／削除（スコープが必要）
スナップショット	あり	なし
メッセージの編集／削除	任意のメッセージ	ボット自身のメッセージのみ
ワークスペース管理	複数のワークスペース	複数のボット、複数のワークスペース
CI/CD への適合性	デスクトップアプリが必要	あり（トークンを設定するだけ）

制限事項

• CLI ではリアルタイムイベントを利用できません（リアルタイムの Socket Mode イベントは SDK 経由で利用できます。README の「Real-time Events (Slack Bot)」セクションを参照してください）
• メッセージ検索はできません（ユーザートークンのスコープが必要です）
• ファイル操作には files:read／files:write スコープが必要です。ボットが削除できるのは、自身がアップロードしたファイルのみです
• ワークスペースのスナップショットは取得できません
• ボットが編集／削除できるのは、自身のメッセージのみです
• ボットはプライベートチャンネルに招待される必要があります
• メッセージの予約投稿はできません

トラブルシューティング

agent-slackbot: command not found

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

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

agent-slackbot message send general "Hello"

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

npx -y agent-messenger slackbot message send general "Hello"
bunx agent-messenger slackbot message send general "Hello"
pnpm dlx agent-messenger slackbot message send general "Hello"

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

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

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

参考資料

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