2026 OpenClaw Skills on Remote Mac M4 Pro:
ClawHub Community Installs, Private Archive Upload, Disk Layering, and Gateway Troubleshooting

Once OpenClaw Gateway is running on a remote Mac mini M4 Pro, the next capability gap is rarely another channel plugin. It is Skills: the callable tool surface your Agent uses for file work, browser automation, shell execution, and team-specific workflows. In the 2026.5.x line, Skills moved from an informal folder convention to a first-class install model with built-in packs, ClawHub community catalogs, and an explicit private archive upload path gated by skills.install.allowUploadedArchives. Teams that treat Skills like Plugins—or skip disk planning—usually discover the failure only after Gateway restarts loop or a zip upload silently lands in the wrong workspace tree.

This article is for operators who already completed base install and daemon onboarding. You will get a Skills versus Plugins boundary map, a 2026.5.x pre-flight checklist, a built-in enablement matrix, ClawHub install and pin commands, private zip upload with security boundaries, remote Mac disk layering with M4 and M4 Pro watermarks, a symptom matrix, a real small-team ramp case, and a 12-step runbook. Pricing is on the NOVAKVM rental pricing page; orders go through the order page; SSH and backup policy lives in the help center. Cross-read the multi-workspace isolation piece, the 2026.5.x external plugin npm piece, the first-run closure, and the install.sh and disk piece. Commands follow upstream docs—reopen the repository after every release.

[ SECTION_01 ] // BOUNDARY_MAP Skills versus Plugins: the boundary that breaks production teams

The most common post-install mistake is installing a Skill through the Plugin CLI—or enabling a channel Plugin when the Agent actually needs a Skill pack. They share a Gateway host and sometimes overlap in naming, but they solve different problems.

• Plugins extend ingress and sidecar services: Telegram, Discord, WeChat ClawBot, mail bridges, and npm-packaged channel adapters attach to Gateway as Plugins. They move messages in and out; they do not define what tools the Agent can call mid-session.
• Skills extend Agent capability: file read/write, browser control, structured API wrappers, internal runbooks packaged as callable tools. Skills load into the Agent runtime and appear in tool lists during conversation.
• Different install roots: Plugins typically live under plugin cache paths documented in the 2026.5.x external-plugin note. Skills land under ~/.openclaw/skills/ with sub-trees for built-in, ClawHub, and uploaded archives.
• Different upgrade blast radius: a Plugin upgrade can drop a channel. A Skill upgrade can change tool schemas and break existing Agent prompts that assumed old argument shapes.
• Different security posture: Plugins often hold OAuth tokens for messaging surfaces. Skills may execute shell commands or read local files—uploaded archives need an explicit allow flag and workspace scoping.

Rule of thumb: if the problem is “my bot cannot receive Telegram messages,” fix Plugins. If the problem is “my Agent cannot run our internal checklist tool,” fix Skills. Mixing the two CLI surfaces wastes an afternoon and sometimes corrupts shared cache directories.

[ SECTION_02 ] // PREFLIGHT 2026.5.x Skills model changes and pre-flight checks

Before installing any Skill pack, confirm four baselines on the remote Mac. Skipping them produces errors that look like corrupt zips but are actually version or permission mismatches.

• OpenClaw major: Skills install semantics trace to 2026.5.x config schema. Run openclaw --version and match the README Skills section for that tag.
• Gateway health: curl -fsS http://127.0.0.1:18789/health must return ok before install mutations. A half-dead Gateway mid-install leaves partial skill trees on disk.
• Doctor pass: openclaw doctor should report clean Node path, writable ~/.openclaw, and launchd context. Skills install runs under the same user as Gateway—PATH drift breaks post-install hooks.
• Workspace context: if you run multiple workspaces, decide which workspace owns the Skill enable list now. Cross-workspace installs without --workspace are the top support pattern for “skill installed but Agent cannot see it.”

novakvm@m4pro-sg-01:~$ openclaw --version
openclaw 2026.5.2 (stable)

novakvm@m4pro-sg-01:~$ curl -fsS http://127.0.0.1:18789/health
{"status":"ok","gateway":"18789","skills":{"builtin":12,"clawhub":0,"uploaded":0}}

novakvm@m4pro-sg-01:~$ openclaw doctor --json | jq '.checks[] | select(.name|test("skills|disk|launchd"))'
[OK] skills.root writable (~/.openclaw/skills)
[OK] launchd PATH includes node and openclaw
[OK] disk free 412 GB (warn below 80 GB)

novakvm@m4pro-sg-01:~$ openclaw skill list --json | jq '.[] | {name,source,enabled,version}'
{"name":"file-tools","source":"builtin","enabled":true,"version":"2026.5.0"}
{"name":"browser-lite","source":"builtin","enabled":false,"version":"2026.5.0"}

Three schema shifts matter in 2026.5.x compared to early 2026.4 builds: Skills config moved under a dedicated skills.* namespace; ClawHub skill packages are versioned independently from Plugins sharing similar names; uploaded archives require explicit opt-in via skills.install.allowUploadedArchives defaulting to false on fresh installs. Treat false as the secure default—only flip it on hosts where you control upload ACLs.

