> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# NanoClaw

> انشر NanoClaw، مساعد ذكاء اصطناعي شخصي خفيف لـ WhatsApp وTelegram، على Venice للحصول على دردشة وتوليد وسائط خاصة وغير مُقيَّدة.

[NanoClaw](https://github.com/qwibitai/nanoclaw) هو مساعد ذكاء اصطناعي خفيف الوزن ومستضاف ذاتيًا يعمل على WhatsApp وTelegram. يضيف هذا التفرّع دعم Venice AI ليعمل كل شيء بخصوصية تامة دون الحاجة إلى اشتراك Anthropic.

<CardGroup cols={3}>
  <Card title="ادفع لكل توكن" icon="coins">
    لا اشتراك. ادفع فقط مقابل ما تستخدمه
  </Card>

  <Card title="استدلال خاص" icon="shield-halved">
    عدم الاحتفاظ بأي بيانات على خوادم Venice
  </Card>

  <Card title="عزل Docker" icon="cube">
    كل محادثة تعمل في حاوية آمنة خاصة بها
  </Card>
</CardGroup>

***

## لماذا Venice AI؟

[Venice](https://venice.ai) منصة ذكاء اصطناعي تضع الخصوصية أولًا. وهم [لا يخزّنون أو يسجّلون أي طلبات أو ردود](https://venice.ai/privacy) على خوادمهم — محادثاتك موجودة فقط على جهازك. تُشفَّر الطلبات من طرف إلى طرف عبر وكيلهم إلى مزوّدي GPU اللامركزيين، مع عدم الاحتفاظ بأي بيانات. هذا يعني أن محادثات مساعد الذكاء الاصطناعي الخاص بك تبقى خاصة، حتى من Venice أنفسهم.

تتيح Venice وصولًا مجهول الهوية إلى النماذج المتطورة (Claude Opus، Claude Sonnet) ووصولًا خاصًا بالكامل إلى النماذج مفتوحة المصدر (GLM، Qwen) عبر واجهة API واحدة — بدّل بينها متى شئت.

|                                  | **Venice AI**                                                                                     | **مزوّدو الذكاء الاصطناعي التقليديون**                 |
| -------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **الاحتفاظ بالبيانات**           | لا شيء — صفر سجلات                                                                                | نعم                                                    |
| **خصوصية الطلبات**               | مشفّرة، ولا تُخزَّن أبدًا                                                                         | تُخزَّن على خوادم المزوّد                              |
| **النماذج مفتوحة المصدر**        | نعم (GLM وQwen وغيرها)                                                                            | لا                                                     |
| **النماذج المتطورة**             | Claude وGPT وغيرها — بشكل مجهول الهوية                                                            | فقط عبر الاشتراكات المباشرة                            |
| **التسعير**                      | الدفع لكل توكن، بدون اشتراك. أو ضع [DIEM](https://venice.ai/lp/diem) للحصول على رصيد يتجدد يوميًا | اشتراكات بقيمة 20-200 دولار/شهر أو API بالدفع لكل توكن |
| **الاستدلال غير الخاضع للرقابة** | نعم (النماذج مفتوحة المصدر)                                                                       | لا                                                     |

***

## لماذا NanoClaw؟

NanoClaw بديل نظيف وبسيط للمنصات الأكبر مثل OpenClaw. مصمّم لشخص واحد يدير بوتًا واحدًا.

|                            | **NanoClaw (Venice)**                                | **OpenClaw**                              |
| -------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| **الشيفرة**                | \~2000 سطر، عدد قليل من الملفات                      | \~500,000 سطر، 53 ملف إعداد               |
| **التبعيات**               | \~15 حزمة                                            | أكثر من 70 حزمة                           |
| **نموذج الأمان**           | عزل حاوية Docker على مستوى نظام التشغيل              | قوائم سماح وأكواد إقران على مستوى التطبيق |
| **العزل لكل مجموعة**       | كل مجموعة تحصل على حاوية ونظام ملفات وذاكرة خاصة بها | عملية مشتركة وذاكرة مشتركة                |
| **الإعداد**                | معالج واحد (`/setup`)، نحو 10 دقائق                  | إعداد يدوي متعدد الخطوات                  |
| **مزوّد الذكاء الاصطناعي** | Venice AI (خاص، بدون اشتراك)                         | Anthropic (يتطلب مفتاح API أو اشتراكًا)   |
| **التخصيص**                | عدّل الشيفرة مباشرة — صغيرة بما يكفي لقراءتها        | ملفات إعداد وملحقات                       |
| **المستخدم المستهدف**      | شخص واحد، بوت واحد                                   | منصة متعددة المستخدمين                    |

***

## ما الذي ستحصل عليه

* مساعد ذكاء اصطناعي شخصي على **Telegram** و/أو **WhatsApp**
* مدعوم بـ **Venice AI** — لا حاجة لحساب Anthropic
* البوت يعمل في **حاوية Docker معزولة** (سندبوكس، لا يستطيع الوصول إلى نظامك)
* **تبديل النماذج** — أخبر البوت "switch to zai-org-glm-5" أو "use opus" في أي وقت
* **مهام مجدولة** — ضع تذكيرات ومهام متكررة
* **بحث وتصفّح ويب** مدمج
* **تنسيق Markdown** في رسائل Telegram

***

## المتطلبات المسبقة

<CardGroup cols={2}>
  <Card title="Node.js 20+" icon="node-js" href="https://nodejs.org/">
    تحقّق باستخدام `node --version`
  </Card>

  <Card title="Docker" icon="docker" href="https://docker.com/products/docker-desktop">
    قم بتثبيته وفتحه مرة واحدة ليعمل
  </Card>

  <Card title="Claude Code CLI" icon="terminal" href="https://claude.ai/download">
    تحقّق باستخدام `claude --version`
  </Card>

  <Card title="مفتاح Venice API" icon="key" href="https://venice.ai/settings/api">
    أنشئه من حسابك في Venice
  </Card>
</CardGroup>

**لـ Telegram** (موصى به للمستخدمين الجدد):

1. افتح Telegram وابحث عن **@BotFather**
2. أرسل `/newbot` واتبع التعليمات
3. احفظ التوكن الذي يعطيه لك BotFather (يبدو مثل `123456789:ABCdef...`)

<Warning>
  **لـ WhatsApp — استخدم رقمًا افتراضيًا، وليس رقمك الشخصي:**

  يتصل NanoClaw كجهاز مرتبط بحساب WhatsApp الخاص بك. هذا يعني أن **الوكيل يمكنه رؤية كل رسالة واردة وصادرة** — جميع محادثاتك الشخصية، والمحادثات الجماعية، والصور، وكل شيء. هاتفك سيستمر بالعمل بشكل طبيعي، لكن البوت سيكون لديه رؤية كاملة لكامل حساب WhatsApp الخاص بك.

  **استخدم رقم هاتف افتراضي بدلًا من ذلك.** توفّر هذه التطبيقات رقمًا ثانيًا يمكنك تخصيصه بالكامل للبوت:

  | التطبيق                                  | السعر         | ملاحظات                                                             |
  | ---------------------------------------- | ------------- | ------------------------------------------------------------------- |
  | [Hushed](https://hushed.com)             | \~5 دولار/شهر | موثوق، يعمل جيدًا للتحقق من WhatsApp                                |
  | [Burner](https://www.burnerapp.com)      | \~5 دولار/شهر | مشابه لـ Hushed، أرقام للاستخدام المؤقت                             |
  | [Google Voice](https://voice.google.com) | مجاني         | الولايات المتحدة فقط، قد لا يعمل للتحقق من WhatsApp في جميع الحالات |

  **كيفية إعداده:**

  1. احصل على رقم افتراضي من أحد التطبيقات أعلاه
  2. ثبّت WhatsApp على جهاز ثانٍ (هاتف قديم، جهاز لوحي، أو محاكي) باستخدام ذلك الرقم الافتراضي
  3. أثناء إعداد NanoClaw، امسح رمز QR بذلك الجهاز الثاني — وليس هاتفك الشخصي
</Warning>

***

## الإعداد

يستغرق الإعداد حوالي 10 دقائق. تحتاج فقط إلى **نافذة Terminal واحدة**.

<Steps>
  <Step title="استنسخ وثبّت">
    افتح Terminal وشغّل:

    ```bash theme={"system"}
    git clone https://github.com/lorenzovenice/nanoclaw-venice.git
    cd nanoclaw-venice
    npm install
    ```

    انتظر حتى ينتهي `npm install` دون أخطاء.
  </Step>

  <Step title="شغّل Claude Code مع Venice">
    استبدل `your-key` بمفتاح Venice API الخاص بك وشغّل:

    ```bash theme={"system"}
    VENICE_API_KEY=your-key npm run venice
    ```

    يبدأ هذا وكيل Venice ويشغّل Claude Code من خلاله بأمر واحد.

    <Note>
      يستخدم Claude Code افتراضيًا **GLM 5** (`zai-org-glm-5`) للحفاظ على انخفاض تكاليف الإعداد. بعد الإعداد، اكتب `/model` داخل Claude Code للتبديل إلى `claude-sonnet-4-6` أو `claude-opus-4-6` للحصول على أفضل أداء.
    </Note>

    إذا ظهرت رسالة "Do you want to use this API key?" — اختر **Yes**.
  </Step>

  <Step title="شغّل معالج الإعداد">
    في طرفية Claude Code، اكتب:

    ```
    /setup
    ```

    يرشدك المعالج عبر:

    1. **التهيئة** — يتحقق من Node.js والتبعيات
    2. **مفتاح Venice API** — يتحقق ويحفظ مفتاحك
    3. **اختيار القناة** — اختر WhatsApp أو Telegram أو كليهما
    4. **بناء الحاوية** — يبني حاوية Docker (يستغرق بضع دقائق في المرة الأولى)
    5. **مصادقة WhatsApp** — امسح رمز QR بهاتفك (إن وُجد)
    6. **إعداد Telegram** — أرسل رسالة إلى البوت ليكتشف محادثتك
    7. **كلمة التشغيل** — البادئة التي تنشّط البوت (الافتراضية: `@Andy`)
    8. **مجلدات الربط** — اختر "No" الآن (يمكنك إضافة وصول إلى الملفات لاحقًا)
    9. **بدء الخدمات** — يبدأ كل من NanoClaw ووكيل Venice كخدمات في الخلفية

    يثبّت معالج الإعداد خدمتين في الخلفية:

    * **NanoClaw** — البوت نفسه
    * **وكيل Venice** — خادم محلي صغير (localhost:4001) يترجم بين Claude Code وVenice AI

    تبدأ كلتاهما تلقائيًا عند الإقلاع وتعيد تشغيل نفسها في حال تعطّلها.

    <Note>
      إذا توقف المعالج بين الخطوات، اكتب "continue" أو "next step" لدفعه للأمام.
    </Note>
  </Step>

  <Step title="ابدأ المحادثة">
    بمجرد اكتمال الإعداد، افتح محادثتك (Telegram أو WhatsApp) وأرسل:

    ```
    @Andy hello, are you there?
    ```

    يجب أن يردّ البوت خلال ثوانٍ. في قناتك الرئيسية، يمكنك الكتابة عاديًا دون البادئة `@Andy`.

    **يمكنك الآن إغلاق نافذة Terminal.** كل شيء يعمل كخدمات في الخلفية ويبدأ تلقائيًا عند تشغيل جهازك.
  </Step>
</Steps>

***

## كيف يعمل

هناك طبقتان في NanoClaw:

| الطبقة              | ما الذي تقوم به                                            |
| ------------------- | ---------------------------------------------------------- |
| **Claude Code CLI** | أداة إدارة للإعداد والتنقيح والتخصيص                       |
| **البوت**           | الذكاء الاصطناعي في محادثتك، يعمل داخل حاوية Docker معزولة |

لفتح Claude Code في أي وقت:

```bash theme={"system"}
cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
```

استخدمه لتشغيل `/setup` أو `/debug` أو `/customize`، أو لإجراء تغييرات على سلوك البوت.

***

## النماذج

| السياق              | النموذج الافتراضي       | كيفية التبديل                                             |
| ------------------- | ----------------------- | --------------------------------------------------------- |
| البوت (في المحادثة) | `claude-sonnet-4-6`     | أخبر البوت: "switch to opus" أو "use zai-org-glm-5"       |
| Claude Code CLI     | `zai-org-glm-5` (GLM 5) | استخدم `/model` في Claude Code أو `claude --model <name>` |

<Tip>
  يستخدم CLI افتراضيًا GLM 5 لإبقاء تكاليف الإعداد منخفضة. بعد الإعداد، بدّل إلى `claude-sonnet-4-6` أو `claude-opus-4-6` للحصول على أفضل أداء.
</Tip>

راجع [كتالوج النماذج](/models/text) لجميع نماذج Venice المتاحة.

***

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="الوكيل لا يعمل">
    يعمل وكيل Venice كخدمة في الخلفية ويعيد تشغيل نفسه تلقائيًا. إذا لم يكن يعمل:

    **macOS:**

    ```bash theme={"system"}
    # تحقّق إن كان يعمل
    launchctl list | grep venice-proxy

    # أعد تشغيله
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

    # تحقّق من السجلات
    tail -f ~/nanoclaw-venice/logs/venice-proxy.log
    ```

    **Linux:**

    ```bash theme={"system"}
    # تحقّق إن كان يعمل
    systemctl --user status nanoclaw-venice-proxy

    # أعد تشغيله
    systemctl --user restart nanoclaw-venice-proxy

    # تحقّق من السجلات
    tail -f ~/nanoclaw-venice/logs/venice-proxy.log
    ```
  </Accordion>

  <Accordion title="يُظهر Claude Code خطأ 403 أو 'Please run /login'">
    يعني هذا أن Claude Code لا يستطيع الاتصال بوكيل Venice.

    1. **تحقّق من أن الوكيل يعمل.** راجع خطوة استكشاف الأخطاء أعلاه.
    2. **تأكّد من أنك في المجلد الصحيح.** نفّذ دائمًا `cd nanoclaw-venice` أولًا.
    3. **ابدأ من جديد:** أغلق جميع الطرفيات وشغّل:
       ```bash theme={"system"}
       cd nanoclaw-venice
       ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
       ```
  </Accordion>

  <Accordion title="أخطاء النموذج ('model does not exist')">
    أعد تشغيل الوكيل والبوت:

    **macOS:**

    ```bash theme={"system"}
    # أعد تشغيل الوكيل
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

    # أعد تشغيل البوت
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw
    ```

    **Linux:**

    ```bash theme={"system"}
    # أعد تشغيل الوكيل
    systemctl --user restart nanoclaw-venice-proxy

    # أعد تشغيل البوت
    systemctl --user restart nanoclaw
    ```

    تحقّق من النماذج المتاحة في [كتالوج النماذج](/models/text).
  </Accordion>

  <Accordion title="البوت لا يردّ على الرسائل">
    اتبع هذه الخطوات بالترتيب:

    1. **تحقّق من كلمة التشغيل.** تأكّد من استخدامك للبادئة الصحيحة (مثل `@Andy hello`).
    2. **تحقّق من أن Docker يعمل.** نفّذ `docker info` — إذا حدث خطأ، افتح Docker Desktop.
    3. **تحقّق من أن الوكيل يعمل.** راجع "الوكيل لا يعمل" أعلاه.
    4. **تحقّق من السجلات:** `tail -f logs/nanoclaw.log` في مجلد المشروع.
    5. **تحقّق من سجلات الحاوية.** افتح مجلد `nanoclaw-venice/groups/main/logs/`. افتح الملف الأحدث الذي يبدأ بـ `container-`.
    6. **أعد تشغيل كل شيء:** أعد تشغيل كل من الوكيل والبوت (راجع أعلاه).
  </Accordion>

  <Accordion title="بناء الحاوية يفشل أثناء الإعداد">
    تأكّد من أن Docker Desktop مفتوح ويعمل. انتظر 10 ثوانٍ ليبدأ Docker بالكامل، ثم اكتب `continue` في المعالج لإعادة المحاولة.
  </Accordion>

  <Accordion title="انقطع اتصال WhatsApp">
    قد تنتهي صلاحية جلسة WhatsApp. لإعادة الاتصال:

    ```bash theme={"system"}
    cd nanoclaw-venice
    npm run auth
    ```

    امسح رمز QR باستخدام WhatsApp (الإعدادات → الأجهزة المرتبطة → ربط جهاز)، ثم أعد تشغيل البوت:

    * macOS: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
    * Linux: `systemctl --user restart nanoclaw`
  </Accordion>
</AccordionGroup>

***

## متقدّم

<AccordionGroup>
  <Accordion title="منح البوت وصولًا إلى ملفات على جهازك">
    افتراضيًا، يكون البوت معزولًا تمامًا عن جهازك — لا يمكنه رؤية سوى ذاكرته الخاصة وسجل المحادثة.

    * **أثناء الإعداد:** عندما يُسأل عن الوصول إلى المجلدات، اختر "Yes"
    * **بعد الإعداد:** شغّل `/customize` في Claude Code
  </Accordion>

  <Accordion title="بدء/إيقاف البوت يدويًا">
    يشغّل NanoClaw خدمتين في الخلفية تبدأن تلقائيًا عند الإقلاع.

    **macOS:**

    | الإجراء            | الأمر                                                                     |
    | ------------------ | ------------------------------------------------------------------------- |
    | بدء البوت          | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist`                |
    | إيقاف البوت        | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist`              |
    | إعادة تشغيل البوت  | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`                        |
    | بدء الوكيل         | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`   |
    | إيقاف الوكيل       | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist` |
    | إعادة تشغيل الوكيل | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy`           |

    **Linux:**

    | الإجراء            | الأمر                                            |
    | ------------------ | ------------------------------------------------ |
    | بدء البوت          | `systemctl --user start nanoclaw`                |
    | إيقاف البوت        | `systemctl --user stop nanoclaw`                 |
    | إعادة تشغيل البوت  | `systemctl --user restart nanoclaw`              |
    | بدء الوكيل         | `systemctl --user start nanoclaw-venice-proxy`   |
    | إيقاف الوكيل       | `systemctl --user stop nanoclaw-venice-proxy`    |
    | إعادة تشغيل الوكيل | `systemctl --user restart nanoclaw-venice-proxy` |
  </Accordion>

  <Accordion title="استخدام Claude Code عبر Venice (بدون بوت)">
    إذا أردت فقط استخدام Claude Code مع Venice ولا تحتاج إلى WhatsApp/Telegram، يجب أن تكون خدمة الوكيل قيد التشغيل. إذا كنت قد شغّلت `/setup`، فهي قيد التشغيل أصلًا كخدمة في الخلفية.

    ```bash theme={"system"}
    cd nanoclaw-venice
    ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
    ```

    **نصيحة:** أضف هذا إلى `~/.zshrc` (أو `~/.bashrc`) لتتمكّن من تبديل أي طرفية بسرعة إلى Venice:

    ```bash theme={"system"}
    alias venice='export ANTHROPIC_BASE_URL=http://localhost:4001 && export ANTHROPIC_API_KEY=venice-proxy && echo "Using Venice API"'
    alias anthropic='unset ANTHROPIC_BASE_URL && unset ANTHROPIC_API_KEY && echo "Using Anthropic API"'
    ```

    ثم اكتب فقط `venice` في أي طرفية قبل تشغيل `claude` لاستخدام Venice، أو `anthropic` للعودة.
  </Accordion>

  <Accordion title="تشغيل عدة بوتات">
    يمكنك تشغيل عدة بوتات NanoClaw على الجهاز نفسه (مثل واحد للاستخدام الشخصي وآخر لفريق). فقط استنسخ المستودع في مجلد مختلف وشغّل الإعداد مجددًا. ملاحظة: تشترك جميعها في صورة Docker نفسها، لذا إعادة بناء واحدة تؤثر على الجميع.
  </Accordion>

  <Accordion title="أوامر المطوّرين">
    لمن يريد تعديل شيفرة NanoClaw:

    ```bash theme={"system"}
    npm run dev          # بدء الوكيل + NanoClaw مع إعادة التحميل الحارة
    npm run proxy        # بدء وكيل Venice فقط
    npm run build        # ترجمة TypeScript
    npm test             # تشغيل الاختبارات
    ./container/build.sh # إعادة بناء حاوية الوكيل
    ```
  </Accordion>
</AccordionGroup>

***

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

```
أنت (WhatsApp/Telegram)
        ↓
   NanoClaw (Node.js)
        ↓
   حاوية Docker (سندبوكس معزول)
        ↓
   وكيل Venice (localhost:4001)
        ↓
   api.venice.ai (استدلال خاص)
```

| الملف                      | الغرض                                            |
| -------------------------- | ------------------------------------------------ |
| `proxy/venice-proxy.ts`    | يترجم تنسيق Anthropic إلى تنسيق OpenAI لـ Venice |
| `src/index.ts`             | المنسّق الرئيسي — حلقة الرسائل واستدعاء الوكيل   |
| `src/channels/whatsapp.ts` | اتصال WhatsApp عبر baileys                       |
| `src/channels/telegram.ts` | بوت Telegram عبر grammy                          |
| `src/container-runner.ts`  | يطلق حاويات وكيل معزولة                          |

***

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

<AccordionGroup>
  <Accordion title="لماذا أحتاج إلى وكيل؟">
    يتحدّث Claude Agent SDK بتنسيق رسائل Anthropic. وتتحدّث Venice بتنسيق OpenAI. يترجم الوكيل بينهما حتى يعمل كل شيء دون تعديل الـ SDK.
  </Accordion>

  <Accordion title="هل يمكنني استخدام النماذج مفتوحة المصدر؟">
    نعم. تستضيف Venice العديد من النماذج. أخبر البوت "switch to zai-org-glm-5" أو أي معرّف نموذج Venice. راجع [كتالوج النماذج](/models/text).
  </Accordion>

  <Accordion title="هل هو آمن؟">
    تعمل الوكلاء في حاويات Docker مع عزل حقيقي على مستوى نظام التشغيل. يُمرَّر مفتاح Venice API عبر stdin، ولا يُكتب أبدًا على القرص داخل الحاويات. كل مجموعة تحصل على بيئة معزولة خاصة بها.
  </Accordion>

  <Accordion title="هل أحتاج إلى اشتراك Anthropic؟">
    لا. كل شيء يعمل عبر Venice AI. تحتاج فقط إلى مفتاح Venice API.
  </Accordion>

  <Accordion title="هل يمكنني استخدام هذا على خادم؟">
    نعم. يعمل على أي جهاز Linux مع Docker. استخدم خدمة systemd للبدء التلقائي عند الإقلاع.
  </Accordion>
</AccordionGroup>

***

## المصادر

<CardGroup cols={2}>
  <Card title="مستودع NanoClaw Venice" icon="github" href="https://github.com/lorenzovenice/nanoclaw-venice">
    الشيفرة المصدرية وملف README الكامل
  </Card>

  <Card title="NanoClaw الأصلي" icon="github" href="https://github.com/qwibitai/nanoclaw">
    المشروع الأصلي من qwibitai
  </Card>

  <Card title="كتالوج نماذج Venice" icon="list" href="/models/text">
    تصفّح النماذج المتاحة
  </Card>

  <Card title="خصوصية Venice" icon="shield-halved" href="/overview/privacy">
    كيف تحمي Venice بياناتك
  </Card>
</CardGroup>