Skills
پیکربندی Skills
بیشتر پیکربندی مهارتها زیر skills در
~/.openclaw/openclaw.json قرار دارد. قابلیت مشاهده ویژه هر عامل زیر
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[]دایرکتوریهای مهارت اضافی برای پویش، با پایینترین اولویت (پس از مهارتهای
داخلی و Plugin). مسیرها با پشتیبانی از ~ گسترش داده میشوند.
skills.load.allowSymlinkTargetsstring[]دایرکتوریهای هدف واقعی و مورد اعتماد که پوشههای مهارت symlinkشده میتوانند
به آنها resolve شوند، حتی وقتی symlink بیرون از root پیکربندیشده قرار دارد.
از این برای چیدمانهای عمدی repoهای همسطح مانند
<workspace>/skills/manager -> ~/Projects/manager/skills استفاده کنید. این فهرست
را محدود نگه دارید — به rootهای گستردهای مثل ~ یا ~/Projects اشاره نکنید.
skills.load.watchbooleandefault: trueپوشههای مهارت را پایش کنید و وقتی فایلهای SKILL.md تغییر میکنند،
snapshot مهارتها را تازهسازی کنید. فایلهای تودرتو زیر rootهای مهارت گروهبندیشده
را نیز پوشش میدهد.
skills.load.watchDebounceMsnumberdefault: 250پنجره debounce برای رویدادهای watcher مهارت، برحسب میلیثانیه.
نصب (skills.install)
skills.install.preferBrewbooleandefault: trueوقتی brew در دسترس است، نصبکنندههای Homebrew را ترجیح دهید.
skills.install.nodeManager"npm" | "pnpm" | "yarn" | "bun"default: "npm"ترجیح مدیر بسته Node برای نصب مهارتها. این فقط بر نصب مهارتها اثر میگذارد —
runtime مربوط به Gateway همچنان باید از Node استفاده کند (Bun برای
WhatsApp/Telegram توصیه نمیشود). برای npm، pnpm، یا bun از
openclaw setup --node-manager استفاده کنید؛ برای نصب مهارتهای مبتنی بر Yarn،
"yarn" را دستی تنظیم کنید.
skills.install.allowUploadedArchivesbooleandefault: falseبه کلاینتهای Gateway مورد اعتماد operator.admin اجازه دهید آرشیوهای zip خصوصی
را که از طریق skills.upload.* آماده شدهاند نصب کنند. نصبهای معمول ClawHub
به این تنظیم نیاز ندارند.
سیاست نصب اپراتور (security.installPolicy)
وقتی اپراتورها به یک فرمان محلی مورد اعتماد نیاز دارند تا نصب مهارت و Plugin را
با سیاست ویژه میزبان تأیید یا مسدود کند، از security.installPolicy استفاده کنید.
این سیاست پس از آن اجرا میشود که OpenClaw مواد منبع را آماده کرده و پیش از آنکه
نصب یا بهروزرسانی ادامه پیدا کند. این سیاست بر مهارتهای ClawHub، مهارتهای
بارگذاریشده، مهارتهای Git/محلی، نصبکنندههای وابستگی مهارت، و منابع نصب/بهروزرسانی
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مسیر مطلق به executable سیاست مورد اعتماد. OpenClaw آن را بدون shell اجرا میکند و مسیر را پیش از استفاده اعتبارسنجی میکند.
security.installPolicy.exec.argsstring[]آرگومانهای ثابت که پس از command ارسال میشوند.
security.installPolicy.exec.timeoutMsnumberdefault: 10000حداکثر runtime زمان دیواری برای یک تصمیم سیاست.
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[]allowlist اختیاری از دایرکتوریهایی که ممکن است executable سیاست را در خود داشته باشند.
security.installPolicy.exec.allowInsecurePathbooleandefault: falseبررسیهای مالکیت و مجوز مسیر فرمان را دور میزند. فقط وقتی استفاده کنید که مسیر با سازوکار دیگری محافظت میشود.
security.installPolicy.exec.allowSymlinkCommandbooleandefault: falseاجازه میدهد مسیر فرمان پیکربندیشده یک symlink باشد. هدف resolveشده همچنان باید سایر بررسیهای مسیر را برآورده کند. آرگومانهای اسکریپت مفسر باید فایلهای عادی مستقیم باشند، نه symlink.
این سیاست یک شیء JSON را روی stdin با protocolVersion: 1، openclawVersion،
targetType، targetName، sourcePath، sourcePathKind، source ساختاریافته
اختیاری، origin ساختاریافته، و request دریافت میکند. باید یک شیء JSON روی
stdout بنویسد: { "protocolVersion": 1, "decision": "allow" } یا
{ "protocolVersion": 1, "decision": "block", "reason": "..." }. خروج غیرصفر،
timeout، JSON بدشکل، فیلدهای گمشده، یا نسخههای protocol پشتیبانینشده بهصورت
بسته شکست میخورند.
OpenClaw در زمان startup معمول Gateway سیاست نصب را اجرا نمیکند. وقتی سیاست فعال
اما در دسترس نباشد، نصبها و بهروزرسانیها بهصورت بسته شکست میخورند.
openclaw doctor اعتبارسنجی ایستا انجام میدهد، و openclaw doctor --deep
یک پروب نصب ساختگی را در برابر فرمان پیکربندیشده اجرا میکند.
بهروزرسانیهای انبوه سیاست را برای هر هدف اعمال میکنند: بهروزرسانی مسدودشده یک مهارت یا Plugin همان هدف را شکست میدهد، بدون اینکه سیاست را غیرفعال کند یا هدفهای بعدی در batch را نادیده بگیرد.
نمونه 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" }));});allowlist مهارتهای داخلی
skills.allowBundledstring[]allowlist اختیاری فقط برای مهارتهای داخلی. وقتی تنظیم شود، فقط مهارتهای داخلی موجود در فهرست واجد شرایط هستند. مهارتهای مدیریتشده، سطح عامل، و workspace تحت تأثیر قرار نمیگیرند.
ورودیهای هر مهارت (skills.entries)
کلیدهای زیر entries بهطور پیشفرض با name مهارت مطابقت دارند. اگر یک مهارت
metadata.openclaw.skillKey را تعریف کند، بهجای آن از همان کلید استفاده کنید.
نامهای دارای خط تیره را quote کنید (JSON5 کلیدهای quoteشده را مجاز میداند).
OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk
.enabled" type="boolean">
false مهارت را حتی وقتی داخلی یا نصبشده باشد غیرفعال میکند. مهارت داخلی
coding-agent opt-in است — آن را روی true تنظیم کنید و مطمئن شوید یکی از
claude، codex، opencode، یا CLI پشتیبانیشده دیگری نصب و احراز هویت شده است.
OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk
.apiKey" type='string | { source, provider, id }'>
فیلد کمکی برای مهارتهایی که metadata.openclaw.primaryEnv را اعلام میکنند.
از یک رشته plaintext یا یک SecretRef پشتیبانی میکند: { source: "env", provider: "default", id: "VAR_NAME" }.
"skills.entries.<key �����r�"skills.entries.<key �w₫��ܩallowlistهای عامل (agents)
وقتی rootهای مهارت یکسانی برای machine/workspace میخواهید اما مجموعه مهارت قابل مشاهده متفاوتی برای هر عامل نیاز دارید، از پیکربندی عامل استفاده کنید.
{ 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[]allowlist پایه مشترک که عاملهایی که agents.list[].skills را حذف کردهاند
از آن ارث میبرند. برای اینکه مهارتها بهطور پیشفرض نامحدود بمانند، کاملاً حذف کنید.
agents.list[].skillsstring[]مجموعه مهارت نهایی صریح برای آن عامل. فهرستهای صریح defaultهای ارثبریشده را
جایگزین میکنند — merge نمیشوند. برای اینکه هیچ مهارتی برای آن عامل آشکار نشود،
روی [] تنظیم کنید.
کارگاه (skills.workshop)
skills.workshop.autonomous.enabledbooleandefault: falseوقتی true باشد، عاملها میتوانند پس از turnهای موفق، از سیگنالهای مکالمه
ماندگار proposalهای pending ایجاد کنند. ایجاد مهارت با prompt کاربر، صرفنظر از
این تنظیم، همیشه از کارگاه مهارت عبور میکند.
skills.workshop.approvalPolicy"pending" | "auto"default: "pending"pending پیش از اعمال، رد کردن یا قرنطینهای که توسط عامل آغاز شده باشد،
تأیید اپراتور را الزامی میکند. auto این اقدامات را بدون تأیید مجاز میکند.
skills.workshop.allowSymlinkTargetWritesbooleandefault: falseبه اعمال کارگاه مهارت اجازه دهید از طریق symlinkهای مهارت فضای کاری بنویسد
که مقصد واقعی آنها از پیش توسط skills.load.allowSymlinkTargets مورد اعتماد است. این گزینه را
غیرفعال نگه دارید مگر آنکه اعمال پیشنهادهای تولیدشده باید آن ریشه مهارت مشترک را
تغییر دهد.
skills.workshop.maxPendingnumberdefault: 50بیشترین تعداد پیشنهادهای در انتظار و قرنطینهشده که برای هر فضای کاری نگه داشته میشود.
skills.workshop.maxSkillBytesnumberdefault: 40000بیشترین اندازه بدنه پیشنهاد بر حسب بایت. توضیحات پیشنهاد بهطور سختگیرانه در 160 بایت محدود شدهاند، چون در خروجی کشف و فهرستگیری نمایش داده میشوند.
ریشههای مهارت symlinkشده
بهطور پیشفرض، ریشههای مهارت فضای کاری، عامل پروژه، دایرکتوری اضافه و بستهشده
مرزهای محصورسازی هستند. پوشه مهارت symlinkشده زیر <workspace>/skills
که به بیرون از ریشه resolve شود، با یک پیام لاگ نادیده گرفته میشود.
برای مجاز کردن یک چیدمان symlink عمدی، مقصد مورد اعتماد را اعلام کنید:
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}با این پیکربندی، <workspace>/skills/manager -> ~/Projects/manager/skills پس از
realpath resolution پذیرفته میشود. extraDirs مخزن همسطح را مستقیماً اسکن میکند؛
allowSymlinkTargets مسیر symlinkشده را برای چیدمانهای موجود حفظ میکند.
اعمال کارگاه مهارت بهطور پیشفرض از طریق آن symlinkها نمینویسد. برای اینکه Workshop apply بتواند مهارتهای زیر مقصدهای symlink از پیش مورد اعتماد را تغییر دهد، جداگانه opt in کنید:
{ skills: { load: { allowSymlinkTargets: ["~/Projects/manager/skills"], }, workshop: { allowSymlinkTargetWrites: true, }, },}دایرکتوریهای مدیریتشده ~/.openclaw/skills و شخصی ~/.agents/skills
از پیش symlinkهای دایرکتوری مهارت را میپذیرند (محصورسازی SKILL.md برای هر مهارت همچنان
اعمال میشود).
مهارتهای سندباکسشده و متغیرهای محیطی
رازها را با این پیکربندی به یک سندباکس Docker بدهید:
{ 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 فعال باشد، یا در نوبت بعدی عامل، وقتی watcher تغییری را تشخیص دهد، اعمال میشوند.
