Skills

Skills

Skills فایل‌های دستورالعملی Markdown هستند که به عامل یاد می‌دهند چگونه و چه زمانی از ابزارها استفاده کند. هر Skill در یک پوشه قرار دارد که شامل فایل SKILL.md با frontmatter از نوع YAML و بدنه Markdown است. OpenClaw، Skills همراه بسته و هر بازنویسی محلی را بارگذاری می‌کند و در زمان بارگذاری، آن‌ها را بر اساس محیط، پیکربندی و وجود باینری فیلتر می‌کند.

ترتیب بارگذاری

OpenClaw از این منابع بارگذاری می‌کند، با بالاترین تقدم در ابتدا. وقتی نام یک Skill در چند محل ظاهر شود، منبع با بالاترین تقدم برنده می‌شود.

اولویت منبع مسیر
۱ — بالاترین Skills فضای کاری <workspace>/skills
۲ Skills عامل پروژه <workspace>/.agents/skills
۳ Skills عامل شخصی ~/.agents/skills
۴ Skills مدیریت‌شده / محلی ~/.openclaw/skills
۵ Skills همراه بسته همراه نصب ارائه می‌شود
۶ — پایین‌ترین پوشه‌های اضافی skills.load.extraDirs + Skills مربوط به Plugin

ریشه‌های Skill از چیدمان‌های گروه‌بندی‌شده پشتیبانی می‌کنند. OpenClaw هر زمان SKILL.md در هر جایی زیر یک ریشه پیکربندی‌شده ظاهر شود، یک Skill را کشف می‌کند:

text
<workspace>/skills/research/SKILL.md          ✓ found as "research"<workspace>/skills/personal/research/SKILL.md ✓ also found as "research"

مسیر پوشه فقط برای سازمان‌دهی است. نام Skill، دستور slash و کلید فهرست مجاز همگی از فیلد frontmatter با نام name می‌آیند (یا وقتی name وجود ندارد، از نام پوشه).

Skills مختص هر عامل در برابر Skills مشترک

در راه‌اندازی‌های چندعاملی، هر عامل فضای کاری خودش را دارد. از مسیری استفاده کنید که با میزان دیدپذیری دلخواه شما سازگار است:

دامنه مسیر قابل مشاهده برای
مختص هر عامل <workspace>/skills فقط همان عامل
عامل پروژه <workspace>/.agents/skills فقط عامل همان فضای کاری
عامل شخصی ~/.agents/skills همه عامل‌های این دستگاه
مدیریت‌شده مشترک ~/.openclaw/skills همه عامل‌های این دستگاه
پوشه‌های اضافی skills.load.extraDirs همه عامل‌های این دستگاه

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

محل Skill (تقدم) و دیدپذیری Skill (اینکه کدام عامل می‌تواند از آن استفاده کند) کنترل‌های جداگانه‌ای هستند. از فهرست‌های مجاز برای محدود کردن Skills قابل مشاهده برای یک عامل استفاده کنید، فارغ از اینکه از کجا بارگذاری شده‌اند.

json5
{  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    ],  },}
Allowlist rules
  • برای اینکه همه Skills به‌صورت پیش‌فرض نامحدود باشند، agents.defaults.skills را حذف کنید.
  • برای به ارث بردن agents.defaults.skills، مقدار agents.list[].skills را حذف کنید.
  • برای اینکه هیچ Skill برای آن عامل ارائه نشود، agents.list[].skills: [] را تنظیم کنید.
  • یک فهرست غیرخالی agents.list[].skills مجموعه نهایی است — با پیش‌فرض‌ها ادغام نمی‌شود.
  • فهرست مجاز مؤثر در ساخت prompt، کشف دستورهای slash، همگام‌سازی sandbox و snapshotهای Skill اعمال می‌شود.
  • این مرز مجوزدهی پوسته میزبان نیست. اگر همان عامل می‌تواند از exec استفاده کند، آن پوسته را جداگانه با sandboxing، جداسازی کاربر سیستم‌عامل، فهرست‌های رد/مجاز exec و اعتبارنامه‌های مختص هر منبع محدود کنید.

Pluginها و Skills

Pluginها می‌توانند با فهرست کردن پوشه‌های skills در openclaw.plugin.json (مسیرها نسبت به ریشه Plugin)، Skills خودشان را ارائه کنند. Skills مربوط به Plugin وقتی Plugin فعال باشد بارگذاری می‌شوند — برای مثال، Plugin مرورگر یک Skill با نام browser-automation برای کنترل چندمرحله‌ای مرورگر ارائه می‌کند.

پوشه‌های Skill مربوط به Plugin در همان سطح کم‌تقدم skills.load.extraDirs ادغام می‌شوند، بنابراین یک Skill همراه بسته، مدیریت‌شده، عامل یا فضای کاری با همان نام، آن‌ها را بازنویسی می‌کند. آن‌ها را از طریق metadata.openclaw.requires.config روی ورودی پیکربندی Plugin محدود کنید.

برای سامانه کامل Plugin، Pluginها و ابزارها را ببینید.

Skill Workshop

Skill Workshop صف پیشنهادی میان عامل و فایل‌های Skill فعال شماست. وقتی عامل کار قابل استفاده مجددی را تشخیص دهد، به‌جای نوشتن مستقیم در SKILL.md یک پیشنهاد تهیه می‌کند. شما پیش از هر تغییری آن را بازبینی و تأیید می‌کنید.

bash
openclaw skills workshop listopenclaw skills workshop inspect <proposal-id>openclaw skills workshop apply <proposal-id>

برای چرخه عمر کامل، مرجع CLI و پیکربندی، Skill Workshop را ببینید.

نصب از ClawHub

ClawHub رجیستری عمومی Skills است. برای نصب و به‌روزرسانی از دستورهای openclaw skills استفاده کنید، یا برای انتشار و همگام‌سازی از CLI clawhub استفاده کنید.

کنش دستور
نصب یک Skill در فضای کاری openclaw skills install @owner/<slug>
نصب از یک مخزن Git openclaw skills install git:owner/repo@ref
نصب یک پوشه Skill محلی openclaw skills install ./path/to/skill --as my-tool
نصب برای همه عامل‌های محلی openclaw skills install @owner/<slug> --global
به‌روزرسانی همه Skills فضای کاری openclaw skills update --all
به‌روزرسانی یک Skill مدیریت‌شده مشترک openclaw skills update @owner/<slug> --global
به‌روزرسانی همه Skills مدیریت‌شده مشترک openclaw skills update --all --global
بررسی پوشش اعتماد یک Skill openclaw skills verify @owner/<slug>
چاپ Skill Card تولیدشده openclaw skills verify @owner/<slug> --card
انتشار / همگام‌سازی از طریق CLI ClawHub clawhub sync --all
Install details

openclaw skills install به‌صورت پیش‌فرض در پوشه skills/ فضای کاری فعال نصب می‌کند. برای نصب در پوشه مشترک ~/.openclaw/skills، که برای همه عامل‌های محلی قابل مشاهده است مگر اینکه فهرست‌های مجاز عامل آن را محدود کنند، --global را اضافه کنید.

نصب‌های Git و محلی انتظار دارند SKILL.md در ریشه منبع باشد. slug ابتدا از frontmatter فایل SKILL.md و فیلد name در صورت معتبر بودن گرفته می‌شود، سپس به نام پوشه یا مخزن برمی‌گردد. برای بازنویسی از --as <slug> استفاده کنید. openclaw skills update فقط نصب‌های ClawHub را دنبال می‌کند — برای تازه‌سازی منابع Git یا محلی، آن‌ها را دوباره نصب کنید.

Verification and security scanning

openclaw skills verify @owner/<slug> از ClawHub پوشش اعتماد clawhub.skill.verify.v1 مربوط به Skill را درخواست می‌کند. Skills نصب‌شده از ClawHub در برابر نسخه و رجیستری ثبت‌شده در .clawhub/origin.json بررسی می‌شوند. slugهای تنها برای Skills نصب‌شده موجود یا بدون ابهام همچنان پذیرفته می‌شوند، اما ارجاع‌های دارای owner از ابهام ناشر جلوگیری می‌کنند.

صفحه‌های Skill در ClawHub تازه‌ترین وضعیت اسکن امنیتی را پیش از نصب نشان می‌دهند، همراه با صفحه‌های جزئیات برای VirusTotal، ClawScan و تحلیل ایستا. وقتی ClawHub بررسی را ناموفق علامت‌گذاری کند، دستور با وضعیت غیرصفر خارج می‌شود. ناشران false positiveها را از طریق داشبورد ClawHub یا clawhub skill rescan @owner/<slug> برطرف می‌کنند.

Private archive installs

کلاینت‌های Gateway که به تحویل خارج از ClawHub نیاز دارند می‌توانند یک آرشیو zip از Skill را با skills.upload.begin، skills.upload.chunk و skills.upload.commit آماده کنند، سپس با skills.install({ source: "upload", ... }) نصب کنند. این مسیر به‌صورت پیش‌فرض غیرفعال است و به skills.install.allowUploadedArchives: true در openclaw.json نیاز دارد. نصب‌های عادی ClawHub هرگز به آن تنظیم نیاز ندارند.

امنیت

Path containment

کشف Skill در فضای کاری، عامل پروژه و پوشه‌های اضافی فقط ریشه‌های Skill را می‌پذیرد که realpath حل‌شده آن‌ها داخل ریشه پیکربندی‌شده بماند، مگر اینکه skills.load.allowSymlinkTargets به‌طور صریح به یک ریشه مقصد اعتماد کند. Skill Workshop فقط وقتی skills.workshop.allowSymlinkTargetWrites فعال باشد از طریق آن مقصدهای مورد اعتماد می‌نویسد. پوشه‌های مدیریت‌شده ~/.openclaw/skills و شخصی ~/.agents/skills ممکن است شامل پوشه‌های Skill symlinkشده باشند، اما realpath هر SKILL.md همچنان باید داخل پوشه Skill حل‌شده خودش بماند.

Operator install policy

security.installPolicy را پیکربندی کنید تا پیش از ادامه نصب Skill، یک دستور سیاست محلی مورد اعتماد اجرا شود. این سیاست metadata و مسیر منبع آماده‌شده را دریافت می‌کند، برای مسیرهای ClawHub، آپلودشده، Git، محلی، به‌روزرسانی و نصب‌کننده وابستگی اعمال می‌شود و وقتی دستور نتواند تصمیم معتبری برگرداند، بسته و ناموفق می‌شود.

Secret injection scope

skills.entries.*.env و skills.entries.*.apiKey اسرار را فقط برای همان نوبت عامل به فرایند میزبان تزریق می‌کنند — نه به sandbox. اسرار را از promptها و logها دور نگه دارید.

برای مدل تهدید گسترده‌تر و چک‌لیست‌های امنیتی، امنیت را ببینید.

قالب SKILL.md

هر Skill حداقل به یک name و description در frontmatter نیاز دارد:

markdown
---name: image-labdescription: Generate or edit images via a provider-backed image workflow--- When the user asks to generate an image, use the `image_generate` tool...

کلیدهای اختیاری frontmatter

homepagestring

URL که در رابط کاربری macOS Skills به‌صورت "Website" نمایش داده می‌شود. از طریق metadata.openclaw.homepage نیز پشتیبانی می‌شود.

user-invocablebooleandefault: true

وقتی true باشد، Skill به‌صورت یک دستور slash قابل فراخوانی توسط کاربر ارائه می‌شود.

disable-model-invocationbooleandefault: false

وقتی true باشد، OpenClaw دستورالعمل‌های Skill را از prompt عادی عامل بیرون نگه می‌دارد. وقتی user-invocable نیز true باشد، Skill همچنان به‌صورت دستور slash در دسترس است.

command-dispatch"tool"

