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