---
read_when:
    - فراخوانی ابزارها بدون اجرای یک نوبت کامل عامل
    - ساخت خودکارسازی‌هایی که به اعمال خط‌مشی ابزار نیاز دارند
summary: یک ابزار را مستقیماً از طریق نقطهٔ پایانی HTTP Gateway فراخوانی کنید
title: ابزارها API را فراخوانی می‌کنند
x-i18n:
    generated_at: "2026-05-10T19:45:36Z"
    model: gpt-5.5
    provider: openai
    source_hash: 531e77673fb9c06d0cc8f8145d874e22f7e590dc3e4c5dee1574874af5666886
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

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` را حذف کند

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

```json
{
  "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` سفارشی کنید:

```json5
{
  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 } }` (خطای غیرمنتظرهٔ اجرای ابزار؛ پیام پاک‌سازی‌شده)

## مثال

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

## مرتبط

- [پروتکل Gateway](/fa/gateway/protocol)
- [ابزارها و plugins](/fa/tools)