diff --git a/docs/cli/health.md b/docs/cli/health.md index 8d55d385f92..bdfd5ab42f1 100644 --- a/docs/cli/health.md +++ b/docs/cli/health.md @@ -9,12 +9,14 @@ title: "Health" Fetch health from the running Gateway. -Options: +## Options -- `--json`: machine-readable output -- `--timeout `: 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 ` | `10000` | Connection timeout in milliseconds. | +| `--verbose` | `false` | Verbose logging. Forces a live probe and expands per-agent output. | +| `--debug` | `false` | Alias for `--verbose`. | Examples: diff --git a/docs/cli/setup.md b/docs/cli/setup.md index 027f09a8c20..6cea62fbb73 100644 --- a/docs/cli/setup.md +++ b/docs/cli/setup.md @@ -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. -`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. -Related: +## Options -- Getting started: [Getting started](/start/getting-started) -- CLI onboarding: [Onboarding (CLI)](/start/wizard) +| Flag | Description | +| -------------------------- | --------------------------------------------------------------------------------------------------- | ---------------- | +| `--workspace ` | Agent workspace directory (default `~/.openclaw/workspace`; stored as `agents.defaults.workspace`). | +| `--wizard` | Run interactive onboarding. | +| `--non-interactive` | Run onboarding without prompts. | +| `--mode ` | Onboarding mode. | +| `--import-from ` | Migration provider to run during onboarding. | +| `--import-source ` | Source agent home for `--import-from`. | +| `--import-secrets` | Import supported secrets during onboarding migration. | +| `--remote-url ` | Remote Gateway WebSocket URL. | +| `--remote-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 ``` -## Options +## Notes -- `--workspace `: agent workspace directory (stored as `agents.defaults.workspace`) -- `--wizard`: run onboarding -- `--non-interactive`: run onboarding without prompts -- `--mode `: onboarding mode -- `--import-from `: migration provider to run during onboarding -- `--import-source `: source agent home for `--import-from` -- `--import-secrets`: import supported secrets during onboarding migration -- `--remote-url `: remote Gateway WebSocket URL -- `--remote-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) diff --git a/docs/cli/voicecall.md b/docs/cli/voicecall.md index 0e07a47602e..d04147bdab0 100644 --- a/docs/cli/voicecall.md +++ b/docs/cli/voicecall.md @@ -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 ] [--message ] [--mode ] [--yes] [--json] +openclaw voicecall call -m [-t ] [--mode ] +openclaw voicecall start --to [--message ] [--mode ] +openclaw voicecall continue --call-id --message +openclaw voicecall speak --call-id --message +openclaw voicecall dtmf --call-id --digits +openclaw voicecall end --call-id +openclaw voicecall status [--call-id ] [--json] +openclaw voicecall tail [--file ] [--since ] [--poll ] +openclaw voicecall latency [--file ] [--last ] +openclaw voicecall expose [--mode ] [--path

] [--port ] [--serve-path

] +``` -## 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 -openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify -openclaw voicecall continue --call-id --message "Any questions?" -openclaw voicecall dtmf --call-id --digits "ww123456#" -openclaw voicecall end --call-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 ` 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 ` | (none) | Phone number to call for a live smoke. | +| `--message ` | `OpenClaw voice call smoke test.` | Message to speak during the smoke call. | +| `--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) + +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. + + +## Call lifecycle + +### `call` + +Initiate an outbound voice call. + +| Flag | Required | Default | Description | +| ---------------------- | -------- | ----------------- | -------------------------------------------------------------------------- | +| `-m, --message ` | yes | (none) | Message to speak when the call connects. | +| `-t, --to ` | no | config `toNumber` | E.164 phone number to call. | +| `--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 ` | yes | (none) | Phone number to call. | +| `--message ` | no | (none) | Message to speak when the call connects. | +| `--mode ` | no | `conversation` | Call mode: `notify` or `conversation`. | + +### `continue` + +Speak a message and wait for a response. + +| Flag | Required | Description | +| ------------------ | -------- | ----------------- | +| `--call-id ` | yes | Call ID. | +| `--message ` | yes | Message to speak. | + +### `speak` + +Speak a message without waiting for a response. + +| Flag | Required | Description | +| ------------------ | -------- | ----------------- | +| `--call-id ` | yes | Call ID. | +| `--message ` | yes | Message to speak. | + +### `dtmf` + +Send DTMF digits to an active call. + +| Flag | Required | Description | +| ------------------- | -------- | ----------------------------------------- | +| `--call-id ` | yes | Call ID. | +| `--digits ` | yes | DTMF digits (e.g. `ww123456#` for waits). | + +### `end` + +Hang up an active call. + +| Flag | Required | Description | +| ---------------- | -------- | ----------- | +| `--call-id ` | yes | Call ID. | + +### `status` + +Inspect active calls. + +| Flag | Default | Description | +| ---------------- | ------- | ---------------------------- | +| `--call-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 +``` + +## 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 ` | resolved from plugin store | Path to `calls.jsonl`. | +| `--since ` | `25` | Lines to print before tailing. | +| `--poll ` | `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 ` | resolved from plugin store | Path to `calls.jsonl`. | +| `--last ` | `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 ` | `funnel` | `off`, `serve` (tailnet), or `funnel` (public). | +| `--path ` | config `tailscale.path` or `--serve-path` | Tailscale path to expose. | +| `--port ` | config `serve.port` or `3334` | Local webhook port. | +| `--serve-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. + +Only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible. + ## Related