Gateway

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

تحدد هذه الصفحة العقد الصارم الذي يفرضه openclaw secrets apply. إذا لم يطابق هدفٌ ما هذه القواعد، تفشل عملية التطبيق قبل تعديل أي ملف.

بنية ملف الخطة

يتوقع openclaw secrets apply --from <plan.json> مصفوفة targets من أهداف الخطة:

json5

{  version: 1,  protocolVersion: 1,  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.openai.apiKey",      pathSegments: ["models", "providers", "openai", "apiKey"],      providerId: "openai",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },    {      type: "auth-profiles.api_key.key",      path: "profiles.openai:default.key",      pathSegments: ["profiles", "openai:default", "key"],      agentId: "main",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },  ],}

ينشئ openclaw secrets configure الخطط بهذه البنية. ويمكنك أيضًا كتابة خطة أو تعديلها يدويًا.

إدراج المزوّدين أو تحديثهم وحذفهم

قد تتضمن الخطط أيضًا حقلين اختياريين في المستوى الأعلى يعدّلان خريطة secrets.providers إلى جانب عمليات الكتابة الخاصة بكل هدف:

providerUpserts -- كائن مفهرس بالاسم البديل للمزوّد. كل قيمة هي تعريف لمزوّد (بالبنية نفسها المقبولة ضمن secrets.providers.<alias> في openclaw.json، مثل مزوّد exec أو file).
providerDeletes -- مصفوفة من الأسماء البديلة للمزوّدين المراد إزالتها.

تُنفّذ providerUpserts قبل targets، لذا يمكن أن يشير target.ref.provider إلى اسم بديل لمزوّد تضيفه الخطة نفسها في providerUpserts. من دون هذا الترتيب، تفشل الخطط التي تشير إلى اسم بديل لم يُضبط بعد في openclaw.json بالخطأ provider "<alias>" is not configured.

json5

{  version: 1,  protocolVersion: 1,  providerUpserts: {    onepassword_anthropic: {      source: "exec",      command: "/usr/bin/op",      args: ["read", "op://Vault/Anthropic/credential"],    },  },  providerDeletes: ["legacy_unused_alias"],  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.anthropic.apiKey",      pathSegments: ["models", "providers", "anthropic", "apiKey"],      providerId: "anthropic",      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },    },  ],}

تظل مزوّدات Exec المُضافة عبر providerUpserts خاضعة لقواعد الموافقة على Exec الواردة في سلوك الموافقة على مزوّد Exec: تتطلب الخطط التي تحتوي على مزوّدات Exec الخيار --allow-exec في وضع الكتابة.

نطاق الأهداف المدعوم

تُقبل أهداف الخطة لمسارات بيانات الاعتماد المدعومة في نطاق بيانات اعتماد SecretRef.

سلوك نوع الهدف

يجب أن يكون target.type نوع هدف معروفًا، ويجب أن يطابق target.path بعد تسويته بنية المسار المسجلة لذلك النوع.

تقبل بعض أنواع الأهداف اسمًا بديلًا للتوافق في target.type للخطط الحالية، بالإضافة إلى اسم النوع الأساسي:

النوع الأساسي	الاسم البديل المقبول
`models.providers.apiKey`	`models.providers.*.apiKey`
`skills.entries.apiKey`	`skills.entries.*.apiKey`
`channels.googlechat.serviceAccount`	`channels.googlechat.accounts.*.serviceAccount`

قواعد التحقق من صحة المسار

يُتحقق من كل هدف وفق جميع القواعد الآتية:

يجب أن يكون type نوع هدف معروفًا.
يجب أن يكون path مسارًا نقطيًا غير فارغ.
يمكن حذف pathSegments. وإذا قُدّم، فيجب أن ينتج بعد التسوية المسار نفسه تمامًا الذي ينتجه path.
تُرفض المقاطع المحظورة: __proto__ وprototype وconstructor.
يجب أن يطابق المسار بعد التسوية بنية المسار المسجلة لنوع الهدف.
إذا ضُبط providerId أو accountId، فيجب أن يطابق المعرّف المضمّن في المسار.
تتطلب أهداف auth-profiles.json وجود agentId.
عند إنشاء تعيين جديد في auth-profiles.json، ضمّن authProfileProvider.

سلوك الفشل

إذا فشل التحقق من صحة هدف، تنتهي عملية التطبيق بخطأ مثل:

text

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

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

سلوك الموافقة على مزوّد Exec

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

ملاحظات حول نطاق وقت التشغيل والتدقيق

تُضمَّن إدخالات auth-profiles.json التي تحتوي على مراجع فقط (keyRef/tokenRef) في حل بيانات الاعتماد في وقت التشغيل وفي تغطية التدقيق.
يكتب secrets apply أهداف openclaw.json المدعومة وأهداف auth-profiles.json المدعومة، وينفّذ ثلاث عمليات تنظيف اختيارية مفعّلة افتراضيًا: scrubEnv (تزيل قيم النص الصريح التي رُحّلت من .env)، وscrubAuthProfilesForProviderTargets (تمحو بقايا النص الصريح أو المراجع غير المستخدمة في auth-profiles.json للمزوّدين الذين رحّلتهم الخطة للتو)، وscrubLegacyAuthJson (تحذف إدخالات api_key المُرحّلة من مخازن auth.json القديمة). اضبط أيًا من options.scrubEnv أو options.scrubAuthProfilesForProviderTargets أو options.scrubLegacyAuthJson على false في الخطة لتخطي تلك العملية.

فحوصات المشغّل

bash

# التحقق من صحة الخطة من دون كتابةopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run # ثم التطبيق فعليًاopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json # للخطط التي تحتوي على exec، وافق صراحةً في كلا الوضعينopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

إذا فشلت عملية التطبيق برسالة تفيد بأن مسار الهدف غير صالح، فأعِد إنشاء الخطة باستخدام openclaw secrets configure أو صحّح مسار الهدف ليتوافق مع إحدى البنى المدعومة أعلاه.

وثائق ذات صلة

Was this useful?