API فراخوانی ابزارها

Gateway مربوط به OpenClaw یک endpoint ساده HTTP برای فراخوانی مستقیم یک ابزار واحد ارائه می‌دهد. این endpoint همیشه فعال است و از احراز هویت Gateway به‌همراه سیاست ابزار استفاده می‌کند. مانند سطح سازگار با OpenAI یعنی /v1/*، احراز هویت bearer با secret مشترک به‌عنوان دسترسی قابل‌اعتماد operator برای کل gateway در نظر گرفته می‌شود.

• POST /tools/invoke
• همان پورت Gateway (ترکیب WS + HTTP): http://<gateway-host>:<port>/tools/invoke

حداکثر اندازه پیش‌فرض payload برابر 2 MB است.

احراز هویت

از پیکربندی احراز هویت Gateway استفاده می‌کند.

مسیرهای رایج احراز هویت HTTP:

• احراز هویت با secret مشترک (gateway.auth.mode="token" یا "password"): Authorization: Bearer <token-or-password>
• احراز هویت HTTP دارای هویت قابل‌اعتماد (gateway.auth.mode="trusted-proxy"): از طریق proxy پیکربندی‌شده و آگاه از هویت مسیریابی کنید و اجازه دهید headerهای هویتی لازم را تزریق کند
• احراز هویت باز برای ingress خصوصی (gateway.auth.mode="none"): نیازی به header احراز هویت نیست

نکته‌ها:

• وقتی gateway.auth.mode="token" است، از gateway.auth.token (یا OPENCLAW_GATEWAY_TOKEN) استفاده کنید.
• وقتی gateway.auth.mode="password" است، از gateway.auth.password (یا OPENCLAW_GATEWAY_PASSWORD) استفاده کنید.
• وقتی gateway.auth.mode="trusted-proxy" است، درخواست HTTP باید از یک منبع trusted proxy پیکربندی‌شده بیاید؛ proxyهای loopback روی همان host به gateway.auth.trustedProxy.allowLoopback = true صریح نیاز دارند.
• فراخوان‌های داخلی روی همان host که proxy را دور می‌زنند می‌توانند از gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD به‌عنوان یک fallback مستقیم محلی استفاده کنند. وجود هر شواهدی در headerهای Forwarded، ‏X-Forwarded-* یا X-Real-IP در عوض درخواست را روی مسیر trusted-proxy نگه می‌دارد.
• اگر gateway.auth.rateLimit پیکربندی شده باشد و شکست‌های احراز هویت بیش از حد رخ دهد، endpoint با 429 و Retry-After پاسخ می‌دهد.

مرز امنیتی (مهم)

این endpoint را به‌عنوان سطح دسترسی کامل operator برای نمونه gateway در نظر بگیرید.

• احراز هویت HTTP bearer در اینجا یک مدل scope محدود برای هر کاربر نیست.
• یک token/password معتبر Gateway برای این endpoint باید مانند credential مالک/operator در نظر گرفته شود.
• برای حالت‌های احراز هویت با secret مشترک (token و password)، endpoint پیش‌فرض‌های عادی و کامل operator را بازمی‌گرداند، حتی اگر فراخواننده header محدودتری با نام x-openclaw-scopes بفرستد.
• احراز هویت با secret مشترک همچنین فراخوانی مستقیم ابزارها روی این endpoint را به‌عنوان نوبت‌های owner-sender در نظر می‌گیرد.
• حالت‌های HTTP دارای هویت قابل‌اعتماد (برای مثال احراز هویت trusted proxy یا gateway.auth.mode="none" روی ingress خصوصی) در صورت وجود x-openclaw-scopes به آن احترام می‌گذارند و در غیر این صورت به مجموعه scope پیش‌فرض عادی operator برمی‌گردند.
• این endpoint را فقط روی loopback/tailnet/ingress خصوصی نگه دارید؛ آن را مستقیما در معرض اینترنت عمومی قرار ندهید.

ماتریس احراز هویت:

• gateway.auth.mode="token" یا "password" + Authorization: Bearer ...
  • مالکیت secret مشترک operator gateway را اثبات می‌کند
  • x-openclaw-scopes محدودتر را نادیده می‌گیرد
  • مجموعه scope پیش‌فرض کامل operator را بازمی‌گرداند: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • فراخوانی مستقیم ابزارها روی این endpoint را به‌عنوان نوبت‌های owner-sender در نظر می‌گیرد
• حالت‌های HTTP دارای هویت قابل‌اعتماد (برای مثال احراز هویت trusted proxy، یا gateway.auth.mode="none" روی ingress خصوصی)
  • نوعی هویت بیرونی قابل‌اعتماد یا مرز deployment را احراز می‌کنند
  • وقتی header وجود دارد به x-openclaw-scopes احترام می‌گذارند
  • وقتی header وجود ندارد به مجموعه scope پیش‌فرض عادی operator برمی‌گردند
  • فقط زمانی معنای مالک را از دست می‌دهند که فراخواننده scopeها را صراحتا محدود کند و operator.admin را حذف کند

بدنه درخواست

{  "tool": "sessions_list",  "action": "json",  "args": {},  "sessionKey": "main",  "dryRun": false}

فیلدها:

• tool (رشته، الزامی): نام ابزاری که باید فراخوانی شود.
• action (رشته، اختیاری): اگر schema ابزار از action پشتیبانی کند و payload مربوط به args آن را حذف کرده باشد، داخل args نگاشت می‌شود.
• args (شیء، اختیاری): آرگومان‌های مخصوص ابزار.
• sessionKey (رشته، اختیاری): کلید session هدف. اگر حذف شود یا "main" باشد، Gateway از کلید session اصلی پیکربندی‌شده استفاده می‌کند (session.mainKey و agent پیش‌فرض را رعایت می‌کند، یا در scope سراسری از global استفاده می‌کند).
• dryRun (boolean، اختیاری): برای استفاده آینده رزرو شده است؛ در حال حاضر نادیده گرفته می‌شود.

رفتار سیاست + مسیریابی

دسترسی‌پذیری ابزار از همان زنجیره سیاستی فیلتر می‌شود که agentهای Gateway استفاده می‌کنند:

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• سیاست‌های گروهی (اگر کلید session به یک گروه یا channel نگاشت شود)
• سیاست subagent (هنگام فراخوانی با کلید session مربوط به subagent)

اگر ابزاری طبق سیاست مجاز نباشد، endpoint مقدار 404 برمی‌گرداند.

نکته‌های مهم درباره مرز:

• تاییدهای exec گاردریل‌های operator هستند، نه یک مرز مجوزدهی جداگانه برای این endpoint HTTP. اگر ابزاری از طریق احراز هویت Gateway + سیاست ابزار در اینجا قابل دسترسی باشد، /tools/invoke یک prompt تایید اضافی برای هر فراخوان اضافه نمی‌کند.
• اگر exec در اینجا قابل دسترسی باشد، آن را به‌عنوان یک سطح shell تغییردهنده در نظر بگیرید. رد کردن write، ‏edit، ‏apply_patch یا ابزارهای HTTP برای نوشتن در فایل‌سیستم، اجرای shell را read-only نمی‌کند.
• credentialهای bearer مربوط به Gateway را با فراخوانندگان غیرقابل‌اعتماد به اشتراک نگذارید. اگر به جداسازی میان مرزهای اعتماد نیاز دارید، gatewayهای جداگانه اجرا کنید (و در حالت ایده‌آل، کاربران/hostهای جداگانه OS).

HTTP مربوط به Gateway همچنین به‌طور پیش‌فرض یک deny list سخت اعمال می‌کند (حتی اگر سیاست session ابزار را مجاز بداند):

• exec - اجرای مستقیم فرمان (سطح RCE)
• spawn - ایجاد فرایند فرزند دلخواه (سطح RCE)
• shell - اجرای فرمان shell (سطح RCE)
• fs_write - تغییر دلخواه فایل روی host
• fs_delete - حذف دلخواه فایل روی host
• fs_move - جابه‌جایی/تغییرنام دلخواه فایل روی host
• apply_patch - اعمال patch می‌تواند فایل‌های دلخواه را بازنویسی کند
• sessions_spawn - orchestration مربوط به session؛ ایجاد agentها از راه دور RCE است
• sessions_send - تزریق پیام میان sessionها
• cron - control plane اتوماسیون پایدار
• gateway - control plane مربوط به gateway؛ از پیکربندی مجدد از طریق HTTP جلوگیری می‌کند
• nodes - relay فرمان node می‌تواند به system.run روی hostهای paired برسد
• whatsapp_login - راه‌اندازی تعاملی که به اسکن QR در ترمینال نیاز دارد؛ روی HTTP معلق می‌ماند

می‌توانید این deny list را از طریق gateway.tools سفارشی کنید:

{  gateway: {    tools: {      // Additional tools to block over HTTP /tools/invoke      deny: ["browser"],      // Remove tools from the default deny list for owner/admin callers      allow: ["gateway"],    },  },}

gateway.tools.allow یک override برای exposure است، نه ارتقای scope. در حالت‌های HTTP دارای هویت، cron، ‏gateway و nodes برای فراخوانندگانی که هویت owner/admin (operator.admin) ندارند همچنان در دسترس نیستند، حتی وقتی در gateway.tools.allow فهرست شده باشند. احراز هویت shared-secret bearer همچنان از قاعده trusted-operator کامل بالا پیروی می‌کند.

برای کمک به resolve شدن context سیاست‌های گروهی، می‌توانید به‌صورت اختیاری تنظیم کنید:

• x-openclaw-message-channel: <channel> (مثال: slack, telegram)
• x-openclaw-account-id: <accountId> (وقتی چند حساب وجود دارد)

پاسخ‌ها

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (درخواست نامعتبر یا خطای ورودی ابزار)
• 401 → غیرمجاز
• 429 → احراز هویت rate-limited شده است (Retry-After تنظیم شده است)
• 404 → ابزار در دسترس نیست (پیدا نشد یا در allowlist نیست)
• 405 → روش مجاز نیست
• 500 → { ok: false, error: { type, message } } (خطای غیرمنتظره اجرای ابزار؛ پیام sanitize شده است)

مثال

curl -sS http://127.0.0.1:18789/tools/invoke \  -H 'Authorization: Bearer secret' \  -H 'Content-Type: application/json' \  -d '{    "tool": "sessions_list",    "action": "json",    "args": {}  }'

مرتبط

• پروتکل Gateway
• ابزارها و Pluginها