تطبيق سطح المكتب يمكن أيضًا التحكم فيه بواسطة الوكيل: دليل تعليمي من 5 خطوات لربط agent-desktop بالنموذج

ملاحظة المؤلف: يشرح هذا المقال تثبيت agent-desktop ومنحه الأذونات، وتشغيل الحلقة المغلقة الدنيا من snapshot إلى click ثم snapshot مرة أخرى، إضافة إلى ربطه بوكيلك عبر MCP، وكيفية ضبط النموذج وعنوان URL الأساسي (Base URL) لـ«الدماغ الموجود داخل الحلقة».

في الماضي، كان إجبار وكيل برمجي أو وكيل من صنعك على النقر في Finder أو ملء إعدادات النظام أو تشغيل تطبيق أصلي، ممكنًا فقط تقريبًا عبر لقطات الشاشة ونماذج الرؤية وإحداثيات البكسل؛ سلسلة طويلة ومعرّضة للأخطاء. أما agent-desktop مفتوح المصدر من Vercel Labs فقد سلك طريقًا مختلفًا: يقرأ شجرة إمكانية الوصول (Accessibility Tree) في نظام التشغيل، ويحوّل واجهة سطح المكتب إلى JSON يحمل مراجع ref، ثم ينفّذ الوكيل النقر والكتابة وفق ref. وهذا ما يقصده بعبارة «computer use بدون لقطات شاشة».

هذا ليس روبوت سطح مكتب آخر يحمل ذكاءً اصطناعيًا مدمجًا. قبل البدء، إليك ثلاث نقاط واضحة:

agent-desktop لا يتضمن نموذجًا: لا يوجد LLM مضمّن في الملف التنفيذي، ولا واجهة رسومية، ولا موجه تفاعلي. كل أمر يطبع مغلّف JSON ثم يخرج.
الحلقة لدى الجهة المستدعية: حلقة المراقبة والتنفيذ والتحقق (observe-act-verify) مسؤولية الوكيل الذي يستدعي الأداة، مثل Claude Code أو OpenCode أو سكربت تكتبه بنفسك.
لا يتعامل مع صفحات الويب: أتمتة الويب متروكة للمشروع الشقيق agent-browser، بينما يتولى agent-desktop تطبيقات سطح المكتب الأصلية فقط.

بما أن الأداة نفسها لا تتضمن نموذجًا، فعلى الوكيل المستدعي توفير «الدماغ». وتحتاج هذه الخطوة إلى مفتاح API ورمز Token. يمكنك توجيه عنوان URL الأساسي (Base URL) للوكيل المستدعي إلى APIYI على apiyi.com، واستخدام مفتاح واحد لاستدعاء نماذج مثل claude-opus-5-5 وclaude-sonnet-5-5.

القيمة الأساسية: بعد قراءة هذا المقال، ستكون قادرًا على تثبيت agent-desktop ومنحه الأذونات، وتشغيل الحلقة المغلقة الدنيا من snapshot → click → snapshot مرة أخرى، ثم ربطه بوكيلك عبر MCP، وضبط عنوان URL الأساسي ومعرّف النموذج على جانب النموذج.

Table of Contents

النقاط الأساسية في agent-desktop

لنبدأ بجدول واحد يوضح لنا موقع agent-desktop بوضوح. المعلومات الواردة في الجدول أدناه مأخوذة من ملف README الرسمي، والأسئلة الشائعة (FAQ)، وموقع التوثيق، بتاريخ رصد 2026-11-13.

النقطة	الشرح	القيمة بالنسبة للمطورين
مصدر البيانات	يقرأ شجرة الوصول (Accessibility Tree) الخاصة بنظام التشغيل: على macOS عبر AX API، وعلى Windows عبر UI Automation، وعلى Linux عبر AT-SPI	لا يعتمد على لقطات الشاشة أو مطابقة البكسلات، ودرجة تنظيمه عالية
صيغة الإخراج	كل أمر يُخرج مغلّف JSON (JSON envelope) ثم ينتهي، وتكون العناصر مرفقة بـ ref	يسهّل على نماذج اللغة الكبيرة تحليل النتائج، ويسهّل على السكربتات إجراء التحققات (assertions)
الوضع الافتراضي	وضع headless، يعمل عبر واجهات الوصول (Accessibility API)، ولا يحرّك المؤشر ولا يستحوذ على التركيز	يسمح بالعمل في الخلفية دون مقاطعة المستخدم
هل يتضمن نموذجًا؟	لا يتضمن، فالحلقة (loop) مسؤولية الجهة المستدعية	اختيار النموذج متروك لك، والتكلفة والفعالية تحت سيطرتك أنت
طريقة الدمج	CLI، وMCP (stdio)، وskills، ومكتبة C عبر FFI	يمكن دمجه في Claude Code وOpenCode والوكلاء التي تبنيها بنفسك

