vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-18 20:24:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(cli): rewrite voicecall and tighten setup/health with code-verified options

Browse Source
This commit is contained in:
Vincent Koc
2026-05-10 22:40:16 +08:00
parent 25efb80e30
commit 7a463f3019
3 changed files with 199 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/cli/health.md
View File

@@ -9,12 +9,14 @@ title: "Health"
Fetch health from the running Gateway.
Options:
## Options
- `--json`: machine-readable output
- `--timeout <ms>`: connection timeout in milliseconds (default `10000`)
- `--verbose`: verbose logging
- `--debug`: alias for `--verbose`
| Flag | Default | Description |
| ---------------- | ------- | ------------------------------------------------------------------ |
| `--json` | `false` | Print machine-readable JSON instead of text. |
| `--timeout <ms>` | `10000` | Connection timeout in milliseconds. |
| `--verbose` | `false` | Verbose logging. Forces a live probe and expands per-agent output. |
| `--debug` | `false` | Alias for `--verbose`. |
Examples:

53
docs/cli/setup.md
View File

@@ -1,23 +1,39 @@
---
summary: "CLI reference for `openclaw setup` (initialize config + workspace)"
summary: "CLI reference for `openclaw setup` (initialize config plus workspace, optionally run onboarding)"
read_when:
- You're doing first-run setup without full CLI onboarding
- You want to set the default workspace path
- You need every flag and how setup decides between baseline and wizard mode
title: "Setup"
---
# `openclaw setup`
Initialize the baseline config and agent workspace without running the full guided onboarding flow.
Initialize the baseline config and agent workspace. With any onboarding flag present, also runs the wizard.
<Note>
`openclaw setup` is for mutable config installs. In Nix mode (`OPENCLAW_NIX_MODE=1`), OpenClaw refuses setup writes because the config file is managed by Nix. Agents should use the first-party [nix-openclaw Quick Start](https://github.com/openclaw/nix-openclaw#quick-start) or the equivalent source config for another Nix package.
`openclaw setup` is for mutable config installs. In Nix mode (`OPENCLAW_NIX_MODE=1`) OpenClaw refuses setup writes because the config file is managed by Nix. Use the first-party [nix-openclaw Quick Start](https://github.com/openclaw/nix-openclaw#quick-start) or the equivalent source config for another Nix package.
</Note>
Related:
## Options
- Getting started: [Getting started](/start/getting-started)
- CLI onboarding: [Onboarding (CLI)](/start/wizard)
| Flag | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------- | ---------------- |
| `--workspace <dir>` | Agent workspace directory (default `~/.openclaw/workspace`; stored as `agents.defaults.workspace`). |
| `--wizard` | Run interactive onboarding. |
| `--non-interactive` | Run onboarding without prompts. |
| `--mode <local | remote>` | Onboarding mode. |
| `--import-from <provider>` | Migration provider to run during onboarding. |
| `--import-source <path>` | Source agent home for `--import-from`. |
| `--import-secrets` | Import supported secrets during onboarding migration. |
| `--remote-url <url>` | Remote Gateway WebSocket URL. |
| `--remote-token <token>` | Remote Gateway token (optional). |
### Wizard auto-trigger
`openclaw setup` runs the wizard when any of these flags are explicitly present, even without `--wizard`:
`--wizard`, `--non-interactive`, `--mode`, `--import-from`, `--import-source`, `--import-secrets`, `--remote-url`, `--remote-token`.
## Examples
@@ -29,32 +45,15 @@ openclaw setup --wizard --import-from hermes --import-source ~/.hermes
openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
```
## Options
## Notes
- `--workspace <dir>`: agent workspace directory (stored as `agents.defaults.workspace`)
- `--wizard`: run onboarding
- `--non-interactive`: run onboarding without prompts
- `--mode <local|remote>`: onboarding mode
- `--import-from <provider>`: migration provider to run during onboarding
- `--import-source <path>`: source agent home for `--import-from`
- `--import-secrets`: import supported secrets during onboarding migration
- `--remote-url <url>`: remote Gateway WebSocket URL
- `--remote-token <token>`: remote Gateway token
To run onboarding via setup:
```bash
openclaw setup --wizard
```
Notes:
- Plain `openclaw setup` initializes config + workspace without the full onboarding flow.
- Plain `openclaw setup` initializes config and workspace without running the full onboarding flow.
- After plain setup, run `openclaw onboard` for the full guided journey, `openclaw configure` for targeted changes, or `openclaw channels add` to add channel accounts.
- Onboarding auto-runs when any onboarding flags are present (`--wizard`, `--non-interactive`, `--mode`, `--import-from`, `--import-source`, `--import-secrets`, `--remote-url`, `--remote-token`).
- If Hermes state is detected, interactive onboarding can offer migration automatically. Import onboarding requires a fresh setup; use [Migrate](/cli/migrate) for dry-run plans, backups, and overwrite mode outside onboarding.
## Related
- [CLI reference](/cli)
- [Onboarding (CLI)](/start/wizard)
- [Getting started](/start/getting-started)
- [Install overview](/install)

198
docs/cli/voicecall.md
View File

@@ -1,60 +1,192 @@
---
summary: "CLI reference for `openclaw voicecall` (voice-call plugin command surface)"
read_when:
- You use the voice-call plugin and want the CLI entry points
- You want quick examples for `voicecall setup|smoke|call|continue|dtmf|status|tail|expose`
- 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
title: "Voicecall"
---
# `openclaw voicecall`
`voicecall` is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled.
`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`, and `status`) are sent to that Gateway's
voice-call runtime. If no Gateway is reachable, they fall back to a standalone
CLI runtime.
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.
Primary doc:
## Subcommands
- Voice-call plugin: [Voice Call](/plugins/voice-call)
```bash
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>]
```
## Common commands
| 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.
```bash
openclaw voicecall setup
openclaw voicecall smoke
openclaw voicecall status --json
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
openclaw voicecall end --call-id <id>
```
`setup` prints human-readable readiness checks by default. Use `--json` for
scripts:
```bash
openclaw voicecall setup --json
```
`status` prints active calls as JSON by default. Pass `--call-id <id>` to inspect
one call.
### `smoke`
For external providers (`twilio`, `telnyx`, `plivo`), setup must resolve a public
webhook URL from `publicUrl`, a tunnel, or Tailscale exposure. A loopback/private
serve fallback is rejected because carriers cannot reach it.
Runs the same readiness checks. It will not place a real phone call unless both `--to` and `--yes` are present.
`smoke` runs the same readiness checks. It will not place a real phone call
unless 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. |
```bash
openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123" # dry run
openclaw voicecall smoke --to "+15555550123" --yes # live notify call
```
## Exposing webhooks (Tailscale)
<Note>
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.
</Note>
## 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). |
```bash
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 (e.g. `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. |
```bash
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.
| 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. |
```bash
openclaw voicecall expose --mode serve
@@ -62,7 +194,9 @@ openclaw voicecall expose --mode funnel
openclaw voicecall expose --mode off
```
Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
<Warning>
Only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
</Warning>
## Related