skip to content

Extension Layer

The three ways to give OpenClaw new abilities: Markdown skills, code plugins loaded into the Gateway, and external MCP servers. Interviewers ask which to pick and what each one is trusted with.

part ofAI coding toolsread it →
on this pageshow

explore

questions

17

In OpenClaw, what is the difference between a skill and a plugin, and when is a skill enough?

level: juniorimportance: must knowfreq 14%

answer

  1. instructions versus code
  2. SKILL.md goes into the prompt
  3. plugins load inside the Gateway process
  4. new channel or provider needs code
  5. a skill cannot block a tool call

basics

~20 s

An OpenClaw skill is SKILL.md instructions for tools the agent already has; a plugin is code the Gateway loads in-process to add tools, channels, providers or hooks. A skill is enough when existing tools can do the work.

solid answer

~50 s

A skill is a folder with a `SKILL.md` file: YAML frontmatter plus Markdown instructions that OpenClaw lists in the agent's prompt when the skill is eligible. It adds no code and no new tools; it tells the model how and when to use `exec`, `web_fetch`, `browser` or a CLI that is already installed. A plugin is a code package (a native one ships `openclaw.plugin.json` plus a runtime module) that the Gateway imports into its own process, where it can register agent tools, a messaging channel, a model provider, typed hooks and services, and ship skills of its own. So a skill is enough when the capability exists and the agent needs a workflow or rubric. You need a plugin for a new chat platform, a new provider, a typed tool with a schema, or a hook that must block or rewrite something, because instructions only shape what the model tends to do.

go deeper

for a junior

Recall the one-line split: a skill is SKILL.md instructions for tools the agent already has, a plugin is code that adds tools, channels, providers or hooks.

for a middle

Explain where each one lands: eligible skills are listed in the agent's prompt, plugins are imported into the Gateway through a manifest and runtime module, and a plugin can ship its own skills.

for a senior

Draw the guidance-versus-enforcement line: enforcing layers such as tool policy, approvals, the sandbox or a plugin hook stop an action, and both extension types are trusted code to review.

for a principal

Frame the choice as cost and blast radius: a skill when tools exist, an external tool server when the integration already is one, and a reviewed plugin only when the Gateway itself must change.

## Two extension points that do different jobs OpenClaw's own overview splits its capabilities three ways: **tools** are callable actions (`exec`, `browser`, `web_search`, `message`), **skills** teach the agent how to work, and **plugins** add runtime capabilities such as tools, providers, channels, hooks and packaged skills. The question "skill or plugin?" is really "does the agent lack *knowledge* or lack a *capability*?" ## What a skill is A **skill** is a directory containing a `SKILL.md` file: YAML frontmatter (at minimum a `name` and a `description`) and a Markdown body of instructions. OpenClaw discovers skills from several roots, filters them at load time (for example, a skill can require a binary or an environment variable), and injects a compact list of eligible skills into the system prompt so the model can read the full instructions when a task matches. - A skill contains **no runtime code that OpenClaw loads**. It cannot register a tool, open a socket or listen to a chat platform. - It works through tools the agent already has: it might say "run `gh pr list` with `exec`, then summarise" or "fetch the status page with `web_fetch`". - Writing one is cheap: edit Markdown, and the skills watcher picks up `SKILL.md` changes on a later turn. ## What a plugin is A **plugin** is a code package the Gateway loads. A native OpenClaw plugin ships an `openclaw.plugin.json` manifest plus a TypeScript or JavaScript runtime module; OpenClaw also recognises compatible bundle layouts (Agent Plugins, Codex, Claude and Cursor) and maps their skills, commands and hook packs into its plugin inventory. A native plugin can: - register agent tools with `api.registerTool(...)`, with a typed parameter schema; - add a **messaging channel** or a **model provider** (many of OpenClaw's own channels and providers are themselves plugins); - register typed lifecycle hooks with `api.on(...)`, for example `before_tool_call`; - run services, Gateway methods and CLI commands, and list `skills` directories that load while the plugin is enabled. Native plugins run **in-process with the Gateway** and are not sandboxed, so a loaded plugin has the same trust boundary as core code. ## Choosing between them | Need | Skill enough? | Why | | --- | --- | --- | | A repeatable workflow with tools the agent has | Yes | Instructions are the missing piece | | A review rubric or house style for a task | Yes | Pure guidance | | A chat platform OpenClaw does not ship | No | Needs a channel adapter in code | | A new model or speech provider | No | Needs provider code and auth setup | | A typed tool with validated parameters | No | Tools are registered by code | | Stopping a risky call before it runs | No | Needs an enforcing layer | OpenClaw's own guidance matches this: use a skill "when the agent already has the tools it needs", and a plugin when the capability has code, credentials, lifecycle hooks, manifest metadata or installable packaging. A third option sits beside both: an external MCP server, connected under `mcp.servers`, contributes tools from a separate process and is covered with the MCP connection material. ## Guidance versus enforcement The most common confusion is treating a skill as a control. A line in `SKILL.md` such as "never delete files" shapes what the model tends to do; it does not stop anything. What can actually stop a call is code or configuration the Gateway enforces: 1. tool policy (`tools.allow` / `tools.deny`) decides which tools the model sees; 2. exec approvals and the sandbox decide whether and where a command runs; 3. a plugin's `before_tool_call` hook can return `block: true` or request approval. ## Neither one is harmless It is tempting to call skills "safe because they are only Markdown". OpenClaw's security guidance says the opposite: treat skill folders as trusted code and restrict who can modify them, because a skill's instructions can steer the agent to run commands or send data with the tools it holds. Plugins are a step further: installing one runs executable code inside the Gateway, so a malicious plugin is equivalent to arbitrary code execution in the OpenClaw process. Pick the smallest mechanism that does the job, and review either one before you trust it.

  • Can an OpenClaw plugin and a skill be combined?
    Yes. A native plugin can list skill directories in the `skills` field of `openclaw.plugin.json`, and those skills load while the plugin is enabled, so a plugin can register a tool and ship the instructions for using it. Plugin skills sit at the lowest load precedence, so a same-named workspace, managed or bundled skill overrides them.
  • Is a skill safe to install unread because it is only Markdown?
    No. A skill's instructions can steer the agent to run commands with `exec` or send data with tools it already holds, and OpenClaw's security guidance says to treat skill folders as trusted code. What limits the damage is tool policy, exec approvals and the sandbox, not the file format.

