inclusionai/OpenClaw

📚 OpenClaw Installation and Discord Configuration Guide

1. Environment Setup

1.1 System Requirements

• Node.js: v22.16.0+ (required)
• npm: Installed with Node.js
• pnpm: Must be installed globally
• Git: For cloning the repository

1.2 PATH Issues (Important!)

On macOS, Node.js may not be in the default PATH; you may need to specify it explicitly:

/usr/local/bin/node --version
/usr/local/bin/npm --version

Solution: Prepend export PATH="/usr/local/bin:$PATH" before running commands.

---

2. Installation Steps

2.1 Clone the Repository

git clone https://github.com/openclaw/openclaw.git
cd openclaw

2.2 Install Dependencies

# Install pnpm (if not already installed)
/usr/local/bin/node /usr/local/bin/npm install -g pnpm
# Install project dependencies
export PATH="/usr/local/bin:$PATH"
npm install

2.3 Build the Project

export PATH="/usr/local/bin:$PATH"
pnpm build

⚠️ Note: The build takes about 20–30 seconds and produces the dist/ directory.

---

3. Basic Configuration

3.1 Set Gateway Mode

export PATH="/usr/local/bin:$PATH"
node dist/index.js config set gateway.mode '"local"' --json

3.2 Configuration File Locations

• Main config: ~/.openclaw/openclaw.json
• Log files: /tmp/openclaw/openclaw-YYYY-MM-DD.log

---

4. Discord Configuration

4.1 Create a Discord Bot

1. Go to https://discord.com/developers/applications
2. Create New Application → Bot
3. Required intents:
   • ✅ Message Content Intent
   • ✅ Server Members Intent
4. Copy the Bot Token (format: MTQ3...)
5. Invite the bot to your server using the OAuth2 URL

4.2 Configure Discord Channel

# Enable Discord
node dist/index.js config set channels.discord.enabled 'true' --json
# Set Bot Token
node dist/index.js config set channels.discord.token '"YOUR_BOT_TOKEN"' --json

4.3 Verify Configuration

cat ~/.openclaw/openclaw.json

It should include:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN"
    }
  },
  "gateway": {
    "mode": "local"
  }
}

---

5. Starting the Gateway

5.1 Run in Background (Recommended)

export PATH="/usr/local/bin:$PATH"
cd openclaw
# Run in background with nohup
nohup node dist/index.js gateway --port 18789 > /tmp/gateway.log 2>&1 &
# Check process
ps aux | grep openclaw-gateway | grep -v grep

5.2 Verify Gateway Status

# Check port
lsof -i :18789
# Check channel status
node dist/index.js channels status --probe

---

6. Sending Discord Messages

6.1 Command Format

node dist/index.js message send \
  --channel discord \
  --target "user:USER_ID" \
  --message "Message content"

6.2 Full Example

export PATH="/usr/local/bin:$PATH"
cd openclaw
node dist/index.js message send \
  --channel discord \
  --target "user:USER_ID" \
  --message "🦞 Hello from OpenClaw!"

---

7. Troubleshooting

7.1 Discord Connection Failed: fetch failed

Symptoms:

Error: Failed to get gateway information from Discord: fetch failed
discord: failed to deploy native commands: fetch failed

Possible causes:

1. Invalid Bot Token – Token revoked or expired
2. Network issues – Cannot reach discord.com
3. Intents not enabled – Message Content Intent is disabled

Solution:

# Verify token
curl -H "Authorization: Bot YOUR_TOKEN" \
  https://discord.com/api/v10/users/@me

7.2 Gateway Exits Right After Starting

Symptoms: Gateway process starts then exits immediately.

Solution:

• Check logs: tail -f /tmp/openclaw/openclaw-YYYY-MM-DD.log
• Ensure Discord token is valid
• Use nohup so it keeps running in the background

7.3 TypeError: fetch failed When Sending Messages

Cause: Gateway not running or Discord not connected.

Solution:

1. Check if Gateway is running: ps aux | grep openclaw-gateway
2. Check Discord status: node dist/index.js channels status --probe
3. Restart Gateway and wait for Discord to connect (about 5–10 seconds)

---

8. Command Quick Reference

| Action | Command | |--------|--------| | Build project | pnpm build | | Start Gateway | nohup node dist/index.js gateway --port 18789 > /tmp/gateway.log 2>&1 & | | View config | cat ~/.openclaw/openclaw.json | | Set config | node dist/index.js config set KEY 'VALUE' --json | | Send message | node dist/index.js message send --channel discord --target "user:ID" --message "content" | | Check status | node dist/index.js channels status --probe | | View logs | tail -f /tmp/openclaw/openclaw-YYYY-MM-DD.log |

---

9. Best Practices

1. Use full paths: /usr/local/bin/node instead of node
2. Run Gateway in background: Use nohup and &
3. Wait for connection: Discord needs 5–10 seconds to connect; do not send messages immediately
4. Verify token: Use curl to verify the Bot token before use
5. Check logs: When something fails, check the log file first

---