Gateway

ابزارها 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"): نیازی به سرآیند احراز هویت نیست

نکات:

mode="token" از gateway.auth.token (یا OPENCLAW_GATEWAY_TOKEN) استفاده می‌کند.
mode="password" از gateway.auth.password (یا OPENCLAW_GATEWAY_PASSWORD) استفاده می‌کند.
mode="trusted-proxy" مستلزم آن است که درخواست HTTP از یک مبدأ پراکسی مورد اعتماد پیکربندی‌شده آمده باشد؛ پراکسی‌های 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 یک سطح دارای دسترسی کامل اپراتور در نظر بگیرید.

احراز هویت bearer در HTTP در اینجا مدل محدوده محدود برای هر کاربر نیست.
توکن/گذرواژه معتبر Gateway برای این نقطه پایانی باید مانند اعتبارنامه مالک/اپراتور در نظر گرفته شود.
در حالت‌های احراز هویت با راز مشترک (token و password)، نقطه پایانی حتی اگر فراخواننده سرآیند محدودتر x-openclaw-scopes را ارسال کند، پیش‌فرض‌های عادی و کامل اپراتور را بازیابی می‌کند.
احراز هویت با راز مشترک همچنین فراخوانی مستقیم ابزار در این نقطه پایانی را نوبت‌های فرستنده-مالک در نظر می‌گیرد.
حالت‌های HTTP مورد اعتماد و حامل هویت (احراز هویت پراکسی مورد اعتماد، یا gateway.auth.mode="none" در یک ورودی خصوصی) در صورت وجود، x-openclaw-scopes را رعایت می‌کنند و در غیر این صورت به مجموعه محدوده پیش‌فرض عادی اپراتور بازمی‌گردند.
این نقطه پایانی را فقط روی 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 برمی‌گرداند.

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

تأییدهای Exec حفاظ‌های اپراتور هستند، نه یک مرز مجوزدهی جداگانه برای این نقطه پایانی HTTP. اگر ابزاری در اینجا از طریق احراز هویت Gateway و سیاست ابزار قابل دسترسی باشد، /tools/invoke درخواست تأیید اضافی برای هر فراخوانی ایجاد نمی‌کند.
اگر exec در اینجا قابل دسترسی باشد، آن را یک سطح پوسته تغییردهنده در نظر بگیرید. رد کردن write، edit، apply_patch یا ابزارهای نوشتن فایل‌سیستم از طریق HTTP، اجرای پوسته را فقط‌خواندنی نمی‌کند.
اعتبارنامه‌های bearer مربوط به 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: {      // ابزارهای اضافی برای مسدودسازی از طریق HTTP /tools/invoke      deny: ["browser"],      // حذف ابزارها از فهرست رد پیش‌فرض برای فراخوانندگان مالک/مدیر      allow: ["gateway"],    },  },}

gateway.tools.allow یک بازنویسیِ میزان در معرض بودن است، نه ارتقای محدوده. در حالت‌های HTTP حامل هویت، cron، gateway و nodes حتی در صورت درج در gateway.tools.allow، برای فراخوانندگانی که هویت مالک/مدیر (operator.admin) ندارند در دسترس نمی‌مانند. احراز هویت bearer با راز مشترک همچنان از قاعده کامل اپراتور مورد اعتماد در بالا پیروی می‌کند.

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

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?