Dirigent/docs/DISCORD_CONTROL.md

Discord Control API

目标：补齐 OpenClaw 内置 message 工具当前未覆盖的两个能力：

1. 创建指定名单可见的私人频道
2. 查看 server 成员列表（分页）

Start

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'
node server.mjs

Health:

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

{
  "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

{
  "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

{
  "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 选子字段

---

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 并透传错误细节。