Config Explorer

open-wa has one configuration schema, and every option can be set three ways:

in a config file (wa.config.json / wa.config.mjs), by its key
as a CLI flag (--kebab-case)
as an environment variable (WA_UPPER_SNAKE)

Use the explorer below to search every option, filter by group, and switch between the three forms. The table and the copy-paste snippet update to match the format you pick. Options are grouped by area (browser, session, server, logging, and so on) — the groups are inferred from the config schema itself, so they always match the source.

Session & Authentication (8)

ephemeralbooleandefault: false

When true, prevents auto-derivation of userDataDir from sessionId. The browser launches with an ephemeral temp profile that is discarded on exit. Useful for testing without leaving _IGNORE_ directories behind.

licenseKeystring | object | functionoptional

License key for unknown number messaging.

linkCodestringoptional

Link code for new login method.

sessionDataobject | stringoptional

Deprecated compatibility input for JSON or base64 session restore. This MD-obsolete flow remains only for legacy migration. Prefer userDataDir for persistent auth state.

sessionDataPathstringdefault: ""

Deprecated legacy path for .data.json session restore files. This only exists for MD-obsolete JSON session compatibility. Prefer userDataDir.

sessionIdstringdefault: "session"

Name of the session. Must be unique.

skipSessionSavebooleandefault: false

Deprecated legacy flag for .data.json session persistence. This only affects the MD-obsolete JSON restore path. Prefer userDataDir-managed persistence.

userDataDirstringoptional

Browser profile directory used for persistent session storage.

Browser Configuration (22)

allowDangerousBrowserArgsbooleanoptional

Allow known-dangerous chromium args (--single-process, --no-zygote) that are normally stripped. Unsupported: these cause detached-frame crash loops on modern Chrome.

browserRevisionstringoptional

Specific browser revision to download and use.

browserWSEndpointstringoptional

Connect to existing chrome window (Experimental).

bypassCSPbooleandefault: false

Disable cors (bypass pagesetbypasscspenabled).

chromiumArgsstring[]optional

Custom chrome/chromium argument strings. Note: --single-process and --no-zygote are stripped by default because they crash WhatsApp Web with "Navigating frame was detached" on modern Chrome; set allowDangerousBrowserArgs to force them.

corsFixbooleandefault: false

Bypass web security to fix CORS issues.

executablePathstringoptional

Path to chrome instance.

headlessbooleandefault: true

Run browser in headless mode.

lightpandaobjectoptional

Lightpanda local mode configuration.

lightpanda.disableTelemetrybooleandefault: false

Disable Lightpanda telemetry for deterministic startup.

lightpanda.executablePathstringoptional

Override path to Lightpanda binary.

lightpanda.hoststringdefault: "127.0.0.1"

Lightpanda bind address.

lightpanda.portStartnumberdefault: 9000

First Lightpanda port to try.

lightpanda.startupTimeoutMsnumberdefault: 30000

How long to wait for Lightpanda readiness.

proxyServerCredentialsobjectoptional

Proxy server credentials.

raspibooleandefault: false

Enable Raspberry Pi OS support.

resizablebooleandefault: true

Sync viewport size with window size.

useChromebooleandefault: false

Automatically detect chrome instance.

useLightpandabooleandefault: false

Enable Lightpanda local browser mode.

useNativeProxybooleandefault: false

Use native proxy system.

useStealthbooleandefault: false

Enable/disable puppeteer stealth plugin.

viewportobjectoptional

QR Code Configuration (7)

ezqrbooleandefault: true

Enable easy QR code endpoint.

qrFormat"png" | "jpeg" | "webm"default: "png"

QR code output format.

qrLogSkipbooleandefault: false

Skip logging QR Code to console.

qrMaxnumberoptional

Automatically kill the process after a set amount of qr codes.

qrPopUpOnlybooleanoptional

Downgraded legacy QR convenience flag. v5 may still expose QR PNG output, but popup and local QR parity is not a guaranteed runtime contract.

qrQualitynumberdefault: 1

QR code output quality (0.1 - 1.0).

qrTimeoutnumberdefault: 60

Wait time for QR scan before killing process. 0 to wait forever.

Authentication & Timeouts (4)

authTimeoutnumberdefault: 60

Wait time for session authentication.

callTimeoutnumberdefault: 0

Wait time for client method resolution.

oorTimeoutnumberdefault: 60

Phone out of reach check timeout.

waitForRipeSessionTimeoutnumberdefault: 5

Wait time for session to load fully. 0 to wait forever.

Popup & UI (1)

popupboolean | numberdefault: false

Downgraded legacy compatibility option. Opens a local browser window for status or manual inspection, but v5 does not guarantee legacy popup QR parity.

Logging & Debugging (9)

devtoolsboolean | objectoptional

Enable remote devtools.

disableSpinsbooleandefault: false

Disable spins in logs (for docker).

logConsolebooleandefault: false

Log console messages from browser.

logConsoleErrorsbooleandefault: false

Log error messages from browser.

logDebugInfoAsObjectbooleandefault: false

Log debug info as object instead of console.table.

logFilebooleandefault: false

Create log file for all actions.

loggingobject[]optional

Winston logging transport configurations.

logInternalEventsbooleanoptional

Log all internal wa web events.

logLevelstringoptional

Logging level (VERBOSE, INFO, ERROR, SILENT).

Process Behavior (5)

killClientOnLogoutbooleandefault: false

Kill client when logout detected.

killProcessOnBanbooleandefault: true

Kill process when temporary ban detected.

killProcessOnBrowserClosebooleandefault: false

Kill process when browser closes.

killProcessOnTimeoutbooleandefault: false

Kill process on auth/qr timeout.

restartOnCrashanyoptional

Function to call upon restart if page crashes.

Safety & Error Handling (4)

Error handling strategy.

safeModebooleandefault: false

Check if page is valid before each command.

throwErrorOnTosBlockbooleanoptional

Throw error if session blocked or unable to get QR.

throwOnExpiredSessionDatabooleandefault: false

Return false if session data expired.

Features & Behavior (22)

aggressiveGarbageCollectionbooleanoptional

Run gc() before every command sent to the browser.

autoRefreshbooleandefault: true

Automatically refresh QR codes (Deprecated).

blockAssetsbooleandefault: false

Block all assets from loading.

blockCrashLogsbooleandefault: true

Block network calls to crash log servers.

cachedPatchbooleandefault: false

Save local copy of patches.json.

cacheEnabledbooleandefault: false

Enable/disable cache.

customUserAgentstringoptional

Custom user agent.

deleteSessionDataOnLogoutbooleandefault: false

Delete session data file on logout.

ensureHeadfulIntegritybooleanoptional

Makes sure the headless session is usable even on first login.

eventModebooleandefault: true

Automatically register SimpleListener events.

ghPatchbooleandefault: false

Use default cached raw github link for patches.

Language of host notification.

idCorrectionbooleandefault: false

Attempt to correct invalid chatIds.

ignoreNukebooleanoptional

Don't implicitly determine if the host logged out.

inDockerbooleandefault: false

Try to infer config from environment variables.

keepUpdatedbooleandefault: false

Always start with latest version (Alpha).

legacybooleandefault: false

Roll back on late beta features.

qrRefreshSnumberoptional

QR refresh interval (Deprecated).

screenshotOnInitializationBrowserErrorbooleandefault: false

Screenshot on unexpected initialization error.

skipBrokenMethodsCheckbooleandefault: false

Bypass health check before startup.

skipUpdateCheckbooleandefault: false

Bypass latest version check.

waitForRipeSessionbooleandefault: true

Wait for a valid headful session.

Stickers & Messaging (3)

autoEmojistring | falsedefault: ":"

Automatic emoji detection character.

linkParserstringdefault: "https://link.openwa.cloud/api"

URL of serverless meta grabber.

stickerServerEndpointstring | booleandefault: "https://sticker-api.openwa.dev"

Sticker server endpoint.

Preprocessors & Cloud Upload (4)

cloudUploadOptionsobjectoptional

Options for cloud upload preprocessor.

messagePreprocessoranyoptional

Message preprocessor options.

pQueueDefaultanyoptional

Default pqueue options.

preprocFilterstringoptional

Filter for message preprocessor.

Session Limits (3)

discordstringoptional

Your Discord ID to get onto the sticker leaderboard.

maxChatsnumberoptional

Maximum amount of chats to be present in a session.

maxMessagesnumberoptional

Maximum amount of messages to be present in a session.

Multi-device (2)

multiDevicebooleandefault: true

Enable multi-device support (Beta).

sessionDataBucketAuthstringoptional

Base64 encoded S3 Bucket & Authentication object.

v5 Specific Features (6)

apiLifecycle"immediate" | "post-connection" | "hybrid"default: "hybrid"

When to start the API: immediate, after connection, or hybrid (QR only first).

dashboardbooleandefault: true

Launch the session management dashboard. Disable with --no-dashboard.

dashboardPortnumberdefault: 3000

Port for the dashboard sidecar. Defaults to 3000.

integrationsobjectoptional

Integration configurations (chatwoot, webhook, n8n, etc.). Changes require restart.

proxyHoststringoptional

Host of the Cloudflare session proxy worker, e.g. wss://proxy.account.workers.dev

proxyTokenstringoptional

Token used to authenticate this session with the Cloudflare proxy upstream.

Server Configuration (5)

apiKeystringoptional

API key for authentication (minimum 8 characters).

corsstring | string[]default: "*"

CORS allowed origins.

hoststringdefault: "localhost"

Host address to bind.

portnumberdefault: 8080

Port for the API server.

webhookstringoptional

Webhook URL for events.

ElasticSearch Monitoring (10)

elasticBufferSizenumberdefault: 50

ElasticSearch buffer size.

elasticIndexPrefixstringdefault: "open-wa-"