A skill is a recipe card handed to a cook who already has the kitchen's appliances; a plugin is a new appliance wired into the kitchen itself. A recipe changes how the cook works, but it cannot add an oven or lock the knife drawer.

  • A skill can add a new tool or chat channel to OpenClaw.
  • Skills are plain Markdown, so installing one unread is harmless.
  • A rule written in a SKILL.md blocks the agent from calling a tool.
  • OpenClaw plugins run sandboxed, apart from the Gateway process.
  • Supporting a new model provider only needs a skill describing its API.
open as a page

What is an OpenClaw skill, and where does `openclaw skills install @owner/<slug>` put the skill it fetches from ClawHub?

level: juniorimportance: must knowfreq 14%

basics

~20 s

An OpenClaw skill is a folder holding a SKILL.md: YAML frontmatter with a name and description, then Markdown instructions that teach the agent a task. openclaw skills install @owner/<slug> copies it from ClawHub into the active workspace's skills folder; --global targets the shared directory.

open as a page

In OpenClaw, how do you add a local stdio MCP server, such as a database tool server, and prove it actually works?

level: middleimportance: must knowfreq 12%

basics

~20 s

Run openclaw mcp add <name> --command <exe> --arg <arg>, or write an mcp.servers entry with command, args, env and cwd, then run openclaw mcp doctor <name> --probe, which checks the definition and opens a live connection that lists the server's tools.

open as a page

An OpenClaw assistant that also answers strangers gains a database MCP server; do its tools bypass tool policy, and how do you scope them?

level: seniorimportance: must knowfreq 10%

basics

~20 s

No. MCP tools become OpenClaw tools under the bundle-mcp plugin id, named server__tool, and pass the same tool profile, allow and deny lists, per-sender limits and sandbox gate as built-in tools; filter the server's tools and deny them to strangers.

open as a page

In OpenClaw, what is the difference between openclaw mcp serve and openclaw mcp add, and which side is the MCP server in each?

level: juniorimportance: should knowfreq 8%

basics

~20 s

openclaw mcp add saves a third-party MCP server under mcp.servers so OpenClaw's agents can use its tools. openclaw mcp serve makes OpenClaw itself a stdio MCP server that another client spawns to read and reply to its channel conversations.

open as a page

In OpenClaw's mcp.servers, how do you configure a hosted HTTP MCP server, and which transport does it get if you omit one?

level: middleimportance: should knowfreq 6%

basics

~20 s

Give the mcp.servers entry a url and set transport to streamable-http, because an entry with no transport uses sse. Authenticate with auth set to oauth plus openclaw mcp login, or with headers fed from an environment variable, then probe it.

open as a page

How does `openclaw plugins install` treat ClawHub, npm, git and local `--link` sources differently?

level: middleimportance: should knowfreq 8%

basics

~20 s

