LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/bonjour.md
View on GitHub# Bonjour / mDNS Discovery Reference
> Source: https://docs.openclaw.ai/gateway/bonjour
## Overview
OpenClaw uses Bonjour (mDNS/DNS-SD) to let companion apps (macOS, iOS, Android) discover the Gateway on the LAN automatically. The Gateway advertises a `_openclaw-gw._tcp` service.
## Service Types
| Service | Purpose |
|---|---|
| `_openclaw-gw._tcp` | Gateway transport beacon (used by macOS/iOS/Android nodes) |
## TXT Keys (Non-Secret Hints)
| Key | Value | Notes |
|---|---|---|
| `role` | `gateway` | Always |
| `displayName` | `<friendly name>` | Human-readable |
| `lanHost` | `<hostname>.local` | LAN hostname |
| `gatewayPort` | `<port>` | Gateway WS + HTTP port |
| `gatewayTls` | `1` | Only when TLS enabled |
| `gatewayTlsSha256` | `<sha256>` | Only when TLS + fingerprint available |
| `canvasPort` | `<port>` | Currently same as gatewayPort |
| `sshPort` | `<port>` | Default 22 |
| `transport` | `gateway` | Always |
| `cliPath` | `<path>` | Optional: abs path to openclaw |
| `tailnetDns` | `<magicdns>` | Optional: when Tailnet available |
### Security Notes
- TXT records are **unauthenticated**. Clients must not treat TXT as authoritative routing.
- Route using resolved SRV + A/AAAA records. Treat `lanHost`, `tailnetDns`, `gatewayPort`, `gatewayTlsSha256` as **hints only**.
- TLS pinning must never allow advertised `gatewayTlsSha256` to override a previously stored pin.
- iOS/Android nodes should treat discovery-based connects as TLS-only with user confirmation for first-time fingerprints.
## Wide-Area Bonjour (Unicast DNS-SD over Tailscale)
For cross-network discovery (beyond LAN):
1. Run a DNS server on the gateway host (reachable over Tailnet).
2. Publish DNS-SD records under a dedicated zone (e.g., `openclaw.internal.`).
3. Configure Tailscale split DNS to resolve via that DNS server.
### Gateway Config (Recommended)
```json5
{
gateway: {
bonjour: {
domain: "openclaw.internal.", // zone for wide-area DNS-SD
},
},
}
```
## Debugging
### On macOS
```bash
# Browse instances
dns-sd -B _openclaw-gw._tcp local.
# Resolve one instance
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```
### In Gateway Logs
Filter log file for `bonjour:`:
- `bonjour: advertise failed ...`
- `bonjour: ... name conflict resolved`
- `bonjour: watchdog detected non-announced service ...`
### On iOS Node
- Settings → Gateway → Advanced → Discovery Debug Logs
- Settings → Gateway → Advanced → Discovery Logs → reproduce → Copy
## Common Failure Modes
| Problem | Cause | Fix |
|---|---|---|
| Bonjour doesn't work across networks | mDNS is LAN-only | Use Tailnet or SSH |
| Multicast blocked | Some Wi-Fi networks disable mDNS | Switch network or use SSH |
| Sleep / interface churn | macOS may temporarily drop mDNS results | Retry or restart Gateway |
| Browse works but resolve fails | Complex machine names (emojis/punctuation) | Simplify hostname, restart Gateway |
| Escaped `\032` in names | Normal RFC encoding for spaces | UIs decode (iOS: `BonjourEscapes.decode`) |
## Disabling / Configuration
```json5
{
gateway: {
bonjour: {
enabled: false, // disable entirely
},
},
}
```
## See Also
- [presence_discovery.md](presence_discovery.md) — Overview of presence + discovery
- [remote_access.md](remote_access.md) — SSH, Tailscale remote access
- [gateway_internals.md](gateway_internals.md) — Network model
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |