---
read_when:
    - کار روی حل‌وفصل نمایهٔ احراز هویت یا مسیریابی اعتبارنامه‌ها
    - اشکال‌زدایی از خرابی‌های احراز هویت مدل یا ترتیب پروفایل
summary: معناشناسی واجد شرایط بودن و تفکیک اعتبارنامهٔ کانونی برای پروفایل‌های احراز هویت
title: معناشناسی اعتبارنامه‌های احراز هویت
x-i18n:
    generated_at: "2026-05-07T13:13:24Z"
    model: gpt-5.5
    provider: openai
    source_hash: 2d916ff95ca2ac1fe21e66f64b887b1df1e6b97d7dcc681e5bb9a9dee8ce9473
    source_path: auth-credential-semantics.md
    workflow: 16
---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## حل هدف کاوش

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

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

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

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

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

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

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

`Auth profile credentials are missing or expired.`

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

## مرتبط

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