ابزارها و Pluginها

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

# ابزارها، Skills و Pluginها

OpenClaw سه لایه دارد که با هم کار می‌کنند:

# ابزارهای داخلی

این ابزارها همراه OpenClaw ارائه می‌شوند و بدون نصب هیچ Pluginی در دسترس هستند:

ابزار	چه کاری انجام می‌دهد	صفحه
exec / process	اجرای فرمان‌های shell، مدیریت فرایندهای پس‌زمینه	Exec، تأییدهای Exec
code_execution	اجرای تحلیل Python راه‌دور در sandbox	اجرای کد
browser	کنترل مرورگر Chromium (پیمایش، کلیک، screenshot)	مرورگر
web_search / x_search / web_fetch	جست‌وجوی وب، جست‌وجوی پست‌های X، واکشی محتوای صفحه	وب، واکشی وب
read / write / edit	ورودی/خروجی فایل در workspace
apply_patch	وصله‌های چندبخشی فایل	اعمال وصله
message	ارسال پیام در همهٔ کانال‌ها	ارسال عامل
canvas	هدایت node Canvas (ارائه، eval، snapshot)
nodes	کشف و هدف‌گیری دستگاه‌های جفت‌شده
cron / gateway	مدیریت کارهای زمان‌بندی‌شده؛ بازرسی، وصله، راه‌اندازی مجدد، یا به‌روزرسانی Gateway
image / image_generate	تحلیل یا تولید تصویر	تولید تصویر
music_generate	تولید قطعه‌های موسیقی	تولید موسیقی
video_generate	تولید ویدئوها	تولید ویدئو
tts	تبدیل یک‌مرحله‌ای متن به گفتار	TTS
sessions_* / subagents / agents_list	مدیریت نشست، وضعیت و هماهنگ‌سازی زیرعامل‌ها	زیرعامل‌ها
session_status	بازخوانی سبک به سبک /status و بازنویسی مدل نشست	ابزارهای نشست

