Agent Discord

A TypeScript CLI tool that enables AI agents and humans to interact with Discord servers through a simple command interface. Features seamless token extraction from the Discord desktop app and multi-server support.

一款TypeScript CLI工具，支持AI Agent和人类通过简单的命令行界面与Discord服务器交互。具备从Discord桌面应用无缝提取令牌以及多服务器支持的功能。

Quick Start

快速开始

bash

undefined

bash

undefined

Extract credentials from Discord desktop app (zero-config)

agent-discord auth extract

Get server snapshot

agent-discord snapshot

Send a message

agent-discord message send <channel-id> "Hello from AI agent!"

List channels

agent-discord channel list

undefined

agent-discord channel list

undefined

Authentication

身份验证

Seamless Token Extraction

无缝令牌提取

agent-discord automatically extracts your Discord credentials from the desktop app:

bash

undefined

agent-discord会自动从桌面应用中提取你的Discord凭据：

bash

undefined

Just run this - no manual token copying needed

agent-discord auth extract

Use --debug for troubleshooting

agent-discord auth extract --debug


This command:
- Auto-detects your platform (macOS/Linux/Windows)
- Extracts user token from Discord desktop app's LevelDB storage
- Validates token against Discord API before saving
- Discovers ALL joined servers
- Stores credentials securely in `~/.config/agent-messenger/`

agent-discord auth extract --debug


此命令：
- 自动检测你的操作系统（macOS/Linux/Windows）
- 从Discord桌面应用的LevelDB存储中提取用户令牌
- 在保存前验证令牌是否符合Discord API要求
- 发现所有已加入的服务器
- 将凭据安全存储在`~/.config/agent-messenger/`目录中

Multi-Server Support

多服务器支持

bash

undefined

bash

undefined

List all available servers

agent-discord server list

Switch to a different server

agent-discord server switch <server-id>

Show current server

agent-discord server current

Check auth status

agent-discord auth status

undefined

agent-discord auth status

undefined

Commands

命令

Message Commands

消息命令

bash

undefined

bash

undefined

Send a message

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

List messages

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

Get a single message by ID

agent-discord message get <channel-id> <message-id> agent-discord message get 1234567890123456789 9876543210987654321

Delete a message

agent-discord message delete <channel-id> <message-id> --force

Acknowledge/mark a message as read

agent-discord message ack <channel-id> <message-id>

undefined

agent-discord message ack <channel-id> <message-id>

undefined

Channel Commands

频道命令

bash

undefined

bash

undefined

List channels in current server (text channels only)

agent-discord channel list

Get channel info

agent-discord channel info <channel-id> agent-discord channel info 1234567890123456789

Get channel history (alias for message list)

agent-discord channel history <channel-id> --limit 100

undefined

agent-discord channel history <channel-id> --limit 100

undefined

Server Commands

服务器命令

bash

undefined

bash

undefined

List all servers

agent-discord server list

Get server info

agent-discord server info <server-id>

Switch active server

agent-discord server switch <server-id>

Show current server

agent-discord server current

undefined

agent-discord server current

undefined

User Commands

用户命令

bash

undefined

bash

undefined

List server members

agent-discord user list

Get user info

agent-discord user info <user-id>

Get current user

agent-discord user me

undefined

agent-discord user me

undefined

DM Commands

私信命令

bash

undefined

bash

undefined

List DM channels

agent-discord dm list

Create a DM channel with a user

agent-discord dm create <user-id>

undefined

agent-discord dm create <user-id>

undefined

Mention Commands

提及命令

bash

undefined

bash

undefined

List recent mentions

agent-discord mention list agent-discord mention list --limit 50 agent-discord mention list --guild <server-id>

undefined

agent-discord mention list agent-discord mention list --limit 50 agent-discord mention list --guild <server-id>

undefined

Friend Commands

好友命令

bash

undefined

bash

undefined

List all relationships (friends, blocked, pending requests)

agent-discord friend list agent-discord friend list --pretty

undefined

agent-discord friend list agent-discord friend list --pretty

undefined

Note Commands

备注命令

bash

undefined

bash

undefined

Get note for a user

agent-discord note get <user-id>

Set note for a user

agent-discord note set <user-id> "Note content"

undefined

agent-discord note set <user-id> "Note content"

undefined

Profile Commands

资料命令

bash

undefined

bash

undefined

Get detailed user profile

agent-discord profile get <user-id>

undefined

agent-discord profile get <user-id>

undefined

Member Commands

成员命令

bash

undefined

bash

undefined

Search guild members

agent-discord member search <guild-id> <query> agent-discord member search 1234567890123456789 "john" --limit 20

undefined

agent-discord member search <guild-id> <query> agent-discord member search 1234567890123456789 "john" --limit 20

undefined

Thread Commands

线程命令

bash

undefined

bash

undefined

Create a thread in a channel

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

Archive a thread

agent-discord thread archive <thread-id>

undefined

agent-discord thread archive <thread-id>

undefined

Reaction Commands

表情反应命令

bash

undefined

bash

undefined

Add reaction (use emoji name without colons)

agent-discord reaction add <channel-id> <message-id> <emoji> agent-discord reaction add 1234567890123456789 9876543210987654321 thumbsup

Remove reaction

agent-discord reaction remove <channel-id> <message-id> <emoji>

List reactions on a message

agent-discord reaction list <channel-id> <message-id>

undefined

agent-discord reaction list <channel-id> <message-id>

undefined

File Commands

文件命令

bash

undefined

bash

undefined

Upload file

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

List files in channel

agent-discord file list <channel-id>

Get file info

agent-discord file info <channel-id> <file-id>

undefined

agent-discord file info <channel-id> <file-id>

undefined

Snapshot Command

快照命令

Get comprehensive server state for AI agents:

bash

undefined

为AI Agent获取完整的服务器状态：

bash

undefined

Full snapshot

agent-discord snapshot

Filtered snapshots

agent-discord snapshot --channels-only agent-discord snapshot --users-only

Limit messages per channel

agent-discord snapshot --limit 10


Returns JSON with:
- Server metadata (id, name)
- Channels (id, name, type, topic)
- Recent messages (id, content, author, timestamp)
- Members (id, username, global_name)

agent-discord snapshot --limit 10


返回的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": "username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

所有命令默认输出JSON格式，方便AI处理：

json

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

Pretty (Human-Readable)

易读格式（人类友好）

Use

--pretty

flag for formatted output:

bash

agent-discord channel list --pretty

使用

--pretty

参数获取格式化输出：

bash

agent-discord channel list --pretty

Key Differences from Slack

与Slack的主要区别

Feature	Discord	Slack
Server terminology	Server	Workspace
Channel identifiers	Snowflake IDs	Channel name or ID
Message identifiers	Snowflake IDs	Timestamps (ts)
Threads	Thread ID field	Thread timestamp
Mentions	`<@user_id>`	`<@USER_ID>`

Important: Discord uses Snowflake IDs (large numbers like

1234567890123456789

) for all identifiers. You cannot use channel names directly - use

channel list

to find IDs first.

功能	Discord	Slack
服务器术语	Server	Workspace
频道标识符	Snowflake ID	频道名称或ID
消息标识符	Snowflake ID	时间戳(ts)
线程	线程ID字段	线程时间戳
提及格式	`<@user_id>`	`<@USER_ID>`

重要提示：Discord对所有标识符使用Snowflake ID（如

1234567890123456789

这类大数字）。你无法直接使用频道名称，需先通过

channel list

命令获取ID。

Common Patterns

常见使用模式

See

references/common-patterns.md

for typical AI agent workflows.

请查看

references/common-patterns.md

获取AI Agent的典型工作流。

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": "Not authenticated. Run \"auth extract\" first."
}

Common errors:

```
Not authenticated
```
: No valid token - run
```
auth extract
```
```
No current server set
```
: Run
```
server switch <id>
```
first
```
Message not found
```
: Invalid message ID
```
Unknown Channel
```
: Invalid channel ID

