---
read_when:
    - امکان مشاهده و کنترل یک دسکتاپ جفت‌شده برای عامل Gateway
    - فعال‌سازی، مجوزها یا ایمنی برای استفاده از رایانه
    - گسترش فرمان Node‏ `computer.act` یا اجراکننده‌های آن
summary: کنترل دسکتاپ مبتنی بر قابلیت از طریق ابزار رایانه و فرمان نود `computer.act`
title: استفاده از رایانه
x-i18n:
    generated_at: "2026-07-27T15:29:12Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: df8ce87e607ce1b22d91e4ed8702d500bccd4d4f59dab7b0eafac565e730d48a
    source_path: nodes/computer-use.md
    workflow: 16
---

استفاده از رایانه به عامل Gateway امکان می‌دهد یک دسکتاپ جفت‌شده و توانمند را ببیند و کنترل کند. واجد شرایط بودن بر اساس قابلیت است: Node متصل باید هر دو `computer.act` و `screen.snapshot` را اعلام کند و نتیجه آن باید شامل یک `displayFrameId` باشد. ابزار یک اسکرین‌شات را به‌عنوان فریم مرجع خود ثبت می‌کند، سپس نشانگر و صفحه‌کلید را از طریق فرمان خطرناک `computer.act` هدایت می‌کند. مجموعه کنش‌ها از کنش‌های اصلی استفاده از رایانه Anthropic پیروی می‌کند؛ بزرگ‌نمایی اختیاری `computer_20251124` ارائه نمی‌شود. یک مدل دارای قابلیت بینایی، آن را از طریق ابزار عامل داخلی `computer` هدایت می‌کند.

عامل یک فرمان یکپارچه، یعنی `computer.act`، صادر می‌کند؛ عامل نمی‌تواند تشخیص دهد که یک Node چگونه آن را اجرا می‌کند. برنامه همراه macOS فرمان را درون همان فرایند، با سرویس‌های تعبیه‌شده Peekaboo و عملیات پایه محدود CoreGraphics، مدیریت می‌کند (مجوزهای صحیح TCC، بدون فرایند اضافی). Windows و Linux می‌توانند از Plugin اختیاری و آزمایشی `cua-computer` همراه با باینری `cua-driver` که جداگانه نصب شده است استفاده کنند. هر دو اجراکننده از سیاست یکسان جفت‌سازی و مسلح‌سازی استفاده می‌کنند.

## الزامات

- یک Node جفت‌شده و متصل که هر دو `computer.act` و `screen.snapshot` را اعلام کند و `screen.snapshot` در آن `displayFrameId` را برگرداند.
- **اجراکننده macOS:** تنظیم برنامه **اجازه کنترل رایانه** فعال باشد (پیش‌فرض: خاموش).
- **اجراکننده macOS:** مجوز **دسترسی‌پذیری** به OpenClaw اعطا شده باشد (برای تزریق ورودی نشانگر/صفحه‌کلید) و مجوز **ضبط صفحه** نیز برای `screen.snapshot` اعطا شده باشد.
- **اجراکننده Windows/Linux:** Plugin همراه `cua-computer` فعال باشد و یک فایل اجرایی سازگار `cua-driver` نسخه 0.10.x نصب شده باشد.
- فرمان `computer.act` در Gateway مسلح شده باشد (این فرمان خطرناک است و به‌طور پیش‌فرض مسلح نیست).
- یک مدل عامل دارای قابلیت بینایی.
- سیاست ابزاری که `computer` را ارائه کند. پروفایل پیش‌فرض `coding` آن را ارائه نمی‌کند. `computer` را به `tools.alsoAllow` اضافه کنید؛ عامل‌های sandboxشده نیز به آن در `tools.sandbox.tools.alsoAllow` نیاز دارند.

## ابزار عامل `computer`

