في الجزء 1 شاهدت AgentX يعمل من دون أن تثبّت شيئًا: شغّل العرض التجريبي ثلاث خدمات خلفية، ونقل مهمة واحدة بينها، ثم نظّف ما خلّفه. في هذا الجزء تثبّت AgentX فعليًا على حاسوبك.

التثبيت أمر واحد. المهارة المفيدة تأتي بعده: أن تعرف هل التثبيت سليم، وإن لم يكن سليمًا فما الذي ينقصه بالضبط. لدى AgentX أمر لهذا الغرض اسمه agentx doctor. يفحص الأسباب الشائعة التي تمنع AgentX من العمل، ويطبع تحت كل مشكلة حلًّا مقترحًا. ومعظم هذا الدليل عن قراءة ذلك التقرير.

هذا هو الجزء 2 من سلسلة AgentX عمليًا، وهي أدلة قصيرة ينتهي كل جزء منها بشيء واحد يعمل.

ما الذي ستحصل عليه في النهاية

الأمر agentx مثبّتًا على حاسوبك، بإصدار تعرف رقمه.
مجلد مشروع فيه ملف إعدادات AgentX.
الخدمة الخلفية لـ AgentX تعمل وتستجيب.
تقرير doctor تستطيع قراءته، فيه خطآن باقيان تفهم سببهما. كلاهما يخص نموذج الذكاء الاصطناعي، ويعالجهما الجزء 3.

ما لا يفعله هذا الجزء. لا يربط نموذجًا، فلا يردّ أي وكيل على رسالة بعد. وهذا مقصود: مهمة واحدة لكل جزء. AgentX جزء من برنامج منتجات نقطة، وما يزال تجريبيًا. سترى أثر ذلك في الخطوة 5، وهذا الدليل يدلّك على طريق يتجاوزه.

المتطلبات

Node.js 22.19 أو أحدث، حتى الإصدار 26. يرفض AgentX العمل على غير هذه الإصدارات. شُغّل هذا الدليل على Node.js 22.22.0.
macOS أو Linux. لم يختبر القائمون على AgentX نظام Windows؛ استخدم WSL عليه. شغّلنا هذا الدليل على macOS.
طرفية ومتصفح.
نحو دقيقتين للتنزيل.

لا تحتاج في هذا الجزء إلى Git ولا Docker ولا حساب ولا مفتاح API.

كيف شغّلناه. ثبّتنا AgentX في مجلد منزلي نظيف ومنفصل، على جهاز Mac يعمل عليه AgentX آخر أصلًا، حتى لا يعتمد شيء في هذا الدليل على إعداد سابق. ولنفصل بين الاثنين نقلنا الخدمة الخلفية التجريبية إلى المنفذ 19021 ولوحة التحكم إلى المنفذ 19031. فحيث يظهر هذان الرقمان في مخرجاتنا سيظهر عندك الرقمان الافتراضيان: 18800 للخدمة الخلفية و4202 للوحة التحكم. وشغّلنا agentx setup مع --no-open، وهو يطبع عنوان لوحة التحكم بدل فتح المتصفح. واختصرنا كذلك مسارات المجلدات، وحذفنا بضعة أسطر من المخرجات، ووضعنا my-computer مكان اسم حاسوبنا.

الخطوة 1: تحقّق من إصدار Node.js

node --version

مخرجاتنا:

v22.22.0

إذا كان الرقم أقل من v22.19 أو أعلى من v26، فثبّت Node.js 22 من nodejs.org وأعد تشغيل الأمر. الإصدار 20 من Node.js أقدم من المطلوب، وقسم حل المشكلات يعرض الرسالة التي تظهر معه.

الخطوة 2: ثبّت AgentX من npm

npm install -g agentix-cli@latest

اسم الحزمة agentix-cli، واسم الأمر الذي تثبّته agentx. مخرجاتنا:

npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
npm warn deprecated domexception@4.0.0: Use your platform's native DOMException instead
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
 
added 347 packages in 2m

أسطر npm warn deprecated الثلاثة لا ضرر منها. هي تخص مكتبات يعتمد عليها AgentX، لا تثبيتك أنت. استغرق التثبيت على جهازنا 93 ثانية.

لتحصل على ما يعرضه هذا الدليل بالضبط، ثبّت الإصدار الذي اختبرناه:

npm install -g agentix-cli@0.137.3

يصدر AgentX إصدارات كثيرة، وأحيانًا أكثر من إصدار في اليوم، فقد تختلف صياغة سطر في إصدار أحدث. أما الخطوات فتبقى كما هي.

الخطوة 3: تأكّد من وجود الأمر

agentx --version

0.137.3

إذا ردّت الطرفية بـ command not found: agentx، فالتثبيت نجح لكن الطرفية لا ترى الأمر. الحل في قسم حل المشكلات.

الخطوة 4: شغّل doctor في مجلد فارغ

يحفظ AgentX إعداداته في المجلد الذي تشغّله منه. أنشئ له مجلدًا وادخل إليه:

mkdir my-agentx
cd my-agentx

ثم اطلب فحصًا:

agentx doctor

مخرجاتنا:

  agentx doctor
 
  Environment
    ✓ Node.js 22.22.0
    ✓ npm on PATH
      /Users/you/.nvm/versions/node/v22.22.0/bin/npm
    ! claude CLI not on PATH
      Only required for agents on the claude-code tier.
      → See https://docs.anthropic.com/en/docs/claude-code
    ! codex CLI not on PATH
      Only required for agents on the codex-cli tier.
      → Install with `npm i -g @openai/codex`.
    ! opencode CLI not on PATH
      Only required for agents on the opencode tier.
      → Install from https://opencode.ai/docs/.
    ✓ better-sqlite3 loads for Node v22.22.0
      NODE_MODULE_VERSION 127
 
  Config
    ✗ agentx.json not found
      Looked in /Users/you/my-agentx/agentx.json
      → Run `agentx setup` to create one via the web wizard.
 
  1 error, 3 warnings. Fix the error and rerun.

هكذا تقرأ أي تقرير من doctor:

✓ نجح الفحص.
! تحذير. يستحق القراءة، لكنه لا يوقف AgentX.
✗ خطأ. لن يعمل AgentX كما ينبغي حتى يُصلَح.
→ الحل المقترح للسطر الذي فوقه.
الفحوص موزّعة على مجموعات. هنا مجموعتان: Environment (حاسوبك) وConfig (إعداداتك). وتظهر مجموعات أخرى حين توجد إعدادات تُفحص.
السطر الأخير يعدّ الأخطاء والتحذيرات.

doctor يفحص فقط. لا يثبّت شيئًا ولا يصلح شيئًا.

ما يقوله هذا التقرير الأول:

البيئة سليمة. إصدار Node.js مدعوم، وbetter-sqlite3، وهي قاعدة البيانات الصغيرة التي يحفظ فيها AgentX سجلاته، تُحمَّل بلا مشكلة. السطر الثاني مهم: هذا هو الجزء الأكثر عرضة للتعطل حين لا يتوافق إصدار Node.js.
التحذيرات الثلاثة قائمة اختيارات، لا قائمة مهام. claude وcodex وopencode ثلاث أدوات ذكاء اصطناعي للبرمجة يستطيع AgentX استخدام أي منها محرّكًا للوكيل. وكل تحذير يقول الشيء نفسه: هذه الأداة مطلوبة فقط إذا استخدمها وكيل. لا تحتاج إلى الثلاث، وقد لا تحتاج إلى أي منها.
الخطأ الوحيد متوقع. لا يوجد ملف إعدادات بعد، لأنك لم تنشئه.

الخطوة 5: أنشئ ملف الإعدادات

يقترح doctor الأمر agentx setup، وهو يفتح صفحة إعداد في المتصفح. في الإصدار الذي اختبرناه لا يعمل هذا الأمر في مجلد فارغ. شغّلناه فظهر هذا:

  No agentx.json yet — the wizard will create one.
  Opening http://127.0.0.1:19031/setup
 
  Starting dashboard server on port 19031 (Ctrl-C to quit)…
  No agentx.json found — starting dashboard in setup-only mode.
  Visit http://127.0.0.1:19031 to run the wizard.
 
  Cannot read properties of undefined (reading 'enabled')

ثم يتوقف الأمر ولا تُحمَّل صفحة الإعداد أبدًا. هذا خلل في AgentX 0.137.3، وليس خطأ منك. إذا رأيت السطر الأخير فاسلك الطريق التالي. قد يصلحه إصدار لاحق، والطريق التالي يعمل في الحالتين.

أنشئ ملف الإعدادات من الطرفية:

agentx init

  agentx init
 
  ✓ Created agentx.json
  ✓ Created .env template
  ✓ Created .agentx/sessions/
  ✓ Created .claude/
 
  Next steps:
    1. Edit agentx.json — configure agents, channels, crons
    2. Edit .env — add API keys and bot tokens
    3. Run  agentx daemon start — start the daemon
    4. Run  agentx daemon status — verify everything

ما الذي أنشأه:

agentx.json هو ملف الإعدادات. يبدأ بوكيل واحد اسمه assistant، بلا قنوات ولا مهام مجدولة.
.env مكان المفاتيح الخاصة. يبدأ قالبًا كل أسطره معطّلة بعلامة التعليق، فلا مفتاح فيه بعد.
.agentx/ مجلد عمل AgentX لهذا التثبيت: قاعدة بياناته وجلساته وسجلاته.
.claude/ فيه إعدادات تخص مجلد الوكيل.

تستطيع أن تتأكد من صحة ملف الإعدادات وحده:

agentx config check

  ✓ Config valid
    Node: my-computer (my-computer)
    Bind: 127.0.0.1:19021
    Agents: 1
    Crons: 0
    Mesh peers: 0
    Telegram: disabled
    WhatsApp: disabled
  ✓ All workspaces valid

Node هو هذا الحاسوب، ويأخذ اسمه. وBind هو العنوان الذي ستستمع عليه الخدمة الخلفية. 127.0.0.1 يعني هذا الحاسوب فقط، فلا يصل إلى AgentX شيء من خارجه. وعندك يظهر 127.0.0.1:18800.

الخطوة 6: شغّل doctor مرة ثانية

agentx doctor

مجموعة Environment كما كانت. ومن Config فما بعدها صار تقريرنا هكذا:

  Config
    ✓ agentx.json valid (1 agents, 0 schedules)
    ✗ 1 agent(s) use claude-code tier but claude CLI is missing
      assistant
      → Install Claude Code (https://docs.anthropic.com/en/docs/claude-code) or switch these agents to tier=sdk.
 
  Secrets
    ✗ 1 env var(s) referenced in agentx.json but missing
      ANTHROPIC_API_KEY
      → Add to .env — e.g. ANTHROPIC_API_KEY=<value>
 
  Workspaces
    ✓ All agent workspace folders exist
 
  Workspace settings
    ✓ All 1 agent .claude/settings.json files clean
 
  Routing
    ✓ 0 webhook(s), 0 telegram account(s) — all routing references resolve
 
  Notifications
    ! AgentX Helper is not installed, so banners come from Script Editor and show its icon.
      → Run agentx desktop install, then run agentx notify "Hello" --title "Test" and click Allow.
 
  Runtime
    ! Daemon not reachable (not running?)
      http://127.0.0.1:19021
      → Run `agentx daemon start`. Skip this check with `agentx doctor --no-running`.
 
  2 errors, 5 warnings. Fix the errors and rerun.

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

claude CLI is missing. الوكيل الابتدائي مضبوط على استخدام Claude Code محرّكًا له، و Claude Code غير مثبّت على هذا الجهاز. في الخطوة 4 كان هذا تحذيرًا فقط، لأن لا وكيل كان يحتاجه. الآن يحتاجه وكيل، فصار خطأ. doctor هنا دقيق، ولا يناقض نفسه.
ANTHROPIC_API_KEY مفقود. يشير ملف الإعدادات إلى مفتاح لا يحتويه ملف .env بعد.
AgentX Helper is not installed. يظهر على Mac فقط. يخص إشعارات سطح المكتب، وهو اختياري.
Daemon not reachable. تحذير، وهو السطر الوحيد الذي تصلحه في هذا الجزء. الخدمة الخلفية لم تُشغَّل بعد.

الخطآن يقولان شيئًا واحدًا: ليس لدى الوكيل نموذج ذكاء اصطناعي يفكّر به. وربط النموذج مهمة الجزء 3. اتركهما الآن.

الخطوة 7: شغّل الخدمة الخلفية وتحقّق منها

الخدمة الخلفية (daemon) هي ما يستقبل الرسائل ويشغّل الوكلاء ويرسل الردود. شغّلها في الخلفية:

agentx daemon start --detach

Daemon started in background (PID: 33860)
  Logs: tail -f /tmp/agentx-daemon.log
  Stop: agentx daemon stop

ثم اسأل عن حالها:

agentx daemon status

  my-computer (my-computer)
  Status: running — uptime 9s
  AgentX 0.137.3 (c2e6a0a)   node my-computer
  Running since   2026-10-13 10:05 (Africa/Tunis), 9s ago, pid 33860
  Last restart    2026-10-13 10:05, first start on record
  Restarts        1 today, 1 in the last 7 days (on record since 2026-10-13 10:05)
  Build on disk   dist newer than process: no
  Service         none (started from a terminal, nothing starts it again)
 
  Agents:
    Assistant (claude-code)
      /Users/you/my-agentx

سطران يستحقان قراءة متأنية:

Status: running هو السطر الذي تريده.
Service: none (started from a terminal, nothing starts it again) يصارحك بحدّ قائم. أنت شغّلت الخدمة بيدك، فإذا أُعيد تشغيل الحاسوب لم تعد الخدمة من تلقاء نفسها. وهذا يكفي الآن.

شغّل doctor مرة ثالثة. تتغير المجموعة الأخيرة:

  Runtime
    ✓ Daemon healthy — 1 agents live, uptime 0m
      http://127.0.0.1:19021
    ✓ Daemon finds ffmpeg to measure phone recordings
 
  2 errors, 4 warnings. Fix the errors and rerun.

اختفى تحذير Daemon not reachable وحلّ مكانه Daemon healthy. وبقي خطآ النموذج كما توقعنا.

الخطوة 8: شاهد التقرير نفسه في المتصفح

لدى AgentX لوحة تحكم في المتصفح، وتقرير doctor موجود فيها. وبعد أن صار ملف الإعدادات موجودًا، يشغّل agentx setup لوحة التحكم من دون خلل الخطوة 5:

agentx setup

  Found agentx.json — the wizard will extend your current install.
  Opening http://127.0.0.1:19031/setup
 
  Starting dashboard server on port 19031 (Ctrl-C to quit)…
 
  Live dashboard: http://127.0.0.1:19031
 
  (bound to localhost; no auth token — safe default)

اترك هذه الطرفية مفتوحة، فهي التي تشغّل لوحة التحكم. يفتح متصفحك صفحة الإعداد. لا تملأها الآن: هذا موضوع الجزء 3. افتح بدلًا من ذلك /admin/health على العنوان نفسه (عندك http://127.0.0.1:4202/admin/health) واختر تبويب Doctor.

تبويب Doctor في صفحة Health في AgentX: مجموعات Environment و Config و Secrets بعلامات OK و WARN و FAIL، والملخص ok=9 warn=4 fail=2

هي الفحوص نفسها، بعلامات OK وWARN وFAIL مكان الرموز الثلاثة، ومعها زر Re-run checks. والملخص يقول ok=9 warn=4 fail=2، وهو يطابق الطرفية: خطآن و4 تحذيرات.

ثم افتح Live من الشريط العلوي.

تبويب Live في AgentX بعد تثبيت جديد: 1/1 machines، ووكيل واحد اسمه @assistant، خامل ولم يُستخدم بعد

يعرض Live العبارة 1/1 machines ووكيلًا واحدًا هو @assistant، وعليه IDLE وnot used yet. في الجزء 1 كانت هذه الصفحة تعرض ثلاثة أجهزة محاكاة. هذه المرة الجهاز جهازك.

حين تنتهي، اضغط Ctrl-C في الطرفية التي تشغّل لوحة التحكم. الخدمة الخلفية تبقى تعمل، فهي برنامج مستقل.

الخطوة 9: أوقف الخدمة الخلفية

agentx daemon stop

Daemon stopped (PID: 33860)

بعدها يقول agentx daemon status العبارة AgentX is stopped ويذكّرك بطريقة تشغيله من جديد. شغّل هذه الأوامر من مجلد my-agentx: يجد AgentX خدمته الخلفية عبر ملف الإعدادات في المجلد الحالي.

خيارات مفيدة في doctor

الخياران شُغّلا لهذا الدليل على الإصدار 0.137.3.

الخيار	ما يفعله
`agentx doctor --no-running`	يتخطى فحص استجابة الخدمة الخلفية. استخدمه حين توقف الخدمة عمدًا. نزل تقريرنا من 5 تحذيرات إلى 4.
`agentx doctor --json`	يطبع الفحوص نفسها بصيغة تقرؤها البرامج الأخرى. لكل فحص `severity` و`group` و`title`، ومعها `fix` إن وُجد.

ينتهي doctor برمز الخروج 1 إذا وُجد خطأ واحد على الأقل. ويمكن لسكربت أن يعتمد على ذلك.

تحقّق من النجاح

يطبع agentx --version رقم إصدار.
يعرض agentx doctor السطر ✓ agentx.json valid تحت Config.
والخدمة الخلفية تعمل، يعرض agentx doctor السطر ✓ Daemon healthy تحت Runtime.
أسطر ✗ الباقية هي فقط السطران الخاصان بالنموذج: المحرّك المفقود والمفتاح المفقود.

إذا تحققت الأربعة، فـ AgentX مثبّت ويعمل، وأنت تعرف بالضبط ما يفصلك عن وكيل يعمل.

حل المشكلات

AgentX needs Node.js 22.19 or newer, up to 26. This is Node.js 20.20.2. أعدنا إنتاج هذه الرسالة بتشغيل agentx نفسه على Node.js 20. كل الأوامر، ومنها agentx doctor، تتوقف عند هذا السطر الواحد. ثبّت Node.js 22 وتحقق بـ node --version.

command not found: agentx. الحزمة مثبّتة، لكن المجلد الذي يضع فيه npm الأوامر ليس ضمن مسار البحث في طرفيتك. أعدنا إنتاج الحالة بحذف ذلك المجلد من المسار. اعرف المجلد بهذا الأمر:

npm prefix -g

الأمر agentx موجود في مجلد bin داخل المجلد المطبوع. أضف مجلد bin هذا إلى PATH، أو افتح طرفية جديدة إن كنت ثبّتّ Node.js للتو.

Cannot read properties of undefined (reading 'enabled') بعد agentx setup. هذا خلل الخطوة 5. يحدث في الإصدار 0.137.3 حين لا يكون في المجلد ملف agentx.json. شغّل agentx init أولًا ثم agentx setup.

Daemon not reachable (not running?). شغّل الخدمة بـ agentx daemon start --detach من المجلد الذي فيه agentx.json. وإن كنت أوقفتها عمدًا فاستخدم agentx doctor --no-running.

agentx.json not found. أنت في مجلد غير الذي شغّلت فيه agentx init. يطبع doctor المسار الذي بحث فيه؛ ارجع إلى مجلد my-agentx بالأمر cd.

يفشل npm install -g بخطأ صلاحيات (EACCES). لم نُعد إنتاج هذه الحالة. تحدث حين يكون Node.js مثبّتًا على مستوى النظام ولا يُسمح لـ npm بالكتابة في مجلده. تثبيت Node.js عبر مدير إصدارات مثل nvm يجنّبك إياها.

إزالة التثبيت

اختبرنا هذا أيضًا. من مجلد my-agentx:

agentx daemon stop
npm uninstall -g agentix-cli

removed 347 packages in 2s

هذا يزيل الأمر. ولا يمسّ مجلد مشروعك: يبقى agentx.json و.env و.agentx و.claude في مكانها، ومعها AGENTS.md وCLAUDE.md، وهما ملفا تعليمات كانا في مجلدنا عند نهاية التشغيل. احذف مجلد my-agentx إن أردت ألا يبقى شيء. وإن كنت ستكمل إلى الجزء 3 فاحتفظ بكل شيء.

شاهده

الفيديو الثاني من سلسلة Learn AgentX يشرح التثبيت: youtu.be/arOqm5bB1Lw.

الجزء التالي من السلسلة

الجزء 3 ينشئ وكيلك الأول: يربط نموذج ذكاء اصطناعي، فيزول الخطآن اللذان ما زال doctor يعرضهما، ثم يرسل إلى الوكيل رسالته الأولى. وإلى ذلك الحين، توثيق AgentX على github.com/anis-marrouchi/agentx.

الخلاصة

ثبّتّ AgentX، وأنشأت إعداداته، وشغّلت خدمته الخلفية، وقرأت تقرير فحصه ثلاث مرات ورأيته يتغير كلما اكتمل جزء. ورأيت كذلك فائدة الفحص: حوّل عبارة «لا يعمل» إلى سطرين محدّدين، تحت كل منهما حلّه.

إذا أردت وكلاء يعملون على أدوات فريقك، مثبّتين ومفحوصين ونُبقيهم سليمين عنك، تحدّث إلينا.