스킬 설정

모든 스킬 관련 설정은 ~/.openclaw/openclaw.json의 skills 아래에 있습니다.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (게이트웨이 런타임은 여전히 Node; bun은 비권장)
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 또는 평문 문자열
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

필드

• allowBundled: 번들 스킬에 대한 선택적 허용 목록. 설정 시 목록에 포함된 번들 스킬만 적용 가능 (관리/워크스페이스 스킬은 영향 없음).
• load.extraDirs: 스캔할 추가 스킬 디렉터리 (최저 우선순위).
• load.watch: 스킬 폴더를 감시하고 스킬 스냅샷을 갱신합니다 (기본값: true).
• load.watchDebounceMs: 스킬 감시자 이벤트 디바운스 시간 (밀리초, 기본값: 250).
• install.preferBrew: 가능한 경우 brew 설치 프로그램 선호 (기본값: true).
• install.nodeManager: node 설치 프로그램 선호도 (npm | pnpm | yarn | bun, 기본값: npm). 스킬 설치에만 영향을 미칩니다. 게이트웨이 런타임에는 여전히 Node를 사용해야 합니다 (WhatsApp/Telegram에는 Bun 비권장).
• entries.<skillKey>: 스킬별 재정의.

스킬별 필드:

• enabled: false로 설정하면 번들/설치된 스킬도 비활성화됩니다.
• env: 에이전트 실행에 주입되는 환경 변수 (이미 설정되지 않은 경우에만).
• apiKey: 기본 환경 변수를 선언하는 스킬을 위한 편의 기능. 평문 문자열 또는 SecretRef 객체({ source, provider, id })를 지원합니다.

참고

• entries 아래의 키는 기본적으로 스킬 이름에 매핑됩니다. 스킬이 metadata.openclaw.skillKey를 정의한 경우 해당 키를 사용하세요.
• 감시자가 활성화된 경우 스킬 변경은 다음 에이전트 턴에서 반영됩니다.

샌드박스 스킬 + 환경 변수

세션이 샌드박스된 경우, 스킬 프로세스는 Docker 내에서 실행됩니다. 샌드박스는 호스트 process.env를 상속하지 않습니다.

다음 중 하나를 사용하세요:

• agents.defaults.sandbox.docker.env (또는 에이전트별 agents.list[].sandbox.docker.env)
• 사용자 정의 샌드박스 이미지에 환경 변수 내장

전역 env와 skills.entries.<skill>.env/apiKey는 호스트 실행에만 적용됩니다.