vilvona 1.0.0

package/docs/tools/index.md

@@ -0,0 +1,176 @@
+---
+doc-schema-version: 1
+summary: "OpenClaw tools, skills, and plugins overview: what agents can call and how to extend them"
+read_when:
+  - You want to understand what tools OpenClaw provides
+  - You are deciding between built-in tools, skills, and plugins
+  - You need the right docs entry point for tool policy, automation, or agent coordination
+title: "Overview"
+---
+
+Use this page to choose the right Capabilities surface. **Tools** are callable
+actions, **skills** teach agents how to work, and **plugins** add runtime
+capabilities such as tools, providers, channels, hooks, and packaged skills.
+
+This is an overview and routing page. For exhaustive tool policy, defaults,
+group membership, provider restrictions, and configuration fields, use
+[Tools and custom providers](/gateway/config-tools).
+
+## Start here
+
+For most agents, start with the built-in tool categories, then adjust policy
+only when the agent should see fewer tools or needs explicit host access.
+
+| If you need to...                           | Use this first                                 | Then read                                                                                                       |
+| ------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Let an agent act with existing capabilities | [Built-in tools](#built-in-tool-categories)    | [Tool categories](#built-in-tool-categories)                                                                    |
+| Control what an agent can call              | [Tool policy](#configure-access-and-approvals) | [Tools and custom providers](/gateway/config-tools)                                                             |
+| Teach an agent a workflow                   | [Skills](#choose-tools-skills-or-plugins)      | [Skills](/tools/skills), [Creating skills](/tools/creating-skills), and [Skill Workshop](/tools/skill-workshop) |
+| Add a new integration or runtime surface    | [Plugins](#extend-capabilities)                | [Plugins](/tools/plugin) and [Build plugins](/plugins/building-plugins)                                         |
+| Run work later or in the background         | [Automation](/automation)                      | [Automation overview](/automation)                                                                              |
+| Coordinate multiple agents or harnesses     | [Sub-agents](/tools/subagents)                 | [ACP agents](/tools/acp-agents) and [Agent send](/tools/agent-send)                                             |
+| Search a large OpenClaw tool catalog        | [Tool Search](/tools/tool-search)              | [Tool Search](/tools/tool-search)                                                                               |
+
+## Choose tools, skills, or plugins
+
+<Steps>
+  <Step title="Use a tool when the agent needs to act">
+    A tool is a typed function the agent can call, such as `exec`, `browser`,
+    `web_search`, `message`, or `image_generate`. Use tools when the agent
+    needs to read data, change files, send messages, call a provider, or operate
+    another system. Visible tools are sent to the model as structured function
+    definitions.
+
+    The model only sees tools that survive the active profile, allow/deny
+    policy, provider restrictions, sandbox state, channel permissions, and
+    plugin availability.
+
+  </Step>
+
+  <Step title="Use a skill when the agent needs instructions">
+    A skill is a `SKILL.md` instruction pack loaded into the agent prompt. Use a
+    skill when the agent already has the tools it needs, but needs a repeatable
+    workflow, review rubric, command sequence, or operating constraint.
+
+    Skills can live in a workspace, shared skill directory, managed OpenClaw
+    skill root, or plugin package.
+
+    [Skills](/tools/skills) | [Skill Workshop](/tools/skill-workshop) | [Creating skills](/tools/creating-skills) | [Skills config](/tools/skills-config)
+
+  </Step>
+
+  <Step title="Use a plugin when OpenClaw needs a new capability">
+    A plugin can add tools, skills, channels, model providers, speech, realtime
+    voice, media generation, web search, web fetch, hooks, and other runtime
+    capabilities. Use a plugin when the capability has code, credentials,
+    lifecycle hooks, manifest metadata, or installable packaging. Existing
+    plugins can be installed from ClawHub, npm, git, local directories, or
+    archives.
+
+    [Install and configure plugins](/tools/plugin) | [Build plugins](/plugins/building-plugins) | [Plugin SDK](/plugins/sdk-overview)
+
+  </Step>
+</Steps>
+
+## Built-in tool categories
+
+The table lists representative tools so you can recognize the surface. It is
+not the full policy reference. For exact groups, defaults, and allow/deny
+semantics, use [Tools and custom providers](/gateway/config-tools).
+
+| Category                | Use when the agent needs to...                                                | Representative tools                                                 | Read next                                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Runtime                 | Run commands, manage processes, or use provider-backed Python analysis        | `exec`, `process`, `code_execution`                                  | [Exec](/tools/exec), [Code execution](/tools/code-execution)                                |
+| Files                   | Read and change workspace files                                               | `read`, `write`, `edit`, `apply_patch`                               | [Apply patch](/tools/apply-patch)                                                           |
+| Web                     | Search the web, search X posts, or fetch readable page content                | `web_search`, `x_search`, `web_fetch`                                | [Web tools](/tools/web), [Web fetch](/tools/web-fetch)                                      |
+| Browser                 | Operate a browser session                                                     | `browser`                                                            | [Browser](/tools/browser)                                                                   |
+| Messaging and channels  | Send replies or channel actions                                               | `message`                                                            | [Agent send](/tools/agent-send)                                                             |
+| Sessions and agents     | Inspect sessions, delegate work, steer another run, or report status          | `sessions_*`, `subagents`, `agents_list`, `session_status`, `goal`   | [Goal](/tools/goal), [Sub-agents](/tools/subagents), [Session tool](/concepts/session-tool) |
+| Automation              | Schedule work or respond to background events                                 | `cron`, `heartbeat_respond`                                          | [Automation](/automation)                                                                   |
+| Gateway and nodes       | Inspect Gateway state or paired target devices                                | `gateway`, `nodes`                                                   | [Gateway configuration](/gateway/configuration), [Nodes](/nodes)                            |
+| Media                   | Analyze, generate, or speak media                                             | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` | [Media overview](/tools/media-overview)                                                     |
+| Large OpenClaw catalogs | Search and call many eligible tools without sending every schema to the model | `tool_search_code`, `tool_search`, `tool_describe`                   | [Tool Search](/tools/tool-search)                                                           |
+
+<Note>
+Tool Search is an experimental OpenClaw agent surface. Codex harness runs use
+Codex-native code mode, native tool search, deferred dynamic tools, and nested
+tool calls instead of `tools.toolSearch`.
+</Note>
+
+## Plugin-provided tools
+
+Plugins can register additional tools. Plugin authors wire tools through
+`api.registerTool(...)` and the manifest's `contracts.tools`; use
+[Plugin SDK](/plugins/sdk-overview) and [Plugin manifest](/plugins/manifest)
+for contract details.
+
+Common plugin-provided tools include:
+
+- [Diffs](/tools/diffs) for rendering file and markdown diffs
+- [LLM Task](/tools/llm-task) for JSON-only workflow steps
+- [Lobster](/tools/lobster) for typed workflows with resumable approvals
+- [Tokenjuice](/tools/tokenjuice) for compacting noisy `exec` and `bash` tool
+  output
+- [Tool Search](/tools/tool-search) for discovering and calling large tool
+  catalogs without putting every schema in the prompt
+- [Canvas](/plugins/reference/canvas) for node Canvas control and A2UI
+  rendering
+
+## Configure access and approvals
+
+Tool policy is enforced before the model call. If policy removes a tool, the
+model does not receive that tool's schema for the turn. A run can lose tools
+because of global config, per-agent config, channel policy, provider
+restrictions, sandbox rules, channel/runtime policy, or plugin availability.
+
+- [Tools and custom providers](/gateway/config-tools) documents tool profiles,
+  allow/deny lists, provider-specific restrictions, loop detection, and
+  provider-backed tool settings.
+- [Exec approvals](/tools/exec-approvals) documents host command approval
+  policy.
+- [Elevated exec](/tools/elevated) documents controlled execution outside the
+  sandbox.
+- [Sandbox vs tool policy vs elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) explains which layer controls file and process access.
+- [Per-agent sandbox and tool restrictions](/tools/multi-agent-sandbox-tools)
+  documents agent-specific restrictions for delegated runs.
+
+## Extend capabilities
+
+Choose the extension path by the job you need OpenClaw to do:
+
+- Install or manage an existing plugin with [Plugins](/tools/plugin).
+- Build a new integration, provider, channel, tool, or hook with
+  [Build plugins](/plugins/building-plugins).
+- Add or tune reusable agent instructions with [Skills](/tools/skills) and
+  [Creating skills](/tools/creating-skills).
+- Use [Plugin SDK](/plugins/sdk-overview) and [Plugin manifest](/plugins/manifest) when you need implementation contracts.
+
+## Troubleshoot missing tools
+
+If the model cannot see or call a tool, start with the effective policy for the
+current turn:
+
+1. Check the active profile, `tools.allow`, and `tools.deny` in
+   [Tools and custom providers](/gateway/config-tools).
+2. Check provider-specific restrictions in
+   [Tools and custom providers](/gateway/config-tools) and confirm the selected
+   [model provider](/concepts/model-providers) supports the tool shape.
+3. Check channel permissions, sandbox state, and elevated access with
+   [Sandbox vs tool policy vs elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) and [Elevated exec](/tools/elevated).
+4. Check whether the owning plugin is installed and enabled in
+   [Plugins](/tools/plugin).
+5. For delegated runs, check per-agent restrictions in
+   [Per-agent sandbox and tool restrictions](/tools/multi-agent-sandbox-tools).
+6. For large OpenClaw catalogs, confirm whether the run uses direct tool exposure or
+   [Tool Search](/tools/tool-search).
+
+## Related
+
+- [Automation](/automation) for cron, tasks, heartbeat, commitments, hooks, standing orders, and Task Flow
+- [Agents](/concepts/agent) for the agent model, sessions, memory, and multi-agent coordination
+- [Tools and custom providers](/gateway/config-tools) for the canonical tool policy reference
+- [Plugins](/tools/plugin) for plugin installation and management
+- [Plugin SDK](/plugins/sdk-overview) for plugin author reference
+- [Skills](/tools/skills) for skill load order, gating, and config
+- [Skill Workshop](/tools/skill-workshop) for generated and reviewed skill creation
+- [Tool Search](/tools/tool-search) for compact OpenClaw tool catalog discovery

package/docs/tools/kimi-search.md

@@ -0,0 +1,105 @@
+---
+summary: "Kimi web search via Moonshot web search"
+read_when:
+  - You want to use Kimi for web_search
+  - You need a KIMI_API_KEY or MOONSHOT_API_KEY
+title: "Kimi search"
+---
+
+OpenClaw supports Kimi as a `web_search` provider, using Moonshot web search
+to produce AI-synthesized answers with citations.
+
+## Get an API key
+
+<Steps>
+  <Step title="Create a key">
+    Get an API key from [Moonshot AI](https://platform.moonshot.cn/).
+  </Step>
+  <Step title="Store the key">
+    Set `KIMI_API_KEY` or `MOONSHOT_API_KEY` in the Gateway environment, or
+    configure via:
+
+    ```bash
+    openclaw configure --section web
+    ```
+
+  </Step>
+</Steps>
+
+When you choose **Kimi** during `openclaw onboard` or
+`openclaw configure --section web`, OpenClaw can also ask for:
+
+- the Moonshot API region:
+  - `https://api.moonshot.ai/v1`
+  - `https://api.moonshot.cn/v1`
+- the default Kimi web-search model (defaults to `kimi-k2.6`)
+
+## Config
+
+```json5
+{
+  plugins: {
+    entries: {
+      moonshot: {
+        config: {
+          webSearch: {
+            apiKey: "sk-...", // optional if KIMI_API_KEY or MOONSHOT_API_KEY is set
+            baseUrl: "https://api.moonshot.ai/v1",
+            model: "kimi-k2.6",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "kimi",
+      },
+    },
+  },
+}
+```
+
+If you use the China API host for chat (`models.providers.moonshot.baseUrl`:
+`https://api.moonshot.cn/v1`), OpenClaw reuses that same host for Kimi
+`web_search` when `tools.web.search.kimi.baseUrl` is omitted, so keys from
+[platform.moonshot.cn](https://platform.moonshot.cn/) do not hit the
+international endpoint by mistake (which often returns HTTP 401). Override
+with `tools.web.search.kimi.baseUrl` when you need a different search base URL.
+
+**Environment alternative:** set `KIMI_API_KEY` or `MOONSHOT_API_KEY` in the
+Gateway environment. For a gateway install, put it in `~/.openclaw/.env`.
+
+If you omit `baseUrl`, OpenClaw defaults to `https://api.moonshot.ai/v1`.
+If you omit `model`, OpenClaw defaults to `kimi-k2.6`.
+
+## How it works
+
+Kimi uses Moonshot web search to synthesize answers with inline citations,
+similar to Gemini and Grok's grounded response approach.
+
+OpenClaw treats Kimi `web_search` as successful only after Moonshot returns
+native web-search grounding evidence, such as a replayable `$web_search` tool
+payload, `search_results`, or citation URLs. If Kimi stops immediately with a
+plain chat answer like "I cannot browse the internet" and no grounding evidence,
+OpenClaw returns a structured `kimi_web_search_ungrounded` error instead of
+wrapping that text as a search result. Retry the query, switch to a structured
+provider such as Brave, or use `web_fetch` / the browser tool when you already
+have a target URL.
+
+## Supported parameters
+
+Kimi search supports `query`.
+
+`count` is accepted for shared `web_search` compatibility, but Kimi still
+returns one synthesized answer with citations rather than an N-result list.
+
+Provider-specific filters are not currently supported.
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Moonshot AI](/providers/moonshot) -- Moonshot model + Kimi Coding provider docs
+- [Gemini Search](/tools/gemini-search) -- AI-synthesized answers via Google grounding
+- [Grok Search](/tools/grok-search) -- AI-synthesized answers via xAI grounding

package/docs/tools/llm-task.md

@@ -0,0 +1,137 @@
+---
+summary: "JSON-only LLM tasks for workflows (optional plugin tool)"
+read_when:
+  - You want a JSON-only LLM step inside workflows
+  - You need schema-validated LLM output for automation
+title: "LLM task"
+---
+
+`llm-task` is an **optional plugin tool** that runs a JSON-only LLM task and
+returns structured output (optionally validated against JSON Schema).
+
+This is ideal for workflow engines like Lobster: you can add a single LLM step
+without writing custom OpenClaw code for each workflow.
+
+## Enable the plugin
+
+1. Enable the plugin:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": { "enabled": true }
+    }
+  }
+}
+```
+
+2. Allow the optional tool:
+
+```json
+{
+  "tools": {
+    "alsoAllow": ["llm-task"]
+  }
+}
+```
+
+Use `tools.allow` only when you want restrictive allowlist mode.
+
+## Config (optional)
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": {
+        "enabled": true,
+        "config": {
+          "defaultProvider": "openai",
+          "defaultModel": "gpt-5.5",
+          "defaultAuthProfileId": "main",
+          "allowedModels": ["openai/gpt-5.5"],
+          "maxTokens": 800,
+          "timeoutMs": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+`allowedModels` is an allowlist of `provider/model` strings. If set, any request
+outside the list is rejected.
+
+## Tool parameters
+
+- `prompt` (string, required)
+- `input` (any, optional)
+- `schema` (object, optional JSON Schema)
+- `provider` (string, optional)
+- `model` (string, optional)
+- `thinking` (string, optional)
+- `authProfileId` (string, optional)
+- `temperature` (number, optional)
+- `maxTokens` (number, optional)
+- `timeoutMs` (number, optional)
+
+`thinking` accepts the standard OpenClaw reasoning presets, such as `low` or `medium`.
+
+## Output
+
+Returns `details.json` containing the parsed JSON (and validates against
+`schema` when provided).
+
+## Example: Lobster workflow step
+
+### Important limitation
+
+The example below assumes the **standalone Lobster CLI** is running in an environment where `openclaw.invoke` already has the correct gateway URL/auth context.
+
+For the bundled **embedded** Lobster runner inside OpenClaw, this nested CLI pattern is **not currently reliable**:
+
+```lobster
+openclaw.invoke --tool llm-task --action json --args-json '{ ... }'
+```
+
+Until embedded Lobster has a supported bridge for this flow, prefer either:
+
+- direct `llm-task` tool calls outside Lobster, or
+- Lobster steps that do not rely on nested `openclaw.invoke` calls.
+
+Standalone Lobster CLI example:
+
+```lobster
+openclaw.invoke --tool llm-task --action json --args-json '{
+  "prompt": "Given the input email, return intent and draft.",
+  "thinking": "low",
+  "input": {
+    "subject": "Hello",
+    "body": "Can you help?"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "intent": { "type": "string" },
+      "draft": { "type": "string" }
+    },
+    "required": ["intent", "draft"],
+    "additionalProperties": false
+  }
+}'
+```
+
+## Safety notes
+
+- The tool is **JSON-only** and instructs the model to output only JSON (no
+  code fences, no commentary).
+- No tools are exposed to the model for this run.
+- Treat output as untrusted unless you validate with `schema`.
+- Put approvals before any side-effecting step (send, post, exec).
+
+## Related
+
+- [Thinking levels](/tools/thinking)
+- [Sub-agents](/tools/subagents)
+- [Slash commands](/tools/slash-commands)