Config Explorer

open-wa has one configuration schema. The runtime exposes each schema field in the config file, while the CLI and environment adapters cover smaller, explicitly supported subsets:

in a config file (wa.config.json / wa.config.mjs), by its key
as a CLI flag where the v5 CLI parser supports that option
as an environment variable where the environment loader supports that key

Use the explorer below to search every option, filter by group, and switch between the three forms. The table and copy-paste snippet update to match the format you pick. Options are grouped by area (browser, session, server, logging, and so on) from the config schema itself. Nested fields are shown under their full config path, and a config file only label means the selected adapter does not accept that field.

For the complete source-backed option reference, including full types and defaults, see Configuration and CLI.

JSON config supports every schema field. CLI flags and environment variables appear only where the runtime adapter accepts them.

Session & Authentication (12)

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.

sessionData.WABrowserIdstringoptional

sessionData.WASecretBundlestringoptional

sessionData.WAToken1stringoptional

sessionData.WAToken2stringoptional

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 (28)

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.

proxyServerCredentials.addressstringoptional

Proxy Server address. This can include the port e.g '127.0.0.1:5005'

proxyServerCredentials.passwordstringoptional

Password for Proxy Server authentication

proxyServerCredentials.protocolstringoptional

The protocol on which the proxy is running. E.g `http`, `https`, `socks4` or `socks5`

proxyServerCredentials.usernamestringoptional

Username for Proxy Server authentication

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

viewport.heightnumberdefault: 900

Page height in pixels

viewport.widthnumberdefault: 1440

Page width in pixels

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 (11)

devtoolsboolean | objectoptional

Enable remote devtools.

devtools.passstringoptional

Password for devtools

devtools.userstringoptional

Username for 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 (15)

Error handling strategy.

safeModebooleandefault: false

Check if page is valid before each command.

sandboxChatsboolean | objectdefault: false

Run explicit per-chat user code in a worker, process, or container sandbox.

sandboxChats.capabilitiesstring[]default: ["sendText"]

sandboxChats.concurrencynumberdefault: 1

sandboxChats.env"none" | string[]default: "none"

sandboxChats.filesystem"none" | "read-only" | "workspace"default: "none"

sandboxChats.idleTimeoutMsnumberdefault: 300000

sandboxChats.isolation"worker" | "process" | "container"default: "process"

sandboxChats.memoryMbnumberdefault: 256

sandboxChats.network"none" | "allowlist"default: "none"

sandboxChats.networkAllowliststring[]default: []

sandboxChats.timeoutMsnumberdefault: 30000

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 (13)

cloudUploadOptionsobjectoptional

Options for cloud upload preprocessor.

cloudUploadOptions.accessKeyIdstringoptional

cloudUploadOptions.bucketstringoptional

cloudUploadOptions.directory"DATE" | "CHAT" | "CHAT_DATE" | "DATE_CHAT" | stringoptional

cloudUploadOptions.headersobjectoptional

cloudUploadOptions.ignoreHostAccountbooleanoptional

cloudUploadOptions.publicbooleanoptional

cloudUploadOptions.regionstringoptional

cloudUploadOptions.secretAccessKeystringoptional

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 (6)

elasticBufferSizenumberdefault: 50

ElasticSearch buffer size.

elasticIndexPrefixstringdefault: "open-wa-"

ElasticSearch index prefix.

elasticPasswordstringoptional

ElasticSearch password.

elasticPipelinestringoptional

ElasticSearch ingest pipeline.

elasticUrlstringoptional

ElasticSearch URL.

elasticUsernamestringoptional

ElasticSearch username.

MCP (4)

mcpobjectoptional

Easy API MCP configuration. Hosted MCP requires apiKey.

mcp.enabledbooleandefault: false

Enable the hosted MCP endpoint for Easy API. Requires apiKey.

mcp.exposeToolsMetabooleandefault: true

Expose /meta/mcp-tools.json for dashboard and debugging.

mcp.pathstringdefault: "/mcp"

Hosted MCP endpoint path for Easy API.

Plugin System (2)

pluginConfigobjectdefault: {}

Plugin configuration keyed by plugin name.

pluginsstring[]default: []

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

Session Sync (9)

s3Syncobjectoptional

S3 Session Synchronization configuration

s3Sync.accessKeyIdstringoptional

AWS access key ID

s3Sync.bucketstringoptional

S3 bucket name

s3Sync.enableLocalCompressionbooleanoptional

Enable local session compression

s3Sync.endpointstringoptional

Custom S3 endpoint

s3Sync.hoststringoptional

PicoS3 support

s3Sync.regionstringoptional

S3 region

s3Sync.secretAccessKeystringoptional

AWS secret access key

s3Sync.syncIntervalnumberdefault: 600000

Sync interval in ms

Show the 158 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": {
    "accessKeyId": "<cloudUploadOptions.accessKeyId>",
    "bucket": "<cloudUploadOptions.bucket>",
    "directory": "<cloudUploadOptions.directory>",
    "headers": {},
    "ignoreHostAccount": true,
    "provider": "<cloudUploadOptions.provider>",
    "public": true,
    "region": "<cloudUploadOptions.region>",
    "secretAccessKey": "<cloudUploadOptions.secretAccessKey>"
  },
  "cors": "*",
  "corsFix": false,
  "customUserAgent": "<customUserAgent>",
  "dashboard": true,
  "dashboardPort": 3000,
  "deleteSessionDataOnLogout": false,
  "devtools": {
    "pass": "<devtools.pass>",
    "user": "<devtools.user>"
  },
  "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": {},
  "keepUpdated": false,
  "killClientOnLogout": false,
  "killProcessOnBan": true,
  "killProcessOnBrowserClose": false,
  "killProcessOnTimeout": false,
  "legacy": false,
  "licenseKey": {},
  "lightpanda": {
    "disableTelemetry": false,
    "executablePath": "<lightpanda.executablePath>",
    "host": "127.0.0.1",
    "portStart": 9000,
    "startupTimeoutMs": 30000
  },
  "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": {
    "enabled": false,
    "exposeToolsMeta": true,
    "path": "/mcp"
  },
  "messagePreprocessor": "<messagePreprocessor>",
  "multiDevice": true,
  "onError": "NOTHING",
  "oorTimeout": 60,
  "pluginConfig": {},
  "plugins": [],
  "popup": false,
  "port": 8080,
  "pQueueDefault": "<pQueueDefault>",
  "preprocFilter": "<preprocFilter>",
  "proxyHost": "<proxyHost>",
  "proxyServerCredentials": {
    "address": "<proxyServerCredentials.address>",
    "password": "<proxyServerCredentials.password>",
    "protocol": "<proxyServerCredentials.protocol>",
    "username": "<proxyServerCredentials.username>"
  },
  "proxyToken": "<proxyToken>",
  "qrFormat": "png",
  "qrLogSkip": false,
  "qrMax": 0,
  "qrPopUpOnly": true,
  "qrQuality": 1,
  "qrRefreshS": 0,
  "qrTimeout": 60,
  "raspi": false,
  "resizable": true,
  "restartOnCrash": "<restartOnCrash>",
  "s3Sync": {
    "accessKeyId": "<s3Sync.accessKeyId>",
    "bucket": "<s3Sync.bucket>",
    "enableLocalCompression": true,
    "endpoint": "<s3Sync.endpoint>",
    "host": "<s3Sync.host>",
    "region": "<s3Sync.region>",
    "secretAccessKey": "<s3Sync.secretAccessKey>",
    "syncInterval": 600000
  },
  "safeMode": false,
  "sandboxChats": {
    "capabilities": [
      "sendText"
    ],
    "concurrency": 1,
    "env": "none",
    "filesystem": "none",
    "idleTimeoutMs": 300000,
    "isolation": "process",
    "memoryMb": 256,
    "network": "none",
    "networkAllowlist": [],
    "timeoutMs": 30000
  },
  "screenshotOnInitializationBrowserError": false,
  "sessionData": {
    "WABrowserId": "<sessionData.WABrowserId>",
    "WASecretBundle": "<sessionData.WASecretBundle>",
    "WAToken1": "<sessionData.WAToken1>",
    "WAToken2": "<sessionData.WAToken2>"
  },
  "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": {
    "height": 900,
    "width": 1440
  },
  "waitForRipeSession": true,
  "waitForRipeSessionTimeout": 5,
  "webhook": "<webhook>"
}

This page is generated from @open-wa/config's schema plus the v5 CLI and environment adapters, so the displayed forms describe what each runtime path actually accepts.

Was this helpful?

Your answer includes the page path and docs version.