---
read_when:
    - کار روی تفکیک پروفایل احراز هویت یا مسیریابی اعتبارنامه‌ها
    - اشکال‌زدایی از خرابی‌های احراز هویت مدل یا ترتیب پروفایل
summary: معناشناسی معیارهای صلاحیت و حل‌وفصل اعتبارنامه‌های متعارف برای پروفایل‌های احراز هویت
title: معناشناسی اعتبارنامه‌های احراز هویت
x-i18n:
    generated_at: "2026-06-27T17:09:06Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 591c0384e1d43512252aaa7b362141b6bc93183b30b5847168758f86127f0663
    source_path: auth-credential-semantics.md
    workflow: 16
---

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

- `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.`

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

## مرتبط

- [مدیریت اسرار](/fa/gateway/secrets)
- [ذخیره‌سازی احراز هویت](/fa/concepts/oauth)