Security Best Practices for OpenClaw Integrations

Overview

Properly securing your API keys, tokens, and credentials is critical when working with OpenClaw integrations. This guide covers the correct methods for storing and managing sensitive information to prevent unauthorized access and data breaches.

The Golden Rule

Never share API keys, tokens, or secrets in chat platforms like Discord, WhatsApp, Slack, or Telegram.

Even if you plan to delete them later, these messages can be:

• Cached by the platform
• Visible in notification previews
• Captured in screenshots
• Logged by bots or integrations
• Accessible to other team members

Environment Variables: The Proper Method

Why Use Environment Variables?

1. AI Model Training: Models like OpenClaw are trained NOT to reveal environment variables
2. File Permissions: .env files are protected by OS-level permissions
3. Separation: Secrets stay separate from code and chat logs
4. Version Control: Easy to exclude from Git repositories
5. Easy Rotation: Update secrets without changing code

Setting Up Your .env File

Location

Store your .env file in the OpenClaw directory:

~/.openclaw/.env

Creating the File

# Create directory if it doesn't exist
mkdir -p ~/.openclaw

# Create .env file with restricted permissions
touch ~/.openclaw/.env
chmod 600 ~/.openclaw/.env

The chmod 600 command ensures only your user account can read/write the file.

Editing the File

Use a terminal text editor like nano:

nano ~/.openclaw/.env

Format

Each secret should be on its own line in KEY=value format:

# Notion Integration
NOTION_API_KEY=secret_abc123XYZ456def789

# Discord Bot
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GhIjKl.MnOpQrStUvWxYzAbCdEfGhIjKlMnOpQrStUv

# Telegram Bot
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567890

# YouTube Transcripts API
YOUTUBE_TRANSCRIPT_API_KEY=yt_live_abc123def456ghi789

# Custom APIs
COINGECKO_API_KEY=CG-abc123def456ghi789jkl012
TWITTER_API_KEY=AAAAAAAAAAAAAAAAAAAAABcde

Saving Changes

In nano:

1. Press Ctrl + X to exit
2. Press Y to confirm save
3. Press Enter to confirm filename

Verifying Your Setup

Check that the file exists and has correct permissions:

ls -la ~/.openclaw/.env

Expected output:

-rw------- 1 username username 256 May 6 12:00 /home/username/.openclaw/.env

The -rw------- means only you can read/write the file.

API Key Management by Platform

Notion

Where to Get:

• notion.so/my-integrations
• Create integration → Copy "Internal Integration Secret"

Environment Variable:

NOTION_API_KEY=secret_your_key_here

Permissions:

• Use read-only if you only need data analysis
• Enable write permissions for task management

Rotation:

• Click "Regenerate" in integration settings
• Update .env file immediately
• Restart OpenClaw gateway

Discord

Where to Get:

• discord.com/developers/applications
• Create application → Bot → Reset Token

Environment Variable:

DISCORD_BOT_TOKEN=your_token_here

Security Settings:

• Enable "Server Members Intent"
• Enable "Message Content Intent"
• Use bot permissions, not administrator (when possible)

Rotation:

• Reset token in Discord Developer Portal
• Update .env file
• Restart OpenClaw gateway
• Bot will automatically reconnect

Telegram

Where to Get:

• Message @BotFather on Telegram
• Use /newbot command
• Copy the token provided

Environment Variable:

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Security Settings:

• Configure pairing policy (DM only, allowlist, etc.)
• Use pairing codes for new users
• Regularly review paired users

Rotation:

• Message @BotFather
• Use /revoke command
• Get new token with /token
• Update .env file

Third-Party APIs

General Pattern:

SERVICE_NAME_API_KEY=your_key_here

Examples:

• YOUTUBE_TRANSCRIPT_API_KEY - YouTube Transcripts API
• COINGECKO_API_KEY - CoinGecko crypto data
• OPENAI_API_KEY - OpenAI API
• ANTHROPIC_API_KEY - Anthropic Claude API

Git and Version Control

.gitignore Configuration

Always add .env files to your .gitignore:

# Environment variables
.env
.env.local
.env.*.local
**/.env

# OpenClaw specific
.openclaw/.env
.openclaw/**/.env

Checking for Exposed Secrets

Before committing, verify no secrets are included:

# Check what will be committed
git status

# Search for potential secrets in staged files
git diff --cached | grep -i "api_key\|token\|secret\|password"

If You Accidentally Commit Secrets

1. Immediately rotate all exposed keys
2. Remove from Git history:

# Remove file from Git history (use with caution)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch .env" \
  --prune-empty --tag-name-filter cat -- --all

# Force push (only if you're sure)
git push origin --force --all

3. Better approach: Consider the repository compromised and rotate all secrets

Access Control

Principle of Least Privilege

Only grant the minimum permissions needed:

Use Case	Notion Permissions	Discord Permissions	Telegram Policy
Data Analysis	Read only	N/A	Read only
Task Management	Read + Write	Send messages, Read history	DM pairing
Team Collaboration	Read + Write	Manage channels, Send messages	Allowlist
Public Bot	Read + Write	Limited to specific channels	Pairing codes

Regular Audits

Monthly checklist:

• Review all active API integrations
• Remove unused integrations
• Check who has access to .env files
• Verify bot permissions haven't expanded
• Review paired Telegram users
• Check Discord bot role assignments
• Rotate keys for critical services

Incident Response

If an API Key is Exposed

Immediate Actions (within 5 minutes):

1. Revoke the exposed key at the source (Notion, Discord, etc.)
2. Generate a new key
3. Update your .env file with the new key
4. Restart OpenClaw gateway: openclaw gateway restart

Follow-up Actions (within 24 hours):

5. Review logs for unauthorized access
6. Check for unexpected changes in connected services
7. Notify team members if it's a shared integration
8. Document the incident and how it happened
9. Update procedures to prevent recurrence

If .env File is Compromised

Immediate Actions:

1. Rotate ALL keys in the .env file
2. Check system logs for unauthorized access:

   sudo grep "\.env" /var/log/auth.log
   

3. Review recent file access:

   ls -lu ~/.openclaw/.env
   

4. Change system passwords if needed

Follow-up Actions:

5. Enable 2FA on all integrated services
6. Review SSH access logs
7. Consider changing SSH keys
8. Audit all connected services for suspicious activity

Common Mistakes to Avoid

❌ Mistake 1: Sharing Keys in Chat

Wrong:

Discord: "Hey team, here's the Notion API key: secret_abc123..."

Right:

Discord: "I've added the Notion integration. Each team member should create their own integration at notion.so/my-integrations and add it to their local .env file."

❌ Mistake 2: Committing .env to Git

Wrong:

git add .env
git commit -m "Add configuration"

Right:

# Add to .gitignore first
echo ".env" >> .gitignore
git add .gitignore
git commit -m "Add .gitignore for environment variables"

❌ Mistake 3: Using Same Key Everywhere

Wrong:

• One Notion integration for all projects
• One Discord bot for all servers
• Shared API keys across team

Right:

• Separate integration per project
• Separate bot per server/purpose
• Individual API keys per team member

❌ Mistake 4: Hardcoding Secrets

Wrong:

# config.py
NOTION_API_KEY = "secret_abc123def456"
DISCORD_TOKEN = "MTIzNDU2Nzg5..."

Right:

# config.py
import os
NOTION_API_KEY = os.getenv("NOTION_API_KEY")
DISCORD_TOKEN = os.getenv("DISCORD_BOT_TOKEN")

❌ Mistake 5: Overly Permissive Access

Wrong:

• Discord bot with Administrator permission
• Notion integration with full workspace access
• Telegram bot with no pairing policy

Right:

• Discord bot with specific channel permissions
• Notion integration connected only to needed databases
• Telegram bot with allowlist or pairing codes

Security Checklist

Initial Setup

• Create .env file with chmod 600 permissions
• Add .env to .gitignore
• Use unique keys for each integration
• Enable only required permissions
• Document which keys are used where

Ongoing Maintenance

• Rotate keys every 90 days (or per your security policy)
• Review access logs monthly
• Remove unused integrations
• Update OpenClaw regularly
• Monitor for security advisories

Before Sharing/Recording

• Never show .env file contents
• Blur/redact API keys in screenshots
• Use dummy keys in tutorials
• Regenerate any keys shown in videos
• Review recordings before publishing

Advanced Security

Using Secret Management Tools

For production environments, consider:

HashiCorp Vault:

# Store secret in Vault
vault kv put secret/openclaw notion_api_key="secret_abc123"

# Retrieve in OpenClaw
export NOTION_API_KEY=$(vault kv get -field=notion_api_key secret/openclaw)

AWS Secrets Manager:

# Store secret
aws secretsmanager create-secret \
  --name openclaw/notion \
  --secret-string "secret_abc123"

# Retrieve in OpenClaw
export NOTION_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id openclaw/notion \
  --query SecretString \
  --output text)

SSH Key-Based Access

For remote OpenClaw servers:

1. Disable password authentication
2. Use SSH keys only
3. Restrict SSH access by IP (if possible)
4. Use SSH key passphrases

# Generate SSH key with passphrase
ssh-keygen -t ed25519 -C "openclaw-server"

# Copy to server
ssh-copy-id user@openclaw-server

# Disable password auth on server
sudo nano /etc/ssh/sshd_config
# Set: PasswordAuthentication no
sudo systemctl restart sshd

Firewall Configuration

Restrict access to OpenClaw server:

# Allow only SSH and OpenClaw ports
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 8080/tcp  # OpenClaw (if needed)
sudo ufw enable

Resources

• OWASP API Security Top 10
• GitHub Secret Scanning
• OpenClaw Security Documentation

Related Guides

• Notion Integration
• Discord Integration
• Telegram Integration
• API Integration Guide

---

Remember: Security is not a one-time setup. It's an ongoing practice. Stay vigilant, rotate keys regularly, and always follow the principle of least privilege.