@@ -1,68 +1,202 @@
11---
22summary: "CLI reference for `openclaw voicecall` (voice-call plugin command surface)"
33read_when:
4- - You use the voice-call plugin and want the CLI entry points
5- - You want quick examples for `voicecall setup|smoke|call|continue|dtmf|status|tail|expose`
4+ - You use the voice-call plugin and want every CLI entry point
5+ - You need flag tables and defaults for setup, smoke, call, continue, speak, dtmf, end, status, tail, latency, expose, and start
66title: "Voicecall"
77---
8899# `openclaw voicecall`
101011-`voicecall` is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled.
11+`voicecall` is a plugin-provided command. It only appears when the voice-call plugin is installed and enabled.
121213-When the Gateway is running, operational commands (`call`, `start`,
14-`continue`, `speak`, `dtmf`, `end`, and `status`) are sent to that Gateway's
15-voice-call runtime. If no Gateway is reachable, they fall back to a standalone
16-CLI runtime.
13+When the Gateway is running, operational commands (`call`, `start`, `continue`, `speak`, `dtmf`, `end`, `status`) are routed to that Gateway's voice-call runtime. If no Gateway is reachable, they fall back to a standalone CLI runtime.
171418-Primary doc:
15+## Subcommands
191620-- Voice-call plugin: [Voice Call](/plugins/voice-call)
17+```bash
18+openclaw voicecall setup [--json]
19+openclaw voicecall smoke [-t <phone>] [--message <text>] [--mode <m>] [--yes] [--json]
20+openclaw voicecall call -m <text> [-t <phone>] [--mode <m>]
21+openclaw voicecall start --to <phone> [--message <text>] [--mode <m>]
22+openclaw voicecall continue --call-id <id> --message <text>
23+openclaw voicecall speak --call-id <id> --message <text>
24+openclaw voicecall dtmf --call-id <id> --digits <digits>
25+openclaw voicecall end --call-id <id>
26+openclaw voicecall status [--call-id <id>] [--json]
27+openclaw voicecall tail [--file <path>] [--since <n>] [--poll <ms>]
28+openclaw voicecall latency [--file <path>] [--last <n>]
29+openclaw voicecall expose [--mode <m>] [--path <p>] [--port <port>] [--serve-path <p>]
30+```
31+32+| Subcommand | Description |
33+| ---------- | --------------------------------------------------------------- |
34+| `setup` | Show provider and webhook readiness checks. |
35+| `smoke` | Run readiness checks; place a live test call only with `--yes`. |
36+| `call` | Initiate an outbound voice call. |
37+| `start` | Alias for `call` with `--to` required and `--message` optional. |
38+| `continue` | Speak a message and wait for the next response. |
39+| `speak` | Speak a message without waiting for a response. |
40+| `dtmf` | Send DTMF digits to an active call. |
41+| `end` | Hang up an active call. |
42+| `status` | Inspect active calls (or one by `--call-id`). |
43+| `tail` | Tail `calls.jsonl` (useful during provider tests). |
44+| `latency` | Summarize turn-latency metrics from `calls.jsonl`. |
45+| `expose` | Toggle Tailscale serve/funnel for the webhook endpoint. |
46+47+## Setup and smoke
214822-## Common commands
49+### `setup`
50+51+Prints human-readable readiness checks by default. Pass `--json` for scripts.
23522453```bash
2554openclaw voicecall setup
55+openclaw voicecall setup --json
56+```
57+58+### `smoke`
59+60+Runs the same readiness checks. It will not place a real phone call unless both `--to` and `--yes` are present.
61+62+| Flag | Default | Description |
63+| ------------------ | --------------------------------- | --------------------------------------- |
64+| `-t, --to <phone>` | (none) | Phone number to call for a live smoke. |
65+| `--message <text>` | `OpenClaw voice call smoke test.` | Message to speak during the smoke call. |
66+| `--mode <mode>` | `notify` | Call mode: `notify` or `conversation`. |
67+| `--yes` | `false` | Actually place the live outbound call. |
68+| `--json` | `false` | Print machine-readable JSON. |
69+70+```bash
2671openclaw voicecall smoke
27-openclaw voicecall status --json
28-openclaw voicecall status --call-id <id>
29-openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
30-openclaw voicecall continue --call-id <id> --message "Any questions?"
31-openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
32-openclaw voicecall end --call-id <id>
72+openclaw voicecall smoke --to "+15555550123" # dry run
73+openclaw voicecall smoke --to "+15555550123" --yes # live notify call
3374```
347535-`setup` prints human-readable readiness checks by default. Use `--json` for
36-scripts:
76+<Note>
77+For external providers (`twilio`, `telnyx`, `plivo`), `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.
78+</Note>
79+80+## Call lifecycle
81+82+### `call`
83+84+Initiate an outbound voice call.
85+86+| Flag | Required | Default | Description |
87+| ---------------------- | -------- | ----------------- | -------------------------------------------------------------------------- |
88+| `-m, --message <text>` | yes | (none) | Message to speak when the call connects. |
89+| `-t, --to <phone>` | no | config `toNumber` | E.164 phone number to call. |
90+| `--mode <mode>` | no | `conversation` | Call mode: `notify` (hang up after message) or `conversation` (stay open). |
37913892```bash
39-openclaw voicecall setup --json
93+openclaw voicecall call --to "+15555550123" --message "Hello"
94+openclaw voicecall call -m "Heads up" --mode notify
4095```
419642-`status` prints active calls as JSON by default. Pass `--call-id <id>` to inspect
43-one call.
97+### `start`
98+99+Alias for `call` with a different default flag shape.
100+101+| Flag | Required | Default | Description |
102+| ------------------ | -------- | -------------- | ---------------------------------------- |
103+| `--to <phone>` | yes | (none) | Phone number to call. |
104+| `--message <text>` | no | (none) | Message to speak when the call connects. |
105+| `--mode <mode>` | no | `conversation` | Call mode: `notify` or `conversation`. |
106+107+### `continue`
108+109+Speak a message and wait for a response.
4411045-For external providers (`twilio`, `telnyx`, `plivo`), setup must resolve a public
46-webhook URL from `publicUrl`, a tunnel, or Tailscale exposure. A loopback/private
47-serve fallback is rejected because carriers cannot reach it.
111+| Flag | Required | Description |
112+| ------------------ | -------- | ----------------- |
113+| `--call-id <id>` | yes | Call ID. |
114+| `--message <text>` | yes | Message to speak. |
4811549-`smoke` runs the same readiness checks. It will not place a real phone call
50-unless both `--to` and `--yes` are present:
116+### `speak`
117+118+Speak a message without waiting for a response.
119+120+| Flag | Required | Description |
121+| ------------------ | -------- | ----------------- |
122+| `--call-id <id>` | yes | Call ID. |
123+| `--message <text>` | yes | Message to speak. |
124+125+### `dtmf`
126+127+Send DTMF digits to an active call.
128+129+| Flag | Required | Description |
130+| ------------------- | -------- | ----------------------------------------- |
131+| `--call-id <id>` | yes | Call ID. |
132+| `--digits <digits>` | yes | DTMF digits (e.g. `ww123456#` for waits). |
133+134+### `end`
135+136+Hang up an active call.
137+138+| Flag | Required | Description |
139+| ---------------- | -------- | ----------- |
140+| `--call-id <id>` | yes | Call ID. |
141+142+### `status`
143+144+Inspect active calls.
145+146+| Flag | Default | Description |
147+| ---------------- | ------- | ---------------------------- |
148+| `--call-id <id>` | (none) | Restrict output to one call. |
149+| `--json` | `false` | Print machine-readable JSON. |
5115052151```bash
53-openclaw voicecall smoke --to "+15555550123" # dry run
54-openclaw voicecall smoke --to "+15555550123" --yes # live notify call
152+openclaw voicecall status
153+openclaw voicecall status --json
154+openclaw voicecall status --call-id <id>
55155```
5615657-## Exposing webhooks (Tailscale)
157+## Logs and metrics
158+159+### `tail`
160+161+Tail the voice-call JSONL log. Prints the last `--since` lines on start, then streams new lines as they are written.
162+163+| Flag | Default | Description |
164+| --------------- | -------------------------- | ------------------------------ |
165+| `--file <path>` | resolved from plugin store | Path to `calls.jsonl`. |
166+| `--since <n>` | `25` | Lines to print before tailing. |
167+| `--poll <ms>` | `250` (minimum 50) | Poll interval in milliseconds. |
168+169+### `latency`
170+171+Summarize turn-latency and listen-wait metrics from `calls.jsonl`. Output is JSON with `recordsScanned`, `turnLatency`, and `listenWait` summaries.
172+173+| Flag | Default | Description |
174+| --------------- | -------------------------- | ------------------------------------ |
175+| `--file <path>` | resolved from plugin store | Path to `calls.jsonl`. |
176+| `--last <n>` | `200` (minimum 1) | Number of recent records to analyze. |
177+178+## Exposing webhooks
179+180+### `expose`
181+182+Enable, disable, or change the Tailscale serve/funnel configuration for the voice webhook.
183+184+| Flag | Default | Description |
185+| --------------------- | ----------------------------------------- | ----------------------------------------------- |
186+| `--mode <mode>` | `funnel` | `off`, `serve` (tailnet), or `funnel` (public). |
187+| `--path <path>` | config `tailscale.path` or `--serve-path` | Tailscale path to expose. |
188+| `--port <port>` | config `serve.port` or `3334` | Local webhook port. |
189+| `--serve-path <path>` | config `serve.path` or `/voice/webhook` | Local webhook path. |
5819059191```bash
60192openclaw voicecall expose --mode serve
61193openclaw voicecall expose --mode funnel
62194openclaw voicecall expose --mode off
63195```
6419665-Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
197+<Warning>
198+Only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
199+</Warning>
6620067201## Related
68202此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。