vilvona 1.0.0

package/docs/providers/perplexity-provider.md

@@ -0,0 +1,123 @@
+---
+summary: "Perplexity web search provider setup (API key, search modes, filtering)"
+title: "Perplexity"
+read_when:
+  - You want to configure Perplexity as a web search provider
+  - You need the Perplexity API key or OpenRouter proxy setup
+---
+
+The Perplexity plugin provides web search capabilities through the Perplexity
+Search API or Perplexity Sonar via OpenRouter.
+
+<Note>
+This page is the Perplexity **provider** setup. For the Perplexity **tool** (how the agent uses it), see [Perplexity tool](/tools/perplexity-search).
+</Note>
+
+| Property    | Value                                                                  |
+| ----------- | ---------------------------------------------------------------------- |
+| Type        | Web search provider (not a model provider)                             |
+| Auth        | `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter) |
+| Config path | `plugins.entries.perplexity.config.webSearch.apiKey`                   |
+
+## Getting started
+
+<Steps>
+  <Step title="Set the API key">
+    Run the interactive web-search configuration flow:
+
+    ```bash
+    openclaw configure --section web
+    ```
+
+    Or set the key directly:
+
+    ```bash
+    openclaw config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
+    ```
+
+  </Step>
+  <Step title="Start searching">
+    The agent will automatically use Perplexity for web searches once the key is
+    configured. No additional steps are required.
+  </Step>
+</Steps>
+
+## Search modes
+
+The plugin auto-selects the transport based on API key prefix:
+
+<Tabs>
+  <Tab title="Native Perplexity API (pplx-)">
+    When your key starts with `pplx-`, OpenClaw uses the native Perplexity Search
+    API. This transport returns structured results and supports domain, language,
+    and date filters (see filtering options below).
+  </Tab>
+  <Tab title="OpenRouter / Sonar (sk-or-)">
+    When your key starts with `sk-or-`, OpenClaw routes through OpenRouter using
+    the Perplexity Sonar model. This transport returns AI-synthesized answers with
+    citations.
+  </Tab>
+</Tabs>
+
+| Key prefix | Transport                    | Features                                         |
+| ---------- | ---------------------------- | ------------------------------------------------ |
+| `pplx-`    | Native Perplexity Search API | Structured results, domain/language/date filters |
+| `sk-or-`   | OpenRouter (Sonar)           | AI-synthesized answers with citations            |
+
+## Native API filtering
+
+<Note>
+Filtering options are only available when using the native Perplexity API
+(`pplx-` key). OpenRouter/Sonar searches do not support these parameters.
+</Note>
+
+When using the native Perplexity API, searches support the following filters:
+
+| Filter         | Description                            | Example                             |
+| -------------- | -------------------------------------- | ----------------------------------- |
+| Country        | 2-letter country code                  | `us`, `de`, `jp`                    |
+| Language       | ISO 639-1 language code                | `en`, `fr`, `zh`                    |
+| Date range     | Recency window                         | `day`, `week`, `month`, `year`      |
+| Domain filters | Allowlist or denylist (max 20 domains) | `example.com`                       |
+| Content budget | Token limits per response / per page   | `max_tokens`, `max_tokens_per_page` |
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Environment variable for daemon processes">
+    If the OpenClaw Gateway runs as a daemon (launchd/systemd), make sure
+    `PERPLEXITY_API_KEY` is available to that process.
+
+    <Warning>
+    A key exported only in an interactive shell will not be visible to a
+    launchd/systemd daemon unless that environment is explicitly imported. Set
+    the key in `~/.openclaw/.env` or via `env.shellEnv` to ensure the gateway
+    process can read it.
+    </Warning>
+
+  </Accordion>
+
+  <Accordion title="OpenRouter proxy setup">
+    If you prefer to route Perplexity searches through OpenRouter, set an
+    `OPENROUTER_API_KEY` (prefix `sk-or-`) instead of a native Perplexity key.
+    OpenClaw will detect the prefix and switch to the Sonar transport
+    automatically.
+
+    <Tip>
+    The OpenRouter transport is useful if you already have an OpenRouter account
+    and want consolidated billing across multiple providers.
+    </Tip>
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Perplexity search tool" href="/tools/perplexity-search" icon="magnifying-glass">
+    How the agent invokes Perplexity searches and interprets results.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full configuration reference including plugin entries.
+  </Card>
+</CardGroup>

package/docs/providers/pixverse.md

@@ -0,0 +1,165 @@
+---
+summary: "PixVerse video generation setup in OpenClaw"
+title: "PixVerse"
+read_when:
+  - You want to use PixVerse video generation in OpenClaw
+  - You need the PixVerse API key/env setup
+  - You want to make PixVerse the default video provider
+---
+
+OpenClaw provides `pixverse` as an official external plugin for hosted PixVerse video generation. The plugin registers the `pixverse` provider against the `videoGenerationProviders` contract.
+
+| Property           | Value                                                                |
+| ------------------ | -------------------------------------------------------------------- |
+| Provider id        | `pixverse`                                                           |
+| Plugin package     | `@openclaw/pixverse-provider`                                        |
+| Auth env var       | `PIXVERSE_API_KEY`                                                   |
+| Onboarding flag    | `--auth-choice pixverse-api-key`                                     |
+| Direct CLI flag    | `--pixverse-api-key <key>`                                           |
+| API                | PixVerse Platform API v2 (`video_id` submission plus result polling) |
+| Default model      | `pixverse/v6`                                                        |
+| Default API region | International                                                        |
+
+## Getting started
+
+<Steps>
+  <Step title="Install the plugin">
+    ```bash
+    openclaw plugins install clawhub:@openclaw/pixverse-provider
+    openclaw gateway restart
+    ```
+  </Step>
+  <Step title="Set the API key">
+    ```bash
+    openclaw onboard --auth-choice pixverse-api-key
+    ```
+
+    The wizard asks whether to use the International endpoint
+    (`https://app-api.pixverse.ai/openapi/v2`) or the CN endpoint
+    (`https://app-api.pixverseai.cn/openapi/v2`) before writing `region` and
+    `baseUrl` into the provider config.
+
+  </Step>
+  <Step title="Set PixVerse as the default video provider">
+    ```bash
+    openclaw config set agents.defaults.videoGenerationModel.primary "pixverse/v6"
+    ```
+  </Step>
+  <Step title="Generate a video">
+    Ask the agent to generate a video. PixVerse will be used automatically.
+  </Step>
+</Steps>
+
+## Supported modes and models
+
+The provider exposes PixVerse generation models through OpenClaw's shared video tool.
+
+| Mode           | Models               | Reference input         |
+| -------------- | -------------------- | ----------------------- |
+| Text-to-video  | `v6` (default), `c1` | None                    |
+| Image-to-video | `v6` (default), `c1` | 1 local or remote image |
+
+Local image references are uploaded to PixVerse before the image-to-video request. Remote image URLs are passed through the PixVerse image upload endpoint as `image_url`.
+
+| Option          | Supported values                                                            |
+| --------------- | --------------------------------------------------------------------------- |
+| Duration        | 1-15 seconds                                                                |
+| Resolution      | `360P`, `540P`, `720P`, `1080P`                                             |
+| Aspect ratio    | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `2:3`, `3:2`, `21:9` for text-to-video |
+| Generated audio | `audio: true`                                                               |
+
+<Note>
+PixVerse image template generation is not exposed through `image_generate` yet. That API is template-id driven, while OpenClaw's shared image-generation contract does not currently have a PixVerse-specific typed option bag.
+</Note>
+
+## Provider options
+
+The video provider accepts these optional provider-specific keys:
+
+| Option                               | Type   | Effect                            |
+| ------------------------------------ | ------ | --------------------------------- |
+| `seed`                               | number | Deterministic seed when supported |
+| `negativePrompt` / `negative_prompt` | string | Negative prompt                   |
+| `quality`                            | string | PixVerse quality such as `720p`   |
+| `motionMode` / `motion_mode`         | string | Image-to-video motion mode        |
+| `cameraMovement` / `camera_movement` | string | PixVerse camera movement preset   |
+| `templateId` / `template_id`         | number | Activated PixVerse template id    |
+
+## Configuration
+
+```json5
+{
+  agents: {
+    defaults: {
+      videoGenerationModel: {
+        primary: "pixverse/v6",
+      },
+    },
+  },
+}
+```
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="API region">
+    OpenClaw defaults to the international PixVerse API. Set `models.providers.pixverse.region`
+    manually when your key belongs to a specific PixVerse platform region, or use
+    `openclaw onboard --auth-choice pixverse-api-key` to choose one in the setup wizard:
+
+    | Region value    | PixVerse API base URL                         |
+    | --------------- | --------------------------------------------- |
+    | `international` | `https://app-api.pixverse.ai/openapi/v2`      |
+    | `cn`            | `https://app-api.pixverseai.cn/openapi/v2`    |
+
+    ```json5
+    {
+      models: {
+        providers: {
+          pixverse: {
+            region: "cn", // "international" or "cn"
+            baseUrl: "https://app-api.pixverseai.cn/openapi/v2",
+            models: [],
+          },
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+
+  <Accordion title="Custom base URL">
+    Set `models.providers.pixverse.baseUrl` only when routing through a trusted compatible proxy.
+    `baseUrl` takes precedence over `region`.
+
+    ```json5
+    {
+      models: {
+        providers: {
+          pixverse: {
+            baseUrl: "https://app-api.pixverse.ai/openapi/v2",
+          },
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+
+  <Accordion title="Task polling">
+    PixVerse returns a `video_id` from the generation request. OpenClaw polls
+    `/openapi/v2/video/result/{video_id}` until the task succeeds, fails,
+    or times out.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Video generation" href="/tools/video-generation" icon="video">
+    Shared tool parameters, provider selection, and async behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
+    Agent default settings including video generation model.
+  </Card>
+</CardGroup>

package/docs/providers/qianfan.md

@@ -0,0 +1,132 @@
+---
+summary: "Use Qianfan's unified API to access many models in OpenClaw"
+read_when:
+  - You want a single API key for many LLMs
+  - You need Baidu Qianfan setup guidance
+title: "Qianfan"
+---
+
+Qianfan is Baidu's MaaS platform, providing a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+| Property | Value                             |
+| -------- | --------------------------------- |
+| Provider | `qianfan`                         |
+| Auth     | `QIANFAN_API_KEY`                 |
+| API      | OpenAI-compatible                 |
+| Base URL | `https://qianfan.baidubce.com/v2` |
+
+## Getting started
+
+<Steps>
+  <Step title="Create a Baidu Cloud account">
+    Sign up or log in at the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey) and ensure you have Qianfan API access enabled.
+  </Step>
+  <Step title="Generate an API key">
+    Create a new application or select an existing one, then generate an API key. The key format is `bce-v3/ALTAK-...`.
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    openclaw onboard --auth-choice qianfan-api-key
+    ```
+  </Step>
+  <Step title="Verify the model is available">
+    ```bash
+    openclaw models list --provider qianfan
+    ```
+  </Step>
+</Steps>
+
+## Built-in catalog
+
+| Model ref                            | Input       | Context | Max output | Reasoning | Notes         |
+| ------------------------------------ | ----------- | ------- | ---------- | --------- | ------------- |
+| `qianfan/deepseek-v3.2`              | text        | 98,304  | 32,768     | Yes       | Default model |
+| `qianfan/ernie-5.0-thinking-preview` | text, image | 119,000 | 64,000     | Yes       | Multimodal    |
+
+<Tip>
+The default bundled model ref is `qianfan/deepseek-v3.2`. You only need to override `models.providers.qianfan` when you need a custom base URL or model metadata.
+</Tip>
+
+## Config example
+
+```json5
+{
+  env: { QIANFAN_API_KEY: "bce-v3/ALTAK-..." },
+  agents: {
+    defaults: {
+      model: { primary: "qianfan/deepseek-v3.2" },
+      models: {
+        "qianfan/deepseek-v3.2": { alias: "QIANFAN" },
+      },
+    },
+  },
+  models: {
+    providers: {
+      qianfan: {
+        baseUrl: "https://qianfan.baidubce.com/v2",
+        api: "openai-completions",
+        models: [
+          {
+            id: "deepseek-v3.2",
+            name: "DEEPSEEK V3.2",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 98304,
+            maxTokens: 32768,
+          },
+          {
+            id: "ernie-5.0-thinking-preview",
+            name: "ERNIE-5.0-Thinking-Preview",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 119000,
+            maxTokens: 64000,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+<AccordionGroup>
+  <Accordion title="Transport and compatibility">
+    Qianfan runs through the OpenAI-compatible transport path, not native OpenAI request shaping. This means standard OpenAI SDK features work, but provider-specific parameters may not be forwarded.
+  </Accordion>
+
+  <Accordion title="Catalog and overrides">
+    The bundled catalog currently includes `deepseek-v3.2` and `ernie-5.0-thinking-preview`. Add or override `models.providers.qianfan` only when you need a custom base URL or model metadata.
+
+    <Note>
+    Model refs use the `qianfan/` prefix (for example `qianfan/deepseek-v3.2`).
+    </Note>
+
+  </Accordion>
+
+  <Accordion title="Troubleshooting">
+    - Ensure your API key starts with `bce-v3/ALTAK-` and has Qianfan API access enabled in the Baidu Cloud console.
+    - If models are not listed, confirm your account has the Qianfan service activated.
+    - The default base URL is `https://qianfan.baidubce.com/v2`. Only change it if you use a custom endpoint or proxy.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full OpenClaw configuration reference.
+  </Card>
+  <Card title="Agent setup" href="/concepts/agent" icon="robot">
+    Configuring agent defaults and model assignments.
+  </Card>
+  <Card title="Qianfan API docs" href="https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb" icon="arrow-up-right-from-square">
+    Official Qianfan API documentation.
+  </Card>
+</CardGroup>

package/docs/providers/qwen-oauth.md

@@ -0,0 +1,115 @@
+---
+summary: "Use the Qwen Portal provider id with OpenClaw"
+read_when:
+  - You want to configure the qwen-oauth provider id
+  - You previously used Qwen Portal OAuth credentials
+  - You need the Qwen Portal endpoint or migration guidance
+title: "Qwen OAuth / Portal"
+---
+
+`qwen-oauth` is the Qwen Portal provider id. It targets the Qwen Portal endpoint
+and keeps older Qwen OAuth / portal setups addressable through a distinct
+provider id.
+
+Use this provider when you specifically have a current Qwen Portal token for
+`https://portal.qwen.ai/v1`, or when you are migrating an older Qwen Portal /
+Qwen CLI setup and want to keep those credentials separate from the canonical
+Qwen Cloud provider. It is not the recommended first choice for new Qwen users.
+
+For new Qwen Cloud setups, prefer [Qwen](/providers/qwen) with the Standard
+ModelStudio endpoint unless you specifically have a current Qwen Portal token.
+
+## Setup
+
+Provide your portal token through onboarding:
+
+```bash
+openclaw onboard --auth-choice qwen-oauth
+```
+
+Or set:
+
+```bash
+export QWEN_API_KEY="<your-qwen-portal-token>" # pragma: allowlist secret
+```
+
+## Defaults
+
+- Provider: `qwen-oauth`
+- Aliases: `qwen-portal`, `qwen-cli`
+- Base URL: `https://portal.qwen.ai/v1`
+- Env var: `QWEN_API_KEY`
+- API style: OpenAI-compatible
+- Default model: `qwen-oauth/qwen3.5-plus`
+
+## How this differs from Qwen
+
+OpenClaw has two Qwen-facing provider ids:
+
+| Provider     | Endpoint family                                          | Best for                                                                               |
+| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `qwen`       | Qwen Cloud / Alibaba DashScope and Coding Plan endpoints | New API-key setups, Standard pay-as-you-go, Coding Plan, multimodal DashScope features |
+| `qwen-oauth` | Qwen Portal endpoint at `portal.qwen.ai/v1`              | Existing Qwen Portal tokens and legacy Qwen OAuth / CLI setups                         |
+
+Both providers use OpenAI-compatible request shapes, but they are separate auth
+surfaces. A token stored for `qwen-oauth` should not be treated as a DashScope
+or ModelStudio key, and a new DashScope key should use the canonical `qwen`
+provider instead.
+
+## When to choose Qwen OAuth / Portal
+
+- You already have a working Qwen Portal token.
+- You are preserving a legacy Qwen OAuth or Qwen CLI workflow while moving to
+  OpenClaw's provider model.
+- You need to test compatibility with the Qwen Portal endpoint specifically.
+
+Choose [Qwen](/providers/qwen) for new setup, broader endpoint choices, Standard
+ModelStudio, Coding Plan, and the full bundled Qwen catalog.
+
+## Models
+
+The bundled catalog seeds the Qwen Portal default:
+
+- `qwen-oauth/qwen3.5-plus`
+
+Availability depends on the current Qwen Portal account and token. If your
+account uses ModelStudio / DashScope API keys instead, configure the canonical
+`qwen` provider:
+
+```bash
+openclaw onboard --auth-choice qwen-standard-api-key
+openclaw models set qwen/qwen3-coder-plus
+```
+
+## Migration
+
+Legacy Qwen Portal OAuth profiles may not be refreshable. If a portal profile
+stops working, re-authenticate with a current token or switch to the Standard
+Qwen provider:
+
+```bash
+openclaw onboard --auth-choice qwen-standard-api-key
+```
+
+Standard global ModelStudio uses:
+
+```text
+https://dashscope-intl.aliyuncs.com/compatible-mode/v1
+```
+
+## Troubleshooting
+
+- Portal OAuth refresh failures: legacy Qwen Portal OAuth profiles may not be
+  refreshable. Re-run onboarding with a current token.
+- Wrong endpoint errors: confirm the model ref starts with `qwen-oauth/` when
+  using a portal token. Use `qwen/` refs only for the canonical Qwen provider.
+- `QWEN_API_KEY` confusion: both Qwen pages mention this env var, but onboarding
+  stores credentials under the selected provider id. Prefer onboarding when you
+  keep both `qwen` and `qwen-oauth` available on the same machine.
+
+## Related
+
+- [Qwen](/providers/qwen)
+- [Alibaba Model Studio](/providers/alibaba)
+- [Model providers](/concepts/model-providers)
+- [All providers](/providers/index)