diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ae595a9c644..a8811f5c45f1 100644 --- 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. diff --git a/README.md b/README.md index ff3c910adc63..1a2ca1609e52 100644 --- 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" diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md index 1a7f1c846e9a..b0fac1049c68 100644 --- 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 \ + --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. diff --git a/docs/automation/taskflow.md b/docs/automation/taskflow.md index 76e75376adf2..882f04ff00f7 100644 --- 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 diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index 01edf03dc851..f9786fde9879 100644 --- 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) diff --git a/docs/channels/whatsapp.md b/docs/channels/whatsapp.md index d5e32b1e0586..35de4d6f4d45 100644 --- 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 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.) + +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. + + ## Deployment patterns @@ -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/ \ + ~/.openclaw/credentials/whatsapp/.bak + openclaw channels logout --channel whatsapp --account + openclaw channels login --channel whatsapp --account ``` If `~/.openclaw/logs/whatsapp-health.log` says `Gateway inactive` but diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index cc8a0868ed0f..716173c1749a 100644 --- 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. + + +A successful minimal `curl` does not guarantee that real SDK-style requests will +pass through the same upstream security layer. + + +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: diff --git a/docs/tools/creating-skills.md b/docs/tools/creating-skills.md index d23b1caff023..41cd53e62783 100644 --- 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..env` and + `skills.entries..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 diff --git a/src/gateway/server-plugins.test.ts b/src/gateway/server-plugins.test.ts index 70cfb669f86d..3a9c903cf5fe 100644 --- 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..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..subagent.allowModelOverride', ); }); diff --git a/src/gateway/server-plugins.ts b/src/gateway/server-plugins.ts index 7bbe3f7208a2..757233d1bf89 100644 --- 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..subagent.allowModelOverride", }; }