ContextQMD
Back to Eliza

Plugin Setup Guide

packages/docs/plugin-setup-guide.md

2.0.134.9 KB
Original Source

Plugin Setup Guide — Eliza AI

Comprehensive setup instructions for all connector, AI provider, and streaming plugins. When users ask how to set up a plugin, use this guide: give them the exact env var names, where to get the credentials, minimum required fields, and tips for optional fields.

AI Providers

OpenAI

Get credentials: https://platform.openai.com/api-keys Minimum required: OPENAI_API_KEY (starts with sk-) Variables:

  • OPENAI_API_KEY — Your secret API key from platform.openai.com
  • OPENAI_BASE_URL — Leave blank for OpenAI default; set to a proxy URL if using a custom endpoint
  • OPENAI_SMALL_MODEL — e.g. gpt-5-mini (used for fast/cheap tasks)
  • OPENAI_LARGE_MODEL — e.g. gpt-5 (used for complex reasoning)
  • OPENAI_EMBEDDING_MODEL — e.g. text-embedding-3-small (for semantic search)
  • OPENAI_TTS_MODEL / OPENAI_TTS_VOICE — e.g. tts-1 / alloy (for voice synthesis)
  • OPENAI_IMAGE_DESCRIPTION_MODEL — e.g. gpt-5 (for image understanding) Tips: OpenAI is the default fallback for most features. If you have credits, set this first. Use gpt-5-mini as small model to save costs.

Anthropic

Get credentials: https://console.anthropic.com/settings/keys Minimum required: ANTHROPIC_API_KEY (starts with sk-ant-) or CLAUDE_API_KEY Variables:

  • ANTHROPIC_API_KEY / CLAUDE_API_KEY — Your secret key from console.anthropic.com (either works for auto-enable)
  • ANTHROPIC_SMALL_MODEL — e.g. claude-haiku-4-5-20251001
  • ANTHROPIC_LARGE_MODEL — e.g. claude-sonnet-4-6
  • ANTHROPIC_BROWSER_BASE_URL — (Advanced) Proxy URL for browser-side requests Tips: Best for complex reasoning and long context. Claude Haiku is very fast for the small model slot.

Google Gemini

Get credentials: https://aistudio.google.com/app/apikey Minimum required: GOOGLE_GENERATIVE_AI_API_KEY or GOOGLE_API_KEY Variables:

  • GOOGLE_GENERATIVE_AI_API_KEY / GOOGLE_API_KEY — From AI Studio or Google Cloud (either works for auto-enable)
  • GOOGLE_SMALL_MODEL — e.g. gemini-2.5-flash
  • GOOGLE_LARGE_MODEL — e.g. gemini-2.5-pro
  • GOOGLE_EMBEDDING_MODEL — e.g. text-embedding-004
  • GOOGLE_IMAGE_MODEL — e.g. gemini-2.0-flash-001 Tips: Gemini Flash is fast and cheap; great for small model. The free tier is generous.

Groq

Get credentials: https://console.groq.com/keys Minimum required: GROQ_API_KEY Variables:

  • GROQ_API_KEY — From console.groq.com
  • GROQ_SMALL_MODEL — e.g. openai/gpt-oss-120b
  • GROQ_LARGE_MODEL — e.g. openai/gpt-oss-120b
  • GROQ_TTS_MODEL / GROQ_TTS_VOICE — e.g. canopylabs/orpheus-v1-english / troy
  • GROQ_TTS_RESPONSE_FORMAT — Audio response format (default: wav) Tips: Groq is extremely fast inference — great for latency-sensitive use cases. Free tier available.

OpenRouter

Get credentials: https://openrouter.ai/keys Minimum required: OPENROUTER_API_KEY Variables:

  • OPENROUTER_API_KEY — From openrouter.ai/keys
  • OPENROUTER_SMALL_MODEL — e.g. openai/gpt-5-mini or openai/gpt-oss-120b
  • OPENROUTER_LARGE_MODEL — e.g. anthropic/claude-sonnet-4-6
  • OPENROUTER_IMAGE_MODEL — e.g. openai/gpt-5 (for vision tasks)
  • OPENROUTER_IMAGE_GENERATION_MODEL — e.g. openai/dall-e-3
  • OPENROUTER_EMBEDDING_MODEL — e.g. openai/text-embedding-3-small
  • OPENROUTER_TOOL_EXECUTION_MAX_STEPS — Max tool call steps per turn (default: 15) Tips: OpenRouter gives you access to 200+ models through one API key. Great if you want to switch models without managing multiple accounts. Use model IDs in provider/model-name format.

xAI (Grok)

