پیکربندی Skills

بیشتر پیکربندی Skills زیر skills در ~/.openclaw/openclaw.json قرار دارد. قابلیت مشاهدهٔ مختص هر عامل زیر agents.defaults.skills و agents.entries.*.skills قرار دارد.

{  skills: {    allowBundled: ["gemini", "peekaboo"],    load: {      extraDirs: ["~/Projects/agent-scripts/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],      watch: true,    },    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.install)

خط‌مشی نصب اپراتور (security.installPolicy)

هنگامی که اپراتورها به یک فرمان محلی مورد اعتماد برای تأیید یا مسدودسازی نصب Skills و Plugins با خط‌مشی مختص میزبان نیاز دارند، از security.installPolicy استفاده کنید. خط‌مشی پس از آن اجرا می‌شود که OpenClaw محتوای منبع را آماده کرده و پیش از آن‌که نصب یا به‌روزرسانی ادامه یابد. این خط‌مشی بر Skills مربوط به ClawHub، Skills بارگذاری‌شده، Skills مربوط به Git/محلی، نصب‌کننده‌های وابستگی 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"],      },    },  },}

خط‌مشی یک شیء JSON را در stdin دریافت می‌کند که شامل protocolVersion: 1، openclawVersion، targetType، targetName، sourcePath، sourcePathKind، source ساختاریافتهٔ اختیاری، origin ساختاریافته و request است. باید یک شیء JSON را در stdout بنویسد: { "protocolVersion": 1, "decision": "allow" } یا { "protocolVersion": 1, "decision": "block", "reason": "..." }. خروج با کد غیرصفر، پایان مهلت، 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" }));});

فهرست مجاز Skills همراه

ورودی‌های هر Skill (skills.entries)

کلیدهای زیر entries به‌طور پیش‌فرض با name مربوط به Skill مطابقت دارند. اگر یک Skill مقدار metadata.openclaw.skillKey را تعریف می‌کند، به‌جای آن از همان کلید استفاده کنید. نام‌های دارای خط تیره را درون نقل‌قول قرار دهید (JSON5 کلیدهای نقل‌قول‌شده را می‌پذیرد).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk .enabled" type="boolean"> false حتی در صورت همراه یا نصب‌شده بودن Skill، آن را غیرفعال می‌کند. Skill همراه coding-agent نیازمند فعال‌سازی صریح است — آن را روی true تنظیم کنید و مطمئن شوید یکی از claude، codex، opencode یا یک CLI پشتیبانی‌شدهٔ دیگر نصب و احراز هویت شده است.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk .apiKey" type='string | { source, provider, id }'> فیلد کمکی برای Skills که metadata.openclaw.primaryEnv را اعلام می‌کنند. از یک رشتهٔ متن ساده یا SecretRef پشتیبانی می‌کند: { source: "env", provider: "default", id: "VAR_NAME" }.

فهرست‌های مجاز عامل (agents)

هنگامی از پیکربندی عامل استفاده کنید که می‌خواهید ریشه‌های Skill ماشین/فضای کاری یکسان باشند، اما مجموعهٔ Skills قابل مشاهده برای هر عامل متفاوت باشد.

{  agents: {    defaults: {      skills: ["github", "weather"], // خط پایهٔ مشترک    },    list: [      { id: "writer" }, // github و weather را به ارث می‌برد      { id: "docs", skills: ["docs-search"] }, // پیش‌فرض‌ها را کاملاً جایگزین می‌کند      { id: "locked-down", skills: [] }, // بدون Skill    ],  },}

Workshop (skills.workshop)

برای معیارهای واجد شرایط بودن، حریم خصوصی، هزینه، مجوزهای صرفاً پیشنهادی و عیب‌یابی، به خودآموزی مراجعه کنید.

برای چرخهٔ عمر پیشنهاد، فرمان‌های CLI، پارامترهای ابزار عامل و روش‌های Gateway که این پیکربندی کنترل می‌کند، به Skill Workshop مراجعه کنید.

ریشه‌های Skill دارای پیوند نمادین

به‌طور پیش‌فرض، ریشه‌های Skill مربوط به فضای کاری، عامل پروژه، دایرکتوری اضافی و Skillهای همراه، مرزهای محصورسازی هستند. پوشهٔ Skill دارای پیوند نمادین زیر <workspace>/skills که به بیرون از ریشه منتهی شود، همراه با یک پیام گزارش نادیده گرفته می‌شود.

برای مجاز کردن یک چیدمان عمدی پیوند نمادین، هدف مورد اعتماد را اعلام کنید:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

با این پیکربندی، <workspace>/skills/manager -> ~/Projects/manager/skills پس از تفکیک realpath پذیرفته می‌شود. extraDirs مخزن هم‌سطح را مستقیماً اسکن می‌کند؛ allowSymlinkTargets مسیر دارای پیوند نمادین را برای چیدمان‌های موجود حفظ می‌کند.

اعمال Skill Workshop به‌طور پیش‌فرض از طریق این پیوندهای نمادین نمی‌نویسد. برای اینکه اعمال Workshop بتواند Skillهای زیر اهداف پیوند نمادینِ از قبل مورد اعتماد را تغییر دهد، جداگانه آن را فعال کنید:

{  skills: {    load: {      allowSymlinkTargets: ["~/Projects/manager/skills"],    },    workshop: {      allowSymlinkTargetWrites: true,    },  },}

دایرکتوری‌های مدیریت‌شدهٔ ~/.openclaw/skills و شخصیِ ~/.agents/skills از قبل پیوندهای نمادین دایرکتوری Skill را بدون شرط می‌پذیرند (محصورسازی SKILL.md برای هر Skill همچنان اعمال می‌شود) — allowSymlinkTargets فقط برای ریشه‌های فضای کاری، دایرکتوری اضافی و عامل پروژه (<workspace>/.agents/skills) لازم است.

Skillهای سندباکس‌شده و متغیرهای محیطی

اطلاعات محرمانه را به این شکل به یک سندباکس Docker منتقل کنید:

{  agents: {    defaults: {      sandbox: {        docker: {          env: { GEMINI_API_KEY: "your-key-here" },        },      },    },  },}

یادآوری ترتیب بارگذاری

workspace/skills      (بالاترین)workspace/.agents/skills~/.agents/skills~/.openclaw/skillsSkillهای همراهskills.load.extraDirs (پایین‌ترین)

وقتی ناظر فعال باشد، تغییرات Skillها و پیکربندی در نشست جدید بعدی اعمال می‌شوند؛ یا وقتی ناظر تغییری را تشخیص دهد، در نوبت بعدی عامل اعمال می‌شوند.

مرتبط