OpenClaw 스킬 가이드: 에이전트 도구 설정 및 관리 방법

OpenClaw는 에이전트에게 도구 사용법을 가르치기 위해 AgentSkills와 호환되는 스킬 폴더를 사용해요. 각 스킬은 YAML frontmatter와 지침이 담긴 SKILL.md 파일이 포함된 디렉토리예요. OpenClaw는 기본으로 제공되는 bundled skills와 선택 사항인 로컬 오버라이드를 함께 로드하며, 실행 시점의 환경, 설정, 바이너리 존재 여부에 따라 이를 필터링합니다.

위치 및 우선순위

OpenClaw는 다음 소스에서 스킬을 불러와요:

1. Extra skill folders: skills.load.extraDirs로 설정된 폴더
2. Bundled skills: 설치 시 함께 제공되는 스킬 (npm 패키지 또는 OpenClaw.app)
3. Managed/local skills: ~/.openclaw/skills
4. Personal agent skills: ~/.agents/skills
5. Project agent skills: <workspace>/.agents/skills
6. Workspace skills: <workspace>/skills

만약 스킬 이름이 충돌한다면, 다음 우선순위를 따릅니다:

<workspace>/skills (가장 높음) → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled skills → skills.load.extraDirs (가장 낮음)

에이전트별 스킬 vs 공유 스킬

멀티 에이전트 설정에서는 각 에이전트가 자신만의 workspace를 가집니다. 이 경우 스킬은 다음과 같이 관리돼요:

• 에이전트별 스킬은 해당 에이전트 전용으로 <workspace>/skills에 위치합니다.
• 프로젝트 에이전트 스킬은 <workspace>/.agents/skills에 위치하며, 일반적인 workspace의 skills/ 폴더보다 먼저 해당 workspace에 적용됩니다.
• 개인 에이전트 스킬은 ~/.agents/skills에 위치하며, 해당 장비의 모든 workspace에 걸쳐 적용됩니다.
• 공유 스킬은 ~/.openclaw/skills (managed/local)에 위치하며, 같은 장비의 모든 에이전트가 볼 수 있습니다.
• 여러 에이전트가 공통으로 사용하는 스킬 팩을 만들고 싶다면 skills.load.extraDirs를 통해 공유 폴더를 추가할 수도 있어요 (우선순위는 가장 낮습니다).

동일한 이름의 스킬이 여러 곳에 있다면 앞서 설명한 우선순위가 적용돼요. workspace 스킬이 이기고, 그다음 프로젝트 에이전트, 개인 에이전트, 관리형/로컬, 번들, 추가 디렉토리 순서입니다.

에이전트 스킬 허용 목록 (Allowlists)

스킬의 위치와 스킬의 가시성은 서로 별개로 제어됩니다.

• 위치와 우선순위는 이름이 같은 스킬 중 어떤 복사본을 사용할지 결정해요.
• 에이전트 허용 목록은 에이전트가 실제로 어떤 스킬을 사용할 수 있는지 결정합니다.

agents.defaults.skills를 사용해 공통 기준을 정하고, agents.list[].skills를 통해 에이전트별로 설정을 덮어쓰는 방식을 추천해요:

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

규칙은 다음과 같아요:

• 기본적으로 모든 스킬을 제한 없이 사용하려면 agents.defaults.skills를 생략하세요.
• agents.defaults.skills를 상속받으려면 agents.list[].skills를 생략하세요.
• 스킬을 아예 사용하지 않으려면 agents.list[].skills: []로 설정하세요.
• 비어 있지 않은 agents.list[].skills 목록은 해당 에이전트의 최종 스킬 세트가 되며, 기본값과 병합되지 않습니다.

OpenClaw는 프롬프트 생성, 스킬 슬래시 명령어 탐색, 샌드박스 동기화, 스킬 스냅샷 전반에 걸쳐 이 에이전트 스킬 세트를 적용합니다.

플러그인과 스킬

