openclaw secrets

أدِر مراجع الأسرار SecretRefs وحافظ على سلامة اللقطة النشطة لوقت التشغيل.

دورة التشغيل الموصى بها:

openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets audit --checkopenclaw secrets reload

إذا كانت خطتك تتضمن مراجع أسرار SecretRefs أو مزوّدين من نوع exec، فمرّر --allow-exec إلى أمري apply في وضع التشغيل التجريبي ووضع الكتابة.

رموز الخروج لعمليات CI/البوابات:

• يُرجع audit --check الرمز 1 عند وجود نتائج.
• تُرجع المراجع غير المحلولة الرمز 2 (بغض النظر عن --check).

ذو صلة: إدارة الأسرار · سطح بيانات اعتماد SecretRef · الأمان

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

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

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

الخيارات: --url <url>، و--token <token>، و--timeout <ms>، و--json.

التدقيق

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

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

يعتمد اكتشاف ترويسات المزوّد الحساسة على استدلال الاسم: إذ يضع علامة على الترويسات التي تتطابق أسماؤها مع أجزاء شائعة مرتبطة بالمصادقة أو بيانات الاعتماد (authorization، وx-api-key، وtoken، وsecret، وpassword، وcredential).

openclaw secrets auditopenclaw secrets audit --checkopenclaw secrets audit --jsonopenclaw secrets audit --allow-exec

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

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

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

أنشئ تغييرات المزوّد وSecretRef تفاعليًا، وشغّل الفحص المسبق، وطبّقها اختياريًا:

openclaw secrets configureopenclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.jsonopenclaw secrets configure --apply --yesopenclaw secrets configure --providers-onlyopenclaw secrets configure --skip-provider-setupopenclaw secrets configure --agent opsopenclaw secrets configure --json

التدفق: إعداد المزوّد أولًا (إضافة/تعديل/إزالة الأسماء المستعارة في secrets.providers)، ثم ربط بيانات الاعتماد (تحديد الحقول وتعيين المراجع {source, provider, id})، ثم الفحص المسبق والتطبيق الاختياري.

العلامات:

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

لا يمكن الجمع بين --providers-only و--skip-provider-setup.

ملاحظات:

• يتطلب TTY تفاعليًا.
• يستهدف الحقول المحتوية على أسرار في openclaw.json بالإضافة إلى auth-profiles.json ضمن نطاق الوكيل المحدد؛ السطح القياسي المدعوم: سطح بيانات اعتماد SecretRef.
• يدعم إنشاء عمليات ربط جديدة في auth-profiles.json مباشرةً ضمن تدفق أداة الاختيار.
• يشغّل تحليل الفحص المسبق قبل التطبيق.
• تفعّل الخطط المُنشأة خيارات التنقية افتراضيًا (scrubEnv، وscrubAuthProfilesForProviderTargets، وscrubLegacyAuthJson). لا يمكن التراجع عن تطبيق قيم النص الصريح بعد تنقيتها.
• من دون --apply، يظل CLI يعرض المطالبة Apply this plan now? بعد الفحص المسبق.
• مع --apply (ومن دون --yes)، يعرض CLI مطالبة إضافية لتأكيد الترحيل غير القابل للتراجع.
• يطبع --json الخطة مع تقرير الفحص المسبق، لكنه يظل يتطلب TTY تفاعليًا.

أمان مزوّد exec

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

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

openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

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

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

• openclaw.json (أهداف SecretRef مع إضافة المزوّدين أو تحديثهم أو حذفهم)
• auth-profiles.json (تنقية أهداف المزوّدين)
• مخلّفات auth.json القديمة
• مفاتيح الأسرار المعروفة في ~/.openclaw/.env التي رُحّلت قيمها

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

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

لا يكتب secrets apply عمدًا نسخًا احتياطية للتراجع تحتوي على قيم النص الصريح القديمة. تتحقق السلامة من خلال فحص مسبق صارم وتطبيق شبه ذري، مع محاولة استعادة داخل الذاكرة عند الفشل بأفضل جهد ممكن.

مثال

openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets audit --check

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

ذو صلة

• مرجع CLI
• إدارة الأسرار
• مراجع أسرار Vault من نوع SecretRefs