2026년 OpenClaw Skills 실전:
원격 Mac M4 Pro에서 ClawHub 설치, 비공개 아카이브 업로드, 디스크 계층화 및 Gateway 트러블슈팅

원격 Mac mini M4 Pro에서 OpenClaw Gateway가 상시 구동되고 채널도 연결된 뒤, 다음 병목은 대부분 「플러그인을 하나 더」가 아닙니다. 병목은 Skills입니다. Skills는 Agent가 대화 중 호출하는 도구 표면으로, 파일 작업, 브라우저 자동화, 셸 실행, 팀별 Runbook을 제공합니다. 2026.5.x 계열에서는 Skills가 내장 팩, ClawHub 커뮤니티 카탈로그, skills.install.allowUploadedArchives로 제어되는 비공개 zip 업로드의 세 경로로 정리되었습니다. Skills를 Plugins와 같은 CLI로 다루거나 디스크 설계를 미루면 Gateway 재시작 루프, zip이 잘못된 워크스페이스 트리에 풀리는 현상을 늦게 발견하게 됩니다.

본 글은 기본 설치와 데몬 온보딩을 마친 운영자를 대상으로 합니다. Skills와 Plugins 경계표, 2026.5.x 사전 점검, 내장 활성화 매트릭스, ClawHub 설치와 pin 명령, 비공개 zip 업로드 보안 경계, M4와 M4 Pro 디스크 기준선, 증상 매트릭스, 소규모 팀 단계 사례, 12단계 런북을 제공합니다. 가격은 NOVAKVM 가격 페이지, 주문은 주문 페이지, SSH와 백업 정책은 고객 센터를 참고하십시오. 멀티 워크스페이스 격리 편, 2026.5.x 외부 Plugin npm 편, 첫 실행 클로저 편, install.sh와 디스크 편도 함께 읽어 주십시오. 명령은 상류 문서를 우선하며, 릴리스 후 다시 확인하십시오.

[ SECTION_01 ] // BOUNDARY_MAP Skills와 Plugins: 프로덕션 팀에서 가장 먼저 무너지는 경계

설치 직후 가장 흔한 실수는 Skill을 Plugin CLI로 설치하거나, Agent가 Skill을 필요로 하는데 채널 Plugin만 켜 두는 것입니다. 동일 Gateway에서 공존하지만 역할은 다릅니다.

• Plugins는 입구와 사이드카를 확장합니다: Telegram, Discord, WeChat ClawBot, 메일 브리지, npm 채널 어댑터는 Plugin으로 Gateway에 붙습니다. 메시지 입출력을 담당하며, 세션 중 Agent가 호출할 도구 정의 자체는 아닙니다.
• Skills는 Agent 능력을 확장합니다: 파일 읽기·쓰기, 브라우저 제어, 구조화 API 래퍼, 사내 Runbook을 호출 가능한 도구로 제공합니다. Agent 런타임에 로드되어 대화 중 도구 목록에 나타납니다.
• 설치 루트가 다릅니다: Plugin은 2026.5.x 외부 Plugin 글에서 설명한 캐시 경로 아래에 둡니다. Skills는 ~/.openclaw/skills/ 아래 built-in, ClawHub, uploaded 서브트리로 펼쳐집니다.
• 업그레이드 영향 범위가 다릅니다: Plugin 업데이트는 채널 중단으로 이어질 수 있습니다. Skill 업데이트는 도구 스키마를 바꿔 기존 Agent 프롬프트를 깨뜨릴 수 있습니다.
• 보안 자세도 다릅니다: Plugin은 메시징 OAuth 토큰을 보관하는 경우가 많습니다. Skills는 셸 실행과 로컬 파일 읽기를 수반하므로 uploaded 아카이브에는 명시적 허용 플래그와 워크스페이스 스코프가 필요합니다.

기준은 간단합니다. 「Telegram을 받을 수 없다」면 Plugins를 고칩니다. 「사내 체크리스트 도구를 Agent가 호출하지 못한다」면 Skills를 고칩니다. CLI 표면을 혼동하면 반나절을 잃고 공유 캐시 디렉터리를 손상시킬 수 있습니다.

