پیکربندی 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.install)

سیاست نصب اپراتور (security.installPolicy)

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

سیاست یک شیء 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: "local plugin paths are not approved on this host",      }),    );    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)

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

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

کارگاه (skills.workshop)

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

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

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

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

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

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

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

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

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

Skills محصورشده و متغیرهای محیطی

مقادیر محرمانه را با روش زیر به محیط محصور Docker منتقل کنید:

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

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

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

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

مرتبط