151 lines
3.5 KiB
Markdown
151 lines
3.5 KiB
Markdown
# Discord Control API
|
||
|
||
目标：补齐 OpenClaw 内置 message 工具当前未覆盖的两个能力：
|
||
|
||
> 现在可以通过 WhisperGate 插件内置的可选工具 `discord_control` 直接调用（无需手写 curl）。
|
||
> 注意：该工具是 optional，需要在 agent tools allowlist 中显式允许（例如允许 `whispergate` 或 `discord_control`）。
|
||
|
||
1. 创建指定名单可见的私人频道
|
||
2. 查看 server 成员列表（分页）
|
||
|
||
## Start
|
||
|
||
```bash
|
||
cd discord-control-api
|
||
export DISCORD_BOT_TOKEN='xxx'
|
||
# 建议启用
|
||
export AUTH_TOKEN='strong-token'
|
||
# optional hard requirement
|
||
# export REQUIRE_AUTH_TOKEN=true
|
||
# optional action gates
|
||
# export ENABLE_CHANNEL_PRIVATE_CREATE=true
|
||
# export ENABLE_CHANNEL_PRIVATE_UPDATE=true
|
||
# export ENABLE_MEMBER_LIST=true
|
||
# optional allowlist
|
||
# export ALLOWED_GUILD_IDS='123,456'
|
||
# export ALLOWED_CALLER_IDS='agent-main,agent-admin'
|
||
# optional limits
|
||
# export MAX_MEMBER_FIELDS=20
|
||
# export MAX_MEMBER_RESPONSE_BYTES=500000
|
||
# export MAX_PRIVATE_MUTATION_TARGETS=200
|
||
node server.mjs
|
||
```
|
||
|
||
Health:
|
||
|
||
```bash
|
||
curl -sS http://127.0.0.1:8790/health
|
||
```
|
||
|
||
## Unified action endpoint
|
||
|
||
`POST /v1/discord/action`
|
||
|
||
- Header: `Authorization: Bearer <AUTH_TOKEN>`（若配置）
|
||
- Header: `X-OpenClaw-Caller-Id: <id>`（若配置了 `ALLOWED_CALLER_IDS`）
|
||
- Body: `{ "action": "...", ... }`
|
||
|
||
---
|
||
|
||
## Action: channel-private-create
|
||
|
||
与 OpenClaw `channel-create` 参数保持风格一致，并增加私密覆盖参数。
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"action": "channel-private-create",
|
||
"guildId": "123",
|
||
"name": "private-room",
|
||
"type": 0,
|
||
"parentId": "456",
|
||
"topic": "secret",
|
||
"position": 3,
|
||
"nsfw": false,
|
||
"allowedUserIds": ["111", "222"],
|
||
"allowedRoleIds": ["333"],
|
||
"allowMask": "67648",
|
||
"denyEveryoneMask": "1024",
|
||
"dryRun": false
|
||
}
|
||
```
|
||
|
||
说明：
|
||
- 默认 deny `@everyone` 的 `VIEW_CHANNEL`。
|
||
- 默认给 allowed targets 放行：`VIEW_CHANNEL + SEND_MESSAGES + READ_MESSAGE_HISTORY`。
|
||
- `allowMask/denyEveryoneMask` 使用 Discord permission bit string。
|
||
|
||
---
|
||
|
||
## Action: channel-private-update
|
||
|
||
对现有频道的白名单/覆盖权限做增删改。
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"action": "channel-private-update",
|
||
"guildId": "123",
|
||
"channelId": "789",
|
||
"mode": "merge",
|
||
"addUserIds": ["111"],
|
||
"addRoleIds": ["333"],
|
||
"removeTargetIds": ["222"],
|
||
"allowMask": "67648",
|
||
"denyMask": "0",
|
||
"dryRun": false
|
||
}
|
||
```
|
||
|
||
说明：
|
||
- `mode=merge`：在现有覆盖基础上增删
|
||
- `mode=replace`：重建覆盖（保留/补上 @everyone deny）
|
||
|
||
---
|
||
|
||
## Action: member-list
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"action": "member-list",
|
||
"guildId": "123",
|
||
"limit": 100,
|
||
"after": "0",
|
||
"fields": ["user.id", "user.username", "nick", "roles", "joined_at"]
|
||
}
|
||
```
|
||
|
||
说明：
|
||
- `limit` 1~1000
|
||
- `after` 用于分页（Discord snowflake）
|
||
- `fields` 可选：字段裁剪，减小返回体；可用 `user.xxx` 选子字段
|
||
|
||
---
|
||
|
||
## Curl examples
|
||
|
||
示例文件：`docs/EXAMPLES.discord-control.json`
|
||
|
||
快速检查脚本：
|
||
|
||
```bash
|
||
./scripts/smoke-discord-control.sh
|
||
# with env
|
||
# AUTH_TOKEN=xxx CALLER_ID=agent-main GUILD_ID=123 CHANNEL_ID=456 ./scripts/smoke-discord-control.sh
|
||
```
|
||
|
||
## Notes
|
||
|
||
鉴权与内置风格对齐（简化版）：
|
||
- 控制面 token：`AUTH_TOKEN` / `REQUIRE_AUTH_TOKEN`
|
||
- 调用者 allowlist：`ALLOWED_CALLER_IDS`（配合 `X-OpenClaw-Caller-Id`）
|
||
- action gate：`ENABLE_CHANNEL_PRIVATE_CREATE` / `ENABLE_MEMBER_LIST`
|
||
- guild allowlist：`ALLOWED_GUILD_IDS`
|
||
|
||
- 这不是 bot 自提权工具；bot 仍需由管理员授予足够权限。
|
||
- 若无权限，Discord API 会返回 403 并透传错误细节。
|