diff --git a/docs/automation/index.md b/docs/automation/index.md index 613e951836a..abee5f81155 100644 --- a/docs/automation/index.md +++ b/docs/automation/index.md @@ -4,7 +4,7 @@ read_when: - Deciding how to automate work with OpenClaw - Choosing between heartbeat, cron, commitments, hooks, and standing orders - Looking for the right automation entry point -title: "Automation & tasks" +title: "Automation and tasks" --- OpenClaw runs work in the background through tasks, scheduled jobs, inferred diff --git a/docs/concepts/agent-loop.md b/docs/concepts/agent-loop.md index 1917012aa91..757b9d3d865 100644 --- a/docs/concepts/agent-loop.md +++ b/docs/concepts/agent-loop.md @@ -6,8 +6,8 @@ read_when: title: "Agent loop" --- -An agentic loop is the full “real” run of an agent: intake → context assembly → model inference → -tool execution → streaming replies → persistence. It’s the authoritative path that turns a message +An agentic loop is the full "real" run of an agent: intake → context assembly → model inference → +tool execution → streaming replies → persistence. It's the authoritative path that turns a message into actions and a final reply, while keeping session state consistent. In OpenClaw, a loop is a single, serialized run per session that emits lifecycle and stream events @@ -67,7 +67,7 @@ wired end-to-end. ## Prompt assembly + system prompt -- System prompt is built from OpenClaw’s base prompt, skills prompt, bootstrap context, and per-run overrides. +- System prompt is built from OpenClaw's base prompt, skills prompt, bootstrap context, and per-run overrides. - Model-specific limits and compaction reserve tokens are enforced. - See [System prompt](/concepts/system-prompt) for what the model sees. diff --git a/docs/gateway/discovery.md b/docs/gateway/discovery.md index f64501468d6..d2aed9327a3 100644 --- a/docs/gateway/discovery.md +++ b/docs/gateway/discovery.md @@ -7,8 +7,6 @@ read_when: title: "Discovery and transports" --- -# Discovery & transports - OpenClaw has two distinct problems that look similar on the surface: 1. **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere. @@ -31,7 +29,7 @@ Protocol details: - [Gateway protocol](/gateway/protocol) - [Bridge protocol (legacy)](/gateway/bridge-protocol) -## Why we keep both "direct" and SSH +## Why we keep both direct and SSH - **Direct WS** is the best UX on the same network and within a tailnet: - auto-discovery on LAN via Bonjour @@ -57,7 +55,7 @@ Target direction: - The **gateway** advertises its WS endpoint via Bonjour when the bundled `bonjour` plugin is enabled. The plugin auto-starts on macOS hosts and is opt-in elsewhere. -- Clients browse and show a “pick a gateway” list, then store the chosen endpoint. +- Clients browse and show a "pick a gateway" list, then store the chosen endpoint. Troubleshooting and beacon details: [Bonjour](/gateway/bonjour). @@ -83,7 +81,7 @@ Security notes: - Bonjour/mDNS TXT records are **unauthenticated**. Clients must treat TXT values as UX hints only. - Routing (host/port) should prefer the **resolved service endpoint** (SRV + A/AAAA) over TXT-provided `lanHost`, `tailnetDns`, or `gatewayPort`. - TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin. -- iOS/Android nodes should require an explicit “trust this fingerprint” confirmation before storing a first-time pin (out-of-band verification) whenever the chosen route is secure/TLS-based. +- iOS/Android nodes should require an explicit "trust this fingerprint" confirmation before storing a first-time pin (out-of-band verification) whenever the chosen route is secure/TLS-based. Enable/disable/override: @@ -102,7 +100,7 @@ Enable/disable/override: ### 2) Tailnet (cross-network) -For London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is: +For London/Vienna style setups, Bonjour won't help. The recommended "direct" target is: - Tailscale MagicDNS name (preferred) or a stable tailnet IP. @@ -128,7 +126,7 @@ See [Remote access](/gateway/remote). Recommended client behavior: 1. If a paired direct endpoint is configured and reachable, use it. -2. Else, if discovery finds a gateway on `local.` or the configured wide-area domain, offer a one-tap “Use this gateway” choice and save it as the direct endpoint. +2. Else, if discovery finds a gateway on `local.` or the configured wide-area domain, offer a one-tap "Use this gateway" choice and save it as the direct endpoint. 3. Else, if a tailnet DNS/IP is configured, try direct. For mobile nodes on tailnet/public routes, direct means a secure endpoint, not plaintext remote `ws://`. 4. Else, fall back to SSH. diff --git a/docs/gateway/remote.md b/docs/gateway/remote.md index f58e7cdc49c..a5edc21c8fa 100644 --- a/docs/gateway/remote.md +++ b/docs/gateway/remote.md @@ -5,7 +5,7 @@ read_when: title: "Remote access" --- -This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it. +This repo supports "remote over SSH" by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it. - For **operators (you / the macOS app)**: SSH tunneling is the universal fallback. - For **nodes (iOS/Android and future devices)**: connect to the Gateway **WebSocket** (LAN/tailnet or SSH tunnel as needed). @@ -61,7 +61,7 @@ Flow example (Telegram → node): Notes: - **Nodes do not run the gateway service.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). -- macOS app “node mode” is just a node client over the Gateway WebSocket. +- macOS app "node mode" is just a node client over the Gateway WebSocket. ## SSH tunnel (CLI + tools) @@ -101,7 +101,7 @@ You can persist a remote target so CLI commands use it by default: ``` When the gateway is loopback-only, keep the URL at `ws://127.0.0.1:18789` and open the SSH tunnel first. -In the macOS app’s SSH tunnel transport, discovered gateway hostnames belong in +In the macOS app's SSH tunnel transport, discovered gateway hostnames belong in `gateway.remote.sshTarget`; `gateway.remote.url` remains the local tunnel URL. ## Credential precedence @@ -127,7 +127,7 @@ Gateway credential resolution follows one shared contract across call/probe/stat WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket. - Forward `18789` over SSH (see above), then connect clients to `ws://127.0.0.1:18789`. -- On macOS, prefer the app’s “Remote over SSH” mode, which manages the tunnel automatically. +- On macOS, prefer the app's "Remote over SSH" mode, which manages the tunnel automatically. ## macOS app Remote over SSH @@ -137,7 +137,7 @@ Runbook: [macOS remote access](/platforms/mac/remote). ## Security rules (remote/VPN) -Short version: **keep the Gateway loopback-only** unless you’re sure you need a bind. +Short version: **keep the Gateway loopback-only** unless you're sure you need a bind. - **Loopback + SSH/Tailscale Serve** is the safest default (no public exposure). - Plaintext `ws://` is loopback-only by default. For trusted private networks, diff --git a/docs/platforms/mac/child-process.md b/docs/platforms/mac/child-process.md index dcda292c7c7..41693e9fd70 100644 --- a/docs/platforms/mac/child-process.md +++ b/docs/platforms/mac/child-process.md @@ -2,23 +2,21 @@ summary: "Gateway lifecycle on macOS (launchd)" read_when: - Integrating the mac app with the gateway lifecycle -title: "Gateway lifecycle" +title: "Gateway lifecycle on macOS" --- -# Gateway lifecycle on macOS - The macOS app **manages the Gateway via launchd** by default and does not spawn -the Gateway as a child process. It first tries to attach to an already‑running +the Gateway as a child process. It first tries to attach to an already-running Gateway on the configured port; if none is reachable, it enables the launchd service via the external `openclaw` CLI (no embedded runtime). This gives you -reliable auto‑start at login and restart on crashes. +reliable auto-start at login and restart on crashes. -Child‑process mode (Gateway spawned directly by the app) is **not in use** today. +Child-process mode (Gateway spawned directly by the app) is **not in use** today. If you need tighter coupling to the UI, run the Gateway manually in a terminal. ## Default behavior (launchd) -- The app installs a per‑user LaunchAgent labeled `ai.openclaw.gateway` +- The app installs a per-user LaunchAgent labeled `ai.openclaw.gateway` (or `ai.openclaw.` when using `--profile`/`OPENCLAW_PROFILE`; legacy `com.openclaw.*` is supported). - When Local mode is enabled, the app ensures the LaunchAgent is loaded and starts the Gateway if needed. @@ -35,7 +33,7 @@ Replace the label with `ai.openclaw.` when running a named profile. ## Unsigned dev builds -`scripts/restart-mac.sh --no-sign` is for fast local builds when you don’t have +`scripts/restart-mac.sh --no-sign` is for fast local builds when you don't have signing keys. To prevent launchd from pointing at an unsigned relay binary, it: - Writes `~/.openclaw/disable-launchagent`. @@ -61,12 +59,12 @@ remote host and connects over that tunnel. ## Why we prefer launchd -- Auto‑start at login. -- Built‑in restart/KeepAlive semantics. +- Auto-start at login. +- Built-in restart/KeepAlive semantics. - Predictable logs and supervision. -If a true child‑process mode is ever needed again, it should be documented as a -separate, explicit dev‑only mode. +If a true child-process mode is ever needed again, it should be documented as a +separate, explicit dev-only mode. ## Related