​

إدارة الأسرار

​

الأهداف ونموذج وقت التشغيل

• يتم الحل بشكل متحمّس أثناء التفعيل، وليس كسلوك كسول في مسارات الطلبات.
• يفشل بدء التشغيل سريعًا عندما يتعذر حل SecretRef نشط فعليًا.
• تستخدم إعادة التحميل التبديل الذري: نجاح كامل، أو الاحتفاظ بآخر لقطة سليمة معروفة.
• تؤدي مخالفات سياسة SecretRef ‏(على سبيل المثال ملفات تعريف مصادقة في وضع OAuth مع إدخال SecretRef) إلى فشل التفعيل قبل تبديل وقت التشغيل.
• تقرأ طلبات وقت التشغيل من اللقطة النشطة داخل الذاكرة فقط.
• بعد أول تفعيل/تحميل ناجح للإعدادات، تستمر مسارات شيفرة وقت التشغيل في القراءة من تلك اللقطة النشطة داخل الذاكرة حتى تؤدي إعادة تحميل ناجحة إلى استبدالها.
• تقرأ مسارات التسليم الصادر أيضًا من تلك اللقطة النشطة (على سبيل المثال تسليم الرد/السلسلة في Discord وإرسالات الإجراءات في Telegram)؛ ولا تعيد حل SecretRefs عند كل إرسال.

​

تصفية الأسطح النشطة

• الأسطح المفعلة: تمنع المراجع غير المحلولة بدء التشغيل/إعادة التحميل.
• الأسطح غير النشطة: لا تمنع المراجع غير المحلولة بدء التشغيل/إعادة التحميل.
• تصدر المراجع غير النشطة تشخيصات غير قاتلة بالرمز SECRETS_REF_IGNORED_INACTIVE_SURFACE.

• إدخالات القنوات/الحسابات المعطلة.
• بيانات اعتماد القناة العليا التي لا يرثها أي حساب مفعّل.
• أسطح الأدوات/الميزات المعطلة.
• مفاتيح مزوّدي البحث على الويب الخاصة بكل مزوّد غير المحددة بواسطة tools.web.search.provider. في الوضع التلقائي (عندما لا يكون المزوّد مضبوطًا)، تتم استشارة المفاتيح حسب الأولوية لاكتشاف المزوّد تلقائيًا حتى يتم حل أحدها. وبعد الاختيار، تُعامل مفاتيح المزوّدين غير المختارين على أنها غير نشطة حتى يتم اختيارها.
• مواد مصادقة SSH الخاصة بـ sandbox ‏(agents.defaults.sandbox.ssh.identityData، وcertificateData، وknownHostsData، بالإضافة إلى التجاوزات لكل وكيل) تكون نشطة فقط عندما تكون خلفية sandbox الفعالة هي ssh للوكيل الافتراضي أو لوكيل مفعّل.
• تكون مراجع SecretRef الخاصة بـ gateway.remote.token / gateway.remote.password نشطة إذا تحقق أحد ما يلي:
  • gateway.mode=remote
  • تم إعداد gateway.remote.url
  • قيمة gateway.tailscale.mode هي serve أو funnel
  • في الوضع المحلي من دون تلك الأسطح البعيدة:
    • يكون gateway.remote.token نشطًا عندما يمكن أن تفوز مصادقة الرمز ولا يكون هناك رمز مضبوط في env/auth.
    • يكون gateway.remote.password نشطًا فقط عندما يمكن أن تفوز مصادقة كلمة المرور ولا تكون هناك كلمة مرور مضبوطة في env/auth.
• يكون SecretRef الخاص بـ gateway.auth.token غير نشط في حل مصادقة بدء التشغيل عندما يكون OPENCLAW_GATEWAY_TOKEN مضبوطًا، لأن إدخال رمز env يفوز لذلك وقت التشغيل.

​

تشخيصات سطح مصادقة Gateway

• active: يكون SecretRef جزءًا من سطح المصادقة الفعّال ويجب أن يُحل.
• inactive: يتم تجاهل SecretRef لهذا وقت التشغيل لأن سطح مصادقة آخر يفوز، أو لأن المصادقة البعيدة معطلة/غير نشطة.

​

الفحص المسبق لمرجع onboarding

• مراجع env: يتحقق من اسم متغير البيئة ويؤكد أن قيمة غير فارغة مرئية أثناء الإعداد.
• مراجع المزوّد (file أو exec): يتحقق من اختيار المزوّد، ويحل id، ويتحقق من نوع القيمة المحلولة.
• مسار إعادة استخدام البدء السريع: عندما يكون gateway.auth.token بالفعل SecretRef، يقوم onboarding بحلّه قبل التهيئة الأولية للفحص/لوحة المعلومات (بالنسبة إلى مراجع env وfile وexec) باستخدام بوابة الفشل السريع نفسها.

​

عقد SecretRef

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

​

source: "env"

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

