---
read_when:
    - ساخت یک کلاینت اپراتور، داشبورد یا WebChat خارج از مخزن OpenClaw
    - پیاده‌سازی اتصال مجدد Gateway، تاریخچه، تأییدها یا جفت‌سازی دستگاه
    - به‌روزرسانی یک کلاینت شخص ثالث برای نسخه جدید پروتکل سیمی Gateway
summary: یک کلاینت اپراتور شخص ثالث یا WebChat برای پروتکل WebSocket ‏Gateway بسازید
title: ساخت کلاینت Gateway
x-i18n:
    generated_at: "2026-07-27T15:13:48Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: fa24b196ff1fa28fb3b64d49ac25597f22cf1945aea56029e78e4375f1bdddb7
    source_path: gateway/clients.md
    workflow: 16
---

از بسته‌های منتشرشده Gateway برای ساخت داشبوردهای اپراتور، کلاینت‌های WebChat و دیگر برنامه‌های شخص ثالث استفاده کنید. این راهنما چرخهٔ عمر کلاینت پیرامون قرارداد ارتباطی را پوشش می‌دهد: احراز هویت، قابلیت‌ها، بازیابی پس از اتصال مجدد، تاریخچه، اشتراک‌ها و ارتقای نسخه‌ها.

برای شکل فریم‌ها، دست‌دهی، خطاها و سطح کامل متدها، [مشخصات پروتکل Gateway](https://docs.openclaw.ai/gateway/protocol) را بخوانید.

## نصب بسته‌ها

```bash
npm install @openclaw/gateway-client @openclaw/gateway-protocol
```

<Note>
این بسته‌ها همراه با چرخه‌های انتشار OpenClaw عرضه می‌شوند. در طول عرضهٔ اولیه، ممکن است npm تا زمانی که نخستین نسخهٔ OpenClaw حاوی این بسته‌ها منتشر شود، `E404` را برگرداند؛ آن‌ها را فقط پس از دردسترس‌بودن صفحه‌های رجیستری زیر نصب کنید.
</Note>

- [`@openclaw/gateway-protocol`](https://www.npmjs.com/package/@openclaw/gateway-protocol)
  طرح‌واره‌ها، اعتبارسنج‌های زمان اجرا، نوع‌های TypeScript، رجیستری‌های هویت و
  قابلیت کلاینت، خوانشگرهای خطای ساختاریافته و ثابت‌های نسخهٔ پروتکل را فراهم می‌کند.
  بستهٔ tar آن در npm همچنین قرارداد ماشین‌خوان تولیدشدهٔ
  [`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` را وارد کنید.

نقطهٔ ورودی Node انتقال WebSocket خود را مدیریت می‌کند. میزبان مرورگر یک آداپتور WebSocket به‌همراه ذخیره‌سازی پایدار و callbackهای امضا برای هویت دستگاه و توکن دستگاه فراهم می‌کند.

## انتخاب دامنه‌ها و جفت‌کردن دستگاه

یک کلاینت کامل گفت‌وگوی تعاملی که اعلان‌های تأیید را نیز نمایش می‌دهد، باید `role: "operator"` را با این دامنه‌ها درخواست کند:

| دامنه                | کاربرد                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `operator.read`      | `chat.history`، `sessions.list`، `sessions.subscribe`، وضعیت مدل و رویدادهای فقط‌خواندنی |
| `operator.write`     | `chat.send` و تغییرات معمول نشست                                                |
| `operator.approvals` | فهرست‌کردن، نمایش و رفع تأییدهای exec یا Plugin                               |

فقط اگر کلاینت پرسش‌های تعاملی را مدیریت می‌کند، `operator.questions` را اضافه کنید؛ فقط اگر دستگاه‌ها یا Nodeهای جفت‌شده را مدیریت می‌کند، `operator.pairing` را اضافه کنید؛ و `operator.admin` را تنها برای عملیات مدیریتی مانند `config.patch` اضافه کنید.
[مرجع دامنه‌های اپراتور](https://docs.openclaw.ai/gateway/operator-scopes)
قواعد کامل متدها و زمان تأیید را تعریف می‌کند.

با ویرایش دستی `openclaw.json` برای هر کلاینت توکن حامل نسازید. احراز هویت راه‌اندازی مشترک Gateway را با `openclaw configure --section
gateway` یا گزینه‌های `openclaw onboard --gateway-auth ...` پیکربندی کنید، سپس اجازه دهید جفت‌سازی دستگاه توکن کلاینت را صادر کند:

1. یک هویت دستگاه Ed25519 را در کلاینت به‌طور پایدار ذخیره کنید.
2. منتظر `connect.challenge` بمانید، محتوای دستگاه مقید به چالش را امضا کنید و
   `connect` را با نقش اپراتور و دامنه‌های درخواستی، و توکن مشترک Gateway
   یا گذرواژه برای احراز هویت راه‌اندازی ارسال کنید.
3. اگر Gateway جزئیات ساختاریافتهٔ `PAIRING_REQUIRED` را برگرداند، شناسهٔ درخواست
   را نمایش دهید و مطابق `error.details.recommendedNextStep` مکث یا تلاش مجدد کنید.
4. در میزبان Gateway، درخواست را با `openclaw devices list` بازبینی کنید، سپس
   دقیقاً همان درخواست جاری را با `openclaw devices approve <requestId>` تأیید کنید.
5. دوباره متصل شوید و `hello-ok.auth.deviceToken` را همراه با نقش و
   دامنه‌های توافق‌شده به‌طور پایدار ذخیره کنید. برای اتصال‌های بعدی از آن توکن دستگاه استفاده کنید.

ارتقای دامنه یا نقش، درخواست جفت‌سازی معلق جدیدی ایجاد می‌کند. چرخش توکن نمی‌تواند قرارداد جفت‌سازی تأییدشده را گسترش دهد. برای فرمان‌های تأیید، چرخش و لغو، به [CLI دستگاه‌ها](https://docs.openclaw.ai/cli/devices) مراجعه کنید.

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

`connect.params.caps` رفتار اختیاری قابل‌استفاده برای کلاینت را توصیف می‌کند. این مورد مجوز اعطا نمی‌کند. به‌جای تکرار رشته‌های ثابت، نام‌ها را از `GATEWAY_CLIENT_CAPS` وارد کنید:

```ts
import { GATEWAY_CLIENT_CAPS } from "@openclaw/gateway-protocol/client-info";

const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];
```

رجیستری کنونی شامل `approvals`، `exec-approvals`، `inline-widgets`،
`run-tool-bindings`، `session-scoped-events`، `plugin-approvals`،
`task-suggestions`، `terminal-offset-seq`، `tool-events` و `ui-commands` است.
فقط قابلیت‌هایی را اعلام کنید که کلاینت واقعاً پیاده‌سازی می‌کند.

<Warning>
`tool-events` پخش زندهٔ اجرای ابزار را کنترل می‌کند. Gateway تنها
اتصال‌هایی را که این قابلیت را اعلام می‌کنند، به‌عنوان دریافت‌کنندگان رویدادهای ساختاریافتهٔ
ابزار یک اجرا ثبت می‌کند. بدون آن، اتصال هیچ رویداد زندهٔ ابزاری دریافت نمی‌کند و
دست‌دهی خطایی گزارش نمی‌دهد.
</Warning>

ابزارهای عاملِ مقید به قابلیت، کاربرد جداگانه‌ای از همین اعلان هستند. اگر یک ابزار عامل به قابلیتی از کلاینت نیاز داشته باشد، Gateway آن ابزار را حذف می‌کند، مگر آنکه کلاینت مبدأ همهٔ قابلیت‌های لازم را اعلام کرده باشد.

## بازیابی وضعیت پس از اتصال مجدد

هر اتصال مجدد موفق را به‌عنوان تصویری جدید بر تاریخچهٔ پایدار و وضعیت جاری اجرای درون حافظه در نظر بگیرید:

1. `sessions.subscribe` و اشتراک `sessions.messages.subscribe` نشست انتخاب‌شده را
   دوباره برقرار کنید.
2. برای `sessionKey` انتخاب‌شده، `chat.history` را فراخوانی کنید و ردیف‌های پایدار محلی
   را با تصویر `messages` برگشتی جایگزین کنید.
3. اگر `inFlightRun` موجود است، `runId`، `text` بافرشده و
   `plan` اختیاری آن را بپذیرید. حتی وقتی `text` خالی است، اجرا را بپذیرید.
4. `sessionInfo.hasActiveRun` و `sessionInfo.activeRunIds` را بخوانید. هنگام تصمیم‌گیری دربارهٔ اینکه آیا یک اجرای نگه‌داشته‌شده همچنان مالک رابط کاربری پخش است،
   عضویت دقیق در `activeRunIds` را ترجیح دهید. مقدار درست `hasActiveRun` بدون شناسهٔ فهرست‌شده می‌تواند نمایانگر تصویر فعال زمان اجرای دیگری باشد.
5. رویدادهای بعدی `agent` را با `payload.runId` و `payload.seq`
   تطبیق دهید. بالاترین توالی پذیرفته‌شده را برای هر اجرا به‌طور مستقل نگه دارید، توالی
   دیده‌شده یا پایین‌تر را نادیده بگیرید و فاصلهٔ رو به جلو را دلیلی برای بارگذاری مجدد
   تاریخچهٔ مرجع در نظر بگیرید.

فریم بیرونی رویداد نیز یک `seq` اختیاری دارد که رویدادها را در اتصال WebSocket جاری مرتب می‌کند. این مقدار با اتصال جدید بازنشانی می‌شود. `seq` داخل محتوای رویداد `agent` به‌ازای هر اجرا تخصیص می‌یابد و چرخهٔ عمر، دستیار، طرح، ابزار و دیگر رویدادهای جریان آن اجرا را مرتب می‌کند.

## استفاده از فرادادهٔ تاریخچه و لنگرهای پایدار

ردیف‌های برگشتی از `chat.history` می‌توانند یک پوشش فرادادهٔ `__openclaw` داشته باشند:

- `id` هویت ورودی رونوشت است. از آن برای درخواست‌های تاریخچهٔ لنگرشده استفاده کنید،
  اما نه به‌عنوان کلید یکتای ردیف نمایش.
- `seq` توالی مثبت رکورد رونوشت است. یک رکورد ذخیره‌شده می‌تواند
  به بیش از یک ردیف نمایش تبدیل شود؛ بنابراین ردیف‌های هم‌خانواده با `id` و توالی یکسان را
  کنار هم نگه دارید.
- `kind` ردیف‌های مصنوعی را مشخص می‌کند. یک مرز Compaction از
  `kind: "compaction"` استفاده می‌کند و اگر checkpoint متناظری آن سنجه‌ها را ثبت کرده باشد، ممکن است شامل `tokensBefore` و `tokensAfter` باشد.

با مقادیر `hasMore` و `nextOffset` پاسخ، به عقب صفحه‌بندی کنید. offsetهای عددی تصویر جاری رونوشت را توصیف می‌کنند، بنابراین آن‌ها را در طول بازنشانی یا Compaction به‌عنوان نشانک‌های بلندمدت ذخیره نکنید. در عوض `__openclaw.id` را ذخیره کنید.
برای بازیابی پیرامون یک ردیف شناخته‌شده، `chat.history` را با `messageId` و
`sessionId`ای که آن را برگردانده است فراخوانی کنید. Gateway می‌تواند آن لنگر را از تاریخچهٔ بایگانی بازنشانی پیدا کند؛ پاسخ‌های لنگرشده عمداً فرادادهٔ صفحه‌بندی عددی را حذف می‌کنند.

## اشتراک به‌جای پایش دوره‌ای مصرف

فهرست اولیه را با `sessions.list` بارگذاری کنید، سپس `sessions.subscribe` را برای هر اتصال یک‌بار فراخوانی کنید. رویدادهای `sessions.changed` را بر اساس `sessionKey` ادغام کنید. محتوای تغییر نشست می‌تواند شامل `inputTokens`، `outputTokens`، `totalTokens`،
`totalTokensFresh`، `contextTokens`، `estimatedCostUsd`، تنظیمات مصرف پاسخ
و وضعیت اجرای فعال باشد.

برخی اعلان‌های تغییر فقط سیگنال بی‌اعتبارسازی هستند. اگر رویدادی فیلدهای ردیف موردنیاز نمای شما را ندارد، `sessions.list` را تازه‌سازی کنید. برای به‌روز نگه‌داشتن فهرست زندهٔ نشست‌ها، `usage.cost` یا
`sessions.usage` را به‌طور دوره‌ای پایش نکنید؛ این متدها را برای گزارش‌های تجمیعی یا تفصیلی برحسب تقاضا نگه دارید.

## تکمیل تأییدهای exec

کلاینتی با `operator.approvals` باید به‌محض تکمیل
`hello-ok` شنوندهٔ رویداد خود را نصب کند، سپس `exec.approval.list` را برای تکمیل درخواست‌هایی که
پیش از اتصال بوده‌اند فراخوانی کند. فهرست و رویدادهای زندهٔ
`exec.approval.requested` / `exec.approval.resolved` را بر اساس شناسهٔ تأیید تطبیق دهید تا
انتقالی که با درخواست فهرست رقابت می‌کند نه از دست برود و نه دوباره زنده شود.

## پیگیری نسخه‌های پروتکل

نسخهٔ جاری ارتباطی `4` است. کلاینت‌های عمومی اپراتور و WebChat باید
نسخهٔ جاری دقیق را با `minProtocol: 4` و `maxProtocol: 4` مذاکره کنند.
فقط کلاینت‌های Node احرازهویت‌شده و کاوشگرهای سبک بازهٔ پذیرش N-1 را دارند که در حال حاضر پروتکل `3` تا `4` است.

تغییرات پروتکل ابتدا افزایشی هستند. `protocol.schema.json` شامل فرادادهٔ
قدمت انتشار `since` و فرادادهٔ دامنهٔ الزامی برای متدهای اصلی است، اما افزایش نسخهٔ ارتباطی همچنان یک رویداد ناسازگار صریح برای کلاینت‌های شخص ثالث است. نسخه‌های بسته‌ای را که آزمایش می‌کنید ثابت نگه دارید، هنگام تغییر نسخهٔ ارتباطی کلاینت و Gateway را با هم ارتقا دهید و پیش از هر ارتقا
[تغییرات OpenClaw](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
را بازبینی کنید.

## مرتبط

- [پروتکل Gateway](https://docs.openclaw.ai/gateway/protocol)
- [جاسازی OpenClaw](https://docs.openclaw.ai/gateway/embedding)
- [مرجع RPC ‏Gateway](https://docs.openclaw.ai/reference/rpc)
- [یکپارچه‌سازی‌های Gateway برای برنامه‌های خارجی](https://docs.openclaw.ai/gateway/external-apps)