Back to Details

agent-discordbot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent DiscordBot

Agent DiscordBot

A TypeScript CLI tool that enables AI agents and humans to interact with Discord servers using bot tokens. Unlike agent-discord which extracts user tokens from the desktop app, agent-discordbot uses standard Discord Bot tokens for server-side and CI/CD integrations.
一款TypeScript CLI工具，支持AI Agent和人类使用机器人令牌与Discord服务器交互。与从桌面应用提取用户令牌的agent-discord不同，agent-discordbot使用标准Discord Bot令牌，适用于服务器端和CI/CD集成场景。

Key Concepts

核心概念

Before diving in, a few things about Discord Bot integration:
  • Bot tokens — Issued from the Discord Developer Portal (discord.com/developers/applications). Bots act as the bot application's user, with their own ID and presence.
  • Server (Guild) preference — A bot can be in many servers. Use 
    server switch <id>
    to set the active server, or pass 
    --server <id>
    per command.
  • Privileged intents — 
    MessageContent
    , 
    GuildMembers
    , and 
    GuildPresences
    are privileged and must be enabled in the Developer Portal before they can be used by the SDK listener.
  • Permission gates — Bot capabilities depend on the role's permission flags in each server. Missing permissions return 403 errors.
  • Real-time events — Available via the SDK's Gateway listener, not via the CLI.
  • Channel resolution — Use channel IDs (snowflake numbers) directly. The CLI does not resolve 
    #channel-name
    syntax.
开始使用前，先了解一些Discord机器人集成的要点：
  • Bot tokens — 从Discord开发者门户（discord.com/developers/applications）获取。机器人作为机器人应用的用户存在，拥有独立的ID和在线状态。
  • Server (Guild) preference — 一个机器人可加入多个服务器。使用
    server switch <id>
    设置当前活跃服务器，或在每个命令中添加
    --server <id>
    参数指定。
  • Privileged intents — 
    MessageContent
    、
    GuildMembers
    和
    GuildPresences
    属于特权权限，必须在开发者门户中启用后，SDK监听器才能使用。
  • Permission gates — 机器人的功能取决于其在各服务器中的角色权限。缺少权限会返回403错误。
  • Real-time events — 仅通过SDK的Gateway监听器提供，CLI不支持。
  • Channel resolution — 直接使用频道ID（雪花数字）。CLI不支持解析
    #channel-name
    格式。

Quick Start

快速开始

bash
undefined
bash
undefined

Set your bot token

设置机器人令牌

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

Verify authentication

验证认证状态

agent-discordbot auth status
agent-discordbot auth status

Send a message

发送消息

agent-discordbot message send 1234567890123456789 "Hello from bot!"
agent-discordbot message send 1234567890123456789 "Hello from bot!"

List channels

列出频道

agent-discordbot channel list
undefined
agent-discordbot channel list
undefined

Authentication

认证

Bot Token Setup

Bot令牌设置

agent-discordbot uses Discord Bot tokens which you create in the Discord Developer Portal:
bash
undefined
agent-discordbot使用在Discord开发者门户创建的Discord Bot令牌：
bash
undefined

Set bot token (validates against Discord API before saving)

设置机器人令牌（保存前会验证Discord API有效性）

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

Set with a custom bot identifier

使用自定义机器人标识设置

agent-discordbot auth set your-bot-token --bot deploy --name "Deploy Bot"
agent-discordbot auth set your-bot-token --bot deploy --name "Deploy Bot"

Check auth status

检查认证状态

agent-discordbot auth status
agent-discordbot auth status

Clear stored credentials

清除存储的凭证

agent-discordbot auth clear

For bot token setup, server invite flow, Message Content Intent, and multi-bot management, see [references/authentication.md](references/authentication.md).
agent-discordbot auth clear

关于Bot令牌设置、服务器邀请流程、消息内容权限和多机器人管理，请查看[references/authentication.md](references/authentication.md)。

Memory

内存管理

The agent maintains a 
~/.config/agent-messenger/MEMORY.md
file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the 
Read
and 
Write
tools to manage your memory file.
Agent会维护一个
~/.config/agent-messenger/MEMORY.md
文件，作为跨会话的持久化内存。该文件由Agent管理——CLI不会读写此文件。使用
Read
和
Write
工具管理内存文件。