Get credentials: https://console.x.ai/ Minimum required: XAI_API_KEY or GROK_API_KEY Variables:

  • XAI_API_KEY / GROK_API_KEY — From console.x.ai (either works for auto-enable)
  • XAI_MODEL — e.g. grok-3 (overrides small/large)
  • XAI_SMALL_MODEL / XAI_LARGE_MODEL — Specific model slots
  • XAI_EMBEDDING_MODEL — e.g. grok-embedding
  • X_AUTH_MODE — env (default) or oauth
  • X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET — Twitter OAuth keys (for the X connector side of xAI)
  • X_ENABLE_POST, X_ENABLE_REPLIES, X_ENABLE_ACTIONS — Toggle X/Twitter behaviors Tips: xAI = Grok models. The X_* vars are for the Twitter integration bundled with xAI. Keep auth mode as api_key unless you need OAuth. For a standalone Twitter connector (without Grok), see the Twitter/X connector section below — it uses TWITTER_* env vars and connectors.twitter config instead.

Ollama (Local Models)

Get credentials: No API key needed — install Ollama locally Setup: https://ollama.com — create the Eliza-1 Ollama models from packages/training/cloud/ollama/ Minimum required: OLLAMA_BASE_URL = http://localhost:11434 (auto-enable trigger) or OLLAMA_API_ENDPOINT = http://localhost:11434/api Variables:

  • OLLAMA_BASE_URL — Auto-enable trigger. Default: http://localhost:11434
  • OLLAMA_API_ENDPOINT — Plugin endpoint. Default: http://localhost:11434/api
  • OLLAMA_SMALL_MODEL — e.g. eliza-1-2b
  • OLLAMA_MEDIUM_MODEL — e.g. eliza-1-9b
  • OLLAMA_LARGE_MODEL — e.g. eliza-1-9b
  • OLLAMA_EMBEDDING_MODEL — e.g. nomic-embed-text Tips: Completely free and private. Requires Ollama running on your machine or a server. Build Eliza-1 models with ollama create eliza-1-9b -f packages/training/cloud/ollama/Modelfile.eliza-1-9b-q4_k_m.

Local AI

Get credentials: No API key — uses local model files Variables:

  • MODELS_DIR — Path to your local model files (e.g. /Users/you/models)
  • CACHE_DIR — Path for caching (e.g. /tmp/ai-cache)
  • LOCAL_SMALL_MODEL / LOCAL_LARGE_MODEL — Model filenames in MODELS_DIR
  • LOCAL_EMBEDDING_MODEL / LOCAL_EMBEDDING_DIMENSIONS — Embedding model and its dimension count
  • CUDA_VISIBLE_DEVICES — GPU selection, e.g. 0 for first GPU Tips: Use when you have .gguf or similar model files and want full offline operation.

Vercel AI Gateway

Get credentials: https://vercel.com/docs/ai/ai-gateway Minimum required: AI_GATEWAY_API_KEY and AI_GATEWAY_BASE_URL Variables:

  • AI_GATEWAY_API_KEY / AIGATEWAY_API_KEY — Your gateway key (either works)
  • VERCEL_OIDC_TOKEN — For Vercel-hosted deployments only
  • AI_GATEWAY_BASE_URL — Your gateway endpoint URL
  • AI_GATEWAY_SMALL_MODEL / AI_GATEWAY_LARGE_MODEL / AI_GATEWAY_EMBEDDING_MODEL — Model IDs
  • AI_GATEWAY_IMAGE_MODEL — For image generation
  • AI_GATEWAY_TIMEOUT_MS — Request timeout, default 60000ms Tips: Routes model calls through Vercel's AI gateway for caching, rate limiting, and observability. Useful if you're already on Vercel.

Eliza Cloud

Get credentials: From the elizaOS Cloud service Minimum required: ELIZAOS_CLOUD_API_KEY or ELIZAOS_CLOUD_ENABLED=true Variables:

  • ELIZAOS_CLOUD_API_KEY — Your Eliza Cloud API key
  • ELIZAOS_CLOUD_ENABLED — Set to true to enable cloud features Tips: Eliza Cloud provides hosted infrastructure for running Eliza agents with managed scaling and monitoring.

Connectors

Discord

Get credentials: https://discord.com/developers/applications → New Application → Bot → Reset Token Minimum required: DISCORD_API_TOKEN Variables:

  • DISCORD_API_TOKEN — Bot token (from Bot section, click Reset Token)
  • DISCORD_APPLICATION_ID — Application ID (from General Information, optional if runtime auto-resolve succeeds)
  • CHANNEL_IDS — Comma-separated channel IDs to listen in
  • DISCORD_VOICE_CHANNEL_ID — For voice channel support
  • DISCORD_SHOULD_IGNORE_BOT_MESSAGES — true to prevent bot-to-bot loops
  • DISCORD_SHOULD_IGNORE_DIRECT_MESSAGES — true to disable DM responses
  • DISCORD_SHOULD_RESPOND_ONLY_TO_MENTIONS — true to only respond when @mentioned
  • DISCORD_LISTEN_CHANNEL_IDS — Channel IDs to listen but not post unsolicited Setup steps:
  1. Create app at discord.com/developers/applications
  2. Go to Bot tab → Reset Token (copy immediately)
  3. Get Application ID from General Information tab
  4. Under OAuth2 → URL Generator → Bot → select permissions: Send Messages, Read Messages, Use Slash Commands
  5. Invite bot using generated URL
  6. Enable Message Content Intent under Bot → Privileged Gateway Intents Tips: You need BOTH the Bot Token AND Application ID — without Application ID slash commands won't register. Right-click a channel and Copy ID to get channel IDs (enable Developer Mode in Discord settings first).

Telegram

Get credentials: Message @BotFather on Telegram Minimum required: TELEGRAM_BOT_TOKEN Variables:

  • TELEGRAM_BOT_TOKEN — From @BotFather after /newbot
  • TELEGRAM_ALLOWED_CHATS — JSON array of allowed chat IDs, e.g. ["123456789", "-100987654321"]
  • TELEGRAM_API_ROOT — Leave blank for default; set if using a Telegram proxy
  • TELEGRAM_TEST_CHAT_ID — For testing (advanced) Setup steps:
  1. Message @BotFather: /newbot
  2. Give it a name and username
  3. Copy the token it gives you
  4. To get your chat ID: message @userinfobot Tips: Use negative IDs for groups (they start with -100). Use TELEGRAM_ALLOWED_CHATS to restrict who can talk to the bot for safety.

Twitter / X

Twitter/X integration is bundled with the xAI provider plugin (@elizaos/plugin-xai). There is no separate @elizaos/plugin-x.

Get credentials: https://developer.twitter.com/en/portal/dashboard Minimum required: xAI plugin enabled + Twitter OAuth keys in connector config or env vars. Variables (xAI plugin X_* convention):

  • X_API_KEY — Twitter API consumer key
  • X_API_SECRET — Twitter API consumer secret
  • X_ACCESS_TOKEN — OAuth access token
  • X_ACCESS_TOKEN_SECRET — OAuth access token secret
  • X_AUTH_MODE — api_key (default) or oauth
  • X_ENABLE_POST — true to enable autonomous posting
  • X_ENABLE_REPLIES — true to reply to @mentions
  • X_ENABLE_ACTIONS — true to enable like/retweet/quote actions

Connector config alternative — set these under connectors.twitter in eliza.json:

  • apiKey, apiSecretKey, accessToken, accessTokenSecret — OAuth credentials
  • postEnable, postIntervalMin, postIntervalMax, dryRun — posting behavior
  • searchEnable, autoRespondMentions, pollInterval — engagement settings

Setup steps:

  1. Apply for developer account at developer.twitter.com (instant for basic tier)
  2. Create a Project and App
  3. Generate all 4 keys from "Keys and Tokens" tab
  4. Set app permissions to Read and Write
  5. Regenerate tokens AFTER setting permissions Tips: Start with TWITTER_DRY_RUN=true to verify without posting. Free API tier has very limited write access — check X developer docs for current limits. You need ALL 4 OAuth keys — missing any one will cause auth failure.

Slack

Get credentials: https://api.slack.com/apps → Create New App Minimum required: SLACK_BOT_TOKEN + SLACK_APP_TOKEN Variables:

  • SLACK_BOT_TOKEN — Starts with xoxb- (from OAuth & Permissions → Bot Token)
  • SLACK_APP_TOKEN — Starts with xapp- (from Basic Information → App-Level Tokens; scope: connections:write)
  • SLACK_SIGNING_SECRET — From Basic Information (for webhook verification)
  • SLACK_USER_TOKEN — Starts with xoxp- (optional, for user-level actions)
  • SLACK_CHANNEL_IDS — Comma-separated channel IDs, e.g. C01ABCDEF,C02GHIJKL
  • SLACK_SHOULD_IGNORE_BOT_MESSAGES — Prevent bot loops
  • SLACK_SHOULD_RESPOND_ONLY_TO_MENTIONS — Only reply when @mentioned Setup steps:
  1. Create app at api.slack.com/apps (From Scratch → choose workspace)
  2. Socket Mode: Enable Socket Mode → generate App-Level Token with connections:write scope
  3. Bot Token Scopes (OAuth & Permissions): chat:write, channels:read, channels:history, groups:history, im:history, app_mentions:read
  4. Install app to workspace → copy Bot Token
  5. Enable Event Subscriptions → Subscribe to bot events: message.channels, message.im, app_mention Tips: Socket Mode means you DON'T need a public webhook URL. Both Bot Token (xoxb-) AND App Token (xapp-) are required for Socket Mode. To get channel IDs: right-click channel in Slack → Copy link, the ID is in the URL.

WhatsApp

Two modes — choose one:

Mode 1: Cloud API (Business, recommended) Get credentials: https://developers.facebook.com/apps → WhatsApp → API Setup

  • WHATSAPP_ACCESS_TOKEN — Permanent system user token from Meta Business
  • WHATSAPP_PHONE_NUMBER_ID — From WhatsApp → API Setup
  • WHATSAPP_BUSINESS_ACCOUNT_ID — From WhatsApp Business settings
  • WHATSAPP_WEBHOOK_VERIFY_TOKEN — Any string you choose (used to verify webhook)
  • WHATSAPP_API_VERSION — e.g. v18.0 (use latest) Setup: Need Meta Business account, verified phone number, approved WhatsApp Business App

