CLI commands
Voicecall
openclaw voicecall
voicecall is a plugin-provided command. It only appears when the voice-call
plugin is installed and enabled. If openclaw voicecall is not recognized,
install and enable the plugin on the Gateway host, then restart the Gateway:
openclaw plugins install @openclaw/voice-callopenclaw plugins enable voice-callSee Voice call plugin for provider credentials and webhook configuration.
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 persisted call records or an explicit custom JSONL log. |
latency |
Summarize turn latency from call history or a custom JSONL log. |
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 setupopenclaw voicecall setup --jsonsmoke
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 smokeopenclaw voicecall smoke --to "+15555550123" # dry runopenclaw voicecall smoke --to "+15555550123" --yes # live notify callCall 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 notifystart
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 statusopenclaw voicecall status --jsonopenclaw voicecall status --call-id <id>Logs and metrics
tail
Tail persisted voice-call records from SQLite: print the last --since records
initially, then only new snapshots (--since 0 starts with new snapshots only).
With an existing custom --file
whose basename is not calls.jsonl, prints the last --since nonempty complete
lines on start, then streams new complete lines. Partial lines wait for a newline;
file replacement or observed truncation starts a fresh stream. Slow output pipes
pause reading instead of accumulating the rest of the log in memory.
| 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 SQLite or an existing custom
log selected with --file. Output is JSON with recordsScanned, turnLatency,
and listenWait summaries.
Custom logs are scanned incrementally without a byte cap on requested history.
latency selects the last N nonempty records, skips malformed JSON, and accepts
a final JSON record without a newline. It parses one selected record at a time;
memory still scales with the largest selected JSON record and the requested
number of metric samples.
| 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 serveopenclaw voicecall expose --mode funnelopenclaw voicecall expose --mode off