diff --git a/.gitignore b/.gitignore index 932dc39b7ac..f4507163ad8 100644 --- a/.gitignore +++ b/.gitignore @@ -118,6 +118,8 @@ USER.md !.agents/skills/gitcrawl/ !.agents/skills/gitcrawl/** !.agents/skills/openclaw-docs/** +!.agents/skills/openclaw-refactor-docs/ +!.agents/skills/openclaw-refactor-docs/** !.agents/skills/openclaw-debugging/ !.agents/skills/openclaw-debugging/** !.agents/skills/openclaw-ghsa-maintainer/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 501f754071f..e555333802c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai - Runtime/Fly: detect Fly Machines as container environments from their runtime env vars, so gateway bind and Bonjour defaults match remote container launches. (#80209) Thanks @liorb-mountapps. - Providers/fal: route GPT Image 2 and Nano Banana 2 reference-image edit requests to `/edit` with `image_urls` array, enforce NB2 edit geometry using `aspect_ratio` and `resolution` params, lift Fal edit mode input-image caps to 10 for GPT Image 2 and 14 for Nano Banana 2, and allow aspect-ratio hints in edit mode. (#77295) Thanks @leoge007. - Control UI: show a plain HTML recovery panel when the app module never registers, giving blank dashboard pages a retry path and browser-extension troubleshooting link. Fixes #44107. Thanks @BunsDev. +- Docs: rename the broad tools nav to Capabilities, keep automation and agent coordination as sections, and keep the tools overview focused on tools, skills, and plugins. https://docs.openclaw.ai/tools - Build: enable additional low-churn oxlint rules for promise, TypeScript, and runtime footgun checks. - Build: enable stricter Vitest lint rules for focused, disabled, conditional, hook, matcher, and expectation hazards. diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 65ad8c14e75..5a70a9b936a 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -867,6 +867,66 @@ "source": "/cli/config", "target": "/cli/config" }, + { + "source": "Automation", + "target": "自动化" + }, + { + "source": "Tools, skills, and plugins", + "target": "工具、技能和插件" + }, + { + "source": "Capabilities", + "target": "能力" + }, + { + "source": "Overview", + "target": "概览" + }, + { + "source": "Tools, skills, and plugins overview", + "target": "工具、技能和插件概览" + }, + { + "source": "Tools overview", + "target": "工具概览" + }, + { + "source": "Automation overview", + "target": "自动化概览" + }, + { + "source": "Sub-agents", + "target": "子智能体" + }, + { + "source": "ACP agents", + "target": "ACP 智能体" + }, + { + "source": "Tools and custom providers", + "target": "工具和自定义提供商" + }, + { + "source": "Exec approvals", + "target": "Exec 审批" + }, + { + "source": "Elevated exec", + "target": "提升权限的 Exec" + }, + { + "source": "Sandbox vs tool policy vs elevated", + "target": "沙箱、工具策略和提升权限" + }, + { + "source": "Per-agent sandbox and tool restrictions", + "target": "按 Agent 配置的沙箱和工具限制" + }, + { + "source": "Agents", + "target": "智能体" + }, { "source": "fs-safe Cleanup Plan", "target": "fs-safe Cleanup Plan" diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md index 3c09c5b1174..e686711efec 100644 --- a/docs/automation/cron-jobs.md +++ b/docs/automation/cron-jobs.md @@ -486,7 +486,7 @@ openclaw doctor ## Related -- [Automation & Tasks](/automation) — all automation mechanisms at a glance +- [Automation](/automation) — all automation mechanisms at a glance - [Background Tasks](/automation/tasks) — task ledger for cron executions - [Heartbeat](/gateway/heartbeat) — periodic main-session turns - [Timezone](/concepts/timezone) — timezone configuration diff --git a/docs/automation/cron-vs-heartbeat.md b/docs/automation/cron-vs-heartbeat.md index a5a112fa422..4f2ebf54faa 100644 --- a/docs/automation/cron-vs-heartbeat.md +++ b/docs/automation/cron-vs-heartbeat.md @@ -3,7 +3,7 @@ summary: "Redirect to /automation" title: "Cron vs heartbeat" --- -The decision guide for cron vs heartbeat lives under [Automation and tasks](/automation). +The decision guide for cron vs heartbeat lives under [Automation](/automation). ## Related diff --git a/docs/automation/index.md b/docs/automation/index.md index abee5f81155..ed1a1f29cbc 100644 --- a/docs/automation/index.md +++ b/docs/automation/index.md @@ -1,10 +1,11 @@ --- +doc-schema-version: 1 summary: "Overview of automation mechanisms: tasks, cron, hooks, standing orders, and Task Flow" read_when: - Deciding how to automate work with OpenClaw - Choosing between heartbeat, cron, commitments, hooks, and standing orders - Looking for the right automation entry point -title: "Automation and tasks" +title: "Automation" --- OpenClaw runs work in the background through tasks, scheduled jobs, inferred diff --git a/docs/automation/standing-orders.md b/docs/automation/standing-orders.md index 51bb285ff39..46c9bf2916a 100644 --- a/docs/automation/standing-orders.md +++ b/docs/automation/standing-orders.md @@ -243,7 +243,7 @@ Each program should have: ## Related -- [Automation and tasks](/automation): all automation mechanisms at a glance. +- [Automation](/automation): all automation mechanisms at a glance. - [Cron jobs](/automation/cron-jobs): schedule enforcement for standing orders. - [Hooks](/automation/hooks): event-driven scripts for agent lifecycle events. - [Webhooks](/automation/cron-jobs#webhooks): inbound HTTP event triggers. diff --git a/docs/automation/tasks.md b/docs/automation/tasks.md index 707503940fb..6c0efd411a8 100644 --- a/docs/automation/tasks.md +++ b/docs/automation/tasks.md @@ -9,7 +9,7 @@ sidebarTitle: "Background tasks" --- -Looking for scheduling? See [Automation and tasks](/automation) for choosing the right mechanism. This page is the activity ledger for background work, not the scheduler. +Looking for scheduling? See [Automation](/automation) for choosing the right mechanism. This page is the activity ledger for background work, not the scheduler. Background tasks track work that runs **outside your main conversation session**: ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations. @@ -367,7 +367,7 @@ A sweeper runs every **60 seconds** and handles four things: ## Related -- [Automation & Tasks](/automation) - all automation mechanisms at a glance +- [Automation](/automation) - all automation mechanisms at a glance - [CLI: Tasks](/cli/tasks) - CLI command reference - [Heartbeat](/gateway/heartbeat) - periodic main-session turns - [Scheduled Tasks](/automation/cron-jobs) - scheduling background work diff --git a/docs/docs.json b/docs/docs.json index 13c7482f3ea..71414fa8192 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1179,7 +1179,7 @@ ] }, { - "tab": "Tools & Plugins", + "tab": "Capabilities", "groups": [ { "group": "Overview", @@ -1250,7 +1250,7 @@ ] }, { - "group": "Automation and tasks", + "group": "Automation", "pages": [ "automation/index", "automation/cron-jobs", diff --git a/docs/gateway/heartbeat.md b/docs/gateway/heartbeat.md index 5ea320ded43..e458fdddf11 100644 --- a/docs/gateway/heartbeat.md +++ b/docs/gateway/heartbeat.md @@ -8,7 +8,7 @@ sidebarTitle: "Heartbeat" --- -**Heartbeat vs cron?** See [Automation & Tasks](/automation) for guidance on when to use each. +**Heartbeat vs cron?** See [Automation](/automation) for guidance on when to use each. Heartbeat runs **periodic agent turns** in the main session so the model can surface anything that needs attention without spamming you. @@ -485,7 +485,7 @@ Current heartbeats preserve the shared session's existing runtime model after th ## Related -- [Automation & Tasks](/automation) — all automation mechanisms at a glance +- [Automation](/automation) — all automation mechanisms at a glance - [Background Tasks](/automation/tasks) — how detached work is tracked - [Timezone](/concepts/timezone) — how timezone affects heartbeat scheduling - [Troubleshooting](/automation/cron-jobs#troubleshooting) — debugging automation issues diff --git a/docs/help/faq-first-run.md b/docs/help/faq-first-run.md index 964f0875f2f..8340cd1715e 100644 --- a/docs/help/faq-first-run.md +++ b/docs/help/faq-first-run.md @@ -74,7 +74,7 @@ and troubleshooting see the main [FAQ](/help/faq). In task mode, due timestamps are only advanced after a real heartbeat run completes. Skipped runs do not mark tasks as completed. - Docs: [Heartbeat](/gateway/heartbeat), [Automation & Tasks](/automation). + Docs: [Heartbeat](/gateway/heartbeat), [Automation](/automation). diff --git a/docs/help/faq.md b/docs/help/faq.md index 6467f2408fe..b55a57f8c98 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -258,7 +258,7 @@ lives on the [First-run FAQ](/help/faq-first-run). openclaw cron runs --id --limit 50 ``` - Docs: [Cron jobs](/automation/cron-jobs), [Automation & Tasks](/automation). + Docs: [Cron jobs](/automation/cron-jobs), [Automation](/automation). @@ -344,7 +344,7 @@ lives on the [First-run FAQ](/help/faq-first-run). - **Heartbeat** for "main session" periodic checks. - **Isolated jobs** for autonomous agents that post summaries or deliver to chats. - Docs: [Cron jobs](/automation/cron-jobs), [Automation & Tasks](/automation), + Docs: [Cron jobs](/automation/cron-jobs), [Automation](/automation), [Heartbeat](/gateway/heartbeat). diff --git a/docs/refactor/ingress-core.md b/docs/refactor/ingress-core.md index 30cdf374a51..5a7528f3003 100644 --- a/docs/refactor/ingress-core.md +++ b/docs/refactor/ingress-core.md @@ -335,7 +335,7 @@ Each work package records: - compatibility code is isolated to SDK/core seams - bundled plugins consume ingress projections or generic outcomes directly - plugin production LOC is at least 1,500 net negative against `origin/main` -- core production LOC is <= +1,500, or any excess is paid for while total stays - <= +2,000 +- core production LOC is `<= +1,500`, or any excess is paid for while total + stays `<= +2,000` - representative tests cover redaction, route, command/event, activation, access-group, and channel-specific fallback behavior diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 45b939f78cb..6b414b8c896 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -109,7 +109,7 @@ Use these hubs to discover every page, including deep dives and reference docs t - [PDF tool](/tools/pdf) - [Elevated mode](/tools/elevated) - [Cron jobs](/automation/cron-jobs) -- [Automation & Tasks](/automation) +- [Automation](/automation) - [Thinking + verbose](/tools/thinking) - [Models](/concepts/models) - [Sub-agents](/tools/subagents) diff --git a/docs/tools/index.md b/docs/tools/index.md index ca70607619c..b38557eec6e 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -1,237 +1,178 @@ --- -summary: "OpenClaw tools and plugins overview: what the agent can do and how to extend it" +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 need to configure, allow, or deny tools - You are deciding between built-in tools, skills, and plugins -title: "Tools and plugins" + - You need the right docs entry point for tool policy, automation, or agent coordination +title: "Overview" --- -Everything the agent does beyond generating text happens through **tools**. -Tools are how the agent reads files, runs commands, browses the web, sends -messages, and interacts with devices. +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. -## Tools, skills, and plugins +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). -OpenClaw has three layers that work together: +## 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) and [Creating skills](/tools/creating-skills) | +| 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 PI tool catalog | [Tool Search](/tools/tool-search) | [Tool Search](/tools/tool-search) | + +## Choose tools, skills, or plugins - - A tool is a typed function the agent can invoke (e.g. `exec`, `browser`, - `web_search`, `message`). OpenClaw ships a set of **built-in tools** and - plugins can register additional ones. + + 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 agent sees tools as structured function definitions sent to the model API. + The model only sees tools that survive the active profile, allow/deny + policy, provider restrictions, sandbox state, channel permissions, and + plugin availability. - - A skill is a markdown file (`SKILL.md`) injected into the system prompt. - Skills give the agent context, constraints, and step-by-step guidance for - using tools effectively. Skills live in your workspace, in shared folders, - or ship inside plugins. + + 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 reference](/tools/skills) | [Creating skills](/tools/creating-skills) + Skills can live in a workspace, shared skill directory, managed OpenClaw + skill root, or plugin package. + + [Skills](/tools/skills) | [Creating skills](/tools/creating-skills) | [Skills config](/tools/skills-config) - - A plugin is a package that can register any combination of capabilities: - channels, model providers, tools, skills, speech, realtime transcription, - realtime voice, media understanding, image generation, video generation, - web fetch, web search, and more. Some plugins are **core** (shipped with - OpenClaw), others are **external** (published on npm by the community). + + 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 your own](/plugins/building-plugins) + [Install and configure plugins](/tools/plugin) | [Build plugins](/plugins/building-plugins) | [Plugin SDK](/plugins/sdk-overview) -## Built-in tools +## Built-in tool categories -These tools ship with OpenClaw and are available without installing any plugins: +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). -| Tool | What it does | Page | -| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ | -| `exec` / `process` | Run shell commands, manage background processes | [Exec](/tools/exec), [Exec Approvals](/tools/exec-approvals) | -| `code_execution` | Run sandboxed remote Python analysis | [Code Execution](/tools/code-execution) | -| `browser` | Control a Chromium browser (navigate, click, screenshot) | [Browser](/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Search the web, search X posts, fetch page content | [Web](/tools/web), [Web Fetch](/tools/web-fetch) | -| `read` / `write` / `edit` | File I/O in the workspace | | -| `apply_patch` | Multi-hunk file patches | [Apply Patch](/tools/apply-patch) | -| `message` | Send messages across all channels | [Agent Send](/tools/agent-send) | -| `nodes` | Discover and target paired devices | | -| `cron` / `gateway` | Manage scheduled jobs; inspect, patch, restart, or update the gateway | | -| `image` / `image_generate` | Analyze or generate images | [Image Generation](/tools/image-generation) | -| `music_generate` | Generate music tracks | [Music Generation](/tools/music-generation) | -| `video_generate` | Generate videos | [Video Generation](/tools/video-generation) | -| `tts` | One-shot text-to-speech conversion | [TTS](/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Session management, status, and sub-agent orchestration | [Sub-agents](/tools/subagents) | -| `session_status` | Lightweight `/status`-style readback and session model override | [Session Tools](/concepts/session-tool) | - -For image work, use `image` for analysis and `image_generate` for generation or editing. If you target `openai/*`, `google/*`, `fal/*`, or another non-default image provider, configure that provider's auth/API key first. - -For music work, use `music_generate`. If you target `google/*`, `minimax/*`, or another non-default music provider, configure that provider's auth/API key first. - -For video work, use `video_generate`. If you target `qwen/*` or another non-default video provider, configure that provider's auth/API key first. - -For workflow-driven audio generation, use `music_generate` when a plugin such as -ComfyUI registers it. This is separate from `tts`, which is text-to-speech. - -`session_status` is the lightweight status/readback tool in the sessions group. -It answers `/status`-style questions about the current session and can -optionally set a per-session model override; `model=default` clears that -override. Like `/status`, it can backfill sparse token/cache counters and the -active runtime model label from the latest transcript usage entry. - -`gateway` is the owner-only runtime tool for gateway operations: - -- `config.schema.lookup` for one path-scoped config subtree before edits -- `config.get` for the current config snapshot + hash -- `config.patch` for partial config updates with restart -- `config.apply` only for full-config replacement -- `update.run` for explicit self-update + restart - -For partial changes, prefer `config.schema.lookup` then `config.patch`. Use -`config.apply` only when you intentionally replace the entire config. -For broader config docs, read [Configuration](/gateway/configuration) and -[Configuration reference](/gateway/configuration-reference). -The tool also refuses to change `tools.exec.ask` or `tools.exec.security`; -legacy `tools.bash.*` aliases normalize to the same protected exec paths. - -### Plugin-provided tools - -Plugins can register additional tools. Some examples: - -- [Canvas](/plugins/reference/canvas) — experimental bundled plugin for node Canvas control and A2UI rendering -- [Diffs](/tools/diffs) — diff viewer and renderer -- [LLM Task](/tools/llm-task) — JSON-only LLM step for structured output -- [Lobster](/tools/lobster) — typed workflow runtime with resumable approvals -- [Music Generation](/tools/music-generation) — shared `music_generate` tool with workflow-backed providers -- [OpenProse](/prose) — markdown-first workflow orchestration -- [Tokenjuice](/tools/tokenjuice) — compact noisy `exec` and `bash` tool results - -Plugin tools are still authored with `api.registerTool(...)` and declared in -the plugin manifest's `contracts.tools` list. OpenClaw captures the validated -tool descriptor during discovery and caches it by plugin source and contract, so -later tool planning can skip plugin runtime loading. Tool execution still loads -the owning plugin and calls the live registered implementation. - -[Tool Search](/tools/tool-search) is the compact surface -for large catalogs. Instead of putting every OpenClaw, MCP, or client tool -schema into the prompt, OpenClaw can give the model an isolated Node runtime -with `openclaw.tools.search`, `openclaw.tools.describe`, and -`openclaw.tools.call`. Calls still flow back through the Gateway, so tool -policy, approvals, hooks, and session logs remain authoritative. - -## Tool configuration - -### Allow and deny lists - -Control which tools the agent can call via `tools.allow` / `tools.deny` in -config. Deny always wins over allow. - -```json5 -{ - tools: { - allow: ["group:fs", "browser", "web_search"], - deny: ["exec"], - }, -} -``` - -OpenClaw fails closed when an explicit allowlist resolves to no callable tools. -For example, `tools.allow: ["query_db"]` only works if a loaded plugin actually -registers `query_db`. If no built-in, plugin, or bundled MCP tool matches the -allowlist, the run stops before the model call instead of continuing as a -text-only run that could hallucinate tool results. - -### Tool profiles - -`tools.profile` sets a base allowlist before `allow`/`deny` is applied. -Per-agent override: `agents.list[].tools.profile`. - -| Profile | What it includes | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | All core and optional plugin tools; unrestricted baseline for broader command/control access | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `minimal` | `session_status` only | +| 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` | [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 PI 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) | -`tools.profile: "messaging"` is intentionally narrow for channel-focused -agents. It leaves out broader command/control tools such as filesystem, runtime, -browser, canvas, nodes, cron, and gateway control. Use `tools.profile: "full"` -as the unrestricted baseline for broader command/control access, then trim -access with `tools.allow` / `tools.deny` when needed. +Tool Search is an experimental PI-agent surface. Codex harness runs use +Codex-native code mode, native tool search, deferred dynamic tools, and nested +tool calls instead of `tools.toolSearch`. -`coding` includes lightweight web tools (`web_search`, `web_fetch`, `x_search`) -but not the full browser-control tool. Browser automation can drive real -sessions and logged-in profiles, so add it explicitly with -`tools.alsoAllow: ["browser"]` or a per-agent -`agents.list[].tools.alsoAllow: ["browser"]`. +## Plugin-provided tools - -Configuring `tools.exec` or `tools.fs` under a restrictive profile (`messaging`, `minimal`) does not implicitly widen the profile's allowlist. Add explicit `tools.alsoAllow` entries (for example `["exec", "process"]` for exec, or `["read", "write", "edit"]` for fs) when you want a restrictive profile to use those configured sections. OpenClaw logs a startup warning when a config section is present without a matching `alsoAllow` grant. - +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. -The `coding` and `messaging` profiles also allow configured bundle MCP tools -under the plugin key `bundle-mcp`. Add `tools.deny: ["bundle-mcp"]` when you -want a profile to keep its normal built-ins but hide all configured MCP tools. -The `minimal` profile does not include bundle MCP tools. +Common plugin-provided tools include: -Example (broadest tool surface by default): +- [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 -```json5 -{ - tools: { - profile: "full", - }, -} -``` +## Configure access and approvals -### Tool groups +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, owner-only gating, or plugin availability. -Use `group:*` shorthands in allow/deny lists: +- [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. -| Group | Tools | -| ------------------ | --------------------------------------------------------------------------------------------------------- | -| `group:runtime` | exec, process, code_execution (`bash` is accepted as an alias for `exec`) | -| `group:fs` | read, write, edit, apply_patch | -| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | -| `group:memory` | memory_search, memory_get | -| `group:web` | web_search, x_search, web_fetch | -| `group:ui` | browser, canvas when the bundled Canvas plugin is enabled | -| `group:automation` | heartbeat_respond, cron, gateway | -| `group:messaging` | message | -| `group:nodes` | nodes | -| `group:agents` | agents_list, update_plan | -| `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | All built-in OpenClaw tools (excludes plugin tools) | +## Extend capabilities -`sessions_history` returns a bounded, safety-filtered recall view. It strips -thinking tags, `` scaffolding, plain-text tool-call XML -payloads (including `...`, -`...`, `...`, -`...`, and truncated tool-call blocks), -downgraded tool-call scaffolding, leaked ASCII/full-width model control -tokens, and malformed MiniMax tool-call XML from assistant text, then applies -redaction/truncation and possible oversized-row placeholders instead of acting -as a raw transcript dump. +Choose the extension path by the job you need OpenClaw to do: -### Provider-specific restrictions +- 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). +- Package reusable workflow material with + [Skill workshop](/plugins/skill-workshop) when the workflow belongs in a + plugin-distributed skill bundle. +- Use [Plugin SDK](/plugins/sdk-overview) and [Plugin manifest](/plugins/manifest) when you need implementation contracts. -Use `tools.byProvider` to restrict tools for specific providers without -changing global defaults: +## Troubleshoot missing tools -```json5 -{ - tools: { - profile: "coding", - byProvider: { - "google-antigravity": { profile: "minimal" }, - }, - }, -} -``` +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 PI 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 +- [Tool Search](/tools/tool-search) for compact PI tool catalog discovery diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md index e8e209ccbca..0154035eac6 100644 --- a/docs/tools/lobster.md +++ b/docs/tools/lobster.md @@ -360,6 +360,6 @@ One public example: a "second brain" CLI + Lobster pipelines that manage three M ## Related -- [Automation & Tasks](/automation) - scheduling Lobster workflows +- [Automation](/automation) - scheduling Lobster workflows - [Automation Overview](/automation) - all automation mechanisms - [Tools Overview](/tools) - all available agent tools