Disclaw — Discord Structure as Code

Disclaw manages Discord workspace structure (categories, channels, threads) and OpenClaw agent-to-channel bindings as code via a YAML config file.

Disclaw vs Discord plugin: Disclaw manages structure (create/rename/delete channels, categories, threads; manage bindings and routing gates). The Discord plugin manages messaging (send/receive, reactions, pins, thread replies). They do not conflict.

Installation

CODEBLOCK0

Prerequisites

1. 1. Discord bot token must be in OpenClaw config at INLINECODE0
2. Gateway API access — add to openclaw.json:

   { gateway: { tools: { allow: ["gateway"] } } }
   

1. 3. Config file — create disclaw.yaml in the workspace (see format below)

Verify Setup

CODEBLOCK2

Config File Format

The config file (disclaw.yaml) declares the desired state of Discord workspace structure.

CODEBLOCK3

Key rules

• - guild is the Discord server ID (right-click server → Copy Server ID)
• Channel names must be lowercase, no spaces (Discord enforces this)
• Thread names can have spaces and mixed case
• Agent bindings reference channel names from the channels section
• INLINECODE6 controls whether the bot needs @mention to respond in that channel

Commands

disclaw diff — Show what would change

CODEBLOCK4

Shows: managed resources (create/update/delete/noop), unmanaged resources, unbound agents, stale agents, routing health warnings, and pinned messages.

disclaw apply — Apply changes (dry-run by default)

CODEBLOCK5

Safety: Always takes a snapshot before mutating. Creates before deletes. Bindings and routing gates are updated atomically.

disclaw import — Import unmanaged Discord resources

CODEBLOCK6

Discovers Discord channels/categories/threads not in the config and adds them. Also finds unbound OpenClaw agents.

disclaw rollback — Restore from snapshot

CODEBLOCK7

Restores Discord state from the most recent pre-apply snapshot. Drift-aware (shows what changed since the snapshot).

disclaw validate — Validate config (no API calls)

CODEBLOCK8

Safe for CI. Checks: schema validity, empty names, duplicate channels/threads, binding refs pointing to non-existent channels.

Filter flags (diff, apply, import)

CODEBLOCK9

Gateway options (all commands except validate)

CODEBLOCK10

Also via env vars: OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN.

Common Workflows

Add a new channel

1. 1. Edit disclaw.yaml — add channel under the appropriate category
2. Validate: INLINECODE15
3. Preview: INLINECODE16
4. Apply: INLINECODE17

Bind an agent to a channel

1. 1. Edit disclaw.yaml — add entry under INLINECODE19
2. Preview: INLINECODE20
3. Apply: INLINECODE21

This creates the binding AND allowlists the channel in routing gates automatically.

Import existing Discord channels

1. 1. Run: disclaw import -c disclaw.yaml (dry-run to preview)
2. Review the output
3. Run: disclaw import -c disclaw.yaml --yes (writes to config)
4. Verify: INLINECODE24

Delete a channel

1. 1. Remove the channel from INLINECODE25
2. Preview: INLINECODE26
3. Apply: INLINECODE27

Warning: --prune is required for deletions. Without it, removed channels are shown as "unmanaged" but not deleted.

Rename a channel

1. 1. Change the channel name in INLINECODE29
2. Preview: disclaw diff -c disclaw.yaml (shows delete old + create new)
3. Apply: INLINECODE31

Note: Discord doesn't support true renames via API — disclaw creates the new channel and (with --prune) deletes the old one.

Troubleshooting

"Discord bot token not found"

• - Ensure channels.discord.token is set in INLINECODE34
• Or set DISCORD_BOT_TOKEN env var

"Gateway tool not available"

• - Add gateway.tools.allow: ["gateway"] to INLINECODE37
• Or disclaw will fall back to CLI automatically

"Gateway auth failed"

• - Check OPENCLAW_GATEWAY_TOKEN env var matches gateway.auth.token in config
• Or pass INLINECODE40

"OpenClaw CLI timed out"

• - Check if the gateway is running: INLINECODE41
• Check network: INLINECODE42

"Discord connection timed out"

• - Check internet connectivity
• Verify bot token is valid
• Try again (Discord API can be flaky)

"Permission denied" during apply

• - Bot needs: Manage Channels, Manage Threads permissions
• Check bot role position in Discord server settings

Safety

• - Dry-run by default — all mutating commands require INLINECODE43
• Snapshot before apply — automatic, saved to INLINECODE44
• Rollback available — INLINECODE45
• Managed-scope only — disclaw only touches resources in the config
• Creates before deletes — safer ordering during apply
• Validation — config is validated before any API calls