Nodes and media
استفاده از رایانه
استفاده از رایانه به عامل 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 نیاز دارد:
-
یک باینری
cua-driverنسخه 0.10.x را از انتشارهای بالادستی نصب کنید و آن را درPATHدر دسترس قرار دهید. برای استفاده از محل فایل اجرایی دیگری،plugins.entries.cua-computer.config.driverPathرا تنظیم کنید. -
Plugin را فعال کنید:
bash openclaw plugins enable cua-computer -
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های دوربین و صفحهنمایش را ببینید.
فعالسازی و مسلحسازی
-
اجراکننده پلتفرم را فعال کنید: در macOS، Settings → Allow Computer Control را فعال کنید، سپس در Settings → Permissions مجوزهای Accessibility و Screen Recording را اعطا کنید؛ در Windows/Linux، راهاندازی آزمایشی
cua-computerدر بالا را دنبال کنید. -
بهروزرسانی جفتسازی را در Gateway تأیید کنید (هر فرمان جدید، جفتسازی مجدد را اجباری میکند).
-
ابزار را در اختیار عامل دارای قابلیت بینایی قرار دهید. برای نمایه پیشفرض
coding:json5 { tools: { alsoAllow: ["computer"], // عاملهای سندباکسشده به این دروازه دوم نیز نیاز دارند: sandbox: { tools: { alsoAllow: ["computer"] } }, },} -
برای یک بازه محدود،
computer.actرا مسلح کنید. Pluginphone-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).
- محتوای صفحه را نامطمئن در نظر بگیرید؛ ممکن است حاوی تزریق پرامپت باشد.
ارتباط با دیگر مسیرهای کنترل دسکتاپ
این مسیر مبتنی بر عامل است. برای آگاهی از ارتباط آن با میزبان PeekabooBridge، قابلیت استفاده از رایانه در Codex و MCP مستقیم cua-driver، به پل Peekaboo مراجعه کنید.
