NanoClaw

مساعد ذكاء اصطناعي يُشغّل العوامل (agents) بشكل آمن داخل حاوياتها الخاصة. خفيف الوزن، صُمم ليكون سهل الفهم وقابلًا للتخصيص الكامل حسب احتياجاتك.

nanoclaw.dev • الوثائق • 中文 • 日本語 • 한국어 • •

لماذا بنيت NanoClaw

OpenClaw مشروع مذهل، لكن ما كنت لأستطيع النوم لو منحت برنامجًا معقدًا لا أفهمه صلاحية الوصول الكامل إلى حياتي. يحتوي OpenClaw على ما يقرب من نصف مليون سطر من الكود، و53 ملف إعدادات، وأكثر من 70 تبعية. أمانه يعتمد على مستوى التطبيق (قوائم السماح، رموز الاقتران) وليس على عزل حقيقي على مستوى نظام التشغيل. كل شيء يعمل في عملية Node واحدة بذاكرة مشتركة.

NanoClaw يوفّر نفس الوظائف الأساسية، لكن في قاعدة كود صغيرة بما يكفي لفهمها: عملية واحدة ومجموعة ملفات محدودة. تعمل العوامل (agents) داخل حاويات Linux الخاصة بها مع عزل لنظام الملفات، وليس فقط خلف فحوصات الأذونات.

بداية سريعة

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh

يأخذك nanoclaw.sh من جهاز جديد إلى عامل مسمى يمكنك مراسلته. يقوم بتثبيت Node وpnpm وDocker إذا كانت مفقودة، ويسجل بيانات اعتماد Anthropic الخاصة بك مع OneCLI، ويبني حاوية العامل، ويقوم بإقران قناتك الأولى (Telegram أو Discord أو WhatsApp أو CLI محلي). إذا فشلت إحدى الخطوات، يتم استدعاء Claude Code تلقائيًا لتشخيص المشكلة واستئناف العمل من حيث توقفت.

هل تنتقل من NanoClaw v1؟

شغّل من إصدار v2 جديد بجوار تثبيت v1 الحالي:

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash migrate-v2.sh

migrate-v2.sh يجد تثبيت v1 الخاص بك (دليل مجاور، أو NANOCLAW_V1_PATH=/path/to/nanoclaw)، ويهاجر الحالة إلى إصدار v2، ثم يُنفّذ exec إلى Claude Code لإكمال الأجزاء التي تتطلب حكمًا (تهيئة المالك، تنظيف CLAUDE.local.md، إعادة تشغيل تخصيصات fork).

شغّل السكريبت مباشرة، وليس من داخل جلسة Claude — فالجزء الحتمي يحتاج إلى موجهات تفاعلية وإدخال/إخراج حقيقي من shell لتشغيل Node/pnpm وDocker وOneCLI وبناء الحاوية.

ما يفعله: يدمج .env، ويهيئ قاعدة بيانات v2 من registered_groups، وينسخ مجلدات المجموعات + بيانات الجلسات + المهام المجدولة، ويُثبّت محولات القنوات التي تختارها، وينسخ حالة مصادقة القناة (بما في ذلك مخزن مفاتيح Baileys لواتساب — يتم الآن حل تعيين LID لكل رسالة بواسطة محول Baileys v7، وليس هجرة)، ويبني حاوية العامل.

ما لا يفعله: تغيير خدمة النظام. اختر "التبديل إلى v2" عند المطالبة، أو افعل ذلك يدويًا بعد الاختبار — تثبيت v1 الخاص بك يبقى دون تغيير.

انظر docs/v1-to-v2-changes.md للاطلاع على الاختلافات و docs/migration-dev.md لملاحظات التطوير.

الفلسفة

صغير بما يكفي للفهم. عملية واحدة، عدد قليل من ملفات المصدر ولا توجد خدمات مصغرة. إذا أردت فهم قاعدة كود NanoClaw بالكامل، فقط اطلب من Claude Code أن يشرحها لك خطوة بخطوة.