Reading Memory

读取内存

At the start of every task, read 
~/.config/agent-messenger/MEMORY.md
using the 
Read
tool to load any previously discovered server IDs, channel IDs, user IDs, and preferences.
  • If the file doesn't exist yet, that's fine — proceed without it and create it when you first have useful information to store.
  • If the file can't be read (permissions, missing directory), proceed without memory — don't error out.
在每个任务开始时，使用
Read
工具读取
~/.config/agent-messenger/MEMORY.md
，加载之前保存的服务器ID、频道ID、用户ID和偏好设置。
  • 如果文件尚未存在，无需处理——继续执行任务，当有有用信息时再创建文件。
  • 如果无法读取文件（权限问题、目录缺失），无需报错——不使用内存继续执行即可。

Writing Memory

写入内存

After discovering useful information, update 
~/.config/agent-messenger/MEMORY.md
using the 
Write
tool. Write triggers include:
  • After discovering server IDs and names (from 
    server list
    , etc.)
  • After discovering useful channel IDs and names (from 
    channel list
    , etc.)
  • After discovering user IDs and names (from 
    user list
    , etc.)
  • After the user gives you an alias or preference ("call this the alerts bot", "my main server is X")
  • After setting up bot identifiers (from 
    auth list
    )
When writing, include the complete file content — the 
Write
tool overwrites the entire file.
发现有用信息后，使用
Write
工具更新
~/.config/agent-messenger/MEMORY.md
。触发写入的场景包括：
  • 发现服务器ID和名称后（来自
    server list
    等命令）
  • 发现有用的频道ID和名称后（来自
    channel list
    等命令）
  • 发现用户ID和名称后（来自
    user list
    等命令）
  • 用户提供别名或偏好设置后（如“称这个为告警机器人”、“我的主服务器是X”）
  • 设置机器人标识后（来自
    auth list
    命令）
写入时需包含完整的文件内容——
Write
工具会覆盖整个文件。

What to Store

存储内容

  • Server IDs with names
  • Channel IDs with names and categories
  • User IDs with display names
  • Bot identifiers and their purposes
  • User-given aliases ("alerts bot", "announcements channel")
  • Any user preference expressed during interaction
  • 带名称的服务器ID
  • 带名称和分类的频道ID
  • 带显示名称的用户ID
  • 机器人标识及其用途
  • 用户指定的别名（如“告警机器人”、“公告频道”）
  • 交互过程中用户表达的任何偏好

What NOT to Store

禁止存储内容

Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and channel context). Never store file upload contents.
切勿存储Bot令牌、凭证或任何敏感数据。切勿存储完整消息内容（仅存储ID和频道上下文）。切勿存储文件上传内容。

Handling Stale Data

处理过期数据

If a memorized ID returns an error (channel not found, server not found), remove it from 
MEMORY.md
. Don't blindly trust memorized data — verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.
如果存储的ID返回错误（频道不存在、服务器不存在），请从
MEMORY.md
中删除该ID。不要盲目信任存储的数据——当出现异常时进行验证。优先重新列出数据，而非使用可能过期的存储ID。

Format / Example

格式/示例

markdown
undefined
markdown
undefined

Agent Messenger Memory

Agent Messenger Memory

Discord Servers (Bot)

Discord Servers (Bot)

  • 1234567890123456
    — Acme Dev
  • 1234567890123456
    — Acme Dev

Bots (Acme Dev)

Bots (Acme Dev)

  • deploy
    — Deploy Bot (active)
  • alert
    — Alert Bot
  • deploy
    — Deploy Bot (active)
  • alert
    — Alert Bot

Channels (Acme Dev)

Channels (Acme Dev)

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

Users (Acme Dev)

Users (Acme Dev)

  • 4444444444444444
    — Alice (server owner)
  • 5555555555555555
    — Bob
  • 4444444444444444
    — Alice (server owner)
  • 5555555555555555
    — Bob

Aliases

