ابزارها API را فراخوانی می‌کنند

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

• POST /tools/invoke
• همان پورت Gateway (چندبخشی‌سازی WS + HTTP): http://<gateway-host>:<port>/tools/invoke

اندازهٔ پیش‌فرض بیشینهٔ بار درخواست 2 MB است.

احراز هویت

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

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

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

نکته‌ها:

• وقتی 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 باید از یک منبع پراکسی مورد اعتمادِ پیکربندی‌شده بیاید؛ پراکسی‌های loopback روی همان میزبان به gateway.auth.trustedProxy.allowLoopback = true صریح نیاز دارند.
• اگر gateway.auth.rateLimit پیکربندی شده باشد و شکست‌های احراز هویت بیش از حد رخ دهد، نقطهٔ پایانی 429 را با Retry-After برمی‌گرداند.

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

با این نقطهٔ پایانی به‌عنوان سطح دسترسی کامل اپراتور برای نمونهٔ Gateway برخورد کنید.

• احراز هویت bearer HTTP در اینجا یک مدل دامنهٔ محدود برای هر کاربر نیست.
• یک توکن/گذرواژهٔ معتبر Gateway برای این نقطهٔ پایانی باید مانند اعتبارنامهٔ مالک/اپراتور در نظر گرفته شود.
• برای حالت‌های احراز هویت با راز مشترک (token و password)، حتی اگر فراخواننده یک سرآیند محدودتر x-openclaw-scopes بفرستد، نقطهٔ پایانی پیش‌فرض‌های عادی و کامل اپراتور را بازیابی می‌کند.
• احراز هویت با راز مشترک همچنین فراخوانی‌های مستقیم ابزار روی این نقطهٔ پایانی را به‌عنوان نوبت‌های فرستنده-مالک در نظر می‌گیرد.
• حالت‌های HTTP مورد اعتمادِ حامل هویت (برای مثال احراز هویت پراکسی مورد اعتماد یا gateway.auth.mode="none" روی یک ورودی خصوصی) در صورت وجود x-openclaw-scopes به آن احترام می‌گذارند و در غیر این صورت به مجموعهٔ دامنهٔ پیش‌فرض عادی اپراتور برمی‌گردند.
• این نقطهٔ پایانی را فقط روی loopback/tailnet/ورودی خصوصی نگه دارید؛ آن را مستقیماً در معرض اینترنت عمومی قرار ندهید.

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

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

بدنهٔ درخواست

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

فیلدها:

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

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

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

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

اگر ابزاری توسط سیاست مجاز نباشد، نقطهٔ پایانی 404 برمی‌گرداند.

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

• تأییدهای exec حفاظ‌های اپراتور هستند، نه یک مرز مجوزدهی جداگانه برای این نقطهٔ پایانی HTTP. اگر ابزاری اینجا از طریق احراز هویت Gateway + سیاست ابزار قابل دسترسی باشد، /tools/invoke یک درخواست تأیید اضافی برای هر فراخوانی اضافه نمی‌کند.
• اگر exec در اینجا قابل دسترسی باشد، با آن به‌عنوان سطح shell تغییردهنده برخورد کنید. رد کردن write، edit، apply_patch یا ابزارهای نوشتن فایل‌سیستم از طریق HTTP اجرای shell را فقط‌خواندنی نمی‌کند.
• اعتبارنامه‌های bearer Gateway را با فراخوانندگان نامطمئن به اشتراک نگذارید. اگر به جداسازی میان مرزهای اعتماد نیاز دارید، Gatewayهای جداگانه اجرا کنید (و ترجیحاً کاربران/میزبان‌های سیستم‌عامل جداگانه).

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

• exec - اجرای مستقیم فرمان (سطح RCE)
• spawn - ایجاد پردازهٔ فرزند دلخواه (سطح RCE)
• shell - اجرای فرمان shell (سطح RCE)
• fs_write - تغییر دلخواه فایل روی میزبان
• fs_delete - حذف دلخواه فایل روی میزبان
• fs_move - جابه‌جایی/تغییرنام دلخواه فایل روی میزبان
• apply_patch - اعمال وصله می‌تواند فایل‌های دلخواه را بازنویسی کند
• sessions_spawn - هماهنگ‌سازی نشست؛ ایجاد عامل‌ها از راه دور RCE است
• sessions_send - تزریق پیام میان‌نشستی
• cron - صفحهٔ کنترل خودکارسازی پایدار
• gateway - صفحهٔ کنترل Gateway؛ از پیکربندی دوباره از طریق HTTP جلوگیری می‌کند
• nodes - انتقال فرمان Node می‌تواند به system.run روی میزبان‌های جفت‌شده برسد
• whatsapp_login - راه‌اندازی تعاملی که به پویش QR در پایانه نیاز دارد؛ روی HTTP معلق می‌ماند

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

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

برای کمک به سیاست‌های گروهی در حل زمینه، می‌توانید به‌صورت اختیاری تنظیم کنید:

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

پاسخ‌ها

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

مثال

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
• ابزارها و plugins