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

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

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

تُحل الأسرار في لقطة وقت تشغيل داخل الذاكرة.

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

يبقي هذا انقطاعات مزود الأسرار خارج مسارات الطلبات الساخنة.

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

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

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

• تستخدم بيانات الاعتماد المدعومة 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 حالة السطح صراحةً:

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

تُسجل هذه الإدخالات مع SECRETS_GATEWAY_AUTH_SURFACE وتتضمن السبب المستخدم بواسطة سياسة السطح النشط، بحيث يمكنك رؤية سبب معاملة بيانات اعتماد على أنها نشطة أو غير نشطة.

فحص مرجع التهيئة المسبق

عندما تعمل التهيئة في الوضع التفاعلي وتختار تخزين SecretRef، يشغل OpenClaw تحققًا مسبقًا قبل الحفظ:

• مراجع البيئة: تتحقق من اسم متغير البيئة وتؤكد أن قيمة غير فارغة مرئية أثناء الإعداد.
• مراجع المزود (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", // or "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": { "message": "not found" } }}

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

لا تضع سلاسل file:... في كتلة env في التكوين. كتلة 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 لمعرفة حقول التكوين التي تقبل SecretRefs.

أمثلة تكامل exec

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

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

#!/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(`Failed to parse request: ${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 exited ${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, // 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

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

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

بيانات الاعتماد الأساسية المدعومة وغير المدعومة مدرجة في:

• سطح بيانات اعتماد 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.
• يُبقي فشل إعادة التحميل في وقت التشغيل آخر لقطة سليمة معروفة.
• يرفض فشل الفحص التمهيدي لـ Write-RPC الإعدادات المُرسلة ويُبقي إعدادات القرص ولقطة وقت التشغيل النشطة بلا تغيير.
• لا يؤدي تقديم رمز قناة صريح لكل استدعاء إلى استدعاء مساعد/أداة صادرة إلى تشغيل تفعيل SecretRef؛ تبقى نقاط التفعيل هي بدء التشغيل، وإعادة التحميل، وsecrets.reload الصريح.

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

عندما يفشل التفعيل وقت إعادة التحميل بعد حالة سليمة، يدخل OpenClaw حالة أسرار متدهورة.

أكواد حدث النظام والسجل أحادية الإرسال:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

السلوك:

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

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

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

هناك سلوكان عامان:

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

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

سير عمل التدقيق والتهيئة

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

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

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

إذا حفظت خطة بدلًا من تطبيقها أثناء 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 منفصلًا.

ملاحظة Web UI

بعض اتحادات SecretInput أسهل في تهيئتها في وضع المحرر الخام منها في وضع النموذج.

ذات صلة

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