Mode 2: Baileys (Personal, QR code)

  • WHATSAPP_AUTH_DIR — Directory to store session files, e.g. /data/whatsapp-auth
  • No other credentials needed — it scans a QR code on first run Tips: Baileys mode works with your personal WhatsApp number but violates ToS. Use Cloud API for production. Cloud API requires a real business and Meta app approval.

Instagram

Get credentials: Use your Instagram account credentials Minimum required: INSTAGRAM_USERNAME + INSTAGRAM_PASSWORD Variables:

  • INSTAGRAM_USERNAME — Your Instagram username
  • INSTAGRAM_PASSWORD — Your Instagram password
  • INSTAGRAM_VERIFICATION_CODE — Your 2FA code if enabled
  • INSTAGRAM_PROXY — Proxy URL if rate limited or blocked Tips: ⚠️ Uses unofficial API. Instagram frequently blocks automated access. Use a dedicated account, not your personal one. A proxy reduces bans. 2FA users must supply the code on startup.

Bluesky

Get credentials: https://bsky.app → Settings → App Passwords Minimum required: BLUESKY_HANDLE + BLUESKY_PASSWORD (app password, not your real password) Variables:

  • BLUESKY_HANDLE — Your handle e.g. yourname.bsky.social
  • BLUESKY_PASSWORD — App password (not your login password — create one in Settings)
  • BLUESKY_ENABLED — true to enable
  • BLUESKY_SERVICE — Default: https://bsky.social (only change for self-hosted PDS)
  • BLUESKY_ENABLE_POSTING — true for autonomous posts
  • BLUESKY_POST_INTERVAL_MIN / BLUESKY_POST_INTERVAL_MAX — Seconds between posts
  • BLUESKY_MAX_POST_LENGTH — Max characters per post (default: 300)
  • BLUESKY_POLL_INTERVAL — Seconds between checking mentions/DMs
  • BLUESKY_ENABLE_DMS — true to respond to direct messages Tips: Create an App Password at bsky.app → Settings → App Passwords. Never use your main login password.

Farcaster

Get credentials: https://warpcast.com → Settings, then https://neynar.com for API Minimum required: FARCASTER_FID + FARCASTER_SIGNER_UUID + FARCASTER_NEYNAR_API_KEY Variables:

  • FARCASTER_FID — Your Farcaster ID (number shown in profile URL)
  • FARCASTER_SIGNER_UUID — Signer UUID from Neynar dashboard
  • FARCASTER_NEYNAR_API_KEY — From neynar.com (needed for read/write)
  • ENABLE_CAST — true to enable autonomous casting
  • CAST_INTERVAL_MIN / CAST_INTERVAL_MAX — Minutes between casts
  • MAX_CAST_LENGTH — Default 320 characters
  • FARCASTER_POLL_INTERVAL — Seconds between notification checks
  • FARCASTER_HUB_URL — Custom Farcaster hub (advanced, leave blank for default) Setup steps:
  1. Create Warpcast account, get your FID from your profile URL
  2. Sign up at neynar.com, create a signer for your FID
  3. Get your API key from Neynar dashboard Tips: Neynar is required — it's the indexer that makes Farcaster data accessible via API.

WeChat

Not yet available: The @elizaos/plugin-wechat package is not currently in the plugin registry. The configuration below is for reference when the plugin becomes available.

Get credentials: From your WeChat proxy service provider Minimum required: WECHAT_API_KEY + proxy URL in config Variables:

  • WECHAT_API_KEY — Proxy service API key Config-only fields (set in connectors.wechat, not env vars):
  • proxyUrl — Required — Your WeChat proxy service URL
  • webhookPort — Webhook listener port (default: 18790)
  • deviceType — Device emulation: ipad (default) or mac
  • features.images — Enable image send/receive (default: false)
  • features.groups — Enable group chat support (default: false) Setup steps:
  1. Get API key from your WeChat proxy service
  2. Configure connectors.wechat in eliza.json with apiKey and proxyUrl
  3. Start Eliza — scan the QR code displayed in terminal with WeChat Tips: WeChat uses a third-party proxy service, not an official API. Only use a proxy you trust — it sees all message traffic. Multi-account supported via accounts map. Package: @elizaos/plugin-wechat.

GitHub

Get credentials: https://github.com/settings/tokens → Fine-grained or Classic Minimum required: GITHUB_API_TOKEN Variables:

  • GITHUB_API_TOKEN — Personal access token or GitHub App token
  • GITHUB_OWNER — Repository owner (username or org)
  • GITHUB_REPO — Repository name
  • GITHUB_BRANCH — Default branch (e.g. main)
  • GITHUB_WEBHOOK_SECRET — For GitHub App webhook verification
  • GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY / GITHUB_INSTALLATION_ID — For GitHub Apps Tips: Fine-grained tokens are more secure — scope only to the repos you need. For org repos, you may need to request access from the org.

Twitch