وقتی روی tool تنظیم شود، دستور slash مدل را دور می‌زند و مستقیماً به یک ابزار ثبت‌شده dispatch می‌شود.

command-toolstring

نام ابزاری که وقتی command-dispatch: tool تنظیم شده است فراخوانی می‌شود.

command-arg-mode"raw"default: raw

برای ارسال ابزار، رشته خام آرگومان‌ها را بدون هیچ تحلیل هسته‌ای به ابزار ارسال می‌کند. ابزار { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" } را دریافت می‌کند.

دروازه‌گذاری

OpenClaw هنگام بارگذاری، مهارت‌ها را با استفاده از metadata.openclaw (JSON تک‌خطی در frontmatter) فیلتر می‌کند. مهارتی که بلوک metadata.openclaw ندارد همیشه واجد شرایط است، مگر اینکه صراحتا غیرفعال شده باشد.

markdown
---name: image-labdescription: Generate or edit images via a provider-backed image workflowmetadata:  {    "openclaw":      {        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },        "primaryEnv": "GEMINI_API_KEY",      },  }---
alwaysboolean

وقتی true باشد، همیشه مهارت را شامل می‌کند و همه دروازه‌های دیگر را رد می‌کند.

emojistring

ایموجی اختیاری که در رابط Skills در macOS نشان داده می‌شود.

homepagestring

URL اختیاری که با عنوان «وب‌سایت» در رابط Skills در macOS نشان داده می‌شود.

os"darwin" | "linux" | "win32"

فیلتر پلتفرم. وقتی تنظیم شود، مهارت فقط روی سیستم‌عامل‌های فهرست‌شده واجد شرایط است.

requires.binsstring[]

هر باینری باید روی PATH وجود داشته باشد.

requires.anyBinsstring[]

حداقل یک باینری باید روی PATH وجود داشته باشد.

requires.envstring[]

هر متغیر محیطی باید در فرایند وجود داشته باشد یا از طریق پیکربندی ارائه شود.

requires.configstring[]

هر مسیر openclaw.json باید truthy باشد.

primaryEnvstring

نام متغیر محیطی مرتبط با skills.entries.<name>.apiKey.

installobject[]

مشخصات نصب‌کننده اختیاری که توسط رابط Skills در macOS استفاده می‌شود (brew / node / go / uv / download).

مشخصات نصب‌کننده

مشخصات نصب‌کننده به رابط Skills در macOS می‌گوید چگونه یک وابستگی را نصب کند:

markdown
---name: geminidescription: Use Gemini CLI for coding assistance and Google search lookups.metadata:  {    "openclaw":      {        "emoji": "♊️",        "requires": { "bins": ["gemini"] },        "install":          [            {              "id": "brew",              "kind": "brew",              "formula": "gemini-cli",              "bins": ["gemini"],              "label": "Install Gemini CLI (brew)",            },          ],      },  }---
قواعد انتخاب نصب‌کننده
  • وقتی چند نصب‌کننده فهرست شده باشند، Gateway یک گزینه ترجیحی را انتخاب می‌کند (brew وقتی در دسترس باشد، وگرنه node).
  • اگر همه نصب‌کننده‌ها download باشند، OpenClaw هر ورودی را فهرست می‌کند تا بتوانید همه artifactهای موجود را ببینید.
  • مشخصات می‌توانند شامل os: ["darwin"|"linux"|"win32"] باشند تا براساس پلتفرم فیلتر شوند.
  • نصب‌های Node به skills.install.nodeManager در openclaw.json احترام می‌گذارند (پیش‌فرض: npm؛ گزینه‌ها: npm / pnpm / yarn / bun). این فقط روی نصب مهارت‌ها اثر می‌گذارد؛ runtime مربوط به Gateway همچنان باید Node باشد.
  • ترجیح نصب‌کننده Gateway: Homebrew → uv → مدیر node پیکربندی‌شده → go → download.