حتى تاريخ 2026-11-13، كان مستودع GitHub ‏vercel-labs/agent-desktop يضم نحو 22,900 نجمة، وهو مرخّص بموجب Apache-2.0، واسم حزمة npm هو agent-desktop نفسه، ولا تزال تصل إليه عمليات commit جديدة في ذلك اليوم. ويبلغ إجمالي الأوامر نحو 61 اسمًا، منها 57 قابلًا للتشغيل، وتنقسم إلى مجموعات: Observe وAct on ref وKeyboard mouse وApps windows وNotifications وClipboard وWait وSessions وSandboxes وSystem وغيرها.

كيف يعمل agent-desktop: شجرة الوصول و ref

المفهومان الأساسيان في agent-desktop هما snapshot و ref. عند تنفيذ snapshot، يمرّ على شجرة الوصول (accessibility tree) الخاصة بالتطبيق الهدف، ويُخرج العناصر — الأزرار وحقول النص وعناصر القوائم وغيرها — على هيئة JSON، مع تخصيص ref لكل عنصر. الشكل الكامل لـ ref يشبه @s8f3k2p9:e8: النصف الأول هو معرّف هذه الـ snapshot، والنصف الثاني هو رقم العنصر.

الـ ref ينتمي فقط إلى الـ snapshot التي أنتجته. وإذا مرّرت @e8 المجرّدة وحدها، فستحصل على INVALID_ARGS. وبعد تغيّر الواجهة قد يصبح الـ ref القديم غير صالح، فتحصل على STALE_REF أو AMBIGUOUS_TARGET، وعندها لا بد من تنفيذ snapshot من جديد. هذا التصميم يُلزم الطرف المستدعي بإعادة المراقبة بعد كل إجراء، أي خطوة “التحقق” في observe-act-verify.

خطوة “اختيار Agent للـ ref” في المخطط أعلاه هي لحظة اتخاذ القرار في النموذج. agent-desktop مسؤوليته الوحيدة هي تسليم الواجهة بشكل مُهيكل؛ أما قراءة JSON وتحديد العنصر الذي سيُنقر عليه، فكلاهما مهمة النموذج المستدعي.

كيف يتوزّع العمل بين agent-desktop و agent-browser

كلا المشروعين ينتمي إلى Vercel Labs، ويقع موقع التوثيق الخاص بهما في المكان نفسه، لكن حدود المسؤوليات واضحة تمامًا:

البند المقارن	agent-desktop	agent-browser
الهدف	تطبيقات سطح المكتب الأصلية (Finder، إعدادات النظام، العملاء الأصليون)	صفحات الويب وصفحات المتصفح
طريقة المراقبة	شجرة إمكانية الوصول (Accessibility Tree) في نظام التشغيل	بنية الصفحة من جهة المتصفح
تطبيقات Chromium / Electron	يمكن تسليمها إلى agent-browser عبر منفذ DevTools	مناسبة للتعامل مع محتوى الويب داخل هذه التطبيقات
هل يتضمن نموذجًا	لا	يُستخدم كذلك كأداة يستدعيها الوكيل (Agent)
الأوامر النموذجية	`snapshot`، `click`، `clipboard-set`	التنقل والتفاعل الموجّهان إلى الصفحة

أحد التوزيعات العملية المفيدة هو: النوافذ الأصلية، وشريط القوائم، وDock، والإشعارات تُسلَّم إلى agent-desktop؛ أما عند الوصول إلى محتوى ويب أو محتوى Web داخل تطبيق Electron، فيتم الانتقال إلى agent-browser عبر منفذ DevTools.

إصدارات agent-desktop ومصادر المعلومات