[ SECTION_03 ] // BUILTIN_MATRIX Built-in skills: what to enable and what to leave off

Built-in Skills ship with OpenClaw and need no ClawHub fetch. The decision is not “install or not” but enable or disable per workspace, with awareness of disk and security tradeoffs.

novakvm@m4pro-sg-01:~$ openclaw skill enable file-tools --workspace acme
novakvm@m4pro-sg-01:~$ openclaw skill disable shell-exec --workspace acme
novakvm@m4pro-sg-01:~$ openclaw skill enable browser-lite --workspace internal

novakvm@m4pro-sg-01:~$ openclaw skill list --workspace acme --json | jq '.[] | select(.enabled==true) | .name'
"file-tools"
"http-fetch"

[WARN] shell-exec remains disabled on acme; internal workspace may differ.

Production hygiene: enable the smallest tool surface that satisfies the workflow. A support bot that only answers FAQs does not need shell-exec on day one. Add Skills in maintenance windows, snapshot openclaw skill list --json before and after, and attach the diff to the change ticket—the same discipline as Plugin pins in the multi-workspace article.

[ SECTION_04 ] // CLAWHUB_SKILLS ClawHub community Skills: install, pin, and rollback

ClawHub hosts community Skill packs distinct from Plugin entries. Names collide—always verify source: clawhub in JSON output before you pin. Install flow mirrors Plugins but writes under ~/.openclaw/skills/clawhub/.

novakvm@m4pro-sg-01:~$ openclaw skill search notion-export --source clawhub
notion-export 1.3.1 (stable) — export pages to markdown
notion-export 1.4.0-beta.2 (beta) — block API v2

novakvm@m4pro-sg-01:~$ openclaw skill install notion-export@1.3.1 --workspace acme --channel stable
[OK] installed notion-export@1.3.1 → ~/.openclaw/skills/clawhub/notion-export/1.3.1

novakvm@m4pro-sg-01:~$ openclaw skill pin notion-export@1.3.1 --workspace acme
novakvm@m4pro-sg-01:~$ openclaw skill enable notion-export --workspace acme

novakvm@m4pro-sg-01:~$ launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
novakvm@m4pro-sg-01:~$ curl -fsS http://127.0.0.1:18789/health | jq '.skills'
{"builtin":12,"clawhub":1,"uploaded":0}

Rollback when a ClawHub Skill breaks prompts or disk:

1. openclaw skill disable <name> --workspace <ws> to stop new sessions from binding the tool.
2. openclaw skill pin <name>@<old> --workspace <ws> to lock the previous version.
3. launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway and re-check /health.
4. If schema migration corrupted state, remove the version folder under clawhub/<name>/ only after archiving it—never delete the entire skills/ root.

Canary pattern: install beta Skills only on an internal or canary workspace, run 24 hours of regression prompts, then promote pin to production workspaces. Never let openclaw skill update --all run unattended on a multi-tenant host.

[ SECTION_05 ] // PRIVATE_UPLOAD Private Skill archives: upload path, allowUploadedArchives, and security boundaries

Teams with internal runbooks often package Skills as zip archives—manifest plus tool definitions—rather than publishing to ClawHub. OpenClaw 2026.5.x supports upload install when administrators explicitly set skills.install.allowUploadedArchives=true. Default false is intentional: uploaded archives can contain shell hooks.

• Config gate: set allow flag in openclaw.json or via openclaw config set skills.install.allowUploadedArchives=true. Document who approved the change; pair with workspace allowlists where available.
• Upload landing zone: archives extract to ~/.openclaw/skills/uploaded/<workspace>/<skill-name>/<version>/. Keep one version directory per upload for clean rollback.
• Manifest requirements: zip must include skill.manifest.json with name, version, entry tool definitions, and optional permission declarations. Doctor validates manifest before enable.
• Transport: use openclaw skill upload on the Gateway host or SCP zip into a staging dir then openclaw skill install --from-archive. Do not unzip manually into random paths—hash mismatch breaks enable.
• Secrets: never embed API keys inside uploaded zips. Inject via ~/.openclaw/secrets/<workspace>/.env.local and reference env names in manifest.
• ACL: chmod 700 on uploaded/; restrict upload command to operator accounts; audit uploads in change tickets with sha256 of the zip.

novakvm@m4pro-sg-01:~$ openclaw config set skills.install.allowUploadedArchives=true
novakvm@m4pro-sg-01:~$ shasum -a 256 /tmp/acme-runbook-skill-2.1.0.zip
a4f8c2...  /tmp/acme-runbook-skill-2.1.0.zip

novakvm@m4pro-sg-01:~$ openclaw skill upload /tmp/acme-runbook-skill-2.1.0.zip \
       --workspace acme --name acme-runbook --version 2.1.0
[OK] extracted → ~/.openclaw/skills/uploaded/acme/acme-runbook/2.1.0
[OK] manifest validated (tools=4, permissions=file-read,shell-exec)