جزئیات هر نصب‌کننده
  • Homebrew: OpenClaw به‌صورت خودکار Homebrew را نصب نمی‌کند یا فرمول‌های brew را به دستورهای بسته سیستم ترجمه نمی‌کند. در کانتینرهای Linux بدون brew، نصب‌کننده‌های فقط brew پنهان می‌شوند؛ از یک image سفارشی استفاده کنید یا وابستگی را دستی نصب کنید.
  • Go: OpenClaw برای نصب خودکار مهارت‌ها به Go 1.21 یا جدیدتر نیاز دارد و تنظیمات موجود GOBIN، GOPATH و GOTOOLCHAIN را حفظ می‌کند. اگر toolchain پیکربندی‌شده نتواند نسخه Go موردنیاز یک ماژول را تامین کند، onboarding پس از تلاش نصب، مهارت را همراه با پیش‌نیازهای دستی Go گروه‌بندی می‌کند. اگر go وجود نداشته باشد و Homebrew در دسترس باشد، OpenClaw ابتدا Go را از طریق Homebrew نصب می‌کند و GOBIN را روی bin متعلق به Homebrew تنظیم می‌کند. در Linux، OpenClaw می‌تواند به‌جای آن از apt-get به‌عنوان root یا از طریق sudo بدون گذرواژه استفاده کند، وقتی candidate تازه‌سازی‌شده golang-go حداقل نسخه را برآورده کند.
  • Download: url (الزامی)، archive (tar.gz | tar.bz2 | zipextract (پیش‌فرض: تشخیص خودکار وقتی آرشیو شناسایی شود)، stripComponents، targetDir (پیش‌فرض: ~/.openclaw/tools/<skillKey>).
نکات sandboxing

requires.bins هنگام بارگذاری مهارت روی host بررسی می‌شود. اگر یک agent در sandbox اجرا شود، باینری باید داخل کانتینر هم وجود داشته باشد. آن را از طریق agents.defaults.sandbox.docker.setupCommand یا یک image سفارشی نصب کنید. setupCommand یک بار پس از ایجاد کانتینر اجرا می‌شود و به خروج شبکه، فایل‌سیستم root قابل نوشتن، و کاربر root در sandbox نیاز دارد.

overrideهای پیکربندی

مهارت‌های bundled یا managed را زیر skills.entries در ~/.openclaw/openclaw.json روشن و پیکربندی کنید:

json5
{  skills: {    entries: {      "image-lab": {        enabled: true,        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },        config: {          endpoint: "https://example.invalid",          model: "nano-pro",        },      },      peekaboo: { enabled: true },      sag: { enabled: false },    },  },}
enabledboolean

false مهارت را حتی وقتی bundled یا نصب‌شده باشد غیرفعال می‌کند. مهارت bundled coding-agent اختیاری است — skills.entries.coding-agent.enabled: true را تنظیم کنید و مطمئن شوید یکی از claude، codex، opencode یا CLI پشتیبانی‌شده دیگری نصب و احراز هویت شده است.

apiKeystring | { source, provider, id }

فیلد کمکی برای مهارت‌هایی که metadata.openclaw.primaryEnv را اعلام می‌کنند. از یک رشته متن ساده یا شیء SecretRef پشتیبانی می‌کند.

env"Record<string,
configobject

کیسه اختیاری برای فیلدهای پیکربندی سفارشی هر مهارت.

allowBundledstring[]

allowlist اختیاری فقط برای مهارت‌های bundled. وقتی تنظیم شود، فقط مهارت‌های bundled داخل فهرست واجد شرایط هستند. مهارت‌های managed و workspace تحت تاثیر قرار نمی‌گیرند.

تزریق محیط

