openclaw voicecall CLI Reference

`openclaw voicecall`

voicecall is a command supplied by a plugin. It shows up only when the voice-call plugin is installed and active.

While the Gateway is up, operational commands (call, start, continue, speak, dtmf, end, status) are directed to the voice-call runtime on that Gateway. When no Gateway is available, they switch to a standalone CLI runtime instead. status relies on the persisted call store and does not spin up that runtime.

The fallback only covers cases where transport is missing. If the Gateway returns a request or authentication error, or stays silent past the timeout, the command exits with a nonzero status and directs you to openclaw gateway status; it never launches a second webhook server. When the standalone fallback cannot bind the configured serve.port, the error points to the likely running Gateway rather than showing a raw EADDRINUSE failure.

Subcommands

openclaw voicecall setup    [--json]
openclaw voicecall smoke    [-t <phone>] [--message <text>] [--mode <m>] [--yes] [--json]
openclaw voicecall call     -m <text> [-t <phone>] [--mode <m>]
openclaw voicecall start    --to <phone> [--message <text>] [--mode <m>]
openclaw voicecall continue --call-id <id> --message <text>
openclaw voicecall speak    --call-id <id> --message <text>
openclaw voicecall dtmf     --call-id <id> --digits <digits>
openclaw voicecall end      --call-id <id>
openclaw voicecall status   [--call-id <id>] [--json]
openclaw voicecall tail     [--file <path>] [--since <n>] [--poll <ms>]
openclaw voicecall latency  [--file <path>] [--last <n>]
openclaw voicecall expose   [--mode <m>] [--path <p>] [--port <port>] [--serve-path <p>]

Subcommand	Description
`setup`	Display readiness checks for the provider and webhook.
`smoke`	Execute readiness checks; make a live test call only with `--yes`.
`call`	Start an outbound voice call.
`start`	Shortcut for `call`, where `--to` is mandatory and `--message` is optional.
`continue`	Say a message, then wait for the next reply.
`speak`	Say a message without waiting for a reply.
`dtmf`	Send DTMF tones to a call that is currently active.
`end`	End an active call.
`status`	Look at active calls, or a single one by `--call-id`.
`tail`	Follow `calls.jsonl` (handy while testing providers).
`latency`	Pull together turn-latency stats from `calls.jsonl`.
`expose`	Switch Tailscale serve/funnel for the webhook endpoint on or off.

Setup and smoke

`setup`

By default, human-readable readiness checks are printed. For scripting, pass --json.

openclaw voicecall setup
openclaw voicecall setup --json

`smoke`

The same readiness checks are run here. A real phone call is placed only when both --to and --yes are supplied.

Flag	Default	Description
`-t, --to <phone>`	(none)	Number to dial for a live smoke test.
`--message <text>`	`OpenClaw voice call smoke test.`	Text spoken during the smoke call.
`--mode <mode>`	`notify`	Call mode: `notify` or `conversation`.
`--yes`	`false`	Truly place the live outbound call.
`--json`	`false`	Emit machine-readable JSON.

openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"        # dry run
openclaw voicecall smoke --to "+15555550123" --yes  # live notify call

Note

With external providers (plivo, telnyx, twilio), setup and smoke demand a public webhook URL from publicUrl, a tunnel, or Tailscale exposure. A loopback or private serve fallback is refused, since carriers cannot reach it.

Call lifecycle

`call`

Place an outgoing voice call.

Flag	Required	Default	Description
`-m, --message <text>`	yes	(none)	Text to say once the call picks up.
`-t, --to <phone>`	no	config `toNumber`	Destination number in E.164 format.
`--mode <mode>`	no	`conversation`	Mode of the call: `notify` (end after the message) or `conversation` (keep the line open).

openclaw voicecall call --to "+15555550123" --message "Hello"
openclaw voicecall call -m "Heads up" --mode notify

`start`

A shortcut for call that uses a distinct default flag layout.

Flag	Required	Default	Description
`--to <phone>`	yes	(none)	Number to dial.
`--message <text>`	no	(none)	Text to say once the call picks up.
`--mode <mode>`	no	`conversation`	Mode of the call: `notify` or `conversation`.

`continue`

Deliver a message and then listen for input.

Flag	Required	Description
`--call-id <id>`	yes	Identifier of the call.
`--message <text>`	yes	Text to speak.

`speak`

Deliver a message without listening for input.

Flag	Required	Description
`--call-id <id>`	yes	Identifier of the call.
`--message <text>`	yes	Text to speak.

`dtmf`

Send DTMF tones to a live call.

Flag	Required	Description
`--call-id <id>`	yes	Identifier of the call.
`--digits <digits>`	yes	DTMF tones (such as `ww123456#` to insert pauses).

`end`

Terminate a live call.

Flag	Required	Description
`--call-id <id>`	yes	Identifier of the call.

`status`

View calls that are currently active.

Flag	Default	Description
`--call-id <id>`	(none)	Limit results to a single call.
`--json`	`false`	Emit output as machine-readable JSON.

openclaw voicecall status
openclaw voicecall status --json
openclaw voicecall status --call-id <id>

Logs and metrics

`tail`

Follow the voice-call JSONL log. On startup the last --since lines are shown, then newly written lines appear as they arrive.

Flag	Default	Description
`--file <path>`	resolved from plugin store	Location of `calls.jsonl`.
`--since <n>`	`25`	Number of lines shown before following.
`--poll <ms>`	`250` (minimum 50)	Polling frequency in milliseconds.

`latency`

Compute turn-latency and listen-wait statistics from calls.jsonl. The result is JSON containing recordsScanned, turnLatency, and listenWait breakdowns.

Flag	Default	Description
`--file <path>`	resolved from plugin store	Location of `calls.jsonl`.
`--last <n>`	`200` (minimum 1)	How many recent entries to evaluate.

Exposing webhooks

`expose`

Turn on, turn off, or modify the Tailscale serve or funnel setup for the voice webhook. When realtime or streaming audio is active, the command also publishes or removes that mode's WebSocket stream path. The external HTTPS port is taken from tailscale.port (defaulting to 443); Funnel accepts 443, 8443, or 10000.

Flag	Default	Description
`--mode <mode>`	`funnel`	`off`, `serve` (tailnet), or `funnel` (public).
`--path <path>`	config `tailscale.path` or `--serve-path`	Tailscale path to expose.
`--port <port>`	config `serve.port` or `3334`	Local webhook port.
`--serve-path <path>`	config `serve.path` or `/voice/webhook`	Local webhook path.

openclaw voicecall expose --mode serve
openclaw voicecall expose --mode funnel
openclaw voicecall expose --mode off

Warning

Restrict the webhook endpoint to trusted networks only. Whenever possible, choose Tailscale Serve over Funnel.