ابزار داخلی `computer` در هر فراخوانی یک کنش می‌پذیرد. مختصات، پیکسل‌های صحیح نامنفی در جدیدترین اسکرین‌شات هستند؛ Node آن‌ها را به نقاط نمایشگر نگاشت می‌کند. کنش‌های مختصاتی باید `frameId` نتیجه اسکرین‌شات را عیناً بازتاب دهند و یک `screenIndex` صریح باید با آن فریم مطابقت داشته باشد. OpenClaw همچنین یک هویت نمایشگر صادرشده از سوی Node را از اسکرین‌شات به کنش منتقل می‌کند؛ در نتیجه، اتصال مجدد نمایشگر یا تغییر هندسه به‌صورت بسته و ایمن شکست می‌خورد، نه اینکه بی‌سروصدا همان شاخص را دوباره هدف بگیرد. این بررسی‌ها توکن‌های حدس‌زده‌شده و توکن‌های متعلق به فریم یا نمایشگر تحویل‌شده دیگری را رد می‌کنند. توکن تضمین‌کننده تازگی نیست: برنامه‌ها می‌توانند پس از ثبت، پیکسل‌های همان نمایشگر را تغییر دهند؛ بنابراین هر زمان ممکن است صحنه تغییر کرده باشد، یک اسکرین‌شات جدید بگیرید.

- خواندن: `screenshot`.
- نشانگر: `left_click`، `right_click`، `middle_click`، `double_click`، `triple_click`، `mouse_move`، `left_click_drag` (با `startCoordinate`)، `left_mouse_down`، `left_mouse_up`.
- پیمایش: `scroll` با `scrollDirection` (`up|down|left|right`) و `scrollAmount` (تیک‌های چرخ).
- صفحه‌کلید: `type` (متن)، `key` (ترکیبی مانند `cmd+shift+t` یا `Return`)، `hold_key` (ترکیب `text` که به‌مدت `duration` ثانیه نگه داشته می‌شود).
- تنظیم آهنگ اجرا: `wait` (`duration` ثانیه).

کلیدهای تغییردهنده در فیلد `text` کنش‌های کلیک و پیمایش قرار می‌گیرند (`shift`، `ctrl`، `alt`، `cmd`). پس از یک کنش ورودی، ابزار یک اسکرین‌شات تازه برمی‌گرداند تا مدل بتواند نتیجه را مشاهده کند. اگر بیش از یک Node دارای قابلیت رایانه متصل است، `node` را صریحاً ارسال کنید.

اسکرین‌شات‌ها **فقط برای مدل** نگه داشته می‌شوند: آن‌ها هرگز به‌طور خودکار به کانال گفت‌وگو تحویل داده نمی‌شوند. تمام محتوای روی صفحه را ورودی غیرقابل‌اعتماد در نظر بگیرید؛ ابزار به مدل هشدار می‌دهد از دستورالعمل‌های روی صفحه که با درخواست کاربر تعارض دارند پیروی نکند.

## Windows و Linux (آزمایشی، از طریق cua-driver)

Plugin همراه `cua-computer` یک اجراکننده آزمایشی برای میزبان‌های Node مبتنی بر Windows و Linux فراهم می‌کند. این Plugin به‌طور پیش‌فرض غیرفعال است و به قرارداد درایور پیش‌انتشار 0.10.x نیاز دارد:

1. یک باینری `cua-driver` نسخه 0.10.x را از [انتشارهای بالادستی](https://github.com/trycua/cua/releases) نصب کنید و آن را در `PATH` در دسترس قرار دهید. برای استفاده از محل فایل اجرایی دیگری، `plugins.entries.cua-computer.config.driverPath` را تنظیم کنید.
2. Plugin را فعال کنید:

   ```bash
   openclaw plugins enable cua-computer
   ```

3. `openclaw node run` را از نشست تعاملی دسکتاپ اجرا کنید. Plugin هنگام رسیدن نخستین درخواست ثبت یا کنش، دیمن درایور محلی را به‌صورت تنبل راه‌اندازی می‌کند.

این اجراکننده در حال حاضر فقط نمایشگر اصلی را کنترل می‌کند. X11/XWayland مسیر اصلی در Linux است. Wayland بومی همچنان یک قابلیت انتخابی بالادستی است: پیش از راه‌اندازی Node، `CUA_DRIVER_RS_ENABLE_WAYLAND` را خودتان تنظیم کنید؛ OpenClaw هرگز آن را به‌طور خودکار تنظیم نمی‌کند. KDE/KWin در مسیر ورودی بومی Wayland بالادستی پشتیبانی نمی‌شود. `hold_key`، `left_mouse_down` و `left_mouse_up` در دسترس نیستند، زیرا cua-driver نسخه 0.10.x قرارداد نگه‌داشتن ورودی در سطح دسکتاپ و میان‌سکویی ندارد. پیمایش و کشیدن با کلید تغییردهنده نگه‌داشته‌شده در هر دو پلتفرم و کلیک با کلید تغییردهنده نگه‌داشته‌شده در Linux در دسترس نیست. کنش `key` کلیدهای نام‌گذاری‌شده، حروف و ترکیب‌های کلید تغییردهنده را می‌پذیرد (برای مثال `cmd+c` یا `Return`)؛ کلیدهای رقم و نشانه‌گذاری رد می‌شوند، زیرا درایور وضعیت Shift وابسته به چیدمان آن‌ها را حذف می‌کند؛ بنابراین آن متن را در عوض از طریق کنش `type` ارسال کنید. تایپ متن را نمی‌توان در میانه یک فراخوانی درایور `type_text` لغو کرد.

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

OpenClaw تله‌متری و بررسی به‌روزرسانی cua-driver را برای فرایندهای `mcp` و `serve` که مدیریت می‌کند غیرفعال می‌سازد. OpenClaw باینری درایور را بارگیری یا به‌روزرسانی نمی‌کند.

### عیب‌یابی

اجراکننده `cua-computer` کدهای خطای نوع‌دار را در نتیجه ابزار و گزارش‌های Node ارائه می‌کند. موارد رایج:

| کد                                                 | علت                                                                                                                                                           | راه‌حل                                                                                                                                                                                                                                  |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `COMPUTER_DRIVER_UNAVAILABLE`                        | باینری `cua-driver` در `PATH` نیست (یا `driverPath` نادرست است)، دیمن به‌موقع آماده نشده است، یا Node مبتنی بر Windows/Linux نیست.                 | `cua-driver` نسخه 0.10.x را در `PATH` نصب کنید یا `driverPath` را تنظیم کنید. `openclaw node run` را داخل نشست تعاملی دسکتاپ اجرا کنید؛ در Linux مطمئن شوید یک `DISPLAY` از نوع X11 (یا یک `WAYLAND_DISPLAY` با `CUA_DRIVER_RS_ENABLE_WAYLAND`) وجود دارد. |
| `COMPUTER_DRIVER_UNSUPPORTED`                        | درایور متصل‌شده `cua-driver` نسخه 0.10.x نیست، یا نسخه قابلیت/شِمای آن متفاوت است.                                                                      | یک بیلد پشتیبانی‌شده 0.10.x نصب کنید. Plugin حدود 30 ثانیه پس از اصلاح، دوباره آن را بررسی می‌کند؛ بنابراین نیازی به راه‌اندازی مجدد Node نیست.                                                                                                          |
| `COMPUTER_REFUSED_<code>`                            | درایور کنش را با یک کد ساختاریافته مانند `background_unavailable`، `background_occluded` یا `foreground_unavailable` (Wayland در KDE/KWin) رد کرده است.   | پنجره هدف را به جلو بیاورید، به X11 تغییر دهید یا از یک ترکیب‌گر پشتیبانی‌شده استفاده کنید. یادداشت‌های سازگاری بالا را ببینید.                                                                                                                    |
| `COMPUTER_STALE_FRAME`                               | مختصات به اسکرین‌شاتی اشاره داشت که دیگر جاری نیست (Compaction زمینه، تغییر هندسه نمایشگر یا تغییر عرض مرجع).                 | پیش از کنش مختصاتی، یک `screenshot` تازه بگیرید.                                                                                                                                                                              |
| `COMPUTER_UNSUPPORTED_ACTION`                        | کنشی که این اجراکننده نمی‌تواند با وفاداری اجرا کند: `hold_key`، `left_mouse_down`، `left_mouse_up`، کشیدن/پیمایش با کلید تغییردهنده نگه‌داشته‌شده، یا کلیک با کلید تغییردهنده نگه‌داشته‌شده در Linux. | از یک کنش پشتیبانی‌شده استفاده کنید. cua-driver نسخه 0.10.x قرارداد نگه‌داشتن ورودی در سطح دسکتاپ ندارد.                                                                                                                                                  |
| `COMPUTER_UNSUPPORTED_DISPLAY`                       | یک `screenIndex` غیر اصلی، ناهماهنگی هندسه ثبت/صفحه، یا قرار داشتن مکان‌نما بیرون از نمایشگر اصلی.                                                       | فقط نمایشگر اصلی را هدایت کنید.                                                                                                                                                                                                      |
| `COMPUTER_UNSUPPORTED_KEY`                           | مقداری برای `key` که درایور نمی‌تواند با اطمینان بازتولید کند: یک کلید رقم یا نشانه‌گذاری که وضعیت Shift آن به چیدمان وابسته است، یا یک کلید ناشناخته.                        | آن متن را در عوض از طریق کنش `type` ارسال کنید.                                                                                                                                                                                    |
| `COMPUTER_DRIVER_ERROR` / `COMPUTER_INVALID_REQUEST` | درایور بدون کد ساختاریافته شکست خورده است، یا آرگومان‌های کنش نادرست بوده‌اند.                                                                            | وضعیت درایور را بررسی کنید و دوباره اسکرین‌شات بگیرید؛ آرگومان‌های کنش را اصلاح کنید.                                                                                                                                                        |

## فرمان Node با نام `computer.act`

`computer.act` تنها فرمان Node است که ابزار ورودی را از طریق آن مسیریابی می‌کند (`node.invoke` همراه با `command: "computer.act"`). این فرمان:

- **به‌طور پیش‌فرض خطرناک است**: در فهرست فرمان‌های خطرناک داخلی Node قرار دارد و تا زمانی که صریحاً مسلح نشود، از فهرست مجاز زمان اجرا حذف می‌شود. Nodeهای دسکتاپ macOS، Windows و Linux همچنان می‌توانند آن را هنگام جفت‌سازی اعلام کنند تا این سطح فقط یک‌بار تأیید شود.
- **مبتنی بر قابلیت است**: ابزار به یک Node متصل نیاز دارد که هر دو `computer.act` و `screen.snapshot` را اعلام کند. برنامه همراه macOS و Plugin آزمایشی و انتخابی `cua-computer` همان جفت فرمان را اجرا می‌کنند.

خواندن‌ها از `screen.snapshot` دوباره استفاده می‌کنند؛ مسیر ثبت دومی وجود ندارد. برای فرمان ثبت مشترک، [Nodeهای دوربین و صفحه‌نمایش](/fa/nodes/camera) را ببینید.

## فعال‌سازی و مسلح‌سازی

1. اجراکننده پلتفرم را فعال کنید: در macOS، **Settings → Allow Computer Control** را فعال کنید، سپس در **Settings → Permissions** مجوزهای **Accessibility** و **Screen Recording** را اعطا کنید؛ در Windows/Linux، راه‌اندازی آزمایشی `cua-computer` در بالا را دنبال کنید.
2. به‌روزرسانی جفت‌سازی را در Gateway تأیید کنید (هر فرمان جدید، جفت‌سازی مجدد را اجباری می‌کند).
3. ابزار را در اختیار عامل دارای قابلیت بینایی قرار دهید. برای نمایه پیش‌فرض `coding`:

   ```json5
   {
     tools: {
       alsoAllow: ["computer"],
       // عامل‌های سندباکس‌شده به این دروازه دوم نیز نیاز دارند:
       sandbox: { tools: { alsoAllow: ["computer"] } },
     },
   }
   ```

4. برای یک بازه محدود، `computer.act` را مسلح کنید. Plugin `phone-control` یک گروه `computer` ارائه می‌کند:

   ```text
   /phone arm computer 30m
   /phone status
   /phone disarm
   ```

   مسلح‌سازی به `operator.admin` (یا مالک) نیاز دارد و به‌طور خودکار منقضی می‌شود. گروه قدیمی `/phone arm all` عمداً کنترل دسکتاپ را شامل نمی‌شود؛ از گروه صریح `computer` استفاده کنید. مسلح‌سازی فقط تعیین می‌کند Gateway مجاز به فراخوانی چه چیزی است؛ برنامه Node همچنان تنظیمات مختص پلتفرم و مجوزهای سیستم‌عامل خود را اعمال می‌کند که در macOS شامل **Allow Computer Control**، Accessibility و Screen Recording است.

برای مجوز دائمی، `computer.act` را به `gateway.nodes.commands.allow` اضافه کنید **و آن را از** `gateway.nodes.commands.deny` **حذف کنید**؛ فهرست عدم‌اجازه اولویت دارد. مجوز دائمی به‌طور خودکار منقضی نمی‌شود. ورودی‌هایی که پیش از `/phone arm` وجود داشته‌اند، پس از `/phone disarm` باقی می‌مانند؛ تا زمانی که یک مجوز موقت مسلح است، آن را به مجوز دائمی تبدیل نکنید.

مجوزدهی عمداً میان فعال‌سازی و استفاده تفکیک شده است. مسلح‌سازی یا
پیکربندی دائمی `computer.act` به اختیار مدیریتی نیاز دارد.
پس از مسلح‌شدن، یک اپراتور احراز هویت‌شده دارای `operator.write` می‌تواند
تا زمان انقضای مجوز یا خلع سلاح، `computer.act` را از طریق `node.invoke` فراخوانی کند؛
برای هر کنش، بررسی مدیریتی جداگانه‌ای انجام نمی‌شود. تأیید یک Node که
`computer.act` را اعلام می‌کند، فقط این سطح را ثبت می‌کند تا بعداً بتوان آن را مسلح کرد و
به‌خودی‌خود فراخوانی را فعال نمی‌کند.

## ایمنی

- پیش از صدور مجوز، همه لایه‌ها (سیاست ابزار، سیاست فرمان Gateway، تنظیم برنامه Node و مجوزهای پلتفرم) باید موافق باشند. برای اجراکننده فعلی macOS، این موارد شامل **Allow Computer Control**، Accessibility و Screen Recording است. پس از مسلح‌سازی، کنش‌ها تا زمان انقضا یا `/phone disarm` بدون تأیید جداگانه برای هر کنش اجرا می‌شوند.
- اجراکننده macOS متن را هر بار یک گرافیم ارسال می‌کند؛ بنابراین لغو، قطع اتصال، مکث، غیرفعال‌سازی یا جایگزینی نقطه پایانی، آن را پیش از گرافیم بعدی متوقف می‌کند. اجراکننده آزمایشی cua-driver نمی‌تواند فراخوانی `type_text` را در میانه تایپ لغو کند.
- نماگرفت‌ها فقط برای مدل هستند و هرگز به‌طور خودکار به گپ ارسال نمی‌شوند (مسئله [#44759](https://github.com/openclaw/openclaw/issues/44759)).
- محتوای صفحه را نامطمئن در نظر بگیرید؛ ممکن است حاوی تزریق پرامپت باشد.

## ارتباط با دیگر مسیرهای کنترل دسکتاپ

این مسیر مبتنی بر عامل است. برای آگاهی از ارتباط آن با میزبان PeekabooBridge، قابلیت استفاده از رایانه در Codex و MCP مستقیم `cua-driver`، به [پل Peekaboo](/fa/platforms/mac/peekaboo) مراجعه کنید.