Guides

مرجع إعداد CLI

تغطي هذه الصفحة سلوك الإعداد الأولي خطوة بخطوة، ومخرجاته، وتفاصيله الداخلية. للاطلاع على شرح تفصيلي، راجع الإعداد الأولي (CLI). وللاطلاع على المرجع الكامل لعلامات CLI (كل --flag، وأمثلة الوضع غير التفاعلي، والأوامر الخاصة بموفري الخدمات)، راجع openclaw onboard.

ما الذي يفعله المعالج

يرشدك الوضع المحلي (الافتراضي) خلال:

إعداد النموذج والمصادقة (Anthropic، وOAuth لاشتراك OpenAI Code، وxAI، وOpenCode، ونقاط النهاية المخصصة، والمزيد من تدفقات المصادقة التي يملكها موفرو الخدمات)
موقع مساحة العمل وملفات التمهيد
إعدادات Gateway (المنفذ، والربط، والمصادقة، وTailscale)
القنوات وموفرو الخدمات (Discord، وFeishu، وGoogle Chat، وiMessage، وMattermost، وMicrosoft Teams، وQQ Bot، وSignal، وSlack، وTelegram، وWhatsApp، وغيرها من القنوات المضمّنة أو قنوات Plugin)
موفر بحث الويب (اختياري)
تثبيت الخدمة الخفية (LaunchAgent، أو وحدة مستخدم systemd، أو مهمة Windows مجدولة أصلية مع الرجوع إلى مجلد Startup)
فحص السلامة
إعداد Skills

يهيئ الوضع البعيد هذا الجهاز للاتصال بـ Gateway موجود في مكان آخر. وهو لا يثبّت أو يعدّل أي شيء على المضيف البعيد.

تفاصيل التدفق المحلي

اكتشاف الإعدادات الحالية

إذا كان ~/.openclaw/openclaw.json موجودًا، فاختر الاحتفاظ بالقيم الحالية، أو المراجعة والتحديث، أو إعادة الضبط قبل الإعداد.
لا تؤدي إعادة تشغيل المعالج إلى مسح أي شيء ما لم تختر إعادة الضبط صراحةً (أو تمرر --reset).
تكون قيمة CLI ‏--reset الافتراضية هي config+creds+sessions؛ استخدم --reset-scope full لإزالة مساحة العمل أيضًا.
إذا كانت الإعدادات غير صالحة أو تحتوي على مفاتيح قديمة، يتوقف المعالج ويطلب تشغيل openclaw doctor قبل المتابعة.
تنقل إعادة الضبط الحالة إلى سلة المهملات (ولا تحذفها مباشرةً أبدًا)، وتوفر النطاقات التالية:
- الإعدادات فقط
- الإعدادات + بيانات الاعتماد + الجلسات
- إعادة ضبط كاملة (تزيل مساحة العمل أيضًا)

النموذج والمصادقة

توجد مصفوفة الخيارات الكاملة في خيارات المصادقة والنموذج.

مساحة العمل

القيمة الافتراضية ~/.openclaw/workspace (قابلة للتهيئة).
ينشئ ملفات مساحة العمل اللازمة لتمهيد التشغيل الأول.
تخطيط مساحة العمل: مساحة عمل الوكيل.

Gateway

يطلب المنفذ، والربط، ووضع المصادقة، وإتاحة الوصول عبر Tailscale.
موصى به: أبقِ مصادقة الرمز المميز مفعّلة حتى مع الاسترجاع الحلقي، لكي تُلزم عملاء WS المحليين بالمصادقة.
في وضع الرمز المميز، يتيح الإعداد التفاعلي:
- إنشاء/تخزين رمز مميز بنص صريح (الافتراضي)
- استخدام SecretRef (اشتراك اختياري)
في وضع كلمة المرور، يدعم الإعداد التفاعلي أيضًا التخزين بنص صريح أو باستخدام SecretRef.
مسار SecretRef للرمز المميز في الوضع غير التفاعلي: --gateway-token-ref-env <ENV_VAR>.
- يتطلب متغير بيئة غير فارغ في بيئة عملية الإعداد الأولي.
- لا يمكن دمجه مع --gateway-token.
عطّل المصادقة فقط إذا كنت تثق تمامًا بكل عملية محلية.
لا تزال عمليات الربط غير الحلقية تتطلب المصادقة.

القنوات

