2026 OpenClaw Skills & Plugins in Practice:
Load Order, Allowlists & Gateway Extensions

1. Mental model: skills vs plugins vs gateway core

Skills

Skills are usually small, declarative bundles (markdown + optional schemas) that teach the model when to call a tool and what arguments look like. They should be cheap to load, easy to audit, and safe to sync from git.

Plugins

Plugins ship executable logic: HTTP handlers, background jobs, custom auth hooks, or bridges to messengers. They run in the same trust domain as the gateway process—treat them like server-side code.

Gateway core

The gateway owns sockets, auth, rate limits, logging, and the lifecycle of plugins. Extensions should register explicitly; implicit auto-discovery is convenient in dev and dangerous in production.

2. Skill resolution & load priority (practical order)

Most deployments resolve skills from several directories. When two files expose the same skill ID, the higher-priority source wins and the other is silently shadowed—exactly the kind of bug that looks like “the model forgot a tool.”

Example resolution stack (newest / most specific wins)

• • 1. Per-workspace .openclaw/skills (or your team’s canonical subfolder)
• • 2. User-level skills path (home directory)
• • 3. Installation / bundled defaults under the OpenClaw prefix

Repro: duplicate skill ID

Goal: prove which file wins.

• • 1. Create two skill files with the same id but different descriptions.
• • 2. Restart only the gateway (not the whole shell) and call openclaw doctor --verbose if available, or inspect startup logs for “loaded skills.”
• • 3. Remove the higher-priority copy; confirm the description flips.

3. Allowlists: shrinking your blast radius

Allowlists belong in three layers: filesystem (which plugin roots may exist), runtime (which routes/tools are registered), and network (egress to APIs and webhooks).

Start strict in production: enumerate plugins in config, disable glob importers, and require explicit version pins for anything that mutates disk or runs subprocesses.

4. Gateway extensions: registration, ordering, and rollback

Registration

Plugins should export a manifest (name, semver, permissions, routes). The gateway should reject unknown permission classes rather than warn-only.

Ordering

When two plugins register middleware on the same path, last-writer-wins is common. Document an explicit priority integer in your internal plugins and sort deterministically.

Upgrade / rollback playbook

• • 1. Snapshot OPENCLAW_STATE_DIR and your config directory to a tarball with a dated name.
• • 2. Install the candidate build in a separate prefix or git worktree.
• • 3. Point a staging LaunchAgent plist at the candidate binary and a different state dir; run synthetic traffic.
• • 4. Swap the plist ProgramArguments symlink or path; launchctl bootout / bootstrap; verify health checks.
• • 5. Rollback = restore tarball + previous plist + previous binary path.

5. Multi-workspace isolation on one Mac

Running multiple gateways for different clients or repos on the same machine requires separate state directories, separate listening ports, and separate plugin/skill roots. Sharing a state dir causes lock contention, mixed credentials, and “ghost” sessions.

6. Permission & error matrix (macOS + gateway)

7. FAQ

Should skills and plugins live in the same git repo?

Skills yes; plugins only if you fully trust every contributor with production gateway privileges. Otherwise split repos and promote plugin builds via signed artifacts.

How do I test a plugin safely?

Use a disposable state dir, loopback-only bind, synthetic credentials, and an outbound firewall profile that denies wide egress except your mock server.

What about cross-border latency?

Keep hot skills local; lazy-load heavy reference docs; pin tool calls server-side close to the APIs they wrap. Long RTT hurts interactive loops more than raw throughput.