docs: absorb small documentation PRs

2026-06-06 05:51:15 +08:00 · 2026-05-22 23:42:45 +01:00
parent 13a4c57991
commit 658be7f1c7
10 changed files with 115 additions and 4 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai

 ### Changes

+- Docs: clarify README onboarding and Gateway startup paths, WhatsApp QR/408 recovery, cron output language prompts, skill advanced features, gateway upstream 403 troubleshooting, and plugin fallback override guidance. Thanks @deepujain, @Zacxxx, @Jah-yee, @neyric, @usimic, @Renu-Cybe, @BigUncle, and @SeashoreShi.
 - 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.
--- a/README.md
+++ b/README.md
@@ -92,7 +92,7 @@ Works with npm, pnpm, or bun.

 - **[OpenAI](https://openai.com/)** (ChatGPT/Codex)

-Model note: while many providers and models are supported, prefer a current flagship model from the provider you trust and already use. See [Onboarding](https://docs.openclaw.ai/start/onboarding).
+Model note: while many providers and models are supported, prefer a current flagship model from the provider you trust and already use. See [Onboarding](https://docs.openclaw.ai/start/wizard).

 ## Install (recommended)

@@ -113,11 +113,23 @@ Runtime: **Node 24 (recommended) or Node 22.19+**.

 Full beginner guide (auth, pairing, channels): [Getting started](https://docs.openclaw.ai/start/getting-started)

+Recommended daemon mode:
+
 ```bash
 openclaw onboard --install-daemon
+openclaw gateway status
+```

+Foreground/debug mode:
+
+```bash
+openclaw gateway stop
 openclaw gateway --port 18789 --verbose
+```

+Send a test message or ask the assistant after either startup mode is running:
+
+```bash
 # Send a message
 openclaw message send --target +1234567890 --message "Hello from OpenClaw"

--- a/docs/automation/cron-jobs.md
+++ b/docs/automation/cron-jobs.md
@@ -177,6 +177,21 @@ When an agent creates an isolated reminder from an active chat, OpenClaw stores

 Implicit announce delivery uses configured channel allowlists to validate and reroute stale targets. DM pairing-store approvals are not fallback automation recipients; set `delivery.to` or configure the channel `allowFrom` entry when a scheduled job should proactively send to a DM.

+## Output language
+
+Cron jobs do not infer a reply language from channel, locale, or previous
+messages. Put the language rule in the scheduled message or template:
+
+```bash
+openclaw cron edit <jobId> \
+  --message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."
+```
+
+For template files, keep the language instruction in the rendered prompt and
+verify placeholders such as `{{language}}` are filled before the job runs. If
+the output mixes languages, make the rule explicit, for example: "Use Chinese
+for narrative text and keep technical terms in English."
+
 Failure notifications follow a separate destination path:

 - `cron.failureDestination` sets a global default for failure notifications.
--- a/docs/automation/taskflow.md
+++ b/docs/automation/taskflow.md
@@ -1,5 +1,5 @@
 ---
-summary: "Task Flow flow orchestration layer above background tasks"
+summary: "Task Flow orchestration layer above background tasks"
 read_when:
  - You want to understand how Task Flow relates to background tasks
  - You encounter Task Flow or openclaw tasks flow in release notes or docs
--- a/docs/channels/troubleshooting.md
+++ b/docs/channels/troubleshooting.md
@@ -56,6 +56,7 @@ clean state.
 | Group messages ignored              | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group.                                                                          |
 | QR login times out with 408         | Check gateway `HTTPS_PROXY` / `HTTP_PROXY` env      | Set a reachable proxy; use `NO_PROXY` only for bypasses.                                                                         |
 | Random disconnect/relogin loops     | `openclaw channels status --probe` + logs           | Recent reconnects are flagged even when currently connected; watch logs, restart the gateway, then relink if flapping continues. |
+| `status=408 Request Time-out` loop  | Probe, logs, doctor, then gateway status            | Fix host connectivity/timing first; back up auth and re-link the account if the loop persists.                                   |
 | Replies arrive seconds/minutes late | `openclaw doctor --fix`                             | Doctor stops verified stale local TUI clients when they are degrading the Gateway event loop.                                    |

 Full troubleshooting: [WhatsApp troubleshooting](/channels/whatsapp#troubleshooting)
--- a/docs/channels/whatsapp.md
+++ b/docs/channels/whatsapp.md
@@ -66,6 +66,10 @@ fallback. Pin an exact version only when you need a reproducible install.
 openclaw channels login --channel whatsapp
 ```

+    Current login is QR-based. In remote or headless environments, make sure you
+    have a reliable path to deliver the live QR code to the phone that will scan
+    it before starting login.
+
    For a specific account:

 ```bash
@@ -105,6 +109,13 @@ openclaw pairing approve whatsapp <CODE>
 OpenClaw recommends running WhatsApp on a separate number when possible. (The channel metadata and setup flow are optimized for that setup, but personal-number setups are also supported.)
 </Note>

+<Warning>
+The current WhatsApp setup flow is QR-only. Terminal-rendered QRs, screenshots,
+PDFs, or chat attachments can expire or become unreadable while being relayed
+from a remote machine. For remote/headless hosts, prefer a direct QR image
+handoff path over manual terminal capture.
+</Warning>
+
 ## Deployment patterns

 <AccordionGroup>
@@ -586,8 +597,20 @@ Behavior notes:
    Fix:

    ```bash
+    openclaw channels status --probe
    openclaw doctor
    openclaw logs --follow
+    openclaw gateway status
+    ```
+
+    If the loop persists after host connectivity and timing are fixed, back up
+    the account auth directory and re-link that account:
+
+    ```bash
+    cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
+      ~/.openclaw/credentials/whatsapp/<accountId>.bak
+    openclaw channels logout --channel whatsapp --account <accountId>
+    openclaw channels login --channel whatsapp --account <accountId>
    ```

    If `~/.openclaw/logs/whatsapp-health.log` says `Gateway inactive` but
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -195,6 +195,43 @@ Related:
 - [Token use and costs](/reference/token-use)
 - [Why am I seeing HTTP 429 from Anthropic?](/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)

+## Upstream 403 blocked responses
+
+Use this when an upstream LLM provider returns a generic `403` such as
+`Your request was blocked`.
+
+Do not assume this is always an OpenClaw configuration issue. The response can
+come from an upstream security layer such as a CDN, WAF, bot-management rule, or
+reverse proxy in front of an OpenAI-compatible endpoint.
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+```
+
+Look for:
+
+- multiple models under the same provider failing in the same way
+- HTML or generic security text instead of a normal provider API error
+- provider-side security events for the same request time
+- a tiny direct `curl` probe succeeding while normal SDK-shaped requests fail
+
+Fix the provider-side filtering first when the evidence points to a WAF/CDN
+block. Prefer a narrowly scoped allow or skip rule for the API path OpenClaw
+uses, and avoid disabling protection for the whole site.
+
+<Warning>
+A successful minimal `curl` does not guarantee that real SDK-style requests will
+pass through the same upstream security layer.
+</Warning>
+
+Related:
+
+- [OpenAI-compatible endpoints](/gateway/configuration-reference#openai-compatible-endpoints)
+- [Provider configuration](/providers)
+- [Logs](/reference/logs)
+
 ## Local OpenAI-compatible backend passes direct probes but agent runs fail

 Use this when:
--- a/docs/tools/creating-skills.md
+++ b/docs/tools/creating-skills.md
@@ -94,6 +94,28 @@ The YAML frontmatter supports these fields:
 | `metadata.openclaw.requires.bins`   | No       | Required binaries on PATH                                      |
 | `metadata.openclaw.requires.config` | No       | Required config keys                                           |

+## Advanced features
+
+Once a basic skill works, these fields help make it reliable and portable:
+
+- **Conditional activation** — use `requires.bins`, `requires.env`, or
+  `requires.config` to load the skill only when required dependencies are
+  available. See [Skills reference: gating](/tools/skills#gating).
+- **Environment and API-key wiring** — use `skills.entries.<name>.env` and
+  `skills.entries.<name>.apiKey` to inject host-side environment for a skill
+  turn. See [Skills reference: config wiring](/tools/skills#config-wiring).
+- **Invocation control** — set `user-invocable: false` to hide a slash command,
+  or `disable-model-invocation: true` to keep a command-style skill out of the
+  model prompt. See [Skills reference: frontmatter](/tools/skills#frontmatter).
+- **Direct command dispatch** — use `command-dispatch: tool` with
+  `command-tool` when a slash command should call a tool directly instead of
+  routing through the model.
+- **Portable paths** — use `{baseDir}` in `SKILL.md` when referencing scripts
+  or assets inside the skill directory.
+- **Publishing** — use the ClawHub skill when preparing a skill for publication.
+  It documents the current `clawhub publish` command shape and required
+  metadata.
+
 ## Best practices

 - **Be concise** — instruct the model on _what_ to do, not how to be an AI
--- a/src/gateway/server-plugins.test.ts
+++ b/src/gateway/server-plugins.test.ts
@@ -968,7 +968,7 @@ describe("loadGatewayPlugins", () => {
        }),
      ),
    ).rejects.toThrow(
-      'plugin "voice-call" is not trusted for fallback provider/model override requests. See https://docs.openclaw.ai/gateway/configuration-reference#plugins and search for: plugins.entries.<id>.subagent.allowModelOverride',
+      'plugin "voice-call" is not trusted for fallback provider/model override requests. See https://docs.openclaw.ai/plugins/sdk-runtime#api-runtime-subagent and search for: plugins.entries.<id>.subagent.allowModelOverride',
    );
  });

--- a/src/gateway/server-plugins.ts
+++ b/src/gateway/server-plugins.ts
@@ -188,7 +188,7 @@ function authorizeFallbackModelOverride(params: {
      allowed: false,
      reason:
        `plugin "${pluginId}" is not trusted for fallback provider/model override requests. ` +
-        "See https://docs.openclaw.ai/gateway/configuration-reference#plugins and search for: " +
+        "See https://docs.openclaw.ai/plugins/sdk-runtime#api-runtime-subagent and search for: " +
        "plugins.entries.<id>.subagent.allowModelOverride",
    };
  }