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

​

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

{
  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" },
    },
  ],
}

​

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

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

{
  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" },
    },
  ],
}

​

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

​

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

​

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

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

​

سلوك الفشل

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 في الخطة لتخطي تلك العملية.

​

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

# التحقق من صحة الخطة من دون كتابة
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-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

​

وثائق ذات صلة

• إدارة الأسرار
• CLI ‏secrets
• نطاق بيانات اعتماد SecretRef
• مرجع الإعدادات