آمن بفضل العزل. تعمل العوامل داخل حاويات Linux ولا يمكنها رؤية سوى ما تم تركيبه صراحةً. الوصول إلى Bash آمن لأن الأوامر تُنفّذ داخل الحاوية، وليس على جهازك المضيف.

مبني للمستخدم الفردي. NanoClaw ليس إطار عمل متجانسًا؛ إنه برنامج يناسب احتياجات كل مستخدم تمامًا. بدلاً من أن يصبح برنامجًا منتفخًا، صُمم NanoClaw ليكون مخصصًا. أنشئ fork خاصًا بك واطلب من Claude Code تعديله ليتوافق مع احتياجاتك.

التخصيص = تغييرات في الكود. لا توجد فوضى في ملفات الإعدادات. تريد سلوكًا مختلفًا؟ عدّل الكود. قاعدة الكود صغيرة بما يكفي لجعل التغييرات آمنة.

أصلي للذكاء الاصطناعي، هجين بطبيعته. عملية التثبيت والإعداد هي مسار مُحسَّن ومُبرمج، سريع وحتمي. عندما تحتاج خطوة إلى حكم، سواء كان تثبيتًا فاشلاً، أو قرارًا موجهًا، أو تخصيصًا، يتم تسليم التحكم إلى Claude Code بسلاسة. بعد الإعداد، لا توجد لوحة مراقبة أو واجهة تصحيح أخطاء أيضًا: صِف المشكلة في الدردشة وسيتولى Claude Code معالجتها.

المهارات (Skills) قبل الميزات. الفرع الرئيسي (trunk) يوفّر السجل والبنية التحتية، وليس محولات القنوات المحددة أو موفري العوامل البديلين. القنوات (Discord، Slack، Telegram، WhatsApp، …) تعيش على فرع طويل الأجل يُسمى channels؛ المزوّدون البديلون (OpenCode، Ollama) يعيشون على providers. تُشغّل /add-telegram أو /add-opencode إلخ وتقوم المهارة بنسخ الوحدة (الوحدات) التي تحتاجها بالضبط إلى fork الخاص بك. لا توجد ميزة لم تطلبها.

أفضل عتاد، أفضل نموذج. يستخدم NanoClaw بشكل أصلي Claude Code عبر حزمة Claude Agent SDK الرسمية من Anthropic، لذا تحصل على أحدث نماذج Claude ومجموعة أدوات Claude Code الكاملة، بما في ذلك القدرة على تعديل وتوسيع fork الخاص بك من NanoClaw. المزوّدون الآخرون قابلون للإضافة كخيار: /add-codex لـ OpenAI's Codex (اشتراك ChatGPT أو مفتاح API)، /add-opencode لـ OpenRouter، Google، DeepSeek والمزيد عبر OpenCode، و /add-ollama-provider للنماذج مفتوحة الوزن المحلية. المزوّد قابل للتكوين لكل مجموعة عوامل.

ما يدعمه

المراسلة عبر قنوات متعددة — WhatsApp، Telegram، Discord، Slack، Microsoft Teams، iMessage، Matrix، Google Chat، Webex، Linear، GitHub، WeChat، والبريد الإلكتروني عبر Resend. يُثبّت عند الطلب باستخدام مهارات /add-<channel>. شغّل واحدة أو عدة منها في نفس الوقت.
عزل مرن — اربط كل قناة بعاملها الخاص للخصوصية الكاملة، أو شارك عاملًا واحدًا عبر قنوات متعددة لذاكرة موحدة مع محادثات منفصلة، أو ادمج عدة قنوات في جلسة واحدة مشتركة لتمتد محادثة واحدة عبر العديد من الأسطح. اختر لكل قناة عبر /manage-channels. انظر docs/isolation-model.md.
مساحة عمل لكل عامل — لكل مجموعة عوامل ملف CLAUDE.md خاص بها، وذاكرة خاصة بها، وحاوية خاصة بها، وتركيباتها المسموح بها فقط. لا شيء يعبر الحدود ما لم تقم بتوصيله.
المهام المجدولة: مهام متكررة ينفذها العامل، مع بوابات سكريبت اختيارية تتجنب إيقاظه عندما لا يكون هناك عمل
الوصول إلى الويب — البحث وجلب المحتوى من الإنترنت
عزل الحاوية — العوامل محصورة في حاويات Docker (macOS/Linux/WSL2)
أمان بيانات الاعتماد — لا تمتلك العوامل مفاتيح API خام أبدًا. يتم توجيه الطلبات الصادرة عبر خزانة العوامل في OneCLI، الذي يحقن بيانات الاعتماد عند الطلب ويفرض سياسات ومعدلات حد لكل عامل.
قوالب العوامل: أنشئ عاملًا جاهزًا للتشغيل (تعليمات + أدوات MCP + مهارات، بدون أسرار) من حزمة قابلة لإعادة الاستخدام عبر ncl groups create --template <ref>. يتم تحميل القوالب من المجلد المحلي templates/؛ يمكنك ملؤه يدويًا أو بنسخه من المكتبة العامة. انظر .

الاستخدام

تحدث إلى مساعدك باستخدام كلمة التنبيه (الافتراضية: @Andy):

@Andy أرسل نظرة عامة على مسار المبيعات كل صباح يوم عمل في الساعة 9 صباحًا (لديه حق الوصول إلى مجلد Obsidian الخاص بي)
@Andy راجع تاريخ git للأسبوع الماضي كل يوم جمعة وقم بتحديث README إذا كان هناك انحراف
@Andy كل يوم اثنين في الساعة 8 صباحًا، اجمع أخبارًا عن تطورات الذكاء الاصطناعي من Hacker News وTechCrunch وأرسل لي موجزًا

من قناة تمتلكها أو تديرها، يمكنك إدارة المجموعات والمهام:

@Andy اذكر جميع المهام المجدولة عبر المجموعات
@Andy أوقف مهمة الإحاطة الصباحية ليوم الاثنين مؤقتًا
@Andy انضم إلى مجموعة Family Chat

التخصيص

NanoClaw لا يستخدم ملفات إعدادات. لإجراء تغييرات، فقط أخبر Claude Code بما تريد:

"غيّر كلمة التنبيه إلى @Bob"
"تذكر في المستقبل أن تجعل الردود أقصر وأكثر مباشرة"
"أضف تحية مخصصة عندما أقول صباح الخير"
"خزّن ملخصات المحادثات أسبوعيًا"

أو قم بتشغيل /customize لإجراء تغييرات موجهة.

قاعدة الكود صغيرة بما يكفي ليقوم Claude بتعديلها بأمان.

المساهمة

لا تضف ميزات. أضف مهارات (Skills).

إذا كنت ترغب في إضافة قناة جديدة أو مزود عوامل جديد، لا تضفه إلى الفرع الرئيسي (trunk). محولات القنوات الجديدة تُوضع على فرع channels؛ مزودو العوامل الجدد يُوضعون على providers. يقوم المستخدمون بتثبيتها في fork الخاص بهم باستخدام مهارات /add-<name>، التي تنسخ الوحدة (الوحدات) ذات الصلة إلى المسارات القياسية، وتُسجّل التوصيلات، وتثبّت التبعيات.

هذا يحافظ على trunk كسجل وبنية تحتية نقية، ويبقى كل fork خفيفًا — يحصل المستخدمون على القنوات والمزودين الذين طلبوهم فقط ولا شيء غير ذلك.

RFS (طلب المهارات)

لا توجد حاليًا مهارات قنوات أو مزودين مطلوبة — اقترح واحدة عبر issue.

المتطلبات

macOS أو Linux (Windows عبر WSL2)
Node.js 20+ و pnpm 10+ (سيقوم المثبّت بتثبيتهما إذا كانا مفقودين)
Docker Desktop (macOS/Windows) أو Docker Engine (Linux)
Claude Code لـ /customize و /debug واسترداد الأخطاء أثناء الإعداد وجميع مهارات /add-<channel>

البنية المعمارية

تطبيقات المراسلة → العملية المضيفة (الموجه) → inbound.db → الحاوية (Bun، Claude Agent SDK) → outbound.db → العملية المضيفة (التوصيل) → تطبيقات المراسلة

عقدة مضيفة واحدة (Node) تنسق حاويات العوامل لكل جلسة. عندما تصل رسالة، يقوم المضيف بتوجيهها عبر نموذج الكيان (المستخدم → مجموعة المراسلة → مجموعة العوامل → الجلسة)، ويكتبها في inbound.db الخاصة بالجلسة، ويوقظ الحاوية. يقوم مشغل العامل داخل الحاوية باستقصاء inbound.db، ويشغّل العامل، ويكتب الردود إلى outbound.db. يقوم المضيف باستقصاء outbound.db ويوصل الرد عبر محول القناة.

ملفا SQLite لكل جلسة، لكل منهما كاتب واحد بالضبط — لا تنازع على نقاط التحميل، لا IPC، لا توصيل stdin. القنوات والمزوّدون البديلون يسجّلون أنفسهم عند بدء التشغيل؛ الفرع الرئيسي يوفّر السجل وجسر Chat SDK، بينما تُثبّت المحولات نفسها كمهارات لكل fork.

للحصول على الشرح الكامل للبنية المعمارية، انظر docs/architecture.md; لنموذج العزل ثلاثي المستويات، انظر docs/isolation-model.md.

الملفات الرئيسية:

src/index.ts — نقطة الدخول: تهيئة قاعدة البيانات، محولات القنوات، استقصاءات التوصيل، الكنس
src/router.ts — التوجيه الوارد: مجموعة المراسلة → مجموعة العوامل → الجلسة → inbound.db
src/delivery.ts — استقصاء outbound.db، التوصيل عبر المحول، معالجة الإجراءات النظامية
src/host-sweep.ts — كنس كل 60 ثانية: كشف الجلسات القديمة، إيقاظ الرسائل المستحقة، التكرار
src/session-manager.ts — حل الجلسات، فتح inbound.db / outbound.db
src/container-runner.ts — تشغيل حاويات لكل مجموعة عوامل، حقن بيانات اعتماد OneCLI
src/db/ — قاعدة البيانات المركزية (المستخدمون، الأدوار، مجموعات العوامل، مجموعات المراسلة، التوصيلات، الترحيلات)
src/channels/ — بنية محولات القنوات (المحولات تُثبّت عبر مهارات )

الأسئلة الشائعة

لماذا Docker؟

يوفر Docker دعمًا عبر المنصات (macOS و Linux و Windows عبر WSL2) ونظامًا بيئيًا ناضجًا.

هل يمكنني تشغيل هذا على Linux أو Windows؟

نعم. Docker هو وقت التشغيل الافتراضي ويعمل على macOS و Linux و Windows (عبر WSL2). فقط شغّل bash nanoclaw.sh.

هل هذا آمن؟

تعمل العوامل داخل حاويات، وليس خلف فحوصات أذونات على مستوى التطبيق. يمكنها فقط الوصول إلى الأدلة المثبّتة صراحةً. لا تدخل بيانات الاعتماد إلى الحاوية أبدًا — يتم توجيه طلبات API الصادرة عبر خزانة العوامل في OneCLI، الذي يحقن المصادقة على مستوى الوكيل ويدعم معدلات الحد وسياسات الوصول. لا يزال يتعين عليك مراجعة ما تقوم بتشغيله، لكن قاعدة الكود صغيرة بما يكفي لتتمكن بالفعل من ذلك. انظر وثائق الأمان للحصول على نموذج الأمان الكامل.

لماذا لا توجد ملفات إعدادات؟

نحن لا نريد فوضى الإعدادات. يجب على كل مستخدم تخصيص NanoClaw بحيث يفعل الكود بالضبط ما يريده، بدلاً من تكوين نظام عام. إذا كنت تفضل وجود ملفات إعدادات، يمكنك إخبار Claude بإضافتها.

هل يمكنني استخدام نماذج الطرف الثالث أو مفتوحة المصدر؟

نعم. المسار المدعوم هو /add-opencode (OpenRouter، OpenAI، Google، DeepSeek، والمزيد عبر تكوين OpenCode) أو /add-ollama-provider (النماذج المحلية مفتوحة الوزن عبر Ollama). كلاهما قابل للتكوين لكل مجموعة عوامل، لذا يمكن لعوامل مختلفة العمل على خلفيات مختلفة في نفس التثبيت.

للتجارب الفردية، أي نقطة نهاية متوافقة مع Claude API تعمل أيضًا عبر .env:

ANTHROPIC_BASE_URL=https://your-api-endpoint.com
ANTHROPIC_AUTH_TOKEN=your-token-here

كيف يمكنني تصحيح الأخطاء؟

اسأل Claude Code. "لماذا لا يعمل المجدول؟" "ما موجود في السجلات الأخيرة؟" "لماذا لم تحصل هذه الرسالة على رد؟" هذا هو النهج الأصلي للذكاء الاصطناعي الذي يقوم عليه NanoClaw.

لماذا لا يعمل الإعداد معي؟

إذا فشلت إحدى الخطوات، يقوم nanoclaw.sh بتسليم المهمة إلى Claude Code لتشخيص المشكلة واستئناف العمل. إذا لم يحل ذلك المشكلة، شغّل claude ثم /debug. إذا حدد Claude مشكلة من المحتمل أن تؤثر على مستخدمين آخرين، افتح PR ضد خطوة الإعداد أو المهارة ذات الصلة.

كيف يمكنني إلغاء تثبيت NanoClaw؟

bash nanoclaw.sh --uninstall

كل تثبيت مُوسوم بمعرف خاص بكل نسخة، لذا يزيل برنامج الإزالة فقط ما ينتمي إلى تلك النسخة: الخدمة الخلفية، الحاويات والصورة، بيانات التطبيق والسجلات، ملفات العوامل الخاصة بك، وعوامل خزانة OneCLI لهذه النسخة. الأشياء المشتركة — تطبيق OneCLi وبيانات اعتمادك، ونسخ NanoClaw الأخرى على الجهاز — تُترك كما هي. يعرض بالضبط ما وجده ويطلب التأكيد لكل مجموعة؛ لا يتم حذف شيء حتى تقول نعم. استخدم --dry-run للمعاينة دون تغيير أي شيء، أو --yes لتخطي المطالبات. يتم عمل نسخة احتياطية من .env الخاص بك قبل الإزالة. للإنهاء، احذف مجلد النسخة (checkout) نفسه.

ما هي التغييرات التي سيتم قبولها في قاعدة الكود؟

سيتم قبول إصلاحات الأمان فقط، وإصلاحات الأخطاء، والتحسينات الواضحة في التكوين الأساسي. هذا كل شيء.

كل شيء آخر (قدرات جديدة، توافق مع أنظمة تشغيل، دعم أجهزة، تحسينات) يجب أن يُساهم به كمهارات: كود القنوات والمزوّدين على فروع السجل channels/providers، وكل شيء آخر كمهارة مستقلة بذاتها. انظر docs/customizing.md و CONTRIBUTING.md.

هذا يحافظ على النظام الأساسي في حده الأدنى ويسمح لكل مستخدم بتخصيص تثبيته دون وراثة ميزات لا يريدها.

المجتمع

أسئلة؟ أفكار؟ انضم إلى Discord.

سجل التغييرات

انظر CHANGELOG.md للتغييرات الجذرية، أو سجل الإصدارات الكامل على موقع الوثائق.

الترخيص

MIT

nanoclaw

الأكثر شعبية