Gateway

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

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

POST /tools/invoke
همان درگاه Gateway (تسهیم WS و HTTP): http://<gateway-host>:<port>/tools/invoke
حداکثر اندازهٔ پیش‌فرض بدنهٔ درخواست: ۲ مگابایت

احراز هویت

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

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

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

نکته‌ها:

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

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

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

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

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

حالت احراز هویت رفتار

token یا password به‌همراه Authorization: Bearer ... در اختیار داشتن راز مشترک اپراتور Gateway را اثبات می‌کند. x-openclaw-scopes محدودتر را نادیده می‌گیرد. مجموعهٔ کامل دامنه‌های دسترسی پیش‌فرض اپراتور را بازیابی می‌کند: operator.admin، operator.approvals، operator.pairing، operator.read، operator.talk.secrets، operator.write. فراخوانی مستقیم ابزار را به‌عنوان نوبت‌های فرستندهٔ مالک تلقی می‌کند.

HTTP قابل‌اعتماد و حامل هویت (احراز هویت پراکسی قابل‌اعتماد، یا mode="none" روی ورودی خصوصی) یک هویت قابل‌اعتماد بیرونی یا مرز استقرار را احراز می‌کند. در صورت وجود x-openclaw-scopes آن را رعایت می‌کند. در نبود این سرآیند، به مجموعهٔ دامنه‌های دسترسی پیش‌فرض و عادی اپراتور بازمی‌گردد. تنها زمانی معنای مالک را از دست می‌دهد که فراخوان صراحتاً دامنه‌ها را محدود و operator.admin را حذف کند.

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

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

json

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

فیلدها:

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

رفتار خط‌مشی و مسیریابی

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

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

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

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

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

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

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

cron، gateway و nodes همچنین فقط مخصوص مالک هستند: حتی خارج از این فهرست منع پیش‌فرض، فراخوان‌های غیرمالک نمی‌توانند آن‌ها را روی این سطح فراخوانی کنند.

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

json5

{  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 یک بازنویسی برای در معرض قرار دادن است، نه ارتقای دامنهٔ دسترسی. در حالت‌های HTTP حامل هویت، cron، gateway و nodes حتی زمانی که در gateway.tools.allow فهرست شده‌اند، برای فراخوان‌هایی که هویت مالک/مدیر (operator.admin) ندارند همچنان در دسترس نیستند. احراز هویت حامل با راز مشترک همچنان از قاعدهٔ اپراتور کاملاً قابل‌اعتماد در بالا پیروی می‌کند.

برای کمک به خط‌مشی‌های گروه در تعیین زمینه، می‌توانید این موارد را به‌صورت اختیاری تنظیم کنید:

x-openclaw-message-channel: <channel> (مثال: slack، telegram)
x-openclaw-account-id: <accountId> (هنگامی که چند حساب وجود دارد)
x-openclaw-message-to: <target> (مقصد تحویل برای خط‌مشی ابزار پیام)
x-openclaw-thread-id: <threadId> (زمینهٔ رشته برای خط‌مشی ابزار پیام)

پاسخ‌ها

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

مثال

bash

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": {}  }'

مرتبط

Was this useful?