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

يدعم OpenClaw مراجع SecretRefs الإضافية، بحيث لا يلزم تخزين بيانات الاعتماد المدعومة كنص صريح في الإعدادات.

نموذج وقت التشغيل

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

يُبقي هذا انقطاعات موفّري الأسرار خارج مسارات الطلبات الحساسة للأداء.

الحقن عند الخروج (العلامات الحارسة)

بالنسبة إلى بيانات اعتماد موفّري النماذج المدعومة بواسطة SecretRefs، ينشئ OpenClaw علامة حارسة مبهمة ومحلية للعملية أثناء حل مصادقة النموذج. لذلك ترى عمليات تخزين المصادقة وخيارات البث وإعدادات SDK والسجلات وكائنات الأخطاء ومعظم عمليات فحص وقت التشغيل قيمة مثل oc-sent-v1-...، لا بيانات اعتماد الموفّر. يستبدل جلب النموذج المحمي وفحوصات سلامة الموفّر المحلي المُدار العلامات الحارسة المعروفة في قيم عناوين URL والترويسات مباشرة قبل مغادرة كل طلب للعملية.

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

تستخدم محوّلات الموفّرين أحدث نقطة حقن تدعمها حزمة SDK الخاصة بها:

• تتلقى حزم SDK التي توفر خيار جلب مخصص عملية الجلب المحمية من OpenClaw، ولذلك تحتفظ حزمة SDK بالعلامة الحارسة.
• تفك حزم SDK التي لا توفر خيار جلب مخصص العلامة الحارسة مباشرة قبل إنشاء العميل. وتفك تدفقات الموفّرين المملوكة لـ Plugin وأطر تشغيل الوكلاء العلامة عند نقطة التسليم النهائية المملوكة للنواة، لأن وسائل النقل هذه لا تشارك عملية الجلب المحمية الخاصة بـ OpenClaw.

تقلل العلامات الحارسة انكشاف النص الصريح عبر سلسلة استدعاء النموذج، لكنها لا توفر عزلًا للعملية. تظل القيمة الحقيقية موجودة في ذاكرة العملية نفسها، وتظهر عند حد المحوّل النهائي. وتظل بيانات اعتماد البيئة النصية الصريحة التي لم تُضبط عبر SecretRefs نصًا صريحًا وخارج هذه الآلية.

عيّن OPENCLAW_SECRET_SENTINELS=off (ويقبل أيضًا 0 أو false، دون حساسية لحالة الأحرف) لتعطيل إنشاء العلامات الحارسة أثناء الاستجابة للحوادث أو استكشاف مشكلات التوافق وإصلاحها. لا يعطّل مفتاح الإيقاف تسجيل الحجب عند التطابق التام للقيم.

حدود وصول الوكيل

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

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

• تستخدم بيانات الاعتماد المدعومة SecretRefs بدلًا من القيم النصية الصريحة.
• تُزال بقايا النص الصريح القديمة من openclaw.json وauth-profiles.json و.env وملفات models.json المُنشأة.
• يكون openclaw secrets audit --check خاليًا من المشكلات بعد الترحيل.
• تُحمى أي بيانات اعتماد متبقية غير مدعومة أو دورية التغيير بواسطة عزل نظام التشغيل أو عزل الحاويات أو وكيل خارجي لبيانات الاعتماد.

لهذا السبب يُعد سير عمل التدقيق/الضبط/التطبيق بوابة ترحيل أمنية، وليس مجرد أداة مساعدة للراحة.

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

لا تُتحقق صلاحية SecretRefs إلا على الأسطح النشطة فعليًا:

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

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

عند تعيين SecretRef على gateway.auth.token أو gateway.auth.password أو gateway.remote.token أو gateway.remote.password، يسجل بدء تشغيل Gateway/إعادة تحميله حالة السطح تحت الرمز SECRETS_GATEWAY_AUTH_SURFACE:

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

يتضمن إدخال السجل السبب الذي استخدمته سياسة السطح النشط.

الفحص المسبق لمراجع الإعداد الأولي

في الإعداد الأولي التفاعلي، يؤدي اختيار تخزين SecretRef إلى تشغيل تحقق مسبق قبل الحفظ:

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

يُظهر فشل التحقق الخطأ ويتيح إعادة المحاولة.

عقد SecretRef

شكل كائن واحد في كل المواضع:

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

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

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

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

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

إعداد الموفّر

عرّف الموفّرين ضمن secrets.providers:

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

{ "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": { "code": "NOT_FOUND" } }}

مفاتيح API المدعومة بملفات

لا تضع سلاسل file:... في كتلة env ضمن الإعداد. هذه الكتلة حرفية ولا تتجاوز القيم، لذلك لا يُحلّ file:... فيها مطلقًا.

استخدم بدلًا من ذلك SecretRef لملف في حقل بيانات اعتماد مدعوم:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

بالنسبة إلى mode: "singleValue"، يكون id الخاص بـ SecretRef هو "value". وبالنسبة إلى mode: "json"، استخدم مؤشر JSON مطلقًا مثل "/providers/xai/apiKey".

راجع سطح بيانات اعتماد SecretRef لمعرفة الحقول التي تقبل مراجع SecretRef.

أمثلة على تكامل التنفيذ

للحصول على دليل مخصص لـ 1Password يغطي حسابات الخدمة وSkills الوكيل المضمّنة واستكشاف الأخطاء وإصلاحها، راجع 1Password.

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // مطلوب للملفات التنفيذية المرتبطة رمزيًا بواسطة Homebrew        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" },      },    },  },}

{  secrets: {    providers: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // مطلوب للملفات التنفيذية المرتبطة رمزيًا بواسطة Homebrew        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" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`تعذّر تحليل الطلب: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `خرج pass بالحالة ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // مطلوب للملفات التنفيذية المرتبطة رمزيًا بواسطة Homebrew        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

تقبل متغيرات بيئة خادم MCP المُعدّة عبر plugins.entries.acpx.config.mcpServers النوع SecretInput، مما يُبقي مفاتيح API والرموز المميزة خارج الإعداد ذي النص الصريح:

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

تظل القيم النصية الصريحة صالحة. تُحلّ مراجع قوالب البيئة مثل ${MCP_SERVER_API_KEY} وكائنات SecretRef أثناء تنشيط Gateway، قبل إنشاء عملية خادم MCP. وكما هو الحال مع أسطح SecretRef الأخرى، لا تمنع المراجع غير المحلولة التنشيط إلا عندما تكون Plugin ‏acpx نشطة فعليًا.

مواد مصادقة SSH لصندوق العزل

يدعم أيضًا برنامج الواجهة الخلفية الأساسي لصندوق العزل ssh مراجع SecretRef لمواد مصادقة SSH:

{  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 هذه المراجع أثناء تفعيل بيئة العزل، وليس بصورة كسولة عند كل استدعاء SSH.
• تُكتب القيم المحلولة في دليل مؤقت بأذونات ملفات مقيّدة (0o600)، وتُستخدم في إعداد SSH المُنشأ.
• إذا لم تكن الواجهة الخلفية الفعلية لبيئة العزل هي ssh (أو كان وضع بيئة العزل هو off)، فتبقى هذه المراجع غير نشطة ولا تعوق بدء التشغيل.

نطاق بيانات الاعتماد المدعوم

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

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

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

إشارات التحذير والتدقيق:

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

توافق Google Chat: تكون الأسبقية لـ serviceAccountRef على serviceAccount ذي النص الصريح؛ وتُتجاهل قيمة النص الصريح بمجرد تعيين المرجع الشقيق.

مشغلات التفعيل

يُنفّذ تفعيل الأسرار عند:

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

عقد التفعيل:

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

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

عند فشل التفعيل في وقت إعادة التحميل بعد حالة سليمة، يدخل OpenClaw حالة أسرار متدهورة، ويصدر أحداث نظام لمرة واحدة ورموز سجل:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

السلوك:

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

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

يمكن لمسارات الأوامر الاشتراك في حل SecretRef المدعوم عبر استدعاء RPC للقطة Gateway. وينطبق سلوكان عامان:

ملاحظات أخرى:

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

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

التدفق الافتراضي للمشغّل:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

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

إذا حفظت خطة بدلًا من تطبيقها أثناء configure، فطبّق تلك الخطة المحفوظة باستخدام openclaw secrets apply --from <plan-path> قبل إعادة التدقيق.

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-exec

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

نموذج الأمان:

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

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

بالنسبة إلى بيانات الاعتماد الثابتة، لم يعد وقت التشغيل يعتمد على تخزين المصادقة القديم بنص صريح.

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

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

يسهل إعداد بعض اتحادات SecretInput في وضع المحرر الخام مقارنةً بوضع النموذج.

ذو صلة

• المصادقة - إعداد المصادقة
• CLI: الأسرار - أوامر CLI
• مراجع أسرار Vault - إعداد مزوّد HashiCorp Vault
• متغيرات البيئة - أسبقية البيئة
• نطاق بيانات اعتماد SecretRef - نطاق بيانات الاعتماد
• عقد خطة تطبيق الأسرار - تفاصيل عقد الخطة
• الأمان - الوضع الأمني