fix: stabilize live probes and docs

2026-01-11 02:24:35 +00:00
parent 6668805aca
commit 20b4e2b859
14 changed files with 149 additions and 89 deletions
--- a/docs/cli/gateway.md
+++ b/docs/cli/gateway.md
@@ -39,6 +39,7 @@ Notes:
 - `--password <password>`: password override (also sets `CLAWDBOT_GATEWAY_PASSWORD` for the process).
 - `--tailscale <off|serve|funnel>`: expose the Gateway via Tailscale.
 - `--tailscale-reset-on-exit`: reset Tailscale serve/funnel config on shutdown.
+- `--allow-unconfigured`: allow gateway start without `gateway.mode=local` in config.
 - `--dev`: create a dev config + workspace if missing (skips BOOTSTRAP.md).
 - `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`).
 - `--force`: kill any existing listener on the selected port before starting.
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -52,6 +52,7 @@ clawdbot [--dev] [--profile <name>] <command>
  providers
    list
    status
+    logs
    add
    remove
    login
@@ -74,6 +75,14 @@ clawdbot [--dev] [--profile <name>] <command>
    health
    status
    discover
+  daemon
+    status
+    install
+    uninstall
+    start
+    stop
+    restart
+  logs
  models
    list
    status
@@ -83,6 +92,12 @@ clawdbot [--dev] [--profile <name>] <command>
    fallbacks list|add|remove|clear
    image-fallbacks list|add|remove|clear
    scan
+    auth add|setup-token|paste-token
+    auth order get|set|clear
+  sandbox
+    list
+    recreate
+    explain
  wake
  cron
    status
@@ -106,7 +121,8 @@ clawdbot [--dev] [--profile <name>] <command>
    run
    notify
    camera list|snap|clip
-    canvas snapshot
+    canvas snapshot|present|hide|navigate|eval
+    canvas a2ui push|reset
    screen record
    location get
  browser
@@ -180,6 +196,7 @@ Options:
 - `--workspace <dir>`
 - `--non-interactive`
 - `--mode <local|remote>`
+- `--flow <quickstart|advanced>`
 - `--auth-choice <setup-token|claude-cli|token|openai-codex|openai-api-key|codex-cli|antigravity|gemini-api-key|zai-api-key|apiKey|minimax-cloud|minimax-api|minimax|opencode-zen|skip>`
 - `--token-provider <id>` (non-interactive; used with `--auth-choice token`)
 - `--token <token>` (non-interactive; used with `--auth-choice token`)
@@ -201,9 +218,12 @@ Options:
 - `--tailscale <off|serve|funnel>`
 - `--tailscale-reset-on-exit`
 - `--install-daemon`
+- `--no-install-daemon` (alias: `--skip-daemon`)
 - `--daemon-runtime <node|bun>`
+- `--skip-providers`
 - `--skip-skills`
 - `--skip-health`
+- `--skip-ui`
 - `--node-manager <npm|pnpm|bun>`
 - `--json`

@@ -222,19 +242,20 @@ Options:
 ## Provider helpers

 ### `providers`
-Manage chat provider accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage).
+Manage chat provider accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams).

 Subcommands:
 - `providers list`: show configured chat providers and auth profiles (Claude Code + Codex CLI OAuth sync included).
 - `providers status`: check gateway reachability and provider health (`--probe` runs extra checks; use `clawdbot health` or `clawdbot status --deep` for gateway health probes).
 - Tip: `providers status` prints warnings with suggested fixes when it can detect common misconfigurations (then points you to `clawdbot doctor`).
