openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(sync): mirror docs from openclaw/openclaw@f2370b769c

Browse Source
This commit is contained in:
openclaw-docs-sync[bot] 2026-05-02 04:46:15 +00:00
parent c15bbd77ec
commit 7dbc3a200d
15 changed files with 101 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.openclaw-sync/source.json
View File

@ -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"
}

4
docs/.generated/plugin-sdk-api-baseline.sha256
View File

@ -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

2
docs/automation/cron-jobs.md
View File

@ -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:<id>`, `user:<id>`). 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:<id>`, `user:<id>`, `imessage:<handle>`, and `sms:<number>` 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.

6
docs/channels/channel-routing.md
View File

@ -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:<id>`, `user:<id>`, `room:<id>`, `thread:<id>`, `imessage:<handle>`, and `sms:<number>` 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:

1
docs/channels/slack.md
View File

@ -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:<agentId>:slack:channel:<channelId>`.
- Thread replies can create thread session suffixes (`:thread:<threadTs>`) when applicable.

1
docs/channels/synology-chat.md
View File

@ -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.

2
docs/channels/telegram.md
View File

@ -878,7 +878,7 @@ channels:
proxy: socks5://<user>:<password>@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

14
docs/ci.md
View File

@ -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=<sha>`:
```bash
pnpm ci:full-release --sha <full-sha>
```
GitHub workflow dispatch refs must be branches or tags, not raw commit SHAs. The
helper pushes a temporary `release-ci/<sha>-...` 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.

2
docs/cli/cron.md
View File

@ -35,6 +35,8 @@ Run `openclaw cron --help` for the full command surface. See [Cron jobs](/automa
`openclaw cron list` and `openclaw cron show <job-id>` 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.
<Note>
Isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`.
</Note>

15
docs/providers/google.md
View File

@ -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.
<Tip>
Gemini 3 models use `thinkingLevel` rather than `thinkingBudget`. OpenClaw maps

12
docs/providers/minimax.md
View File

@ -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.
</Card>
<Card title="MiniMax Search" href="/tools/minimax-search" icon="magnifying-glass">
Web search configuration via MiniMax Coding Plan.
Web search configuration via MiniMax Token Plan.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
General troubleshooting and FAQ.

20
docs/reference/RELEASING.md
View File

@ -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 <full-sha>
```
The helper pushes `release-ci/<sha>-...`, dispatches `Full Release Validation`
from that branch with `ref=<sha>`, 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=<sha>` for exact commit proof on moving `main`;
raw commit SHAs cannot be workflow dispatch refs, so use
`pnpm ci:full-release --sha <sha>` to create the pinned temporary branch.
Use `release_profile` to select live/provider breadth:

23
docs/tools/gemini-search.md
View File

@ -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.
</Step>
<Step title="Store the 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.

24
docs/tools/minimax-search.md
View File

@ -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
<Steps>
<Step title="Create a key">
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.
</Step>
<Step title="Store the key">
Set `MINIMAX_CODE_PLAN_KEY` in the Gateway environment, or configure via:
@ -28,8 +29,9 @@ snippets, and related queries.
</Step>
</Steps>
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

14
docs/tools/web.md
View File

@ -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.
</Card>
<Card title="MiniMax Search" icon="globe" href="/tools/minimax-search">
Structured results via the MiniMax Coding Plan search API.
Structured results via the MiniMax Token Plan search API.
</Card>
<Card title="Ollama Web Search" icon="globe" href="/tools/ollama-search">
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.<plugin>.config.webSearch.*`. See the provider pages for
examples.
`plugins.entries.<plugin>.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: