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

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

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

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

# کدهای دلیل پایدار probe

• 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. معنای حل‌کننده برای expires با معنای واجد شرایط بودن یکسان است.
2. برای پروفایل‌های واجد شرایط، ماده توکن می‌تواند از مقدار درون‌خطی یا tokenRef حل‌وفصل شود.
3. ارجاع‌های غیرقابل حل در خروجی models status --probe مقدار unresolved_ref تولید می‌کنند.

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

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

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

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

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

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

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

# حل‌وفصل هدف probe

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

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

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

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

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

# پیام‌رسانی سازگار با legacy

برای سازگاری script، خط اول خطاهای probe بدون تغییر می‌ماند:

Auth profile credentials are missing or expired.

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

# مرتبط

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