+- `providers logs`: show recent provider logs from the gateway log file.
 - `providers add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode.
 - `providers remove`: disable by default; pass `--delete` to remove config entries without prompts.
 - `providers login`: interactive provider login (WhatsApp Web only).
 - `providers logout`: log out of a provider session (WhatsApp Web only).

 Common options:
- `--provider <name>`: `whatsapp|telegram|discord|slack|signal|imessage`
+- `--provider <name>`: `whatsapp|telegram|discord|slack|signal|imessage|msteams`
 - `--account <id>`: provider account id (default `default`)
 - `--name <label>`: display name for the account

@@ -251,6 +272,11 @@ Common options:
 - `--no-usage`: skip provider usage/quota snapshots (OAuth/API-backed only).
 - `--json`: output JSON (includes usage unless `--no-usage` is set).

+`providers logs` options:
+- `--provider <name|all>` (default `all`)
+- `--lines <n>` (default `200`)
+- `--json`
+
 OAuth sync sources:
 - Claude Code → `anthropic:claude-cli`
  - macOS: Keychain item "Claude Code-credentials" (choose "Always Allow" to avoid launchd prompts)
@@ -336,7 +362,7 @@ Options:
 - `--session-id <id>`
 - `--thinking <off|minimal|low|medium|high>`
 - `--verbose <on|off>`
- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
+- `--provider <whatsapp|telegram|discord|slack|signal|imessage|msteams>`
 - `--local`
 - `--deliver`
 - `--json`
@@ -377,10 +403,12 @@ Show linked session health and recent recipients.

 Options:
 - `--json`
+- `--all` (full diagnosis; read-only, pasteable)
 - `--deep` (probe providers)
 - `--usage` (show provider usage/quota)
 - `--timeout <ms>`
 - `--verbose`
+- `--debug` (alias for `--verbose`)

 ### Usage tracking
 Clawdbot can surface provider usage/quota when OAuth/API creds are available.
@@ -431,8 +459,11 @@ Options:
 - `--reset` (reset dev config + credentials + sessions + workspace)
 - `--force` (kill existing listener on port)
 - `--verbose`
+- `--claude-cli-logs`
 - `--ws-log <auto|full|compact>`
 - `--compact` (alias for `--ws-log compact`)
+- `--raw-stream`
+- `--raw-stream-path <path>`

 ### `daemon`
 Manage the Gateway service (launchd/systemd/schtasks).
@@ -476,6 +507,7 @@ Subcommands:
 - `gateway call <method> [--params <json>]`
 - `gateway health`
 - `gateway status`
+- `gateway discover`

 Common RPCs:
 - `config.apply` (validate + write config + restart + wake)
@@ -495,6 +527,10 @@ clawdbot models status
 ### `models` (root)
 `clawdbot models` is an alias for `models status`.

+Root options:
+- `--status-json` (alias for `models status --json`)
+- `--status-plain` (alias for `models status --plain`)
+
 ### `models list`
 Options:
 - `--all`
@@ -545,12 +581,25 @@ Options:
 - `--max-candidates <n>`
 - `--timeout <ms>`
 - `--concurrency <n>`
+- `--no-probe`
 - `--yes`
 - `--no-input`
 - `--set-default`
 - `--set-image`
 - `--json`

+### `models auth add|setup-token|paste-token`
+Options:
+- `add`: interactive auth helper
+- `setup-token`: `--provider <name>` (default `anthropic`), `--yes`
+- `paste-token`: `--provider <name>`, `--profile-id <id>`, `--expires-in <duration>`
+
+### `models auth order get|set|clear`
+Options:
+- `get`: `--provider <name>`, `--agent <id>`, `--json`
+- `set`: `--provider <name>`, `--agent <id>`, `<profileIds...>`
+- `clear`: `--provider <name>`, `--agent <id>`
+
 ## Cron + wake

 ### `wake`
--- a/docs/cli/message.md
+++ b/docs/cli/message.md
@@ -24,8 +24,8 @@ Provider selection:
 Target formats (`--to`):
 - WhatsApp: E.164 or group JID
 - Telegram: chat id or `@username`
- Discord/Slack: `channel:<id>` or `user:<id>` (raw id is ambiguous for Discord)
- Signal: E.164, `group:<id>`, or `signal:+E.164`
+- Discord/Slack: `channel:<id>` or `user:<id>` (raw `channelId` is also accepted)
+- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
 - iMessage: handle or `chat_id:<id>`
 - MS Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`

@@ -42,61 +42,79 @@ Target formats (`--to`):
 ### Core

 - `send`
+  - Providers: WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams
  - Required: `--to`, `--message`
  - Optional: `--media`, `--reply-to`, `--thread-id`, `--gif-playback`
  - Telegram only: `--buttons-json` (requires `"inlineButtons"` in `telegram.capabilities` or `telegram.accounts.<id>.capabilities`)
