معنای اطلاعات احراز هویت

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

• 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. ارجاع‌های تفکیک‌ناپذیر، unresolved_ref را در خروجی models status --probe ایجاد می‌کنند.

انتقال‌پذیری کپی عامل

وراثت احراز هویت عامل به‌صورت خواندن عبوری انجام می‌شود. وقتی یک عامل پروفایل محلی ندارد، پروفایل‌ها را هنگام اجرا از مخزن عامل پیش‌فرض/اصلی تفکیک می‌کند، بدون آنکه محتوای محرمانه را در مخزن اطلاعات اعتباری خودش کپی کند (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 خارجی مبتنی بر فایل استفاده می‌کنند و نتایج macOS Keychain را نمی‌خوانند یا دوباره استفاده نمی‌کنند.

محافظ خط‌مشی 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]: ... می‌آیند.

مرتبط

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