يتطور agent-desktop بوتيرة سريعة، وقد جاءت عدة إصدارات رئيسية بتغييرات في السلوك، بعضها تغييرات كاسرة. يوضح الجدول التالي المصدر لكل معلومة، حيث تعني «غير معروف» أن المواد الرسمية لم توضح الأمر بعد.

الإصدار / التاريخ	التغييرات الرئيسية	المصدر
1.0.0 (2026-10-27)	دعم Linux يدخل رسميًا إلى الإصدار 1.0	سجل التغييرات الرسمي
1.1.0 (2026-11-02)	ترقية envelope إلى 2.6؛ دعم macOS Dock وmenu-bar-extras؛ تغييرات كاسرة متعلقة بإثبات الهوية	سجل التغييرات الرسمي
1.2.0 (2026-11-05)	إضافة MCP (`agent-desktop mcp`)؛ دعم `type` / `set-value` / `clipboard-set` للخيار `--stdin`	سجل التغييرات الرسمي
1.3.0 (2026-11-11)	إضافة `agent-desktop sandbox` وموفّر sandbox لنظام macOS؛ لقطة menu/menubar لم تعد تتضمن data.window (تغيير كاسر)	سجل التغييرات الرسمي
بيئة العزل (sandbox) على Windows / Linux	هل سيُوفَّر موفّر مقابل لها	غير معروف

البدء السريع مع agent-desktop

في ما يلي، سنمر بالترتيب التالي: التثبيت ← التفويض ← دورة عمل مصغرة مكتملة ← ربط MCP.

الخطوة 1: تثبيت agent-desktop

متطلبات المنصات: macOS 13+؛ Windows 10 1809+ (x64 / ARM64)؛ Linux: Ubuntu 24.04+ (x86_64 / aarch64)، ويمكن استخدام X11 أو Wayland. اختر أي طريقة تثبيت من الطرق التالية:

npm (يتطلب Node 18+، وتتضمن الحزمة ملفات ثنائية أصلية لكل منصة): npm install -g agent-desktop
Homebrew (macOS / Linux، ومتوفر في homebrew-core): brew install agent-desktop
الأرشيف الأصلي: نزّله من GitHub Releases، ويجب وضع helper بجانب الملف القابل للتنفيذ

بعد التثبيت، شغّل agent-desktop status أولاً للتأكد من أن الملف الثنائي وبيئة المنصة الحالية سليمة.

الخطوة 2: منح الصلاحيات إلى agent-desktop

على macOS، تحتاج إلى منح صلاحية “إمكانية الوصول” (Accessibility) للتطبيق الطرفي (Terminal) أو للعملية المضيفة، وإلا فلن تتمكن الأداة من قراءة شجرة إمكانية الوصول. توفر الأداة أمرًا إرشاديًا رسميًا لهذا الغرض:

agent-desktop permissions --guide: يرشدك خطوة بخطوة لإتمام منح صلاحية إمكانية الوصول داخل إعدادات النظام
بعد إتمام المنح، شغّل agent-desktop status مرة أخرى للتأكد

انتبه إلى أن الجهة التي تُمنح الصلاحية هي “العملية التي تشغّل agent-desktop نفسه”. فإذا كنت تستدعي الأداة بشكل غير مباشر عبر Claude Code أو محرر معيّن أو عميل MCP، فقد تحتاج إلى منح الصلاحية للتطبيق المضيف المقابل.

الخطوة 3: إتمام أصغر حلقة مغلقة snapshot ← click ← snapshot

لنأخذ Finder مثالًا؛ ثلاث أوامر فقط تكفي لتشكيل دورة كاملة من الملاحظة ثم الإجراء ثم التحقق:

agent-desktop snapshot --app Finder -i: الحصول على شجرة إمكانية الوصول الخاصة بـ Finder؛ ويُستخدم -i لتركيز العناصر القابلة للتفاعل، بحيث يحتوي ناتج JSON على مراجع ref مثل @s8f3k2p9:e8
agent-desktop click @s8f3k2p9:e8: النقر على العنصر الهدف من آخر snapshot، مع ضرورة كتابة ref كاملًا
agent-desktop snapshot --app Finder -i: الملاحظة مجددًا للتحقق مما إذا كانت الواجهة قد تغيّرت كما هو متوقع

إذا أبلغت الخطوة الثانية عن STALE_REF أو AMBIGUOUS_TARGET، فهذا يعني أن الواجهة تغيّرت بالفعل، وما عليك سوى العودة إلى الخطوة الأولى وإعادة تنفيذ snapshot. وإذا صادفت تطبيقًا يحتاج إلى أحداث مؤشر أو لوحة مفاتيح حقيقية، يمكنك إضافة المُعامل العام --headed للتحول إلى وضع الإدخال الفيزيائي.

أما الواجهات التي تحتوي على عدد كبير من العناصر، فإن snapshot كاملًا دفعة واحدة سيكون طويلًا جدًا ويستهلك رموز النموذج بلا فائدة. لذلك يمكنك الحصول عليه على مستويين:

agent-desktop snapshot --skeleton --app Finder: احصل على الهيكل العظمي أولًا لترى المناطق العامة
agent-desktop snapshot --app Finder --root @<ref من الهيكل العظمي>: ثم انزل إلى شجرة فرعية محددة

هذه الحيلة تقصّر السياق المُرسل إلى النموذج بشكل ملحوظ. وبالنسبة للمستدعي، كلما كان السياق أقصر، انخفضت التكلفة عند الفوترة حسب الـ Token.

الخطوة 4: ربط الوكيل عبر MCP وskills

بدءًا من الإصدار 1.2.0، يتضمن agent-desktop خدمة MCP مدمجة تعمل عبر stdio، وتكشف عن أدوات مثل desktop_snapshot وdesktop_click. تختلف صيغة الإعداد قليلًا بين العملاء، وفيما يلي توضيح:

أمر التشغيل: agent-desktop mcp
نموذج إعداد JSON عام: {"mcpServers": {"agent-desktop": {"command": "agent-desktop", "args": ["mcp"]}}}
توضيح Claude Code: claude mcp add agent-desktop -- agent-desktop mcp

إذا كان الوكيل لديك يدعم skills، فيمكنك أيضًا تحميل تعليمات الاستخدام الرسمية مباشرةً، ليعرف النموذج كيفية الاستدعاء:

agent-desktop skills get desktop وagent-desktop skills get platform: إخراج تعليمات المهارة
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop: التثبيت عبر skills.sh

وفي الحالات التي تتطلب استدعاءً داخل العملية نفسها، يمكنك أيضًا استخدام مكتبة C ‏libagent_desktop_ffi.

اختياري: agent-desktop sandbox في الإصدار 1.3.0

يضيف الإصدار 1.3.0 الأمر الفرعي agent-desktop sandbox ومزوّد sandbox الخاص بنظام macOS، ما يتيح تشغيل الأتمتة داخل جهاز افتراضي macOS موقّع محليًا، وعزل عمليات الوكيل عن سطح مكتبك الحقيقي. هذه ليست خطوة إلزامية، فالحلقة المغلقة الدنيا لا تعتمد عليها. وإذا كنت قلقًا من أن يتعامل الوكيل خطأً مع ملفاتك الحقيقية، أو ترغب في تشغيل عدد كبير من المهام الاستكشافية، فيمكنك إعطاءها الأولوية.

🚀 بداية سريعة: بعد إعداد MCP، لا يزال الوكيل المستدعي بحاجة إلى نموذج صالح للاستخدام. الطريقة الموصى بها رسميًا هي إنشاء رمز (token) في لوحة تحكم APIYI على apiyi.com، ثم توجيه Base URL الخاص بالوكيل إليه، فيمكن بمفتاح واحد التبديل والمقارنة بين نماذج Claude وGPT وGemini وغيرها.

ربط “عقل” النموذج بحلقة agent-desktop

لا يتولى agent-desktop سوى دور “العينين واليدين”، أما “العقل” الذي يحدد أي ref يجب النقر عليه ويقرر ما إذا كانت المهمة قد اكتملت فيقع لدى الطرف المستدعي. وفي هذه الخطوة هناك إعدادان بالغا الأهمية: Base URL وطراز النموذج.

Base URL: هل يُكتب معه /v1 أم بدونه؟

يستخدم الوكيل المستدعي عادةً نوعين من البروتوكولات، ولكل منهما طريقة كتابة مختلفة لـ Base URL، والخطأ في ذلك هو السبب الأكثر شيوعًا لظهور 404:

بروتوكول متوافق مع OpenAI (معظم السكربتات المكتوبة يدويًا، ومزوّد OpenAI المتوافق في OpenCode): https://api.apiyi.com/v1، أي مع /v1
بروتوكول Anthropic الأصلي (Claude Code وغيرها من العملاء التي تستدعي واجهة messages مباشرة): https://api.apiyi.com، أي بدون /v1

وعلى سبيل المثال مع Claude Code، يمكن توضيح الإعداد عبر متغيرات البيئة:

export ANTHROPIC_BASE_URL=https://api.apiyi.com
export ANTHROPIC_AUTH_TOKEN=你的令牌

إذا كنت تستخدم سكربت Python أو Node مكتوبًا يدويًا مع OpenAI SDK، فاضبط base_url على https://api.apiyi.com/v1 واملأ model بـ claude-opus-5-5. يتم إنشاء التوكن من api.apiyi.com/token، ولمزيد من التفاصيل حول الإعداد يمكنك الرجوع إلى docs.apiyi.com/faq/base-url-config.md.

كيف تكتب حلقة Agent بنفسك

عندما لا تريد الاعتماد على Agent جاهز، فإن كتابة حلقة بنفسك ليست بالمعقدة. الخطوات الأساسية هي:

شغّل agent-desktop snapshot --app 目标应用 -i، واقرأ مغلّف JSON من stdout.
أرسل هدف المهمة مع JSON اللقطة إلى النموذج، واطلب منه أن يعيد الإجراء التالي وref الكامل فقط.
نفّذ الأمر الذي يقترحه النموذج، مثل agent-desktop click @sxxxx:eN.
التقط snapshot مرة أخرى، وسلّم النتيجة الجديدة إلى النموذج ليقرر هل اكتملت المهمة؛ وعند استلام STALE_REF أعد الملاحظة مباشرة.
ضع حدًا أقصى للخطوات ونقاط تأكيد بشرية، لتجنب الحلقات اللانهائية أو العمليات التي تتجاوز الصلاحيات.

تستهلك الخطوتان 2 و4 هنا Tokens. وطريقة --skeleton مع --root للتنقيب المتدرج التي ذكرناها سابقًا تؤثر مباشرة في التكلفة هنا.

اختيار الطراز: claude-opus-5-5 مقابل claude-sonnet-5-5

تم إدراج طرازي Claude كليهما في جدول الطرازات الرئيسي على APIYI، وكلاهما يدعم نقطتي النهاية chat و messages. بيانات الأسعار في الجدول أدناه بتاريخ 2026-11-13، والوحدة لكل 1M Tokens، والطرازات والأسعار تخضع لقائمة الطرازات على المنصة.

الطراز	الإدخال	الإخراج	قراءة التخزين المؤقت	سيناريوهات agent-desktop المناسبة	المنصة المتاحة
`claude-opus-5-5`	$4	$20	$0.2	مهام متعددة الخطوات، وواجهات معقدة، وتحتاج إلى تخطيط أقوى	APIYI apiyi.com
`claude-sonnet-5-5`	$2	$10	$0.1	عمليات يومية واضحة الخطوات وكثيفة التكرار	APIYI apiyi.com

من الأفكار العملية أن تشغّل المسار أولاً باستخدام claude-opus-5-5، وبعد تثبيت الموجه والخطوات، تقيّم إمكانية نقل المراحل المستقرة إلى claude-sonnet-5-5. يحتوي JSON اللقطة على قدر كبير من التوجيهات النظامية وأوصاف الأدوات المتكررة، وسعر قراءة التخزين المؤقت أقل بوضوح من سعر الإدخال؛ لذا فإن تفعيل التخزين المؤقت للموجه مفيد مع الحلقات الطويلة. أما أحدث الأسعار فترجع إلى docs.apiyi.com/models.

استكشاف أخطاء agent-desktop: مشكلة صلاحيات أم مشكلة نموذج

agent-desktop والنموذج يمثلان مسارين مستقلين تمامًا، لذا عند ظهور خطأ فحدد أولًا أي الجانبين وقعت فيه المشكلة، وستختصر على نفسك الكثير من الطرق المسدودة:

العَرَض	الجانب	السبب المحتمل	طريقة المعالجة
الـ snapshot فارغة أو لا يمكن قراءة التطبيق	جانب الأداة	لم تُمنح صلاحية إمكانية الوصول، أو أن التطبيق نفسه لا يوفّر شجرة إمكانية الوصول	شغّل `agent-desktop permissions --guide` وتحقق من تصريح عملية المضيف
`INVALID_ARGS`	جانب الأداة	كتابة ref مجرّدة فقط، مثل `@e8`	استخدم ref كاملة، مثل `@s8f3k2p9:e8`
`STALE_REF` / `AMBIGUOUS_TARGET`	جانب الأداة	تغيّرت الواجهة وصارت الـ ref غير صالحة	أعد إنشاء snapshot
طلب النموذج يعيد 401	جانب النموذج	الرمز خاطئ أو منتهي الصلاحية، أو متغيّر البيئة لم يُفعّل	تحقق من الرمز على `api.apiyi.com/token` ثم أعد تصديره
طلب النموذج يعيد 404	جانب النموذج	كتابة `/v1` بشكل خاطئ في Base URL، أو خطأ إملائي في اسم النموذج	المتوافق مع OpenAI يأتي مع `/v1`، أما Anthropic الأصلي فبدونها؛ راجع الجدول الشامل لمقارنة النماذج

طريقة تشخيص بسيطة: إذا كان أمر agent-desktop يستطيع وحده إخراج JSON في الطرفية، فجانب الأداة سليم، وما بقي من أخطاء يكون في جانب النموذج تقريبًا. أما أخطاء 401/404 في جانب النموذج فيمكنك فحصها بندًا بندًا وفق شرح إعداد Base URL في مركز التوثيق الخاص بـ APIYI على apiyi.com.

مخاطر الأذونات والخصوصية في agent-desktop

يتناول هذا القسم مخاطر أتمتة سطح المكتب في حد ذاتها، ولا علاقة لها بالحساب، لكن يستحق أن تقرأه بتمعّن قبل البدء.

ثقل إذن إمكانية الوصول. تفعيل إمكانية الوصول على macOS يعني أن العملية المصرّح لها تستطيع قراءة واجهة تطبيقات أخرى والتحكم فيها. وبعد منح الإذن لطرفية أو لأحد مضيفات Agent، قد تحصل أي برامج تعمل داخل هذه العملية على القدرة نفسها. لذا يُنصح بمنح الإذن للمضيف الضروري فقط، ويمكنك إيقافه لاحقًا من إعدادات النظام.

قد تحتوي لقطات snapshot والحافظة ولقطات الشاشة على بيانات خاصة. تشير الوثائق الرسمية صراحةً إلى أن snapshot ومحتوى الحافظة ولقطات الشاشة والإشعارات وصفحة debug HTML قد تحمل جميعها معلومات حساسة من سطح المكتب، مثل محتوى المحادثات وعناوين البريد وأسماء الملفات وواجهة مدير كلمات المرور. وهذه البيانات يرسلها الطرف المستدعي إلى النموذج، لذلك لا ترفع سجلات التصحيح علنًا، ولا تلصق snapshot كاملًا في issue مباشرة.

المساعد الاختياري helper يتصل بالشبكة. أداة CLI الأصلية لا تتطلب خدمة نموذج عن بُعد، لكن إن فعّلت helper JEV الاختياري فسيُرسل الهدف ووصف الشاشة إلى مزوّد النموذج الذي ضبطته. وهل تفعّله، وإلى مَن تُرسل البيانات، أمر يجب أن يكون واضحًا في ذهنك.

تبعات العمليات يتحمّلها المستخدم. قد يضغط Agent على زر خاطئ، أو يحذف ملفًا خاطئًا، أو يرسل رسالة ما كان ينبغي إرسالها. ويمكنك تقليل المخاطر بهذه الممارسات: التجربة داخل sandbox في الإصدار 1.3.0، وتقييد نطاق --app، وإضافة تأكيد بشري للعمليات عالية الخطورة مثل الحذف والإرسال والدفع. وانتبه إلى أن التطبيقات التي لا يمكن قراءة شجرة إمكانية الوصول فيها تكون غير مرئية لـ agent-desktop، فهذا حدّ من قدراته، ولا تتوقع منه أن يعمل بالضرورة مع كل البرامج.

ربط وكلاء الطرف الثالث ببوابة API خطر من نوع آخر. عند ربط وكلاء طرف ثالث مثل Claude Code وOpenCode بأي بوابة API، انتبه إلى حفظ الرمز (token) وسقف الحصة وما قد يُكتب في السجلات من محتوى حساس. ويُقيّم هذا الخطر بشكل منفصل عن مخاطر أتمتة سطح المكتب. ويُستحسن إنشاء رمز مستقل للـ Agent مع تحديد حصة له، حتى يمكنك إبطاله وحده عند وقوع مشكلة.

الأسئلة الشائعة (FAQ)

س1: ما هو agent-desktop؟

agent-desktop هي أداة سطر أوامر (CLI) لـ computer use، مفتوحة المصدر من Vercel Labs. من خلال شجرة إمكانية الوصول في نظام التشغيل، تتيح لوكيل الذكاء الاصطناعي أن يرى تطبيقات سطح المكتب على macOS وWindows وLinux ويتفاعل معها، دون الاعتماد على لقطات الشاشة أو مطابقة البكسلات. هي أداة وليست وكيلاً، ولا تحتوي على نموذج في حد ذاتها.

س2: ما الفرق بين agent-desktop وcomputer use القائم على لقطات الشاشة؟

تعتمد الحلول القائمة على لقطات الشاشة على نموذج بصري لفهم البكسلات ثم إخراج الإحداثيات، وهذا مسار طويل ويتأثر بدقة الشاشة. أما agent-desktop فيُخرج مباشرة JSON منظّمًا وref، ويعمل النموذج وفق ref، ويُشغَّل افتراضيًا بوضع headless فلا يستحوذ على المؤشر أو التركيز. الثمن هو أنك لا ترى إلا التطبيقات التي تُعرّض معلومات إمكانية الوصول.

س3: ما الإصدار الحالي من agent-desktop؟

حتى 2026-11-13، أحدث إصدار ظاهر هو 1.3.0 (2026-11-11)، وأضاف sandbox. أما MCP فمتاح منذ 1.2.0 (2026-11-05)، ودخل Linux رسميًا إلى 1.0 في الإصدار 1.0.0 (2026-10-27). التحديثات سريعة، لذا اعتمد على GitHub Releases كمرجع.

س4: ما السيناريوهات المناسبة لـ agent-desktop؟

– **اختبار التطبيقات الأصلية**: النقر الآلي على لوحات الإعدادات والتحقق من حالة الواجهة
– **توسيع وكلاء البرمجة**: أن يفتح Claude Code تطبيق سطح المكتب بعد كتابة الشفرة للتحقق من النتيجة
– **عمليات سطح المكتب المتكررة**: ترتيب ملفات Finder، وقراءة الإشعارات، وقراءة الحافظة والكتابة فيها

أما المهام المتعلقة بالويب فاتركها لـ agent-browser.

س5: كيف يربط الوكيل الذي يستدعي agent-desktop النموذجَ بسرعة؟

1. سجّل في APIYI على apiyi.com وأنشئ مفتاح API من صفحة الرموز (token)، وللمستخدمين الجدد حصة تجربة مجانية
2. في عميل متوافق مع OpenAI اضبط Base URL على `https://api.apiyi.com/v1`، وفي عميل Anthropic الأصلي اضبطه على `https://api.apiyi.com`
3. اختر النموذج `claude-opus-5-5` أو `claude-sonnet-5-5`، ثم شغّل حلقة snapshot الموصوفة في هذا المقال

س6: ضبطت MCP، لكن الوكيل يُرجع 401 أو 404، هل المشكلة في agent-desktop؟

عادةً لا. فـ agent-desktop لا يتصل بخدمة النموذج؛ وخطأ 401 يكون غالبًا مشكلة في الرمز (token)، أما 404 فسببه في الأغلب كتابة `/v1` بشكل خاطئ أو خطأ في تهجئة اسم الطراز. شغّل أولاً في الطرفية الأمر `agent-desktop snapshot` وحدَه للتأكد من أن الأداة تعمل، ثم راجع إعدادات Base URL في وثائق APIYI على apiyi.com لتشخيص جانب النموذج.

س7: ما القيود المعروفة لـ agent-desktop؟

– التطبيقات التي لا تُقرأ شجرة إمكانية الوصول فيها تكون غير مرئية له
– بعض الإصدارات تحمل تغييرات كاسرة (مثل 1.1.0 و1.3.0)، فاقرأ Changelog قبل الترقية
– مزوّد sandbox موجّه حاليًا إلى macOS، وغير معروف حتى الآن ما إذا كانت المنصات الأخرى ستلحقه
– لا يقوم بأتمتة الويب، ويحتاج إلى agent-browser معه