برای کارهای تصویری، از image برای تحلیل و از image_generate برای تولید یا ویرایش استفاده کنید. اگر openai/*، google/*، fal/* یا ارائه‌دهندهٔ تصویر غیرپیش‌فرض دیگری را هدف می‌گیرید، ابتدا احراز هویت/کلید API آن ارائه‌دهنده را پیکربندی کنید.

برای کارهای موسیقی، از music_generate استفاده کنید. اگر google/*، minimax/* یا ارائه‌دهندهٔ موسیقی غیرپیش‌فرض دیگری را هدف می‌گیرید، ابتدا احراز هویت/کلید API آن ارائه‌دهنده را پیکربندی کنید.

برای کارهای ویدئویی، از video_generate استفاده کنید. اگر qwen/* یا ارائه‌دهندهٔ ویدئوی غیرپیش‌فرض دیگری را هدف می‌گیرید، ابتدا احراز هویت/کلید API آن ارائه‌دهنده را پیکربندی کنید.

برای تولید صوت مبتنی بر گردش کار، وقتی Pluginی مانند ComfyUI آن را ثبت می‌کند از music_generate استفاده کنید. این از tts، که متن به گفتار است، جداست.

session_status ابزار سبک وضعیت/بازخوانی در گروه نشست‌ها است. به پرسش‌های به سبک /status دربارهٔ نشست فعلی پاسخ می‌دهد و می‌تواند به‌صورت اختیاری بازنویسی مدل برای هر نشست تنظیم کند؛ model=default آن بازنویسی را پاک می‌کند. مانند /status، می‌تواند شمارنده‌های پراکندهٔ token/cache و برچسب مدل runtime فعال را از آخرین ورودی استفادهٔ transcript تکمیل کند.

gateway ابزار runtime فقط برای مالک در عملیات Gateway است:

• config.schema.lookup برای یک زیردرخت config محدود به path پیش از ویرایش‌ها
• config.get برای snapshot و hash فعلی config
• config.patch برای به‌روزرسانی‌های جزئی config همراه با راه‌اندازی مجدد
• config.apply فقط برای جایگزینی کامل config
• update.run برای self-update صریح + راه‌اندازی مجدد

برای تغییرات جزئی، ابتدا config.schema.lookup و سپس config.patch را ترجیح دهید. از config.apply فقط زمانی استفاده کنید که عمداً کل config را جایگزین می‌کنید. برای مستندات گسترده‌تر config، پیکربندی و مرجع پیکربندی را بخوانید. این ابزار همچنین از تغییر tools.exec.ask یا tools.exec.security خودداری می‌کند؛ نام‌های مستعار قدیمی tools.bash.* به همان مسیرهای محافظت‌شدهٔ exec نرمال‌سازی می‌شوند.

# ابزارهای ارائه‌شده توسط Plugin

Pluginها می‌توانند ابزارهای بیشتری ثبت کنند. چند نمونه:

• Diffها — نمایشگر و renderer تفاوت‌ها
• وظیفهٔ LLM — گام LLM فقط JSON برای خروجی ساخت‌یافته
• Lobster — runtime گردش کار تایپ‌شده با تأییدهای قابل‌ادامه
• تولید موسیقی — ابزار مشترک music_generate با ارائه‌دهندگان مبتنی بر گردش کار
• OpenProse — هماهنگ‌سازی گردش کار markdown-first
• Tokenjuice — فشرده‌سازی نتایج پرنویز ابزارهای exec و bash

ابزارهای Plugin همچنان با api.registerTool(...) نوشته می‌شوند و در فهرست contracts.tools در manifest مربوط به Plugin اعلام می‌شوند. OpenClaw توصیف‌گر اعتبارسنجی‌شدهٔ ابزار را هنگام discovery ثبت می‌کند و آن را بر اساس منبع و قرارداد Plugin cache می‌کند، تا برنامه‌ریزی ابزار در مراحل بعد بتواند از بارگذاری runtime مربوط به Plugin صرف‌نظر کند. اجرای ابزار همچنان Plugin مالک را بارگذاری می‌کند و پیاده‌سازی زندهٔ ثبت‌شده را فراخوانی می‌کند.

# پیکربندی ابزار

# فهرست‌های اجازه و رد

از طریق tools.allow / tools.deny در config کنترل کنید عامل کدام ابزارها را می‌تواند فراخوانی کند. رد کردن همیشه بر اجازه دادن غلبه دارد.

{
  tools: {
    allow: ["group:fs", "browser", "web_search"],
    deny: ["exec"],
  },
}

OpenClaw وقتی allowlist صریح به هیچ ابزار قابل‌فراخوانی منتهی نشود، به‌صورت بسته شکست می‌خورد. برای مثال، tools.allow: ["query_db"] فقط زمانی کار می‌کند که Plugin بارگذاری‌شده‌ای واقعاً query_db را ثبت کند. اگر هیچ ابزار داخلی، Plugin، یا ابزار MCP بسته‌بندی‌شده با allowlist مطابقت نداشته باشد، اجرا پیش از فراخوانی مدل متوقف می‌شود، نه اینکه به‌صورت اجرای فقط متنی ادامه دهد که ممکن است نتایج ابزار را hallucinate کند.

# پروفایل‌های ابزار

tools.profile پیش از اعمال allow/deny یک allowlist پایه تنظیم می‌کند. بازنویسی برای هر عامل: agents.list[].tools.profile.

پروفایل	شامل چه چیزهایی است
full	همهٔ ابزارهای هسته‌ای و اختیاری Plugin؛ خط پایهٔ نامحدود برای دسترسی گسترده‌تر به فرمان/کنترل
coding	group:fs، group:runtime، group:web، group:sessions، group:memory، cron، image، image_generate، music_generate، video_generate
messaging	group:messaging، sessions_list، sessions_history، sessions_send، session_status
minimal	فقط session_status

coding شامل ابزارهای سبک وب (web_search، web_fetch، x_search) است اما ابزار کامل کنترل browser را شامل نمی‌شود. خودکارسازی مرورگر می‌تواند نشست‌های واقعی و پروفایل‌های واردشده را هدایت کند، بنابراین آن را به‌صورت صریح با tools.alsoAllow: ["browser"] یا agents.list[].tools.alsoAllow: ["browser"] برای هر عامل اضافه کنید.

پروفایل‌های coding و messaging همچنین ابزارهای MCP بسته‌بندی‌شدهٔ پیکربندی‌شده را زیر کلید Plugin به نام bundle-mcp مجاز می‌کنند. وقتی می‌خواهید یک پروفایل built-ins معمول خود را نگه دارد اما همهٔ ابزارهای MCP پیکربندی‌شده را پنهان کند، tools.deny: ["bundle-mcp"] را اضافه کنید. پروفایل minimal ابزارهای MCP بسته‌بندی‌شده را شامل نمی‌شود.

مثال (گسترده‌ترین سطح ابزار به‌صورت پیش‌فرض):

{
  tools: {
    profile: "full",
  },
}

# گروه‌های ابزار

از کوتاه‌نویسی‌های group:* در فهرست‌های اجازه/رد استفاده کنید:

گروه	ابزارها
group:runtime	exec، process، code_execution (bash به‌عنوان نام مستعار برای exec پذیرفته می‌شود)
group:fs	read، write، edit، apply_patch
group:sessions	sessions_list، sessions_history، sessions_send، sessions_spawn، sessions_yield، subagents، session_status
group:memory	memory_search، memory_get
group:web	web_search، x_search، web_fetch
group:ui	browser، canvas
group:automation	heartbeat_respond، cron، gateway
group:messaging	message
group:nodes	nodes
group:agents	agents_list، update_plan
group:media	image، image_generate، music_generate، video_generate، tts
group:openclaw	همهٔ ابزارهای داخلی OpenClaw (ابزارهای Plugin را مستثنا می‌کند)

sessions_history یک نمای یادآوری محدود و فیلترشده از نظر ایمنی برمی‌گرداند. این نما برچسب‌های تفکر، چارچوب <relevant-memories>، payloadهای XML فراخوانی ابزار به‌صورت متن ساده (از جمله <tool_call>...</tool_call>، <function_call>...</function_call>، <tool_calls>...</tool_calls>، <function_calls>...</function_calls>، و بلوک‌های کوتاه‌شدهٔ فراخوانی ابزار)، چارچوب تنزل‌یافتهٔ فراخوانی ابزار، توکن‌های کنترلی مدل افشاشدهٔ ASCII/تمام‌عرض، و XML بدشکل فراخوانی ابزار MiniMax را از متن دستیار حذف می‌کند، سپس به‌جای عمل کردن مانند dump خام رونوشت، ویرایش محرمانه/کوتاه‌سازی و جای‌نگهدارهای احتمالی برای ردیف‌های بیش‌ازحد بزرگ را اعمال می‌کند.

# محدودیت‌های مختص ارائه‌دهنده

از tools.byProvider برای محدود کردن ابزارها برای ارائه‌دهندگان مشخص بدون تغییر پیش‌فرض‌های سراسری استفاده کنید:

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}