Skills 설정

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• 네이티브 Nano Banana Pro 스타일 설정: agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"
• 네이티브 fal 설정: agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

​

에이전트 Skills 허용 목록

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

• agents.defaults.skills: agents.list[].skills를 생략한 에이전트가 공유하는 기본 허용 목록입니다.
• Skills가 기본적으로 제한되지 않도록 하려면 agents.defaults.skills를 생략하세요.
• agents.list[].skills: 해당 에이전트의 명시적인 최종 Skills 집합입니다. 기본값과 병합되지 않습니다.
• agents.list[].skills: []: 해당 에이전트에 Skills를 노출하지 않습니다.

​

필드

• 기본 제공 Skills 루트에는 항상 ~/.openclaw/skills, ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills가 포함됩니다.
• allowBundled: 번들된 Skills 전용 선택적 허용 목록입니다. 설정하면 목록에 있는 번들된 Skills만 사용할 수 있습니다(관리형, 에이전트, 워크스페이스 Skills에는 영향 없음).
• load.extraDirs: 추가로 스캔할 Skills 디렉터리입니다(가장 낮은 우선순위).
• load.allowSymlinkTargets: 신뢰할 수 있는 실제 대상 디렉터리입니다. 심볼릭 링크된 Skills 폴더가 해당 대상 루트 밖에 있더라도 이 디렉터리로 해석될 수 있습니다. ~/.agents/skills/manager -> ~/Projects/manager/skills와 같은 의도적인 형제 저장소 레이아웃에 사용하세요.
• load.watch: Skills 폴더를 감시하고 Skills 스냅샷을 새로 고칩니다(기본값: true).
• load.watchDebounceMs: Skills 감시자 이벤트의 디바운스 시간(밀리초)입니다(기본값: 250).
• install.preferBrew: 사용 가능할 때 brew 설치 프로그램을 우선합니다(기본값: true).
• install.nodeManager: Node 설치 프로그램 선호도(npm | pnpm | yarn | bun, 기본값: npm)입니다. 이는 Skills 설치에만 영향을 줍니다. Gateway 런타임은 여전히 Node여야 합니다 (WhatsApp/Telegram에는 Bun을 권장하지 않음).
  • openclaw setup --node-manager는 범위가 더 좁으며 현재 npm, pnpm, bun을 허용합니다. Yarn 기반 Skills 설치를 원하면 skills.install.nodeManager: "yarn"을 수동으로 설정하세요.
• install.allowUploadedArchives: 신뢰할 수 있는 operator.admin Gateway 클라이언트가 skills.upload.*를 통해 준비된 비공개 zip 아카이브를 설치할 수 있게 합니다(기본값: false). 이는 업로드된 아카이브 경로만 활성화합니다. 일반 ClawHub 설치에는 필요하지 않습니다.
• entries.<skillKey>: Skills별 재정의입니다.
• agents.defaults.skills: agents.list[].skills를 생략한 에이전트가 상속하는 선택적 기본 Skills 허용 목록입니다.
• agents.list[].skills: 에이전트별 선택적 최종 Skills 허용 목록입니다. 명시적 목록은 상속된 기본값과 병합되지 않고 대체합니다.

​

심볼릭 링크된 형제 저장소

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

• enabled: Skills가 번들/설치되어 있더라도 비활성화하려면 false로 설정합니다.
• env: 에이전트 실행에 주입되는 환경 변수입니다(아직 설정되지 않은 경우에만).
• apiKey: 기본 환경 변수를 선언하는 Skills를 위한 선택적 편의 기능입니다. 일반 텍스트 문자열 또는 SecretRef 객체({ source, provider, id })를 지원합니다.

​

참고

• entries 아래의 키는 기본적으로 Skills 이름에 매핑됩니다. Skills가 metadata.openclaw.skillKey를 정의하는 경우 그 키를 대신 사용하세요.
• 로드 우선순위는 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 번들된 Skills → skills.load.extraDirs입니다.
• 감시자가 활성화되어 있으면 Skills 변경 사항은 다음 에이전트 턴에 반영됩니다.

​

샌드박스 처리된 Skills와 환경 변수

• Docker 백엔드용 agents.defaults.sandbox.docker.env(또는 에이전트별 agents.list[].sandbox.docker.env).
• 사용자 지정 샌드박스 이미지 또는 원격 샌드박스 환경에 환경 변수를 포함합니다.

​

관련 항목