OpenClaw Main Adds the Agent Plugins 1.0 Portable Bundle Format

OpenClaw has merged support for the new Agent Plugins 1.0 package format into main. A conforming bundle can carry Agent Skills and MCP server definitions in one portable directory, reducing the need to repack the same components for every agent client.

That is a genuine interoperability improvement. It is also a new path for loading instructions and launching external processes, so “portable” must not be mistaken for “trusted.”

Availability boundary: the work is merged on main; operators should not assume a current packaged release supports it until the relevant release notes say so.

What OpenClaw now recognises

The Agent Plugins specification defines a root plugin.json, optional skills under skills/, and optional MCP servers in mcp.json. PR #120115 maps that structure into OpenClaw’s existing bundle system rather than creating a separate plugin runtime.

OpenClaw’s merged implementation:

• recognises a root plugin.json after native and client-specific formats in detection precedence;
• requires a valid JSON manifest with a name while tolerating unknown fields;
• loads immediate skills/ children that contain SKILL.md;
• validates MCP entries independently so one bad server does not prevent valid skills from loading;
• supports stdio, Streamable HTTP and legacy HTTP+SSE MCP transports;
• supplies PLUGIN_ROOT and persistent PLUGIN_DATA paths to stdio servers;
• reports the format as agent (Agent Plugins) in plugin inspection surfaces.

The precedence rule matters. A package that also carries a richer Claude, Cursor, Codex or native OpenClaw marker continues to use that more specific format rather than silently changing behaviour because a portable manifest was added.

OpenClaw gets a narrow extension namespace

A follow-up, PR #120214, reads extensions["ai.openclaw"].activation. That lets a portable package provide OpenClaw activation hints without maintaining an entirely separate client manifest.

The namespace is intentionally narrow. Unknown namespaces and unknown fields are ignored. Provider, channel and configuration-schema declarations remain outside the bundle trust model because these packages do not receive an in-process runtime.

Interpretation: OpenClaw is adopting the common packaging floor while keeping platform-specific authority constrained. That is the right trade-off. Cross-client layout portability should not automatically grant every client-specific capability.

The security review operators still need

An Agent Plugin may contain two very different things:

1. Skills, which can influence model behaviour and point at local scripts or reference material.
2. MCP servers, which may start a subprocess or connect to a network service and expose tools.

Review both before installation. Check the manifest, every SKILL.md, executable files, MCP command and arguments, environment-variable use, working directory, network endpoints and requested data paths. Treat PLUGIN_DATA as durable plugin-owned storage and include it in retention and removal decisions.

A standards-compliant manifest proves structural compatibility, not safety, provenance or least privilege. The Agent Plugins specification deliberately leaves installation, permissions and client UX to each host.

Migration advice for plugin authors

Authors targeting several clients can now put portable skills and MCP definitions in the standard locations, then use ai.openclaw only for activation hints that OpenClaw genuinely needs. Avoid duplicating portable content inside a client-specific tree unless a client requires different behaviour.

Test these cases before distribution:

• installation from a directory and the archive format you publish;
• skill discovery when another child directory lacks SKILL.md;
• one invalid MCP entry alongside a valid skill;
• PLUGIN_ROOT and PLUGIN_DATA expansion without embedding machine-specific paths;
• uninstall and reinstall while preserving or deliberately clearing plugin data;
• format precedence when client-specific markers coexist with plugin.json.

Bottom line

Agent Plugins support makes OpenClaw a better citizen in a multi-client ecosystem. The useful abstraction is a shared package layout, not shared trust. Adopt it for portability, keep OpenClaw-specific metadata narrow, and review every skill and MCP process with the same care you would apply to native plugin code.