• يجب أن يطابق provider النمط ^[a-z][a-z0-9_-]{0,63}$
• يجب أن يطابق id النمط ^[A-Z][A-Z0-9_]{0,127}$

​

source: "file"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

• يجب أن يطابق provider النمط ^[a-z][a-z0-9_-]{0,63}$
• يجب أن يكون id مؤشر JSON مطلقًا (/...)
• هروب RFC6901 داخل المقاطع: ~ => ~0، و/ => ~1

​

source: "exec"

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

• يجب أن يطابق provider النمط ^[a-z][a-z0-9_-]{0,63}$
• يجب أن يطابق id النمط ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• يجب ألا يحتوي id على . أو .. كمقاطع مسار مفصولة بشرطة مائلة (على سبيل المثال يتم رفض a/../b)

​

إعدادات المزوّد

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

​

مزوّد Env

• قائمة السماح عبر allowlist اختيارية.
• تؤدي قيم env المفقودة/الفارغة إلى فشل الحل.

​

مزوّد File

• يقرأ الملف المحلي من path.
• يتوقع mode: "json" حمولة كائن JSON ويحل id كمؤشر.
• يتوقع mode: "singleValue" أن يكون معرّف المرجع "value" ويعيد محتويات الملف.
• يجب أن يجتاز المسار فحوصات الملكية/الأذونات.
• ملاحظة Windows ذات الفشل المغلق: إذا لم يكن التحقق من ACL متاحًا لمسار ما، يفشل الحل. وبالنسبة إلى المسارات الموثوقة فقط، اضبط allowInsecurePath: true على ذلك المزوّد لتجاوز فحوصات أمان المسار.

​

مزوّد Exec

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

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

​

أمثلة تكامل Exec

​

CLI الخاص بـ 1Password

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

​

CLI الخاص بـ HashiCorp Vault

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

​

sops

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

​

متغيرات بيئة خادم MCP

{
  plugins: {
    entries: {
      acpx: {
        enabled: true,
        config: {
          mcpServers: {
            github: {
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-github"],
              env: {
                GITHUB_PERSONAL_ACCESS_TOKEN: {
                  source: "env",
                  provider: "default",
                  id: "MCP_GITHUB_PAT",
                },
              },
            },
          },
        },
      },
    },
  },
}

​

مواد مصادقة SSH الخاصة بـ Sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        ssh: {
          target: "user@gateway-host:22",
          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

• يحل OpenClaw هذه المراجع أثناء تفعيل sandbox، وليس كسلوك كسول أثناء كل استدعاء SSH.
• تُكتب القيم المحلولة إلى ملفات مؤقتة ذات أذونات مقيدة وتُستخدم في إعدادات SSH المُولّدة.
• إذا لم تكن الخلفية الفعالة لـ sandbox هي ssh، تبقى هذه المراجع غير نشطة ولا تمنع بدء التشغيل.

​

سطح بيانات الاعتماد المدعوم

• سطح بيانات اعتماد SecretRef

​

السلوك المطلوب والأولوية

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

• SECRETS_REF_OVERRIDES_PLAINTEXT ‏(تحذير وقت التشغيل)
• REF_SHADOWED ‏(نتيجة تدقيق عندما تكون بيانات اعتماد auth-profiles.json لها الأولوية على مراجع openclaw.json)

• تكون الأولوية لـ serviceAccountRef على serviceAccount النصي الصريح.
• يتم تجاهل القيمة النصية الصريحة عندما يكون المرجع المجاور مضبوطًا.

​

محفزات التفعيل

• بدء التشغيل (فحص مسبق ثم تفعيل نهائي)
• مسار التطبيق المباشر لإعادة تحميل الإعدادات
• مسار التحقق من إعادة التشغيل عند إعادة تحميل الإعدادات
• إعادة التحميل اليدوية عبر secrets.reload
• الفحص المسبق لاستدعاءات RPC لكتابة إعدادات Gateway ‏(config.set / config.apply / config.patch) لإمكانية حل SecretRef للأسطح النشطة داخل حمولة الإعدادات المُقدمة قبل حفظ التعديلات

• النجاح يبدّل اللقطة بشكل ذري.
• فشل بدء التشغيل يوقف بدء تشغيل gateway.
• فشل إعادة التحميل في وقت التشغيل يُبقي آخر لقطة سليمة معروفة.
• فشل الفحص المسبق لاستدعاء كتابة RPC يرفض الإعدادات المُقدمة ويُبقي كلًا من إعدادات القرص واللقطة النشطة في وقت التشغيل دون تغيير.
• توفير رمز قناة صريح لكل استدعاء لأداة/مساعد صادر لا يؤدي إلى تشغيل تفعيل SecretRef؛ وتظل نقاط التفعيل محصورة في بدء التشغيل، وإعادة التحميل، وsecrets.reload الصريح.

​

إشارات التدهور والتعافي

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• التدهور: يحتفظ وقت التشغيل بآخر لقطة سليمة معروفة.
• التعافي: يصدر مرة واحدة بعد التفعيل الناجح التالي.
• الإخفاقات المتكررة أثناء التدهور الحالي تسجل تحذيرات لكنها لا تزعج بالأحداث.
• الفشل السريع عند بدء التشغيل لا يصدر أحداث تدهور لأن وقت التشغيل لم يصبح نشطًا أصلًا.

​

الحل في مسارات الأوامر

• مسارات أوامر صارمة (على سبيل المثال مسارات الذاكرة البعيدة في openclaw memory وopenclaw qr --remote عندما تحتاج إلى مراجع أسرار بعيدة مشتركة) تقرأ من اللقطة النشطة وتفشل سريعًا عندما لا يكون SecretRef المطلوب متاحًا.
• مسارات أوامر للقراءة فقط (على سبيل المثال openclaw status وopenclaw status --all وopenclaw channels status وopenclaw channels resolve وopenclaw security audit وتدفقات doctor/config repair للقراءة فقط) تفضّل أيضًا اللقطة النشطة، لكنها تتدهور بدلًا من الإجهاض عندما لا يكون SecretRef المستهدف متاحًا في مسار ذلك الأمر.

• عندما يكون gateway قيد التشغيل، تقرأ هذه الأوامر من اللقطة النشطة أولًا.
• إذا كان حل gateway غير مكتمل أو كان gateway غير متاح، فإنها تحاول تراجعًا محليًا مستهدفًا لسطح الأمر المحدد.
• إذا ظل SecretRef المستهدف غير متاح، يستمر الأمر بمخرجات قراءة فقط متدهورة مع تشخيصات صريحة مثل “configured but unavailable in this command path”.
• هذا السلوك المتدهور محلي للأمر فقط. وهو لا يضعف مسارات بدء التشغيل، أو إعادة التحميل، أو الإرسال/المصادقة في وقت التشغيل.

• تتم معالجة تحديث اللقطة بعد تدوير الأسرار في الخلفية بواسطة openclaw secrets reload.
• طريقة RPC في gateway المستخدمة بواسطة مسارات الأوامر هذه: secrets.resolve.

​

سير عمل التدقيق وconfigure

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

​

secrets audit

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

• افتراضيًا، يتخطى التدقيق فحوصات إمكانية حل SecretRef من نوع exec لتجنب الآثار الجانبية للأوامر.
• استخدم openclaw secrets audit --allow-exec لتنفيذ مزوّدي exec أثناء التدقيق.

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

​

secrets configure

• يضبط secrets.providers أولًا (env/file/exec، إضافة/تعديل/إزالة)
• يتيح لك تحديد الحقول المدعومة الحاملة للأسرار في openclaw.json بالإضافة إلى auth-profiles.json لنطاق وكيل واحد
• يمكنه إنشاء تعيين جديد في auth-profiles.json مباشرة داخل منتقي الهدف
• يلتقط تفاصيل SecretRef ‏(source وprovider وid)
• يشغّل الحل المسبق preflight
• يمكنه التطبيق فورًا

• يتخطى preflight فحوصات SecretRef من نوع exec ما لم يتم ضبط --allow-exec.
• إذا قمت بالتطبيق مباشرة من configure --apply وكانت الخطة تتضمن مراجع/مزوّدي exec، فأبقِ --allow-exec مضبوطًا لخطوة التطبيق أيضًا.

• openclaw secrets configure --providers-only
• openclaw secrets configure --skip-provider-setup
• openclaw secrets configure --agent <id>

• تنظيف بيانات الاعتماد الثابتة المطابقة من auth-profiles.json للمزوّدين المستهدفين
• تنظيف إدخالات api_key الثابتة القديمة من auth.json
• تنظيف أسطر الأسرار المعروفة المطابقة من <config-dir>/.env

​

secrets apply

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

• يتخطى dry-run فحوصات exec ما لم يتم ضبط --allow-exec.
• يرفض وضع الكتابة الخطط التي تحتوي على مراجع/مزوّدي exec ما لم يتم ضبط --allow-exec.

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

​

سياسة الأمان أحادية الاتجاه

• يجب أن ينجح preflight قبل وضع الكتابة
• يتم التحقق من تفعيل وقت التشغيل قبل الالتزام
• يقوم apply بتحديث الملفات باستخدام استبدال ذري للملفات واستعادة بأفضل جهد عند الفشل

​

ملاحظات توافق المصادقة القديمة

• مصدر بيانات الاعتماد في وقت التشغيل هو اللقطة المحلولة داخل الذاكرة.
• يتم تنظيف إدخالات api_key الثابتة القديمة عند اكتشافها.
• يظل سلوك التوافق المتعلق بـ OAuth منفصلًا.

​

ملاحظة واجهة الويب

​

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

• أوامر CLI: secrets
• تفاصيل عقد الخطة: عقد خطة تطبيق الأسرار
• سطح بيانات الاعتماد: سطح بيانات اعتماد SecretRef
• إعداد المصادقة: المصادقة
• الوضع الأمني: الأمان
• أولوية البيئة: متغيرات البيئة