ElasticSearch index prefix.

elasticPasswordstringoptional

ElasticSearch password.

elasticPipelinestringoptional

ElasticSearch ingest pipeline.

elasticUrlstringoptional

ElasticSearch URL.

elasticUsernamestringoptional

ElasticSearch username.

mcpobjectoptional

Easy API MCP configuration. Hosted MCP requires apiKey.

pluginConfigobjectdefault: {}

Plugin configuration keyed by plugin name.

pluginsstring[]default: []

Plugin references to load (npm packages or file paths).

s3Syncobjectoptional

S3 Session Synchronization configuration

Show the 115 shown options as wa.config.json

{
  "aggressiveGarbageCollection": true,
  "allowDangerousBrowserArgs": true,
  "apiKey": "<apiKey>",
  "apiLifecycle": "hybrid",
  "authTimeout": 60,
  "autoEmoji": ":",
  "autoRefresh": true,
  "blockAssets": false,
  "blockCrashLogs": true,
  "browserRevision": "<browserRevision>",
  "browserWSEndpoint": "<browserWSEndpoint>",
  "bypassCSP": false,
  "cachedPatch": false,
  "cacheEnabled": false,
  "callTimeout": 0,
  "chromiumArgs": "",
  "cloudUploadOptions": "<cloudUploadOptions>",
  "cors": "*",
  "corsFix": false,
  "customUserAgent": "<customUserAgent>",
  "dashboard": true,
  "dashboardPort": 3000,
  "deleteSessionDataOnLogout": false,
  "devtools": "<devtools>",
  "disableSpins": false,
  "discord": "<discord>",
  "elasticBufferSize": 50,
  "elasticIndexPrefix": "open-wa-",
  "elasticPassword": "<elasticPassword>",
  "elasticPipeline": "<elasticPipeline>",
  "elasticUrl": "<elasticUrl>",
  "elasticUsername": "<elasticUsername>",
  "ensureHeadfulIntegrity": true,
  "ephemeral": false,
  "eventMode": true,
  "executablePath": "<executablePath>",
  "ezqr": true,
  "ghPatch": false,
  "headless": true,
  "host": "localhost",
  "hostNotificationLang": "<hostNotificationLang>",
  "idCorrection": false,
  "ignoreNuke": true,
  "inDocker": false,
  "integrations": "<integrations>",
  "keepUpdated": false,
  "killClientOnLogout": false,
  "killProcessOnBan": true,
  "killProcessOnBrowserClose": false,
  "killProcessOnTimeout": false,
  "legacy": false,
  "licenseKey": "<licenseKey>",
  "lightpanda": "<lightpanda>",
  "linkCode": "<linkCode>",
  "linkParser": "https://link.openwa.cloud/api",
  "logConsole": false,
  "logConsoleErrors": false,
  "logDebugInfoAsObject": false,
  "logFile": false,
  "logging": "",
  "logInternalEvents": true,
  "logLevel": "<logLevel>",
  "maxChats": 0,
  "maxMessages": 0,
  "mcp": "<mcp>",
  "messagePreprocessor": "<messagePreprocessor>",
  "multiDevice": true,
  "onError": "NOTHING",
  "oorTimeout": 60,
  "pluginConfig": "{}",
  "plugins": "[]",
  "popup": "false",
  "port": 8080,
  "pQueueDefault": "<pQueueDefault>",
  "preprocFilter": "<preprocFilter>",
  "proxyHost": "<proxyHost>",
  "proxyServerCredentials": "<proxyServerCredentials>",
  "proxyToken": "<proxyToken>",
  "qrFormat": "png",
  "qrLogSkip": false,
  "qrMax": 0,
  "qrPopUpOnly": true,
  "qrQuality": 1,
  "qrRefreshS": 0,
  "qrTimeout": 60,
  "raspi": false,
  "resizable": true,
  "restartOnCrash": "<restartOnCrash>",
  "s3Sync": "<s3Sync>",
  "safeMode": false,
  "screenshotOnInitializationBrowserError": false,
  "sessionData": "<sessionData>",
  "sessionDataBucketAuth": "<sessionDataBucketAuth>",
  "sessionDataPath": "",
  "sessionId": "session",
  "skipBrokenMethodsCheck": false,
  "skipSessionSave": false,
  "skipUpdateCheck": false,
  "stickerServerEndpoint": "https://sticker-api.openwa.dev",
  "throwErrorOnTosBlock": true,
  "throwOnExpiredSessionData": false,
  "useChrome": false,
  "useLightpanda": false,
  "useNativeProxy": false,
  "userDataDir": "<userDataDir>",
  "useStealth": false,
  "viewport": "<viewport>",
  "waitForRipeSession": true,
  "waitForRipeSessionTimeout": 5,
  "webhook": "<webhook>"
}

This page is generated from @open-wa/config's schema, so it always matches the options the runtime actually accepts.

Was this helpful?

Wally and his cute companion coffee mug are coding day and night to keep this up-to-date!