In OpenClaw 2026.9.9, clawhub: and the official catalog are trusted sources; other npm packages, git repositories and local paths are arbitrary sources that warn first and need --force in noninteractive installs. --link points at a local directory without copying it.

open as a page

A ClawHub skill for OpenClaw needs an API key and a binary your host lacks; what happens at load, and how do you fix it?

level: middleimportance: should knowfreq 8%

basics

~20 s

OpenClaw gates skills at load time: if a requires.bins binary is missing from PATH or a requires.env variable is unset, the skill is ineligible and never reaches the agent's prompt. Install the binary, supply the key, then start a new session.

open as a page

After installing an OpenClaw plugin, `openclaw plugins list` shows it but live chats never use it; how do you find out why?

level: seniorimportance: should knowfreq 6%

basics

~20 s

In OpenClaw 2026.9.9, plugins list reads cold config and manifests, not the running Gateway. Confirm the Gateway with openclaw gateway status --deep --require-rpc, check registrations with plugins inspect <id> --runtime --json, then check allowlist, enablement and hook permissions, and trigger the feature.

open as a page

Two OpenClaw skills are both named `github`, one in the workspace `skills/` folder and one installed with `--global`; which does the agent get, and why?

level: seniorimportance: should knowfreq 5%

basics

~20 s

The workspace copy. OpenClaw keeps one skill per name and takes it from the highest-precedence source: the workspace skills folder first, the shared managed directory that --global writes to below it, bundled skills lower, and skills.load.extraDirs plus plugin skills last.

open as a page

For a small team's OpenClaw Gateway connected to a hosted issue-tracker MCP server, would you configure shared or per-requester OAuth, and why?

level: principalimportance: should knowfreq 4%

basics

~20 s

Shared OAuth, the default, suits one operator: every allowed caller acts through the account saved by openclaw mcp login. Per-requester gives each sender their own account and attribution, but needs gateway.publicOrigin and bearer sign-in links, so it fits only a mutually trusting team.

open as a page

As the lead for a team's OpenClaw Gateway, what rules would you set for which third-party plugins may be installed and enabled?

level: principalimportance: should knowfreq 5%

basics

~20 s

Treat every OpenClaw plugin as code running with the Gateway's privileges. In 2026.9.9 that means an exclusive plugins.allow list in reviewed config, pinned versions, a security.installPolicy check, re-review when an update declares new capabilities, and a skill or MCP server whenever one would do.

open as a page

You run one OpenClaw Gateway for a small team; what rule do you set for installing third-party ClawHub skills, and which OpenClaw controls enforce it?

level: principalimportance: should knowfreq 6%

basics

~20 s

Treat every third-party skill as untrusted code: read it, run openclaw skills verify, pin a version and install it only where needed. Enforce that with security.installPolicy, which can allow, warn or block each install, plus agent allowlists, sandboxing and tool policy.

open as a page

Your team needs OpenClaw on a chat platform it does not support; what does a channel plugin's `openclaw.plugin.json` declare, and what does the plugin own?

level: middleimportance: nice to knowfreq 4%

basics

~20 s

A channel plugin's openclaw.plugin.json declares its id, a configSchema, the channel ids it owns under channels, and a channelConfigs schema for channels.<id>. The plugin owns accounts, DM policy, pairing, threading and outbound sends; core keeps the shared message tool.

open as a page

In OpenClaw, how do `agents.defaults.skills` and `agents.entries.*.skills` decide which skills each agent sees, and what do they leave unprotected?

level: middleimportance: nice to knowfreq 4%

basics

~20 s

agents.defaults.skills sets a baseline that agents without their own list inherit; a non-empty agents.entries.<id>.skills replaces it entirely, and an empty list hides every skill. Omitting both leaves skills unrestricted. Allowlists filter what an agent sees, not what its exec tool can run.

open as a page

For Codex runs in OpenClaw, how are MCP tool calls approved, and what does openclaw mcp configure --approval change?

level: seniorimportance: nice to knowfreq 3%

basics

~10 s

By default, Codex MCP approvals follow the session's permission posture: full permission never prompts, stricter postures check unannotated tools. openclaw mcp configure <server> --approval auto|prompt|approve writes codex.defaultToolsApprovalMode and overrides that default for one server.

open as a page

In an OpenClaw plugin, how does a `before_tool_call` hook registered with `api.on` block a tool call or require approval?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

In an OpenClaw plugin, api.on("before_tool_call", handler, { matcher, priority }) gates tool calls. Returning { block: true } stops the call and skips lower-priority handlers; returning requireApproval pauses the run for a user decision; a handler that throws or times out blocks it.

open as a page