Skills
Skills 구성
대부분의 Skills 구성은
~/.openclaw/openclaw.json의 skills 아래에 있습니다. 에이전트별 가시성은
agents.defaults.skills 및 agents.list[].skills 아래에 있습니다.
{ skills: { allowBundled: ["gemini", "peekaboo"], load: { extraDirs: ["~/Projects/agent-scripts/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], watch: true, watchDebounceMs: 250, }, install: { preferBrew: true, nodeManager: "npm", allowUploadedArchives: false, }, workshop: { autonomous: { enabled: false }, allowSymlinkTargetWrites: false, approvalPolicy: "pending", maxPending: 50, maxSkillBytes: 40000, }, entries: { "image-lab": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, sag: { enabled: false }, }, },}로딩(skills.load)
skills.load.extraDirsstring[]가장 낮은 우선순위에서 스캔할 추가 Skill 디렉터리입니다(번들 및
Plugin Skills 뒤). 경로는 ~ 지원과 함께 확장됩니다.
skills.load.allowSymlinkTargetsstring[]심볼릭 링크된 Skill 폴더가 구성된 루트 밖에 있더라도 해석될 수 있는
신뢰할 수 있는 실제 대상 디렉터리입니다. 다음과 같은 의도적인 형제 리포지터리
레이아웃에 사용하세요:
<workspace>/skills/manager -> ~/Projects/manager/skills. 이 목록은
좁게 유지하세요. ~ 또는 ~/Projects 같은 넓은 루트를 가리키지 마세요.
skills.load.watchbooleandefault: trueSkill 폴더를 감시하고 SKILL.md 파일이 변경되면 Skills 스냅샷을
새로 고칩니다. 그룹화된 Skill 루트 아래의 중첩 파일도 포함합니다.
skills.load.watchDebounceMsnumberdefault: 250Skill 감시자 이벤트의 디바운스 기간(밀리초)입니다.
설치(skills.install)
skills.install.preferBrewbooleandefault: truebrew를 사용할 수 있으면 Homebrew 설치 프로그램을 우선합니다.
skills.install.nodeManager"npm" | "pnpm" | "yarn" | "bun"default: "npm"Skill 설치에 사용할 Node 패키지 관리자 선호 설정입니다. 이는 Skill
설치에만 영향을 줍니다. Gateway 런타임은 계속 Node를 사용해야 합니다(Bun은
WhatsApp/Telegram에 권장되지 않습니다). npm, pnpm 또는 bun에는
openclaw setup --node-manager를 사용하고, Yarn 기반 Skill 설치에는
"yarn"을 수동으로 설정하세요.
skills.install.allowUploadedArchivesbooleandefault: false신뢰할 수 있는 operator.admin Gateway 클라이언트가 skills.upload.*를 통해
준비된 비공개 zip 아카이브를 설치하도록 허용합니다. 일반 ClawHub 설치에는
이 설정이 필요하지 않습니다.
운영자 설치 정책(security.installPolicy)
운영자가 호스트별 정책으로 Skill 및 Plugin 설치를 승인하거나 차단할
신뢰할 수 있는 로컬 명령이 필요할 때 security.installPolicy를 사용하세요.
이 정책은 OpenClaw가 소스 자료를 준비한 뒤, 설치 또는 업데이트가 계속되기 전에
실행됩니다. ClawHub Skills, 업로드된 Skills, Git/로컬 Skills,
Skill 의존성 설치 프로그램, Plugin 설치/업데이트 소스에 적용됩니다.
{ security: { installPolicy: { enabled: true, // Omit targets to cover every supported target. targets: ["skill", "plugin"], exec: { source: "exec", command: "/usr/local/bin/openclaw-install-policy", args: ["--json"], timeoutMs: 10000, noOutputTimeoutMs: 10000, maxOutputBytes: 1048576, passEnv: ["OPENCLAW_STATE_DIR", "PATH"], env: { POLICY_MODE: "strict" }, trustedDirs: ["/usr/local/bin"], }, }, },}security.installPolicy.enabledbooleandefault: false운영자 소유 설치 정책을 활성화합니다. 유효한 exec 명령 없이 활성화하면
설치가 닫힌 상태로 실패합니다.
security.installPolicy.targets("skill" | "plugin")[]선택적 대상 필터입니다. 생략하면 정책이 지원되는 모든 대상에 적용되어 새 설치가 예기치 않게 열린 상태로 실패하지 않게 합니다.
security.installPolicy.exec.commandstring신뢰할 수 있는 정책 실행 파일의 절대 경로입니다. OpenClaw는 셸 없이 실행하며 사용 전에 경로를 검증합니다.
security.installPolicy.exec.argsstring[]command 뒤에 전달되는 정적 인수입니다.
security.installPolicy.exec.timeoutMsnumberdefault: 10000하나의 정책 결정에 허용되는 최대 실제 실행 시간입니다.
security.installPolicy.exec.noOutputTimeoutMsnumberdefault: timeoutMs정책이 닫힌 상태로 실패하기 전까지 stdout 또는 stderr 출력 없이 허용되는 최대 시간입니다.
security.installPolicy.exec.maxOutputBytesnumberdefault: 1048576정책 프로세스에서 허용되는 stdout 및 stderr의 최대 합산 바이트 수입니다.
security.installPolicy.exec.env"Record<string,security.installPolicy.exec.passEnvstring[]OpenClaw 프로세스에서 정책 프로세스로 복사되는 환경 변수 이름입니다. 이름이 지정된 변수만 전달됩니다.
security.installPolicy.exec.trustedDirsstring[]정책 실행 파일을 포함할 수 있는 디렉터리의 선택적 허용 목록입니다.
security.installPolicy.exec.allowInsecurePathbooleandefault: false명령 경로 소유권 및 권한 검사를 우회합니다. 경로가 다른 메커니즘으로 보호되는 경우에만 사용하세요.
security.installPolicy.exec.allowSymlinkCommandbooleandefault: false구성된 명령 경로가 심볼릭 링크가 되도록 허용합니다. 해석된 대상은 여전히 다른 경로 검사를 충족해야 합니다. 인터프리터 스크립트 인수는 심볼릭 링크가 아니라 직접적인 일반 파일이어야 합니다.
정책은 stdin으로 protocolVersion: 1, openclawVersion, targetType,
targetName, sourcePath, sourcePathKind, 선택적 구조화된 source,
구조화된 origin, request가 포함된 JSON 객체 하나를 받습니다. stdout에는
JSON 객체 하나를 써야 합니다: { "protocolVersion": 1, "decision": "allow" } 또는
{ "protocolVersion": 1, "decision": "block", "reason": "..." }. 0이 아닌
종료, 타임아웃, 잘못된 JSON, 누락된 필드, 지원되지 않는 프로토콜 버전은
닫힌 상태로 실패합니다.
OpenClaw는 일반 Gateway 시작 중에는 설치 정책을 실행하지 않습니다. 정책이
활성화되어 있지만 사용할 수 없으면 설치 및 업데이트가 닫힌 상태로 실패합니다.
openclaw doctor는 정적 검증을 수행하고, openclaw doctor --deep은 구성된
명령에 대해 합성 설치 프로브를 실행합니다.
일괄 업데이트는 대상별로 정책을 적용합니다. 차단된 Skill 또는 Plugin 업데이트는 정책을 비활성화하거나 배치의 이후 대상을 건너뛰지 않고 해당 대상만 실패시킵니다.
stdin 예시:
{ "protocolVersion": 1, "openclawVersion": "2026.6.1", "targetType": "skill", "targetName": "weather", "sourcePath": "/var/folders/.../openclaw-skill-clawhub/root", "sourcePathKind": "directory", "source": { "kind": "clawhub", "authority": "openclaw", "mutable": false, "network": true }, "origin": { "type": "clawhub", "registry": "https://clawhub.openclaw.ai", "slug": "weather", "version": "1.0.0" }, "request": { "kind": "skill-install", "mode": "install", "requestedSpecifier": "clawhub:weather@1.0.0" }, "skill": { "installId": "clawhub" }}최소 정책 명령:
#!/usr/bin/env node let input = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => { input += chunk;});process.stdin.on("end", () => { const request = JSON.parse(input); if (request.targetType === "plugin" && request.source?.kind === "local-path") { process.stdout.write( JSON.stringify({ protocolVersion: 1, decision: "block", reason: "local plugin paths are not approved on this host", }), ); return; } process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));});번들 Skill 허용 목록
skills.allowBundledstring[]번들 Skills에만 적용되는 선택적 허용 목록입니다. 설정하면 목록에 있는 번들 Skills만 사용할 수 있습니다. 관리형, 에이전트 수준, 워크스페이스 Skills는 영향을 받지 않습니다.
Skill별 항목(skills.entries)
entries 아래의 키는 기본적으로 Skill name과 일치합니다. Skill이
metadata.openclaw.skillKey를 정의하면 대신 해당 키를 사용하세요. 하이픈이
포함된 이름은 따옴표로 감싸세요(JSON5는 따옴표로 감싼 키를 허용합니다).
OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk
.enabled" type="boolean">
false는 번들되었거나 설치된 경우에도 Skill을 비활성화합니다. coding-agent
번들 Skill은 옵트인입니다. 이를 true로 설정하고 claude,
codex, opencode 또는 지원되는 다른 CLI 중 하나가 설치되고 인증되어 있는지
확인하세요.
OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk
.apiKey" type='string | { source, provider, id }'>
metadata.openclaw.primaryEnv를 선언하는 Skills를 위한 편의 필드입니다.
평문 문자열 또는 SecretRef를 지원합니다: { source: "env", provider: "default", id: "VAR_NAME" }.
"skills.entries.<key �����r�"skills.entries.<key �w₫��ܩ에이전트 허용 목록(agents)
같은 머신/워크스페이스 Skill 루트를 사용하되 에이전트별로 다른 표시 Skill 집합을 원할 때 에이전트 구성을 사용하세요.
{ agents: { defaults: { skills: ["github", "weather"], // shared baseline }, list: [ { id: "writer" }, // inherits github, weather { id: "docs", skills: ["docs-search"] }, // replaces defaults entirely { id: "locked-down", skills: [] }, // no skills ], },}agents.defaults.skillsstring[]agents.list[].skills를 생략한 에이전트가 상속하는 공유 기준 허용 목록입니다.
기본적으로 Skills를 제한하지 않으려면 완전히 생략하세요.
agents.list[].skillsstring[]해당 에이전트의 명시적인 최종 Skill 집합입니다. 명시적 목록은 상속된
기본값을 대체하며 병합하지 않습니다. 해당 에이전트에 Skills를 노출하지
않으려면 []로 설정하세요.
Workshop(skills.workshop)
skills.workshop.autonomous.enabledbooleandefault: falsetrue이면 에이전트가 성공적인 턴 이후 지속적인 대화 신호에서 보류 중인
제안을 생성할 수 있습니다. 사용자가 프롬프트한 Skill 생성은 이 설정과
관계없이 항상 Skill Workshop을 거칩니다.
skills.workshop.approvalPolicy"pending" | "auto"default: "pending"pending은 agent가 시작한 적용, 거부 또는 격리 전에 운영자 승인을
요구합니다. auto는 승인 없이 해당 작업을 허용합니다.
skills.workshop.allowSymlinkTargetWritesbooleandefault: falseSkill Workshop 적용이 실제 대상이 이미 skills.load.allowSymlinkTargets에 의해
신뢰되는 workspace skill symlink를 통해 쓰도록 허용합니다. 생성된 제안 적용이
해당 공유 skill root를 변경해야 하는 경우가 아니면 이 설정을 비활성화 상태로
유지하세요.
skills.workshop.maxPendingnumberdefault: 50workspace당 보관되는 대기 중 및 격리된 제안의 최대 수입니다.
skills.workshop.maxSkillBytesnumberdefault: 40000최대 제안 본문 크기(바이트)입니다. 제안 설명은 탐색 및 목록 출력에 표시되므로 160바이트로 엄격히 제한됩니다.
symlink된 skill root
기본적으로 workspace, project-agent, extra-dir 및 번들된 skill root는
격리 경계입니다. 루트 외부로 해석되는 <workspace>/skills 아래의 symlink된
skill 폴더는 로그 메시지와 함께 건너뜁니다.
의도적인 symlink 레이아웃을 허용하려면 신뢰할 대상을 선언하세요.
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}이 config를 사용하면 <workspace>/skills/manager -> ~/Projects/manager/skills가
realpath 해석 후 허용됩니다. extraDirs는 sibling repo를 직접 스캔하고,
allowSymlinkTargets는 기존 레이아웃을 위해 symlink된 경로를 보존합니다.
Skill Workshop 적용은 기본적으로 이러한 symlink를 통해 쓰지 않습니다. Workshop 적용이 이미 신뢰된 symlink 대상 아래의 skills를 변경하도록 하려면 별도로 명시적으로 활성화하세요.
{ skills: { load: { allowSymlinkTargets: ["~/Projects/manager/skills"], }, workshop: { allowSymlinkTargetWrites: true, }, },}관리되는 ~/.openclaw/skills 및 개인 ~/.agents/skills 디렉터리는 이미
skill-directory symlink를 허용합니다(skill별 SKILL.md 격리는 여전히
적용됨).
샌드박스화된 skills 및 env vars
다음으로 Docker sandbox에 secret을 전달하세요.
{ agents: { defaults: { sandbox: { docker: { env: { GEMINI_API_KEY: "your-key-here" }, }, }, }, },}로드 순서 참고
workspace/skills (highest)workspace/.agents/skills~/.agents/skills~/.openclaw/skillsbundled skillsskills.load.extraDirs (lowest)watcher가 활성화된 경우 skills 및 config 변경은 다음 새 session에서 적용되며, watcher가 변경을 감지한 경우 다음 agent turn에서 적용됩니다.
