---
read_when:
    - فراخوانی ابزارها بدون اجرای یک نوبت کامل عامل
    - ساخت خودکارسازی‌هایی که به اعمال خط‌مشی ابزار نیاز دارند
summary: فراخوانی مستقیم یک ابزار واحد از طریق نقطهٔ پایانی HTTP در Gateway
title: ابزارها API را فراخوانی می‌کنند
x-i18n:
    generated_at: "2026-07-12T10:07:12Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6d07f765d63255e718d5e558b662589e77b2992538f43288cd83e6e3f2a06dda
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

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

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

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

## مرتبط

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