vilvona 1.0.0

package/docs/gateway/external-apps.md

@@ -0,0 +1,86 @@
+---
+summary: "Current integration path for external apps, scripts, dashboards, CI jobs, and IDE extensions"
+title: "Gateway integrations for external apps"
+sidebarTitle: "External apps"
+read_when:
+  - You are building an external app, script, dashboard, CI job, or IDE extension that talks to OpenClaw
+  - You are choosing between Gateway RPC and the Plugin SDK
+  - You are integrating with Gateway agent runs, sessions, events, approvals, models, or tools
+---
+
+External apps should talk to OpenClaw through the Gateway protocol today. Use
+Gateway WebSocket and RPC methods when a script, dashboard, CI job, IDE
+extension, or another process wants to start agent runs, stream events, wait for
+results, cancel work, or inspect Gateway resources.
+
+<Warning>
+  There is no public npm client package yet. Do not add OpenClaw client package
+  names as application dependencies until release notes announce a published
+  package and this page includes install instructions.
+</Warning>
+
+<Note>
+  This page is for code outside the OpenClaw process. Plugin code that runs
+  inside OpenClaw should use documented `openclaw/plugin-sdk/*` subpaths instead.
+</Note>
+
+## What is available today
+
+| Surface                                 | Status | Use it for                                                                                    |
+| --------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
+| [Gateway protocol](/gateway/protocol)   | Ready  | WebSocket transport, connect handshake, auth scopes, protocol versioning, and events.         |
+| [Gateway RPC reference](/reference/rpc) | Ready  | Current Gateway methods for agents, sessions, tasks, models, tools, artifacts, and approvals. |
+| [`openclaw agent`](/cli/agent)          | Ready  | One-shot script integration when shelling out to the CLI is enough.                           |
+| [`openclaw message`](/cli/message)      | Ready  | Sending messages or channel actions from scripts.                                             |
+
+The source tree contains internal package work for a future client library, but
+that is not a public install surface. Treat it as preview implementation detail
+until the packages are published and versioned.
+
+## Recommended path
+
+1. Run or discover a Gateway.
+2. Connect over the [Gateway protocol](/gateway/protocol).
+3. Call documented RPC methods from [Gateway RPC reference](/reference/rpc).
+4. Pin the OpenClaw version you test against.
+5. Recheck the RPC reference when upgrading OpenClaw.
+
+For agent runs, start with the `agent` RPC and pair it with `agent.wait` when
+you need a terminal result. For durable conversation state, use the `sessions.*`
+methods. For UI integrations, subscribe to Gateway events and render only the
+event families your app understands.
+
+## App code vs plugin code
+
+Use Gateway RPC when code lives outside OpenClaw:
+
+- Node scripts that start or observe agent runs
+- CI jobs that call a Gateway
+- dashboards and admin panels
+- IDE extensions
+- external bridges that do not need to become channel plugins
+- integration tests with fake or real Gateway transports
+
+Use the Plugin SDK when code runs inside OpenClaw:
+
+- provider plugins
+- channel plugins
+- tool or lifecycle hooks
+- agent harness plugins
+- trusted runtime helpers
+
+External apps should not import `openclaw/plugin-sdk/*`; those subpaths are for
+plugins loaded by OpenClaw.
+
+## Related
+
+- [Gateway protocol](/gateway/protocol)
+- [Gateway RPC reference](/reference/rpc)
+- [CLI agent command](/cli/agent)
+- [CLI message command](/cli/message)
+- [Agent loop](/concepts/agent-loop)
+- [Agent runtimes](/concepts/agent-runtimes)
+- [Sessions](/concepts/session)
+- [Background tasks](/automation/tasks)
+- [ACP agents](/tools/acp-agents)
+- [Plugin SDK overview](/plugins/sdk-overview)

package/docs/gateway/gateway-lock.md

@@ -0,0 +1,37 @@
+---
+summary: "Gateway singleton guard using the WebSocket listener bind"
+read_when:
+  - Running or debugging the gateway process
+  - Investigating single-instance enforcement
+title: "Gateway lock"
+---
+
+## Why
+
+- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
+- Survive crashes/SIGKILL without leaving stale lock files.
+- Fail fast with a clear error when the control port is already occupied.
+
+## Mechanism
+
+- The gateway first acquires a per-config lock file under the state lock directory and probes the configured port for an existing listener.
+- If the recorded lock owner is gone, the port is free, or the lock is stale, startup reclaims the lock and continues.
+- The gateway then binds the HTTP/WebSocket listener (default `ws://127.0.0.1:18789`) using an exclusive TCP listener.
+- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- On shutdown the gateway closes the HTTP/WebSocket server and removes the lock file.
+
+## Error surface
+
+- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
+
+## Operational notes
+
+- If the port is occupied by _another_ process, the error is the same; free the port or choose another with `openclaw gateway --port <port>`.
+- Under a service supervisor, a new gateway process that sees an existing healthy `/healthz` responder leaves that process in control. On systemd, the duplicate starter exits with code 78 so the default `RestartPreventExitStatus=78` stops `Restart=always` from looping on a lock or `EADDRINUSE` conflict. If the existing process never becomes healthy, retries are bounded and startup fails with a clear lock error instead of looping forever.
+- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the lock file plus HTTP/WebSocket bind.
+
+## Related
+
+- [Multiple Gateways](/gateway/multiple-gateways) — running multiple instances with unique ports
+- [Troubleshooting](/gateway/troubleshooting) — diagnosing `EADDRINUSE` and port conflicts