وقتی اجرای یک agent شروع می‌شود، OpenClaw:

  • metadata مهارت را می‌خواند

    OpenClaw فهرست موثر مهارت‌ها را برای agent حل می‌کند و قواعد دروازه‌گذاری، allowlistها، و overrideهای پیکربندی را اعمال می‌کند.

  • محیط و کلیدهای API را تزریق می‌کند

    skills.entries.<key>.env و skills.entries.<key>.apiKey برای مدت اجرای run روی process.env اعمال می‌شوند.

  • system prompt را می‌سازد

    مهارت‌های واجد شرایط در یک بلوک XML فشرده کامپایل می‌شوند و داخل system prompt تزریق می‌شوند.

  • محیط را بازیابی می‌کند

    پس از پایان run، محیط اصلی بازیابی می‌شود.

  • برای backend bundled به نام claude-cli، OpenClaw همان snapshot مهارت‌های واجد شرایط را نیز به‌صورت یک Plugin موقت Claude Code materialize می‌کند و آن را از طریق --plugin-dir ارسال می‌کند. backendهای CLI دیگر فقط از prompt catalog استفاده می‌کنند.

    Snapshotها و refresh

    OpenClaw مهارت‌های واجد شرایط را هنگام شروع یک session snapshot می‌کند و همان فهرست را برای همه turnهای بعدی در session دوباره استفاده می‌کند. تغییرات مهارت‌ها یا پیکربندی در session جدید بعدی اثر می‌گذارند.

    Skills در میانه session در دو حالت refresh می‌شود:

    • watcher مهارت‌ها یک تغییر SKILL.md را شناسایی کند.
    • یک node راه‌دور واجد شرایط جدید متصل شود.

    فهرست refreshشده در turn بعدی agent استفاده می‌شود. اگر allowlist موثر agent تغییر کند، OpenClaw برای هم‌تراز نگه داشتن مهارت‌های قابل مشاهده، snapshot را refresh می‌کند.

    Watcher مهارت‌ها

    به‌صورت پیش‌فرض، OpenClaw پوشه‌های مهارت را watch می‌کند و وقتی فایل‌های SKILL.md تغییر کنند، snapshot را bump می‌کند. زیر skills.load پیکربندی کنید:

    json5
    {  skills: {    load: {      extraDirs: ["~/Projects/agent-scripts/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],      watch: true,      watchDebounceMs: 250,    },  },}

    از allowSymlinkTargets برای چیدمان‌های symlinkشده عمدی استفاده کنید که در آن root یک مهارت به خارج از root پیکربندی‌شده اشاره می‌کند، برای مثال <workspace>/skills/manager -> ~/Projects/manager/skills. skills.workshop.allowSymlinkTargetWrites را فقط وقتی فعال کنید که Skill Workshop باید پیشنهادها را از طریق همان مسیرهای symlinkشده قابل اعتماد نیز اعمال کند.

    nodeهای macOS راه‌دور (Gateway لینوکسی)

    اگر Gateway روی Linux اجرا شود اما یک node macOS با مجوز system.run متصل باشد، OpenClaw می‌تواند مهارت‌های فقط macOS را واجد شرایط بداند، وقتی باینری‌های لازم روی آن node موجود باشند. agent باید آن مهارت‌ها را از طریق ابزار exec با host=node اجرا کند.

    nodeهای offline مهارت‌های فقط راه‌دور را قابل مشاهده نمی‌کنند. اگر یک node پاسخ دادن به probeهای bin را متوقف کند، OpenClaw matchهای bin کش‌شده آن را پاک می‌کند.

    اثر توکن

    وقتی مهارت‌ها واجد شرایط باشند، OpenClaw یک بلوک XML فشرده را داخل system prompt تزریق می‌کند. هزینه قطعی است:

    text
    total = 195 + Σ (97 + len(name) + len(description) + len(filepath))
    • سربار پایه (فقط وقتی ≥ 1 مهارت وجود داشته باشد): حدود 195 کاراکتر
    • برای هر مهارت: حدود 97 کاراکتر + طول فیلدهای name، description و location شما
    • XML escaping، & < > " ' را به entity تبدیل می‌کند و به‌ازای هر رخداد چند کاراکتر اضافه می‌کند
    • با حدود 4 کاراکتر/توکن، 97 کاراکتر ≈ 24 توکن برای هر مهارت پیش از طول فیلدها

    برای کمینه کردن سربار prompt، توضیحات را کوتاه و توصیفی نگه دارید.

    مرتبط

    Was this useful?
    On this page

    On this page