Get credentials: https://dev.twitch.tv/console/apps → Register Your Application Minimum required: TWITCH_USERNAME + TWITCH_CLIENT_ID + TWITCH_ACCESS_TOKEN + TWITCH_CLIENT_SECRET Variables:

  • TWITCH_USERNAME — Your Twitch bot username
  • TWITCH_CLIENT_ID — From Twitch Developer Console
  • TWITCH_CLIENT_SECRET — From Twitch Developer Console
  • TWITCH_ACCESS_TOKEN — OAuth token (get via https://twitchapps.com/tmi/ or Twitch OAuth flow)
  • TWITCH_REFRESH_TOKEN — For long-lived sessions
  • TWITCH_CHANNEL — Primary channel to join (e.g. mychannel)
  • TWITCH_CHANNELS — Additional channels (comma-separated)
  • TWITCH_REQUIRE_MENTION — true to only respond when bot username is mentioned
  • TWITCH_ALLOWED_ROLES — broadcaster, moderator, vip, subscriber, viewer Tips: Create a separate Twitch account for the bot. Use https://twitchapps.com/tmi/ to get an access token for chat bots quickly.

Twilio (SMS + Voice)

Get credentials: https://console.twilio.com Minimum required: TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN + TWILIO_PHONE_NUMBER Variables:

  • TWILIO_ACCOUNT_SID — From Twilio Console dashboard (starts with AC)
  • TWILIO_AUTH_TOKEN — From Twilio Console dashboard
  • TWILIO_PHONE_NUMBER — Your Twilio number in E.164 format (e.g. +15551234567)
  • TWILIO_WEBHOOK_URL — Your publicly accessible URL for incoming messages
  • TWILIO_WEBHOOK_PORT — Port to listen on (if self-hosting, default 3000)
  • VOICE_CALL_PROVIDER — e.g. twilio
  • VOICE_CALL_FROM_NUMBER — Outbound caller ID
  • VOICE_CALL_TO_NUMBER — Default number to call
  • VOICE_CALL_PUBLIC_URL — Publicly accessible URL for voice webhooks
  • VOICE_CALL_MAX_DURATION_SECONDS — Max call length (default 3600)
  • VOICE_CALL_INBOUND_POLICY — allow-all, allow-from, or deny-all
  • VOICE_CALL_INBOUND_GREETING — Text spoken when call is answered Tips: For webhooks to work, Twilio needs a public URL. Use ngrok during development. Get a phone number in Console → Phone Numbers → Buy a Number. Free trial gives ~$15 credit.

Matrix

Get credentials: Your Matrix homeserver account Minimum required: MATRIX_HOMESERVER + MATRIX_USER_ID + MATRIX_ACCESS_TOKEN Variables:

  • MATRIX_HOMESERVER — e.g. https://matrix.org or your own homeserver
  • MATRIX_USER_ID — e.g. @yourbot:matrix.org
  • MATRIX_ACCESS_TOKEN — From Element: Settings → Help & About → Advanced → Access Token
  • MATRIX_DEVICE_ID — Leave blank to auto-assign
  • MATRIX_ROOMS — Comma-separated room IDs (e.g. !abc123:matrix.org)
  • MATRIX_AUTO_JOIN — true to auto-join invite rooms
  • MATRIX_ENCRYPTION — true to enable E2E encryption (requires more setup)
  • MATRIX_REQUIRE_MENTION — true to only respond when @mentioned Tips: Get your access token in Element → Settings → Help & About → Advanced. Matrix IDs use format @user:server.

Microsoft Teams

Get credentials: https://portal.azure.com → Azure Active Directory → App Registrations Minimum required: MSTEAMS_APP_ID + MSTEAMS_APP_PASSWORD + MSTEAMS_TENANT_ID Variables:

  • MSTEAMS_APP_ID — Application (client) ID from Azure portal
  • MSTEAMS_APP_PASSWORD — Client secret value from Azure portal
  • MSTEAMS_TENANT_ID — Your Azure AD tenant ID
  • MSTEAMS_WEBHOOK_PORT / MSTEAMS_WEBHOOK_PATH — Where Bot Framework sends messages
  • MSTEAMS_ALLOWED_TENANTS — Restrict to specific tenants (comma-separated)
  • MSTEAMS_SHAREPOINT_SITE_ID — For SharePoint integration (advanced)
  • MSTEAMS_MEDIA_MAX_MB — Max file upload size (default 25MB) Setup steps:
  1. Register app in Azure portal → App Registrations → New Registration
  2. Add a client secret under Certificates & Secrets
  3. Register bot via https://dev.botframework.com → Create a bot
  4. Connect bot to Microsoft Teams channel in Bot Framework portal Tips: Requires Microsoft 365 admin access or an org that allows app registrations.

Google Chat

Get credentials: https://console.cloud.google.com → APIs → Google Chat API Minimum required: Service account JSON or GOOGLE_APPLICATION_CREDENTIALS path Variables:

  • GOOGLE_CHAT_SERVICE_ACCOUNT_KEY — Full service account JSON (paste the entire JSON)
  • GOOGLE_CHAT_SERVICE_ACCOUNT_FILE — Alternative: path to service account JSON file
  • GOOGLE_APPLICATION_CREDENTIALS — Alternative: path to credentials file
  • GOOGLE_CHAT_SPACES — Comma-separated space names (e.g. spaces/AAAA_space_id)
  • GOOGLE_CHAT_AUDIENCE_TYPE — PUBLISHED or DOMAIN_INSTALL
  • GOOGLE_CHAT_AUDIENCE — Your app's audience URL
  • GOOGLE_CHAT_WEBHOOK_PATH — Webhook path for incoming messages
  • GOOGLE_CHAT_REQUIRE_MENTION — true to require @mention
  • GOOGLE_CHAT_BOT_USER — Bot user ID Tips: Enable Google Chat API in Cloud Console. Create a service account with Chat-scope permissions. Workspace admin must approve the Chat app.

Signal

Get credentials: Your own phone number + signal-cli or signal-api-rest-api Minimum required: SIGNAL_ACCOUNT_NUMBER + SIGNAL_HTTP_URL Variables:

  • SIGNAL_ACCOUNT_NUMBER — Your phone number in E.164 format (e.g. +15551234567)
  • SIGNAL_HTTP_URL — REST API URL, e.g. http://localhost:8080
  • SIGNAL_CLI_PATH — Path to signal-cli binary (optional, for direct CLI mode)
  • SIGNAL_SHOULD_IGNORE_GROUP_MESSAGES — true to ignore group chats Setup: Run signal-api-rest-api server: https://github.com/bbernhard/signal-cli-rest-api Tips: Signal doesn't have an official API. Use bbernhard/signal-cli-rest-api Docker image — it handles the signal-cli connection and exposes a REST API.

iMessage (macOS only)

Get credentials: macOS only — no credentials needed, uses local Messages.app Variables:

  • IMESSAGE_CLI_PATH — Path to imessage-reader CLI (install from GitHub)
  • IMESSAGE_DB_PATH — Path to Messages chat.db (default: ~/Library/Messages/chat.db)
  • IMESSAGE_POLL_INTERVAL_MS — How often to check for new messages (default: 5000ms)
  • IMESSAGE_DM_POLICY — allow-all or allow-from
  • IMESSAGE_GROUP_POLICY — allow-all, allow-from, or deny-all
  • IMESSAGE_ALLOW_FROM — Comma-separated allowed senders
  • IMESSAGE_ENABLED — true to enable Tips: macOS only. Requires Full Disk Access permission for the app to read the Messages database. Only works on the machine that has iMessage configured.

BlueBubbles (iMessage via local server)

Get credentials: Install BlueBubbles server on a Mac with iMessage Minimum required: BLUEBUBBLES_PASSWORD Variables:

  • BLUEBUBBLES_PASSWORD — Password set in the BlueBubbles server app
  • BLUEBUBBLES_SERVER_URL — BlueBubbles server URL (e.g. http://192.168.1.50:1234)
  • BLUEBUBBLES_WEBHOOK_PATH — Custom webhook endpoint path
  • BLUEBUBBLES_DM_POLICY — allow, deny, or allowlist
  • BLUEBUBBLES_ALLOW_FROM — Comma-separated allowed senders
  • BLUEBUBBLES_GROUP_POLICY — Group message policy
  • BLUEBUBBLES_GROUP_ALLOW_FROM — Comma-separated allowed groups
  • BLUEBUBBLES_SEND_READ_RECEIPTS — true to send read receipts
  • BLUEBUBBLES_ENABLED — true to enable Tips: Unlike direct iMessage, BlueBubbles works over the network — the agent doesn't need to run on the same Mac. Supports rich actions: tapbacks, edit/unsend, effects, attachments, and group management.

Blooio (SMS via API)

Get credentials: https://bloo.io Minimum required: BLOOIO_API_KEY Variables:

  • BLOOIO_API_KEY — From bloo.io dashboard
  • BLOOIO_WEBHOOK_URL — Your public URL for incoming SMS webhooks
  • BLOOIO_WEBHOOK_SECRET — Secret for webhook signature verification
  • BLOOIO_BASE_URL — bloo.io API base URL (leave as default)
  • BLOOIO_FROM_NUMBER — Phone number to send from
  • BLOOIO_WEBHOOK_PORT — Port for webhook listener Tips: Blooio bridges iMessage/SMS. Requires a Mac running the Blooio app.

Nostr

Get credentials: Generate your own keypair using any Nostr client Minimum required: NOSTR_PRIVATE_KEY Variables:

  • NOSTR_PRIVATE_KEY — Your nsec private key (hex format)
  • NOSTR_RELAYS — Comma-separated relay URLs, e.g. wss://relay.damus.io,wss://relay.nostr.band
  • NOSTR_DM_POLICY — allow-all or allow-from
  • NOSTR_ALLOW_FROM — Allowed public keys (npub format)
  • NOSTR_ENABLED — true to enable Tips: Generate keys with any Nostr app (Damus, Primal, Amethyst). Keep private key secret — it's your identity. Use multiple relays for reliability.

LINE

Get credentials: https://developers.line.biz/console Minimum required: LINE_CHANNEL_ACCESS_TOKEN + LINE_CHANNEL_SECRET Variables:

  • LINE_CHANNEL_ACCESS_TOKEN — From LINE Developers console → Messaging API → Channel Access Token
  • LINE_CHANNEL_SECRET — From Basic Settings tab
  • LINE_WEBHOOK_PATH — Webhook URL path (configure in LINE console too)
  • LINE_DM_POLICY / LINE_GROUP_POLICY — allow-all or allow-from
  • LINE_ALLOW_FROM — Allowed user IDs
  • LINE_ENABLED — true to enable Setup steps:
  1. Create a channel at developers.line.biz
  2. Issue a channel access token (long-lived, in Messaging API tab)
  3. Set your webhook URL in the console Tips: LINE requires your webhook to be HTTPS with a valid certificate. Use ngrok or deploy to a server for development.

Feishu (Lark)

Get credentials: https://open.feishu.cn (or open.larksuite.com for Lark) Minimum required: FEISHU_APP_ID + FEISHU_APP_SECRET Variables:

  • FEISHU_APP_ID — From Feishu/Lark Developer Console → App Credentials
  • FEISHU_APP_SECRET — From App Credentials section
  • FEISHU_DOMAIN — feishu.cn (default) or larksuite.com
  • FEISHU_ALLOWED_CHATS — Allowed chat IDs (comma-separated)
  • FEISHU_TEST_CHAT_ID — For testing

Mattermost

Get credentials: Your Mattermost instance → System Console → Integrations → Bot Accounts Minimum required: MATTERMOST_SERVER_URL + MATTERMOST_BOT_TOKEN Variables:

  • MATTERMOST_SERVER_URL — e.g. https://mattermost.yourcompany.com
  • MATTERMOST_BOT_TOKEN — From System Console → Bot Accounts → Add Bot Account
  • MATTERMOST_TEAM_ID — Your team ID (from team URL or API)
  • MATTERMOST_DM_POLICY / MATTERMOST_GROUP_POLICY — allow-all or allow-from
  • MATTERMOST_ALLOWED_USERS / MATTERMOST_ALLOWED_CHANNELS — Restrict access
  • MATTERMOST_REQUIRE_MENTION — true to require @mention Tips: Enable Bot Accounts in System Console → Authentication → Bot Accounts. Self-hosted Mattermost is free.

Nextcloud Talk

Get credentials: Your Nextcloud instance → Settings → Security → App Passwords Minimum required: NEXTCLOUD_URL + NEXTCLOUD_BOT_SECRET Variables:

  • NEXTCLOUD_URL — Your Nextcloud URL (e.g. https://cloud.yourserver.com)
  • NEXTCLOUD_BOT_SECRET — Set when registering bot via Nextcloud Talk API
  • NEXTCLOUD_WEBHOOK_PUBLIC_URL — Publicly accessible URL for Talk webhooks
  • NEXTCLOUD_WEBHOOK_PORT / NEXTCLOUD_WEBHOOK_PATH — Webhook server settings
  • NEXTCLOUD_ALLOWED_ROOMS — Room tokens to allow

Tlon (Urbit)

Get credentials: Your Urbit ship access Minimum required: TLON_SHIP + TLON_URL + TLON_CODE Variables:

  • TLON_SHIP — Your ship name (e.g. ~sampel-palnet)
  • TLON_URL — URL to your ship (e.g. http://localhost:8080)
  • TLON_CODE — Your ship's access code (from +code in Dojo)
  • TLON_GROUP_CHANNELS — Channels to listen in (group path format)
  • TLON_DM_ALLOWLIST — Allowed DM senders
  • TLON_AUTO_DISCOVER_CHANNELS — Auto-join channels

Zalo (Vietnam messaging)

Get credentials: https://developers.zalo.me Minimum required: ZALO_APP_ID + ZALO_SECRET_KEY + ZALO_ACCESS_TOKEN Variables:

  • ZALO_APP_ID / ZALO_SECRET_KEY — From Zalo Developer portal
  • ZALO_ACCESS_TOKEN / ZALO_REFRESH_TOKEN — OAuth tokens from Zalo
  • ZALO_WEBHOOK_URL / ZALO_WEBHOOK_PATH / ZALO_WEBHOOK_PORT — Webhook config

Zalo User (Personal)

Personal Zalo account connector (unofficial, no API key needed). Variables:

  • ZALOUSER_COOKIE_PATH — Path to exported Zalo session cookies
  • ZALOUSER_IMEI — Device IMEI for session (from official Zalo app)
  • ZALOUSER_USER_AGENT — Browser user agent string
  • ZALOUSER_PROFILES — Multiple account profiles (JSON)
  • ZALOUSER_ALLOWED_THREADS — Allowed conversation threads
  • ZALOUSER_DM_POLICY / ZALOUSER_GROUP_POLICY — Message policies

ACP (Agent Communication Protocol)

Internal agent-to-agent protocol for connecting multiple AI agents. Variables:

  • ACP_GATEWAY_URL — Gateway URL for the ACP hub
  • ACP_GATEWAY_TOKEN / ACP_GATEWAY_PASSWORD — Authentication credentials
  • ACP_DEFAULT_SESSION_KEY / ACP_DEFAULT_SESSION_LABEL — Session identification
  • ACP_CLIENT_NAME / ACP_CLIENT_DISPLAY_NAME — This agent's identity
  • ACP_AGENT_ID — Unique agent ID
  • ACP_PERSIST_SESSIONS — true to save sessions across restarts
  • ACP_SESSION_STORE_PATH — Where to save sessions

MCP (Model Context Protocol)

Connect to any MCP server for extended tool capabilities. Variables:

  • mcp — JSON configuration object for MCP servers Tips: MCP servers can provide tools (web search, code execution, file access, databases, etc.) directly to the AI. See https://modelcontextprotocol.io for available servers.

IQ (Solana On-chain)

Note: The IQ plugin is an upstream elizaOS connector not included in the bundled plugins.json registry. Install from the remote registry if needed.

On-chain chat via Solana blockchain. Minimum required: SOLANA_PRIVATE_KEY + IQ_GATEWAY_URL Variables:

  • SOLANA_PRIVATE_KEY — Solana wallet private key (base58 encoded)
  • SOLANA_KEYPAIR_PATH — Alternative: path to keypair JSON file
  • SOLANA_RPC_URL — e.g. https://api.mainnet-beta.solana.com
  • IQ_GATEWAY_URL — IQ protocol gateway URL
  • IQ_AGENT_NAME — Display name for your agent
  • IQ_DEFAULT_CHATROOM — Default chatroom to join
  • IQ_CHATROOMS — Additional chatrooms (comma-separated)

Gmail Watch

Monitors Gmail via Google Pub/Sub push notifications. Setup: Requires Google Cloud service account with Gmail API access. Tips: Uses gog gmail watch serve internally. Requires Google Cloud project with Gmail API enabled and Pub/Sub configured.

<div id="streaming"></div>

Streaming (Live Broadcasting)

Enable @elizaos/plugin-streaming once. It covers Twitch, YouTube, X, pump.fun, custom RTMP, and optional multiple named ingests via streaming.rtmpSources in config.

Stream tab (streaming)

Adds the Stream tab to the UI with RTMP destination management when the plugin is enabled.

Twitch

Get credentials: https://dashboard.twitch.tv → Settings → Stream Variable: TWITCH_STREAM_KEY — Your stream key (keep secret!) Tips: Never share your stream key — it lets anyone stream to your channel. Regenerate if leaked.

YouTube

Get credentials: https://studio.youtube.com → Go Live → Stream settings Variables:

  • YOUTUBE_STREAM_KEY — From YouTube Studio → Stream key
  • YOUTUBE_RTMP_URL — Default: rtmp://a.rtmp.youtube.com/live2 (rarely needs changing) Tips: You need a YouTube channel with Live streaming enabled (may require phone verification).

X (Twitter)

Live stream to X using RTMP credentials generated for the active broadcast. Get credentials: From X Live Producer / Media Studio when you create a live stream Variables:

  • X_STREAM_KEY — Stream key for the broadcast
  • X_RTMP_URL — RTMP ingest URL for the broadcast session Tips: X RTMP credentials are often per-broadcast. Create the stream first, then copy both values directly into the plugin.

pump.fun

Stream to pump.fun using the platform's RTMP ingest credentials. Get credentials: From the pump.fun live streaming flow when you create a stream Variables:

  • PUMPFUN_STREAM_KEY — Stream key for pump.fun ingest
  • PUMPFUN_RTMP_URL — RTMP ingest URL for the current stream Tips: Treat both values as session credentials. If the stream refuses to start, re-create the broadcast and paste fresh values.

Custom RTMP

Stream to any platform (Facebook, TikTok, Kick, self-hosted RTMP, etc.) Variables:

  • CUSTOM_RTMP_URL — RTMP endpoint URL, e.g. rtmp://live.kick.com/app
  • CUSTOM_RTMP_KEY — Stream key from the platform Common RTMP URLs:
  • Facebook Live: rtmps://live-api-s.facebook.com:443/rtmp/
  • TikTok: rtmp://push.tiktokcdn.com/third/ (need TikTok Live access)
  • Kick: rtmp://ingest.global-contribute.live-video.net/app

General Tips

Required vs Optional: Every plugin has minimum required fields. Start with just those — you can add optional settings later.

Testing before going live: Most connectors have a "dry run" mode (e.g. TWITTER_DRY_RUN=true, FARCASTER_DRY_RUN=true, BLUESKY_DRY_RUN=true) — use this to verify setup without posting.

Policy fields: Most connectors have DM_POLICY and GROUP_POLICY fields:

  • allow-all — respond to everyone
  • allow-from — only respond to accounts in the ALLOW_FROM list
  • deny-all — never respond (effectively disables that channel type)

Webhook vs Polling: Connectors like LINE, Twilio, WhatsApp Cloud API, and Google Chat use webhooks (they push messages to your server). You need a publicly accessible URL. Use ngrok for local development: ngrok http 3000.

Rate limits: Most platforms enforce rate limits. For Twitter especially, use conservative post intervals (90-180 minutes minimum).