chore(sync): mirror docs from openclaw/openclaw@cb4fc58547
This commit is contained in:
openclaw-docs-sync[bot]
parent
4dd9963129
commit
1aaca6eac2
@ -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"
|
||||
}
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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=<sha256>` (only when TLS is enabled and fingerprint is available)
|
||||
- `canvasPort=<port>` (only when the canvas host is enabled; currently the same as `gatewayPort`)
|
||||
- `transport=gateway`
|
||||
- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
|
||||
- `tailnetDns=<magicdns>` (mDNS full mode only, optional hint when Tailnet is available)
|
||||
- `sshPort=<port>` (mDNS full mode only; wide-area DNS-SD may omit it)
|
||||
- `cliPath=<path>` (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
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
</Accordion>
|
||||
|
||||
### 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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user