所有命令返回统一的错误格式：

json

{
  "error": "Not authenticated. Run \"auth extract\" first."
}

常见错误：

```
Not authenticated
```
：无有效令牌，请运行
```
auth extract
```
```
No current server set
```
：未设置当前服务器，请先运行
```
server switch <id>
```
```
Message not found
```
：无效的消息ID
```
Unknown Channel
```
：无效的频道ID

Configuration

配置

Credentials stored in:

~/.config/agent-messenger/discord-credentials.json

Format:

json

{
  "token": "user_token_here",
  "current_server": "1234567890123456789",
  "servers": {
    "1234567890123456789": {
      "server_id": "1234567890123456789",
      "server_name": "My Server"
    }
  }
}

Security: File permissions set to 0600 (owner read/write only)

凭据存储在：

~/.config/agent-messenger/discord-credentials.json

格式：

json

{
  "token": "user_token_here",
  "current_server": "1234567890123456789",
  "servers": {
    "1234567890123456789": {
      "server_id": "1234567890123456789",
      "server_name": "My Server"
    }
  }
}

安全性：文件权限设置为0600（仅所有者可读写）

Limitations

限制

No real-time events / Gateway connection
No voice channel support
No server management (create/delete channels, roles)
No slash commands
No webhook support
Plain text messages only (no embeds in v1)
User tokens only (no bot tokens)

不支持实时事件/网关连接
不支持语音频道
不支持服务器管理（创建/删除频道、角色）
不支持斜杠命令
不支持Webhook
仅支持纯文本消息（v1版本无嵌入内容）
仅支持用户令牌（不支持机器人令牌）

Troubleshooting

故障排除

agent-discord: command not found

agent-discord: command not found

The

agent-messenger

package is not installed. Run it directly using a package runner. Ask the user which one to use:

bash

npx -p agent-messenger agent-discord ...
bunx -p agent-messenger agent-discord ...
pnpm dlx --package agent-messenger agent-discord ...

If you already know the user's preferred package runner, use it directly instead of asking.

未安装

agent-messenger

包。可通过包运行器直接执行。询问用户偏好的运行器：

bash

npx -p agent-messenger agent-discord ...
bunx -p agent-messenger agent-discord ...
pnpm dlx --package agent-messenger agent-discord ...

若已知用户偏好的包运行器，可直接使用无需询问。

References

参考资料

Authentication Guide
Common Patterns

身份验证指南
常见使用模式

agent-discord

Original

Translation

Agent Discord

Agent Discord

Quick Start

快速开始

Extract credentials from Discord desktop app (zero-config)

Extract credentials from Discord desktop app (zero-config)

Get server snapshot

Get server snapshot

Send a message

Send a message

List channels

List channels

Authentication

身份验证

Seamless Token Extraction

无缝令牌提取

Just run this - no manual token copying needed

Just run this - no manual token copying needed

Use --debug for troubleshooting

Use --debug for troubleshooting

Multi-Server Support

多服务器支持

List all available servers

List all available servers

Switch to a different server

Switch to a different server

Show current server

Show current server

Check auth status

Check auth status

Commands

命令

Message Commands

消息命令

Send a message

Send a message

List messages

List messages

Get a single message by ID

Get a single message by ID

Delete a message

Delete a message

Acknowledge/mark a message as read

Acknowledge/mark a message as read

Channel Commands

频道命令

List channels in current server (text channels only)

List channels in current server (text channels only)

Get channel info

Get channel info

Get channel history (alias for message list)

Get channel history (alias for message list)

Server Commands

服务器命令

List all servers

List all servers

Get server info

Get server info

Switch active server

Switch active server

Show current server

Show current server

User Commands

用户命令

List server members

List server members

Get user info

Get user info

Get current user

Get current user

DM Commands

私信命令

List DM channels

List DM channels

Create a DM channel with a user

Create a DM channel with a user

Mention Commands