قرارداد طرح اعمال اسرار

این صفحه قرارداد سخت‌گیرانه‌ای را تعریف می‌کند که توسط openclaw secrets apply اعمال می‌شود. اگر هدفی با این قواعد مطابقت نداشته باشد، عملیات اعمال پیش از تغییر هرگونه فایل شکست می‌خورد.

ساختار فایل طرح

openclaw secrets apply --from <plan.json> انتظار آرایه‌ای از اهداف طرح با نام targets را دارد:

{  version: 1,  protocolVersion: 1,  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.openai.apiKey",      pathSegments: ["models", "providers", "openai", "apiKey"],      providerId: "openai",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },    {      type: "auth-profiles.api_key.key",      path: "profiles.openai:default.key",      pathSegments: ["profiles", "openai:default", "key"],      agentId: "main",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },  ],}

openclaw secrets configure طرح‌هایی با این ساختار تولید می‌کند. همچنین می‌توانید طرحی را به‌صورت دستی بنویسید یا ویرایش کنید.

درج یا به‌روزرسانی و حذف ارائه‌دهندگان

طرح‌ها همچنین می‌توانند شامل دو فیلد اختیاری در سطح بالا باشند که نگاشت secrets.providers را هم‌زمان با نوشتن هر هدف تغییر می‌دهند:

• providerUpserts -- شیئی که کلیدهای آن نام‌های مستعار ارائه‌دهندگان هستند. هر مقدار، تعریف یک ارائه‌دهنده است؛ با همان ساختاری که در secrets.providers.<alias> در openclaw.json پذیرفته می‌شود، برای مثال ارائه‌دهنده‌ای از نوع exec یا file.
• providerDeletes -- آرایه‌ای از نام‌های مستعار ارائه‌دهندگان که باید حذف شوند.

providerUpserts پیش از targets اجرا می‌شود؛ بنابراین target.ref.provider می‌تواند به نام مستعار ارائه‌دهنده‌ای ارجاع دهد که همان طرح آن را در providerUpserts معرفی می‌کند. بدون این ترتیب، طرح‌هایی که به نام مستعاری ارجاع می‌دهند که هنوز در openclaw.json پیکربندی نشده است، با خطای provider "<alias>" is not configured شکست می‌خورند.

{  version: 1,  protocolVersion: 1,  providerUpserts: {    onepassword_anthropic: {      source: "exec",      command: "/usr/bin/op",      args: ["read", "op://Vault/Anthropic/credential"],    },  },  providerDeletes: ["legacy_unused_alias"],  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.anthropic.apiKey",      pathSegments: ["models", "providers", "anthropic", "apiKey"],      providerId: "anthropic",      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },    },  ],}

ارائه‌دهندگان exec که از طریق providerUpserts معرفی می‌شوند، همچنان مشمول قواعد رضایت اجرای دستور در رفتار رضایت ارائه‌دهنده Exec هستند: طرح‌های شامل ارائه‌دهندگان exec در حالت نوشتن به --allow-exec نیاز دارند.

دامنه اهداف پشتیبانی‌شده

اهداف طرح برای مسیرهای اعتبارنامه پشتیبانی‌شده در سطح اعتبارنامه SecretRef پذیرفته می‌شوند.

رفتار نوع هدف

target.type باید نوع هدفی شناخته‌شده باشد و target.path نرمال‌شده باید با ساختار مسیر ثبت‌شده آن نوع مطابقت داشته باشد.

برخی انواع هدف، علاوه بر نام نوع معیار خود، برای طرح‌های موجود یک نام مستعار سازگاری را نیز به‌عنوان target.type می‌پذیرند:

قواعد اعتبارسنجی مسیر

هر هدف با تمام قواعد زیر اعتبارسنجی می‌شود:

• type باید نوع هدفی شناخته‌شده باشد.
• path باید مسیری نقطه‌ای و غیرخالی باشد.
• pathSegments را می‌توان حذف کرد. در صورت ارائه، باید دقیقاً به همان مسیر path نرمال شود.
• بخش‌های ممنوع رد می‌شوند: __proto__، prototype، constructor.
• مسیر نرمال‌شده باید با ساختار مسیر ثبت‌شده برای نوع هدف مطابقت داشته باشد.
• اگر providerId یا accountId تنظیم شده باشد، باید با شناسه رمزگذاری‌شده در مسیر مطابقت داشته باشد.
• اهداف auth-profiles.json به agentId نیاز دارند.
• هنگام ایجاد نگاشت جدید auth-profiles.json، authProfileProvider را درج کنید.

رفتار هنگام شکست

اگر اعتبارسنجی هدفی شکست بخورد، عملیات اعمال با خطایی مانند نمونه زیر خاتمه می‌یابد:

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

برای طرح نامعتبر هیچ نوشتنی ثبت نمی‌شود: تفکیک اهداف و اعتبارسنجی مسیر پیش از دست‌کاری هر فایل اجرا می‌شوند. جدا از این، پس از آغاز نوشتن یک طرح معتبر، عملیات اعمال ابتدا از هر فایل دست‌کاری‌شده یک تصویر لحظه‌ای تهیه می‌کند و اگر نوشتن بعدی در همان اجرا شکست بخورد، آن تصاویر را بازیابی می‌کند؛ بنابراین نوشتن ناقص هرگز وضعیت پیکربندی، نمایه احراز هویت یا متغیرهای محیطی را ناهماهنگ باقی نمی‌گذارد.

رفتار رضایت ارائه‌دهنده Exec

• --dry-run به‌طور پیش‌فرض بررسی‌های SecretRef از نوع exec را نادیده می‌گیرد.
• طرح‌های شامل SecretRefها یا ارائه‌دهندگان exec در حالت نوشتن رد می‌شوند، مگر اینکه --allow-exec تنظیم شده باشد.
• هنگام اعتبارسنجی یا اعمال طرح‌های شامل exec، گزینه --allow-exec را هم در فرمان اجرای آزمایشی و هم در فرمان نوشتن وارد کنید.

نکات دامنه زمان اجرا و ممیزی

• ورودی‌های صرفاً ارجاعی auth-profiles.json، یعنی keyRef/tokenRef، در تفکیک اعتبارنامه زمان اجرا و پوشش ممیزی گنجانده می‌شوند.
• secrets apply اهداف پشتیبانی‌شده openclaw.json، اهداف پشتیبانی‌شده auth-profiles.json و سه مرحله پاک‌سازی اختیاری را می‌نویسد که هرکدام به‌طور پیش‌فرض فعال‌اند: scrubEnv (مقادیر متن ساده منتقل‌شده را از .env حذف می‌کند)، scrubAuthProfilesForProviderTargets (باقی‌مانده‌های متن ساده یا ارجاع‌های استفاده‌نشده را در auth-profiles.json برای ارائه‌دهندگانی که طرح به‌تازگی منتقل کرده است پاک می‌کند) و scrubLegacyAuthJson (ورودی‌های منتقل‌شده api_key را از مخازن قدیمی auth.json حذف می‌کند). برای رد کردن هر مرحله، مقدار متناظر options.scrubEnv، options.scrubAuthProfilesForProviderTargets یا options.scrubLegacyAuthJson را در طرح روی false تنظیم کنید.

بررسی‌های راهبر

# Validate plan without writesopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run # Then apply for realopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json # For exec-containing plans, opt in explicitly in both modesopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

اگر عملیات اعمال با پیام مسیر هدف نامعتبر شکست خورد، طرح را با openclaw secrets configure دوباره تولید کنید یا مسیر هدف را به یکی از ساختارهای پشتیبانی‌شده بالا اصلاح کنید.

مستندات مرتبط

• مدیریت اسرار
• CLI ‏secrets
• سطح اعتبارنامه SecretRef
• مرجع پیکربندی