플러그인은 openclaw.plugin.json에 skills 디렉토리를 나열하여 자체 스킬을 함께 제공할 수 있어요 (경로는 플러그인 루트 기준). 플러그인 스킬은 플러그인이 활성화될 때 로드됩니다. 현재 이 디렉토리들은 skills.load.extraDirs와 동일한 낮은 우선순위 경로로 병합되므로, 이름이 같은 번들 스킬, 관리형 스킬, 에이전트 또는 workspace 스킬이 있다면 그것들이 우선권을 가집니다.

플러그인 설정 항목의 metadata.openclaw.requires.config를 통해 스킬 사용을 제한할 수도 있어요. 탐색 및 설정에 대해서는 Plugins 문서를, 해당 스킬들이 가르치는 도구 인터페이스에 대해서는 Tools 문서를 참고해 보세요.

ClawHub (설치 및 동기화)

ClawHub은 OpenClaw를 위한 공개 skills 레지스트리예요. https://clawhub.ai에서 다양한 skill을 둘러볼 수 있습니다. 네이티브 openclaw skills 명령어를 사용해 skill을 찾아 설치하거나 업데이트할 수 있고, publish나 sync 워크플로우가 필요할 때는 별도의 clawhub CLI를 사용하면 돼요. 자세한 내용은 ClawHub 가이드를 확인해 보세요.

자주 사용하는 흐름은 다음과 같아요:

• 워크스페이스에 skill 설치하기:
  • openclaw skills install <skill-slug>
• 설치된 모든 skill 업데이트하기:
  • openclaw skills update --all
• 동기화 (스캔 + 업데이트 게시):
  • clawhub sync --all

네이티브 openclaw skills install 명령은 활성화된 워크스페이스의 skills/ 디렉토리에 설치를 진행해요. 별도의 clawhub CLI도 현재 작업 디렉토리 아래의 ./skills에 설치하거나, 설정된 OpenClaw 워크스페이스를 찾아 설치합니다. OpenClaw는 다음 세션에서 이를 <workspace>/skills 경로로 인식하게 돼요.

보안 유의사항

• 서드파티 skill은 신뢰할 수 없는 코드로 취급하세요. 활성화하기 전에 코드를 직접 읽어보는 것이 좋습니다.
• 신뢰할 수 없는 입력값이나 위험한 도구를 사용할 때는 샌드박스 실행을 권장해요. Sandboxing 문서를 참고해 보세요.
• 워크스페이스 및 추가 디렉토리(extra-dir)의 skill 탐색은, 해당 경로가 설정된 루트 디렉토리 내에 있는 skill 루트와 SKILL.md 파일만 허용해요.
• Gateway 기반의 skill 의존성 설치(skills.install, 온보딩, Skills 설정 UI)는 인스톨러 메타데이터를 실행하기 전에 내장된 위험 코드 스캐너를 먼저 실행해요. critical 결과가 나오면 기본적으로 차단되지만, 호출자가 명시적으로 위험 옵션을 무시하도록 설정한 경우는 예외예요. 의심스러운(suspicious) 결과는 경고만 표시합니다.
• openclaw skills install <slug> 방식은 조금 달라요. 이 명령은 ClawHub skill 폴더를 워크스페이스로 직접 다운로드하며, 위에서 언급한 인스톨러 메타데이터 경로를 사용하지 않습니다.
• skills.entries.*.env 및 skills.entries.*.apiKey는 해당 에이전트 턴 동안 호스트 프로세스에 비밀 정보를 주입해요 (샌드박스가 아니에요). 프롬프트나 로그에 비밀 정보가 노출되지 않도록 주의하세요.
• 더 자세한 위협 모델과 체크리스트는 Security 문서에서 확인할 수 있어요.

포맷 (AgentSkills 및 Pi 호환)

SKILL.md 파일에는 최소한 다음 내용이 포함되어야 해요:

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

참고 사항:

• 레이아웃과 의도(intent)는 AgentSkills 스펙을 따라요.
• 내장 에이전트가 사용하는 파서는 한 줄(single-line) frontmatter key만 지원해요.
• metadata는 반드시 한 줄 JSON 객체로 작성해야 합니다.
• skill 폴더 경로를 참조하려면 지침(instructions)에서 {baseDir}을 사용하세요.
• 선택 사항인 frontmatter key들:

  • homepage — macOS Skills UI에서 “Website”로 표시되는 URL이에요 (metadata.openclaw.homepage로도 지원돼요).

  • user-invocable — true|false (기본값: true). true일 때 해당 skill이 사용자의 슬래시 명령어로 노출돼요.

  • disable-model-invocation — true|false (기본값: false). true일 때 모델 프롬프트에서 제외되지만, 사용자 호출은 여전히 가능해요.

  • command-dispatch — tool (선택 사항). tool로 설정하면 슬래시 명령어가 모델을 거치지 않고 도구로 직접 전달돼요.

  • command-tool — command-dispatch: tool일 때 호출할 도구 이름이에요.

  • command-arg-mode — raw (기본값). 도구 전달 시 원본 인자 문자열을 그대로 전달해요 (코어 파싱 없음).

    도구는 다음 파라미터와 함께 호출돼요: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

게이팅 (로드 타임 필터)

OpenClaw는 metadata(한 줄 JSON)를 사용해 로드 타임에 skill을 필터링해요:

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

metadata.openclaw 하위 필드 설명:

• always: true — 다른 필터를 무시하고 항상 skill을 포함해요.
• emoji — macOS Skills UI에서 사용하는 선택 사항 이모지예요.
• homepage — macOS Skills UI에서 “Website”로 표시되는 선택 사항 URL이에요.
• os — 지원 플랫폼 목록이에요 (darwin, linux, win32). 설정하면 해당 OS에서만 skill을 사용할 수 있어요.
• requires.bins — 목록 내의 모든 바이너리가 PATH에 존재해야 해요.
• requires.anyBins — 목록 내의 바이너리 중 적어도 하나가 PATH에 존재해야 해요.
• requires.env — 환경 변수가 존재하거나 설정(config)에 제공되어야 해요.
• requires.config — openclaw.json 경로의 값이 참(truthy)이어야 해요.
• primaryEnv — skills.entries.<name>.apiKey와 연결된 환경 변수 이름이에요.
• install — macOS Skills UI에서 사용하는 인스톨러 스펙 배열이에요 (brew/node/go/uv/download).

샌드박스 관련 참고 사항:

• requires.bins는 skill을 로드할 때 호스트에서 체크해요.
• 에이전트가 샌드박스에서 실행된다면, 해당 바이너리는 컨테이너 내부에도 존재해야 합니다. agents.defaults.sandbox.docker.setupCommand를 사용하거나 커스텀 이미지를 통해 설치하세요. setupCommand는 컨테이너가 생성된 후 한 번 실행돼요. 패키지 설치 시에는 네트워크 연결, 쓰기 가능한 루트 파일 시스템, 샌드박스 내 루트 권한이 필요할 수 있어요. 예를 들어, summarize skill(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)",
            },
          ],
      },
  }
---

참고 사항:

• 인스톨러가 여러 개 나열되면 Gateway는 단 하나의 선호하는 옵션을 선택해요 (Homebrew가 가능하면 우선 선택하고, 아니면 Node 선택).
• 모든 인스톨러가 download 방식이면 OpenClaw는 사용 가능한 모든 항목을 나열해서 보여줘요.
• 인스톨러 스펙에 os: ["darwin"|"linux"|"win32"]를 포함해 플랫폼별로 옵션을 필터링할 수 있어요.
• Node 설치는 openclaw.json의 skills.install.nodeManager 설정을 따릅니다 (기본값: npm, 옵션: npm/pnpm/yarn/bun). 이는 skill 설치에만 영향을 주며, Gateway 런타임은 여전히 Node여야 해요 (WhatsApp/Telegram 연동 시 Bun은 권장하지 않아요).
• Gateway 기반 인스톨러 선택은 Node 전용이 아니라 선호도에 따라 결정돼요. 여러 종류가 섞여 있을 때 skills.install.preferBrew가 활성화되어 있고 brew가 존재하면 Homebrew를 가장 먼저 선택해요. 그다음은 uv, 설정된 Node 매니저, 그리고 go나 download 같은 대체 수단 순서예요.
• 모든 설치 스펙이 download라면 OpenClaw는 하나만 고르는 대신 모든 다운로드 옵션을 노출해요.
• Go 설치: go가 없고 brew를 사용할 수 있다면 Gateway는 Homebrew를 통해 Go를 먼저 설치하고, 가능하면 GOBIN을 Homebrew의 bin으로 설정해요.
• Download 설치: url (필수), archive (tar.gz | tar.bz2 | zip), extract (기본값: 아카이브 감지 시 자동), stripComponents, targetDir (기본값: ~/.openclaw/tools/<skillKey>).

