스킬 (OpenClaw)

OpenClaw는 AgentSkills 호환 스킬 폴더를 사용하여 에이전트에게 도구 사용 방법을 가르칩니다. 각 스킬은 YAML frontmatter와 지침이 있는 SKILL.md를 포함하는 디렉토리입니다. OpenClaw는 번들 스킬과 선택적 로컬 재정의를 로드하고 환경, 구성 및 바이너리 존재에 따라 로드 시 필터링합니다.

위치 및 우선순위

스킬은 세 곳에서 로드됩니다:

  1. 번들 스킬: 설치와 함께 제공됨 (npm 패키지 또는 OpenClaw.app)
  2. 관리/로컬 스킬: ~/.openclaw/skills
  3. 작업 공간 스킬: <workspace>/skills

스킬 이름이 충돌하면 우선순위는:

<workspace>/skills (최고) → ~/.openclaw/skills → 번들 스킬 (최저)

또한 ~/.openclaw/openclaw.json의 skills.load.extraDirs를 통해 추가 스킬 폴더(가장 낮은 우선순위)를 구성할 수 있습니다.

에이전트별 vs 공유 스킬

다중 에이전트 설정에서 각 에이전트는 자체 작업 공간을 갖습니다. 즉:

  • 에이전트별 스킬은 해당 에이전트만을 위한 <workspace>/skills에 있습니다.
  • 공유 스킬은 ~/.openclaw/skills(관리/로컬)에 있으며 동일한 머신의 모든 에이전트에 표시됩니다.
  • 공유 폴더는 여러 에이전트가 사용하는 공통 스킬 팩을 원하는 경우 skills.load.extraDirs를 통해 추가할 수도 있습니다(가장 낮은 우선순위).

동일한 스킬 이름이 둘 이상의 위치에 있으면 일반적인 우선순위가 적용됩니다: 작업 공간이 우선, 그 다음 관리/로컬, 그 다음 번들.

플러그인 + 스킬

플러그인은 openclaw.plugin.json에 skills 디렉토리를 나열하여 자체 스킬을 제공할 수 있습니다 (플러그인 루트에 상대적인 경로). 플러그인 스킬은 플러그인이 활성화될 때 로드되고 일반 스킬 우선순위 규칙에 참여합니다. 플러그인의 구성 항목에서 metadata.openclaw.requires.config를 통해 게이트할 수 있습니다. 검색/구성은 Plugins를, 해당 스킬이 가르치는 도구 표면은 Tools를 참조하세요.

ClawdHub (설치 + 동기화)

ClawdHub는 OpenClaw의 공개 스킬 레지스트리입니다. https://clawdhub.com에서 탐색하세요. 스킬을 검색, 설치, 업데이트 및 백업하는 데 사용하세요. 전체 가이드: ClawdHub.

일반 흐름:

  • 작업 공간에 스킬 설치:
    • clawdhub install <skill-slug>
  • 설치된 모든 스킬 업데이트:
    • clawdhub update --all
  • 동기화(스캔 + 업데이트 게시):
    • clawdhub sync --all

기본적으로 clawdhub는 현재 작업 디렉토리의 ./skills에 설치됩니다 (또는 구성된 OpenClaw 작업 공간으로 폴백). OpenClaw는 다음 세션에서 이를 <workspace>/skills로 감지합니다.

보안 참고사항

  • 타사 스킬을 신뢰할 수 있는 코드로 취급하세요. 활성화하기 전에 읽으세요.
  • 신뢰할 수 없는 입력 및 위험한 도구에는 샌드박스 실행을 선호하세요. Sandboxing을 참조하세요.
  • skills.entries.*.env 및 skills.entries.*.apiKey는 해당 에이전트 턴에 대한 호스트 프로세스에 비밀을 주입합니다(샌드박스 아님). 프롬프트 및 로그에 비밀을 넣지 마세요.
  • 더 광범위한 위협 모델 및 체크리스트는 Security를 참조하세요.

형식 (AgentSkills + Pi 호환)

SKILL.md는 최소한 다음을 포함해야 합니다:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

