discord-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Discord API Skill

Use this skill to run Discord REST operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, auth, and error-handling guidance.

使用此技能通过

uxc

+ OpenAPI执行Discord REST操作。

复用

uxc

技能以实现共享执行、认证和错误处理指导。

Prerequisites

前提条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to
```
https://discord.com/api/v10
```
.

Access to Discord OpenAPI spec URL:

https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json

Discord bot token (recommended) or OAuth2 user authentication (limited functionality).

```
uxc
```
已安装并可在
```
PATH
```
中调用。
可访问
```
https://discord.com/api/v10
```
网络。

可访问Discord OpenAPI规范URL：

https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json

Discord Bot令牌（推荐）或OAuth2用户认证（功能受限）。

Authentication

认证方式

Option 1: Bot Token (Recommended)

选项1：Bot令牌（推荐）

Bot token provides full access to Discord API including reading messages, managing servers, sending messages, and all administrative operations. This is the recommended method for most use cases.

Create a bot application at https://discord.com/developers/applications
Generate a bot token from the Bot section
Configure bot credential:

bash

uxc auth credential set discord-bot \
  --auth-type api_key \
  --header "Authorization=Bot {{secret}}" \
  --secret "YOUR_BOT_TOKEN_HERE"

Bind credential to Discord API endpoint:

bash

uxc auth binding add \
  --id discord-bot \
  --host discord.com \
  --path-prefix /api/v10 \
  --scheme https \
  --credential discord-bot \
  --priority 100

Bot令牌可提供Discord API的完整访问权限，包括读取消息、管理服务器、发送消息及所有管理操作。这是大多数场景下的推荐方式。

在https://discord.com/developers/applications创建Bot应用
在Bot板块生成Bot令牌
配置Bot凭证：

bash

uxc auth credential set discord-bot \
  --auth-type api_key \
  --header "Authorization=Bot {{secret}}" \
  --secret "YOUR_BOT_TOKEN_HERE"

将凭证绑定到Discord API端点：

bash

uxc auth binding add \
  --id discord-bot \
  --host discord.com \
  --path-prefix /api/v10 \
  --scheme https \
  --credential discord-bot \
  --priority 100

Option 2: OAuth2 User Authentication (Limited Use Cases)

选项2：OAuth2用户认证（仅限特定场景）

Important: User OAuth2 has significant limitations and is not recommended for most operations:

❌ Cannot read channel messages via HTTP API (local RPC only)
❌ Cannot send messages or manage servers
✅ Can read user profile, email, connections
✅ Can list user's servers

Only use OAuth2 if you specifically need to access user profile information as the user. For all other operations, use Bot Token.

If you still need OAuth2 for user profile operations:

Configuration:

Client ID:
```
1479302369723285736
```
Redirect URI:
```
http://127.0.0.1:11111/callback
```

OAuth2 Scopes:

Discord user OAuth2 supports read-only operations. It cannot send messages or manage servers as a user (use Bot Token for those operations).

Recommended Scopes (Full Functionality):

bash

--scope "identify email connections guilds guilds.members.read messages.read openid"

Minimal Read-Only Scopes:

bash

--scope "identify email connections guilds guilds.members.read"

Scope Reference:

Scope	Description	Write Operation
`identify`	Basic user info (username, avatar, etc.)	❌ Read
`email`	User's email address	❌ Read
`connections`	Linked third-party accounts (Twitch, YouTube, etc.)	❌ Read
`guilds`	User's server list	❌ Read
`guilds.join`	Join user to servers (requires the same application's bot to already be in that guild)	✅ Write
`guilds.members.read`	User's member info in servers	❌ Read
`messages.read`	Read messages (local RPC only, not HTTP API)	❌ Read
`openid`	OpenID Connect support	❌ Read

Note: User OAuth2 cannot send messages or manage servers as the user. Use Bot Token for write operations.

guilds.join

is a special user OAuth write capability that depends on the same application's bot already being in the target guild, so it is not part of the default read-only flow. See Discord OAuth2 documentation for complete scope list.

Two-Stage OAuth Flow (Agent-Friendly):

Start OAuth flow with desired scopes:

bash

uxc auth oauth start discord-user \
  --endpoint https://discord.com/api/oauth2/token \
  --client-id 1479302369723285736 \
  --redirect-uri http://127.0.0.1:11111/callback \
  --scope "identify email connections guilds guilds.members.read messages.read openid"

Open the displayed authorization URL in browser, complete authorization, then copy the callback URL from browser address bar.
Complete OAuth flow:

bash

uxc auth oauth complete discord-user \
  --session-id <session_id_from_step_1> \
  --authorization-response "<callback_url_from_browser>"

Bind credential:

bash

uxc auth binding add \
  --id discord-user \
  --host discord.com \
  --path-prefix /api/v10 \
  --scheme https \
  --credential discord-user \
  --priority 100

Interactive Alternative (Local Terminal Only):

bash

uxc auth oauth login discord-user \
  --endpoint https://discord.com/api/oauth2/token \
  --flow authorization_code \
  --client-id 1479302369723285736 \
  --redirect-uri http://127.0.0.1:11111/callback \
  --scope "identify email connections guilds guilds.members.read messages.read openid"

Then paste the callback URL when prompted.

重要提示： 用户OAuth2存在显著限制，不推荐用于大多数操作：

❌ 无法通过HTTP API读取频道消息（仅支持本地RPC）
❌ 无法发送消息或管理服务器
✅ 可读取用户资料、邮箱、关联账号
✅ 可列出用户的服务器

仅当你需要以用户身份访问其个人资料信息时才使用OAuth2。所有其他操作请使用Bot令牌。

如果你仍需使用OAuth2进行用户资料操作：

配置信息：

Client ID:
```
1479302369723285736
```
Redirect URI:
```
http://127.0.0.1:11111/callback
```

OAuth2权限范围：

Discord用户OAuth2仅支持只读操作。无法以用户身份发送消息或管理服务器（此类操作请使用Bot令牌）。

推荐权限范围（完整功能）：

bash

--scope "identify email connections guilds guilds.members.read messages.read openid"

最小只读权限范围：

bash

--scope "identify email connections guilds guilds.members.read"

权限范围说明：

权限范围	描述	写入操作
`identify`	基础用户信息（用户名、头像等）	❌ 只读
`email`	用户邮箱地址	❌ 只读
`connections`	关联的第三方账号（Twitch、YouTube等）	❌ 只读
`guilds`	用户的服务器列表	❌ 只读
`guilds.join`	将用户加入服务器（要求同一应用的Bot已在该服务器中）	✅ 写入
`guilds.members.read`	用户在服务器中的成员信息	❌ 只读
`messages.read`	读取消息（仅本地RPC，不支持HTTP API）	❌ 只读
`openid`	OpenID Connect支持	❌ 只读

注意： 用户OAuth2无法以用户身份发送消息或管理服务器。写入操作请使用Bot令牌。

guilds.join

是特殊的用户OAuth写入权限，依赖于同一应用的Bot已在目标服务器中，因此不属于默认只读流程。完整权限范围列表请查看Discord OAuth2文档。

两步式OAuth流程（Agent友好型）：

启动带有指定权限范围的OAuth流程：

bash

uxc auth oauth start discord-user \
  --endpoint https://discord.com/api/oauth2/token \
  --client-id 1479302369723285736 \
  --redirect-uri http://127.0.0.1:11111/callback \
  --scope "identify email connections guilds guilds.members.read messages.read openid"

在浏览器中打开显示的授权URL，完成授权后，从浏览器地址栏复制回调URL。
完成OAuth流程：

bash

uxc auth oauth complete discord-user \
  --session-id <session_id_from_step_1> \
  --authorization-response "<callback_url_from_browser>"

绑定凭证：

bash

uxc auth binding add \
  --id discord-user \
  --host discord.com \
  --path-prefix /api/v10 \
  --scheme https \
  --credential discord-user \
  --priority 100

交互式替代方案（仅限本地终端）：

bash

uxc auth oauth login discord-user \
  --endpoint https://discord.com/api/oauth2/token \
  --flow authorization_code \
  --client-id 1479302369723285736 \
  --redirect-uri http://127.0.0.1:11111/callback \
  --scope "identify email connections guilds guilds.members.read messages.read openid"

然后在提示时粘贴回调URL。

Core Workflow

核心工作流程

Use fixed link command by default:

```
command -v discord-openapi-cli
```

If missing, create it:

uxc link discord-openapi-cli https://discord.com/api/v10 --schema-url https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json

```
discord-openapi-cli -h
```

Discover operations with schema mapping:
- ```
discord-openapi-cli -h
```

Inspect operation schema first:

```
discord-openapi-cli get:/users/@me -h
```

discord-openapi-cli post:/channels/{channel_id}/messages -h

Execute operation:

connectivity check (no auth):
```
discord-openapi-cli get:/gateway
```

key/value:

discord-openapi-cli get:/guilds/{guild_id}/channels guild_id=GUILD_ID

positional JSON:

discord-openapi-cli post:/channels/{channel_id}/messages '{"channel_id":"CHANNEL_ID","content":"Hello from uxc"}'

binding check when auth looks wrong:

uxc auth binding match https://discord.com/api/v10

默认使用固定链接命令：

```
command -v discord-openapi-cli
```

如果不存在，创建链接：

uxc link discord-openapi-cli https://discord.com/api/v10 --schema-url https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json

```
discord-openapi-cli -h
```

通过架构映射发现操作：
- ```
discord-openapi-cli -h
```

先检查操作架构：

```
discord-openapi-cli get:/users/@me -h
```

discord-openapi-cli post:/channels/{channel_id}/messages -h

执行操作：

连通性检查（无需认证）：
```
discord-openapi-cli get:/gateway
```

键值对参数：

discord-openapi-cli get:/guilds/{guild_id}/channels guild_id=GUILD_ID

位置式JSON：

discord-openapi-cli post:/channels/{channel_id}/messages '{"channel_id":"CHANNEL_ID","content":"Hello from uxc"}'

认证异常时检查绑定：

uxc auth binding match https://discord.com/api/v10

Authentication Methods Comparison

认证方式对比

Feature	Bot Token	User OAuth2
Read channel messages	✅ Full access	❌ Not via HTTP API
Send messages	✅ As the bot	❌ Not supported
Manage channels/roles	✅ Bot permissions	❌ Not supported
Moderation actions	✅ Bot permissions	❌ Not supported
List servers	✅ Servers bot is in	✅ User's servers
Read user info	❌ Not available	✅ As the user
Message appearance	Bot badge "BOT"	N/A

Key Recommendation: Use Bot Token for almost all operations. User OAuth2 is only useful if you need to read user profile information as that specific user. For reading channel messages, managing servers, or sending messages, Bot Token is required.

功能	Bot令牌	用户OAuth2
读取频道消息	✅ 完整权限	❌ 不支持HTTP API
发送消息	✅ 以Bot身份	❌ 不支持
管理频道/角色	✅ Bot权限	❌ 不支持
moderation actions	✅ Bot权限	❌ 不支持
列出服务器	✅ Bot所在服务器	✅ 用户的服务器
读取用户信息	❌ 不可用	✅ 以用户身份
消息显示	带有「BOT」标识	无

核心建议： 几乎所有操作都使用Bot令牌。仅当你需要以特定用户身份读取其个人资料信息时，才使用用户OAuth2。读取频道消息、管理服务器或发送消息必须使用Bot令牌。

Subscribe / Gateway Status

订阅/网关状态

Discord inbound events flow through the Gateway WebSocket, not through this REST/OpenAPI surface.

Current

uxc subscribe

status:

the built-in
```
discord-gateway
```
transport now bootstraps through
```
GET /gateway/bot
```
live Gateway sessions reached
```
READY
```
and delivered
```
GUILD_CREATE
```
a real posted channel message produced a
```
MESSAGE_CREATE
```
event in the subscribe sink
heartbeat scheduling,
```
IDENTIFY
```
, sequence tracking, and reconnect handling are implemented

Recommended invocation:

bash

uxc subscribe start https://discord.com/api/v10 \
  '{"intents":4609,"device":"uxc-discord"}' \
  --transport discord-gateway \
  --auth discord-bot \
  --sink file:$HOME/.uxc/subscriptions/discord-gateway.ndjson

Intent notes:

GUILDS | GUILD_MESSAGES | DIRECT_MESSAGES

add
```
32768
```
(
```
MESSAGE_CONTENT
```
) only when the bot has that privileged intent enabled in the Discord developer portal

Use

discord-openapi-cli

for REST calls and

uxc subscribe start ... --transport discord-gateway ...

for inbound Gateway events.

Discord入站事件通过Gateway WebSocket传输，而非此REST/OpenAPI接口。

当前

uxc subscribe

状态：

内置的
```
discord-gateway
```
传输现在通过
```
GET /gateway/bot
```
启动
实时Gateway会话已达到
```
READY
```
状态并推送
```
GUILD_CREATE
```
事件
实际发送的频道消息会在订阅接收器中生成
```
MESSAGE_CREATE
```
事件
已实现心跳调度、
```
IDENTIFY
```
、序列跟踪和重连处理

推荐调用方式：

bash

uxc subscribe start https://discord.com/api/v10 \
  '{"intents":4609,"device":"uxc-discord"}' \
  --transport discord-gateway \
  --auth discord-bot \
  --sink file:$HOME/.uxc/subscriptions/discord-gateway.ndjson

权限范围说明：

GUILDS | GUILD_MESSAGES | DIRECT_MESSAGES

仅当Bot在Discord开发者门户中启用了该特权权限范围时，才添加
```
32768
```
（
```
MESSAGE_CONTENT
```
）

使用

discord-openapi-cli

进行REST调用，使用

uxc subscribe start ... --transport discord-gateway ...

接收入站Gateway事件。

Guardrails

注意事项

OAuth2 Scope Limitation: User OAuth2 tokens cannot read channel messages via HTTP API, send messages, or manage servers. These operations require Bot Token authentication.
Discord OpenAPI spec is persisted in the generated link via
```
uxc link --schema-url ...
```
; pass
```
--schema-url <other-url>
```
only when you need to override it temporarily.
Keep automation on JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
Prefer positional JSON for non-string objects instead of
```
--input-json
```
.

discord-openapi-cli <operation> ...

is equivalent to

uxc https://discord.com/api/v10 --schema-url <discord_openapi_spec> <operation> ...

Treat
```
post:/channels/{channel_id}/messages
```
, delete/update endpoints, and moderation endpoints as write/high-risk operations; require explicit user confirmation before execution.

OAuth2权限范围限制： 用户OAuth2令牌无法通过HTTP API读取频道消息、发送消息或管理服务器。这些操作需要Bot令牌认证。
Discord OpenAPI规范通过
```
uxc link --schema-url ...
```
持久化在生成的链接中；仅当需要临时覆盖时才传入
```
--schema-url <other-url>
```
。
自动化操作请使用JSON输出格式；不要使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
。
对于非字符串对象，优先使用位置式JSON而非
```
--input-json
```
。

discord-openapi-cli <operation> ...

等价于

uxc https://discord.com/api/v10 --schema-url <discord_openapi_spec> <operation> ...

。

将
```
post:/channels/{channel_id}/messages
```
、删除/更新端点和 moderation 端点视为写入/高风险操作；执行前需要用户明确确认。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```
Discord API docs: https://discord.com/developers/docs
Discord API OpenAPI spec: https://github.com/discord/discord-api-spec

使用模式：
```
references/usage-patterns.md
```
Discord API文档：https://discord.com/developers/docs
Discord API OpenAPI规范：https://github.com/discord/discord-api-spec