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

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

• 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 تولید می‌کنند.

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

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

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

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

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

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

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

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

پالایش صریح ترتیب احراز هویت

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

حل هدف probe

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

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

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

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

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

پیام‌رسانی سازگار با نسخه قدیمی

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

Auth profile credentials are missing or expired.

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

مرتبط

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