From 1aaca6eac246432e3c0f74cd8ea668752c7faf69 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Fri, 24 Apr 2026 06:32:20 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@cb4fc585472a3ac9961a8d2948eb2904777585b0 --- .openclaw-sync/source.json | 4 +-- .../.generated/plugin-sdk-api-baseline.sha256 | 4 +-- docs/gateway/bonjour.md | 19 ++++++++----- docs/plugins/architecture-internals.md | 14 ++++++++++ docs/plugins/architecture.md | 6 +++-- docs/plugins/manifest.md | 10 ++++--- docs/plugins/sdk-overview.md | 27 +++++++++++++++++++ 7 files changed, 67 insertions(+), 17 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index e14f066ca..03ec68daf 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "b588b5a2300794745900977d8bf5059898eb092c", - "syncedAt": "2026-04-24T06:21:36.040Z" + "sha": "cb4fc585472a3ac9961a8d2948eb2904777585b0", + "syncedAt": "2026-04-24T06:30:49.022Z" } diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256 index 2ee0b7451..e476d320f 100644 --- a/docs/.generated/plugin-sdk-api-baseline.sha256 +++ b/docs/.generated/plugin-sdk-api-baseline.sha256 @@ -1,2 +1,2 @@ -3ce0dadfe0cac406051ff95ee8201a508d588e634b98ac22659e6b010c3641f6 plugin-sdk-api-baseline.json -69c9058277b146196a3a3ef49fe193e42987a3642a233732370c9ddae60ddf62 plugin-sdk-api-baseline.jsonl +ad7ec565b1702a76a87b1a08904445c9838e10d4d41fb1c58909af886b702d80 plugin-sdk-api-baseline.json +907a07c206dd52ebd910793fab7bca8640c37cf82ff7e7cca88ab1b12b4fbdfe plugin-sdk-api-baseline.jsonl diff --git a/docs/gateway/bonjour.md b/docs/gateway/bonjour.md index 31738f80b..90ef9cefd 100644 --- a/docs/gateway/bonjour.md +++ b/docs/gateway/bonjour.md @@ -9,9 +9,10 @@ title: "Bonjour discovery" # Bonjour / mDNS discovery OpenClaw uses Bonjour (mDNS / DNS‑SD) to discover an active Gateway (WebSocket endpoint). -Multicast `local.` browsing is a **LAN-only convenience**. For cross-network discovery, the -same beacon can also be published through a configured wide-area DNS-SD domain. Discovery is -still best-effort and does **not** replace SSH or Tailnet-based connectivity. +Multicast `local.` browsing is a **LAN-only convenience**. The bundled `bonjour` +plugin owns LAN advertising and is enabled by default. For cross-network discovery, +the same beacon can also be published through a configured wide-area DNS-SD domain. +Discovery is still best-effort and does **not** replace SSH or Tailnet-based connectivity. ## Wide-area Bonjour (Unicast DNS-SD) over Tailscale @@ -79,7 +80,9 @@ For tailnet‑only setups: ## What advertises -Only the Gateway advertises `_openclaw-gw._tcp`. +Only the Gateway advertises `_openclaw-gw._tcp`. LAN multicast advertising is +provided by the bundled `bonjour` plugin; wide-area DNS-SD publishing remains +Gateway-owned. ## Service types @@ -97,7 +100,7 @@ The Gateway advertises small non‑secret hints to make UI flows convenient: - `gatewayTlsSha256=` (only when TLS is enabled and fingerprint is available) - `canvasPort=` (only when the canvas host is enabled; currently the same as `gatewayPort`) - `transport=gateway` -- `tailnetDns=` (optional hint when Tailnet is available) +- `tailnetDns=` (mDNS full mode only, optional hint when Tailnet is available) - `sshPort=` (mDNS full mode only; wide-area DNS-SD may omit it) - `cliPath=` (mDNS full mode only; wide-area DNS-SD still writes it as a remote-install hint) @@ -167,10 +170,12 @@ sequences (e.g. spaces become `\032`). ## Disabling / configuration -- `OPENCLAW_DISABLE_BONJOUR=1` disables advertising (legacy: `OPENCLAW_DISABLE_BONJOUR`). +- `openclaw plugins disable bonjour` disables LAN multicast advertising by disabling the bundled plugin. +- `openclaw plugins enable bonjour` restores the default LAN discovery plugin. +- `OPENCLAW_DISABLE_BONJOUR=1` disables LAN multicast advertising without changing plugin config; accepted truthy values are `1`, `true`, `yes`, and `on` (legacy: `OPENCLAW_DISABLE_BONJOUR`). - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode. - `OPENCLAW_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `OPENCLAW_SSH_PORT`). -- `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT (legacy: `OPENCLAW_TAILNET_DNS`). +- `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT when mDNS full mode is enabled (legacy: `OPENCLAW_TAILNET_DNS`). - `OPENCLAW_CLI_PATH` overrides the advertised CLI path (legacy: `OPENCLAW_CLI_PATH`). ## Related docs diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md index e1422b68c..b874b77fe 100644 --- a/docs/plugins/architecture-internals.md +++ b/docs/plugins/architecture-internals.md @@ -884,6 +884,20 @@ Or point `OPENCLAW_PLUGIN_CATALOG_PATHS` (or `OPENCLAW_MPM_CATALOG_PATHS`) at one or more JSON files (comma/semicolon/`PATH`-delimited). Each file should contain `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. The parser also accepts `"packages"` or `"plugins"` as legacy aliases for the `"entries"` key. +Generated channel catalog entries and provider install catalog entries expose +normalized install-source facts next to the raw `openclaw.install` block. The +normalized facts identify whether the npm spec is an exact version or floating +selector, whether expected integrity metadata is present, and whether a local +source path is also available. Consumers should treat `installSource` as an +additive optional field so older hand-built entries and compatibility shims do +not have to synthesize it. This lets onboarding and diagnostics explain +source-plane state without importing plugin runtime. + +Official external npm entries should prefer an exact `npmSpec` plus +`expectedIntegrity`. Bare package names and dist-tags still work for +compatibility, but they surface source-plane warnings so the catalog can move +toward pinned, integrity-checked installs without breaking existing plugins. + ## Context engine plugins Context engine plugins own session context orchestration for ingest, assembly, diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md index 071a5a0cc..dbb27714b 100644 --- a/docs/plugins/architecture.md +++ b/docs/plugins/architecture.md @@ -49,9 +49,11 @@ native OpenClaw plugin registers against one or more capability types: | Web fetch | `api.registerWebFetchProvider(...)` | `firecrawl` | | Web search | `api.registerWebSearchProvider(...)` | `google` | | Channel / messaging | `api.registerChannel(...)` | `msteams`, `matrix` | +| Gateway discovery | `api.registerGatewayDiscoveryService(...)` | `bonjour` | -A plugin that registers zero capabilities but provides hooks, tools, or -services is a **legacy hook-only** plugin. That pattern is still fully supported. +A plugin that registers zero capabilities but provides hooks, tools, discovery +services, or background services is a **legacy hook-only** plugin. That pattern +is still fully supported. ### External compatibility stance diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index def28efcf..6e633dfec 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -591,10 +591,12 @@ registry loading. Invalid values are rejected; newer-but-valid values skip the plugin on older hosts. Exact npm version pinning already lives in `npmSpec`, for example -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Pair that with -`expectedIntegrity` when you want update flows to fail closed if the fetched -npm artifact no longer matches the pinned release. Interactive onboarding -offers trusted registry npm specs, including bare package names and dist-tags. +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Official external catalog +entries should pair exact specs with `expectedIntegrity` so update flows fail +closed if the fetched npm artifact no longer matches the pinned release. +Interactive onboarding still offers trusted registry npm specs, including bare +package names and dist-tags, for compatibility. Catalog diagnostics can +distinguish exact, floating, integrity-pinned, and missing-integrity sources. When `expectedIntegrity` is present, install/update flows enforce it; when it is omitted, the registry resolution is recorded without an integrity pin. diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index fbbb88728..7c99488a9 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -94,6 +94,7 @@ methods: | `api.registerHook(events, handler, opts?)` | Event hook | | `api.registerHttpRoute(params)` | Gateway HTTP endpoint | | `api.registerGatewayMethod(name, handler)` | Gateway RPC method | +| `api.registerGatewayDiscoveryService(service)` | Local Gateway discovery advertiser | | `api.registerCli(registrar, opts?)` | CLI subcommand | | `api.registerService(service)` | Background service | | `api.registerInteractiveHandler(registration)` | Interactive handler | @@ -119,6 +120,32 @@ and they must declare `contracts.embeddedExtensionFactories: ["pi"]` in does not require that lower-level seam. +### Gateway discovery registration + +`api.registerGatewayDiscoveryService(...)` lets a plugin advertise the active +Gateway on a local discovery transport such as mDNS/Bonjour. OpenClaw calls the +service during Gateway startup when local discovery is enabled, passes the +current Gateway ports and non-secret TXT hint data, and calls the returned +`stop` handler during Gateway shutdown. + +```typescript +api.registerGatewayDiscoveryService({ + id: "my-discovery", + async advertise(ctx) { + const handle = await startMyAdvertiser({ + gatewayPort: ctx.gatewayPort, + tls: ctx.gatewayTlsEnabled, + displayName: ctx.machineDisplayName, + }); + return { stop: () => handle.stop() }; + }, +}); +``` + +Gateway discovery plugins must not treat advertised TXT values as secrets or +authentication. Discovery is a routing hint; Gateway auth and TLS pinning still +own trust. + ### CLI registration metadata `api.registerCli(registrar, opts?)` accepts two kinds of top-level metadata: