Host support: OpenClaw — compatible bundles first, native plugin and ClawHub skill tiers separately

[ScriptedAlchemy]

Scope / research status

P2 feature expansion. Research date 2026-09-06; Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Official OpenClaw documents read; no gateway, plugin install or native invocation was executed.

Correction to the initial Ponytail-based classification: OpenClaw is not limited to ClawHub skills. Current docs describe native in-process plugins and compatible Agent Plugins/Codex/Claude/Cursor bundles. These have materially different capabilities and trust boundaries; one host issue should name the tiers explicitly.

Authoritative references

• Compatible bundle formats and supported/detected-only features
• Native manifest schema and static MCP declarations
• Plugin system overview
• Native SDK entry points
• Plugin installation/management CLI
• Skill loading and gating
• ClawHub distribution
• Agent Plugins specification

Pin actual host/parser/SDK versions before implementation. A compatibility badge or successful manifest parse is not proof that every declared hook executes.

Tier A: prove existing composite/portable output

Compatible bundles use their own manifests, not openclaw.plugin.json. Current docs map skills and supported MCP tools; some Claude/Cursor commands become skills. In contrast, Claude hooks/hooks.json automation and several agent/rule/output-style components are detected but not executed. Native OpenClaw hook packs require OpenClaw's own HOOK.md plus JS/TS handler layout.

Proposed first acceptance artifact:

composite-root/
  plugin.json
  mcp.json                  # only when a server is declared
  skills/review/SKILL.md
  mcp/example.mjs

openclaw plugins install ./composite-root
openclaw plugins install ./example-plugin.tgz
openclaw plugins list
openclaw plugins inspect example-plugin
openclaw gateway restart

Inspect the detected format and effective capabilities. Verify the gateway restart/session boundary rather than promising automatic live adoption. Test all candidate manifests present in a composite and determine which wins; never infer that OpenClaw simultaneously combines their semantics.

Tier B: native plugin only where required

A native plugin's root openclaw.plugin.json is inspected before executable code is loaded. It declares identity/configuration metadata; runtime entry points and registration belong to the documented package/SDK contract, not arbitrary executable properties added to the manifest.

Illustrative minimal manifest:

{
  "id": "example-plugin",
  "configSchema": {"type":"object","additionalProperties":false,"properties":{}},
  "skills": ["./skills"]
}

Only add a compiled native entry when the application needs native-only callbacks/tools. Reuse canonical schemas and operation functions, but verify host-provided SDK imports and callback/result semantics. Do not bundle an entire OpenClaw runtime into every plugin, loosen standalone external policy globally, or execute native registration just to inspect metadata.

Native static MCP declarations can reuse canonical executable records. In operator configuration the documented shape is mcp.servers, and transport selection is explicit:

{
  "mcp": {
    "servers": {
      "example": {
        "command": "node",
        "args": ["/absolute/installed-plugin/mcp/example.mjs"]
      }
    }
  }
}

Bundled/native manifest MCP configuration and operator config are distinct layers. User overrides and tool policy remain authoritative. For remote endpoints explicitly choose the supported transport; a bare URL must not accidentally select a different legacy transport. Credentials stay in native secret/environment mechanisms.

Tier C: ClawHub skill distribution

A skill contains SKILL.md and supporting files. The host handles discovery, gating and activation. Ponytail generates separate skill packages for ClawHub; that does not prove a single composite npm tarball automatically publishes a skill collection there.

Keep skill publication optional and explicit. Validate the current ClawHub CLI/schema before emitting publish instructions, preserve package provenance/version, and never publish or overwrite a skill as part of an ordinary Agent Bundle build. A content-only package must start no native plugin runtime.

Composite / security requirements

• Represent supported versus detected-but-ignored components in inspection. A Claude hook process must not be claimed to work merely because the bundle is accepted.
• Preserve PLUGIN_ROOT/PLUGIN_DATA separation and native path containment. Do not write to installed code or purge unrelated gateway data.
• Namespaced/sanitized MCP names can collide or be truncated. Test native names against canonical operation IDs and expose the mapping without creating duplicate operations.
• Native plugins execute trusted code; compatible bundles can still launch MCP processes. Manifest/config validation and gateway enablement do not grant arbitrary tool approvals.
• Reuse AB portable output where possible; add a new native adapter only for proven requirements. Do not disable custom-target composite isolation without Composite conformance: test cross-host auto-discovery and precedence, not only file collisions #651 conformance tests.

Acceptance

• Pin host version, detected manifest precedence and supported bundle subset.
• Skills-only artifact loads with no synthetic MCP, Flight, SQLite or native SDK entry.
• Existing portable MCP artifact installs from directory and actual archive, then completes a tool call without the source checkout.
• Unsupported foreign hooks/agents/rules are diagnosed as unsupported/detected-only, never silently advertised as runnable.
• Native-only fixture registers exactly the declared functionality, with correct callback cancellation/error/lifetime semantics.
• Config overrides, disabled plugins, permission gates and remote transport choices remain native-authoritative.
• Test canonical operation naming versus native sanitization collisions.
• Verify restart/update/remove and receipt-owned cleanup preserve user data and unrelated configuration.
• Test reversed composite target ordering and forbidden foreign discovery.
• Capture native successful execution separately from static inspection and ClawHub publication validation.

No gateway deployment, model/provider orchestration, new messaging channels, memory engine, unrestricted native UI, or automatic external publishing is required.

[ScriptedAlchemy]

Resolved by #721 (72a8857ebe).

OpenClaw — observed Agent Plugins 1.0.0; docs retrieved 2026-09-06. Supported: the emitted package installs as one plugin.

Surface	State	Evidence
manifest	supported	2026-09-06: https://docs.openclaw.ai/plugins/bundles names the marker "plugin.json at the package root, per the open Agent Plugins 1.0.0 standard", requires strict JSON and a non-empty name, and states "other manifest fields are optional and unknown fields are ignored".
skills	supported	2026-09-06: https://docs.openclaw.ai/plugins/bundles states "Immediate child directories of skills/ that contain a SKILL.md load as skills" — the exact flat layout this projection emits — and https://docs.openclaw.ai/tools/skills requires at minimum a name and description, both of which it emits.
mcp	supported	2026-09-06: https://docs.openclaw.ai/plugins/bundles states mcp.json "must declare the 1.0.0 $schema and an mcpServers object only; stdio, streamable-http, and legacy sse transports are supported" — the document this projection emits.
placeholders	supported	2026-09-06: https://docs.openclaw.ai/plugins/bundles states stdio servers launch with PLUGIN_ROOT and PLUGIN_DATA in their environment and that "${PLUGIN_ROOT} and ${PLUGIN_DATA} placeholders expand in args, env values, and cwd in a single pass", with a stdio command required to be "a bare executable name or a ./-relative path inside the plugin" — the reserved behavior of Agent Plugins 1.0.0 §9.1 and the containment this projection already emits.
hooks	unavailable	2026-09-06: https://docs.openclaw.ai/plugins/bundles supports bundle hooks only as OpenClaw hook packs (HOOK.md plus handler.ts or handler.js) and lists hooks/hooks.json as detect-only; Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document at all.

Paths it reads: mcp.json, plugin.json, skills.
Per-file precedence: openclaw.plugin.json (manifest, skills, mcp, placeholders), .claude-plugin/plugin.json (manifest, skills, mcp, placeholders), .codex-plugin/plugin.json (manifest, skills, mcp, placeholders), .cursor-plugin/plugin.json (manifest, skills, mcp, placeholders).
Install: openclaw plugins install <plugin directory>.

Every row above is pinned to that client's own documentation on the date shown, is validated on every build, and renders in INSTALL.md and the generated hosts reference. A surface recorded unavailable or degraded names exactly what the client would need; no unsupported feature is projected silently.