novakvm@m4pro-sg-01:~$ openclaw skill enable acme-runbook --workspace acme
novakvm@m4pro-sg-01:~$ openclaw skill list --workspace acme --json | jq '.[] | select(.source=="uploaded")'
{"name":"acme-runbook","source":"uploaded","enabled":true,"version":"2.1.0"}

[WARN] Turn allowUploadedArchives off on shared demo hosts after trials.

Security boundaries worth enforcing in policy:

• Uploaded Skills run with the same OS user as Gateway—on remote Macs that user should not be admin.
• Separate upload directories per workspace so a trial zip on pilot never merges into acme tool lists.
• Scan zips in CI before upload; block archives that ship binary blobs without source review.
• Rotate upload ACL quarterly; stale zips accumulate and confuse Agent tool discovery.

[ SECTION_06 ] // DISK_RUNBOOK_FAQ Disk layering, six-region placement, error matrix, 12-step runbook, case study, FAQ

Skills add a fourth disk consumer beside workspace data, Plugin caches, and logs. Layer directories deliberately on remote Macs so a full disk does not take Gateway offline mid-upload.

M4 versus M4 Pro watermarks: on M4 24GB / 512GB, budget roughly 2 GB for Skills trees and cache combined before weekly cleanup. On M4 Pro 48GB / 1TB, five workspaces with mixed ClawHub and uploaded packs comfortably sit below 8 GB Skills footprint if cache rotation runs weekly. Cross 80 GB free disk on any tier and treat it as install-blocking—doctor should warn, but do not rely on warnings alone; cron df -h / into your metrics stack.

Six-region placement: Skills install is CPU-light and disk-bound; region choice follows customer data residency and operator SSH latency, not Skill fetch CDN. Singapore and Tokyo fit APAC operators; US-East and US-West fit Americas; Hong Kong and Seoul bridge cross-border teams. Model round-trip latency still dominates Agent feel—Skills do not fix a wrong region pick.

Real case (anonymized indie ops team on NOVAKVM M4 Pro):

• Week 1: Gateway only, built-in file-tools and http-fetch enabled on one workspace. Skills disk under 400 MB.
• Week 4: Added two ClawHub Skills (notion-export, github-issue-triage) with pins; slope ~120 MB/week mostly cache.
• Week 6: Uploaded private acme-runbook zip after enabling allowUploadedArchives; manifest required shell-exec—disabled on customer workspace, enabled only on internal.
• Week 8 incident: beta ClawHub upgrade broke tool schema; rollback via pin plus disable restored service in 12 minutes without full state restore.

12-step Skills runbook:

1. Record OpenClaw version and workspace list in the change ticket.
2. Run doctor and /health; abort if either fails.
3. Snapshot openclaw skill list --json to before-skills.json.
4. Decide built-in enables per workspace using the Section 3 matrix.
5. For ClawHub: search, install stable, pin, enable—one skill at a time.
6. For private zip: verify sha256, confirm allowUploadedArchives approval, upload, validate manifest output.
7. Enable only after manifest and permissions review.
8. Restart Gateway with launchctl kickstart; wait for /health skills counts to match expectation.
9. Run three regression prompts that invoke each new tool surface.
10. Snapshot after-skills.json and diff against before.
11. Record disk usage: du -sh ~/.openclaw/skills/*.
12. Exit checklist: version, skill list, health, disk free above watermark—then close the window.

Auditable facts:

• Default Gateway port remains 127.0.0.1:18789; /health exposes skill counts by source when 2026.5.x readiness endpoints are enabled.
• Fresh 2026.5.x install ships roughly 12 built-in Skill families; exact count varies by channel—always trust skill list JSON over blog snapshots.
• Private upload remains disabled by default via skills.install.allowUploadedArchives=false until operators opt in.
• Typical three-workspace host with mixed ClawHub and one uploaded pack: 1–3 GB under ~/.openclaw/skills/ after 60 days excluding aggressive browser cache.

FAQ:

• Should I use Plugin install for a Skill-like npm package? No—verify catalog type first. Use skill search versus plugin search.
• Can I copy uploaded zips between remote Macs? Yes—tar skills/uploaded/ plus matching config flags; replay on same OpenClaw major.
• Does allowUploadedArchives affect ClawHub? No—it gates only local archive upload install path.
• How many ClawHub Skills on M4 512GB? Roughly 8–10 pinned packs before you should schedule cache cleanup or move to 1TB.
• Gateway healthy but tool missing in chat? Workspace mismatch—confirm session workspace matches enable target; restart alone does not fix wrong workspace binding.

Skills are where OpenClaw stops being a messaging relay and becomes an operator-grade Agent platform. That power needs pinned versions, explicit upload policy, and disk layers you can inspect over SSH—not a laptop that sleeps and loses half the tree. For teams running Gateway 24/7 with built-in, ClawHub, and private Skills on the same host, NOVAKVM bare-metal Mac mini rental across six regions gives you reproducible paths, room for cache growth, and maintenance windows you can rehearse. Paste the 12-step runbook into your next change ticket before enabling shell-exec on a customer workspace—and keep allowUploadedArchives off until someone signs the ACL.