---
read_when:
    - پیاده‌سازی یا به‌روزرسانی کلاینت‌های WS برای Gateway
    - اشکال‌زدایی عدم تطابق پروتکل یا خطاهای اتصال
    - بازسازی مجدد شِما/مدل‌های پروتکل
summary: 'پروتکل WebSocket در Gateway: دست‌دهی، فریم‌ها، نسخه‌بندی'
title: پروتکل Gateway
x-i18n:
    generated_at: "2026-07-27T16:30:43Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 89d637a9070bc6512a182fea0fd890b56287e0080515ba4fba9b2591c6247e0d
    source_path: gateway/protocol.md
    workflow: 16
---

پروتکل WS مربوط به Gateway، صفحهٔ کنترل واحد و مسیر انتقال Node برای
OpenClaw است. کلاینت‌های اپراتور و Node (CLI، رابط وب، برنامهٔ macOS، Nodeهای iOS/Android،
Nodeهای بدون رابط) از طریق WebSocket متصل می‌شوند و هنگام
دست‌دهی، یک **نقش** و **دامنه** اعلام می‌کنند.

## بسته‌های npm

این بسته‌ها همراه با چرخه‌های انتشار OpenClaw عرضه می‌شوند. در طول عرضهٔ اولیه،
ممکن است npm تا زمان انتشار نخستین نسخهٔ حاوی بسته، `E404` را برگرداند.

- [`@openclaw/gateway-protocol`](https://www.npmjs.com/package/@openclaw/gateway-protocol)
  طرح‌واره‌ها، اعتبارسنج‌ها، نوع‌های TypeScript، ابزارهای کمکی سبک برای فریم و خطا
  و ثابت‌های نسخه را منتشر می‌کند. فایل tarball آن شامل قرارداد ماشین‌خوانِ تولیدشدهٔ
  [`protocol.schema.json`](https://unpkg.com/@openclaw/gateway-protocol/protocol.schema.json)
  است.
- [`@openclaw/gateway-client`](https://www.npmjs.com/package/@openclaw/gateway-client)
  کلاینت مرجع Node و یک ورودی امن برای مرورگر را در
  `@openclaw/gateway-client/browser` منتشر می‌کند.

برای راهنمایی دربارهٔ چرخهٔ عمر برنامه، به
[ساخت کلاینت Gateway](https://docs.openclaw.ai/gateway/clients) مراجعه کنید. برای برنامه‌هایی
که بر Gateway به‌عنوان یک فرایند فرزند نظارت می‌کنند، به
[جاسازی OpenClaw](https://docs.openclaw.ai/gateway/embedding) مراجعه کنید.

## انتقال و فریم‌بندی

- WebSocket، فریم‌های متنی، محموله‌های JSON.
- فریم نخست **باید** یک درخواست `connect` باشد.
- فریم‌های پیش از اتصال به 64 KiB (`MAX_PREAUTH_PAYLOAD_BYTES`) محدودند. پس از
  دست‌دهی، از `hello-ok.policy.maxPayload` و
  `hello-ok.policy.maxBufferedBytes` پیروی کنید. وقتی عیب‌یابی فعال باشد، فریم‌های ورودی
  بیش‌ازحد بزرگ و بافرهای خروجی کند، پیش از آنکه Gateway فریم را ببندد یا
  کنار بگذارد، رویدادهای `payload.large` را منتشر می‌کنند. این رویدادها شامل
  `surface`، اندازه‌های بایتی، محدودیت‌ها و یک کد دلیل امن هستند و هرگز
  شامل بدنهٔ پیام‌ها، محتوای پیوست‌ها، بایت‌های خام فریم، توکن‌ها، کوکی‌ها یا
  اسرار نمی‌شوند.

شکل فریم‌ها:

- درخواست: `{type:"req", id, method, params}`
- پاسخ: `{type:"res", id, ok, payload|error}`
- رویداد: `{type:"event", event, payload, seq?, stateVersion?}`

خطاهای پاسخ از `{ code, message, details?, retryable?, retryAfterMs? }` استفاده می‌کنند.
کلاینت‌ها باید بر اساس `code` و `details.code` شاخه‌بندی کنند؛ `message` برای انسان خوانا باقی می‌ماند
و می‌تواند تغییر کند، مگر آنجا که یادداشت سازگاری خلاف آن را بیان کند. شکست‌های
مجوزدهی در سطح متد از `code: "FORBIDDEN"` در سطح بالا همراه با
جزئیات ساختاریافتهٔ دامنه‌های مفقود استفاده می‌کنند:

- دامنهٔ مفقود: `{ code: "MISSING_SCOPE", missingScope, requiredScopes }`.
  `requiredScopes` مجموعهٔ کامل دامنه‌های شناخته‌شده برای عملیات درخواستی است.
  پیام قدیمی `missing scope: <scope>` برای کلاینت‌های قدیمی‌تر حفظ شده است.

کلاینت‌ها باید ابتدا `details` را بخوانند و از پیام قدیمی فقط به‌عنوان
راهکار بازگشتی سازگاری استفاده کنند. `readMissingScopeError` و `readMissingScopeErrorDetails` از
`@openclaw/gateway-protocol/gateway-error-details` صادر می‌شوند؛ کلاینت Gateway امن برای مرورگر
آن‌ها را دوباره از `@openclaw/gateway-client/browser` صادر می‌کند.

طرح‌واره‌ها با نام‌های `GatewayErrorDetailsSchema` و
`MissingScopeErrorDetailsSchema` از `@openclaw/gateway-protocol/schema` صادر می‌شوند.
شکست‌های دامنهٔ HTTP، شیء `MISSING_SCOPE` را زیر `error.details` بازتاب می‌دهند و
از وضعیت HTTP برابر با `403` استفاده می‌کنند.

متدهای دارای اثر جانبی به کلیدهای هم‌توانی نیاز دارند (طرح‌واره را ببینید).

## دست‌دهی

Gateway یک چالش پیش از اتصال ارسال می‌کند:

```json
{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "…", "ts": 1737264000000 }
}
```

کلاینت با `connect` پاسخ می‌دهد:

```json
{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}
```

Gateway با `hello-ok` پاسخ می‌دهد:

```json
{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}
```

`server`، `features`، `snapshot`، `policy` و `auth` همگی برای
`HelloOkSchema` (`packages/gateway-protocol/src/schema/frames.ts`) الزامی هستند. `auth`
نقش/دامنه‌های مذاکره‌شده را حتی زمانی که هیچ توکن دستگاهی صادر نشده باشد گزارش
می‌کند (شکل بالا). `pluginSurfaceUrls` اختیاری است و نام‌های سطوح Plugin (برای مثال
`canvas`) را به URLهای میزبانی‌شده و دارای دامنه نگاشت می‌کند؛ ممکن است منقضی شود، بنابراین Nodeها
`node.pluginSurface.refresh` را با `{ "surface": "canvas" }` فراخوانی می‌کنند تا یک ورودی تازه دریافت کنند.
مسیر منسوخ‌شدهٔ `canvasHostUrl` / `canvasCapability` / `node.canvas.capability.refresh`
پشتیبانی نمی‌شود؛ از سطوح Plugin استفاده کنید.
`appliedConfigHash` اختیاریِ اسنپ‌شات، بازبینی پیکربندی مبدأِ حل‌شده‌ای است
که زمان اجرای فعال Gateway پذیرفته است. کلاینت‌ها می‌توانند آن را با
`config.get.configRevisionHash` مقایسه کنند تا مشخص شود آیا یک پیکربندی ذخیره‌شدهٔ جدیدتر همچنان
به راه‌اندازی مجدد نیاز دارد یا نه. `config.get.hash` همچنان بازبینی خام فایل ریشه است که
نگهبان‌های تعارض نوشتن پیکربندی از آن استفاده می‌کنند.

تا زمانی که Gateway هنوز در حال تکمیل فرایندهای جانبی راه‌اندازی است، `connect` می‌تواند یک
خطای قابل تلاش مجددِ `UNAVAILABLE` همراه با `details.reason: "startup-sidecars"` و
`retryAfterMs` برگرداند. به‌جای تلقی آن به‌عنوان شکست نهایی دست‌دهی،
در محدودهٔ بودجهٔ اتصال دوباره تلاش کنید.

وقتی توکن دستگاه صادر شود، `hello-ok.auth` آن را اضافه می‌کند:

```json
{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}
```

راه‌اندازی اولیهٔ داخلی با کد QR/راه‌اندازی، یک مسیر تحویل به موبایل است. اتصال موفق
با کد راه‌اندازی پایه، یک توکن اصلی Node به‌علاوهٔ یک توکن اپراتور محدود
برمی‌گرداند:

```json
{
  "auth": {
    "deviceToken": "…",
    "role": "node",
    "scopes": [],
    "deviceTokens": [
      {
        "deviceToken": "…",
        "role": "operator",
        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]
      }
    ]
  }
}
```

این تحویل اپراتور عمداً محدود است: برای آغاز چرخهٔ اپراتور موبایل
و راه‌اندازی بومی، از جمله `operator.talk.secrets` برای خواندن پیکربندی Talk،
کافی است، اما هیچ دامنه‌ای برای تغییر جفت‌سازی و هیچ `operator.admin` ندارد. دسترسی گسترده‌تر
به جفت‌سازی/مدیریت به یک جریان جداگانهٔ جفت‌سازی یا توکنِ تأییدشده نیاز دارد.
`hello-ok.auth.deviceTokens` را فقط زمانی پایدار ذخیره کنید که احراز هویت راه‌اندازی اولیه از طریق یک
انتقال مورداعتماد (`wss://` یا جفت‌سازی loopback/محلی) اجرا شده باشد.

کلاینت‌های مورداعتمادِ بک‌اند در همان فرایند (`client.id: "gateway-client"`،
`client.mode: "backend"`) می‌توانند در اتصال‌های مستقیم loopback هنگام احراز هویت
با توکن/گذرواژهٔ مشترک Gateway، `device` را حذف کنند. این مسیر مختص
RPCهای داخلی صفحهٔ کنترل است (برای مثال به‌روزرسانی نشست‌های عامل فرعی) و مانع از آن می‌شود
که خطوط پایهٔ قدیمی جفت‌سازی CLI/دستگاه، کار محلی بک‌اند را مسدود کنند. کلاینت‌های
راه‌دور، دارای مبدأ مرورگر، Node و کلاینت‌های صریحِ توکن دستگاه/هویت دستگاه همچنان
از بررسی‌های عادی جفت‌سازی و ارتقای دامنه عبور می‌کنند.

### نقش Worker و پروتکل بسته

Workerهای ابری از یک ورودی اختصاصی loopback از طریق تونل SSH تحت مالکیت Gateway
و سنجاق‌شده به کلید میزبان استفاده می‌کنند. این ورودی فقط هویت Worker را می‌پذیرد و هرگز
احراز هویت عمومی، رویدادهای Node، RPCهای اپراتور یا متدهای Plugin را هدایت نمی‌کند. یک `connect`
سخت‌گیرانه، اعتبارنامهٔ کوتاه‌عمر و هش‌شده در حالت ذخیره را که به محیط، هش
بسته، دورهٔ مالک، نسخهٔ مجموعهٔ RPC، زمان انقضا و یک نشست تهی‌پذیر مقید است
اعتبارسنجی می‌کند؛ همچنین نسخه و مجموعهٔ قابلیت‌های فعلی را جداگانه بررسی می‌کند. موفقیت، حداقل
`worker-hello-ok` را برمی‌گرداند؛ مذاکرهٔ قابلیت‌ها مستقل از نسخهٔ عمومی پروتکل
است. فریم‌ها زیر 64 KiB باقی می‌مانند، به‌جز فریم مذاکره‌شدهٔ `worker.inference.start`
که می‌تواند تا 25 MiB باشد. فهرست مجاز بسته شامل `worker.heartbeat`،
`worker.transcript.commit`، `worker.live-event`، `worker.inference.start` و
`worker.inference.cancel` است.

ثبت‌های رونوشت از حصارگذاری دورهٔ مالک، اتصال نشست تحت مالکیت Gateway،
مقایسه‌وتعویض برگ پایه و بازپخش پایدار توالی استفاده می‌کنند؛ Gateway شناسه‌های
ورودی رونوشت و والد را از طریق نویسندهٔ عادی نشست تولید می‌کند. مالکیت و
انقضا در هر RPC دوباره بررسی می‌شوند.

### قابلیت‌های کلاینت

کلاینت‌های اپراتور می‌توانند قابلیت‌های اختیاری را در `connect.params.caps` اعلام کنند:

- `tool-events`: رویدادهای ساختاریافتهٔ چرخهٔ عمر ابزار را می‌پذیرد.
- `inline-widgets`: می‌تواند نتایج ابزارِ ویجت درون‌خطی میزبانی‌شده را رندر کند.

قابلیت‌های کلاینت، کلاینت متصل را توصیف می‌کنند، نه مجوزدهی را. ابزارهای عامل می‌توانند قابلیت‌های الزامی را اعلام کنند؛ Gateway آن ابزارها را حذف می‌کند، مگر اینکه همهٔ الزامات در `caps` کلاینت مبدأ وجود داشته باشند. اجراهای برخاسته از کانال هیچ قابلیت کلاینت Gateway ندارند، بنابراین ابزارهای محدودشده بر اساس قابلیت، حتی وقتی سیاست ابزار صراحتاً آن‌ها را مجاز می‌کند، در دسترس نیستند.

### نمونهٔ اتصال Node

```json
{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}
```

Nodeها ادعاهای قابلیت را هنگام اتصال اعلام می‌کنند:

- `caps`: دسته‌های سطح بالا مانند `camera`، `canvas`، `screen`،
  `location`، `voice`، `talk`.
- `commands`: فهرست مجاز فرمان برای فراخوانی.
- `permissions`: کلیدهای جزئی (برای مثال `screen.record`، `camera.capture`).

Gateway این موارد را به‌عنوان ادعا در نظر می‌گیرد و فهرست‌های مجاز سمت سرور را اعمال می‌کند.

## نقش‌ها و دامنه‌ها

برای مدل کامل دامنهٔ اپراتور، بررسی‌های زمان تأیید و معناشناسی راز مشترک،
به [دامنه‌های اپراتور](/fa/gateway/operator-scopes) مراجعه کنید.

نقش‌ها:

- `operator`: کلاینت صفحهٔ کنترل (CLI/UI/اتوماسیون).
- `node`: میزبان قابلیت (camera/screen/canvas/system.run).
- `worker`: میزبان اجرای ابری روی پروتکل اختصاصی و بستهٔ Worker.

دامنه‌های اپراتور (`src/gateway/operator-scopes.ts`)، مجموعهٔ کامل بسته:

- `operator.read`
- `operator.write`
- `operator.admin`
- `operator.approvals`
- `operator.pairing`
- `operator.talk.secrets`

`talk.config` همراه با `includeSecrets: true` به `operator.talk.secrets` (یا
`operator.admin`) نیاز دارد. وقتی اسرار گنجانده شده‌اند، اعتبارنامهٔ ارائه‌دهندهٔ فعال Talk را
از `talk.resolved.config.apiKey` بخوانید؛ `talk.providers.<id>.apiKey`
شکل مبدأ خود را حفظ می‌کند و ممکن است یک شیء SecretRef یا رشته‌ای پوشانده‌شده باشد.

متدهای RPC مربوط به Gateway که توسط Plugin ثبت شده‌اند می‌توانند دامنهٔ اپراتور
خود را درخواست کنند، اما این پیشوندهای رزروشدهٔ هسته همیشه به `operator.admin`
(`src/shared/gateway-method-policy.ts`) نگاشت می‌شوند: `config.*`، `exec.approvals.*`،
`wizard.*`، `update.*`.

دامنهٔ متد فقط نخستین دروازه است. برخی فرمان‌های اسلش که از طریق
`chat.send` در دسترس قرار می‌گیرند، بررسی‌های سخت‌گیرانه‌تری در سطح فرمان اعمال می‌کنند: نوشتن پایدارِ `/config set` و
`/config unset` به `operator.admin` نیاز دارد، حتی برای کلاینت‌های Gateway که
از قبل دامنهٔ اپراتور پایین‌تری دارند.

`node.pair.approve` افزون بر دامنهٔ پایهٔ متد
(`operator.pairing`)، یک بررسی دامنهٔ اضافی در زمان تأیید دارد که بر اساس
`commands` اعلام‌شدهٔ درخواست در انتظار (`src/infra/node-pairing-authz.ts`) انجام می‌شود:

| فرمان‌های اعلام‌شده                                                                                                             | دامنه‌های موردنیاز                       |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| هیچ‌کدام                                                                                                                          | `operator.pairing`                    |
| فرمان‌های عادی                                                                                                             | `operator.pairing` + `operator.write` |
| شامل `system.run`، `system.run.prepare`، `system.which`، `browser.proxy`، `fs.listDir` یا `system.execApprovals.get/set` | `operator.pairing` + `operator.admin` |

### قابلیت‌ها/فرمان‌ها/مجوزها (Node)

Nodeها هنگام اتصال، ادعاهای قابلیت را اعلام می‌کنند:

- `caps`: دسته‌های سطح‌بالای قابلیت مانند `camera`، `canvas`، `screen`،
  `location`، `voice` و `talk`.
- `commands`: فهرست مجاز فرمان‌ها برای فراخوانی.
- `permissions`: کلیدهای تغییر وضعیت جزئی (برای مثال `screen.record`، `camera.capture`).

Gateway این موارد را به‌عنوان **ادعا** در نظر می‌گیرد و فهرست‌های مجاز را در سمت سرور اعمال می‌کند.
Nodeهای متصل می‌توانند پس از اتصال یا اتصال مجدد موفق، توصیفگرهای اختیاری ابزار Plugin یا MCP را که برای عامل قابل‌مشاهده‌اند با
`node.pluginTools.update` منتشر کنند. میزبان‌های Node بدون رابط برای اعمال تغییرات اعلانی موجودی MCP
دوباره راه‌اندازی می‌شوند. این روش به‌روزرسانی تنها مسیر انتشار است؛ توصیفگرهای ابزار Plugin در
پارامترهای `connect` پذیرفته نمی‌شوند. هر توصیفگر باید از یک `name` ابزار امن برای ارائه‌دهنده استفاده کند و
یک `command` را در فهرست مجاز فرمان‌های کنونی Node نام ببرد. Gateway به فرادادهٔ توصیفگر
از Node جفت‌شده اعتماد می‌کند، توصیفگرهای خارج از سطح فرمان تأییدشده را فیلتر می‌کند،
هنگام قطع اتصال Node آن‌ها را حذف می‌کند و تلاش‌های اپراتور برای
تغییر کاتالوگ Node دیگری را رد می‌کند. برای نادیده‌گرفتن توصیفگرهای منتشرشده توسط Node، `gateway.nodes.pluginTools.enabled: false`
را تنظیم کنید.

میزبان‌های Node متصل، کاتالوگ جایگزین کامل مهارت‌های خود را با
`node.skills.update` منتشر می‌کنند. این روش مخصوص نقش Node تنها مسیر انتشار مهارت‌های Node
است؛ مهارت‌ها در پارامترهای `connect` پذیرفته نمی‌شوند. هر توصیفگر شامل
نامی امن، توضیح و محتوای محدودشدهٔ `SKILL.md` است. Gateway آن
محتوا را با بارگذار معمول مهارت‌ها تجزیه می‌کند، تا زمانی که Node متصل است آن را در نماهای لحظه‌ای مهارت عامل
می‌گنجاند و هنگام قطع اتصال حذف می‌کند. برای نادیده‌گرفتن مهارت‌های منتشرشده توسط Node،
`gateway.nodes.allowSkills: false` را تنظیم کنید.

## حضور

- `system-presence` ورودی‌هایی را برمی‌گرداند که بر پایهٔ هویت دستگاه کلیدگذاری شده‌اند و شامل
  `deviceId`، `roles` و `scopes` هستند؛ بنابراین رابط‌های کاربری می‌توانند برای هر دستگاه یک ردیف نمایش دهند، حتی
  وقتی دستگاه هم به‌عنوان اپراتور و هم به‌عنوان Node متصل می‌شود.
- `node.list` شامل `lastSeenAtMs` و `lastSeenReason` اختیاری است. Nodeهای متصل
  زمان اتصال کنونی را با دلیل `connect` گزارش می‌کنند؛ Nodeهای جفت‌شده همچنین می‌توانند
  حضور پایدار در پس‌زمینه را از طریق یک رویداد مورداعتماد Node گزارش کنند.

Nodeهای بومی macOS همچنین می‌توانند رویدادهای احرازهویت‌شدهٔ `node.presence.activity` را
با زمان بیکاری ورودی محدودشده ارسال کنند. Gateway مُهرهای زمانی فعالیت را بر اساس
ساعت خودش استخراج می‌کند، تازه‌ترین Mac متصل را از طریق `node.list` و
`node.describe` ارائه می‌دهد و به‌روزرسانی‌های `node.presence` را برای کلاینت‌های دارای دامنهٔ خواندن پخش می‌کند.
وقتی کاربر اشتراک‌گذاری فعالیت را غیرفعال می‌کند، برنامه `{ "action": "clear" }` را ارسال می‌کند؛
Gateway مُهرهای زمانی را فقط برای همان اتصال احرازهویت‌شدهٔ دقیق Node پاک می‌کند.
Gatewayهایی که پیش از این اقدام تأییدشونده هستند، آن را مدیریت‌نشده برمی‌گردانند؛ بنابراین Node
مبتنی بر Mac یک بار دوباره متصل می‌شود و اجازه می‌دهد پاک‌سازی هنگام قطع اتصال، وضعیت اتصال قدیمی را حذف کند.
برای رفتار انتخاب، حریم خصوصی، زمینهٔ مدل و مسیریابی اعلان‌ها، به [حضور رایانهٔ فعال](/fa/nodes/presence)
مراجعه کنید.

### رویداد زنده‌بودن Node در پس‌زمینه

Nodeها برای ثبت اینکه یک
Node جفت‌شده هنگام بیدارشدن در پس‌زمینه زنده بوده است، بدون علامت‌گذاری آن به‌عنوان متصل، `node.event` را با `event: "node.presence.alive"` فراخوانی می‌کنند:

```json
{
  "event": "node.presence.alive",
  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}
```

`trigger` یک شمارش بسته است: `background`، `silent_push`، `bg_app_refresh`،
`significant_location`، `manual`، `connect`. مقادیر ناشناخته به
`background` (`src/shared/node-presence.ts`) نرمال‌سازی می‌شوند. رویداد فقط برای
نشست‌های احرازهویت‌شدهٔ دستگاه Node پایدار می‌شود؛ نشست‌های بدون دستگاه یا جفت‌نشده
`handled: false` را برمی‌گردانند.

Gatewayهای موفق نتیجه‌ای ساختاریافته برمی‌گردانند:

```json
{
  "ok": true,
  "event": "node.presence.alive",
  "handled": true,
  "reason": "persisted"
}
```

Gatewayهای قدیمی‌تر ممکن است برای `node.event` فقط `{ "ok": true }` را برگردانند؛ آن را
یک RPC تأییدشده در نظر بگیرید، نه ذخیره‌سازی پایدار حضور.

## دامنه‌بندی رویدادهای پخشی

رویدادهای پخشی ارسال‌شده از سرور با دامنه محدود می‌شوند تا نشست‌های
محدود به جفت‌سازی یا فقط Node، محتوای نشست را به‌طور منفعل دریافت نکنند
(`src/gateway/server-broadcast.ts`):

- قاب‌های گفت‌وگو، عامل و نتیجهٔ ابزار (رویدادهای جریانی `agent`، رویدادهای نتیجهٔ ابزار)
  دست‌کم به `operator.read` نیاز دارند. نشست‌های فاقد آن، این
  قاب‌ها را کاملاً رد می‌کنند.
- پخش‌های `plugin.*` تعریف‌شده توسط Plugin به‌طور پیش‌فرض به `operator.write` یا
  `operator.admin` محدود می‌شوند؛ ورودی‌های صریحی مانند
  `plugin.approval.requested` / `plugin.approval.resolved` در عوض از
  `operator.approvals` استفاده می‌کنند.
- رویدادهای وضعیت/انتقال (`heartbeat`، `presence`، `tick`، چرخهٔ عمر اتصال/قطع اتصال)
  بدون محدودیت باقی می‌مانند تا سلامت انتقال برای همهٔ
  نشست‌های احرازهویت‌شده قابل‌مشاهده باشد.
- خانواده‌های ناشناختهٔ رویداد پخشی به‌طور پیش‌فرض با دامنه محدود می‌شوند (بسته در صورت خطا)،
  مگر اینکه یک کنترل‌کنندهٔ ثبت‌شده صراحتاً این محدودیت را کاهش دهد.

هر اتصال کلاینت شمارهٔ توالی مختص همان کلاینت را نگه می‌دارد؛ بنابراین پخش‌ها
در آن سوکت به‌صورت یکنواخت صعودی مرتب می‌مانند، حتی وقتی کلاینت‌های مختلف
زیرمجموعه‌های متفاوتی از جریان رویداد را پس از فیلتر دامنه می‌بینند.

## خانواده‌های روش RPC

`hello-ok.features.methods` یک فهرست اکتشافی محافظه‌کارانه است که از
`src/gateway/server-methods-list.ts` به‌همراه خروجی‌های روش Plugin/کانال بارگذاری‌شده
ساخته می‌شود؛ این فهرست، خروجی تولیدشدهٔ همهٔ روش‌ها نیست و برخی روش‌ها (برای
مثال `push.test`، `web.login.start`، `web.login.wait`، `sessions.usage`)
عمداً از اکتشاف کنار گذاشته شده‌اند، هرچند روش‌هایی واقعی و قابل‌فراخوانی
هستند. این را اکتشاف قابلیت در نظر بگیرید، نه فهرست کامل
`src/gateway/server-methods/*.ts`.

<AccordionGroup>
  <Accordion title="سامانه و هویت">
    - `health` نمای لحظه‌ای ذخیره‌شده یا تازه بررسی‌شدهٔ سلامت Gateway را برمی‌گرداند.
    - `diagnostics.stability` ثبت‌کنندهٔ اخیر، محدود و تشخیصی پایداری را برمی‌گرداند: نام رویدادها، تعدادها، اندازه‌های بایتی، خوانش‌های حافظه، وضعیت صف/نشست، نام‌های کانال/Plugin و شناسه‌های نشست. بدون متن گفت‌وگو، بدنه‌های Webhook، خروجی ابزار، بدنهٔ خام درخواست/پاسخ، توکن، کوکی یا اسرار. به `operator.read` نیاز دارد.
    - `status` خلاصهٔ Gateway به سبک `/status` را برمی‌گرداند؛ فیلدهای حساس فقط برای کلاینت‌های اپراتور دارای دامنهٔ مدیریت.
    - `gateway.identity.get` هویت دستگاه Gateway را که در جریان‌های رله و جفت‌سازی استفاده می‌شود برمی‌گرداند.
    - `system-presence` نمای لحظه‌ای حضور کنونی دستگاه‌های اپراتور/Node متصل را برمی‌گرداند.
    - `system-event` یک رویداد سیستمی اضافه می‌کند و می‌تواند زمینهٔ حضور را به‌روزرسانی/پخش کند.
    - `last-heartbeat` آخرین رویداد Heartbeat ذخیره‌شده را برمی‌گرداند.
    - `set-heartbeats` پردازش Heartbeat را در Gateway فعال یا غیرفعال می‌کند.
    - `gateway.suspend.prepare` فقط زمانی یک اجارهٔ کوتاه تعلیق مشارکتی ایجاد می‌کند که کار رهگیری‌شدهٔ Gateway بیکار باشد. `gateway.suspend.status` آن اجاره را بررسی می‌کند و `gateway.suspend.resume` پس از خروج از حالت انجماد یا عملیات لغوشدهٔ میزبان، آن را آزاد می‌کند.

  </Accordion>

  <Accordion title="مدل‌ها و میزان استفاده">
    - `models.list` کاتالوگ مدل‌های مجاز در زمان اجرا را برمی‌گرداند. بخش «نماهای `models.list`» را در ادامه ببینید.
    - `usage.status` خلاصهٔ بازه‌های استفاده/سهمیهٔ باقی‌ماندهٔ ارائه‌دهنده را برمی‌گرداند.
    - `usage.cost` خلاصهٔ تجمیعی هزینهٔ استفاده را برای یک بازهٔ زمانی برمی‌گرداند. برای یک عامل، `agentId` را ارسال کنید یا برای تجمیع عامل‌های پیکربندی‌شده، `agentScope: "all"` را ارسال کنید.
    - `doctor.memory.status` آمادگی حافظهٔ برداری / تعبیهٔ ذخیره‌شده برای فضای کاری عامل پیش‌فرض فعال را برمی‌گرداند. `{ "probe": true }` یا `{ "deep": true }` را فقط برای پینگ صریح و زندهٔ ارائه‌دهندهٔ تعبیه ارسال کنید. برای محدودکردن آمار مخزن Dreaming به فضای کاری یک عامل، `{ "agentId": "agent-id" }` را ارسال کنید؛ حذف آن باعث تجمیع فضاهای کاری پیکربندی‌شدهٔ Dreaming می‌شود.
    - `doctor.memory.dreamDiary`، `doctor.memory.backfillDreamDiary`، `doctor.memory.resetDreamDiary`، `doctor.memory.resetGroundedShortTerm`، `doctor.memory.repairDreamingArtifacts` و `doctor.memory.dedupeDreamDiary` مقدار اختیاری `{ "agentId": "agent-id" }` را می‌پذیرند؛ اگر حذف شود، روی فضای کاری عامل پیش‌فرض پیکربندی‌شده عمل می‌کنند.
    - `doctor.memory.remHarness` یک پیش‌نمایش محدود و فقط‌خواندنی از مهار REM را برای کلاینت‌های صفحهٔ کنترل راه‌دور برمی‌گرداند که شامل مسیرهای فضای کاری، قطعه‌های حافظه، Markdown زمینه‌دار رندرشده و نامزدهای ارتقای عمیق است. به `operator.read` نیاز دارد.
    - `sessions.usage` خلاصهٔ استفاده به‌ازای هر نشست را برمی‌گرداند. برای یک عامل، `agentId` را ارسال کنید یا برای فهرست‌کردن عامل‌های پیکربندی‌شده در کنار هم، `agentScope: "all"` را ارسال کنید.
      هر دو روش استفاده، `mode: "specific"` را با یک `timeZone` از IANA برای مرزها و بازه‌های روز تقویمی آگاه از DST می‌پذیرند. `utcOffset` همچنان برای کلاینت‌های قدیمی‌تر و به‌عنوان گزینهٔ جایگزین هنگامی که محیط اجرای Gateway منطقهٔ درخواستی را تشخیص نمی‌دهد، پشتیبانی می‌شود.
    - `sessions.usage.timeseries` استفادهٔ سری زمانی را برای یک نشست برمی‌گرداند.
    - `sessions.usage.logs` ورودی‌های گزارش استفاده را برای یک نشست برمی‌گرداند.

  </Accordion>

  <Accordion title="کانال‌ها و کمک‌ابزارهای ورود">
    - `channels.status` خلاصهٔ وضعیت کانال/Plugin داخلی و همراه را برمی‌گرداند.
    - `channels.logout` در صورت پشتیبانی کانال، از یک کانال/حساب مشخص خارج می‌شود.
    - `web.login.start` جریان ورود QR/وب را برای ارائه‌دهندهٔ کنونی کانال وب دارای قابلیت QR آغاز می‌کند.
    - `web.login.wait` منتظر تکمیل آن جریان می‌ماند و در صورت موفقیت، کانال را راه‌اندازی می‌کند.
    - `push.test` یک اعلان آزمایشی APNs به یک Node ثبت‌شدهٔ iOS ارسال می‌کند.
    - `voicewake.get` محرک‌های ذخیره‌شدهٔ واژهٔ بیدارباش را برمی‌گرداند.
    - `voicewake.set` محرک‌های واژهٔ بیدارباش را به‌روزرسانی و تغییر را پخش می‌کند.

  </Accordion>

  <Accordion title="مدیریت Plugin">
    - `plugins.list` (`operator.read`) فهرست Pluginهای نصب‌شده را به‌همراه گزینه‌های رسمی منتخب محلی، اطلاعات عیب‌یابی، و اینکه آیا حالت نصب فعلی اجازه اعمال تغییرات را می‌دهد، برمی‌گرداند.
    - `plugins.search` (`operator.read`) خانواده‌های کد-Plugin و بسته-Plugin قابل‌نصب ClawHub را جست‌وجو می‌کند. مقدار غیرخالی `query` و مقدار اختیاری `limit` از 1 تا 100 را ارسال کنید.
    - `plugins.install` (`operator.admin`) یا یک ورودی کاتالوگ رسمی را با `{ source: "official", pluginId }` نصب می‌کند، یا یک بسته ClawHub را با `{ source: "clawhub", packageName, version?, acknowledgeClawHubRisk? }`. نصب‌های ClawHub بررسی‌های اعتماد Gateway، یکپارچگی، و سیاست نصب را حفظ می‌کنند. نصب‌های موفق به راه‌اندازی مجدد Gateway نیاز دارند.
    - `plugins.setEnabled` (`operator.admin`) سیاست فعال‌بودن یک Plugin نصب‌شده را با `{ pluginId, enabled }` تغییر می‌دهد. پاسخ شامل ورودی کاتالوگ به‌روزشده، فراداده راه‌اندازی مجدد، و هرگونه هشدار انتخاب جایگاه است.
    - `plugins.uninstall` (`operator.admin`) یک Plugin نصب‌شده خارجی را با `{ pluginId }` حذف می‌کند: ارجاع‌های پیکربندی، رکورد نصب، و فایل‌های مدیریت‌شده. Pluginهای همراه را نمی‌توان حذف نصب کرد و فقط می‌توان آن‌ها را غیرفعال کرد. پاسخ، اقدامات حذف را فهرست می‌کند و همیشه به راه‌اندازی مجدد Gateway نیاز دارد.

  </Accordion>

  <Accordion title="پیام‌رسانی و گزارش‌ها">
    - `send`، RPC تحویل خروجی مستقیم برای ارسال‌های هدف‌گیری‌شده بر اساس کانال/حساب/رشته، خارج از اجراکننده چت است.
    - `logs.tail` دنباله گزارش فایل پیکربندی‌شده Gateway را با کنترل‌های مکان‌نما/حد و حداکثر بایت برمی‌گرداند.

  </Accordion>

  <Accordion title="پایانه اپراتور">
    - `terminal.open` یک PTY میزبان را برای `agentId` صریح یا عامل پیش‌فرض آغاز می‌کند و عامل نهایی، دایرکتوری کاری، پوسته، و وضعیت محدودسازی را برمی‌گرداند.
    - `terminal.input`، `terminal.resize`، و `terminal.close` فقط روی نشست‌هایی عمل می‌کنند که متعلق به اتصال فراخواننده هستند.
    - `terminal.upload` یک فایل base64 تا سقف 16 MiB می‌پذیرد، آن را در یک دایرکتوری موقت خصوصی 24 ساعته روی Gateway نشست یا میزبان Node جفت‌شده قرار می‌دهد، و مسیر مطلق را برمی‌گرداند. فراخواننده همچنان باید آن مسیر را جای‌گذاری یا به‌نحوی دیگر استفاده کند؛ RPC هرگز ورودی پایانه را نمی‌نویسد یا فرمانی را اجرا نمی‌کند.
    - رویدادهای `terminal.data` و `terminal.exit` فقط به اتصالی جریان می‌یابند که مالک نشست است.
    - نشست‌هایی که اتصالشان قطع می‌شود، جدا می‌شوند، نه متوقف: آن‌ها برای `gateway.terminal.detachedSessionTimeoutSeconds` قابل اتصال مجدد باقی می‌مانند (پیش‌فرض 300؛ `0` توقف هنگام قطع اتصال را بازمی‌گرداند)، درحالی‌که خروجی اخیر در یک بافر محدود سمت سرور انباشته می‌شود.
    - `terminal.list` نشست‌های قابل اتصال را برمی‌گرداند؛ `terminal.attach` یک نشست زنده یا جداشده را دوباره به اتصال فراخواننده پیوند می‌دهد و بافر بازپخش را برمی‌گرداند (تصاحب به سبک tmux — مالک زنده قبلی، `terminal.exit` را با دلیل `detached` دریافت می‌کند)؛ `terminal.text` بافر را بدون اتصال، به‌صورت متن ساده می‌خواند.
    - هر متد پایانه به `operator.admin` نیاز دارد؛ `gateway.terminal.enabled` باید صراحتاً true باشد. عامل‌های کاملاً sandboxشده پذیرفته نمی‌شوند و تغییر سیاست عامل، PTYهای موجود و درحال اجرا، ازجمله موارد جداشده، را می‌بندد.

  </Accordion>

  <Accordion title="گفت‌وگو و TTS">
    - `talk.catalog` کاتالوگ فقط‌خواندنی ارائه‌دهندگان گفت‌وگو را برای گفتار، رونویسی جریانی، و صدای بلادرنگ برمی‌گرداند: شناسه‌های استاندارد ارائه‌دهنده، نام‌های مستعار رجیستری، برچسب‌ها، وضعیت پیکربندی‌شده، نتیجه اختیاری `ready` در سطح گروه، شناسه‌های مدل/صدای در معرض نمایش، حالت‌های استاندارد، انتقال‌ها، راهبردهای مغز، و پرچم‌های صوتی/قابلیتی بلادرنگ، بدون بازگرداندن اسرار ارائه‌دهنده یا تغییر پیکربندی سراسری. Gatewayهای فعلی پس از اعمال انتخاب ارائه‌دهنده زمان اجرا، `ready` را تنظیم می‌کنند؛ نبود آن در Gatewayهای قدیمی‌تر را تأییدنشده در نظر بگیرید.
    - `talk.config` محموله پیکربندی مؤثر گفت‌وگو را برمی‌گرداند؛ `includeSecrets` به `operator.talk.secrets` (یا `operator.admin`) نیاز دارد.
    - `talk.session.create` یک نشست گفت‌وگوی تحت مالکیت Gateway را برای `realtime/gateway-relay`، `transcription/gateway-relay`، یا `stt-tts/managed-room` ایجاد می‌کند. برای `stt-tts/managed-room`، فراخوانندگان `operator.write` که `sessionKey` را ارسال می‌کنند، باید `spawnedBy` را نیز برای مشاهده کلید نشست در محدوده ارسال کنند؛ ایجاد `sessionKey` بدون محدوده و `brain: "direct-tools"` به `operator.admin` نیاز دارند.
    - `talk.session.join` توکن نشست اتاق مدیریت‌شده را اعتبارسنجی می‌کند، در صورت نیاز `session.ready` یا `session.replaced` را منتشر می‌کند، و فراداده اتاق/نشست را به‌همراه رویدادهای اخیر گفت‌وگو برمی‌گرداند، اما هرگز توکن متن ساده یا هش آن را بازنمی‌گرداند.
    - `talk.session.appendAudio` صوت ورودی PCM با کدگذاری base64 را به نشست‌های رونویسی و رله بلادرنگ تحت مالکیت Gateway اضافه می‌کند.
    - `talk.session.startTurn`، `talk.session.endTurn`، و `talk.session.cancelTurn` چرخه عمر نوبت اتاق مدیریت‌شده را با رد نوبت منقضی پیش از پاک‌شدن وضعیت هدایت می‌کنند.
    - `talk.session.cancelOutput` خروجی صوتی دستیار را متوقف می‌کند؛ کاربرد اصلی آن ورود مزاحم کنترل‌شده با VAD در نشست‌های رله Gateway است.
    - `talk.session.submitToolResult` فراخوانی ابزار ارائه‌دهنده را که یک نشست رله بلادرنگ تحت مالکیت Gateway منتشر کرده است، تکمیل می‌کند. درخواست منتظر هر سیگنال تکمیل ناهمگامی می‌ماند که پل ارائه‌دهنده در معرض نمایش قرار می‌دهد؛ ارسال‌های ناموفق، اجرای پیوندخورده را فعال نگه می‌دارند و رویداد نتیجه ابزار موفق منتشر نمی‌کنند. برای خروجی موقت ابزار، `options: { willContinue: true }` را ارسال کنید؛ یا وقتی پل ارائه‌دهنده پشتیبانی از سرکوب را اعلام می‌کند و نتیجه نباید پاسخ دیگری را آغاز کند، `options: { suppressResponse: true }` را ارسال کنید.
    - `talk.session.steer` کنترل صوتی اجرای فعال را به یک نشست گفت‌وگوی مبتنی بر عامل و تحت مالکیت Gateway ارسال می‌کند: `{ sessionId, text, mode? }`، که در آن `mode` یکی از `status`، `steer`، `cancel`، یا `followup` است؛ حالت حذف‌شده بر اساس متن گفتاری دسته‌بندی می‌شود.
    - `talk.session.close` یک نشست رله، رونویسی، یا اتاق مدیریت‌شده تحت مالکیت Gateway را می‌بندد و رویدادهای پایانی گفت‌وگو را منتشر می‌کند.
    - `talk.mode` وضعیت حالت فعلی گفت‌وگو را برای کلاینت‌های WebChat/Control UI تنظیم/پخش می‌کند.
    - `talk.client.create` با استفاده از `webrtc` یا `provider-websocket` یک نشست بلادرنگ ارائه‌دهنده تحت مالکیت کلاینت را ایجاد یا از سر می‌گیرد، درحالی‌که Gateway مالک اعتبارنامه‌ها، دستورالعمل‌ها، سیاست ابزار، و `voiceSessionId` بازگردانده‌شده است. کلاینت‌ها `sessionKey` را ارسال می‌کنند و هنگام جایگزینی انتقال ارائه‌دهنده طی یک تماس، از `voiceSessionId` دوباره استفاده می‌کنند.
    - `talk.client.transcript` یک مورد نهایی‌شده `{ role, text }` را به نشست عادی عامل اضافه می‌کند. `entryId` الزامی درون `voiceSessionId` هم‌توان است؛ تلاش‌های مجدد پیام‌های رونویسی را تکراری نمی‌کنند.
    - `talk.client.close` نشست صوتی منطقی را پس از نوشتن رونویسی‌های در انتظار می‌بندد. بستن هم‌توان است و ممکن است خلاصه تماسِ فقط‌جهش را به آخرین کانال غیر WebChat نشست تحویل دهد.
    - `talk.client.toolCall` به انتقال‌های بلادرنگ تحت مالکیت کلاینت اجازه می‌دهد فراخوانی‌های ابزار ارائه‌دهنده را به سیاست Gateway ارسال کنند. نخستین ابزار پشتیبانی‌شده `openclaw_agent_consult` است؛ کلاینت‌ها یک شناسه اجرا دریافت می‌کنند و پیش از ارسال نتیجه ابزار مختص ارائه‌دهنده، منتظر رویدادهای عادی چرخه عمر چت می‌مانند. اقدامات پراثر وابسته به صدا، `VOICE_CONFIRMATION_REQUIRED:<id>` را برمی‌گردانند تا زمانی که یک گفته نهایی‌شده بعدی کاربر صراحتاً همان اقدام دقیق را تأیید کند و مشورت بعدی `confirmationId` را ارائه دهد.
    - `talk.client.steer` کنترل صوتی اجرای فعال را برای انتقال‌های بلادرنگ تحت مالکیت کلاینت ارسال می‌کند. Gateway اجرای تعبیه‌شده فعال را از `sessionKey` تشخیص می‌دهد و به‌جای کنارگذاشتن بی‌صدای هدایت، یک نتیجه ساخت‌یافته پذیرفته‌شده/ردشده برمی‌گرداند.
    - `talk.event` کانال واحد رویداد گفت‌وگو برای آداپتورهای بلادرنگ، رونویسی، STT/TTS، اتاق مدیریت‌شده، تلفن، و جلسه است.
    - `talk.speak` گفتار را از طریق ارائه‌دهنده فعال گفتارِ گفت‌وگو تولید می‌کند.
    - `tts.status` وضعیت فعال‌بودن TTS، ارائه‌دهنده فعال، ارائه‌دهندگان جایگزین، و وضعیت پیکربندی ارائه‌دهنده را برمی‌گرداند.
    - `tts.providers` فهرست قابل‌مشاهده ارائه‌دهندگان TTS را برمی‌گرداند.
    - `tts.enable` و `tts.disable` وضعیت ترجیحات TTS را تغییر می‌دهند.
    - `tts.setProvider` ارائه‌دهنده ترجیحی TTS را به‌روزرسانی می‌کند.
    - `tts.convert` تبدیل یک‌باره متن به گفتار را اجرا می‌کند.
    - `tts.speak` (`operator.write`) مقدار غیرخالی `text` را با زنجیره پیکربندی‌شده ارائه‌دهنده عمومی TTS پردازش می‌کند و یک کلیپ کامل را به‌صورت درون‌خطی در `audioBase64`، به‌همراه `provider` و فراداده اختیاری `outputFormat`، `mimeType`، و `fileExtension` برمی‌گرداند. برخلاف `tts.convert`، مسیر محلی Gateway را برنمی‌گرداند؛ برخلاف `talk.speak`، به ارائه‌دهنده گفت‌وگو نیاز ندارد. متن بیش از `tts.maxTextLength` مقدار `INVALID_REQUEST` را برمی‌گرداند؛ شکست‌های تولید مقدار `UNAVAILABLE` را برمی‌گردانند.

  </Accordion>

  <Accordion title="اسرار، پیکربندی، به‌روزرسانی و راه‌انداز">
    - `secrets.reload` ارجاع‌های فعال SecretRef را دوباره تفکیک می‌کند و وضعیت زمان اجرای آگاه از مالک را به‌صورت اتمی منتشر می‌کند. خرابی‌های مالک واجد شرایط می‌توانند با `warningCount` به‌صورت تنزل سرد یا کهنه منتشر شوند؛ خرابی‌های سخت‌گیرانه یا نگاشت‌نشده بارگذاری مجدد را رد می‌کنند و اسنپ‌شات فعال را حفظ می‌کنند.
    - `secrets.resolve` انتساب‌های رازِ مقصد فرمان را برای یک مجموعه مشخص فرمان/مقصد تفکیک می‌کند.
    - `config.get` اسنپ‌شات فعلی پیکربندی روی دیسک، `hash` خام فایل ریشه، `configRevisionHash` تفکیک‌شده و `appliedConfigHash` اختیاری را برای بازبینی تفکیک‌شده‌ای برمی‌گرداند که زمان اجرای فعال Gateway پذیرفته است.
    - `config.set` یک محموله پیکربندی اعتبارسنجی‌شده را می‌نویسد.
    - `config.patch` یک به‌روزرسانی جزئی پیکربندی را ادغام می‌کند. جایگزینی مخرب آرایه مستلزم وجود مسیر تحت‌تأثیر در `replacePaths` است؛ آرایه‌های تودرتو در ورودی‌های آرایه از مسیرهای `[]` مانند `agents.entries.*.skills` استفاده می‌کنند.
    - `config.apply` کل محموله پیکربندی را اعتبارسنجی و جایگزین می‌کند.
    - `config.schema` محموله زنده طرح‌واره پیکربندی را که ابزارهای Control UI و CLI استفاده می‌کنند برمی‌گرداند: طرح‌واره، `uiHints`، نسخه، فراداده تولید و، در صورت بارگذاری‌پذیر بودن، فراداده طرح‌واره Plugin و کانال. این محموله شامل فراداده `title` / `description` از همان برچسب‌ها و متن راهنمای رابط کاربری است؛ از جمله شاخه‌های ترکیبی شیء تودرتو، نویسه عام، عضو آرایه و `anyOf` / `oneOf` / `allOf`، هرگاه مستندات فیلد منطبق وجود داشته باشد.
    - `config.schema.lookup` یک محموله جست‌وجوی محدود به مسیر را برای یک مسیر پیکربندی برمی‌گرداند: مسیر نرمال‌شده، یک گره کم‌عمق طرح‌واره، راهنمای منطبق به‌همراه `hintPath`، `reloadKind` اختیاری و خلاصه فرزندان بلافصل برای واکاوی در UI/CLI. مقدار `reloadKind` یکی از `restart`، `hot` یا `none` (`src/config/schema.ts`) است و برنامه‌ریز بارگذاری مجدد پیکربندی Gateway را برای مسیر درخواستی بازتاب می‌دهد. گره‌های طرح‌واره جست‌وجو، مستندات کاربرمحور و فیلدهای رایج اعتبارسنجی (`title`، `description`، `type`، `enum`، `const`، `format`، `pattern`، کران‌های عدد/رشته/آرایه/شیء، `additionalProperties`، `deprecated`، `readOnly`، `writeOnly`) را نگه می‌دارند. خلاصه فرزندان، `key`، `path` نرمال‌شده، `type`، `required`، `hasChildren`، `reloadKind` اختیاری و نیز `hint` / `hintPath` منطبق را ارائه می‌کند.
    - `update.run` جریان به‌روزرسانی Gateway را اجرا می‌کند و تنها در صورت موفقیت به‌روزرسانی، راه‌اندازی مجدد را زمان‌بندی می‌کند؛ فراخواننده‌های دارای نشست می‌توانند `continuationMessage` را اضافه کنند تا هنگام راه‌اندازی، یک نوبت پیگیری عامل از طریق صف ادامه پس از راه‌اندازی مجدد از سر گرفته شود. به‌روزرسانی‌های مدیر بسته و به‌روزرسانی‌های نظارت‌شده وارسی‌کارپوشه git از صفحه کنترل، به‌جای جایگزین‌کردن درخت بسته یا تغییر خروجی وارسی‌کارپوشه/ساخت درون Gateway زنده، از تحویل جداشده به سرویس مدیریت‌شده استفاده می‌کنند. یک تحویل آغازشده، `ok: true` را همراه با `result.reason: "managed-service-handoff-started"` و `handoff.status: "started"` برمی‌گرداند. دومین `update.run` هم‌زمان که همان فرایند Gateway آن را مدیریت کند، `ok: false` را همراه با `result.reason: "managed-service-handoff-already-running"` و `handoff.status: "already-running"` برمی‌گرداند؛ ادامه آن پذیرفته نمی‌شود، بنابراین فراخواننده می‌تواند پس از تکمیل به‌روزرسانی فعال دوباره تلاش کند. به‌روزرسان‌های مستقل CLI و فرایندهای جایگزین Gateway خارج از این محافظ محلی فرایند هستند. تحویل‌های دردسترس‌نبوده یا ناموفق، `ok: false` را همراه با `managed-service-handoff-unavailable` یا `managed-service-handoff-failed` و در صورت نیاز به به‌روزرسانی دستی پوسته، به‌همراه `handoff.command` برمی‌گردانند. دردسترس‌نبودن یعنی OpenClaw فاقد مرز امن ناظر یا هویت پایدار سرویس است، مانند `OPENCLAW_SYSTEMD_UNIT` برای systemd. طی یک تحویل آغازشده، نشانگر راه‌اندازی مجدد ممکن است برای مدت کوتاهی `stats.reason: "restart-health-pending"` را گزارش کند؛ ادامه تا زمانی به‌تأخیر می‌افتد که CLI، Gateway راه‌اندازی‌شده مجدد را تأیید کند و نشانگر نهایی `ok` را بنویسد.
    - `update.status` جدیدترین نشانگر راه‌اندازی مجدد به‌روزرسانی را تازه‌سازی و برمی‌گرداند، از جمله نسخه در حال اجرا پس از راه‌اندازی مجدد، در صورت موجود بودن.
    - `wizard.start`، `wizard.next`، `wizard.status` و `wizard.cancel` راه‌انداز ورود اولیه را از طریق WS RPC ارائه می‌کنند.

  </Accordion>

  <Accordion title="ابزارهای کمکی عامل و فضای کاری">
    - `agents.list` ورودی‌های عامل قابل‌مشاهده برای Gateway را برمی‌گرداند، از جمله فراداده مؤثر مدل/زمان اجرا و `kind` معنایی اختیاری (`agent` یا `system`). کلاینت‌ها قابلیت دست‌دهی `agent-kind` را اعلام می‌کنند تا فهرست کامل نوع‌دار را دریافت کنند؛ کلاینت‌های فاقد آن، فهرست قدیمیِ امن برای انتخاب‌گر را بدون ردیف‌های سیستمی نگه می‌دارند. کلاینت‌های آگاه از نوع، ردیف‌های `system` را از انتخاب‌گرهای عادی حذف می‌کنند، اما آن‌ها را در نماهای تشخیصی نگه می‌دارند. Gatewayهای قدیمی‌تر v4 ممکن است ردیف‌هایی بدون `kind` برگردانند.
    - `agents.create`، `agents.update` و `agents.delete` رکوردهای عامل و سیم‌کشی فضای کاری را مدیریت می‌کنند.
    - `agents.files.list`، `agents.files.get` و `agents.files.set` فایل‌های راه‌اندازی اولیه فضای کاری را که برای یک عامل ارائه شده‌اند مدیریت می‌کنند.
    - `audit.activity.list` دفتر ثبت فعالیت نسخه‌بندی‌شده و صرفاً شامل فراداده را برمی‌گرداند؛ `audit.list` همچنان RPC اجرای/ابزارِ امن از نظر سازگاری است.
    - `agents.workspace.list` و `agents.workspace.get` (`operator.read`) مرور صفحه‌بندی‌شده و فقط‌خواندنی پوشه فضای کاری یک عامل را برای کلاینت‌های حاضر در دامنه اپراتور مورداعتمادِ توصیف‌شده در [دامنه‌های اپراتور](/fa/gateway/operator-scopes) ارائه می‌کنند. درخواست‌ها فقط مسیرهای نسبی به فضای کاری را می‌پذیرند؛ خواندن‌ها در ریشه فضای کاری با مسیر واقعی محدود می‌مانند (گریز از طریق پیوند نمادین و پیوند سخت رد می‌شود)، سقف اندازه دارند و به متن UTF-8 به‌همراه انواع رایج تصویر (base64) محدودند. پاسخ‌ها مسیر فضای کاری میزبان را افشا نمی‌کنند. هیچ عملیات نوشتنی در این فضای نام وجود ندارد.
    - `tasks.list`، `tasks.get` و `tasks.cancel` دفتر ثبت وظایف Gateway را در اختیار کلاینت‌های SDK و اپراتور قرار می‌دهند. [RPCهای دفتر ثبت وظایف](#task-ledger-rpcs) را در ادامه ببینید.
    - `artifacts.list`، `artifacts.get` و `artifacts.download` خلاصه‌ها و بارگیری‌های مصنوعات استخراج‌شده از رونوشت را برای یک دامنه صریح `sessionKey`، `runId` یا `taskId` ارائه می‌کنند. پرس‌وجوهای اجرا و وظیفه، نشست مالک را در سمت سرور تفکیک می‌کنند و فقط رسانه‌های رونوشت با منشأ منطبق را برمی‌گردانند؛ منابع URL ناامن یا محلی، به‌جای واکشی در سمت سرور، بارگیری پشتیبانی‌نشده برمی‌گردانند.
    - `environments.list` و `environments.status` کشف محیط محلی Gateway و Node را حفظ می‌کنند. کارکنان ابری پیکربندی‌شده و رکوردهای پایداری که نمایه‌های پیشین به‌جا گذاشته‌اند، فراداده `worker` را با `providerId`، `leaseId` اختیاری، `state`، `ageMs`، `idleMs` اختیاری و `attachedSessionIds` اضافه می‌کنند. وضعیت‌های چرخه عمر کارگر عبارت‌اند از `requested`، `provisioning`، `bootstrapping`، `ready`، `attached`، `idle`، `draining`، `destroying`، `destroyed`، `failed` و `orphaned`.
    - `environments.create` (`{ profileId, idempotencyKey }`) یک کارگر را از نمایه ارائه‌دهنده Plugin پیکربندی‌شده تأمین می‌کند؛ تلاش‌های مجدد با همان کلید، عملیات پایدار را دوباره استفاده می‌کنند. `environments.destroy` (`{ environmentId }`) برچیدن هم‌توان تکرار یک محیط کارگر پایدار را درخواست می‌کند. هر دو به `operator.admin` نیاز دارند، نوشتن‌های صفحه کنترل هستند و همان ساختار خلاصه محیط را که پاسخ‌های وضعیت استفاده می‌کنند برمی‌گردانند.
    - `agent.identity.get` هویت مؤثر دستیار را برای یک عامل یا نشست برمی‌گرداند.
    - `agent.wait` تا پایان یک اجرا منتظر می‌ماند و در صورت موجود بودن، اسنپ‌شات پایانی را برمی‌گرداند.

  </Accordion>

  <Accordion title="کنترل نشست">
    - `sessions.list` نمایهٔ فعلی نشست را برمی‌گرداند که در صورت پیکربندی‌شدن بک‌اند زمان‌اجرای عامل، فرادادهٔ `agentRuntime` هر ردیف را نیز شامل می‌شود. هنگامی که جای‌دهی cloud-worker فعال باشد یا وضعیت بازیابی پایدار وجود داشته باشد، ردیف‌های نشست افزون بر این شامل یک وضعیت بستهٔ `placement` (`local`، `requested`، `provisioning`، `syncing`، `starting`، `active`، `draining`، `reconciling`، `reclaimed` یا `failed`) به‌همراه فیلدهای مختص آن وضعیت برای محیط، دورهٔ مالک، فضای کاری، بسته، نشانگر ACK یا بازیابی هستند.
    - `sessions.subscribe` و `sessions.unsubscribe` اشتراک رویدادهای تغییر نشست را برای کلاینت WS فعلی فعال یا غیرفعال می‌کنند.
    - `sessions.messages.subscribe` و `sessions.messages.unsubscribe` اشتراک رویدادهای رونوشت/پیام را برای یک نشست فعال یا غیرفعال می‌کنند. برای دریافت رویدادهای پالایش‌شدهٔ چرخهٔ حیات `session.approval` مربوط به تأییدهایی که مخاطبان ذخیره‌شدهٔ آن‌ها دقیقاً آن نشست را شامل می‌شوند و اتصال بازبین آن‌ها به کلاینت مشترک‌شونده مجوز می‌دهد، `includeApprovals: true` را نیز ارسال کنید. سپس پاسخ اشتراک شامل `approvalReplay` معوق و کران‌داری می‌شود؛ وقتی `truncated` نادرست باشد، این مقدار مرجع معتبر است. این انتخاب برای هر فراخوانی اشتراک جداگانه است و ماندگار نیست: اشتراک دوباره در همان نشست بدون `includeApprovals: true`، اشتراک تأیید موجود را حذف می‌کند. افزون بر اختیار عادی خواندن نشست، این انتخاب به `operator.admin` یا در دستگاه جفت‌شده به `operator.approvals` نیاز دارد.
    - `sessions.preview` پیش‌نمایش‌های کران‌دار رونوشت را برای کلیدهای مشخص نشست برمی‌گرداند.
    - `sessions.describe` یک ردیف نشست Gateway را برای یک کلید دقیق نشست برمی‌گرداند.
    - `sessions.resolve` یک مقصد نشست را تفکیک یا متعارف‌سازی می‌کند.
    - `sessions.create` یک ورودی نشست جدید ایجاد می‌کند. مقادیر اختیاری `model` و `thinkingLevel` مدل اولیه و بازنویسی‌های استدلال را به‌صورت اتمی ذخیره می‌کنند. `worktree: true` یک worktree مدیریت‌شده فراهم می‌کند؛ `worktreeBaseRef`/`worktreeName` اختیاری مرجع پایه و نام شاخه را انتخاب می‌کنند و `execNode` (`operator.admin`) اجرای نشست را به یک میزبان Node متصل می‌کند. worktree ایجادشده در نتیجه بازگردانده می‌شود و در ردیف نشست (`worktree: { id, branch, repoRoot }`) ذخیره می‌شود. هنگامی که ورودی ایجاد شده اما `chat.send` اولیهٔ تو‌در‌توی آن رد شود، نتیجهٔ موفق شامل `runStarted: false` و `runError` است؛ کلاینت‌ها می‌توانند پرامپت را حفظ کنند و با کلید نشست بازگردانده‌شده دوباره تلاش کنند. فراخوانی که `parentSessionKey` را همراه `emitCommandHooks: true` ارسال می‌کند، باید نحوهٔ چرخهٔ حیات یک فرزند متمایز را نیز اعلام کند: `succeedsParent: true` والد را با `session_end` پایان می‌دهد، درحالی‌که `false` والد را فعال نگه می‌دارد و فقط `session_start` فرزند را منتشر می‌کند. حذف `succeedsParent` رفتار قدیمی انتقال والد را برای کلاینت‌های موجود حفظ می‌کند. این نحوهٔ چرخهٔ حیات هم به پیوند والد و هم به قلاب‌های فرمان نیاز دارد؛ یک انشعاب نمی‌تواند والد خود را موفق کند. رفتار بازنشانی درجا برای نشست اصلی بدون تغییر است، زیرا هیچ فرزند متمایزی ایجاد نمی‌شود. ردیف‌های جدید از درگاه ایجاد مورداعتماد با منشأ ایجاد یک‌بارنوشت (`createdVia`، `createdActor`، `createdAt`) مهر می‌خورند؛ پذیرش یک کلید موجود هرگز آن را دوباره مهر نمی‌زند. برای کنشگران دارای پروفایل انسانی، `createdActor.label` هنگام تصویرسازی ردیف از پروفایل فعلی کاربر تفکیک می‌شود و هرگز در ورودی نشست ذخیره نمی‌شود؛ بنابراین تغییر نام پروفایل باعث واگرایی نمی‌شود. ردیف‌های نشست همچنین دارای `parentSessionKey` (والد پیمایش، ذخیره‌شده)، `controlOwnerSessionKey` (کنترل‌کنندهٔ زمان‌اجرا هنگام فعال‌بودن)، `forkSource` (کلید دقیق منبع + نسل رونوشت برای انشعاب‌ها) و `previousSessionId` (نسل قبلی رونوشت زیر همان کلید) هستند.
    - `sessions.dispatch` (`operator.admin`) یک نشست محلی موجود OpenClaw را که دارای worktree مدیریت‌شده و متعلق به نشست است، به یک پروفایل cloud-worker پیکربندی‌شده منتقل می‌کند. `{ key, profileId, agentId? }` را ارسال کنید. وقتی هیچ پروفایل worker پیکربندی نشده باشد، این متد وجود ندارد؛ پیش از تخلیهٔ کار فعال، پذیرش نوبت محلی را می‌بندد و تنها پس از رسیدن جای‌دهی به مالکیت worker با وضعیت `active` بازمی‌گردد. اعزام یک‌طرفه است؛ بازکشیدن worker به محلی بخشی از این RPC نیست.
    - `sessions.groups.list`، `sessions.groups.put`، `sessions.groups.rename` و `sessions.groups.delete` کاتالوگ گروه‌های سفارشی نشست تحت مالکیت Gateway را مدیریت می‌کنند (نام‌ها + ترتیب نمایش). عضویت در فیلد `category` هر نشست باقی می‌ماند؛ تغییر نام و حذف، نشست‌های عضو را در سمت سرور به‌روزرسانی می‌کنند.
    - `sessions.send` یک پیام به نشست موجود می‌فرستد.
    - `sessions.steer` گونهٔ وقفه‌دادن و هدایت‌کردن برای یک نشست فعال است.
    - `sessions.abort` کار فعال یک نشست را لغو می‌کند. `key` را همراه `runId` اختیاری، یا فقط `runId` را برای اجراهای فعالی که Gateway می‌تواند به یک نشست تفکیک کند ارسال کنید. ارائهٔ `runId` لغو را به همان اجرا محدود نگه می‌دارد. در یک درخواست غیرسراسری که فقط کلید دارد، `clearQueued: true` را تنظیم کنید تا صف‌های پیگیری و مسیر متعلق به آن نشست نیز کنار گذاشته شوند. فراخوان‌های موجودی که `clearQueued` را حذف می‌کنند، آن صف‌ها را حفظ می‌کنند. کلید تحت‌اللفظی `global` قواعد مالکیت موجود `chat.abort` وابسته به عامل را حفظ می‌کند و پاک‌سازی غیرسراسری صف پیگیری یا مسیر را انجام نمی‌دهد.
    - `sessions.patch` فراداده/بازنویسی‌های نشست را به‌روزرسانی می‌کند و مدل متعارف تفکیک‌شده را به‌همراه `agentRuntime` مؤثر گزارش می‌دهد. تبار ایجاد (`spawnedBy`، `spawnedWorkspaceDir`، `spawnedCwd`، `spawnDepth`، `subagentRole`، `subagentControlScope`) دیگر به‌صورت عمومی قابل وصله‌کردن نیست؛ این اطلاعات فقط یک‌بار توسط مسیرهای ایجاد مورداعتماد نوشته می‌شوند و درخواست‌هایی که همچنان آن‌ها را ارسال کنند رد می‌شوند.
    - `sessions.reset`، `sessions.delete` و `sessions.compact` نگهداشت نشست را انجام می‌دهند.
    - `sessions.get` ردیف کامل ذخیره‌شدهٔ نشست را برمی‌گرداند.
    - اجرای چت همچنان از `chat.history`، `chat.send`، `chat.abort` و `chat.inject` استفاده می‌کند. `chat.history` برای کلاینت‌های رابط کاربری از نظر نمایش نرمال‌سازی می‌شود: برچسب‌های دستوری درون‌خطی از متن قابل‌مشاهده حذف می‌شوند؛ محتوای XML فراخوانی ابزار در متن ساده (`<tool_call>...</tool_call>`، `<function_call>...</function_call>`، `<tool_calls>...</tool_calls>`، `<function_calls>...</function_calls>` و بلوک‌های کوتاه‌شدهٔ فراخوانی ابزار) و توکن‌های کنترلی ASCII/تمام‌عرض مدل که نشت کرده‌اند حذف می‌شوند؛ ردیف‌های دستیار که صرفاً توکن سکوت هستند (دقیقاً `NO_REPLY` / `no_reply`) حذف می‌شوند؛ و ردیف‌های بیش‌ازحد بزرگ ممکن است با جای‌نگهدار جایگزین شوند.
    - `chat.message.get` خوانشگر افزایشی، کران‌دار و تمام‌پیام برای یک ورودی قابل‌مشاهدهٔ رونوشت است. `sessionKey`، در صورت وابسته‌بودن انتخاب نشست به عامل `agentId` اختیاری، و یک `messageId` رونوشت که پیش‌تر از طریق `chat.history` ارائه شده است را ارسال کنید؛ اگر ورودی ذخیره‌شده همچنان در دسترس باشد و بیش‌ازحد بزرگ نباشد، Gateway همان تصویرسازی نرمال‌شده برای نمایش را بدون سقف کوتاه‌سازی تاریخچهٔ سبک‌وزن برمی‌گرداند.
    - `chat.toolTitles` عنوان‌های کوتاه هدف را برای فراخوانی‌های ابزاری که در Control UI نمایش داده می‌شوند برمی‌گرداند (دسته‌ای، حداکثر 24 مورد با ورودی‌های کران‌دار). این قابلیت از طریق `gateway.controlUi.toolTitles` انتخابی است (به‌طور پیش‌فرض خاموش)؛ Gatewayهای غیرفعال به `{ titles: {}, disabled: true }` بدون فراخوانی مدل پاسخ می‌دهند تا کلاینت‌ها درخواست‌کردن را متوقف کنند. هنگام فعال‌بودن، عنوان‌ها از مسیریابی استاندارد مدل کاربردی استفاده می‌کنند: یک `utilityModel` که صریحاً پیکربندی شده باشد (تصمیم اپراتور که مانند همهٔ وظایف کاربردی ممکن است محتوای کران‌دار وظیفه را به ارائه‌دهندهٔ انتخاب‌شده بفرستد)، و در غیر این صورت مدل کوچک پیش‌فرض اعلام‌شدهٔ ارائه‌دهندهٔ نشست تا هیچ مقصد خروجی جدیدی به‌طور ضمنی ظاهر نشود؛ `utilityModel` خالی آن‌ها را کاملاً غیرفعال می‌کند. عنوان‌ها هرگز به مدل اصلی بازنمی‌گردند. نتایج در پایگاه دادهٔ وضعیت هر عامل با کلید نام ابزار + ورودی ذخیرهٔ موقت می‌شوند، بنابراین مشاهده‌های تکراری هرگز هزینهٔ دوباره برای همان فراخوانی‌ها ایجاد نمی‌کنند.
    - `chat.send` مقدار یک‌نوبتی `fastMode: "auto"` را می‌پذیرد تا برای فراخوانی‌های مدلی که پیش از آستانهٔ خودکار آغاز می‌شوند از حالت سریع استفاده کند و سپس فراخوانی‌های تلاش مجدد، بازگشت، نتیجهٔ ابزار یا ادامه را که بعدتر آغاز می‌شوند بدون حالت سریع اجرا کند. آستانه به‌طور پیش‌فرض 60 ثانیه (`DEFAULT_FAST_MODE_AUTO_ON_SECONDS`) است و می‌توان آن را برای هر مدل با `agents.defaults.models["<provider>/<model>"].params.fastAutoOnSeconds` پیکربندی کرد. فراخوان `chat.send` می‌تواند `fastAutoOnSeconds` یک‌نوبتی را برای بازنویسی آستانه در آن درخواست ارسال کند. برای بازنویسی حالت ذخیره‌شدهٔ صف فقط برای این درخواست، `queueMode` (`steer`، `followup`، `collect` یا `interrupt`) را ارسال کنید؛ کنش‌های هدایت صریح Control UI از `queueMode: "steer"` استفاده می‌کنند. کلاینت‌های تعاملی می‌توانند `expectedLeafEntryId` را همراه برگ فعال شاخهٔ رونوشت که نمایش می‌دهند، یا `null` را برای یک رونوشت خالی معتبر ارسال کنند؛ اگر کلاینت دیگری ابتدا شاخه‌ها را جابه‌جا کرده باشد، Gateway ارسال را با `details.reason: "active-leaf-changed"` رد می‌کند.

  </Accordion>

  <Accordion title="جفت‌سازی دستگاه و توکن‌های دستگاه">
    - `device.pair.list` دستگاه‌های جفت‌شدهٔ در انتظار و تأییدشده را برمی‌گرداند.
    - `device.pair.setupCode` یک کد راه‌اندازی موبایل و به‌طور پیش‌فرض یک URL دادهٔ QR از نوع PNG ایجاد می‌کند. به `operator.admin` نیاز دارد و عمداً از کشف اعلام‌شده حذف شده است. نتیجه شامل `setupCode`، `qrDataUrl` اختیاری، `gatewayUrl`، برچسب غیرمحرمانهٔ `auth` و `urlSource` است.
    - `device.pair.approve`، `device.pair.reject` و `device.pair.remove` رکوردهای جفت‌سازی دستگاه را مدیریت می‌کنند.
    - `device.pair.rename` یک برچسب اپراتور (`{ deviceId, label }`) اختصاص می‌دهد که بر نام نمایشی گزارش‌شده توسط کلاینت اولویت دارد و پس از تعمیر یا تأیید دوبارهٔ دستگاه نیز باقی می‌ماند.
    - `device.token.rotate` توکن یک دستگاه جفت‌شده را در محدوده‌های نقش تأییدشده و دامنهٔ فراخوان آن تعویض می‌کند.
    - `device.token.revoke` توکن یک دستگاه جفت‌شده را در محدوده‌های نقش تأییدشده و دامنهٔ فراخوان آن باطل می‌کند.

    کد راه‌اندازی یک اعتبارنامهٔ بوت‌استرپ کوتاه‌عمر را در خود دارد. کلاینت‌ها نباید
    آن را خارج از جریان جفت‌سازی ثبت یا ذخیره کنند.

  </Accordion>

  <Accordion title="جفت‌سازی Node، فراخوانی و کار در انتظار">
    - `node.pair.list`، `node.pair.approve`، `node.pair.reject` و `node.pair.remove` تأیید قابلیت‌های Node را پوشش می‌دهند. `node.pair.request` و `node.pair.verify` در 2026.7 همراه با مخزن مستقل جفت‌سازی Node حذف شدند؛ درخواست‌های در انتظار هنگام اتصال Nodeها توسط Gateway ایجاد می‌شوند.
    - `node.list` و `node.describe` وضعیت Nodeهای شناخته‌شده/متصل را برمی‌گردانند.
    - `node.rename` برچسب یک Node جفت‌شده را به‌روزرسانی می‌کند.
    - `node.invoke` یک فرمان را به Node متصل ارسال می‌کند.
    - `node.invoke.result` نتیجهٔ یک درخواست فراخوانی را برمی‌گرداند.
    - `mcp.tools.call.v1` فرمان میزبان Node بدون رابط گرافیکی برای فراخوانی یک ابزار MCP محلی Node پیکربندی‌شده است. این فرمان از طریق `node.invoke` منتقل می‌شود، مستلزم آن است که Node فرمان را اعلام کند و همچنان مشمول تأیید جفت‌سازی و `gateway.nodes.commands.deny` است.
    - `node.event` رویدادهای منشأگرفته از Node را به Gateway بازمی‌گرداند.
    - `node.pluginTools.update` تنها مسیر انتشار برای جایگزینی توصیف‌گرهای ابزار Plugin/MCP قابل‌مشاهده برای عامل در Node متصل است؛ پارامترهای `connect` آن‌ها را حمل نمی‌کنند.
    - `node.pending.pull` و `node.pending.ack` APIهای صف Node متصل هستند.
    - `node.pending.enqueue` و `node.pending.drain` کار پایدار در انتظار را برای Nodeهای آفلاین/قطع‌شده مدیریت می‌کنند.

  </Accordion>

  <Accordion title="خانواده‌های تأیید">
    - `approval.history` تأییدهای نهایی را با ترتیب جدیدترین به قدیمی‌ترین برمی‌گرداند که برای درخواست‌های اجرا، Plugin و عامل سیستم به‌مدت 30 روز نگه‌داری می‌شوند (محدوده `operator.approvals`). این متد از صفحه‌بندی مبتنی بر مکان‌نما و یک فیلتر اختیاری نوع پشتیبانی می‌کند؛ تأییدهای در انتظار، ردیف‌های تاریخچه نیستند.
    - `approval.get` و `approval.resolve` متدهای ماندگار تأیید و مستقل از نوع هستند (محدوده `operator.approvals`). `approval.get` یک نمای پاک‌سازی‌شده از وضعیت در انتظار یا نهایی نگه‌داری‌شده را با `urlPath` پایدار برمی‌گرداند؛ `approval.resolve` شناسه متعارف تأیید، یک `kind` صریح و یک تصمیم را می‌پذیرد، تفکیک «اولین پاسخ برنده است» را اعمال می‌کند و همیشه نتیجه متعارف ثبت‌شده را برمی‌گرداند.
    - `exec.approval.request`، `exec.approval.get`، `exec.approval.list` و `exec.approval.resolve` درخواست‌های یک‌باره تأیید اجرا و نیز جست‌وجو/بازپخش تأیید در انتظار را پوشش می‌دهند. آن‌ها آداپتورهای مرز پروتکل روی همان رجیستری ماندگار تأیید هستند.
    - `exec.approval.waitDecision` منتظر یک تأیید اجرای در انتظار می‌ماند و تصمیم نهایی را برمی‌گرداند (یا در صورت پایان مهلت، `null`).
    - `exec.approvals.get` و `exec.approvals.set` تصویرهای لحظه‌ای خط‌مشی تأیید اجرای Gateway را مدیریت می‌کنند.
    - `exec.approvals.node.get` و `exec.approvals.node.set` خط‌مشی تأیید اجرای محلی Node را از طریق فرمان‌های رله Node مدیریت می‌کنند.
    - `plugin.approval.request`، `plugin.approval.list`، `plugin.approval.waitDecision` و `plugin.approval.resolve` جریان‌های تأیید تعریف‌شده توسط Plugin را پوشش می‌دهند.

  </Accordion>

  <Accordion title="فرمان‌های رابط کاربری کنترل">
    - `ui.command` به یک فراخواننده `operator.write` اجازه می‌دهد فرمان‌های نوع‌دار چیدمان و پیمایش را به کلاینت‌های متصل رابط کاربری کنترل بفرستد که قابلیت `ui-commands` را اعلام می‌کنند.
    - فرمان‌ها تقسیم/بستن/تمرکز پنل، نمایش نوار کناری، نمایش و محل اتصال پنل ترمینال/مرورگر و پیمایش نشست را پوشش می‌دهند.
    - پروتکل v1 عمداً فرمان را به همه رابط‌های کاربری کنترل متصل و توانمند ارسال می‌کند. اگر هیچ‌کدام متصل نباشند، درخواست به‌جای وانمودکردن به تغییر چیدمان، با `UNAVAILABLE` شکست می‌خورد.

  </Accordion>

  <Accordion title="اتوماسیون، Skills و ابزارها">
    - اتوماسیون: `wake` تزریق متن بیدارباش فوری یا در Heartbeat بعدی را زمان‌بندی می‌کند؛ `cron.get`، `cron.list`، `cron.status`، `cron.add`، `cron.update`، `cron.remove`، `cron.run`، `cron.runs` کارهای زمان‌بندی‌شده را مدیریت می‌کنند.
    - `cron.run` همچنان یک RPC از نوع صف‌گذاری برای اجراهای دستی است. کلاینت‌هایی که به معناشناسی تکمیل نیاز دارند باید `runId` برگشتی را بخوانند و `cron.runs` را نظرسنجی کنند.
    - `cron.runs` یک فیلتر اختیاری و غیرخالی `runId` می‌پذیرد تا کلاینت‌ها بتوانند یک اجرای دستی صف‌شده را بدون رقابت با سایر ورودی‌های تاریخچه همان کار دنبال کنند.
    - Skills و ابزارها: `commands.list`، `skills.*`، `tools.catalog`، `tools.effective`، `tools.invoke`. بخش [متدهای کمکی اپراتور](#operator-helper-methods) را در ادامه ببینید.

  </Accordion>
</AccordionGroup>

### خانواده‌های رایج رویداد

- `chat`: به‌روزرسانی‌های گفت‌وگوی رابط کاربری مانند `chat.inject` و سایر رویدادهای گفت‌وگویی که فقط در رونوشت هستند. در پروتکل v4، محموله‌های تفاضلی `deltaText` را حمل می‌کنند؛ `message` همچنان
  تصویر تجمعی دستیار است. جایگزینی‌هایی که پیشوند نیستند
  `replace=true` را تنظیم می‌کنند و از `deltaText` به‌عنوان متن جایگزین استفاده می‌کنند.
- `session.message`، `session.operation`، `session.tool`: به‌روزرسانی‌های رونوشت، عملیات در حال اجرای
  نشست و جریان رویداد برای یک نشست مشترک‌شده.
- `session.approval`: حقیقت پاک‌سازی‌شده تأییدهای در انتظار و نهایی برای
  مشترک یک نشست دقیق که صریحاً انتخاب کرده است. تأییدهای فرزند از مخاطبان
  نیای ذخیره‌شده استفاده می‌کنند؛ رویدادها هرگز رونوشت‌ها را تغییر نمی‌دهند یا عامل‌ها را بیدار نمی‌کنند.
- `sessions.changed`: نمایه یا فراداده نشست تغییر کرده است.
- `presence`: به‌روزرسانی تصویر لحظه‌ای حضور سیستم.
- `tick`: رویداد دوره‌ای زنده‌نگه‌داشتن/فعال‌بودن.
- `health`: به‌روزرسانی تصویر لحظه‌ای سلامت Gateway.
- `heartbeat`: به‌روزرسانی جریان رویداد Heartbeat.
- `cron`: رویداد تغییر اجرا/کار Cron.
- `shutdown`: اعلان خاموش‌شدن Gateway.
- `node.pair.requested` / `node.pair.resolved`: چرخه عمر جفت‌سازی Node.
- `node.invoke.request`: پخش همگانی درخواست فراخوانی Node.
- `device.pair.requested` / `device.pair.resolved`: چرخه عمر دستگاه جفت‌شده.
- `voicewake.changed`: پیکربندی محرک واژه بیدارباش تغییر کرده است.
- `config.changed`: یک نوشتن پیکربندی ذخیره شد (محموله مسیر پیکربندی،
  هش تصویر لحظه‌ای جدید و یک مُهر زمانی را حمل می‌کند — هرگز محتوای پیکربندی را حمل نمی‌کند). محدود به خواندن اپراتور؛
  کلاینت‌ها از طریق `config.get` تازه‌سازی می‌کنند.
- `exec.approval.requested` / `exec.approval.resolved`: چرخه عمر
  تأیید اجرا.
- `plugin.approval.requested` / `plugin.approval.resolved`: چرخه عمر
  تأیید Plugin.

### متدهای کمکی Node

Nodeها می‌توانند برای دریافت فهرست کنونی فایل‌های اجرایی Skill جهت
بررسی‌های مجازسازی خودکار، `skills.bins` را فراخوانی کنند.

## RPC دفترکل ممیزی

`audit.activity.list` نمایی پایدار و مرتب‌شده از جدیدترین به قدیمی‌ترین از فراداده چرخه عمر
اجرای عامل، اقدام ابزار و پیام‌های انتخابی را در اختیار کلاینت‌های اپراتور قرار می‌دهد. این متد به
`operator.read` نیاز دارد. پرس‌وجوها رکوردهای قدیمی‌تر از 30 روز را حذف می‌کنند و دفترکل مشترک
SQLite به 100,000 رکورد محدود است. ردیف‌های منقضی‌شده هنگام
راه‌اندازی Gateway، نگه‌داری ساعتی و نوشتن‌های بعدی حذف می‌شوند. برای مدل داده و معناشناسی حریم خصوصی،
[تاریخچه ممیزی](/fa/gateway/audit) را ببینید.

- پارامترها: `agentId`، `sessionKey` یا `runId` دقیق و اختیاری؛ `kind` اختیاری
  (`"agent_run"`، `"tool_action"` یا `"message"`)؛ `status` اختیاری
  (`"started"`، `"succeeded"`، `"failed"`، `"cancelled"`، `"timed_out"`،
  `"blocked"` یا `"unknown"`)؛ `direction` پیام اختیاری (`"inbound"` یا
  `"outbound"`) و `channel` دقیق؛ کران‌های شامل و اختیاری `after` / `before`
  برحسب میلی‌ثانیه Unix؛ `limit` اختیاری از `1` تا `500`؛ و
  رشته اختیاری `cursor` از صفحه پیشین.
- نتیجه: `{ "events": AuditActivityEventV1[], "nextCursor"?: string }`.

اتحاد نام‌گذاری‌شده نتیجه V1 برای اجرای عامل، اقدام ابزار، پیام ورودی
و پیام خروجی شِماهای جداگانه دارد. متمایزکننده `eventType` به‌ترتیب
`agent_run`، `tool_action`، `inbound_message` یا `outbound_message` است؛ `kind` و
`direction` پیام برای فیلترکردن و نمایش همچنان در دسترس‌اند. هر رویداد دارای
`schemaVersion: 1` صحیح است. ارجاع‌های هویت پیام از قالب دقیق
`hmac-sha256:v1:<32 hex key id>:<64 hex digest>` استفاده می‌کنند؛ شناسه کنشگر فرستنده کانال
نیز از همان قالب استفاده می‌کند.

همه گونه‌ها به `eventType`، `schemaVersion`، `eventId`، `sequence`،
`sourceSequence`، `occurredAt`، `kind`، `action`، `status`، `actor` و
`redaction` نیاز دارند. فیلدهای هر گونه عبارت‌اند از:

| `eventType`        | فیلدهای الزامی                                                   | فیلدهای اختیاری                                                                                                                 |
| ------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `agent_run`        | `agentId`، `runId`؛ `kind: "agent_run"`                           | `sessionKey`، `sessionId`، `errorCode`                                                                                          |
| `tool_action`      | `agentId`، `runId`؛ `kind: "tool_action"`                         | `sessionKey`، `sessionId`، `toolCallId`، `toolName`، `errorCode`                                                                |
| `inbound_message`  | `direction: "inbound"`، `channel`، `conversationKind`، `outcome`  | `agentId`، `runId`، `durationMs`، `resultCount`، ارجاع‌های هویت، `reasonCode`، `errorCode`                                 |
| `outbound_message` | `direction: "outbound"`، `channel`، `conversationKind`، `outcome` | `agentId`، `runId`، `durationMs`، `resultCount`، ارجاع‌های هویت، `reasonCode`، `deliveryKind`، `failureStage`، `errorCode` |

شمارش‌های بسته پیام عبارت‌اند از:

- `conversationKind`: `direct`، `group`، `channel` یا `unknown`.
- `outcome` ورودی: `completed`، `skipped` یا `failed`؛
  `reasonCode` اختیاری: `duplicate`، `reply_operation_active`،
  `reply_operation_aborted`، `fast_abort`، `plugin_bound_handled`،
  `plugin_bound_unavailable`، `plugin_bound_declined`، `plugin_bound_error`،
  `before_dispatch_handled`، `acp_dispatch_completed`، `acp_dispatch_failed`،
  `acp_dispatch_empty` یا `acp_dispatch_aborted`.
- `outcome` خروجی: `sent`، `suppressed`، `failed` یا `unknown`؛
  `reasonCode` اختیاری: `cancelled_by_message_sending_hook`،
  `cancelled_by_reply_payload_sending_hook`،
  `empty_after_message_sending_hook`، `empty_after_reply_payload_sending_hook`
  یا `no_visible_payload`. آداپتوری که هیچ هویت پلتفرمی برنمی‌گرداند
  `unknown` است، زیرا اثر جانبی خارجی را نمی‌توان رد کرد.
- `deliveryKind`: `text`، `media` یا `other`؛ `failureStage`:
  `platform_send`، `queue` یا `unknown`.

فیلدهای نهایی با یکدیگر هم‌بسته‌اند و به‌طور مستقل اختیاری نیستند:

| گونه          | نگاشت نهایی                                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| اجرای عامل        | `started` هیچ `errorCode` ندارد؛ هر وضعیت پایان‌یافته ناموفق به کد `run_*` متناظر خود نیاز دارد.                                                                 |
| اقدام ابزار      | `started` و وضعیت موفق هیچ `errorCode` ندارند؛ هر وضعیت پایان‌یافته دیگر به کد `tool_*` متناظر خود نیاز دارد.                                                       |
| پیام ورودی  | موفق = `completed`؛ مسدود = `skipped`؛ ناموفق = `failed` به‌همراه `message_processing_failed`. در صورت وجود `reasonCode`، باید به همان خانواده نهایی تعلق داشته باشد. |
| پیام خروجی | موفق = `sent`؛ مسدود = `suppressed` به‌همراه `reasonCode`؛ ناموفق = `failed` به‌همراه `errorCode` و `failureStage`؛ ناشناخته = `unknown` به‌همراه `failureStage`.      |

هر رویداد فعالیت شامل شناسه پایدار رویداد، توالی یکنوای دفترکل،
توالی رویداد مبدأ، مُهر زمانی، کنشگر، اقدام، وضعیت، مقدار صحیح
`schemaVersion: 1` و `redaction: "metadata_only"` است. رکوردهای اجرا و ابزار
به منشأ عامل و اجرا نیاز دارند و ممکن است منشأ نشست را نیز شامل شوند. رکوردهای
پیام ممکن است شناسه‌های عامل و اجرا را شامل شوند، اما عمداً هرگز شامل
`sessionKey` یا `sessionId` نیستند؛ بنابراین فیلتر پرس‌وجوی `sessionKey`
فقط بر ردیف‌های اجرا و ابزار اعمال می‌شود. رویدادهای ابزار ممکن است شناسه فراخوانی ابزار و نام ابزار را شامل شوند.

رکوردهای پیام از `message.inbound.processed` یا
`message.outbound.finished` استفاده می‌کنند و جهت، کانال، نوع مکالمه،
نتیجه نرمال‌شده، و نوع تحویل، مرحله شکست، مدت‌زمان،
تعداد نتایج، کد دلیل و نام‌های مستعار کلیددارِ محلیِ نصب برای
حساب/مکالمه/پیام/مقصد را به‌صورت اختیاری اضافه می‌کنند. این نام‌های مستعار به
هم‌بستگی کمک می‌کنند، اما ناشناس‌سازی نیستند: پایگاه داده وضعیت کلید آن‌ها را در خود دارد،
درحالی‌که خروجی‌های RPC و CLI آن را ندارند. دفتر کل، پرامپت‌ها، بدنه پیام‌ها،
آرگومان‌های ابزار، نتایج ابزار، خروجی فرمان یا متن خام خطا را ذخیره نمی‌کند.
مقادیر `sessionKey` مربوط به اجرا/ابزار، به‌عنوان فراداده خام هم‌بستگی باقی می‌مانند و می‌توانند
شناسه‌های حساب پلتفرم یا همتا را در خود جای دهند؛ رکوردهای پیام کلیدهای نشست را حذف می‌کنند.

برای ردیف‌های ورودی، `durationMs` ارسال اصلی را تا وضعیت نهایی آن اندازه‌گیری می‌کند و
`resultCount` تعداد محموله‌های نهایی‌شده ابزار، بلوک و پاسخِ صف‌شده را می‌شمارد. برای
ردیف‌های خروجی، `durationMs` بازه مالکیت تحویل تا تأیید،
نامه مرده یا تطبیق (شامل زمان انتظار در صف) را پوشش می‌دهد و `resultCount`
تعداد ارسال‌های فیزیکی شناسایی‌شده پلتفرم را می‌شمارد. `deliveryKind`، در صورت وجود،
محموله مؤثر پس از هوک‌ها و رندر را توصیف می‌کند؛ ردیف‌های سرکوب‌شده یا
دارای ابهام ناشی از خرابی، آن را حذف می‌کنند.

پوشش کنونی پیام شامل پیام‌های ورودی پذیرفته‌شده‌ای است که به
ارسال اصلی می‌رسند، از جمله نتایج تکراری/نهایی هسته. پوشش خروجی برای
هر محموله منطقی پاسخ اصلی که به تحویل پایدار مشترک می‌رسد، یک ردیف نهایی می‌نویسد؛
قطعه‌بندی و پخش‌شدن در آداپتور در `resultCount` تجمیع می‌شوند. ارسال‌های صف‌شده
قابل‌تلاش‌مجدد یا مبهم، تنها پس از تأیید، نامه مرده یا تطبیق
ثبت می‌شوند. مسیرهای محلی Plugin و ارسال مستقیم که این
مرزهای مشترک را دور می‌زنند، هنوز پوشش داده نشده‌اند. صف محدود کارگر به‌صورت بهترین‌تلاش
عمل می‌کند و ممکن است هنگام شکست یا اشباع، رکوردها را حذف کند؛ بنابراین این سطح یک
بایگانی انطباقِ بدون اتلاف نیست.

ثبت به‌طور پیش‌فرض فعال است و از طریق
[`audit.enabled`](/fa/gateway/configuration-reference#audit) کنترل می‌شود. ثبت پیام
به‌طور جداگانه با `audit.messages` کنترل می‌شود و مقدار پیش‌فرض آن `"off"` است. وقتی
ثبت غیرفعال باشد، `audit.activity.list` همچنان رکوردهای پیش‌تر نوشته‌شده را
تا زمان انقضایشان ارائه می‌کند.

شِماهای عرضه‌شده درخواست، نتیجه و `AuditEvent` مربوط به `audit.list`
بدون تغییر باقی می‌مانند و فقط رکوردهای اجرای عامل و کنش ابزار را برمی‌گردانند. کلاینت‌های
اپراتوری جدید باید وقتی Gateway آن را اعلام می‌کند، `audit.activity.list` را فراخوانی کنند. Gatewayهای
قدیمی‌تر ممکن است `unknown method: audit.activity.list` یا، از آنجا که
مجوزدهی در نسخه‌های عرضه‌شده پیش از جست‌وجوی متد انجام می‌شد، `missing scope:
operator.admin` را برای یک درخواست با دامنه خواندن گزارش کنند. مورد دوم را تنها زمانی
به‌معنای نبود متد تلقی کنید که متد اعلام نشده باشد. سپس کلاینت می‌تواند تنها زمانی `audit.list`
را دوباره امتحان کند که فیلترهایش به پشتیبانی از نوع پیام، جهت یا کانال
نیاز نداشته باشند.

برای پرس‌وجوهای متنی و خروجی‌های محدود JSON از [`openclaw audit`](/fa/cli/audit) استفاده کنید.

## RPCهای دفتر کل وظایف

کلاینت‌های اپراتوری، رکوردهای وظایف پس‌زمینه Gateway را از طریق
RPCهای دفتر کل وظایف (`packages/gateway-protocol/src/schema/tasks.ts`) بررسی و لغو می‌کنند. این RPCها
خلاصه‌های پاک‌سازی‌شده وظایف را برمی‌گردانند، نه وضعیت خام زمان اجرا را.

- `tasks.list` به `operator.read` نیاز دارد.
  - پارامترها: `status` اختیاری (`"queued"`، `"running"`، `"completed"`،
    `"failed"`، `"cancelled"` یا `"timed_out"`) یا آرایه‌ای از این وضعیت‌ها،
    `agentId` اختیاری، `sessionKey` اختیاری، `limit` اختیاری از `1` تا
    `500`، و رشته اختیاری `cursor`.
  - نتیجه: `{ "tasks": TaskSummary[], "nextCursor"?: string }`.
- `tasks.get` به `operator.read` نیاز دارد.
  - پارامترها: `{ "taskId": string }`.
  - نتیجه: `{ "task": TaskSummary }`.
  - شناسه‌های وظیفه ناموجود، قالب خطای یافت‌نشدن Gateway را برمی‌گردانند.
- `tasks.cancel` به `operator.write` نیاز دارد.
  - پارامترها: `{ "taskId": string, "reason"?: string }`.
  - نتیجه: `{ "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }`.
  - `found` گزارش می‌دهد که آیا دفتر کل وظیفه منطبقی داشته است. `cancelled`
    گزارش می‌دهد که آیا زمان اجرا لغو را پذیرفته یا ثبت کرده است.

`TaskSummary` شامل `id`، `status` و فراداده اختیاری است: `kind`،
`runtime`، `title`، `agentId`، `sessionKey`، `childSessionKey`، `ownerKey`،
`runId`، `taskId`، `flowId`، `parentTaskId`، `sourceId`، مُهرهای زمانی، پیشرفت،
خلاصه نهایی و متن پاک‌سازی‌شده خطا. `agentId` عاملی را مشخص می‌کند که
وظیفه را اجرا می‌کند؛ `sessionKey` و `ownerKey` زمینه درخواست‌کننده و کنترل را
حفظ می‌کنند.

## متدهای کمکی اپراتور

- `commands.list` (`operator.read`) فهرست فرمان‌های زمان اجرا را برای
  یک عامل دریافت می‌کند.
  - `agentId` اختیاری است؛ برای خواندن فضای کاری عامل پیش‌فرض آن را حذف کنید.
  - `scope` کنترل می‌کند `name` اصلی کدام سطح را هدف بگیرد: `text`
    توکن فرمان متنی اصلی را بدون `/` ابتدایی برمی‌گرداند؛ `native` و
    مسیر پیش‌فرض `both`، در صورت وجود، نام‌های بومیِ آگاه از ارائه‌دهنده را برمی‌گردانند.
  - `textAliases` نام‌های مستعار دقیق اسلش مانند `/model` و `/m` را در خود دارد.
  - `nativeName` در صورت وجود، نام فرمان بومیِ آگاه از ارائه‌دهنده را در خود دارد.
  - `provider` اختیاری است و فقط بر نام‌گذاری بومی و دسترس‌پذیری فرمان‌های بومی Plugin
    اثر می‌گذارد.
  - `includeArgs=false` فراداده سریال‌شده آرگومان را از پاسخ حذف می‌کند.
- `tools.catalog` (`operator.read`) کاتالوگ ابزار زمان اجرا را برای یک
  عامل دریافت می‌کند. پاسخ شامل ابزارهای گروه‌بندی‌شده و فراداده منشأ است:
  - `source`: `core` یا `plugin`
  - `pluginId`: مالک Plugin هنگامی که `source="plugin"`
  - `optional`: اینکه آیا ابزار Plugin اختیاری است
- `tools.effective` (`operator.read`) فهرست ابزارِ مؤثر در زمان اجرا را برای یک نشست
  دریافت می‌کند.
  - `sessionKey` الزامی است.
  - Gateway به‌جای پذیرفتن زمینه احراز هویت یا تحویلِ ارائه‌شده توسط فراخواننده، زمینه مورداعتماد زمان اجرا را از نشست در سمت سرور
    استخراج می‌کند.
  - پاسخ، تصویری در دامنه نشست و استخراج‌شده توسط سرور از فهرست فعال است که
    ابزارهای هسته، Plugin، کانال و سرور MCP ازپیش‌کشف‌شده را شامل می‌شود.
  - `tools.effective` برای MCP فقط‌خواندنی است: ممکن است کاتالوگ MCP یک نشست گرم را
    از طریق سیاست نهایی ابزار تصویر کند، اما زمان‌های اجرای MCP را ایجاد نمی‌کند،
    انتقال‌ها را متصل نمی‌کند یا `tools/list` صادر نمی‌کند. اگر کاتالوگ گرم منطبقی
    وجود نداشته باشد، پاسخ ممکن است اعلانی مانند `mcp-not-yet-connected`،
    `mcp-not-yet-listed` یا `mcp-stale-catalog` داشته باشد.
  - ورودی‌های مؤثر ابزار از `source="core"`، `source="plugin"`،
    `source="channel"` یا `source="mcp"` استفاده می‌کنند.
- `tools.invoke` (`operator.write`) یک ابزار موجود را از طریق همان
  مسیر سیاست Gateway که `/tools/invoke` استفاده می‌کند، فراخوانی می‌کند.
  - `name` الزامی است. `args`، `sessionKey`، `agentId`، `confirm` و
    `idempotencyKey` اختیاری هستند.
  - اگر هر دو `sessionKey` و `agentId` وجود داشته باشند، عامل نشست حل‌شده
    باید با `agentId` مطابقت داشته باشد.
  - پوشش‌دهنده‌های هسته‌ای مختص مالک مانند `cron`، `gateway` و `nodes` به
    هویت مالک/مدیر (`operator.admin`) نیاز دارند، با اینکه خود `tools.invoke`
    برابر `operator.write` است.
  - پاسخ یک پوشش رو به SDK با فیلدهای `ok`، `toolName`،
    `output` اختیاری و `error` نوع‌دار است. ردشدن‌های تأیید یا سیاست،
    به‌جای دورزدن پایپ‌لاین سیاست ابزار Gateway، `ok:false` را در محموله برمی‌گردانند.
- `skills.status` (`operator.read`) فهرست قابل‌مشاهده مهارت‌ها را برای یک
  عامل دریافت می‌کند.
  - `agentId` اختیاری است؛ برای خواندن فضای کاری عامل پیش‌فرض آن را حذف کنید.
  - پاسخ شامل واجدشرایط‌بودن، نیازمندی‌های موجودنبوده، بررسی‌های پیکربندی
    و گزینه‌های پاک‌سازی‌شده نصب است، بدون اینکه مقادیر خام محرمانه را افشا کند.
- `skills.search` و `skills.detail` (`operator.read`) فراداده کشف ClawHub را
  برمی‌گردانند.
- `skills.upload.begin`، `skills.upload.chunk` و `skills.upload.commit`
  (`operator.admin`) پیش از نصب، یک بایگانی خصوصی مهارت را آماده می‌کنند. این
  یک مسیر بارگذاری مدیریتی جداگانه برای کلاینت‌های مورداعتماد است، نه جریان معمول نصب
  مهارت ClawHub، و به‌طور پیش‌فرض غیرفعال است، مگر اینکه
  `skills.install.allowUploadedArchives` فعال باشد.
  - `skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? })`
    یک بارگذاری وابسته به آن نامک و مقدار اجبار ایجاد می‌کند.
  - `skills.upload.chunk({ uploadId, offset, dataBase64 })` بایت‌ها را در
    آفست رمزگشایی‌شده دقیق اضافه می‌کند.
  - `skills.upload.commit({ uploadId, sha256? })` اندازه نهایی و
    SHA-256 را تأیید می‌کند. ثبت فقط بارگذاری را نهایی می‌کند؛ مهارت را نصب نمی‌کند.
  - بایگانی‌های بارگذاری‌شده مهارت، بایگانی‌های zip حاوی ریشه `SKILL.md` هستند. نام
    دایرکتوری داخلی بایگانی هرگز مقصد نصب را انتخاب نمی‌کند.
- `skills.install` (`operator.admin`) سه حالت دارد:
  - حالت ClawHub: `{ source: "clawhub", slug, version?, force? }` یک
    پوشه مهارت را در دایرکتوری `skills/` فضای کاری عامل پیش‌فرض نصب می‌کند.
  - حالت بارگذاری: `{ source: "upload", uploadId, slug, force?, sha256?, timeoutMs? }`
    یک بارگذاری ثبت‌شده را در دایرکتوری `skills/<slug>`
    فضای کاری عامل پیش‌فرض نصب می‌کند. نامک و مقدار اجبار باید با
    درخواست اصلی `skills.upload.begin` مطابقت داشته باشند. مگر اینکه
    `skills.install.allowUploadedArchives` فعال باشد، رد می‌شود؛ این تنظیم بر
    نصب‌های ClawHub اثر نمی‌گذارد.
  - حالت نصب‌کننده Gateway: `{ name, installId, timeoutMs? }` یک کنش اعلام‌شده
    `metadata.openclaw.install` را روی میزبان Gateway اجرا می‌کند. کلاینت‌های قدیمی‌تر ممکن است
    همچنان `dangerouslyForceUnsafeInstall` را ارسال کنند؛ این فیلد منسوخ شده،
    فقط برای سازگاری پروتکل پذیرفته می‌شود و نادیده گرفته می‌شود. برای
    تصمیم‌های نصب متعلق به اپراتور از `security.installPolicy` استفاده کنید.
- `skills.update` (`operator.admin`) دو حالت دارد:
  - حالت ClawHub یک نامک ردیابی‌شده یا همه نصب‌های ردیابی‌شده ClawHub را در
    فضای کاری عامل پیش‌فرض به‌روزرسانی می‌کند.
  - حالت پیکربندی مقادیر `skills.entries.<skillKey>` مانند `enabled`،
    `apiKey` و `env` را وصله می‌کند.

### نماهای `models.list`

`models.list` یک پارامتر اختیاری `view` می‌پذیرد
(`src/agents/model-catalog-visibility.ts`):

- حذف‌شده یا `"default"`: اگر `agents.defaults.modelPolicy.allow` پیکربندی شده باشد،
  پاسخ کاتالوگ مجاز است، شامل مدل‌های کشف‌شده پویا
  برای ورودی‌های `provider/*`. در غیر این صورت، پاسخ کاتالوگ کامل Gateway
  است.
- `"configured"`: رفتار با اندازه مناسب انتخاب‌گر. اگر `agents.defaults.modelPolicy.allow`
  پیکربندی شده باشد، همچنان اولویت دارد، از جمله کشف در دامنه ارائه‌دهنده برای
  ورودی‌های `provider/*`. بدون فهرست مجاز، پاسخ از ورودی‌های صریح
  `models.providers.<provider>.models` استفاده می‌کند و فقط وقتی هیچ ردیف مدل پیکربندی‌شده‌ای وجود نداشته باشد،
  به کاتالوگ کامل بازمی‌گردد.
- `"provider-config"`: فهرست `models.providers.*.models` تألیف‌شده در منبع،
  مستقل از فهرست‌های مجاز انتخاب‌گر. ردیف‌ها قابلیت‌های عمومی مدل و
  دسترس‌پذیری آگاه از مسیر را شامل می‌شوند، اما نقاط پایانی ارائه‌دهنده، اطلاعات احراز هویت و
  پیکربندی درخواست زمان اجرا را حذف می‌کنند.
- `"all"`: کاتالوگ کامل Gateway که `agents.defaults.modelPolicy.allow` را دور می‌زند. برای
  رابط‌های کاربری عیب‌یابی/کشف استفاده کنید، نه انتخاب‌گرهای معمول مدل.

## تأییدهای اجرا

- هنگامی که یک درخواست exec به تأیید نیاز دارد، Gateway آن را پخش می‌کند:
  `exec.approval.requested`.
- کلاینت‌های اپراتور با فراخوانی `exec.approval.resolve` آن را تعیین تکلیف می‌کنند (نیازمند
  `operator.approvals`).
- برای `host=node`، `exec.approval.request` باید شامل `systemRunPlan`
  (فرادادهٔ متعارف `argv`/`cwd`/`rawCommand`/نشست) باشد. درخواست‌های فاقد
  `systemRunPlan` رد می‌شوند.
- پس از تأیید، فراخوانی‌های هدایت‌شدهٔ `node.invoke system.run` از همان
  `systemRunPlan` متعارف به‌عنوان زمینهٔ معتبر فرمان/cwd/نشست استفاده می‌کنند.
- اگر فراخواننده بین آماده‌سازی و هدایت نهایی و تأییدشدهٔ `system.run`،
  `command`، `rawCommand`، `cwd`، `agentId` یا
  `sessionKey` را تغییر دهد، Gateway به‌جای اعتماد به محتوای تغییریافته، اجرا را رد می‌کند.

## مسیر جایگزین تحویل عامل

- درخواست‌های `agent` می‌توانند برای درخواست تحویل خروجی شامل `deliver=true` باشند.
- `bestEffortDeliver=false` (مقدار پیش‌فرض) رفتار سخت‌گیرانه را حفظ می‌کند: مقصدهای تحویل حل‌نشده یا
  صرفاً داخلی، `INVALID_REQUEST` را برمی‌گردانند.
- `bestEffortDeliver=true` هنگامی که هیچ مسیر قابل‌تحویل خارجی قابل تعیین نباشد، امکان بازگشت به اجرای صرفاً در نشست را فراهم می‌کند (برای مثال نشست‌های داخلی/webchat
  یا پیکربندی‌های چندکانالهٔ مبهم).
- هنگامی که تحویل درخواست شده باشد، نتایج نهایی `agent` ممکن است شامل `result.deliveryStatus` باشند و از همان وضعیت‌های `sent`، `suppressed`، `partial_failed` و
  `failed` مستندشده برای
  [`openclaw agent --json --deliver`](/fa/cli/agent#json-delivery-status) استفاده کنند.

## نسخه‌بندی

- `PROTOCOL_VERSION`، `MIN_CLIENT_PROTOCOL_VERSION`،
  `MIN_NODE_PROTOCOL_VERSION` و `MIN_PROBE_PROTOCOL_VERSION` در
  `packages/gateway-protocol/src/version.ts` قرار دارند.
- کلاینت‌ها `minProtocol` + `maxProtocol` را ارسال می‌کنند. کلاینت‌های اپراتور و رابط کاربری باید
  پروتکل جاری را در آن بازه بگنجانند؛ کلاینت‌ها و سرورهای فعلی از
  پروتکل v4 استفاده می‌کنند.
- کلاینت‌های احراز هویت‌شده‌ای که هم `role: "node"` و هم `client.mode: "node"` را دارند،
  می‌توانند از پروتکل Node نسخهٔ N-1 (در حال حاضر v3) استفاده کنند. کاوشگرهای سبکِ راه‌اندازی مجدد از
  همان بازهٔ N-1 استفاده می‌کنند. احراز هویت دستگاه، جفت‌سازی، دامنه‌ها، سیاست فرمان و تأییدهای exec
  تحت تأثیر این بازهٔ سازگاری قرار نمی‌گیرند. قابلیت‌ها و فرمان‌های Node متعلق به Plugin
  تا زمانی که Node به پروتکل جاری ارتقا نیابد ارائه نمی‌شوند، زیرا سطوح میزبانی‌شدهٔ آن‌ها
  بخشی از قرارداد N-1 نیستند.
- شِماها و مدل‌ها از تعریف‌های TypeBox تولید می‌شوند:
  - `pnpm protocol:gen`
  - `pnpm protocol:gen:swift`
  - `pnpm protocol:check`

### ثابت‌های کلاینت

پیاده‌سازی کلاینت مرجع در `packages/gateway-client/src/` قرار دارد
(OpenClaw آن را از طریق نمای نازک `src/gateway/client.ts` پوشش می‌دهد). این
مقادیر پیش‌فرض در سراسر پروتکل v4 پایدارند و خط مبنای مورد انتظار برای
کلاینت‌های شخص ثالث هستند.

| ثابت                                       | پیش‌فرض                                               | منبع                                                                                                                       |
| ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `PROTOCOL_VERSION`                        | `4`                                                   | `packages/gateway-protocol/src/version.ts`                                                                                |
| `MIN_CLIENT_PROTOCOL_VERSION`             | `4`                                                   | `packages/gateway-protocol/src/version.ts`                                                                                |
| `MIN_NODE_PROTOCOL_VERSION`               | `3`                                                   | `packages/gateway-protocol/src/version.ts`                                                                                |
| `MIN_PROBE_PROTOCOL_VERSION`              | `3`                                                   | `packages/gateway-protocol/src/version.ts`                                                                                |
| مهلت زمانی درخواست (برای هر RPC)           | `30_000` ms                                           | `packages/gateway-client/src/client.ts` (`requestTimeoutMs`)                                                              |
| مهلت زمانی پیش‌احراز هویت / چالش اتصال     | `15_000` ms                                           | `packages/gateway-client/src/timeouts.ts` (متغیر محیطی `OPENCLAW_HANDSHAKE_TIMEOUT_MS` می‌تواند بودجهٔ سرور/کلاینت جفت‌شده را افزایش دهد) |
| تأخیر اولیهٔ اتصال مجدد                    | `1_000` ms                                            | `packages/gateway-client/src/client.ts` (`GATEWAY_RECONNECT_POLICY`)                                                      |
| حداکثر تأخیر اتصال مجدد                    | `30_000` ms                                           | `packages/gateway-client/src/client.ts` (`GATEWAY_RECONNECT_POLICY`)                                                      |
| محدودیت تلاش مجدد سریع پس از بسته‌شدن توکن دستگاه | `250` ms                                              | `packages/gateway-client/src/client.ts`                                                                                   |
| مهلت توقف اجباری پیش از `terminate()` | `250` ms                                              | `FORCE_STOP_TERMINATE_GRACE_MS`                                                                                           |
| مهلت زمانی پیش‌فرض `stopAndWait()`      | `1_000` ms                                            | `STOP_AND_WAIT_TIMEOUT_MS`                                                                                                |
| فاصلهٔ زمانی پیش‌فرض تیک (پیش از `hello-ok`) | `30_000` ms                                           | `packages/gateway-client/src/client.ts`                                                                                   |
| بسته‌شدن بر اثر پایان مهلت تیک             | کد `4000` هنگامی که سکوت از `tickIntervalMs * 2` فراتر رود | `packages/gateway-client/src/client.ts`                                                                                   |
| `MAX_PAYLOAD_BYTES`                       | `25 * 1024 * 1024` (25 MB)                            | `src/gateway/server-constants.ts`                                                                                         |

سرور مقادیر مؤثر `policy.tickIntervalMs`،
`policy.maxPayload` و `policy.maxBufferedBytes` را در `hello-ok` اعلام می‌کند؛ کلاینت‌ها
باید به‌جای مقادیر پیش‌فرض پیش از دست‌دهی، از این مقادیر پیروی کنند.

کلاینت مرجع به درخواست‌های محدود اجازه می‌دهد هنگامی که
هر درخواست معلق مهلتی دارد، مهلت پیکربندی‌شدهٔ خود را مدیریت کنند. یک درخواست `expectFinal` بدون
`timeoutMs` محدود، هر درخواستی با `timeoutMs: null`، یا ترکیبی از درخواست‌های محدود و
نامحدود، پایشگر تیک را فعال نگه می‌دارد. اگر رویدادهای ورودی و
پاسخ‌ها پس از آستانهٔ پایان مهلت تیک همچنان بی‌صدا بمانند، کلاینت
سوکت را با کد `4000` می‌بندد، همهٔ درخواست‌های معلق را رد می‌کند و دوباره متصل می‌شود. پس از
اتصال مجدد، درخواست‌های ردشده را دوباره اجرا نمی‌کند.

## احراز هویت

- احراز هویت Gateway با راز مشترک، بسته به
  `gateway.auth.mode` پیکربندی‌شده (`"none" | "token" | "password" | "trusted-proxy"`)، از `connect.params.auth.token` یا
  `connect.params.auth.password` استفاده می‌کند.
- حالت‌های حامل هویت مانند Tailscale Serve (`gateway.auth.allowTailscale: true`)
  یا `gateway.auth.mode: "trusted-proxy"` غیرِ loopback، بررسی احراز هویت اتصال را به‌جای
  `connect.params.auth.*` از طریق سرآیندهای درخواست برآورده می‌کنند.
- `gateway.auth.mode: "none"` با ورودی خصوصی، احراز هویت اتصال با راز مشترک را
  کاملاً نادیده می‌گیرد؛ این حالت را روی ورودی عمومی/غیرقابل‌اعتماد در معرض دسترسی قرار ندهید.
- پس از جفت‌سازی، Gateway یک توکن دستگاه با دامنه محدود به نقش اتصال
  و دامنه‌ها صادر می‌کند که در `hello-ok.auth.deviceToken` بازگردانده می‌شود. کلاینت‌ها باید
  پس از هر اتصال موفق آن را ذخیره کنند.
- اتصال مجدد با آن توکن دستگاه ذخیره‌شده باید مجموعه دامنه‌های تأییدشده
  ذخیره‌شده برای همان توکن را نیز دوباره استفاده کند. این کار دسترسی خواندن/کاوش/وضعیت
  را که قبلاً اعطا شده حفظ می‌کند و مانع از آن می‌شود که اتصال‌های مجدد بی‌سروصدا به
  دامنه ضمنی محدودتر و فقط مخصوص مدیر فروکاسته شوند.
- ساخت احراز هویت اتصال در سمت کلاینت (`selectConnectAuth` در
  `packages/gateway-client/src/client.ts`):
  - `auth.password` مستقل است و در صورت تنظیم، همیشه ارسال می‌شود.
  - `auth.token` به‌ترتیب اولویت مقداردهی می‌شود: ابتدا توکن مشترک صریح،
    سپس یک `deviceToken` صریح، و بعد یک توکن ذخیره‌شده برای هر دستگاه (با کلید
    `deviceId` + `role`).
  - `auth.bootstrapToken` فقط زمانی ارسال می‌شود که هیچ‌یک از موارد بالا
    `auth.token` را تعیین نکرده باشند. توکن مشترک یا هر توکن دستگاه تعیین‌شده‌ای آن را سرکوب می‌کند.
  - ارتقای خودکار توکن دستگاه ذخیره‌شده در تلاش مجدد یک‌باره
    `AUTH_TOKEN_MISMATCH` فقط به نقاط پایانی قابل‌اعتماد محدود است: loopback،
    یا `wss://` با `tlsFingerprint` سنجاق‌شده. `wss://` عمومی بدون سنجاق‌کردن
    واجد شرایط نیست.
- راه‌اندازی اولیه با کد راه‌اندازی داخلی، `hello-ok.auth.deviceToken` مربوط به Node اصلی
  را به‌همراه یک توکن اپراتور محدود در
  `hello-ok.auth.deviceTokens` برای تحویل امن به موبایل بازمی‌گرداند. توکن اپراتور
  شامل `operator.talk.secrets` برای خواندن پیکربندی بومی Talk است، اما
  دامنه‌های تغییر جفت‌سازی و `operator.admin` را شامل نمی‌شود.
- هنگامی‌که راه‌اندازی اولیه با کد راه‌اندازیِ غیربن‌خط در انتظار تأیید است،
  جزئیات `PAIRING_REQUIRED` شامل `recommendedNextStep: "wait_then_retry"`،
  `retryable: true` و `pauseReconnect: false` است. تا زمان تأیید درخواست یا
  نامعتبرشدن توکن، اتصال مجدد را با همان توکن راه‌اندازی اولیه ادامه دهید.
- `hello-ok.auth.deviceTokens` را فقط زمانی ذخیره کنید که اتصال از احراز هویت راه‌اندازی اولیه
  روی انتقالی قابل‌اعتماد مانند `wss://` یا جفت‌سازی loopback/محلی استفاده کرده باشد.
- اگر کلاینت یک `deviceToken` صریح یا `scopes` صریح ارائه کند،
  مجموعه دامنه درخواستی فراخواننده همچنان مرجع نهایی است؛ دامنه‌های ذخیره‌شده فقط زمانی
  دوباره استفاده می‌شوند که کلاینت از توکن ذخیره‌شده همان دستگاه دوباره استفاده کند.
- توکن‌های دستگاه را می‌توان از طریق `device.token.rotate` و
  `device.token.revoke` چرخاند/لغو کرد (نیازمند `operator.pairing`). چرخاندن یا لغو
  توکن Node یا هر نقش غیر‌اپراتور دیگر نیز به `operator.admin` نیاز دارد.
- `device.token.rotate` فراداده چرخش را بازمی‌گرداند. توکن حامل جایگزین را
  فقط برای فراخوانی‌های همان دستگاه که از قبل با توکن همان دستگاه احراز هویت شده‌اند
  بازمی‌تاباند تا کلاینت‌های فقط‌توکنی بتوانند پیش از اتصال مجدد، توکن جایگزین خود را
  ذخیره کنند. چرخش‌های مشترک/مدیریتی توکن حامل را بازنمی‌تابانند.
- صدور، چرخش و لغو توکن به مجموعه نقش‌های تأییدشده ثبت‌شده در ورودی
  جفت‌سازی آن دستگاه محدود می‌ماند؛ تغییر توکن نمی‌تواند دامنه را گسترش دهد یا
  نقش دستگاهی را هدف قرار دهد که تأیید جفت‌سازی هرگز اعطا نکرده است.
- برای نشست‌های توکن دستگاه جفت‌شده، مدیریت دستگاه به خود دستگاه محدود است، مگر آنکه
  فراخواننده `operator.admin` را نیز داشته باشد: فراخوانندگان غیرمدیر فقط می‌توانند
  توکن اپراتورِ ورودی دستگاه خود را مدیریت کنند. مدیریت توکن Node و دیگر توکن‌های
  غیر‌اپراتور، حتی برای دستگاه خود فراخواننده، فقط در اختیار مدیر است.
- `device.token.rotate` و `device.token.revoke` همچنین مجموعه دامنه‌های
  توکن اپراتور هدف را در برابر دامنه‌های نشست فعلی فراخواننده بررسی می‌کنند.
  فراخوانندگان غیرمدیر نمی‌توانند توکن اپراتوری با دامنه گسترده‌تر از دامنه‌ای که
  خود در اختیار دارند بچرخانند یا لغو کنند.
- شکست‌های احراز هویت شامل `error.details.code` به‌همراه راهنمای بازیابی هستند:
  - `error.details.canRetryWithDeviceToken` (بولی)
  - `error.details.recommendedNextStep`: یکی از `retry_with_device_token`،
    `update_auth_configuration`، `update_auth_credentials`،
    `wait_then_retry`، `review_auth_configuration`
    (`packages/gateway-protocol/src/connect-error-details.ts`).
- رفتار کلاینت برای `AUTH_TOKEN_MISMATCH`:
  - کلاینت‌های قابل‌اعتماد می‌توانند یک تلاش مجدد محدود با توکن ذخیره‌شده
    همان دستگاه انجام دهند.
  - اگر آن تلاش مجدد ناموفق بود، حلقه‌های اتصال مجدد خودکار را متوقف کنید و
    راهنمای اقدام اپراتور را نمایش دهید.
- `AUTH_SCOPE_MISMATCH` یعنی توکن دستگاه شناسایی شده، اما
  نقش/دامنه‌های درخواستی را پوشش نمی‌دهد. این مورد را به‌عنوان توکن نامعتبر نمایش ندهید؛
  از اپراتور بخواهید دوباره جفت‌سازی کند یا قرارداد دامنه محدودتر/گسترده‌تر را تأیید کند.

## هویت دستگاه و جفت‌سازی

- Nodeها باید یک هویت پایدار دستگاه (`device.id`) مشتق‌شده از
  اثر انگشت جفت‌کلید را شامل شوند.
- Gatewayها برای هر دستگاه و نقش، توکن صادر می‌کنند.
- برای شناسه‌های دستگاه جدید، تأیید جفت‌سازی الزامی است، مگر آنکه
  تأیید خودکار محلی فعال باشد.
- تأیید خودکار جفت‌سازی بر اتصال‌های مستقیم loopback محلی متمرکز است.
- OpenClaw همچنین برای جریان‌های کمکی قابل‌اعتماد با راز مشترک،
  یک مسیر محدود خوداتصالی محلیِ بک‌اند/کانتینر دارد.
- اتصال‌های tailnet یا LAN روی همان میزبان همچنان برای جفت‌سازی
  راه‌دور محسوب می‌شوند و به تأیید نیاز دارند.
- کلاینت‌های WS معمولاً هنگام `connect` هویت `device`
  را ارائه می‌کنند (اپراتور + Node). تنها استثناهای اپراتور بدون دستگاه، مسیرهای اعتماد صریح هستند:
  - احراز هویت موفق Control UI اپراتور با `gateway.auth.mode: "trusted-proxy"`.
  - RPCهای بک‌اند `gateway-client` با loopback مستقیم در مسیر کمکی
    داخلی رزروشده.
- حذف هویت دستگاه پیامدهایی برای دامنه‌ها دارد. وقتی اتصال اپراتور
  بدون دستگاه از طریق یک مسیر اعتماد صریح مجاز می‌شود، OpenClaw همچنان
  دامنه‌های خوداظهاری را به مجموعه‌ای خالی پاک می‌کند، مگر آنکه آن مسیر
  استثنای نام‌گذاری‌شده‌ای برای حفظ دامنه داشته باشد. سپس روش‌های مقید به دامنه با
  `missing scope` ناموفق می‌شوند.
- مسیر کمکی بک‌اند `gateway-client` با loopback مستقیم و رزروشده،
  دامنه‌ها را فقط برای RPCهای داخلی صفحه کنترل محلی حفظ می‌کند؛ شناسه‌های سفارشی بک‌اند
  از این استثنا برخوردار نیستند.
- همه اتصال‌ها باید nonce ارائه‌شده از سوی سرور یعنی `connect.challenge` را امضا کنند.

### عیب‌یابی مهاجرت احراز هویت دستگاه

برای کلاینت‌های قدیمی که هنوز از رفتار امضای پیش از چالش استفاده می‌کنند، `connect`
کدهای جزئیات `DEVICE_AUTH_*` را زیر `error.details.code` با یک
`error.details.reason` پایدار بازمی‌گرداند.

خطاهای رایج مهاجرت:

| پیام                        | details.code                     | details.reason           | معنا                                               |
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required`     | `DEVICE_AUTH_NONCE_REQUIRED`     | `device-nonce-missing`   | کلاینت `device.nonce` را حذف کرده است (یا خالی ارسال کرده است). |
| `device nonce mismatch`     | `DEVICE_AUTH_NONCE_MISMATCH`     | `device-nonce-mismatch`  | کلاینت با nonce منقضی/نادرست امضا کرده است.       |
| `device signature invalid`  | `DEVICE_AUTH_SIGNATURE_INVALID`  | `device-signature`       | بار داده امضا با بار داده v2 مطابقت ندارد.         |
| `device signature expired`  | `DEVICE_AUTH_SIGNATURE_EXPIRED`  | `device-signature-stale` | مُهر زمانی امضاشده خارج از انحراف مجاز است.        |
| `device identity mismatch`  | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch`     | `device.id` با اثر انگشت کلید عمومی مطابقت ندارد. |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key`      | قالب/متعارف‌سازی کلید عمومی ناموفق بوده است.       |

هدف مهاجرت:

- همیشه منتظر `connect.challenge` بمانید.
- بار داده v2 را که nonce سرور را شامل می‌شود امضا کنید.
- همان nonce را در `connect.params.device.nonce` ارسال کنید.
- بار داده امضای ترجیحی `v3` است
  (`buildDeviceAuthPayloadV3` در `packages/gateway-client/src/device-auth.ts`)،
  که علاوه بر فیلدهای دستگاه/کلاینت/نقش/دامنه‌ها/توکن/nonce، `platform`
  و `deviceFamily` را نیز مقید می‌کند.
- امضاهای قدیمی `v2` برای سازگاری همچنان پذیرفته می‌شوند، اما
  سنجاق‌کردن فراداده دستگاه جفت‌شده همچنان خط‌مشی فرمان را هنگام اتصال مجدد کنترل می‌کند.

## TLS و سنجاق‌کردن

- TLS برای اتصال‌های WS پشتیبانی می‌شود (پیکربندی `gateway.tls`).
- کلاینت‌ها می‌توانند به‌صورت اختیاری اثر انگشت گواهی Gateway را از طریق
  `gateway.remote.tlsFingerprint` یا `--tls-fingerprint` در CLI سنجاق کنند.

## دامنه

این پروتکل API کامل Gateway را ارائه می‌کند: وضعیت، کانال‌ها، مدل‌ها، گفت‌وگو،
عامل، نشست‌ها، Nodeها، تأییدها و موارد دیگر. سطح دقیق توسط
طرح‌واره‌های TypeBox که از `packages/gateway-protocol/src/schema.ts` دوباره صادر شده‌اند تعریف می‌شود.

## مرتبط

- [ساخت کلاینت Gateway](https://docs.openclaw.ai/gateway/clients)
- [تعبیه OpenClaw](https://docs.openclaw.ai/gateway/embedding)
- [پروتکل پل](/fa/gateway/bridge-protocol)
- [راهنمای عملیاتی Gateway](/fa/gateway)
