# openclaw secrets

استخدم openclaw secrets لإدارة SecretRefs والحفاظ على سلامة لقطة وقت التشغيل النشطة.

أدوار الأوامر:

• reload: استدعاء Gateway RPC (secrets.reload) يعيد حل المراجع ويبدّل لقطة وقت التشغيل فقط عند النجاح الكامل (من دون كتابة إلى الإعدادات).
• audit: فحص للقراءة فقط لإعدادات التخزين/المصادقة/النماذج المولدة والبقايا القديمة بحثًا عن النصوص الصريحة، والمراجع غير المحلولة، وانحراف الأولوية (يتم تخطي مراجع exec ما لم يتم ضبط --allow-exec).
• configure: مخطط تفاعلي لإعداد provider، وربط الأهداف، والتحقق المسبق (يتطلب TTY).
• apply: تنفيذ خطة محفوظة (--dry-run للتحقق فقط؛ يتخطى التنفيذ التجريبي فحوصات exec افتراضيًا، ويرفض وضع الكتابة الخطط التي تحتوي على exec ما لم يتم ضبط --allow-exec)، ثم تنظيف بقايا النصوص الصريحة المستهدفة.

حلقة التشغيل الموصى بها للمشغّل:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

إذا كانت خطتك تتضمن SecretRefs/providers من نوع exec، فمرّر --allow-exec في كل من أوامر التطبيق التجريبي وأوامر التطبيق الكتابي.

ملاحظة حول رموز الخروج لـ CI/البوابات:

• يعيد audit --check القيمة 1 عند وجود نتائج.
• تعيد المراجع غير المحلولة القيمة 2.

ذو صلة:

• دليل الأسرار: إدارة الأسرار
• سطح بيانات الاعتماد: سطح بيانات اعتماد SecretRef
• دليل الأمان: الأمان

# إعادة تحميل لقطة وقت التشغيل

أعِد حل مراجع الأسرار وبدّل لقطة وقت التشغيل ذرّيًا.

openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

ملاحظات:

• يستخدم طريقة Gateway RPC ‏secrets.reload.
• إذا فشل الحلّ، يحتفظ gateway بآخر لقطة سليمة معروفة ويعيد خطأً (من دون تفعيل جزئي).
• تتضمن استجابة JSON الحقل warningCount.

الخيارات:

• --url <url>
• --token <token>
• --timeout <ms>
• --json

# التدقيق

افحص حالة OpenClaw بحثًا عن:

