---
read_when:
    - فراخوانی ابزارها بدون اجرای یک نوبت کامل عامل
    - ساخت خودکارسازی‌هایی که به اعمال سیاست ابزار نیاز دارند
summary: فراخوانی مستقیم یک ابزار واحد از طریق نقطهٔ پایانی HTTP Gateway
title: API فراخوانی ابزارها
x-i18n:
    generated_at: "2026-04-29T22:57:05Z"
    model: gpt-5.5
    provider: openai
    source_hash: 7ba20b7471de76e7f6bccc4d7a3d72c00d9d7b9843ad4e74825685c992a33f1a
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

# فراخوانی ابزارها (HTTP)

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

- `POST /tools/invoke`
- همان پورت Gateway (چندplex کردن WS + HTTP): `http://<gateway-host>:<port>/tools/invoke`

حداکثر اندازهٔ پیش‌فرض payload برابر با ۲ مگابایت است.

## احراز هویت

از پیکربندی احراز هویت 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` (رشته، اختیاری): اگر schema ابزار از `action` پشتیبانی کند و payload آرگومان‌ها آن را حذف کرده باشد، در 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`
- خط‌مشی‌های گروهی (اگر کلید نشست به یک گروه یا کانال نگاشت شود)
- خط‌مشی subagent (هنگام فراخوانی با کلید نشست subagent)

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

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

- تأییدهای Exec حفاظ‌های اپراتور هستند، نه یک مرز مجوزدهی جداگانه برای این نقطهٔ پایانی HTTP. اگر ابزاری از طریق احراز هویت Gateway + خط‌مشی ابزار اینجا قابل‌دسترسی باشد، `/tools/invoke` یک درخواست تأیید اضافی برای هر فراخوان اضافه نمی‌کند.
- اعتبارنامه‌های bearer مربوط به Gateway را با فراخوان‌های نامطمئن به اشتراک نگذارید. اگر به جداسازی بین مرزهای اعتماد نیاز دارید، gatewayهای جداگانه اجرا کنید (و در حالت ایده‌آل، کاربران/میزبان‌های جداگانهٔ سیستم‌عامل).

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

- `exec` — اجرای مستقیم فرمان (سطح RCE)
- `spawn` — ایجاد فرایند فرزند دلخواه (سطح RCE)
- `shell` — اجرای فرمان shell (سطح RCE)
- `fs_write` — تغییر دلخواه فایل روی میزبان
- `fs_delete` — حذف دلخواه فایل روی میزبان
- `fs_move` — جابه‌جایی/تغییر نام دلخواه فایل روی میزبان
- `apply_patch` — اعمال 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"],
    },
  },
}
```

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

- `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)
- [ابزارها و Pluginها](/fa/tools)
