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: "auto", 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 설치에만
영향을 줍니다. 표준 상태 저장소가 node:sqlite을 사용하므로 OpenClaw CLI와
Gateway 런타임에는 Node가 필요합니다. openclaw setup --node-manager 및
openclaw onboard --node-manager은 npm, pnpm 또는
bun을 허용합니다. 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, // 지원되는 모든 대상을 포함하려면 targets를 생략합니다. 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에는 { "protocolVersion": 1, "decision": "allow" } 또는
{ "protocolVersion": 1, "decision": "block", "reason": "..." }이라는 하나의 JSON 객체를 작성해야 합니다. 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: "이 호스트에서는 로컬 Plugin 경로가 승인되지 않았습니다", }), ); 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"], // 공유 기준선 }, list: [ { id: "writer" }, // github, weather 상속 { id: "docs", skills: ["docs-search"] }, // 기본값을 완전히 대체 { id: "locked-down", skills: [] }, // Skills 없음 ], },}agents.defaults.skillsstring[]agents.list[].skills을 생략한 에이전트가 상속하는 공유 기준 허용 목록입니다.
기본적으로 Skills를 제한하지 않으려면 완전히 생략하십시오.
agents.list[].skillsstring[]해당 에이전트의 명시적인 최종 Skill 집합입니다. 명시적 목록은 상속된 기본값을
대체하며 병합하지 않습니다. 해당 에이전트에 어떤 Skills도 노출하지 않으려면
[]로 설정하십시오.
Workshop (skills.workshop)
skills.workshop.autonomous.enabledbooleandefault: falsetrue인 경우 OpenClaw는 지속적인 수정 사항으로부터 대기 중인 제안을 생성할 수 있으며,
시스템이 유휴 상태가 된 후 성공적으로 완료된 상당한 작업을 검토할 수 있습니다.
이로 인해 요건을 충족하는 턴 이후 백그라운드 모델 실행이 추가될 수 있습니다. 사용자가 요청한
스킬 생성과 /learn은 설정이 false인 경우에도 계속 작동합니다.
요건, 개인정보 보호, 비용, 제안 전용 권한 및 문제 해결에 대해서는 자기 학습을 참조하십시오.
skills.workshop.approvalPolicy"pending" | "auto"default: "auto"auto을 사용하면 추가 승인 메시지 없이 에이전트가 적용, 거부 또는 격리를
시작할 수 있습니다. pending은 운영자의 승인이 필요합니다.
skills.workshop.allowSymlinkTargetWritesbooleandefault: falseSkill Workshop 적용 시 실제 대상이 이미 skills.load.allowSymlinkTargets에서 신뢰되는
워크스페이스 스킬 심볼릭 링크를 통해 쓸 수 있도록 허용합니다. 생성된 제안을 적용할 때
해당 공유 스킬 루트를 변경해야 하는 경우가 아니면 이 설정을 비활성화한 상태로 유지하십시오.
skills.workshop.maxPendingnumberdefault: 50워크스페이스별로 보존되는 대기 및 격리된 제안의 최대 개수입니다(허용 범위: 1-200).
skills.workshop.maxSkillBytesnumberdefault: 40000제안 본문의 최대 크기(바이트)입니다(허용 범위: 1024-200000). 제안 설명은 탐색 및 목록 출력에 표시되므로 별도로 160바이트로 엄격히 제한됩니다.
이 구성이 제어하는 제안 수명 주기, CLI 명령, 에이전트 도구 매개변수 및 Gateway 메서드에 대해서는 Skill Workshop을 참조하십시오.
심볼릭 링크로 연결된 스킬 루트
기본적으로 워크스페이스, 프로젝트 에이전트, 추가 디렉터리 및 번들 스킬 루트는
포함 범위의 경계입니다. <workspace>/skills 아래에서 루트 외부로 해석되는
심볼릭 링크 스킬 폴더는 로그 메시지와 함께 건너뜁니다.
의도적인 심볼릭 링크 레이아웃을 허용하려면 신뢰할 대상을 선언하십시오.
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}이 구성을 사용하면 <workspace>/skills/manager -> ~/Projects/manager/skills은
실제 경로 확인 후 허용됩니다. extraDirs은 형제 저장소를
직접 스캔하고, allowSymlinkTargets은 기존 레이아웃을 위해 심볼릭 링크 경로를
유지합니다.
Skill Workshop 적용은 기본적으로 이러한 심볼릭 링크를 통해 쓰지 않습니다. Workshop 적용 시 이미 신뢰되는 심볼릭 링크 대상 아래의 스킬을 변경하도록 하려면 별도로 사용 설정하십시오.
{ skills: { load: { allowSymlinkTargets: ["~/Projects/manager/skills"], }, workshop: { allowSymlinkTargetWrites: true, }, },}관리형 ~/.openclaw/skills 및 개인용 ~/.agents/skills 디렉터리는
이미 스킬 디렉터리 심볼릭 링크를 조건 없이 허용합니다(스킬별
SKILL.md 포함 범위는 계속 적용됨). 따라서 allowSymlinkTargets은
워크스페이스, 추가 디렉터리 및 프로젝트 에이전트(<workspace>/.agents/skills)
루트에만 필요합니다.
샌드박스 스킬 및 환경 변수
다음과 같이 비밀 정보를 Docker 샌드박스에 전달하십시오.
{ agents: { defaults: { sandbox: { docker: { env: { GEMINI_API_KEY: "your-key-here" }, }, }, }, },}로드 순서 알림
workspace/skills (가장 높음)workspace/.agents/skills~/.agents/skills~/.openclaw/skills번들 스킬skills.load.extraDirs (가장 낮음)감시자가 활성화된 경우 스킬 및 구성 변경 사항은 다음 새 세션에서 적용되며, 감시자가 변경을 감지한 경우에는 다음 에이전트 턴에서 적용됩니다.
