# openclaw secrets

از openclaw secrets برای مدیریت SecretRefها و سالم نگه داشتن snapshot فعال runtime استفاده کنید.

نقش‌های فرمان:

• reload: RPC مربوط به Gateway (secrets.reload) که refها را دوباره resolve می‌کند و snapshot runtime را فقط در صورت موفقیت کامل جایگزین می‌کند (بدون نوشتن پیکربندی).
• audit: اسکن فقط‌خواندنی storeهای پیکربندی/auth/generated-model و باقی‌مانده‌های legacy برای plaintext، refهای resolveنشده، و drift در precedence (refهای exec نادیده گرفته می‌شوند مگر اینکه --allow-exec تنظیم شده باشد).
• configure: برنامه‌ریز تعاملی برای راه‌اندازی provider، نگاشت target، و preflight (TTY لازم است).
• apply: اجرای یک plan ذخیره‌شده (--dry-run فقط برای اعتبارسنجی؛ dry-run به‌صورت پیش‌فرض بررسی‌های exec را نادیده می‌گیرد، و حالت write planهای دارای exec را رد می‌کند مگر اینکه --allow-exec تنظیم شده باشد)، سپس پاک‌سازی باقی‌مانده‌های plaintext هدف‌گذاری‌شده.

چرخه پیشنهادی برای operator:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

اگر plan شما شامل SecretRefها/providerهای exec است، در هر دو فرمان dry-run و write apply گزینه --allow-exec را ارسال کنید.

نکته exit code برای CI/gateها:

• audit --check در صورت وجود یافته‌ها 1 برمی‌گرداند.
• refهای resolveنشده 2 برمی‌گردانند.

مرتبط:

• راهنمای Secrets: مدیریت Secrets
• سطح credential: سطح Credential مربوط به SecretRef
• راهنمای امنیت: امنیت

# بارگذاری دوباره snapshot runtime

refهای secret را دوباره resolve کنید و snapshot runtime را به‌صورت اتمی جایگزین کنید.

openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

نکته‌ها:

• از متد RPC مربوط به Gateway با نام secrets.reload استفاده می‌کند.
• اگر resolution شکست بخورد، Gateway آخرین snapshot سالم شناخته‌شده را نگه می‌دارد و خطا برمی‌گرداند (بدون فعال‌سازی جزئی).
• پاسخ JSON شامل warningCount است.

گزینه‌ها:

• --url <url>
• --token <token>
• --timeout <ms>
• --json

# Audit

وضعیت OpenClaw را برای موارد زیر اسکن کنید:

• ذخیره‌سازی secret به‌صورت plaintext
• refهای resolveنشده
• drift در precedence (credentialهای auth-profiles.json که refهای openclaw.json را shadow می‌کنند)
• باقی‌مانده‌های agents/*/agent/models.json تولیدشده (مقادیر apiKey برای provider و headerهای حساس provider)
• باقی‌مانده‌های legacy (ورودی‌های store قدیمی auth، یادآورهای OAuth)

نکته درباره باقی‌مانده header:

• تشخیص header حساس provider بر پایه heuristic نام است (نام‌ها و قطعه‌های رایج header مربوط به auth/credential مانند authorization، x-api-key، token، secret، password، و credential).

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

رفتار exit:

• --check در صورت وجود یافته‌ها با مقدار غیرصفر خارج می‌شود.
• refهای resolveنشده با کد غیرصفر دارای اولویت بالاتر خارج می‌شوند.

نکات برجسته شکل گزارش:

• status: clean | findings | unresolved
• resolution: refsChecked, skippedExecRefs, resolvabilityComplete
• summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
• کدهای یافته:
  • PLAINTEXT_FOUND
  • REF_UNRESOLVED
  • REF_SHADOWED
  • LEGACY_RESIDUE

# Configure (helper تعاملی)

تغییرات provider و SecretRef را به‌صورت تعاملی بسازید، preflight را اجرا کنید، و در صورت نیاز apply کنید:

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

جریان:

• ابتدا راه‌اندازی provider (add/edit/remove برای aliasهای secrets.providers).
• سپس نگاشت credential (انتخاب fieldها و تخصیص refهای {source, provider, id}).
• در پایان preflight و apply اختیاری.

flagها:

• --providers-only: فقط secrets.providers را configure کنید و نگاشت credential را نادیده بگیرید.
• --skip-provider-setup: راه‌اندازی provider را نادیده بگیرید و credentialها را به providerهای موجود نگاشت کنید.
• --agent <id>: کشف target و نوشتن در auth-profiles.json را به یک store agent محدود کنید.
• --allow-exec: بررسی‌های exec SecretRef را هنگام preflight/apply مجاز کنید (ممکن است فرمان‌های provider اجرا شوند).

نکته‌ها:

• به TTY تعاملی نیاز دارد.
• نمی‌توانید --providers-only را با --skip-provider-setup ترکیب کنید.
• configure fieldهای دارای secret در openclaw.json به‌همراه auth-profiles.json را برای scope agent انتخاب‌شده هدف می‌گیرد.
• configure از ساخت مستقیم نگاشت‌های جدید auth-profiles.json در جریان picker پشتیبانی می‌کند.
• سطح canonical پشتیبانی‌شده: سطح Credential مربوط به SecretRef.
• پیش از apply، preflight resolution را انجام می‌دهد.
• اگر preflight/apply شامل refهای exec است، --allow-exec را برای هر دو مرحله تنظیم‌شده نگه دارید.
• planهای تولیدشده به‌صورت پیش‌فرض گزینه‌های scrub را فعال دارند (scrubEnv، scrubAuthProfilesForProviderTargets، scrubLegacyAuthJson همگی فعال هستند).
• مسیر apply برای مقادیر plaintext پاک‌سازی‌شده یک‌طرفه است.
• بدون --apply، CLI پس از preflight همچنان Apply this plan now? را prompt می‌کند.
• با --apply (و بدون --yes)، CLI یک confirmation برگشت‌ناپذیر اضافی prompt می‌کند.
• --json plan و گزارش preflight را چاپ می‌کند، اما فرمان همچنان به TTY تعاملی نیاز دارد.

نکته ایمنی provider نوع exec:

• نصب‌های Homebrew اغلب binaryهای symlinkشده را زیر /opt/homebrew/bin/* عرضه می‌کنند.
• allowSymlinkCommand: true را فقط زمانی تنظیم کنید که برای مسیرهای مورد اعتماد package-manager لازم است، و آن را با trustedDirs همراه کنید (برای مثال ["/opt/homebrew"]).
• در Windows، اگر verification مربوط به ACL برای مسیر provider در دسترس نباشد، OpenClaw به‌شکل fail-closed عمل می‌کند. فقط برای مسیرهای مورد اعتماد، روی آن provider گزینه allowInsecurePath: true را تنظیم کنید تا بررسی‌های امنیت مسیر bypass شوند.

# Apply کردن یک plan ذخیره‌شده

plan تولیدشده قبلی را apply یا preflight کنید:

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
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

رفتار exec:

• --dry-run بدون نوشتن fileها، preflight را اعتبارسنجی می‌کند.
• بررسی‌های exec SecretRef به‌صورت پیش‌فرض در dry-run نادیده گرفته می‌شوند.
• حالت write، planهایی را که شامل SecretRefها/providerهای exec هستند رد می‌کند مگر اینکه --allow-exec تنظیم شده باشد.
• برای opt in به بررسی/اجرای provider نوع exec در هر یک از دو حالت، از --allow-exec استفاده کنید.

جزئیات contract مربوط به plan (مسیرهای target مجاز، قواعد اعتبارسنجی، و semantics شکست):

• Contract مربوط به Secrets Apply Plan

مواردی که apply ممکن است به‌روزرسانی کند:

• openclaw.json (targetهای SecretRef + upsert/delete کردن provider)
• auth-profiles.json (scrub کردن provider-target)
• باقی‌مانده‌های legacy auth.json
• کلیدهای secret شناخته‌شده در ~/.openclaw/.env که مقدارهایشان migrate شده‌اند

# چرا backup برای rollback وجود ندارد

secrets apply عمدا rollback backupهایی که شامل مقدارهای plaintext قدیمی باشند نمی‌نویسد.

ایمنی از preflight سخت‌گیرانه + apply تقریبا اتمی با restore درون‌حافظه‌ای best-effort هنگام شکست به دست می‌آید.

# مثال

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

اگر audit --check همچنان یافته‌های plaintext گزارش می‌کند، مسیرهای target گزارش‌شده باقی‌مانده را به‌روزرسانی کنید و audit را دوباره اجرا کنید.

# مرتبط

• مرجع CLI
• مدیریت Secrets