discord-agent-setup

name	discord-agent-setup
description	Set up and troubleshoot Discord-connected automation agents when facing environmental constraints or connection issues
category	social-media

Discord Automation Agent Setup and Troubleshooting

When to Use This Skill

When you need to deploy an automation agent that communicates via Discord but face:

• Environmental constraints preventing preferred agent installation (e.g., password restrictions, lack of permissions)
• Connection issues between agent and Discord (bot not responding, permission errors)
• Need to maintain progress toward automation goals while debugging connection problems
• Situations where the bot appears connected but isn't functioning correctly in the target environment

Step-by-Step Approach

1. Assess Environmental Constraints

• Identify what prevents installing your preferred automation agent (e.g., Hermes)
• Common constraints: lack of admin/password rights, corporate policies, incompatible OS versions
• Document the specific constraint clearly

2. Select Compatible Alternative Agent

• Choose an agent that works within your environmental constraints
• Examples: OpenClaw Mini Max when Hermes cannot be installed due to password restrictions
• Verify the alternative agent supports Discord integration via bot tokens
• Confirm it can perform the core automation tasks you need (pasting text, clicking elements, etc.)

3. Attempt Discord Connection

• Obtain/create a Discord bot token from Discord Developer Portal
• Configure the agent with the bot token
• Generate an OAuth2 invite link with necessary permissions:
  • bot scope
  • Permissions: Send Messages, Read Message History, View Channels (at minimum)
  • Calculate permissions value: Send Messages (1) + Read Message History (4096) + View Channels (1024) = 5121
  • URL format: https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=5121&scope=bot
• Invite the bot to your target Discord server/channel

4. Troubleshoot Connection Issues

If the bot doesn't respond or appears non-functional:

A. Verify Bot Presence

• Check the member list in your target server/channel
• Bots typically appear separated from human users at the bottom of the list
• If not visible, the bot is not in that location

B. Check Server/Channel Location

• Confirm which server the bot actually joined (bots can only be in one server per invitation)
• Common mistake: creating bot in one server but trying to use it in another
• Solution: Either move conversations to bot's server or reinvite bot to correct server

C. Verify Channel Permissions

• Even if bot is in server, it may lack permissions in specific channels
• Check channel-specific permissions (Edit Channel → Permissions)
• Ensure bot role/member has:
  • ✅ Send Messages
  • ✅ Read Message History
  • ✅ View Channels
• Remember: channel permissions can override server role permissions

D. Test Responsiveness

• Try mentioning the bot in a channel: @bot-name test
• Or send a direct message if configured to accept DMs
• Look for any response indicating the bot is processing or active

5. Implement Value-Preserving Fallbacks

While debugging connection issues, maintain progress toward automation goals:

A. Use Working Alternative Connections

• If you have a working connection method (e.g., ADB tablet, manual browser), use it for immediate value
• Generate automation outputs (listing texts, scripts, etc.) for manual-but-accelerated workflow
• Example: Generate optimized eBay/Mercari/Poshmark texts for manual copy-paste while fixing bot

B. Consider Alternative Communication Platforms

• If Discord persistently problematic, evaluate Slack, webhooks, or other platforms
• These may have simpler permission models or better reliability in your environment
• Can switch primary communication method while keeping Discord as option

C. Document Findings for Future Reference

• Note what worked/didn't work for your specific environment
• Record exact error messages, permission settings, and solutions
• This accelerates future troubleshooting

6. Validate and Document Solution

Once bot is responsive:

• Send test commands to verify full functionality (paste text, click elements, etc.)
• Document the working configuration:
  • Agent software and version
  • Bot token source (consider storing securely)
  • Exact OAuth2 URL used
  • Server/channel where bot resides
  • Permission settings that work
• Create a quick-reference guide for future deployments

Common Pitfalls to Avoid

❌ Assuming Bot Presence

• Don't assume the bot is in your target server just because setup appeared successful
• Always visually verify in member list

❌ Overlooking Channel vs Server Permissions

• Server role permissions don't guarantee channel access
• Always check channel-specific permissions where you expect bot to operate

❌ Ignoring OAuth2 Scope Requirements

• Bots need bot scope in OAuth2 URL to appear in member list as bot
• Missing scope can cause bot to appear as regular user or not at all

❌ Forgetting Explicit "Send Messages" Permission

• This is the most common missing permission
• Must be explicitly granted at channel level for bot to send messages

❌ Losing Sight of Primary Goal

• While debugging, use fallbacks to continue delivering value
• Automation setup is a means to an end, not the end itself

❌ Not Documenting Working Configuration

• Once solved, document exactly what works to avoid repeating troubleshooting

Validation Checks

When your Discord automation agent is properly set up, you should be able to:

1. See the bot in the member list of your target server/channel
2. Have the bot respond to mentions or DMs (if enabled)
3. Successfully execute automation commands (e.g., paste text, click elements)
4. Receive confirmation or results from automated tasks
5. Reproduce the setup consistently using your documented procedure

Environment Notes

This skill is particularly useful when:

• Working on restricted/corporate Windows machines
• Deploying agents in environments with strict software installation policies
• Using alternative agent software due to compatibility constraints
• Needing to bootstrap automation value while resolving platform-specific issues

Related Skills

• hermes-agent: For when you can install and use Hermes Agent directly
• subagent-driven-development: For managing multiple specialized agents
• constrained-multi-agent-orchestration: For complex multi-agent workflows under constraints
• social-media/xitter: For Twitter/X-specific automation (similar principles, different platform)

Self-Documentation

After using this skill, consider:

• Updating the "Pitfalls" section with environment-specific discoveries
• Adding notes about agent-specific quirks you discovered
• Recording any useful command sequences or workflows that proved effective