مراجع الأسرار في Vault

يتيح Plugin ‏Vault المضمّن لـ OpenClaw تحليل مراجع الأسرار exec من HashiCorp Vault عند بدء تشغيل Gateway وعند إعادة التحميل. يخزّن OpenClaw مراجع Vault في الإعدادات، ويحتفظ بالقيم المحلولة في لقطة الأسرار داخل الذاكرة، ولا يعيد كتابة مفاتيح API المحلولة إلى openclaw.json. استخدم هذا عندما تكون قد شغّلت Vault بالفعل أو تريد إبقاء مفاتيح موفّري النماذج خارج ملفات إعدادات OpenClaw. للاطلاع على نموذج وقت تشغيل مراجع الأسرار، راجع إدارة الأسرار.

قبل البدء

تحتاج إلى:

OpenClaw مع توفّر Plugin ‏vault المضمّن
خادم Vault يمكن الوصول إليه
مصادقة Vault يمكنها إصدار رمز عميل مميّز يملك صلاحية قراءة مسارات الأسرار التي ينبغي لـ OpenClaw تحليلها
يجب أن تتضمن البيئة التي تبدأ تشغيل Gateway المتغير VAULT_ADDR، وأحد الخيارات التالية: VAULT_TOKEN، أو OPENCLAW_VAULT_AUTH_METHOD=token_file مع VAULT_TOKEN_FILE، أو تسجيل دخول JWT/Kubernetes مُعدّ

يتصل المحلّل بـ Vault عبر HTTP من Node. لا يحتاج Gateway إلى CLI الخاص بـ Vault لتحليل مراجع الأسرار. فعّل Plugin المضمّن قبل تشغيل أوامر openclaw vault:

openclaw plugins enable vault

تخزين مفتاح موفّر في Vault

يستخدم OpenClaw افتراضيًا KV v2 المثبّت عند secret، بما يتوافق مع أمثلة خادم تطوير Vault. بالنسبة إلى Vault في بيئة الإنتاج، عيّن OPENCLAW_VAULT_KV_MOUNT إلى مسار تثبيت KV الفعلي قبل إنشاء معرّفات مراجع الأسرار. باستخدام إعدادات OpenClaw الافتراضية، يقرأ معرّف مرجع السر هذا:

providers/openrouter/apiKey

حقل Vault التالي:

secret/data/providers/openrouter -> apiKey

إحدى طرق إنشائه باستخدام CLI الخاص بـ Vault هي:

export OPENROUTER_API_KEY=<openrouter-api-key>
vault kv put secret/providers/openrouter apiKey="$OPENROUTER_API_KEY"

استخدم رمز عميل مميّزًا مقيّد النطاق لـ OpenClaw، وليس رمز الجذر المميّز. بالنسبة إلى تخطيط KV v2 الافتراضي، تبدو سياسة دنيا لمفاتيح موفّري النماذج كما يلي:

path "secret/data/providers/*" {
  capabilities = ["read"]
}

إتاحة Vault لـ Gateway

بالنسبة إلى Gateway محلي غير موضوع في حاوية، صدّر إعدادات Vault في الصدفة نفسها التي تبدأ تشغيل OpenClaw. تقرأ طريقة المصادقة الافتراضية رمز عميل Vault المميّز من VAULT_TOKEN:

export VAULT_ADDR=https://vault.example.com
export VAULT_TOKEN=<vault-client-token>

إذا كتب Vault Agent رمزًا مميّزًا في ملف إخراج، فاستخدم المصادقة بملف الرمز المميّز:

export VAULT_ADDR=https://vault.example.com
export OPENCLAW_VAULT_AUTH_METHOD=token_file
export VAULT_TOKEN_FILE=/vault/secrets/token

بالنسبة إلى خادم Vault موقّع بواسطة مرجع مصدّق خاص، ثبّت هذا المرجع المصدّق في مخزن ثقة المضيف وفعّل ثقة النظام في Node:

export NODE_USE_SYSTEM_CA=1

أو وفّر حزمة PEM مباشرةً:

export NODE_EXTRA_CA_CERTS=/path/to/vault-ca.pem

يجب أن تكون هذه المتغيرات موجودة عند بدء تشغيل OpenClaw. يمرّرها Plugin ‏Vault إلى عملية المحلّل الخاصة به. للمصادقة غير التفاعلية باستخدام JWT، استخدم ملف JWT لحمل العمل ودورًا في Vault من النوع jwt:

export VAULT_ADDR=https://vault.example.com
export OPENCLAW_VAULT_AUTH_METHOD=jwt
export OPENCLAW_VAULT_AUTH_MOUNT=jwt
export OPENCLAW_VAULT_AUTH_ROLE=openclaw
export OPENCLAW_VAULT_JWT_FILE=/var/run/secrets/tokens/vault

يجب أن يكون ملف JWT رمز حمل عمل مميّزًا مُسقطًا، مثل رمز حساب خدمة Kubernetes مميّز ذي جمهور يقبله دور Vault. يُعد تسجيل دخول OIDC التفاعلي عبر المتصفح مفيدًا للمستخدمين، لكن وقت تشغيل Gateway يحتاج إلى تسجيل دخول JWT غير تفاعلي أو ملف رمز مميّز. بالنسبة إلى طريقة مصادقة Kubernetes في Vault، استخدم kubernetes. وهي مخصّصة لبوابات Gateway التي تعمل بوصفها Pods؛ ويكون التثبيت الافتراضي هو kubernetes، وملف JWT الافتراضي هو مسار رمز حساب الخدمة المميّز القياسي:

export VAULT_ADDR=https://vault.example.com
export OPENCLAW_VAULT_AUTH_METHOD=kubernetes
export OPENCLAW_VAULT_AUTH_ROLE=openclaw

عيّن OPENCLAW_VAULT_AUTH_MOUNT فقط عندما تكون مصادقة Kubernetes في Vault مثبّتة في موضع آخر غير auth/kubernetes. وعيّن OPENCLAW_VAULT_JWT_FILE فقط عندما يكون رمز حساب الخدمة المميّز مُسقطًا في مسار مخصّص. إعدادات اختيارية:

export VAULT_NAMESPACE=<namespace-name>
export OPENCLAW_VAULT_KV_MOUNT=secret
export OPENCLAW_VAULT_KV_VERSION=2

تحقق مما تستطيع الصدفة الحالية رؤيته:

openclaw vault status

عند إعداد أكثر من موفّر أسرار واحد مدعوم من Vault، اختر أحدها بالاسم المستعار:

openclaw vault status --provider-alias corp-vault

لا يطبع openclaw vault status المتغير VAULT_TOKEN مطلقًا؛ بل يبلّغ فقط عما إذا كان الرمز المميّز وملف الرمز المميّز وملف JWT معيّنة أم لا.

إذا كان Gateway يعمل كخدمة أو LaunchAgent أو وحدة systemd أو مهمة مجدولة أو حاوية، فيجب أن تتلقى بيئة وقت التشغيل هذه متغيرات Vault نفسها. إن تعيين المتغيرات في صدفة تفاعلية يثبت عملها في تلك الصدفة فقط، وليس في Gateway قيد التشغيل بالفعل.

إنشاء خطة لمراجع الأسرار وتطبيقها

أنشئ خطة تربط مفتاح API لموفّر نماذج OpenRouter بـ Vault:

openclaw vault setup \
  --plan-out ./vault-secrets-plan.json \
  --openrouter-id providers/openrouter/apiKey

طبّق الخطة وتحقق منها:

openclaw secrets apply --from ./vault-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from ./vault-secrets-plan.json --allow-exec
openclaw secrets audit --check --allow-exec
openclaw secrets reload

استخدم --allow-exec لأن Plugin ‏Vault ينفّذ التحليل عبر موفّر مراجع أسرار exec يديره OpenClaw. إذا لم يكن Gateway قيد التشغيل بعد، فابدأ تشغيله بالطريقة المعتادة بعد تطبيق الخطة بدلًا من تشغيل openclaw secrets reload.

إعداد المزيد من مفاتيح الموفّرين

اختصارات مضمّنة:

openclaw vault setup --openai-id providers/openai/apiKey
openclaw vault setup --anthropic-id providers/anthropic/apiKey
openclaw vault setup --openrouter-id providers/openrouter/apiKey

مفاتيح موفّرين متعددة في خطة واحدة:

openclaw vault setup \
  --plan-out ./vault-secrets-plan.json \
  --openai-id providers/openai/apiKey \
  --anthropic-id providers/anthropic/apiKey \
  --openrouter-id providers/openrouter/apiKey

بالنسبة إلى الموفّرين المضمّنين الذين لا يملكون اختصارات، أو موفّري النماذج المخصّصين والمتوافقين مع OpenAI والمُعدّين مسبقًا، استخدم --provider-key:

openclaw vault setup \
  --plan-out ./vault-secrets-plan.json \
  --provider-key local-openai=providers/local-openai/apiKey \
  --provider-key groq=providers/groq/apiKey

يكتب كل --provider-key <provider=id> مرجع سر في models.providers.<provider>.apiKey. بالنسبة إلى الموفّرين المخصّصين، لا ينشئ هذا الخيار إعدادات الموفّر baseUrl أو api أو models؛ أعدّها أولًا. استخدم --target <path=id> لأي مسار هدف معروف لمرجع سر:

openclaw vault setup \
  --target channels.telegram.botToken=channels/telegram/botToken \
  --target models.providers.openai.headers.x-api-key=providers/openai/proxyKey \
  --target auth-profiles:main:profiles.openai.key=providers/openai/apiKey

تنطبق مسارات الأهداف المجرّدة على openclaw.json. استخدم auth-profiles:<agentId>:<path> لأهداف auth-profiles.json الموجودة. يجب أن يكون مسار الهدف هدفًا مسجّلًا لمراجع أسرار OpenClaw. لا ينشئ أمر الإعداد أسرارًا اعتباطية مسمّاة في OpenClaw؛ إذ يظل Vault مخزن الأسرار، ولا يخزّن OpenClaw مراجع الأسرار إلا في حقول الإعدادات المدعومة.

تنسيق معرّف مرجع السر

تستخدم معرّفات مراجع أسرار Vault الاصطلاح التالي:

<vault-secret-path>/<field>

أمثلة:

معرّف مرجع السر	قراءة Vault الافتراضية باستخدام KV v2	الحقل المُعاد
`providers/openrouter/apiKey`	`secret/data/providers/openrouter`	`apiKey`
`providers/openai/apiKey`	`secret/data/providers/openai`	`apiKey`
`teams/agent-prod/openrouter`	`secret/data/teams/agent-prod`	`openrouter`

يجب أن يكون حقل Vault المُعاد سلسلة نصية. بالنسبة إلى KV v1، عيّن:

export OPENCLAW_VAULT_KV_VERSION=1

عندئذٍ يقرأ providers/openrouter/apiKey:

secret/providers/openrouter -> apiKey

ما يخزّنه OpenClaw

يؤدي تطبيق خطة إعداد Vault إلى تخزين موفّر يديره Plugin:

{
  "source": "exec",
  "pluginIntegration": {
    "pluginId": "vault",
    "integrationId": "vault"
  }
}

تشير حقول بيانات الاعتماد إلى ذلك الموفّر:

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

توجد القيمة المحلولة فقط في لقطة أسرار وقت التشغيل النشطة.

الحاويات وعمليات النشر المُدارة

تستخدم بوابات Gateway الموضوعة في حاويات إعدادات Plugin ومراجع الأسرار نفسها. يجب أن تتلقى الحاوية:

VAULT_ADDR
مصدر مصادقة واحدًا:
- VAULT_TOKEN
- OPENCLAW_VAULT_AUTH_METHOD=token_file بالإضافة إلى VAULT_TOKEN_FILE
- OPENCLAW_VAULT_AUTH_METHOD=jwt بالإضافة إلى OPENCLAW_VAULT_AUTH_MOUNT وOPENCLAW_VAULT_AUTH_ROLE وOPENCLAW_VAULT_JWT_FILE
- OPENCLAW_VAULT_AUTH_METHOD=kubernetes بالإضافة إلى OPENCLAW_VAULT_AUTH_ROLE؛ ويمكن اختياريًا تجاوز OPENCLAW_VAULT_AUTH_MOUNT أو OPENCLAW_VAULT_JWT_FILE
اختياريًا: VAULT_NAMESPACE وOPENCLAW_VAULT_KV_MOUNT وOPENCLAW_VAULT_KV_VERSION

عند استخدام Kubernetes، فضّل OPENCLAW_VAULT_AUTH_METHOD=kubernetes عندما تكون مصادقة Kubernetes في Vault مُعدّة للعنقود. استخدم OPENCLAW_VAULT_AUTH_METHOD=jwt فقط عندما يكون Vault مُعدًّا للتعامل مع العنقود بوصفه جهة إصدار JWT/OIDC عامة. كلا الخيارين أفضل من رمز Vault مميّز طويل الأجل داخل سر Kubernetes. ويمكن لعمليات النشر التي تستخدم Vault Agent كحاوية جانبية أو أداة حقن استخدام token_file بدلًا من ذلك. بالنسبة إلى إعدادات Vault متعددة المستأجرين، احتفظ بتوجيه المستأجرين ضمن سياسة Vault وإعدادات النشر. لا يتطلب OpenClaw تثبيتًا أو دورًا أو مسارًا ثابتًا؛ إذ يمكن لكل بيئة Gateway تعيين قيمها الخاصة لـ OPENCLAW_VAULT_KV_MOUNT وOPENCLAW_VAULT_AUTH_ROLE ومعرّفات مراجع الأسرار. إذا كان لا بد من أن يحل Gateway مشترك واحد أسرار مستخدمي Vault مختلفين في الوقت نفسه، فاستخدم موفّري exec مُعدّين يدويًا يغلّفون بيئات مصادقة منفصلة، أو وزّع المستأجرين على بيئات Gateway ذات بيئات Vault منفصلة.

مراجع أسرار الخزنة

مراجع الأسرار في Vault

قبل البدء

تخزين مفتاح موفّر في Vault

إتاحة Vault لـ Gateway

إنشاء خطة لمراجع الأسرار وتطبيقها

إعداد المزيد من مفاتيح الموفّرين

تنسيق معرّف مرجع السر

ما يخزّنه OpenClaw

الحاويات وعمليات النشر المُدارة

ذو صلة

​مراجع الأسرار في Vault

​قبل البدء

​تخزين مفتاح موفّر في Vault

​إتاحة Vault لـ Gateway

​إنشاء خطة لمراجع الأسرار وتطبيقها

​إعداد المزيد من مفاتيح الموفّرين

​تنسيق معرّف مرجع السر

​ما يخزّنه OpenClaw

​الحاويات وعمليات النشر المُدارة

​ذو صلة

مراجع الأسرار في Vault

قبل البدء

تخزين مفتاح موفّر في Vault

إتاحة Vault لـ Gateway

إنشاء خطة لمراجع الأسرار وتطبيقها

إعداد المزيد من مفاتيح الموفّرين

تنسيق معرّف مرجع السر

ما يخزّنه OpenClaw

الحاويات وعمليات النشر المُدارة

ذو صلة