• تخزين أسرار بنص صريح
• مراجع غير محلولة
• انحراف الأولوية (حيث تطغى بيانات اعتماد auth-profiles.json على مراجع openclaw.json)
• بقايا مولّدة في agents/*/agent/models.json (قيم apiKey الخاصة بالـ provider ورؤوس provider الحساسة)
• بقايا قديمة (إدخالات مخزن المصادقة القديم، وتذكيرات OAuth)

ملاحظة بقايا الرؤوس:

• يعتمد اكتشاف رؤوس provider الحساسة على استدلال قائم على الأسماء (أسماء ومقاطع رؤوس المصادقة/بيانات الاعتماد الشائعة مثل authorization وx-api-key وtoken وsecret وpassword وcredential).

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

سلوك الخروج:

• يؤدي --check إلى الخروج بقيمة غير صفرية عند وجود نتائج.
• تخرج المراجع غير المحلولة برمز غير صفري ذي أولوية أعلى.

أبرز بنية التقرير:

• status: ‏clean | findings | unresolved
• resolution: ‏refsChecked وskippedExecRefs وresolvabilityComplete
• summary: ‏plaintextCount وunresolvedRefCount وshadowedRefCount وlegacyResidueCount
• رموز النتائج:
  • PLAINTEXT_FOUND
  • REF_UNRESOLVED
  • REF_SHADOWED
  • LEGACY_RESIDUE

# التهيئة (مساعد تفاعلي)

أنشئ تغييرات provider وSecretRef بشكل تفاعلي، وشغّل التحقق المسبق، ثم طبّق اختياريًا:

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

التدفق:

• إعداد provider أولًا (add/edit/remove لأسماء secrets.providers المستعارة).
• ربط بيانات الاعتماد ثانيًا (حدد الحقول وعيّن مراجع {source, provider, id}).
• التحقق المسبق والتطبيق الاختياري أخيرًا.

العلامات:

• --providers-only: هيّئ secrets.providers فقط، وتخطَّ ربط بيانات الاعتماد.
• --skip-provider-setup: تخطَّ إعداد provider واربط بيانات الاعتماد بـ providers الموجودة.
• --agent <id>: قصر اكتشاف الأهداف والكتابة في auth-profiles.json على مخزن وكيل واحد.
• --allow-exec: السماح بفحوصات SecretRef من نوع exec أثناء التحقق المسبق/التطبيق (قد يؤدي إلى تنفيذ أوامر provider).

ملاحظات:

• يتطلب TTY تفاعليًا.
• لا يمكنك الجمع بين --providers-only و--skip-provider-setup.
• يستهدف configure الحقول الحاملة للأسرار في openclaw.json بالإضافة إلى auth-profiles.json ضمن نطاق الوكيل المحدد.
• يدعم configure إنشاء عمليات ربط جديدة في auth-profiles.json مباشرةً داخل تدفق الاختيار.
• السطح المدعوم الرسمي: سطح بيانات اعتماد SecretRef.
• ينفّذ حلّ التحقق المسبق قبل التطبيق.
• إذا تضمن التحقق المسبق/التطبيق مراجع exec، فأبقِ --allow-exec مضبوطًا لكلا الخطوتين.
• تستخدم الخطط المولّدة افتراضيًا خيارات التنظيف (scrubEnv وscrubAuthProfilesForProviderTargets وscrubLegacyAuthJson كلها مفعّلة).
• يكون مسار التطبيق أحادي الاتجاه بالنسبة إلى قيم النص الصريح التي تم تنظيفها.
• من دون --apply، لا يزال CLI يطلب Apply this plan now? بعد التحقق المسبق.
• مع --apply (ومن دون --yes)، يعرض CLI مطالبة تأكيد إضافية لا رجعة فيها.
• يطبع --json الخطة + تقرير التحقق المسبق، لكن الأمر لا يزال يتطلب TTY تفاعليًا.

ملاحظة أمان provider من نوع exec:

• كثيرًا ما تكشف تثبيتات Homebrew ملفات تنفيذية مرتبطة رمزيًا تحت /opt/homebrew/bin/*.
• اضبط allowSymlinkCommand: true فقط عند الحاجة لمسارات مدير حزم موثوقة، واقرن ذلك مع trustedDirs (على سبيل المثال ["/opt/homebrew"]).
• في Windows، إذا لم يكن التحقق من ACL متاحًا لمسار provider، فإن OpenClaw يفشل في وضع مغلق. وبالنسبة إلى المسارات الموثوقة فقط، اضبط allowInsecurePath: true على ذلك provider لتجاوز فحوصات أمان المسار.

# تطبيق خطة محفوظة

طبّق أو تحقّق مسبقًا من خطة تم إنشاؤها سابقًا:

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

سلوك exec:

• يقوم --dry-run بالتحقق من التحقق المسبق من دون كتابة ملفات.
• تُتخطى فحوصات SecretRef من نوع exec افتراضيًا في التنفيذ التجريبي.
• يرفض وضع الكتابة الخطط التي تحتوي على SecretRefs/providers من نوع exec ما لم يتم ضبط --allow-exec.
• استخدم --allow-exec للاشتراك في فحوصات/تنفيذ provider من نوع exec في أي من الوضعين.

تفاصيل عقد الخطة (مسارات الأهداف المسموح بها، وقواعد التحقق، ودلالات الفشل):

• عقد خطة تطبيق الأسرار

ما الذي قد يحدّثه apply:

• openclaw.json (أهداف SecretRef + عمليات upserts/deletes للـ provider)
• auth-profiles.json (تنظيف أهداف provider)
• بقايا auth.json القديمة
• مفاتيح الأسرار المعروفة في ~/.openclaw/.env التي تم ترحيل قيمها

# لماذا لا توجد نسخ احتياطية للتراجع

يتعمد secrets apply عدم كتابة نسخ احتياطية للتراجع تحتوي على قيم النص الصريح القديمة.

تأتي السلامة من التحقق المسبق الصارم + التطبيق شبه الذري مع استعادة داخل الذاكرة بأفضل جهد عند الفشل.

# مثال

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

إذا كان audit --check لا يزال يبلغ عن نتائج نص صريح، فحدّث مسارات الأهداف المتبقية المُبلَّغ عنها وأعد تشغيل التدقيق.

# ذو صلة

• مرجع CLI
• إدارة الأسرار