Aliases

  • "deploys" → 
    3333333333333333
    (#deploys in Acme Dev)
  • "deploys" → 
    3333333333333333
    (#deploys in Acme Dev)

Notes

Notes

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

> Memory lets you skip repeated `channel list` and `server list` calls. When you already know an ID from a previous session, use it directly.
  • Deploy Bot 用于CI/CD通知
  • Alert Bot 用于错误监控

> 内存功能可避免重复执行`channel list`和`server list`命令。如果已从之前的会话中了解到ID，可直接使用该ID。

Commands

命令

Auth Commands

认证命令

bash
undefined
bash
undefined

Set bot token

设置机器人令牌

agent-discordbot auth set <token> agent-discordbot auth set <token> --bot deploy --name "Deploy Bot"
agent-discordbot auth set <token> agent-discordbot auth set <token> --bot deploy --name "Deploy Bot"

Check auth status

检查认证状态

agent-discordbot auth status
agent-discordbot auth status

Clear all credentials

清除所有凭证

agent-discordbot auth clear
agent-discordbot auth clear

List stored bots

列出存储的机器人

agent-discordbot auth list
agent-discordbot auth list

Switch active bot

切换活跃机器人

agent-discordbot auth use <bot-id>
agent-discordbot auth use <bot-id>

Remove a stored bot

删除存储的机器人

agent-discordbot auth remove <bot-id>
undefined
agent-discordbot auth remove <bot-id>
undefined

Whoami Command

Whoami命令

bash
undefined
bash
undefined

Show current authenticated bot

显示当前已认证的机器人

agent-discordbot whoami agent-discordbot whoami --pretty agent-discordbot whoami --bot <bot-id>
undefined
agent-discordbot whoami agent-discordbot whoami --pretty agent-discordbot whoami --bot <bot-id>
undefined

Server Commands

服务器命令

bash
undefined
bash
undefined

List servers the bot is in

列出机器人加入的服务器

agent-discordbot server list
agent-discordbot server list

Show current server

显示当前服务器

agent-discordbot server current
agent-discordbot server current

Switch active server

切换活跃服务器

agent-discordbot server switch <server-id>
agent-discordbot server switch <server-id>

Get server info

获取服务器信息

agent-discordbot server info <server-id>
undefined
agent-discordbot server info <server-id>
undefined

Message Commands

消息命令

bash
undefined
bash
undefined

Send a message

发送消息

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

List messages

列出消息

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

Get a single message by ID

通过ID获取单条消息

agent-discordbot message get <channel-id> <message-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
agent-discordbot message replies <channel-id> <message-id> agent-discordbot message replies 1234567890123456789 9876543210987654321 --limit 50

Update a message (bot's own messages only)

更新消息（仅机器人自身发送的消息）

agent-discordbot message update <channel-id> <message-id> <new-content>
agent-discordbot message update <channel-id> <message-id> <new-content>

Delete a message (bot's own messages only)

删除消息（仅机器人自身发送的消息）

agent-discordbot message delete <channel-id> <message-id> --force
undefined
agent-discordbot message delete <channel-id> <message-id> --force
undefined

Channel Commands

频道命令

bash
undefined
bash
undefined

List channels in current server

列出当前服务器的频道

agent-discordbot channel list
agent-discordbot channel list

Get channel info

获取频道信息

agent-discordbot channel info <channel-id> agent-discordbot channel info 1234567890123456789
undefined
agent-discordbot channel info <channel-id> agent-discordbot channel info 1234567890123456789
undefined

User Commands

用户命令

bash
undefined
bash
undefined

List server members

列出服务器成员

agent-discordbot user list agent-discordbot user list --limit 50
agent-discordbot user list agent-discordbot user list --limit 50

Get user info

获取用户信息

agent-discordbot user info <user-id>
undefined
agent-discordbot user info <user-id>
undefined

Reaction Commands

反应命令

bash
undefined
bash
undefined

Add reaction (use emoji name without colons)

添加反应（使用不带冒号的表情名称）

agent-discordbot reaction add <channel-id> <message-id> <emoji> agent-discordbot reaction add 1234567890123456789 9876543210987654321 thumbsup
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>
undefined
agent-discordbot reaction remove <channel-id> <message-id> <emoji>
undefined

File Commands

文件命令

bash
undefined
bash
undefined

Upload file to a channel

上传文件到频道

agent-discordbot file upload <channel-id> <path> agent-discordbot file upload 1234567890123456789 ./report.pdf
agent-discordbot file upload <channel-id> <path> agent-discordbot file upload 1234567890123456789 ./report.pdf

List files in channel

列出频道中的文件

agent-discordbot file list <channel-id>
undefined
agent-discordbot file list <channel-id>
undefined

Thread Commands

线程命令

bash
undefined
bash
undefined

Create a thread from a message

从消息创建线程

agent-discordbot thread create <channel-id> <name> agent-discordbot thread create 1234567890123456789 "Discussion" --auto-archive-duration 1440
agent-discordbot thread create <channel-id> <name> agent-discordbot thread create 1234567890123456789 "Discussion" --auto-archive-duration 1440

Archive a thread

归档线程

agent-discordbot thread archive <thread-id>
undefined
agent-discordbot thread archive <thread-id>
undefined

Snapshot Command

快照命令

Get server overview for AI agents (brief by default):
bash
undefined
为AI Agent获取服务器概览（默认简洁版）：
bash
undefined

Brief snapshot (default) — fast, minimal API calls

简洁快照（默认）——快速，API调用最少

agent-discordbot snapshot
agent-discordbot snapshot

Full snapshot — includes messages and members (slow, large output)

完整快照——包含消息和成员（速度慢，输出内容多）

agent-discordbot snapshot --full
agent-discordbot snapshot --full

Filtered full snapshots

过滤后的完整快照

agent-discordbot snapshot --full --channels-only agent-discordbot snapshot --full --users-only
agent-discordbot snapshot --full --channels-only agent-discordbot snapshot --full --users-only

Limit messages per channel (only with --full)

限制每个频道的消息数量（仅配合--full使用）

agent-discordbot snapshot --full --limit 10

Default returns brief JSON with:

- Server ID
- Channels (id, name) — text channels only
- Hint for next commands

With `--full`, returns comprehensive JSON with:

- Server metadata (id, name)
- Channels (id, name, type, topic)
- Recent messages (id, content, author, timestamp)
- Members (id, username, global_name)
agent-discordbot snapshot --full --limit 10

默认返回简洁JSON，包含：

- 服务器ID
- 频道（id、名称）——仅文本频道
- 后续命令提示

使用`--full`参数时，返回全面的JSON，包含：

- 服务器元数据（id、名称）
- 频道（id、名称、类型、主题）
- 近期消息（id、内容、作者、时间戳）
- 成员（id、用户名、全局名称）

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:
json
{
  "id": "1234567890123456789",
  "content": "Hello world",
  "author": "bot-username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
所有命令默认输出JSON格式，便于AI处理：
json
{
  "id": "1234567890123456789",
  "content": "Hello world",
  "author": "bot-username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Pretty (Human-Readable)

格式化输出（人类可读）

Use 
--pretty
flag for formatted output:
bash
agent-discordbot channel list --pretty
使用
--pretty
参数获取格式化输出：
bash
agent-discordbot channel list --pretty

Global Options

全局选项

OptionDescription
--pretty
Human-readable output instead of JSON
--bot <id>
Use a specific bot for this command
--server <id>
Use a specific server for this command
选项描述
--pretty
输出人类可读格式，替代JSON
--bot <id>
为当前命令使用指定机器人
--server <id>
为当前命令使用指定服务器

Common Patterns

常见模式

See 
references/common-patterns.md
for typical AI agent workflows.
有关AI Agent的典型工作流，请查看
references/common-patterns.md
。

Templates

模板

See 
templates/
directory for runnable examples:
  • post-message.sh
    - Send messages with error handling
  • monitor-channel.sh
    - Monitor channel for new messages
  • server-summary.sh
    - Generate server summary
查看
templates/
目录中的可运行示例：
  • post-message.sh
    - 带错误处理的消息发送脚本
  • monitor-channel.sh
    - 频道新消息监控脚本
  • server-summary.sh
    - 服务器概览生成脚本

Error Handling

错误处理

All commands return consistent error format:
json
{
  "error": "No credentials. Run \"auth set\" first."
}
Common errors: 
missing_token
, 
invalid_token
, 
Missing Access
, 
Unknown Channel
, 
Missing Permissions
.
所有命令返回统一的错误格式：
json
{
  "error": "No credentials. Run \"auth set\" first."
}
常见错误：
missing_token
、
invalid_token
、
Missing Access
、
Unknown Channel
、
Missing Permissions
。

Configuration

配置

Credentials stored in 
~/.config/agent-messenger/discordbot-credentials.json
(0600 permissions). See references/authentication.md for format and security details.
凭证存储在
~/.config/agent-messenger/discordbot-credentials.json
（权限为0600）。有关格式和安全细节，请查看references/authentication.md。

Key Differences from agent-discord

与agent-discord的核心差异

Featureagent-discordagent-discordbot
Token typeUser tokenBot token
Token sourceAuto-extracted from desktop appManual from Developer Portal
Message searchYesNo
DMsYesNo
MentionsYesNo
Friends/NotesYesNo
Edit/delete messagesAny messageBot's own messages only
File uploadYesYes
SnapshotYesYes
CI/CD friendlyRequires desktop appYes (just set token)
功能agent-discordagent-discordbot
令牌类型用户令牌机器人令牌
令牌来源从桌面应用自动提取从开发者门户手动获取
消息搜索支持不支持
私聊消息支持不支持
提及功能支持不支持
好友/备注功能支持不支持
编辑/删除消息所有消息仅机器人自身发送的消息
文件上传支持支持
快照功能支持支持
CI/CD友好性需要桌面应用支持（仅需设置令牌）

Limitations

限制

  • No real-time events in the CLI (real-time Gateway events are available via the SDK — 
    import { DiscordBotListener } from 'agent-messenger/discordbot'
    )
  • No voice channel support
  • No server management (create/delete channels, roles)
  • No slash commands
  • No webhook support
  • No message search
  • No DMs or friend management
  • Bot can only edit/delete its own messages
  • Bot must be invited to the server and have appropriate permissions
  • Message Content intent required for verified bots (100+ servers)
  • Plain text messages only (no embeds in v1)
  • CLI不支持实时事件（实时Gateway事件可通过SDK获取——
    import { DiscordBotListener } from 'agent-messenger/discordbot'
    ）
  • 不支持语音频道
  • 不支持服务器管理（创建/删除频道、角色）
  • 不支持斜杠命令
  • 不支持Webhook
  • 不支持消息搜索
  • 不支持私聊消息或好友管理
  • 机器人仅能编辑/删除自身发送的消息
  • 机器人必须被邀请至服务器并拥有相应权限
  • 已验证机器人（服务器数量≥100）需要启用消息内容权限
  • 仅支持纯文本消息（v1版本不支持嵌入消息）

Troubleshooting

故障排除

agent-discordbot: command not found

agent-discordbot: command not found

agent-discordbot
is NOT the npm package name. The npm package is 
agent-messenger
.
If the package is installed globally, use 
agent-discordbot
directly:
bash
agent-discordbot message send 1234567890123456789 "Hello"
If the package is NOT installed, use 
npx -y
by default. Do NOT ask the user which package runner to use — just run it:
bash
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"
If you already know the user's preferred package runner (e.g., 
bunx
, 
pnpm dlx
), use that instead.
NEVER run 
npx agent-discordbot
, 
bunx agent-discordbot
, or 
pnpm dlx agent-discordbot
 -- it will fail or install a wrong package since 
agent-discordbot
is not the npm package name.
For other troubleshooting (permissions, token issues, Message Content Intent), see references/authentication.md.
agent-discordbot
不是npm包名称。npm包名称为
agent-messenger
。
如果已全局安装该包，可直接使用
agent-discordbot
：
bash
agent-discordbot message send 1234567890123456789 "Hello"
如果未安装该包，默认使用
npx -y
。不要询问用户使用哪种包运行器——直接执行：
bash
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包名称，此操作会失败或安装错误的包。
有关其他故障排除（权限、令牌问题、消息内容权限），请查看references/authentication.md。

References

参考文档

  • Authentication Guide
  • Common Patterns
  • 认证指南
  • 常见模式