[ SECTION_02 ] // PREFLIGHT 2026.5.x Skills 모델 변경과 사전 점검

Skill 팩을 하나 설치하기 전에 원격 Mac에서 네 가지 기준선을 확인하십시오. 생략하면 zip 손상처럼 보이는 오류가 실제로는 버전 불일치나 권한 문제인 경우가 많습니다.

• OpenClaw 메이저: Skills 설치 의미론은 2026.5.x 설정 스키마에 묶입니다. openclaw --version을 실행하고 해당 태그 README Skills 절과 대조하십시오.
• Gateway 헬스: 설치 변경 전 curl -fsS http://127.0.0.1:18789/health가 ok를 반환해야 합니다. 반쯤 죽은 Gateway에서 install하면 skill 트리가 중간 상태로 남습니다.
• doctor 통과: openclaw doctor는 Node 경로, 쓰기 가능한 ~/.openclaw, launchd 컨텍스트를 보고합니다. Skills install은 Gateway와 동일 사용자로 실행되므로 PATH 드리프트는 post-install 훅 실패로 이어집니다.
• 워크스페이스 맥락: 다중 WS 운영에서는 어떤 WS가 enable 목록을 소유하는지 먼저 정하십시오. --workspace 없는 교차 WS install은 「설치했는데 Agent가 못 본다」 문의의 최다 패턴입니다.

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"}

2026.5.x에서는 2026.4 초기 빌드 대비 세 가지가 중요합니다. Skills 설정이 전용 skills.* 네임스페이스로 이동했습니다. ClawHub Skill 패키지는 동명 Plugin과 독립 버전 관리됩니다. uploaded 아카이브는 skills.install.allowUploadedArchives가 기본 false이므로 명시적 opt-in이 필요합니다. false는 안전 쪽 기본값으로 두고, 업로드 ACL을 통제할 수 있는 호스트에서만 true로 설정하십시오.

[ SECTION_03 ] // BUILTIN_MATRIX 내장 Skills: 활성화와 비활성화 판단

내장 Skills는 OpenClaw에 동봉되며 ClawHub fetch가 필요 없습니다. 판단은 「설치 여부」가 아니라 WS 단위로 enable할지 disable할지입니다. 디스크와 보안 트레이드오프를 함께 보십시오.

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.

프로덕션 위생은 워크플로를 만족하는 최소 도구 표면만 enable하는 것입니다. FAQ만 답하는 지원 Bot에 day-one shell-exec은 필요 없습니다. Skills 추가는 유지보수 창에서 수행하고, 전후로 openclaw skill list --json을 스냅샷해 diff를 변경 티켓에 붙이십시오. Plugin pin과 같은 습관입니다.

[ SECTION_04 ] // CLAWHUB_SKILLS ClawHub 커뮤니티 Skills: 설치, pin, 롤백

ClawHub는 Plugin 항목과 별도의 커뮤니티 Skill 팩을 호스팅합니다. 이름 충돌이 있으므로 pin 전 JSON에서 source: clawhub를 반드시 확인하십시오. 설치 흐름은 Plugin과 유사하지만 쓰기 위치는 ~/.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}

ClawHub Skill이 프롬프트나 디스크를 깨뜨렸을 때 롤백 순서는 다음과 같습니다.

1. openclaw skill disable <name> --workspace <ws>로 신규 세션 바인딩을 중단합니다.
2. openclaw skill pin <name>@<old> --workspace <ws>로 이전 버전을 고정합니다.
3. launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway 후 /health를 재확인합니다.
4. 스키마 마이그레이션으로 상태가 손상되면 clawhub/<name>/ 아래 버전 폴더만 아카이브 후 삭제하고, skills/ 루트 전체는 지우지 마십시오.

카나리아 운영에서는 beta Skill을 internal 또는 canary WS에만 설치하고, 24시간 회귀 프롬프트 후 프로덕션 WS로 pin을 승격하십시오. 멀티테넌트 호스트에서 openclaw skill update --all을 무인 실행하지 마십시오.

[ SECTION_05 ] // PRIVATE_UPLOAD 비공개 Skill 아카이브: 업로드 경로, allowUploadedArchives, 경계

사내 Runbook을 ClawHub에 공개하지 않고 zip으로 배포하는 팀을 위해 OpenClaw 2026.5.x는 skills.install.allowUploadedArchives=true일 때 업로드 install을 허용합니다. 기본 false는 의도적입니다. uploaded 아카이브에는 셸 훅을 넣을 수 있습니다.

• 설정 게이트: openclaw.json 또는 openclaw config set skills.install.allowUploadedArchives=true로 허용합니다. 승인자를 기록하고 가능하면 WS allowlist와 병행하십시오.
• 전개 위치: ~/.openclaw/skills/uploaded/<workspace>/<skill-name>/<version>/. 롤백을 위해 업로드당 하나의 버전 디렉터리를 유지하십시오.
• 매니페스트: zip에는 skill.manifest.json이 필요합니다. name, version, 도구 정의, 선택적 permission 선언을 포함합니다. doctor가 enable 전에 검증합니다.
• 전송: Gateway 호스트에서 openclaw skill upload를 쓰거나 SCP로 staging 후 openclaw skill install --from-archive합니다. 임의 경로에 수동 unzip하면 해시 불일치로 enable할 수 없습니다.
• 시크릿: API 키를 zip에 넣지 마십시오. ~/.openclaw/secrets/<workspace>/.env.local에 주입하고 매니페스트에서는 환경 변수 이름을 참조하십시오.
• ACL: uploaded/는 chmod 700, 업로드 권한은 운영자 계정으로 제한하고 zip sha256을 변경 티켓에 기록하십시오.

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] 공유 데모 호스트에서는 시험 후 allowUploadedArchives를 off로 되돌리십시오.

정책으로 지켜야 할 경계는 다음과 같습니다. uploaded Skill은 Gateway와 동일 OS 사용자 권한으로 실행되므로 원격 Mac에서는 admin이 아닌 전용 사용자를 쓰십시오. WS별 upload 디렉터리를 분리해 pilot 시험 zip이 acme 도구 목록에 섞이지 않게 하십시오. CI에서 zip을 스캔하고 소스 리뷰 없는 바이너리 blob을 차단하십시오. 분기마다 upload ACL을 점검해 오래된 zip이 Agent 탐색을 혼란시키지 않게 하십시오.

[ SECTION_06 ] // DISK_RUNBOOK_FAQ 디스크 계층, 6리전 배치, 증상 매트릭스, 12단계, FAQ

Skills는 WS 데이터, Plugin 캐시, 로그에 더해 네 번째 디스크 소비원입니다. 원격 Mac에서는 디렉터리를 의도적으로 계층화해 upload 중 디스크 full로 Gateway가 떨어지지 않게 하십시오.

M4와 M4 Pro 기준선: M4 24GB / 512GB에서는 Skills 트리와 캐시 합계를 주간 정리 전 약 2 GB 상한으로 보십시오. M4 Pro 48GB / 1TB에서는 ClawHub와 uploaded를 섞은 5 WS도 주간 cache 로테이션이 있으면 Skills 전체 8 GB 미만에 머물기 쉽습니다. 여유 80 GB 아래는 install 차단으로 취급하고 doctor 경고만 믿지 말고 df -h /를 메트릭에 흘리십시오.

6리전 배치: Skills install은 CPU보다 디스크 구속입니다. 리전 선택은 데이터 레지던시와 SSH 지연이 주이며 Skill fetch CDN이 아닙니다. APAC 운영자에는 싱가포르와 도쿄, 미주에는 US-East와 US-West, 홍콩과 서울은 국경을 넘는 팀 중계에 적합합니다. 모델 왕복 지연이 Agent 체감을 지배한다는 점은 변하지 않습니다.

사례(익명 소규모 운영 팀, NOVAKVM M4 Pro):

• 1주차: Gateway만, 1 WS에서 file-tools와 http-fetch enable. Skills 디스크 400 MB 미만.
• 4주차: ClawHub 2개(notion-export, github-issue-triage) pin 설치. 주간 증가는 주로 cache로 약 120 MB.
• 6주차: allowUploadedArchives 승인 후 acme-runbook zip upload. manifest가 shell-exec을 요구해 고객 WS는 off, internal만 enable.
• 8주차 장애: beta ClawHub 업데이트로 스키마 파손. pin과 disable 롤백으로 12분 복구, 전체 state 복원은 불필요했습니다.

12단계 Skills 런북:

1. 변경 티켓에 OpenClaw 버전과 WS 목록을 기록합니다.
2. doctor와 /health를 실행하고 실패 시 중단합니다.
3. openclaw skill list --json을 before-skills.json에 저장합니다.
4. Section 3 매트릭스로 WS별 내장 enable을 결정합니다.
5. ClawHub는 search, stable install, pin, enable을 Skill마다 하나씩 수행합니다.
6. 비공개 zip은 sha256 확인, allowUploadedArchives 승인, upload, manifest 출력 검증을 합니다.
7. manifest와 permission 검토 후에만 enable합니다.
8. launchctl kickstart 후 /health skills 카운트가 기대값과 일치할 때까지 기다립니다.
9. 새 도구 표면마다 회귀 프롬프트 3개를 실행합니다.
10. after-skills.json을 저장해 before와 diff합니다.
11. du -sh ~/.openclaw/skills/*로 디스크 사용량을 기록합니다.
12. exit 체크: 버전, skill list, health, 여유 디스크가 watermark 이상이면 창을 닫습니다.

감사 가능한 사실:

• 기본 Gateway는 127.0.0.1:18789입니다. 2026.5.x readiness 활성 시 /health는 출처별 skill 수를 반환합니다.
• 신규 2026.5.x install의 내장 Skill 패밀리는 대략 12입니다. 정확 수는 skill list JSON을 신뢰하십시오.
• 비공개 upload는 skills.install.allowUploadedArchives=false가 기본이며 opt-in 전까지 비활성입니다.
• ClawHub와 uploaded를 각 1개씩 섞은 3 WS 호스트는 60일 후 1~3 GB가 전형입니다(browser cache 다용 제외).

FAQ:

• Skill형 npm 패키지를 Plugin install로 넣어도 됩니까? 아닙니다. 먼저 카탈로그 종류를 확인하고 skill search와 plugin search를 구분하십시오.
• uploaded zip을 원격 Mac 간에 복사할 수 있습니까? 예. skills/uploaded/를 tar하고 동일 OpenClaw 메이저에서 config 플래그를 재현하십시오.
• allowUploadedArchives가 ClawHub에도 적용됩니까? 아닙니다. 로컬 archive upload 경로만 게이트합니다.
• M4 512GB에서 ClawHub는 몇 개까지? pin 기준 8~10팩이면 cache 정리 또는 1TB 전환을 검토하십시오.
• Gateway는 healthy인데 채팅에 도구가 없습니까? WS 불일치입니다. 세션 WS와 enable 대상 WS를 대조하십시오. 재시작만으로는 고쳐지지 않습니다.

Skills는 OpenClaw를 메시지 중계에서 운영자급 Agent 플랫폼으로 끌어올리는 층입니다. 그만큼 pin, upload 정책, SSH로 점검 가능한 디스크 계층이 필요합니다. 잠들면 트리 절반이 사라지는 노트북이 아니라 내장·ClawHub·비공개 Skills를 24/7 올린다면 NOVAKVM 베어메탈 Mac mini 임대 6리전 노드가 재현 가능한 경로와 cache 여유, 리허설 가능한 유지보수 창을 제공합니다. 고객 WS에서 shell-exec을 enable하기 전 12단계 런북을 변경 티켓에 붙이고, ACL 서명 없이 allowUploadedArchives를 켜지 마십시오.