WhatsApp: تسجيل دخول اختياري عبر رمز QR
Telegram: رمز البوت المميز
Discord: رمز البوت المميز
Google Chat: ملف JSON لحساب الخدمة + جمهور Webhook
Mattermost: رمز البوت المميز + عنوان URL الأساسي
Signal: تثبيت اختياري لـ signal-cli + إعدادات الحساب
iMessage: مسار CLI ‏imsg + الوصول إلى قاعدة بيانات Messages؛ استخدم مغلف SSH عندما يعمل Gateway خارج جهاز Mac
أمان الرسائل المباشرة: الإعداد الافتراضي هو الاقتران. ترسل أول رسالة مباشرة رمزًا؛ وافق عليه عبر openclaw pairing approve <channel> <code> أو استخدم قوائم السماح.

بحث الويب

اختر موفرًا (Brave، أو DuckDuckGo، أو Exa، أو Firecrawl، أو Gemini، أو Grok، أو Kimi، أو MiniMax Search، أو Ollama Web Search، أو Perplexity، أو SearXNG، أو Tavily) أو تخطَّ هذه الخطوة.
تخطَّ هذه الخطوة باستخدام --skip-search؛ وأعد تهيئتها لاحقًا باستخدام openclaw configure --section web.

تثبيت الخدمة الخفية

macOS: ‏LaunchAgent
- يتطلب جلسة مستخدم مسجل الدخول؛ وللتشغيل دون واجهة، استخدم LaunchDaemon مخصصًا (غير مضمّن).
Linux وWindows عبر WSL2: وحدة مستخدم systemd
- يحاول المعالج تنفيذ loginctl enable-linger <user> لكي يظل Gateway قيد التشغيل بعد تسجيل الخروج.
- قد يطلب sudo (يكتب إلى /var/lib/systemd/linger)؛ ويحاول أولًا دون sudo.
Windows الأصلي: المهمة المجدولة أولًا
- إذا رُفض إنشاء المهمة، يرجع OpenClaw إلى عنصر تسجيل دخول لكل مستخدم في مجلد Startup ويبدأ Gateway فورًا.
- تظل المهام المجدولة مفضلة لأنها توفر حالة أفضل للمشرف.
اختيار بيئة التشغيل: يلزم Node لأن مخزن حالة التشغيل الأساسي في OpenClaw يستخدم node:sqlite.

فحص السلامة

يبدأ Gateway (عند الحاجة) ويشغّل openclaw health.
openclaw status --deep يضيف فحص سلامة Gateway المباشر إلى مخرجات الحالة، بما في ذلك فحوصات القنوات عند دعمها.

Skills

يقرأ Skills المتاحة ويتحقق من المتطلبات.
يتيح اختيار مدير Node: ‏npm، أو pnpm، أو bun.
يثبّت التبعيات الاختيارية لـ Skills المضمّنة الموثوقة عندما يكون برنامج التثبيت المطلوب متاحًا.
يتخطى برامج تثبيت Homebrew وuv وGo غير المتاحة، ثم يجمع Skills المتأثرة مع إرشادات الإعداد اليدوي. شغّل openclaw doctor بعد تثبيت المتطلبات الأساسية المفقودة.

الإنهاء

ملخص وخطوات تالية، بما في ذلك خيارات تطبيقات iOS وAndroid وmacOS.

تفاصيل الوضع البعيد

يهيئ الوضع البعيد هذا الجهاز للاتصال بـ Gateway موجود في مكان آخر. وهو لا يثبّت أو يعدّل أي شيء على المضيف البعيد.

ما تضبطه:

عنوان URL لـ Gateway البعيد (ws://... أو wss://...)
رمز مميز، أو كلمة مرور، أو دون مصادقة، بما يطابق إعدادات Gateway البعيد

الاكتشاف (اختياري)

إذا كان dns-sd ‏(macOS) أو avahi-browse ‏(Linux) متاحًا، يتيح الإعداد الأولي البحث عن إشارات Gateway عبر Bonjour/mDNS قبل الرجوع إلى إدخال عنوان URL يدويًا. كما تُجرَّب خدمة اكتشاف DNS-SD واسعة النطاق عند تهيئتها. الوثائق: اكتشاف Gateway، Bonjour.

طريقة الاتصال

عند تحديد إشارة، اختر WebSocket مباشرًا أو نفق SSH:

مباشر: يتصل عبر wss:// ويطلب الوثوق ببصمة TLS المكتشفة (تثبيت الثقة عند أول استخدام؛ لا تُثبّت إلا إذا وافقت).
نفق SSH: يطبع أمر ssh -N -L 18789:127.0.0.1:18789 <user>@<host> لتشغيله أولًا، ثم يتصل بنقطة نهاية النفق المحلية.

المصادقة

اختر الرمز المميز (موصى به)، أو كلمة المرور، أو عدم استخدام المصادقة، ثم يمكنك اختياريًا تخزينه بصفته SecretRef بدلًا من النص الصريح.

خيارات المصادقة والنموذج

إذا فشلت خطوة إعداد موفر خدمة أثناء الإعداد الأولي التفاعلي (مثل خيار إعادة استخدام CLI من دون تسجيل دخول محلي)، يعرض المعالج الخطأ ويعود إلى منتقي موفر الخدمة بدلًا من الخروج. وتظل عمليات تشغيل --auth-choice الصريحة تفشل سريعًا لأغراض الأتمتة.

مفتاح Anthropic API

يستخدم ANTHROPIC_API_KEY إذا كان موجودًا، أو يطلب مفتاحًا، ثم يحفظه لاستخدام الخدمة الخفية.

Anthropic Claude CLI

المسار المحلي المفضل في الإعداد الأولي/التهيئة التفاعلية؛ يعيد استخدام تسجيل دخول Claude CLI حالي عند توفره.

اشتراك OpenAI Code ‏(OAuth)

تدفق عبر المتصفح؛ الصق code#state.

في إعداد جديد دون نموذج أساسي، يضبط agents.defaults.model على openai/gpt-5.6-sol عبر بيئة تشغيل Codex.

اشتراك OpenAI Code (اقتران الجهاز)

تدفق اقتران عبر المتصفح باستخدام رمز جهاز قصير الأجل.

في إعداد جديد دون نموذج أساسي، يضبط agents.defaults.model على openai/gpt-5.6-sol عبر بيئة تشغيل Codex.

مفتاح OpenAI API

يستخدم OPENAI_API_KEY إذا كان موجودًا، أو يطلب مفتاحًا، ثم يخزّن بيانات الاعتماد في ملفات تعريف المصادقة.

في إعداد جديد دون نموذج أساسي، يضبط agents.defaults.model على openai/gpt-5.6؛ ويُحل معرّف نموذج API المباشر المجرد إلى فئة Sol.

تحافظ إضافة OpenAI أو إعادة مصادقته على نموذج أساسي صريح حالي، بما في ذلك openai/gpt-5.5. إذا كان الحساب لا يتيح GPT-5.6، فحدد openai/gpt-5.5 صراحةً؛ ولا يخفض OpenClaw إصداره ضمنيًا.

xAI (Grok) OAuth

تسجيل الدخول عبر المتصفح للحسابات المؤهلة في SuperGrok أو X Premium. هذا هو مسار xAI الموصى به لمعظم المستخدمين. يخزّن OpenClaw ملف تعريف المصادقة الناتج لنماذج Grok وGrok web_search وx_search وcode_execution.

رمز جهاز xAI (Grok)

تسجيل دخول عبر المتصفح ملائم للاتصال عن بُعد باستخدام رمز قصير بدلًا من استدعاء رجوع إلى localhost. استخدمه من مضيفات SSH أو Docker أو VPS.

مفتاح API لـ xAI (Grok)

يطلب XAI_API_KEY ويضبط xAI بوصفه موفّر نماذج. استخدم هذا عندما تريد مفتاح API من xAI Console بدلًا من OAuth الخاص بالاشتراك.

OpenCode

يطلب OPENCODE_API_KEY (أو OPENCODE_ZEN_API_KEY) ويتيح لك اختيار كتالوج Zen أو Go (يغطي مفتاح API واحد كليهما). رابط الإعداد: opencode.ai/auth.

مفتاح API (عام)

يخزّن المفتاح نيابةً عنك.

Vercel AI Gateway

يطلب AI_GATEWAY_API_KEY. مزيد من التفاصيل: Vercel AI Gateway.

Cloudflare AI Gateway

يطلب معرّف الحساب ومعرّف Gateway وCLOUDFLARE_AI_GATEWAY_API_KEY. مزيد من التفاصيل: Cloudflare AI Gateway.

MiniMax

تُكتب الإعدادات تلقائيًا. القيمة الافتراضية للاستضافة هي MiniMax-M3؛ ويستخدم الإعداد بمفتاح API ‏minimax/...، بينما يستخدم إعداد OAuth ‏minimax-portal/.... مزيد من التفاصيل: MiniMax.

StepFun

تُكتب الإعدادات تلقائيًا لخدمة StepFun القياسية أو Step Plan على نقاط النهاية الصينية أو العالمية. تتضمن الخدمة القياسية حاليًا step-3.5-flash، كما تتضمن Step Plan ‏step-3.5-flash-2603. مزيد من التفاصيل: StepFun.

Synthetic (متوافق مع Anthropic)

يطلب SYNTHETIC_API_KEY. مزيد من التفاصيل: Synthetic.

Ollama (نماذج مفتوحة سحابية ومحلية)

يطلب أولًا Cloud + Local أو Cloud only أو Local only. يستخدم Cloud only ‏OLLAMA_API_KEY مع https://ollama.com. تطلب الأنماط المعتمدة على المضيف عنوان URL الأساسي (القيمة الافتراضية http://127.0.0.1:11434)، وتكتشف النماذج المتاحة، وتقترح القيم الافتراضية. يتحقق Cloud + Local أيضًا مما إذا كان مضيف Ollama هذا مسجّل الدخول للوصول السحابي. مزيد من التفاصيل: Ollama.

Moonshot وKimi Coding

تُكتب إعدادات Moonshot ‏(Kimi K2) وKimi Coding تلقائيًا. مزيد من التفاصيل: Moonshot AI ‏(Kimi وKimi Coding).

موفّر مخصص

يعمل مع نقاط نهاية متوافقة مع OpenAI ومتوافقة مع OpenAI Responses ومتوافقة مع Anthropic.

يدعم الإعداد التفاعلي خيارات تخزين مفتاح API نفسها التي تدعمها تدفقات مفاتيح API للموفّرين الآخرين:

لصق مفتاح API الآن (نص صريح)
استخدام مرجع سرّي (مرجع متغير بيئة أو مرجع موفّر مضبوط، مع تحقق مسبق)

يستنتج الإعداد دعم الصور لمعرّفات نماذج الرؤية الشائعة (GPT-4o/4.1/5.x وClaude 3/4 وGemini وQwen-VL وLLaVA وPixtral وما شابهها)، ولا يسأل إلا عندما يكون اسم النموذج غير معروف.

علامات الوضع غير التفاعلي:

--auth-choice custom-api-key
--custom-base-url
--custom-model-id
--custom-api-key (اختياري؛ يعود إلى CUSTOM_API_KEY)
--custom-provider-id (اختياري)
--custom-compatibility <openai|openai-responses|anthropic> (اختياري؛ القيمة الافتراضية openai)
--custom-image-input / --custom-text-input (اختياري؛ يتجاوز قدرة إدخال النموذج المستنتجة)

تخطي

يترك المصادقة دون ضبط.

سلوك النموذج:

اختر النموذج الافتراضي من الخيارات المكتشفة، أو أدخل الموفّر والنموذج يدويًا.
عندما يبدأ الإعداد من خيار مصادقة موفّر، يمنح منتقي النماذج الأفضلية لذلك الموفّر تلقائيًا. وبالنسبة إلى Volcengine وBytePlus، تطابق الأفضلية نفسها أيضًا متغيرات خطط البرمجة الخاصة بهما (volcengine-plan/* وbyteplus-plan/*).
إذا كان مرشح الموفّر المفضّل سيُرجع قائمة فارغة، يعود المنتقي إلى الكتالوج الكامل بدلًا من عدم عرض أي نماذج.
يشغّل المعالج فحصًا للنموذج ويحذّر إذا كان النموذج المضبوط غير معروف أو كانت مصادقته مفقودة.

مسارات بيانات الاعتماد وملفات التعريف:

ملفات تعريف المصادقة (مفاتيح API وOAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
استيراد OAuth القديم: ~/.openclaw/credentials/oauth.json

وضع تخزين بيانات الاعتماد:

يحفظ سلوك الإعداد الافتراضي مفاتيح API كقيم نصية صريحة في ملفات تعريف المصادقة.
يُفعّل --secret-input-mode ref وضع المراجع بدلًا من تخزين المفتاح كنص صريح. في الإعداد التفاعلي، يمكنك اختيار أحد الخيارين:
- مرجع متغير بيئة (مثل keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
- مرجع موفّر مضبوط (file أو exec) مع الاسم المستعار للموفّر ومعرّفه
يشغّل وضع المراجع التفاعلي تحققًا مسبقًا سريعًا قبل الحفظ.
- مراجع متغيرات البيئة: يتحقق من اسم المتغير ومن وجود قيمة غير فارغة في بيئة الإعداد الحالية.
- مراجع الموفّرين: يتحقق من إعدادات الموفّر ويحلّ المعرّف المطلوب.
- إذا فشل التحقق المسبق، يعرض الإعداد الخطأ ويتيح لك إعادة المحاولة.
في الوضع غير التفاعلي، لا يعتمد --secret-input-mode ref إلا على متغيرات البيئة.
- عيّن متغير بيئة الموفّر في بيئة عملية الإعداد.
- تتطلب علامات المفاتيح المضمّنة (مثل --openai-api-key) تعيين متغير البيئة ذاك؛ وإلا يفشل الإعداد فورًا.
- بالنسبة إلى الموفّرين المخصصين، يخزّن وضع ref غير التفاعلي القيمة models.providers.<id>.apiKey بوصفها { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
- في حالة الموفّر المخصص هذه، يتطلب --custom-api-key تعيين CUSTOM_API_KEY؛ وإلا يفشل الإعداد فورًا.
تدعم بيانات اعتماد مصادقة Gateway خياري النص الصريح وSecretRef في الإعداد التفاعلي:
- وضع الرمز المميز: إنشاء/تخزين رمز مميز كنص صريح (افتراضي) أو استخدام SecretRef.
- وضع كلمة المرور: نص صريح أو SecretRef.
مسار SecretRef للرمز المميز في الوضع غير التفاعلي: --gateway-token-ref-env <ENV_VAR>.
تستمر الإعدادات الحالية ذات النص الصريح في العمل دون تغيير.

المخرجات والتفاصيل الداخلية

الحقول المعتادة في ~/.openclaw/openclaw.json:

agents.defaults.workspace
agents.defaults.skipBootstrap عند تمرير --skip-bootstrap
agents.defaults.model / models.providers (إذا اختير Minimax)
tools.profile (يعتمد الإعداد المحلي القيمة الافتراضية "coding" عند عدم تعيينها؛ وتُحفظ القيم الصريحة الحالية)
gateway.* (الوضع، الربط، المصادقة، Tailscale)
session.dmScope (يعتمد الإعداد المحلي القيمة الافتراضية per-channel-peer لهذا الحقل عند عدم تعيينه؛ وتُحفظ القيم الصريحة الحالية)
channels.telegram.botToken، channels.discord.token، channels.matrix.*، channels.signal.*، channels.imessage.*
قوائم السماح للقنوات (Discord وiMessage وSignal وSlack وTelegram وWhatsApp) عند الاشتراك فيها أثناء المطالبات؛ ويحوّل Discord وSlack أيضًا الأسماء المُدخلة إلى معرّفات
skills.install.nodeManager
- تقبل العلامة setup --node-manager ‏npm أو pnpm أو bun.
- لا يزال من الممكن ضبط skills.install.nodeManager: "yarn" لاحقًا يدويًا في الإعدادات.
wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode
wizard.securityAcknowledgedAt

يكتب openclaw agents add ‏agents.list[] وbindings الاختياري.

تُخزّن بيانات اعتماد WhatsApp ضمن ~/.openclaw/credentials/whatsapp/<accountId>/. تُخزّن الجلسات النشطة والنصوص المفرّغة في ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. ويُستخدم دليل ~/.openclaw/agents/<agentId>/sessions/ لمدخلات الترحيل القديمة وعناصر الأرشفة/الدعم.

الإعداد غير التفاعلي

يتطلب --non-interactive ‏--accept-risk (إقرارًا بأن الوكلاء أقوياء وأن الوصول الكامل إلى النظام ينطوي على مخاطر):

bash

openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

مرجع العلامات الكامل وأمثلة خاصة بالموفّرين: openclaw onboard، أتمتة CLI.

RPC لمعالج Gateway

wizard.start
wizard.next
wizard.cancel
wizard.status

يمكن للعملاء (تطبيق macOS وواجهة Control UI) عرض الخطوات دون إعادة تنفيذ منطق الإعداد.

سلوك إعداد Signal

ينزّل أصل الإصدار المناسب من إصدارات GitHub الرسمية لـ signal-cli (بنية أصلية، لنظام Linux ‏x86-64 فقط)
على الأنظمة الأساسية الأخرى (macOS وLinux غير x64)، يثبّت عبر Homebrew بدلًا من ذلك
يخزّن تثبيت أصل الإصدار ضمن ~/.openclaw/tools/signal-cli/<version>/
يكتب channels.signal.cliPath في الإعدادات
نظام Windows الأصلي غير مدعوم بعد؛ شغّل الإعداد داخل WSL2 للحصول على مسار تثبيت Linux

مستندات ذات صلة

مركز الإعداد: الإعداد (CLI)
الأتمتة والبرامج النصية: أتمتة CLI
مرجع الأوامر: openclaw onboard

Was this useful?