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

این معناشناسی‌ها رفتار احراز هویت در زمان انتخاب و زمان اجرا را هم‌راستا نگه می‌دارند. آن‌ها میان موارد زیر مشترک‌اند:

• resolveAuthProfileOrder (ترتیب پروفایل‌ها)
• resolveApiKeyForProfile (تفکیک اعتبارنامه در زمان اجرا)
• openclaw models status --probe
• بررسی‌های احراز هویت openclaw doctor (doctor-auth)

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

نتایج کاوش شامل یک دستهٔ status (ok، auth، rate_limit، billing، timeout، format، unknown، no_model) به‌همراه یک reasonCode پایدار هستند، در صورتی که کاوش هرگز به فراخوانی مدل نرسیده باشد:

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

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

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

قواعد واجد شرایط بودن

1. وقتی هر دو token و tokenRef وجود نداشته باشند، پروفایل توکن واجد شرایط نیست (missing_credential).
2. expires اختیاری است. در صورت وجود، باید عددی متناهی از میلی‌ثانیه‌های دورهٔ Unix، بزرگ‌تر از 0 و حداکثر برابر با بیشینهٔ مُهر زمانی Date در JavaScript (8640000000000000) باشد.
3. اگر expires نامعتبر باشد (نوع نادرست، NaN، 0، منفی، نامتناهی یا فراتر از آن بیشینه)، پروفایل با invalid_expires واجد شرایط نیست.
4. اگر زمان expires گذشته باشد، پروفایل با expired واجد شرایط نیست.
5. tokenRef اعتبارسنجی expires را دور نمی‌زند.

قواعد تفکیک

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

قابلیت انتقال رونوشت عامل

وراثت احراز هویت عامل به‌صورت خواندن مستقیم است. وقتی یک عامل پروفایل محلی ندارد، در زمان اجرا پروفایل‌ها را از مخزن عامل پیش‌فرض/اصلی تفکیک می‌کند، بدون آنکه محتوای محرمانه را در مخزن اعتبارنامهٔ خودش (agents/<agentId>/agent/openclaw-agent.sqlite) کپی کند.

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

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

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

مسیرهای احراز هویت صرفاً پیکربندی‌شده

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

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

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

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

تفکیک مقصد کاوش

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

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

• اعتبارنامه‌های صرفاً زمان اجرا که متعلق به CLIهای خارجی‌اند (Claude CLI برای claude-cli، Codex CLI برای openai و MiniMax CLI برای minimax-portal) فقط زمانی کشف می‌شوند که ارائه‌دهنده، محیط اجرا یا پروفایل احراز هویت در دامنهٔ عملیات جاری باشد، یا از قبل یک پروفایل محلی ذخیره‌شده برای آن منبع خارجی وجود داشته باشد.
• فراخوان‌های مخزن احراز هویت یک حالت صریح کشف CLI خارجی را انتخاب می‌کنند: none فقط برای احراز هویت ماندگار/Plugin، existing برای نوسازی پروفایل‌های CLI خارجی از قبل ذخیره‌شده، یا scoped برای مجموعه‌ای مشخص از ارائه‌دهنده‌ها/پروفایل‌ها.
• مسیرهای فقط‌خواندنی/وضعیت، allowKeychainPrompt: false را ارسال می‌کنند؛ آن‌ها فقط از اعتبارنامه‌های CLI خارجی مبتنی بر فایل استفاده می‌کنند و نتایج Keychain در macOS را نمی‌خوانند یا دوباره استفاده نمی‌کنند.

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

ورودی SecretRef فقط برای اعتبارنامه‌های ایستا است. اعتبارنامه‌های OAuth در زمان اجرا تغییرپذیرند (جریان‌های نوسازی، توکن‌های چرخش‌یافته را ماندگار می‌کنند)، بنابراین محتوای OAuth مبتنی بر SecretRef وضعیت تغییرپذیر را میان مخزن‌ها تقسیم می‌کند.

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

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

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

Auth profile credentials are missing or expired.

جزئیات خوانا برای انسان و کد پایدار دلیل، در خط‌های بعدی به‌شکل ↳ Auth reason [code]: ... می‌آیند.

مرتبط

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