معناشناسی اعتبارنامه‌های احراز هویت

این سند معناشناسی معیار صلاحیت و حل اعتبارنامه را که در موارد زیر استفاده می‌شود تعریف می‌کند:

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

هدف این است که رفتار زمان انتخاب و زمان اجرا هم‌راستا بماند.

کدهای پایدار دلیل کاوش

• ok
• excluded_by_auth_order
• missing_credential
• invalid_expires
• expired
• unresolved_ref
• no_model

اعتبارنامه‌های توکن

اعتبارنامه‌های توکن (type: "token") از token درون‌خطی و/یا tokenRef پشتیبانی می‌کنند.

قواعد صلاحیت

1. وقتی هر دو token و tokenRef غایب باشند، یک پروفایل توکن فاقد صلاحیت است.
2. expires اختیاری است.
3. اگر expires وجود داشته باشد، باید عددی متناهی و بزرگ‌تر از 0 باشد.
4. اگر expires نامعتبر باشد (NaN، 0، منفی، نامتناهی، یا از نوع نادرست)، پروفایل با invalid_expires فاقد صلاحیت است.
5. اگر expires در گذشته باشد، پروفایل با expired فاقد صلاحیت است.
6. tokenRef اعتبارسنجی expires را دور نمی‌زند.

قواعد حل

1. معناشناسی resolver با معناشناسی صلاحیت برای expires مطابقت دارد.
2. برای پروفایل‌های واجد صلاحیت، ماده توکن ممکن است از مقدار درون‌خطی یا tokenRef حل شود.
3. ارجاع‌های حل‌نشدنی در خروجی models status --probe مقدار unresolved_ref تولید می‌کنند.

قابلیت حمل کپی agent

وراثت احراز هویت agent به‌صورت read-through است. وقتی یک agent پروفایل محلی ندارد، می‌تواند در زمان اجرا پروفایل‌ها را از store پیش‌فرض/اصلی agent بدون کپی کردن ماده محرمانه در auth-profiles.json خودش حل کند.

جریان‌های کپی صریح، مانند openclaw agents add، از این سیاست قابلیت حمل استفاده می‌کنند:

• پروفایل‌های api_key قابل حمل هستند مگر اینکه copyToAgents: false باشد.
• پروفایل‌های token قابل حمل هستند مگر اینکه copyToAgents: false باشد.
• پروفایل‌های oauth به‌صورت پیش‌فرض قابل حمل نیستند، زیرا refresh tokenها می‌توانند یک‌بارمصرف یا حساس به چرخش باشند.
• جریان‌های OAuth متعلق به provider فقط زمانی می‌توانند با copyToAgents: true فعال شوند که امن بودن کپی ماده refresh بین agentها معلوم باشد.

پروفایل‌های غیرقابل حمل از طریق وراثت read-through همچنان در دسترس می‌مانند، مگر اینکه agent هدف جداگانه وارد سیستم شود و پروفایل محلی خودش را بسازد.

مسیرهای احراز هویت فقط پیکربندی

ورودی‌های auth.profiles با mode: "aws-sdk" فراداده مسیریابی هستند، نه اعتبارنامه‌های ذخیره‌شده. آن‌ها زمانی معتبرند که provider هدف از models.providers.<id>.auth: "aws-sdk" یا مسیر پیش‌فرض داخلی AWS SDK برای Amazon Bedrock استفاده کند. این شناسه‌های پروفایل حتی وقتی ورودی متناظری در auth-profiles.json وجود ندارد، ممکن است در auth.order و overrideهای نشست ظاهر شوند.

type: "aws-sdk" را در auth-profiles.json ننویسید. اگر یک نصب legacy چنین نشانه‌ای داشته باشد، openclaw doctor --fix آن را به auth.profiles منتقل می‌کند و نشانه را از store اعتبارنامه حذف می‌کند.

فیلتر کردن صریح ترتیب احراز هویت

• وقتی auth.order.<provider> یا override ترتیب auth-store برای یک provider تنظیم شده باشد، models status --probe فقط شناسه‌های پروفایلی را کاوش می‌کند که در ترتیب احراز هویت حل‌شده برای آن provider باقی مانده‌اند.
• پروفایل ذخیره‌شده برای آن provider که از ترتیب صریح حذف شده باشد، بعدا به‌صورت پنهانی امتحان نمی‌شود. خروجی کاوش آن را با reasonCode: excluded_by_auth_order و جزئیات Excluded by auth.order for this provider. گزارش می‌کند.

حل هدف کاوش

• هدف‌های کاوش می‌توانند از پروفایل‌های احراز هویت، اعتبارنامه‌های محیطی، یا models.json بیایند.
• اگر یک provider اعتبارنامه داشته باشد اما OpenClaw نتواند گزینه مدل قابل کاوشی برای آن حل کند، models status --probe مقدار status: no_model را با reasonCode: no_model گزارش می‌کند.

کشف اعتبارنامه CLI خارجی

• اعتبارنامه‌های فقط زمان اجرا که متعلق به CLIهای خارجی هستند، فقط زمانی کشف می‌شوند که provider، زمان اجرا، یا پروفایل احراز هویت در دامنه عملیات فعلی باشد، یا زمانی که یک پروفایل محلی ذخیره‌شده برای آن منبع خارجی از قبل وجود داشته باشد.
• فراخوان‌های auth-store باید یک حالت کشف external-CLI صریح انتخاب کنند: none برای احراز هویت ماندگار/Plugin فقط، existing برای نوسازی پروفایل‌های CLI خارجی که از قبل ذخیره شده‌اند، یا scoped برای مجموعه مشخصی از provider/profile.
• مسیرهای فقط‌خواندنی/وضعیت مقدار allowKeychainPrompt: false را ارسال می‌کنند؛ آن‌ها فقط از اعتبارنامه‌های CLI خارجی مبتنی بر فایل استفاده می‌کنند و نتایج macOS Keychain را نمی‌خوانند یا دوباره استفاده نمی‌کنند.

محافظ سیاست OAuth SecretRef

• ورودی SecretRef فقط برای اعتبارنامه‌های ایستا است.
• اگر اعتبارنامه پروفایل type: "oauth" باشد، اشیای SecretRef برای ماده اعتبارنامه آن پروفایل پشتیبانی نمی‌شوند.
• اگر auth.profiles.<id>.mode برابر "oauth" باشد، ورودی keyRef/tokenRef مبتنی بر SecretRef برای آن پروفایل رد می‌شود.
• نقض‌ها در مسیرهای حل احراز هویت startup/reload خطاهای قطعی هستند.

پیام‌رسانی سازگار با Legacy

برای سازگاری اسکریپت، خط نخست خطاهای کاوش بدون تغییر می‌ماند:

Auth profile credentials are missing or expired.

جزئیات مناسب برای انسان و کدهای دلیل پایدار ممکن است در خط‌های بعدی اضافه شوند.

مرتبط

• مدیریت اسرار
• ذخیره‌سازی احراز هویت