clawdbot-hq

Connect your Clawdbot gateway to OpenClawHQ for monitoring and management.

Quick Start

# One-time connection test
npx clawdbot-hq connect --token "hq_your_token_here"

# Run as daemon (recommended)
npx clawdbot-hq connect --token "hq_your_token_here" --daemon

Get Your Token

1. Sign in at openclawhq.com
2. Go to Settings → Gateway
3. Copy your HQ token (starts with hq_)

Commands

# Connect with token
clawdbot-hq connect --token "hq_xxx"

# Connect and keep running (recommended)
clawdbot-hq connect --token "hq_xxx" --daemon

# Reconnect with saved credentials
clawdbot-hq reconnect --daemon

# Check connection status
clawdbot-hq status

# Disconnect gateway
clawdbot-hq disconnect

How It Works

Your gateway sends heartbeats to OpenClawHQ every 30 seconds:

Gateway (anywhere) → OpenClawHQ API → Firestore → Dashboard

Works through NAT/firewalls — the gateway makes outbound connections, so no port forwarding needed.

Options

| Option | Description | |--------|-------------| | --token, -t | Your OpenClawHQ token | | --daemon, -d | Keep running and send heartbeats | | --interval | Heartbeat interval in seconds (default: 30) |

Running as a Service

macOS (launchd)

# Create plist
cat > ~/Library/LaunchAgents/com.clawdbot.hq.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.clawdbot.hq</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/npx</string>
        <string>clawdbot-hq</string>
        <string>reconnect</string>
        <string>--daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

# Load service
launchctl load ~/Library/LaunchAgents/com.clawdbot.hq.plist

Linux (systemd)

# Create service file
sudo cat > /etc/systemd/system/clawdbot-hq.service << 'EOF'
[Unit]
Description=Clawdbot HQ Connection
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/npx clawdbot-hq reconnect --daemon
Restart=always
User=your-username

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable clawdbot-hq
sudo systemctl start clawdbot-hq

Troubleshooting

"Invalid token" — Make sure you're using the token from Settings → Gateway, not your API key.

"Connection failed" — Check your internet connection. The gateway needs outbound HTTPS access to openclawhq.com.

Gateway shows offline — Make sure the daemon is running. Check with clawdbot-hq status.

Links

• OpenClawHQ Dashboard
• Clawdbot Documentation
• GitHub Issues

License

MIT