SecretRefهای Vault

Plugin همراه Vault به OpenClaw امکان می‌دهد SecretRefهای exec را هنگام راه‌اندازی و بارگذاری مجدد Gateway از HashiCorp Vault دریافت و تفسیر کند. OpenClaw ارجاع‌های Vault را در پیکربندی ذخیره می‌کند، مقادیر دریافت‌شده را در نمای لحظه‌ای اسرارِ درون‌حافظه‌ای نگه می‌دارد و کلیدهای API دریافت‌شده را دوباره در openclaw.json نمی‌نویسد.

هنگامی از این قابلیت استفاده کنید که از قبل Vault را اجرا می‌کنید یا می‌خواهید کلیدهای ارائه‌دهندگان مدل خارج از فایل‌های پیکربندی OpenClaw نگهداری شوند. برای آشنایی با مدل زمان اجرای SecretRef، به مدیریت اسرار مراجعه کنید.

پیش از شروع

به موارد زیر نیاز دارید:

• OpenClaw با Plugin همراه vault
• یک سرور Vault در دسترس
• احراز هویت Vault که بتواند یک توکن کارخواه با دسترسی خواندن به مسیرهای اسراری که OpenClaw باید دریافت کند، ایجاد کند
• محیطی که Gateway را راه‌اندازی می‌کند باید شامل VAULT_ADDR و یکی از این موارد باشد: VAULT_TOKEN، یا OPENCLAW_VAULT_AUTH_METHOD=token_file همراه با VAULT_TOKEN_FILE، یا ورود پیکربندی‌شده JWT/Kubernetes

حل‌کننده از طریق HTTP و از Node با Vault ارتباط برقرار می‌کند. Gateway برای دریافت و تفسیر SecretRefها به CLI مربوط به Vault نیاز ندارد.

پیش از اجرای فرمان‌های openclaw vault، Plugin همراه را فعال کنید:

openclaw plugins enable vault

ذخیره کلید ارائه‌دهنده در Vault

پیش‌فرض OpenClaw استفاده از KV v2 نصب‌شده در secret است که با نمونه‌های سرور توسعه Vault مطابقت دارد. برای Vault عملیاتی، پیش از ایجاد شناسه‌های SecretRef، مقدار OPENCLAW_VAULT_KV_MOUNT را روی مسیر واقعی نصب KV خود تنظیم کنید. با پیش‌فرض‌های OpenClaw، این شناسه SecretRef:

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.comexport VAULT_TOKEN=<vault-client-token>

اگر Vault Agent توکن را در یک فایل مقصد می‌نویسد، از احراز هویت مبتنی بر فایل توکن استفاده کنید:

export VAULT_ADDR=https://vault.example.comexport OPENCLAW_VAULT_AUTH_METHOD=token_fileexport 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.comexport OPENCLAW_VAULT_AUTH_METHOD=jwtexport OPENCLAW_VAULT_AUTH_MOUNT=jwtexport OPENCLAW_VAULT_AUTH_ROLE=openclawexport OPENCLAW_VAULT_JWT_FILE=/var/run/secrets/tokens/vault

فایل JWT باید یک توکن بارکاری فرافکنی‌شده باشد؛ برای مثال، توکن حساب سرویس Kubernetes با مخاطبی که نقش Vault آن را می‌پذیرد. ورود تعاملی OIDC از طریق مرورگر برای کاربران انسانی مفید است، اما زمان اجرای Gateway به ورود غیرتعاملی JWT یا یک فایل توکن نیاز دارد.

برای روش احراز هویت Kubernetes در Vault، از kubernetes استفاده کنید. این روش برای Gatewayهایی در نظر گرفته شده است که به‌شکل Pod اجرا می‌شوند؛ محل نصب پیش‌فرض kubernetes و فایل JWT پیش‌فرض، مسیر استاندارد توکن حساب سرویس است:

export VAULT_ADDR=https://vault.example.comexport OPENCLAW_VAULT_AUTH_METHOD=kubernetesexport 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=secretexport OPENCLAW_VAULT_KV_VERSION=2

بررسی کنید پوسته فعلی چه مواردی را می‌تواند ببیند:

openclaw vault status

هنگامی که بیش از یک ارائه‌دهنده اسرار مبتنی بر Vault پیکربندی شده است، یکی را با نام مستعار انتخاب کنید:

openclaw vault status --provider-alias corp-vault

فرمان openclaw vault status هرگز VAULT_TOKEN را چاپ نمی‌کند؛ فقط گزارش می‌دهد که آیا توکن، فایل توکن و فایل JWT تنظیم شده‌اند یا خیر.

ایجاد و اعمال طرح SecretRef

طرحی ایجاد کنید که کلید 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-execopenclaw secrets apply --from ./vault-secrets-plan.json --allow-execopenclaw secrets audit --check --allow-execopenclaw secrets reload

از --allow-exec استفاده کنید، زیرا Plugin مربوط به Vault عملیات دریافت و تفسیر را از طریق یک ارائه‌دهنده SecretRef از نوع exec و مدیریت‌شده توسط OpenClaw انجام می‌دهد.

اگر Gateway هنوز در حال اجرا نیست، پس از اعمال طرح، به‌جای اجرای openclaw secrets reload آن را به روش معمول راه‌اندازی کنید.

پیکربندی کلیدهای بیشتر ارائه‌دهندگان

میان‌برهای داخلی:

openclaw vault setup --openai-id providers/openai/apiKeyopenclaw vault setup --anthropic-id providers/anthropic/apiKeyopenclaw 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> یک SecretRef را در models.providers.<provider>.apiKey می‌نویسد. برای ارائه‌دهندگان سفارشی، این گزینه تنظیمات baseUrl، api یا models ارائه‌دهنده را ایجاد نمی‌کند؛ ابتدا آن‌ها را پیکربندی کنید.

برای هر مسیر مقصد شناخته‌شده SecretRef از --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.json از auth-profiles:<agentId>:<path> استفاده کنید. مسیر مقصد باید یک مقصد ثبت‌شده SecretRef در OpenClaw باشد. فرمان راه‌اندازی، اسرار نام‌گذاری‌شده دلخواهی را در OpenClaw ایجاد نمی‌کند؛ Vault همچنان مخزن اسرار باقی می‌ماند و OpenClaw فقط SecretRefها را در فیلدهای پیکربندی پشتیبانی‌شده ذخیره می‌کند.

قالب شناسه SecretRef

شناسه‌های SecretRef مربوط به Vault از این قرارداد استفاده می‌کنند:

<vault-secret-path>/<field>

نمونه‌ها:

فیلد بازگردانده‌شده 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 و پیکربندی SecretRef استفاده می‌کنند. کانتینر باید این موارد را دریافت کند:

• 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، اگر احراز هویت Kubernetes در Vault برای خوشه پیکربندی شده است، OPENCLAW_VAULT_AUTH_METHOD=kubernetes را ترجیح دهید. فقط هنگامی از OPENCLAW_VAULT_AUTH_METHOD=jwt استفاده کنید که Vault برای درنظرگرفتن خوشه به‌عنوان صادرکننده عمومی JWT/OIDC پیکربندی شده باشد. هر دو گزینه از یک توکن بلندمدت Vault در Kubernetes Secret بهترند. استقرارهای مبتنی بر همراه جانبی یا تزریق‌کننده Vault Agent می‌توانند به‌جای آن از token_file استفاده کنند.

برای راه‌اندازی‌های چندمستأجری Vault، مسیریابی مستأجر را در خط‌مشی Vault و پیکربندی استقرار نگه دارید. OpenClaw به محل نصب، نقش یا مسیر ثابتی نیاز ندارد: هر محیط Gateway می‌تواند OPENCLAW_VAULT_KV_MOUNT، OPENCLAW_VAULT_AUTH_ROLE و شناسه‌های SecretRef خود را تنظیم کند. اگر یک Gateway مشترک باید هم‌زمان اسرار کاربران متفاوت Vault را دریافت و تفسیر کند، از ارائه‌دهندگان exec با پیکربندی دستی استفاده کنید که محیط‌های احراز هویت مجزا را دربر می‌گیرند، یا مستأجران را میان محیط‌های Gateway با محیط‌های Vault جداگانه تقسیم کنید.

مطالب مرتبط

• مدیریت اسرار
• openclaw secrets
• فهرست Pluginها