From 7dbc3a200dd43fdb46dee9f455377df2d36d5c86 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sat, 2 May 2026 04:46:15 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@f2370b769c6a22e58228eef1ab11d9544cfd4989 --- .openclaw-sync/source.json | 4 ++-- .../.generated/plugin-sdk-api-baseline.sha256 | 4 ++-- docs/automation/cron-jobs.md | 2 ++ docs/channels/channel-routing.md | 6 +++++ docs/channels/slack.md | 1 + docs/channels/synology-chat.md | 1 + docs/channels/telegram.md | 2 +- docs/ci.md | 14 +++++++++++ docs/cli/cron.md | 2 ++ docs/providers/google.md | 15 +++++++----- docs/providers/minimax.md | 12 +++++----- docs/reference/RELEASING.md | 20 ++++++++++++++-- docs/tools/gemini-search.md | 23 +++++++++++------- docs/tools/minimax-search.md | 24 +++++++++++-------- docs/tools/web.md | 14 ++++++----- 15 files changed, 101 insertions(+), 43 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index eab3b2c85..005f0ec8e 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "20333bd58dc9b8d607c2c5a6b80c2fe5bb4c7c33", - "syncedAt": "2026-05-02T04:01:49.585Z" + "sha": "f2370b769c6a22e58228eef1ab11d9544cfd4989", + "syncedAt": "2026-05-02T04:44:26.495Z" } diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256 index c4fc063ec..bbdc6b3a7 100644 --- a/docs/.generated/plugin-sdk-api-baseline.sha256 +++ b/docs/.generated/plugin-sdk-api-baseline.sha256 @@ -1,2 +1,2 @@ -0f9284c6349bf03d3d89c1d25031031840dae4ade032622ca212240ed19829f6 plugin-sdk-api-baseline.json -33706cf425386717973cc87357ae5e0df432dd5a519b4faea8b38e21d7daae78 plugin-sdk-api-baseline.jsonl +1fbd0ea7f65901d96653458ba414f9ac69dc0142ff3772e48d63de8b9fa5567f plugin-sdk-api-baseline.json +2d29f4e632b05bd365f414096c87a2a3d9718f13fdbf9538824cb32db2902436 plugin-sdk-api-baseline.jsonl diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md index eb1b4650c..9956325a8 100644 --- a/docs/automation/cron-jobs.md +++ b/docs/automation/cron-jobs.md @@ -158,6 +158,8 @@ Before an isolated cron run enters the agent runner, OpenClaw checks reachable l Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`; direct RPC/config callers may also pass `delivery.threadId` as a string or number. Slack/Discord/Mattermost targets should use explicit prefixes (`channel:`, `user:`). Matrix room IDs are case-sensitive; use the exact room ID or `room:!room:server` form from Matrix. +When announce delivery uses `channel: "last"` or omits `channel`, a provider-prefixed target such as `telegram:123` can select the channel before cron falls back to session history or a single configured channel. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the target prefix must name the same provider; for example, `channel: "whatsapp"` with `to: "telegram:123"` is rejected instead of letting WhatsApp interpret the Telegram ID as a phone number. Target-kind and service prefixes such as `channel:`, `user:`, `imessage:`, and `sms:` remain channel-owned target syntax, not provider selectors. + For isolated jobs, chat delivery is shared. If a chat route is available, the agent can use the `message` tool even when the job uses `--no-deliver`. If the agent sends to the configured/current target, OpenClaw skips the fallback announce. Otherwise `announce`, `webhook`, and `none` only control what the runner does with the final reply after the agent turn. When an agent creates an isolated reminder from an active chat, OpenClaw stores the preserved live delivery target for the fallback announce route. Internal session keys may be lowercase; provider delivery targets are not reconstructed from those keys when current chat context is available. diff --git a/docs/channels/channel-routing.md b/docs/channels/channel-routing.md index c74944b46..b7beff35c 100644 --- a/docs/channels/channel-routing.md +++ b/docs/channels/channel-routing.md @@ -21,6 +21,12 @@ host configuration. - **AgentId**: an isolated workspace + session store (“brain”). - **SessionKey**: the bucket key used to store context and control concurrency. +## Outbound target prefixes + +Explicit outbound targets may include a provider prefix, such as `telegram:123` or `tg:123`. Core treats that prefix as a channel-selection hint only when the selected channel is `last` or otherwise unresolved, and only when the loaded plugin advertises that prefix. If the caller already selected an explicit channel, the provider prefix must match that channel; cross-channel combinations such as WhatsApp delivery to `telegram:123` fail before plugin-specific target normalization. + +Target-kind and service prefixes such as `channel:`, `user:`, `room:`, `thread:`, `imessage:`, and `sms:` stay inside the selected channel's grammar. They do not select the provider by themselves. + ## Session key shapes (examples) Direct messages collapse to the agent’s **main** session by default: diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 9ff573f4c..065000265 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -596,6 +596,7 @@ Current Slack message actions include `send`, `upload-file`, `download-file`, `r ## Threading, sessions, and reply tags - DMs route as `direct`; channels as `channel`; MPIMs as `group`. +- Slack route bindings accept raw peer IDs plus Slack target forms such as `channel:C12345678`, `user:U12345678`, and `<@U12345678>`. - With default `session.dmScope=main`, Slack DMs collapse to agent main session. - Channel sessions: `agent::slack:channel:`. - Thread replies can create thread session suffixes (`:thread:`) when applicable. diff --git a/docs/channels/synology-chat.md b/docs/channels/synology-chat.md index 963fd8b90..9dabd066d 100644 --- a/docs/channels/synology-chat.md +++ b/docs/channels/synology-chat.md @@ -110,6 +110,7 @@ Examples: ```bash openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw" openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again" +openclaw message send --channel synology-chat --target synology:123456 --text "Short prefix" ``` Media sends are supported by URL-based file delivery. diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index da7043fc7..599aa25ec 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -878,7 +878,7 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ defaults to `autoSelectFamily=true` (except WSL2) and `dnsResultOrder=ipv4first`. + - Node 22+ defaults to `autoSelectFamily=true` (except WSL2). Telegram DNS result order honors `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, then `channels.telegram.network.dnsResultOrder`, then the process default such as `NODE_OPTIONS=--dns-result-order=ipv4first`; if none applies, Node 22+ falls back to `ipv4first`. - If your host is WSL2 or explicitly works better with IPv4-only behavior, force family selection: ```yaml diff --git a/docs/ci.md b/docs/ci.md index ac048ea18..78562743c 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -134,6 +134,20 @@ See [Full release validation](/reference/full-release-validation) for the stage matrix, exact workflow job names, profile differences, artifacts, and focused rerun handles. +For pinned commit proof on a fast-moving branch, use the helper instead of +`gh workflow run ... --ref main -f ref=`: + +```bash +pnpm ci:full-release --sha +``` + +GitHub workflow dispatch refs must be branches or tags, not raw commit SHAs. The +helper pushes a temporary `release-ci/-...` branch at the target SHA, +dispatches `Full Release Validation` from that pinned ref, verifies every child +workflow `headSha` matches the target, and deletes the temporary branch when the +run completes. The umbrella verifier also fails if any child workflow ran at a +different SHA. + `release_profile` controls live/provider breadth passed into release checks. The manual release workflows default to `stable`; use `full` only when you intentionally want the broad advisory provider/media matrix. diff --git a/docs/cli/cron.md b/docs/cli/cron.md index 05ff5d3ae..754d61f15 100644 --- a/docs/cli/cron.md +++ b/docs/cli/cron.md @@ -35,6 +35,8 @@ Run `openclaw cron --help` for the full command surface. See [Cron jobs](/automa `openclaw cron list` and `openclaw cron show ` preview the resolved delivery route. For `channel: "last"`, the preview shows whether the route resolved from the main or current session, or will fail closed. +Provider-prefixed targets can disambiguate unresolved announce channels. For example, `to: "telegram:123"` selects Telegram when `delivery.channel` is omitted or `last`. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the prefix must match that channel; `channel: "whatsapp"` with `to: "telegram:123"` is rejected. Service prefixes such as `imessage:` and `sms:` remain channel-owned target syntax. + Isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`. diff --git a/docs/providers/google.md b/docs/providers/google.md index fc5aea174..d30d83c30 100644 --- a/docs/providers/google.md +++ b/docs/providers/google.md @@ -147,7 +147,8 @@ Choose your preferred auth method and follow the setup steps. ## Web search The bundled `gemini` web-search provider uses Gemini Google Search grounding. -Configure it under `plugins.entries.google.config.webSearch`: +Configure a dedicated search key under `plugins.entries.google.config.webSearch`, +or let it reuse `models.providers.google.apiKey` after `GEMINI_API_KEY`: ```json5 { @@ -156,8 +157,8 @@ Configure it under `plugins.entries.google.config.webSearch`: google: { config: { webSearch: { - apiKey: "AIza...", // optional if GEMINI_API_KEY is set - baseUrl: "https://generativelanguage.googleapis.com/v1beta", + apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set + baseUrl: "https://generativelanguage.googleapis.com/v1beta", // falls back to models.providers.google.baseUrl model: "gemini-2.5-flash", }, }, @@ -167,9 +168,11 @@ Configure it under `plugins.entries.google.config.webSearch`: } ``` -`webSearch.baseUrl` is optional and exists for operator proxies or compatible -Gemini API endpoints. See [Gemini search](/tools/gemini-search) for the -provider-specific tool behavior. +Credential precedence is dedicated `webSearch.apiKey`, then `GEMINI_API_KEY`, +then `models.providers.google.apiKey`. `webSearch.baseUrl` is optional and +exists for operator proxies or compatible Gemini API endpoints; when omitted, +Gemini web search reuses `models.providers.google.baseUrl`. See +[Gemini search](/tools/gemini-search) for the provider-specific tool behavior. Gemini 3 models use `thinkingLevel` rather than `thinkingBudget`. OpenClaw maps diff --git a/docs/providers/minimax.md b/docs/providers/minimax.md index 5e9e10d89..67f6257dd 100644 --- a/docs/providers/minimax.md +++ b/docs/providers/minimax.md @@ -13,7 +13,7 @@ MiniMax also provides: - Bundled speech synthesis via T2A v2 - Bundled image understanding via `MiniMax-VL-01` - Bundled music generation via `music-2.6` -- Bundled `web_search` through the MiniMax Coding Plan search API +- Bundled `web_search` through the MiniMax Token Plan search API Provider split: @@ -357,16 +357,16 @@ when the bundled text-provider catalog still shows text-only M2.7 chat refs. ### Web search -The MiniMax plugin also registers `web_search` through the MiniMax Coding Plan +The MiniMax plugin also registers `web_search` through the MiniMax Token Plan search API. - Provider id: `minimax` - Structured results: titles, URLs, snippets, related queries - Preferred env var: `MINIMAX_CODE_PLAN_KEY` -- Accepted env alias: `MINIMAX_CODING_API_KEY` -- Compatibility fallback: `MINIMAX_API_KEY` when it already points at a coding-plan token +- Accepted env aliases: `MINIMAX_CODING_API_KEY`, `MINIMAX_OAUTH_TOKEN` +- Compatibility fallback: `MINIMAX_API_KEY` when it already points at a token-plan credential - Region reuse: `plugins.entries.minimax.config.webSearch.region`, then `MINIMAX_API_HOST`, then MiniMax provider base URLs -- Search stays on provider id `minimax`; OAuth CN/global setup can still steer region indirectly through `models.providers.minimax-portal.baseUrl` +- Search stays on provider id `minimax`; OAuth CN/global setup can steer region indirectly through `models.providers.minimax-portal.baseUrl` and can provide bearer auth through `MINIMAX_OAUTH_TOKEN` Config lives under `plugins.entries.minimax.config.webSearch.*`. @@ -496,7 +496,7 @@ More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq). Shared video tool parameters and provider selection. - Web search configuration via MiniMax Coding Plan. + Web search configuration via MiniMax Token Plan. General troubleshooting and FAQ. diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md index 0d77c53c8..187da06df 100644 --- a/docs/reference/RELEASING.md +++ b/docs/reference/RELEASING.md @@ -235,8 +235,21 @@ Validation` or from the `main`/release workflow ref so workflow logic and ## Release test boxes `Full Release Validation` is how operators kick off all pre-release tests from -one entrypoint. Run it from the trusted `main` workflow ref and pass the release -branch, tag, or full commit SHA as `ref`: +one entrypoint. For a pinned commit proof on a fast-moving branch, use the +helper so every child workflow runs from a temporary branch fixed at the target +SHA: + +```bash +pnpm ci:full-release --sha +``` + +The helper pushes `release-ci/-...`, dispatches `Full Release Validation` +from that branch with `ref=`, verifies every child workflow `headSha` +matches the target, then deletes the temporary branch. This avoids proving a +newer `main` child run by accident. + +For release branch or tag validation, run it from the trusted `main` workflow +ref and pass the release branch or tag as `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -268,6 +281,9 @@ Child workflows are dispatched from the trusted ref that runs `Full Release Validation`, normally `--ref main`, even when the target `ref` points at an older release branch or tag. There is no separate Full Release Validation workflow-ref input; choose the trusted harness by choosing the workflow run ref. +Do not use `--ref main -f ref=` for exact commit proof on moving `main`; +raw commit SHAs cannot be workflow dispatch refs, so use +`pnpm ci:full-release --sha ` to create the pinned temporary branch. Use `release_profile` to select live/provider breadth: diff --git a/docs/tools/gemini-search.md b/docs/tools/gemini-search.md index e5e4c11c1..89e4e394c 100644 --- a/docs/tools/gemini-search.md +++ b/docs/tools/gemini-search.md @@ -2,7 +2,7 @@ summary: "Gemini web search with Google Search grounding" read_when: - You want to use Gemini for web_search - - You need a GEMINI_API_KEY + - You need a GEMINI_API_KEY or models.providers.google.apiKey - You want Google Search grounding title: "Gemini search" --- @@ -20,7 +20,8 @@ citations. API key. - Set `GEMINI_API_KEY` in the Gateway environment, or configure via: + Set `GEMINI_API_KEY` in the Gateway environment, reuse + `models.providers.google.apiKey`, or configure a dedicated web-search key via: ```bash openclaw configure --section web @@ -38,8 +39,8 @@ citations. google: { config: { webSearch: { - apiKey: "AIza...", // optional if GEMINI_API_KEY is set - baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional proxy/base URL override + apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set + baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional; falls back to models.providers.google.baseUrl model: "gemini-2.5-flash", // default }, }, @@ -56,8 +57,13 @@ citations. } ``` -**Environment alternative:** set `GEMINI_API_KEY` in the Gateway environment. -For a gateway install, put it in `~/.openclaw/.env`. +**Credential precedence:** Gemini web search uses +`plugins.entries.google.config.webSearch.apiKey` first, then `GEMINI_API_KEY`, +then `models.providers.google.apiKey`. For base URLs, the dedicated +`plugins.entries.google.config.webSearch.baseUrl` wins before +`models.providers.google.baseUrl`. + +For a gateway install, put env keys in `~/.openclaw/.env`. ## How it works @@ -95,8 +101,9 @@ model that supports grounding can be used via ## Base URL overrides Set `plugins.entries.google.config.webSearch.baseUrl` when Gemini web search -must route through an operator proxy or custom Gemini-compatible endpoint. A -plain `https://generativelanguage.googleapis.com` value is normalized to +must route through an operator proxy or custom Gemini-compatible endpoint. If +that is unset, Gemini web search reuses `models.providers.google.baseUrl`. A plain +`https://generativelanguage.googleapis.com` value is normalized to `https://generativelanguage.googleapis.com/v1beta`; custom proxy paths are kept as provided after trimming trailing slashes. diff --git a/docs/tools/minimax-search.md b/docs/tools/minimax-search.md index 87d976e2f..d2b4f83b2 100644 --- a/docs/tools/minimax-search.md +++ b/docs/tools/minimax-search.md @@ -1,22 +1,23 @@ --- -summary: "MiniMax Search via the Coding Plan search API" +summary: "MiniMax Search via the Token Plan search API" read_when: - You want to use MiniMax for web_search - - You need a MiniMax Coding Plan key + - You need a MiniMax Token Plan key or OAuth token - You want MiniMax CN/global search host guidance title: "MiniMax search" --- OpenClaw supports MiniMax as a `web_search` provider through the MiniMax -Coding Plan search API. It returns structured search results with titles, URLs, +Token Plan search API. It returns structured search results with titles, URLs, snippets, and related queries. -## Get a Coding Plan key +## Get a Token Plan credential - Create or copy a MiniMax Coding Plan key from + Create or copy a MiniMax Token Plan key from [MiniMax Platform](https://platform.minimax.io/user-center/basic-information/interface-key). + OAuth setups can reuse `MINIMAX_OAUTH_TOKEN` instead. Set `MINIMAX_CODE_PLAN_KEY` in the Gateway environment, or configure via: @@ -28,8 +29,9 @@ snippets, and related queries. -OpenClaw also accepts `MINIMAX_CODING_API_KEY` as an env alias. `MINIMAX_API_KEY` -is still read as a compatibility fallback when it already points at a coding-plan token. +OpenClaw also accepts `MINIMAX_CODING_API_KEY` and `MINIMAX_OAUTH_TOKEN` as env +aliases. `MINIMAX_API_KEY` is still read as a compatibility fallback when it +already points at a token-plan credential. ## Config @@ -40,7 +42,7 @@ is still read as a compatibility fallback when it already points at a coding-pla minimax: { config: { webSearch: { - apiKey: "sk-cp-...", // optional if MINIMAX_CODE_PLAN_KEY is set + apiKey: "sk-cp-...", // optional if a MiniMax Token Plan env var is set region: "global", // or "cn" }, }, @@ -57,7 +59,8 @@ is still read as a compatibility fallback when it already points at a coding-pla } ``` -**Environment alternative:** set `MINIMAX_CODE_PLAN_KEY` in the Gateway environment. +**Environment alternative:** set `MINIMAX_CODE_PLAN_KEY` or `MINIMAX_OAUTH_TOKEN` +in the Gateway environment. For a gateway install, put it in `~/.openclaw/.env`. ## Region selection @@ -80,7 +83,8 @@ automatically keeps MiniMax Search on the CN host too. Even when you authenticated MiniMax through the OAuth `minimax-portal` path, web search still registers as provider id `minimax`; the OAuth provider base URL -is only used as a region hint for CN/global host selection. +is used as a region hint for CN/global host selection, and `MINIMAX_OAUTH_TOKEN` +can satisfy the MiniMax Search bearer credential. ## Supported parameters diff --git a/docs/tools/web.md b/docs/tools/web.md index 746d77489..ad45c0dc4 100644 --- a/docs/tools/web.md +++ b/docs/tools/web.md @@ -79,7 +79,7 @@ local while `web_search` and `x_search` can use xAI Responses under the hood. AI-synthesized answers with citations via Moonshot web search. - Structured results via the MiniMax Coding Plan search API. + Structured results via the MiniMax Token Plan search API. Search via a signed-in local Ollama host or the hosted Ollama API. @@ -106,7 +106,7 @@ local while `web_search` and `x_search` can use xAI Responses under the hood. | [Gemini](/tools/gemini-search) | AI-synthesized + citations | -- | `GEMINI_API_KEY` | | [Grok](/tools/grok-search) | AI-synthesized + citations | -- | `XAI_API_KEY` | | [Kimi](/tools/kimi-search) | AI-synthesized + citations | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | -| [MiniMax Search](/tools/minimax-search) | Structured snippets | Region (`global` / `cn`) | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` | +| [MiniMax Search](/tools/minimax-search) | Structured snippets | Region (`global` / `cn`) | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN` | | [Ollama Web Search](/tools/ollama-search) | Structured snippets | -- | None for signed-in local hosts; `OLLAMA_API_KEY` for direct `https://ollama.com` search | | [Perplexity](/tools/perplexity-search) | Structured snippets | Country, language, time, domains, content limits | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` | | [SearXNG](/tools/searxng-search) | Structured snippets | Categories, language | None (self-hosted) | @@ -164,8 +164,8 @@ first one that is ready: API-backed providers first: 1. **Brave** -- `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey` (order 10) -2. **MiniMax Search** -- `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` or `plugins.entries.minimax.config.webSearch.apiKey` (order 15) -3. **Gemini** -- `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey` (order 20) +2. **MiniMax Search** -- `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN` or `plugins.entries.minimax.config.webSearch.apiKey` (order 15) +3. **Gemini** -- `plugins.entries.google.config.webSearch.apiKey`, `GEMINI_API_KEY`, or `models.providers.google.apiKey` (order 20) 4. **Grok** -- `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey` (order 30) 5. **Kimi** -- `KIMI_API_KEY` / `MOONSHOT_API_KEY` or `plugins.entries.moonshot.config.webSearch.apiKey` (order 40) 6. **Perplexity** -- `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` or `plugins.entries.perplexity.config.webSearch.apiKey` (order 50) @@ -213,8 +213,10 @@ error prompting you to configure one). ``` Provider-specific config (API keys, base URLs, modes) lives under -`plugins.entries..config.webSearch.*`. See the provider pages for -examples. +`plugins.entries..config.webSearch.*`. Gemini can also reuse +`models.providers.google.apiKey` and `models.providers.google.baseUrl` as lower-priority +fallbacks after its dedicated web-search config and `GEMINI_API_KEY`. See the +provider pages for examples. `web_fetch` fallback provider selection is separate: