OpenClaw Skills 설정 가이드: 커스텀 스킬 및 환경 변수 관리

개발을 하다 보면 여러 에이전트나 프로젝트마다 필요한 기능을 일일이 관리하는 게 참 번거롭죠. 특히 환경마다 스킬을 다르게 적용해야 할 때 설정이 꼬여서 고생한 경험, 다들 한 번쯤 있으실 겁니다.

OpenClaw는 OpenClaw의 스킬 설정 및 관리 기능을 통해 이러한 복잡함을 해결해 줍니다. ~/.openclaw/openclaw.json 파일 하나로 스킬 로더와 설치 옵션을 깔끔하게 제어해 보세요.

스킬 설정 구성

대부분의 스킬 로더 및 설치 관련 설정은 ~/.openclaw/openclaw.json 파일의 skills 항목에서 관리합니다. 에이전트별 스킬 가시성은 agents.defaults.skills와 agents.list[].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 (Gateway runtime still Node; bun not recommended)
    },
    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 },
    },
  },
}

내장된 이미지 생성이나 편집 기능을 사용하려면 agents.defaults.imageGenerationModel과 핵심 image_generate 툴을 우선적으로 사용하세요. skills.entries.*는 커스텀 스킬이나 서드파티 스킬 워크플로우를 위한 공간입니다.

특정 이미지 제공자나 모델을 선택했다면, 해당 제공자의 인증 정보나 API 키도 함께 설정해야 합니다. 일반적인 예시로는 google/*를 위한 GEMINI_API_KEY 또는 GOOGLE_API_KEY, openai/*를 위한 OPENAI_API_KEY, 그리고 fal/*를 위한 FAL_KEY 등이 있습니다.

예시:

• Native Nano Banana 스타일 설정: agents.defaults.imageGenerationModel.primary: "google/gemini-3.1-flash-image-preview"
• Native fal 설정: agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

에이전트 스킬 허용 목록

동일한 머신이나 워크스페이스의 스킬 루트를 사용하면서, 에이전트마다 서로 다른 스킬을 노출하고 싶을 때 에이전트 설정을 활용하세요.

{
  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
    ],
  },
}

규칙:

1. agents.defaults.skills: agents.list[].skills를 생략한 에이전트들이 공유하는 기본 허용 목록입니다.
2. agents.defaults.skills를 생략하면 기본적으로 모든 스킬이 제한 없이 허용됩니다.
3. agents.list[].skills: 해당 에이전트를 위한 최종 스킬 세트이며, 기본값과 병합되지 않고 완전히 대체됩니다.
4. agents.list[].skills: []: 해당 에이전트에게 어떤 스킬도 노출하지 않습니다.

필드

각 설정 항목은 스킬의 동작 방식과 설치 환경을 세밀하게 조정합니다.

1. 내장 스킬 루트는 항상 ~/.openclaw/skills, ~/.agents/skills, <workspace>/.agents/skills, 그리고 <workspace>/skills를 포함합니다.
2. allowBundled: bundled 스킬에만 적용되는 선택적 허용 목록입니다. 설정 시 목록에 포함된 bundled 스킬만 사용 가능합니다(관리형, 에이전트, 워크스페이스 스킬은 영향을 받지 않습니다).
3. load.extraDirs: 스캔할 추가 스킬 디렉토리입니다(우선순위가 가장 낮습니다).
4. load.watch: 스킬 폴더를 감시하고 스킬 스냅샷을 새로고침합니다(기본값: true).
5. load.watchDebounceMs: 스킬 감시 이벤트에 대한 디바운스 시간(밀리초 단위, 기본값: 250).
6. install.preferBrew: 사용 가능한 경우 brew 설치 프로그램을 우선 사용합니다(기본값: true).
7. install.nodeManager: Node.js 설치 프로그램 선호도(npm | pnpm | yarn | bun, 기본값: npm). 이는 스킬 설치에만 영향을 주며, Gateway 런타임은 여전히 Node.js여야 합니다(WhatsApp/Telegram의 경우 bun은 권장하지 않습니다).
   • openclaw setup --node-manager는 더 제한적이며 현재 npm, pnpm, bun을 지원합니다. Yarn 기반의 스킬 설치를 원하면 skills.install.nodeManager: "yarn"을 수동으로 설정하세요.
8. entries.<skillKey>: 스킬별 재정의 설정입니다.
9. agents.defaults.skills: agents.list[].skills를 생략한 에이전트가 상속받는 선택적 기본 스킬 허용 목록입니다.
10. agents.list[].skills: 에이전트별 최종 스킬 허용 목록이며, 명시된 목록이 상속된 기본값을 대체합니다.

스킬별 필드:

1. enabled: false로 설정하면 bundled되거나 설치된 스킬이라도 비활성화됩니다.
2. env: 에이전트 실행 시 주입되는 환경 변수입니다(이미 설정되지 않은 경우에만 적용).
3. apiKey: 기본 환경 변수를 선언하는 스킬을 위한 편리한 옵션입니다. 일반 텍스트 문자열이나 SecretRef 객체({ source, provider, id })를 지원합니다.

참고 사항

설정 시 로드 우선순위와 샌드박스 환경에서의 동작 방식을 이해하는 것이 중요합니다.

1. entries 아래의 키는 기본적으로 스킬 이름에 매핑됩니다. 스킬이 metadata.openclaw.skillKey를 정의했다면 해당 키를 대신 사용하세요.
2. 로드 우선순위는 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/openclaw.json → bundled 스킬 → skills.load.extraDirs 순입니다.
3. 스킬 변경 사항은 감시 기능이 활성화된 경우 다음 에이전트 턴에서 즉시 반영됩니다.

샌드박스 스킬 + 환경 변수

세션이 sandboxed 상태일 때, 스킬 프로세스는 설정된 샌드박스 백엔드 내부에서 실행됩니다. 샌드박스는 호스트의 process.env를 상속받지 않습니다.

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

1. Docker 백엔드를 위한 agents.defaults.sandbox.docker.env (또는 에이전트별 agents.list[].sandbox.docker.env)
2. 커스텀 샌드박스 이미지나 원격 샌드박스 환경에 환경 변수를 직접 포함

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

---

더 궁금한 점이 있다면 AI Setup Assistant를 통해 도움을 받아보세요!

다음 단계

• 에이전트 설정 가이드
• 스킬 개발 및 배포
• GitHub 연동 설정