پیکربندی Skills

بیشتر پیکربندی بارگذار/نصب Skills زیر skills در ~/.openclaw/openclaw.json قرار دارد. قابلیت مشاهده Skills مخصوص هر عامل زیر agents.defaults.skills و agents.list[].skills قرار دارد.

{  skills: {    allowBundled: ["gemini", "peekaboo"],    load: {      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],      watch: true,      watchDebounceMs: 250,    },    install: {      preferBrew: true,      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)      allowUploadedArchives: false,    },    entries: {      "image-lab": {        enabled: true,        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string        env: {          GEMINI_API_KEY: "GEMINI_KEY_HERE",        },      },      peekaboo: { enabled: true },      sag: { enabled: false },    },  },}

برای تولید/ویرایش تصویر داخلی، agents.defaults.imageGenerationModel به‌همراه ابزار هسته‌ای image_generate را ترجیح دهید. skills.entries.* فقط برای گردش‌کارهای Skills سفارشی یا شخص ثالث است.

اگر ارائه‌دهنده/مدل تصویر مشخصی را انتخاب می‌کنید، کلید احراز هویت/API همان ارائه‌دهنده را نیز پیکربندی کنید. نمونه‌های رایج: GEMINI_API_KEY یا GOOGLE_API_KEY برای google/*، OPENAI_API_KEY برای openai/*، و FAL_KEY برای fal/*.

نمونه‌ها:

• پیکربندی بومی به سبک Nano Banana Pro: agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"
• پیکربندی بومی fal: agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

فهرست‌های مجاز Skills عامل

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

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits defaults -> github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no skills    ],  },}

قوانین:

• agents.defaults.skills: فهرست مجاز پایه مشترک برای عامل‌هایی که agents.list[].skills را حذف کرده‌اند.
• برای اینکه Skills به‌طور پیش‌فرض نامحدود بماند، agents.defaults.skills را حذف کنید.
• agents.list[].skills: مجموعه نهایی و صریح Skills برای آن عامل؛ با پیش‌فرض‌ها ادغام نمی‌شود.
• agents.list[].skills: []: هیچ Skillsی را برای آن عامل در معرض استفاده قرار ندهید.

فیلدها

• ریشه‌های داخلی Skills همیشه شامل ~/.openclaw/skills، ~/.agents/skills، <workspace>/.agents/skills و <workspace>/skills هستند.
• allowBundled: فهرست مجاز اختیاری فقط برای Skills بسته‌بندی‌شده. وقتی تنظیم شود، فقط Skills بسته‌بندی‌شده موجود در فهرست واجد شرایط هستند (Skills مدیریت‌شده، عامل و فضای کاری تحت تأثیر نیستند).
• load.extraDirs: دایرکتوری‌های اضافی Skills برای اسکن (کمترین تقدم).
• load.allowSymlinkTargets: دایرکتوری‌های مقصد واقعی و مورد اعتماد که پوشه‌های Skills دارای پیوند نمادین می‌توانند به آن‌ها resolve شوند، حتی وقتی پیوند نمادین خارج از آن ریشه مقصد قرار دارد. از این برای چیدمان‌های عمدی مخزن‌های هم‌سطح مانند ~/.agents/skills/manager -> ~/Projects/manager/skills استفاده کنید.
• load.watch: پوشه‌های Skills را رصد کن و snapshot مربوط به Skills را نوسازی کن (پیش‌فرض: true).
• load.watchDebounceMs: debounce برای رویدادهای watcher مربوط به Skills بر حسب میلی‌ثانیه (پیش‌فرض: 250).
• install.preferBrew: نصب‌کننده‌های brew را در صورت وجود ترجیح بده (پیش‌فرض: true).
• install.nodeManager: ترجیح نصب‌کننده node (npm | pnpm | yarn | bun، پیش‌فرض: npm). این فقط بر نصب‌های Skills اثر می‌گذارد؛ runtime مربوط به Gateway همچنان باید Node باشد (Bun برای WhatsApp/Telegram توصیه نمی‌شود).
  • openclaw setup --node-manager محدودتر است و در حال حاضر npm، pnpm یا bun را می‌پذیرد. اگر نصب‌های Skills مبتنی بر Yarn می‌خواهید، skills.install.nodeManager: "yarn" را به‌صورت دستی تنظیم کنید.
• install.allowUploadedArchives: به کلاینت‌های Gateway مورد اعتماد operator.admin اجازه بده آرشیوهای zip خصوصی را که از طریق skills.upload.* مرحله‌بندی شده‌اند نصب کنند (پیش‌فرض: false). این فقط مسیر آرشیو آپلودشده را فعال می‌کند؛ نصب‌های معمول ClawHub به آن نیاز ندارند.
• entries.<skillKey>: overrideهای مخصوص هر Skill.
• agents.defaults.skills: فهرست مجاز پیش‌فرض و اختیاری Skills که عامل‌هایی که agents.list[].skills را حذف می‌کنند آن را به ارث می‌برند.
• agents.list[].skills: فهرست مجاز نهایی و اختیاری Skills برای هر عامل؛ فهرست‌های صریح به‌جای ادغام، پیش‌فرض‌های به‌ارث‌رسیده را جایگزین می‌کنند.

مخزن‌های هم‌سطح دارای پیوند نمادین

به‌طور پیش‌فرض، هر ریشه Skills یک مرز containment است. اگر پوشه‌ای از Skills زیر ~/.agents/skills یک پیوند نمادین باشد که به بیرون از ~/.agents/skills resolve شود، OpenClaw از آن صرف‌نظر می‌کند و Skipping escaped skill path outside its configured root را ثبت می‌کند.

چیدمان پیوند نمادین را نگه دارید و فقط ریشه مقصد مورد اعتماد را مجاز کنید:

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

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

فیلدهای مخصوص هر Skill:

• enabled: برای غیرفعال کردن یک Skill حتی اگر بسته‌بندی/نصب شده باشد، false تنظیم کنید.
• env: متغیرهای محیطی تزریق‌شده برای اجرای عامل (فقط اگر از قبل تنظیم نشده باشند).
• apiKey: میانبر اختیاری برای Skillsی که یک متغیر محیطی اصلی اعلام می‌کنند. از رشته متن ساده یا شیء SecretRef ({ source, provider, id }) پشتیبانی می‌کند.

نکته‌ها

• کلیدهای زیر entries به‌طور پیش‌فرض به نام Skill نگاشت می‌شوند. اگر یک Skill metadata.openclaw.skillKey را تعریف کند، به‌جای آن از همان کلید استفاده کنید.
• تقدم بارگذاری به این صورت است: <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → Skills بسته‌بندی‌شده → skills.load.extraDirs.
• وقتی watcher فعال باشد، تغییرات Skills در نوبت بعدی عامل دریافت می‌شوند.

Skills سندباکس‌شده و متغیرهای env

وقتی یک نشست سندباکس‌شده است، فرایندهای Skills داخل backend سندباکس پیکربندی‌شده اجرا می‌شوند. سندباکس process.env میزبان را به ارث نمی‌برد.

از یکی از این‌ها استفاده کنید:

• agents.defaults.sandbox.docker.env برای backend مربوط به Docker (یا agents.list[].sandbox.docker.env برای هر عامل).
• env را در تصویر سندباکس سفارشی یا محیط سندباکس راه دور خود bake کنید.

مرتبط