참고:

  • 레이아웃/의도에 대해 AgentSkills 사양을 따릅니다.
  • 임베디드 에이전트가 사용하는 파서는 단일 라인 frontmatter 키만 지원합니다.
  • metadata는 단일 라인 JSON 객체여야 합니다.
  • 지침에서 스킬 폴더 경로를 참조하려면 {baseDir}을 사용하세요.
  • 선택적 frontmatter 키:

    • homepage — macOS 스킬 UI에서 "Website"로 표시되는 URL (metadata.openclaw.homepage를 통해서도 지원됨).

    • user-invocable — true|false (기본값: true). true일 때 스킬은 사용자 슬래시 명령으로 노출됩니다.

    • disable-model-invocation — true|false (기본값: false). true일 때 스킬은 모델 프롬프트에서 제외됩니다(사용자 호출을 통해서는 여전히 사용 가능).

    • command-dispatch — tool (선택사항). tool로 설정되면 슬래시 명령이 모델을 우회하고 도구로 직접 디스패치됩니다.

    • command-tool — command-dispatch: tool이 설정된 경우 호출할 도구 이름.

    • command-arg-mode — raw (기본값). 도구 디스패치의 경우 원시 args 문자열을 도구에 전달합니다(핵심 파싱 없음).

      도구는 다음 매개변수로 호출됩니다: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

게이팅 (로드 시 필터)

OpenClaw는 metadata (단일 라인 JSON)를 사용하여 로드 시 스킬을 필터링합니다:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata: {"openclaw":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
---

metadata.openclaw 아래의 필드:

  • always: true — 항상 스킬을 포함합니다(다른 게이트 건너뛰기).
  • emoji — macOS 스킬 UI에서 사용하는 선택적 이모지.
  • homepage — macOS 스킬 UI에서 "Website"로 표시되는 선택적 URL.
  • os — 선택적 플랫폼 목록 (darwin, linux, win32). 설정된 경우 스킬은 해당 OS에서만 적격입니다.
  • requires.bins — 목록; 각각은 PATH에 존재해야 합니다.
  • requires.anyBins — 목록; 하나 이상이 PATH에 존재해야 합니다.
  • requires.env — 목록; env var가 존재하거나 구성에 제공되어야 합니다.
  • requires.config — 진실이어야 하는 openclaw.json 경로 목록.
  • primaryEnv — skills.entries.<name>.apiKey와 연결된 env var 이름.
  • install — macOS 스킬 UI에서 사용하는 선택적 설치 프로그램 사양 배열 (brew/node/go/uv/download).

샌드박싱에 대한 참고사항:

  • requires.bins는 스킬 로드 시 호스트에서 확인됩니다.
  • 에이전트가 샌드박스화된 경우 바이너리도 컨테이너 내부에 존재해야 합니다. agents.defaults.sandbox.docker.setupCommand(또는 사용자 지정 이미지)를 통해 설치하세요. setupCommand는 컨테이너 생성 후 한 번 실행됩니다. 패키지 설치에는 샌드박스의 네트워크 송신, 쓰기 가능한 루트 FS 및 루트 사용자도 필요합니다. 예: summarize 스킬 (skills/summarize/SKILL.md)은 샌드박스 컨테이너에 summarize CLI가 필요합니다.

설치 프로그램 예제:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata: {"openclaw":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
---

참고:

  • 여러 설치 프로그램이 나열된 경우 게이트웨이는 단일 선호 옵션을 선택합니다(사용 가능한 경우 brew, 그렇지 않으면 node).
  • 모든 설치 프로그램이 download인 경우 OpenClaw는 사용 가능한 아티팩트를 볼 수 있도록 각 항목을 나열합니다.
  • 설치 프로그램 사양은 플랫폼별로 옵션을 필터링하기 위해 os: ["darwin"|"linux"|"win32"]를 포함할 수 있습니다.
  • Node 설치는 openclaw.json의 skills.install.nodeManager를 따릅니다(기본값: npm; 옵션: npm/pnpm/yarn/bun). 이는 스킬 설치에만 영향을 미칩니다; 게이트웨이 런타임은 여전히 Node여야 합니다 (WhatsApp/Telegram에는 Bun 권장하지 않음).
  • Go 설치: go가 없고 brew가 사용 가능한 경우 게이트웨이는 먼저 Homebrew를 통해 Go를 설치하고 가능한 경우 GOBIN을 Homebrew의 bin으로 설정합니다.
  • Download 설치: url (필수), archive (tar.gz | tar.bz2 | zip), extract (기본값: 아카이브 감지 시 자동), stripComponents, targetDir (기본값: ~/.openclaw/tools/<skillKey>).

metadata.openclaw가 없으면 스킬은 항상 적격입니다(구성에서 비활성화되거나 번들 스킬의 skills.allowBundled에 의해 차단되지 않는 한).

구성 재정의 (~/.openclaw/openclaw.json)

번들/관리 스킬은 토글하고 env 값을 제공할 수 있습니다:

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE"
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro"
        }
      },
      peekaboo: { enabled: true },
      sag: { enabled: false }
    }
  }
}

참고: 스킬 이름에 하이픈이 포함된 경우 키를 인용하세요(JSON5는 인용된 키를 허용).

구성 키는 기본적으로 스킬 이름과 일치합니다. 스킬이 metadata.openclaw.skillKey를 정의하면 skills.entries 아래에서 해당 키를 사용하세요.

규칙:

  • enabled: false는 번들/설치되었더라도 스킬을 비활성화합니다.
  • env: 변수가 프로세스에 아직 설정되지 않은 경우에만 주입됩니다.
  • apiKey: metadata.openclaw.primaryEnv를 선언하는 스킬을 위한 편의 기능.
  • config: 스킬별 사용자 지정 필드를 위한 선택적 백; 사용자 지정 키는 여기에 있어야 합니다.
  • allowBundled: 번들 스킬만을 위한 선택적 allowlist입니다. 설정된 경우 목록에 있는 번들 스킬만 적격입니다(관리/작업 공간 스킬은 영향 받지 않음).

환경 주입 (에이전트 실행별)

에이전트 실행이 시작될 때 OpenClaw는:

  1. 스킬 메타데이터를 읽습니다.
  2. skills.entries.<key>.env 또는 skills.entries.<key>.apiKey를 process.env에 적용합니다.
  3. 적격 스킬로 시스템 프롬프트를 빌드합니다.
  4. 실행이 종료된 후 원래 환경을 복원합니다.

이는 에이전트 실행으로 범위가 지정되며 전역 쉘 환경이 아닙니다.

세션 스냅샷 (성능)

OpenClaw는 세션이 시작될 때 적격 스킬을 스냅샷하고 동일한 세션의 후속 턴에 대해 해당 목록을 재사용합니다. 스킬 또는 구성에 대한 변경 사항은 다음 새 세션에서 적용됩니다.

스킬 감시자가 활성화되거나 새로운 적격 원격 노드가 나타날 때 세션 중간에 스킬을 새로 고칠 수도 있습니다(아래 참조). 이를 핫 리로드라고 생각하세요: 새로 고쳐진 목록은 다음 에이전트 턴에서 감지됩니다.

원격 macOS 노드 (Linux 게이트웨이)

게이트웨이가 Linux에서 실행 중이지만 macOS 노드가 system.run 허용됨으로 연결된 경우 (Exec 승인 보안이 deny로 설정되지 않음), OpenClaw는 필요한 바이너리가 해당 노드에 있을 때 macOS 전용 스킬을 적격으로 처리할 수 있습니다. 에이전트는 nodes 도구(일반적으로 nodes.run)를 통해 해당 스킬을 실행해야 합니다.

이는 노드가 명령 지원을 보고하고 system.run을 통한 bin 프로브에 의존합니다. macOS 노드가 나중에 오프라인이 되면 스킬은 계속 표시됩니다; 노드가 다시 연결될 때까지 호출이 실패할 수 있습니다.

스킬 감시자 (자동 새로 고침)

기본적으로 OpenClaw는 스킬 폴더를 감시하고 SKILL.md 파일이 변경될 때 스킬 스냅샷을 범프합니다. skills.load 아래에서 구성하세요:

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250
    }
  }
}

토큰 영향 (스킬 목록)

스킬이 적격인 경우 OpenClaw는 시스템 프롬프트에 사용 가능한 스킬의 컴팩트 XML 목록을 주입합니다 (pi-coding-agent의 formatSkillsForPrompt를 통해). 비용은 결정론적입니다:

  • 기본 오버헤드 (≥1 스킬인 경우에만): 195자.
  • 스킬당: 97자 + XML 이스케이프된 <name>, <description>, <location> 값의 길이.

공식 (문자):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

참고:

  • XML 이스케이프는 & < > " '를 엔티티(&amp;, &lt; 등)로 확장하여 길이를 늘립니다.
  • 토큰 수는 모델 토크나이저에 따라 다릅니다. 대략적인 OpenAI 스타일 추정은 ~4자/토큰이므로 97자 ≈ 24토큰 스킬당 + 실제 필드 길이.

관리 스킬 수명 주기

OpenClaw는 설치의 일부로 기본 스킬 세트를 번들 스킬로 제공합니다 (npm 패키지 또는 OpenClaw.app). ~/.openclaw/skills는 로컬 재정의를 위해 존재합니다(예: 번들 복사본을 변경하지 않고 스킬 고정/패치). 작업 공간 스킬은 사용자 소유이며 이름 충돌 시 둘 다를 재정의합니다.

구성 참조

전체 구성 스키마는 Skills config를 참조하세요.

더 많은 스킬을 찾고 있나요?

https://clawdhub.com을 탐색하세요.

← 문서로 돌아가기