+  - Telegram only: `--thread-id` (forum topic id)
+  - WhatsApp only: `--gif-playback`

 - `poll`
+  - Providers: WhatsApp/Discord/MS Teams
  - Required: `--to`, `--poll-question`, `--poll-option` (repeat)
  - Optional: `--poll-multi`, `--poll-duration-hours`, `--message`
+  - Discord only: `--poll-duration-hours`

 - `react`
+  - Providers: Discord/Slack/WhatsApp
  - Required: `--to`, `--message-id`
  - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--channel-id`
+  - WhatsApp only: `--participant`, `--from-me`

 - `reactions`
+  - Providers: Discord/Slack
  - Required: `--to`, `--message-id`
  - Optional: `--limit`, `--channel-id`

 - `read`
+  - Providers: Discord/Slack
  - Required: `--to`
  - Optional: `--limit`, `--before`, `--after`, `--around`, `--channel-id`

 - `edit`
+  - Providers: Discord/Slack
  - Required: `--to`, `--message-id`, `--message`
  - Optional: `--channel-id`

 - `delete`
+  - Providers: Discord/Slack
  - Required: `--to`, `--message-id`
  - Optional: `--channel-id`

 - `pin` / `unpin`
+  - Providers: Discord/Slack
  - Required: `--to`, `--message-id`
  - Optional: `--channel-id`

 - `pins` (list)
+  - Providers: Discord/Slack
  - Required: `--to`
  - Optional: `--channel-id`

 - `permissions`
+  - Providers: Discord
  - Required: `--to`
  - Optional: `--channel-id`

 - `search`
+  - Providers: Discord
  - Required: `--guild-id`, `--query`
  - Optional: `--channel-id`, `--channel-ids` (repeat), `--author-id`, `--author-ids` (repeat), `--limit`

 ### Threads

 - `thread create`
+  - Providers: Discord
  - Required: `--thread-name`, `--to` (channel id) or `--channel-id`
  - Optional: `--message-id`, `--auto-archive-min`

 - `thread list`
+  - Providers: Discord
  - Required: `--guild-id`
  - Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`

 - `thread reply`
+  - Providers: Discord
  - Required: `--to` (thread id), `--message`
  - Optional: `--media`, `--reply-to`

@@ -104,18 +122,22 @@ Target formats (`--to`):

 - `emoji list`
  - Discord: `--guild-id`
+  - Slack: no extra flags

 - `emoji upload`
+  - Providers: Discord
  - Required: `--guild-id`, `--emoji-name`, `--media`
  - Optional: `--role-ids` (repeat)

 ### Stickers

 - `sticker send`
+  - Providers: Discord
  - Required: `--to`, `--sticker-id` (repeat)
  - Optional: `--message`

 - `sticker upload`
+  - Providers: Discord
  - Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`

 ### Roles / Channels / Members / Voice
--- a/docs/cli/sandbox.md
+++ b/docs/cli/sandbox.md
@@ -107,22 +107,24 @@ clawdbot sandbox recreate --agent alfred

 ## Configuration

-Sandbox settings are in `clawdbot.config.json`:
+Sandbox settings live in `~/.clawdbot/clawdbot.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):

 ```jsonc
 {
-  "agent": {
-    "sandbox": {
-      "mode": "all",                    // off, non-main, all
-      "scope": "agent",                 // session, agent, shared
-      "docker": {
-        "image": "clawdbot-sandbox:bookworm-slim",
-        "containerPrefix": "clawdbot-sbx-"
-        // ... more Docker options
-      },
-      "prune": {
-        "idleHours": 24,               // Auto-prune after 24h idle
-        "maxAgeDays": 7                // Auto-prune after 7 days
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "mode": "all",                    // off, non-main, all
+        "scope": "agent",                 // session, agent, shared
+        "docker": {
+          "image": "clawdbot-sandbox:bookworm-slim",
+          "containerPrefix": "clawdbot-sbx-"
+          // ... more Docker options
+        },
+        "prune": {
+          "idleHours": 24,               // Auto-prune after 24h idle
+          "maxAgeDays": 7                // Auto-prune after 7 days
+        }
      }
    }
  }