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

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

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

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

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

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

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

لا تُتحقق مراجع 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" }

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

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

# إعداد المزود

عرّف المزودين تحت 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,
      },
    },
    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" } }
}

# أمثلة تكامل 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: {
      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" },
      },
    },
  },
}

{
  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
• الفحص المسبق لكتابة إعدادات Gateway عبر RPC (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 تحديث اللقطة بعد تدوير سر الواجهة الخلفية.
• طريقة Gateway RPC التي تستخدمها مسارات الأوامر هذه: secrets.resolve.

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

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

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

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

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

نموذج السلامة:

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

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

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

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

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

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

# ذو صلة

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