package/docs/gateway/health.md

@@ -0,0 +1,73 @@
+---
+summary: "Health check commands and gateway health monitoring"
+read_when:
+  - Diagnosing channel connectivity or gateway health
+  - Understanding health check CLI commands and options
+title: "Health checks"
+---
+
+Short guide to verify channel connectivity without guessing.
+
+## Quick checks
+
+- `openclaw status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
+- `openclaw status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
+- `openclaw status --deep` — asks the running gateway for a live health probe (`health` with `probe:true`), including per-account channel probes when supported.
+- `openclaw health` — asks the running gateway for its health snapshot (WS-only; no direct channel sockets from the CLI).
+- `openclaw health --verbose` — forces a live health probe and prints gateway connection details.
+- `openclaw health --json` — machine-readable health snapshot output.
+- Send `/status` as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent.
+- Logs: tail `/tmp/openclaw/openclaw-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
+
+For Discord and other chat providers, session rows are not socket liveness.
+`openclaw sessions`, Gateway `sessions.list`, and the agent `sessions_list` tool
+read stored conversation state. A provider can reconnect and show healthy channel
+status before any new session row is materialized. Use the channel status and
+health commands above for live connectivity checks.
+
+## Deep diagnostics
+
+- Creds on disk: `ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
+- Session store: `ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
+- Relink flow: `openclaw channels logout && openclaw channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
+- Diagnostics are enabled by default. The gateway records operational facts unless `diagnostics.enabled: false` is set. Memory events record RSS/heap byte counts, threshold pressure, and growth pressure. Critical memory pressure logs through the gateway logger. When `diagnostics.memoryPressureSnapshot: true` is set, critical memory pressure also writes a pre-OOM stability bundle with V8 heap stats, Linux cgroup counters when available, active resource counts, and the largest session/transcript files by redacted relative path. Liveness warnings record event-loop delay, event-loop utilization, CPU-core ratio, and active/waiting/queued session counts when the process is running but saturated. Oversized-payload events record what was rejected, truncated, or chunked, plus sizes and limits when available. They do not record the message text, attachment contents, webhook body, raw request or response body, tokens, cookies, or secret values. The same heartbeat starts the bounded stability recorder, which is available through `openclaw gateway stability` or the `diagnostics.stability` Gateway RPC. Fatal Gateway exits, shutdown timeouts, and restart startup failures persist the latest recorder snapshot under `~/.openclaw/logs/stability/` when events exist; critical memory pressure does too only when `diagnostics.memoryPressureSnapshot: true` is set. Inspect the newest saved bundle with `openclaw gateway stability --bundle latest`.
+- For bug reports, run `openclaw gateway diagnostics export` and attach the generated zip. The export combines a Markdown summary, the newest stability bundle, sanitized log metadata, sanitized Gateway status/health snapshots, and config shape. It is meant to be shared: chat text, webhook bodies, tool outputs, credentials, cookies, account/message identifiers, and secret values are omitted or redacted. See [Diagnostics Export](/gateway/diagnostics).
+
+## Health monitor config
+
+- `gateway.channelHealthCheckMinutes`: how often the gateway checks channel health. Default: `5`. Set `0` to disable health-monitor restarts globally.
+- `gateway.channelStaleEventThresholdMinutes`: how long a connected channel can stay idle before the health monitor treats it as stale and restarts it. Default: `30`. Keep this greater than or equal to `gateway.channelHealthCheckMinutes`.
+- `gateway.channelMaxRestartsPerHour`: rolling one-hour cap for health-monitor restarts per channel/account. Default: `10`.
+- `channels.<provider>.healthMonitor.enabled`: disable health-monitor restarts for a specific channel while leaving global monitoring enabled.
+- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: multi-account override that wins over the channel-level setting.
+- These per-channel overrides apply to the built-in channel monitors that expose them today: Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, and WhatsApp.
+
+## When something fails
+
+- `logged out` or status 409–515 → relink with `openclaw channels logout` then `openclaw channels login`.
+- Gateway unreachable → start it: `openclaw gateway --port 18789` (use `--force` if the port is busy).
+- No inbound messages → confirm linked phone is online and the sender is allowed (`channels.whatsapp.allowFrom`); for group chats, ensure allowlist + mention rules match (`channels.whatsapp.groups`, `agents.list[].groupChat.mentionPatterns`).
+
+## Dedicated "health" command
+
+`openclaw health` asks the running gateway for its health snapshot (no direct channel
+sockets from the CLI). By default it can return a fresh cached gateway snapshot; the
+gateway then refreshes that cache in the background. `openclaw health --verbose` forces
+a live probe instead. The command reports linked creds/auth age when available,
+per-channel probe summaries, session-store summary, and a probe duration. It exits
+non-zero if the gateway is unreachable or the probe fails/timeouts.
+
+Options:
+
+- `--json`: machine-readable JSON output
+- `--timeout <ms>`: override the default 10s probe timeout
+- `--verbose`: force a live probe and print gateway connection details
+- `--debug`: alias for `--verbose`
+
+The health snapshot includes: `ok` (boolean), `ts` (timestamp), `durationMs` (probe time), per-channel status, agent availability, and session-store summary.
+
+## Related
+
+- [Gateway runbook](/gateway)
+- [Diagnostics export](/gateway/diagnostics)
+- [Gateway troubleshooting](/gateway/troubleshooting)