From b3622beecb11291b539ab4161ed88bfd064c4a81 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 22 May 2026 23:28:31 +0100 Subject: [PATCH] docs: absorb contributor documentation fixes Co-authored-by: ayesha-aziz123 Co-authored-by: dishraters Co-authored-by: hougangdev Co-authored-by: Brandon Lipman --- CHANGELOG.md | 1 + docs/gateway/config-agents.md | 1 + docs/gateway/troubleshooting.md | 15 +++++++++++++++ docs/help/environment.md | 1 + docs/start/onboarding.md | 5 ++++- skills/peekaboo/SKILL.md | 8 ++++++++ 6 files changed, 30 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7f1048d99f3..4d94c6beeca9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai ### Changes +- Docs: clarify context-pruning ratio bounds, local dashboard recovery, CLI env markers, remote onboarding token behavior, and Peekaboo Bridge permissions for subprocess agents. Thanks @ayesha-aziz123, @dishraters, @hougangdev, and @brandonlipman. - Docs: clarify browser CDP diagnostics, Plugin SDK allowlist imports, status-reaction timing defaults, queue steering behavior, limited-tool troubleshooting, cron HEARTBEAT handling, Telegram multi-agent groups, Bitwarden SecretRef setup, and EasyRunner deployments. Thanks @Quratulain-bilal, @mbelinky, @Mickey-, @vancece, @xenouzik, @posigit, @surlymochan, @janaka, and @choiking. - Docs: clarify IPv4-only Gateway BYOH binding, trusted-proxy scope clearing, Android pairing approval, macOS Accessibility grants, Zalo profile env vars, password-store SecretRef setup, and Chinese memory navigation. Thanks @itskai-dev, @gwh7078, @longstoryscott, @MoeJaberr, and @yuaiccc. - Docs: consolidate GLM under Z.AI, add the Upstash Box install guide and Gateway exposure runbook, clarify MEDIA directives, Copilot and Voyage setup, config path quoting, real behavior proof, and memory-file write guidance. Thanks @BobDu, @alitariksahin, @Jefsky, @musaabhasan, @OmerZeyveli, @leno23, @WuKongAI-CMU, @luoyanglang, and @majin1102. diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md index 601edaa026d5..7eca7de5eb38 100644 --- a/docs/gateway/config-agents.md +++ b/docs/gateway/config-agents.md @@ -723,6 +723,7 @@ Prunes **old tool results** from in-memory context before sending to the LLM. Do - `mode: "cache-ttl"` enables pruning passes. - `ttl` controls how often pruning can run again (after the last cache touch). - Pruning soft-trims oversized tool results first, then hard-clears older tool results if needed. +- `softTrimRatio` and `hardClearRatio` accept values from `0.0` through `1.0`; config validation rejects values outside that range. **Soft-trim** keeps beginning + end and inserts `...` in the middle. diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index ea032aef6155..cc8a0868ed0f 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -294,6 +294,21 @@ Look for: - Auth mode/token mismatch between client and gateway. - HTTP usage where device identity is required. +If a local browser cannot connect to `127.0.0.1:18789` after an update, first +recover the local Gateway service and confirm it is serving the dashboard: + +```bash +openclaw gateway restart +lsof -i :18789 +curl http://127.0.0.1:18789 +``` + +If `curl` returns OpenClaw HTML, the Gateway is working and the remaining issue +is likely browser cache, an old deep link, or stale tab state. Open +`http://127.0.0.1:18789` directly and navigate from the dashboard. If restart +does not leave the service running, run `openclaw gateway start` and recheck +`openclaw gateway status`. + - `device identity required` → non-secure context or missing device auth. diff --git a/docs/help/environment.md b/docs/help/environment.md index 72e2360c8b05..913d669ff775 100644 --- a/docs/help/environment.md +++ b/docs/help/environment.md @@ -96,6 +96,7 @@ OpenClaw also injects context markers into spawned child processes: - `OPENCLAW_SHELL=acp`: set for ACP runtime backend process spawns (for example `acpx`). - `OPENCLAW_SHELL=acp-client`: set for `openclaw acp client` when it spawns the ACP bridge process. - `OPENCLAW_SHELL=tui-local`: set for local TUI `!` shell commands. +- `OPENCLAW_CLI=1`: set for child processes spawned by the CLI entry point. These are runtime markers (not required user config). They can be used in shell/profile logic to apply context-specific rules. diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md index c60a85737b62..e32e5f2c5a30 100644 --- a/docs/start/onboarding.md +++ b/docs/start/onboarding.md @@ -46,7 +46,10 @@ Where does the **Gateway** run? - **This Mac (Local only):** onboarding can configure auth and write credentials locally. - **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth; - credentials must exist on the gateway host. + credentials must exist on the gateway host. The remote gateway token field + stores the token used by the macOS app to connect to that Gateway; existing + non-plaintext `gateway.remote.token` values are preserved until you replace + them. - **Configure later:** skip setup and leave the app unconfigured. diff --git a/skills/peekaboo/SKILL.md b/skills/peekaboo/SKILL.md index c5a6a49e1a45..d751349372ec 100644 --- a/skills/peekaboo/SKILL.md +++ b/skills/peekaboo/SKILL.md @@ -187,4 +187,12 @@ peekaboo type "Line 1\nLine 2" --delay 10 Notes - Requires Screen Recording + Accessibility permissions. +- In OpenClaw subprocesses, use the default Bridge path. Do not pass + `--no-remote` unless the calling process has its own Screen Recording grant. +- Diagnose subprocess capture failures with `peekaboo bridge status --json`, + then `peekaboo permissions status --json`, then a normal Bridge-routed + capture such as `peekaboo image --mode screen --json`. +- On macOS 15+, the "bypass private window picker" prompt is separate from the + base Screen Recording grant; it can appear even when Bridge permissions are + otherwise correct. - Use `peekaboo see --annotate` to identify targets before clicking.