metadata.openclaw가 없으면 해당 skill은 항상 사용 가능한 상태가 됩니다 (설정에서 비활성화하거나 번들 skill이 skills.allowBundled에 의해 차단된 경우는 제외).

설정 덮어쓰기 (~/.openclaw/openclaw.json)

번들로 제공되거나 관리되는 skill은 활성화 여부를 전환하거나 환경 변수(env) 값을 설정할 수 있어요.

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

참고로 skill 이름에 하이픈(-)이 포함되어 있다면 키를 따옴표로 감싸주세요 (JSON5는 따옴표가 있는 키를 허용해요).

OpenClaw 내부에서 기본 이미지 생성이나 편집 기능을 사용하고 싶다면, 번들 skill 대신 agents.defaults.imageGenerationModel과 함께 코어 image_generate tool을 사용하세요. 여기에 있는 skill 예시는 커스텀 또는 서드파티 워크플로우를 위한 것이에요.

네이티브 이미지 분석에는 agents.defaults.imageModel과 함께 image tool을 사용하면 돼요. 네이티브 이미지 생성 및 편집에는 agents.defaults.imageGenerationModel과 함께 image_generate를 사용하세요. 만약 openai/*, google/*, fal/* 또는 다른 provider 전용 이미지 모델을 선택했다면, 해당 provider의 인증/API key도 추가해야 해요.

설정 키는 기본적으로 skill name과 일치해요. 만약 skill이 metadata.openclaw.skillKey를 정의했다면, skills.entries 아래에 해당 키를 사용하세요.

규칙은 다음과 같아요:

• enabled: false: 번들로 제공되거나 설치된 skill이라도 비활성화해요.
• env: 프로세스에 해당 변수가 아직 설정되지 않은 경우에만 주입돼요.
• apiKey: metadata.openclaw.primaryEnv를 선언하는 skill을 위한 편의 기능이에요. 일반 텍스트 문자열이나 SecretRef 객체({ source, provider, id })를 지원해요.
• config: skill별 커스텀 필드를 위한 선택적 영역이에요. 커스텀 키는 반드시 여기에 위치해야 해요.
• allowBundled: 번들 skill 전용 선택적 허용 목록(allowlist)이에요. 이 설정이 있으면 목록에 있는 번들 skill만 사용할 수 있어요 (관리형/워크스페이스 skill에는 영향을 주지 않아요).

환경 변수 주입 (에이전트 실행당)

에이전트 실행이 시작될 때 OpenClaw는 다음과 같은 작업을 수행해요:

1. skill metadata를 읽어요.
2. skills.entries.<key>.env 또는 skills.entries.<key>.apiKey 설정을 process.env에 적용해요.
3. 사용 가능한 skill들로 system prompt를 구성해요.
4. 실행이 끝나면 원래 환경으로 복구해요.

이 작업은 글로벌 쉘 환경이 아니라 에이전트 실행 범위(scope) 내에서만 이루어져요.

번들로 제공되는 claude-cli backend의 경우, OpenClaw는 동일한 스냅샷을 임시 Claude Code 플러그인으로 구체화하고 --plugin-dir과 함께 전달해요. 이를 통해 Claude Code는 자체적인 skill resolver를 사용하면서도, OpenClaw가 가진 우선순위, 에이전트별 허용 목록, 게이팅(gating), 그리고 skills.entries.*를 통한 env/API key 주입 기능을 그대로 유지할 수 있어요. 다른 CLI backend들은 prompt catalog만 사용해요.

세션 스냅샷 (성능)

OpenClaw는 세션이 시작될 때 사용 가능한 skill들의 스냅샷을 찍고, 같은 세션의 후속 턴에서 이 목록을 재사용해요. skill이나 설정의 변경 사항은 다음 새 세션부터 적용돼요.

skill watcher가 활성화되어 있거나 새로운 사용 가능한 원격 node가 나타나면 세션 중간에도 skill을 새로고침할 수 있어요. 이것을 hot reload라고 생각하면 돼요. 새로고침된 목록은 다음 에이전트 턴에서 반영돼요.

해당 세션의 유효한 에이전트 skill 허용 목록이 변경되면, OpenClaw는 스냅샷을 새로고침해서 현재 에이전트와 일치하도록 유지해요.

원격 macOS 노드 (Linux Gateway)

Gateway가 Linux에서 실행 중이더라도, system.run이 허용된 (실행 승인 보안이 deny로 설정되지 않은) macOS node가 연결되어 있다면, 해당 node에 필요한 바이너리가 있을 때 OpenClaw는 macOS 전용 skill을 사용 가능한 것으로 간주할 수 있어요. 에이전트는 host=node 설정과 함께 exec tool을 통해 해당 skill을 실행해야 해요.

이 기능은 node가 자신의 커맨드 지원 여부를 보고하고 system.run을 통한 바이너리 확인(bin probe)에 의존해요. 만약 나중에 macOS node가 오프라인이 되어도 skill은 계속 표시되지만, node가 다시 연결될 때까지 실행은 실패할 수 있어요.

Skills watcher (자동 새로고침)

기본적으로 OpenClaw는 skill 폴더를 감시하다가 SKILL.md 파일이 변경되면 skill snapshot을 자동으로 갱신해요. 이 설정은 skills.load 아래에서 구성할 수 있어요.

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

Token 영향 (skills 리스트)

Skill을 사용할 수 있는 상태가 되면, OpenClaw는 시스템 프롬프트에 사용 가능한 skill 목록을 압축된 XML 형태로 삽입해요 (pi-coding-agent 내부의 formatSkillsForPrompt 기능을 사용해요). 이때 발생하는 비용은 다음과 같이 계산할 수 있어요.

• 기본 오버헤드 (skill이 1개 이상일 때만 발생): 195자
• Skill당 추가 비용: 97자 + XML 이스케이프 처리가 된 <name>, <description>, <location> 값의 길이

계산 공식 (문자 수 기준):

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

참고할 점:

• XML 이스케이프 처리는 & < > " ' 같은 문자를 엔티티(&, < 등)로 변환하기 때문에 전체 길이가 늘어날 수 있어요.
• Token 수는 모델의 tokenizer에 따라 달라져요. OpenAI 스타일로 대략 계산하면 4자당 1 token 정도이므로, 각 skill당 97자 ≈ 24 tokens에 실제 필드 길이를 더한 만큼 소모된다고 보면 돼요.

관리형 Skill 라이프사이클

OpenClaw는 설치 과정(npm 패키지 또는 OpenClaw.app)의 일부로 기본적인 Skill 세트를 bundled skills 형태로 제공해요. ~/.openclaw/skills 경로는 로컬에서 설정을 덮어쓰기 위해 존재해요. 예를 들어, 기본으로 제공되는 복사본을 직접 수정하지 않고도 특정 Skill을 고정(pinning)하거나 패치(patching)할 수 있죠. Workspace Skill은 사용자가 직접 관리하며, 이름이 충돌할 경우 bundled skills와 로컬 설정을 모두 덮어쓰고 우선적으로 적용돼요.

설정 레퍼런스

전체 구성 스키마에 대한 자세한 내용은 Skills config 문서를 확인해 보세요.

더 많은 Skill을 찾고 계신가요?

https://clawhub.ai에서 더 다양한 Skill을 둘러보세요.

관련 문서

• Creating Skills — 커스텀 Skill 만들기
• Skills Config — Skill 설정 레퍼런스
• Slash Commands — 사용 가능한 모든 Slash Command
• Plugins — Plugin 시스템 개요