النقاط الأساسية في agent-desktop

الأداة لا تتضمن النموذج: يخرج agent-desktop فقط JSON envelope، بينما تُدار الحلقة والقرارات في جهة الاستدعاء
computer use دون لقطات شاشة: يعتمد على أشجار الوصول AX وUI Automation وAT-SPI، وينفذ العمليات حسب ref
يجب أن يكون ref كاملاً: بالشكل @s8f3k2p9:e8، وعند تغيّر الواجهة يلزم إعادة snapshot
متاح على ثلاث منصات: macOS 13+ وWindows 10 1809+ وUbuntu 24.04+
تكامل MCP بسطر واحد: بدءاً من 1.2.0 يعمل agent-desktop mcp عبر stdio
الويب يُسلّم إلى agent-browser: يمكن تسليم تطبيقات Electron عبر منفذ DevTools
ربط الدماغ: وجّه Base URL في جهة الاستدعاء إلى APIYI apiyi.com، واختر claude-opus-5-5

الخلاصة

النقاط الأساسية في agent-desktop:

تحديد الدور واضح: هو «العينان واليدان» لتطبيقات سطح المكتب، ولا يتضمن النموذج ولا يتولى الويب
حلقة العمل بسيطة: التثبيت ← permissions --guide ← snapshot ← click ← إعادة snapshot، مع --skeleton للتحكم في طول السياق
تكامل مرن: يمكن استخدام CLI وMCP وskills وFFI، وsandbox في الإصدار 1.3.0 مناسب لتجربة معزولة
يجب ضبط المخاطر: تفويض إمكانية الوصول ومحتوى الخصوصية في snapshot يحتاجان إلى إدارة وفق معايير أتمتة سطح المكتب

بعد تشغيل الجانب الخاص بالأداة بنجاح، تبقى مهمة تجهيز «دماغ» مناسب لحلقة العمل. نوصي بإنشاء رمز عبر APIYI apiyi.com، وتوجيه Base URL الخاص بـ Claude Code أو OpenCode أو سكربت من إعدادك إلى هناك، والتحقق من سير العمل أولاً باستخدام claude-opus-5-5، ثم تقييم الانتقال إلى claude-sonnet-5-5 حسب تعقيد المهمة.

📚 المراجع

GitHub – agent-desktop: المستودع الرسمي مفتوح المصدر، ويشمل README وFAQ وChangelog
الرابط: github.com/vercel-labs/agent-desktop
الوصف: تُعتمد هنا تغييرات الإصدارات وقائمة الأوامر وإشعارات الخصوصية
وثائق agent-desktop الرسمية: المفاهيم والبداية السريعة
الرابط: agent-browser.dev/desktop، agent-browser.dev/desktop/quick-start
الوصف: التثبيت والتفويض وأمثلة أصغر حلقة متكاملة
npm – agent-desktop: صفحة حزمة npm
الرابط: npmjs.com/package/agent-desktop
الوصف: للاطلاع على الإصدار المنشور حاليًا
Vercel – What is computer use: مقدمة عن مفهوم computer use
الرابط: vercel.com/i/what-is-computer-use
الوصف: فهم الفرق بين أسلوب شجرة إمكانية الوصول وأسلوب لقطة الشاشة
مركز وثائق APIYI: الجدول العام للطرازات، وإعداد Base URL، وشرح قدرات Claude
الرابط: docs.apiyi.com/models.md، docs.apiyi.com/faq/base-url-config.md، docs.apiyi.com/api-capabilities/claude.md
الوصف: تُعتمد الطرازات والأسعار وفق قائمة الطرازات في المنصة

المؤلف: فريق APIYI التقني
التواصل التقني: يسعدنا تواصلك معنا عبر الصفحة الرئيسية لموقع APIYI على apiyi.com، ولمزيد من المواد يمكنك زيارة مركز الوثائق docs.apiyi.com

تطبيق سطح المكتب يمكن أيضًا التحكم فيه بواسطة الوكيل: دليل تعليمي من 5 خطوات لربط agent-desktop بالنموذج

النقاط الأساسية في agent-desktop

كيف يعمل agent-desktop: شجرة الوصول و ref