openclaw/docs/cli/voicecall.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw voicecall` (voice-call plugin command surface)	You use the voice-call plugin and want every CLI entry point You need flag tables and defaults for setup, smoke, call, continue, speak, dtmf, end, status, tail, latency, expose, and start	Voicecall

openclaw voicecall

voicecall is a plugin-provided command. It only appears when the voice-call plugin is installed and enabled.

When the Gateway is running, operational commands (call, start, continue, speak, dtmf, end, status) route to that Gateway's voice-call runtime. If no Gateway is reachable, they fall back to a standalone CLI runtime. status uses the persisted call store instead of starting that runtime.

Fallback is limited to transport-level absence. If the Gateway responds with a request or authentication error, or does not answer before the timeout, the command exits nonzero and points to openclaw gateway status; it does not start a second webhook server. If standalone fallback cannot bind the configured serve.port, the error identifies the likely running Gateway instead of printing 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	Show provider and webhook readiness checks.
smoke	Run readiness checks; place a live test call only with --yes.
call	Initiate an outbound voice call.
start	Alias for call with --to required and --message optional.
continue	Speak a message and wait for the next response.
speak	Speak a message without waiting for a response.
dtmf	Send DTMF digits to an active call.
end	Hang up an active call.
status	Inspect active calls (or one by --call-id).
tail	Tail calls.jsonl (useful during provider tests).
latency	Summarize turn-latency metrics from calls.jsonl.
expose	Toggle Tailscale serve/funnel for the webhook endpoint.

Setup and smoke

setup

Prints human-readable readiness checks by default. Pass --json for scripts.

openclaw voicecall setup
openclaw voicecall setup --json

smoke

Runs the same readiness checks. Places a real phone call only when both --to and --yes are present.

Flag	Default	Description
-t, --to <phone>	(none)	Phone number to call for a live smoke.
--message <text>	OpenClaw voice call smoke test.	Message to speak during the smoke call.
--mode <mode>	notify	Call mode: notify or conversation.
--yes	false	Actually place the live outbound call.
--json	false	Print machine-readable JSON.

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

For external providers (`plivo`, `telnyx`, `twilio`), `setup` and `smoke` require a public webhook URL from `publicUrl`, a tunnel, or Tailscale exposure. A loopback or private serve fallback is rejected because carriers cannot reach it.

Call lifecycle

call

Initiate an outbound voice call.

Flag	Required	Default	Description
-m, --message <text>	yes	(none)	Message to speak when the call connects.
-t, --to <phone>	no	config toNumber	E.164 phone number to call.
--mode <mode>	no	conversation	Call mode: notify (hang up after message) or conversation (stay open).

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

start

Alias for call with a different default flag shape.

Flag	Required	Default	Description
--to <phone>	yes	(none)	Phone number to call.
--message <text>	no	(none)	Message to speak when the call connects.
--mode <mode>	no	conversation	Call mode: notify or conversation.

continue

Speak a message and wait for a response.

Flag	Required	Description
--call-id <id>	yes	Call ID.
--message <text>	yes	Message to speak.

speak

Speak a message without waiting for a response.

Flag	Required	Description
--call-id <id>	yes	Call ID.
--message <text>	yes	Message to speak.

dtmf

Send DTMF digits to an active call.

Flag	Required	Description
--call-id <id>	yes	Call ID.
--digits <digits>	yes	DTMF digits (for example ww123456# for waits).

end

Hang up an active call.

Flag	Required	Description
--call-id <id>	yes	Call ID.

status

Inspect active calls.

Flag	Default	Description
--call-id <id>	(none)	Restrict output to one call.
--json	false	Print machine-readable JSON.

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

Logs and metrics

tail

Tail the voice-call JSONL log. Prints the last --since lines on start, then streams new lines as they are written.

Flag	Default	Description
--file <path>	resolved from plugin store	Path to calls.jsonl.
--since <n>	25	Lines to print before tailing.
--poll <ms>	250 (minimum 50)	Poll interval in milliseconds.

latency

Summarize turn-latency and listen-wait metrics from calls.jsonl. Output is JSON with recordsScanned, turnLatency, and listenWait summaries.

Flag	Default	Description
--file <path>	resolved from plugin store	Path to calls.jsonl.
--last <n>	200 (minimum 1)	Number of recent records to analyze.

Exposing webhooks

expose

Enable, disable, or change the Tailscale serve/funnel configuration for the voice webhook. When realtime or streaming audio is enabled, the command also exposes or clears that mode's WebSocket stream path. The external HTTPS port comes from tailscale.port (default 443); Funnel supports 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

Only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.

Related

• CLI reference
• Voice call plugin