---
read_when:
    - می‌خواهید OAuth در OpenClaw را به‌صورت سرتاسری درک کنید
    - با مشکل بی‌اعتبار شدن توکن / خروج از حساب مواجه می‌شوید
    - شما جریان‌های احراز هویت Claude CLI یا OAuth را می‌خواهید
    - چندین حساب یا مسیریابی نمایه می‌خواهید
summary: 'OAuth در OpenClaw: تبادل و ذخیره‌سازی توکن و الگوهای چندحسابی'
title: OAuth
x-i18n:
    generated_at: "2026-07-12T09:59:31Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 51aa98a9cb9614107ce979eca235c175a1748df2facdded852cd8899cebba22c
    source_path: concepts/oauth.md
    workflow: 16
---

OpenClaw از OAuth («احراز هویت اشتراکی») برای ارائه‌دهندگانی که آن را عرضه می‌کنند پشتیبانی می‌کند،
به‌ویژه **OpenAI Codex (ChatGPT OAuth)** و **استفادهٔ مجدد از Anthropic Claude CLI**.
برای Anthropic، تفکیک عملی به این صورت است:

- **کلید API شرکت Anthropic**: صورت‌حساب عادی API شرکت Anthropic.
- **Anthropic Claude CLI / احراز هویت اشتراکی درون OpenClaw**: کارکنان Anthropic
  به ما گفته‌اند که این نوع استفاده دوباره مجاز است، بنابراین OpenClaw استفادهٔ مجدد از Claude CLI و
  استفاده از `claude -p` را برای این یکپارچه‌سازی مجاز تلقی می‌کند، مگر اینکه Anthropic
  سیاست جدیدی منتشر کند. برای استفاده از Anthropic در محیط عملیاتی، احراز هویت با کلید API همچنان
  مسیر پیشنهادی و ایمن‌تر است.

OpenClaw هم احراز هویت با کلید API شرکت OpenAI و هم ChatGPT/Codex OAuth را زیر شناسهٔ
اصلی ارائه‌دهنده، یعنی `openai`، ذخیره می‌کند. شناسه‌های قدیمی نمایه با الگوی `openai-codex:*` و
ورودی‌های `auth.order.openai-codex` وضعیت قدیمی‌ای هستند که با
`openclaw doctor --fix` اصلاح می‌شوند؛ برای پیکربندی جدید از شناسه‌های نمایهٔ `openai:*` و
`auth.order.openai` استفاده کنید.

این صفحه موارد زیر را پوشش می‌دهد:

- نحوهٔ کار **تبادل توکن** در OAuth ‏(PKCE)
- محل **ذخیره‌سازی** توکن‌ها و دلیل آن
- نحوهٔ مدیریت **چند حساب** (نمایه‌ها + بازنویسی‌های مختص هر نشست)

Pluginهای ارائه‌دهنده که جریان OAuth یا کلید API خود را ارائه می‌کنند، از همان
نقطهٔ ورود اجرا می‌شوند:

```bash
openclaw models auth login --provider <id>
```

## مخزن توکن (چرا وجود دارد)

ارائه‌دهندگان OAuth معمولاً در هر ورود یا نوسازی، یک توکن نوسازی جدید صادر می‌کنند.
برخی ارائه‌دهندگان با صدور توکن جدید برای همان کاربر/برنامه، توکن نوسازی قبلی را
باطل می‌کنند. نشانهٔ عملی: از طریق OpenClaw _و_
Claude Code / Codex CLI وارد می‌شوید و بعداً یکی از آن‌ها به‌طور تصادفی از حساب خارج می‌شود.

برای کاهش این مشکل، OpenClaw مخزن نمایه‌های احراز هویت را به‌عنوان یک **مخزن توکن** در نظر می‌گیرد:

- محیط اجرا اعتبارنامه‌ها را برای هر عامل از یک محل می‌خواند
- چند نمایه می‌توانند هم‌زمان وجود داشته باشند و به‌شکلی قطعی مسیریابی شوند
- استفادهٔ مجدد از CLI خارجی مختص ارائه‌دهنده است: وقتی OpenClaw مالک یک نمایهٔ محلی OAuth
  برای یک ارائه‌دهنده باشد، توکن نوسازی محلی مرجع اصلی است. اگر آن توکن
  نوسازی محلی رد شود، OpenClaw به‌جای بازگشت به دادهٔ توکن CLI خارجی، نمایه را برای
  احراز هویت مجدد گزارش می‌کند.
  راه‌اندازی اولیهٔ Codex CLI حتی محدودتر است: فقط پیش از آنکه OpenClaw مالک OAuth آن
  ارائه‌دهنده شود، می‌تواند یک نمایهٔ خالی به سبک
  `openai:default` را مقداردهی اولیه کند؛ پس از آن، نوسازی‌های تحت مالکیت OpenClaw مرجع اصلی باقی می‌مانند
- مسیرهای وضعیت/راه‌اندازی، کشف CLI خارجی را به مجموعهٔ ارائه‌دهندگانی محدود می‌کنند
  که از قبل پیکربندی شده‌اند؛ بنابراین در راه‌اندازی تک‌ارائه‌دهنده‌ای، مخزن ورود یک CLI
  نامرتبط بررسی نمی‌شود

## ذخیره‌سازی (توکن‌ها کجا قرار دارند)

اسرار به‌ازای هر عامل و با نام منطقی `auth-profiles.json` نگهداری می‌شوند (مخزن
زیربنایی، پایگاه‌دادهٔ SQLite عامل است؛ نام JSON برای
سازگاری و نمایش در ابزارها حفظ شده است):

- نمایه‌های احراز هویت (OAuth + کلیدهای API + ارجاع‌های اختیاری در سطح مقدار):
  `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- فایل سازگاری قدیمی: `~/.openclaw/agents/<agentId>/agent/auth.json`
  (ورودی‌های ایستای `api_key` هنگام شناسایی پاک‌سازی می‌شوند)

فایل قدیمیِ صرفاً مخصوص واردسازی (همچنان پشتیبانی می‌شود، اما مخزن اصلی نیست):

- `~/.openclaw/credentials/oauth.json` (در نخستین استفاده به مخزن نمایهٔ احراز هویت وارد می‌شود)

همهٔ موارد بالا از `$OPENCLAW_STATE_DIR` نیز پیروی می‌کنند (بازنویسی پوشهٔ وضعیت). مرجع کامل: [/gateway/configuration-reference#auth-storage](/fa/gateway/configuration-reference#auth-storage)

برای ارجاع‌های ایستای اسرار و رفتار فعال‌سازی تصویر لحظه‌ای محیط اجرا، به [مدیریت اسرار](/fa/gateway/secrets) مراجعه کنید.

وقتی یک عامل ثانویه نمایهٔ احراز هویت محلی ندارد، OpenClaw از وراثت
خواندنی از مخزن عامل پیش‌فرض/اصلی استفاده می‌کند؛ هنگام خواندن، مخزن عامل اصلی را
همانندسازی نمی‌کند. توکن‌های نوسازی OAuth به‌ویژه حساس هستند: جریان‌های عادی
کپی به‌طور پیش‌فرض آن‌ها را نادیده می‌گیرند، زیرا برخی ارائه‌دهندگان توکن‌های
نوسازی را پس از استفاده تعویض یا باطل می‌کنند. وقتی عاملی به یک حساب مستقل
نیاز دارد، یک ورود OAuth جداگانه برای آن پیکربندی کنید.

## استفادهٔ مجدد از Anthropic Claude CLI

OpenClaw از استفادهٔ مجدد از Anthropic Claude CLI و `claude -p` به‌عنوان یک مسیر
مجاز احراز هویت پشتیبانی می‌کند. اگر از قبل روی میزبان ورود محلی Claude دارید،
فرایند راه‌اندازی اولیه/پیکربندی می‌تواند مستقیماً از آن استفاده کند. توکن راه‌اندازی Anthropic
همچنان به‌عنوان یک مسیر پشتیبانی‌شدهٔ احراز هویت با توکن در دسترس است، اما OpenClaw در صورت
وجود، استفادهٔ مجدد از Claude CLI را ترجیح می‌دهد.

<Warning>
مستندات عمومی Claude Code شرکت Anthropic می‌گویند استفادهٔ مستقیم از Claude Code درون
محدودیت‌های اشتراک Claude باقی می‌ماند، و کارکنان Anthropic به ما گفته‌اند استفاده از Claude
CLI به سبک OpenClaw دوباره مجاز است. بنابراین OpenClaw استفادهٔ مجدد از Claude CLI و
استفاده از `claude -p` را برای این یکپارچه‌سازی مجاز تلقی می‌کند، مگر اینکه Anthropic
سیاست جدیدی منتشر کند.

برای مستندات فعلی طرح‌های استفادهٔ مستقیم از Claude Code در Anthropic، به [استفاده از Claude Code
با طرح Pro یا Max
خود](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
و [استفاده از Claude Code با طرح Team یا Enterprise
خود](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/) مراجعه کنید.

اگر گزینه‌های اشتراکی دیگری در OpenClaw می‌خواهید، به [OpenAI
Codex](/fa/providers/openai)، [طرح کدنویسی ابری Qwen
](/fa/providers/qwen)، [طرح کدنویسی MiniMax](/fa/providers/minimax)،
و [طرح کدنویسی Z.AI / GLM](/fa/providers/zai) مراجعه کنید.
</Warning>

## تبادل OAuth (ورود چگونه انجام می‌شود)

جریان‌های ورود تعاملی OpenClaw در `openclaw/plugin-sdk/llm.ts` پیاده‌سازی شده‌اند و به راهنماهای گام‌به‌گام/فرمان‌ها متصل هستند.

### توکن راه‌اندازی Anthropic

ساختار جریان:

1. توکن راه‌اندازی Anthropic را از OpenClaw آغاز کنید یا توکن را جای‌گذاری کنید
2. OpenClaw اعتبارنامهٔ حاصل از Anthropic را در یک نمایهٔ احراز هویت ذخیره می‌کند
3. انتخاب مدل روی `anthropic/...` باقی می‌ماند
4. نمایه‌های احراز هویت موجود Anthropic برای بازگشت به وضعیت قبلی/کنترل ترتیب همچنان در دسترس می‌مانند

### OpenAI Codex (ChatGPT OAuth)

OAuth در OpenAI Codex صراحتاً برای استفاده خارج از Codex CLI، از جمله جریان‌های کاری OpenClaw، پشتیبانی می‌شود.

فرمان ورود از شناسهٔ اصلی ارائه‌دهندهٔ OpenAI استفاده می‌کند:

```bash
openclaw models auth login --provider openai
```

برای چند حساب ChatGPT/Codex OAuth در یک عامل، از `--profile-id openai:<name>` استفاده کنید.
برای نمایه‌های جدید از `openai-codex:<name>` استفاده نکنید. Doctor
آن پیشوند قدیمی را به یک شناسهٔ نمایهٔ `openai:*` بدون تداخل منتقل می‌کند؛ پس از اصلاح و پیش از کپی‌کردن
شناسه‌های نمایه در `auth.order` یا `/model ...@<profileId>`، فرمان
`openclaw models auth list --provider openai` را اجرا کنید.

ساختار جریان (PKCE):

1. یک تأییدکننده/چالش PKCE و یک `state` تصادفی تولید کنید
2. نشانی `https://auth.openai.com/oauth/authorize?...` را باز کنید (دامنهٔ دسترسی
   `openid profile email offline_access`)
3. تلاش کنید فراخوان بازگشتی را در `http://localhost:1455/auth/callback` دریافت کنید (میزبان
   فراخوان بازگشتی به‌طور پیش‌فرض `localhost` است و فقط میزبان‌های local loopback را می‌پذیرد؛
   با `OPENCLAW_OAUTH_CALLBACK_HOST` بازنویسی کنید)
4. اگر می‌توانید پیش از رسیدن فراخوان بازگشتی یک کد جای‌گذاری کنید (یا به‌صورت
   راه‌دور/بدون رابط گرافیکی هستید و فراخوان بازگشتی نمی‌تواند متصل شود)، به‌جای آن نشانی تغییرمسیر/کد را
   جای‌گذاری کنید — جای‌گذاری دستی با فراخوان بازگشتی مرورگر رقابت می‌کند و هرکدام زودتر کامل شود،
   برنده است
5. کد را در `https://auth.openai.com/oauth/token` مبادله کنید
6. `accountId` را از توکن دسترسی استخراج و `{ access, refresh, expires, accountId }` را ذخیره کنید

مسیر راهنمای گام‌به‌گام `openclaw onboard` ← انتخاب احراز هویت `openai` است.

## نوسازی + انقضا

نمایه‌ها یک مُهر زمانی `expires` ذخیره می‌کنند. در زمان اجرا:

- اگر `expires` در آینده باشد، از توکن دسترسی ذخیره‌شده استفاده کنید
- اگر منقضی شده باشد، آن را نوسازی کنید (تحت قفل فایل) و اعتبارنامه‌های ذخیره‌شده را بازنویسی کنید
- اگر یک عامل ثانویه نمایهٔ OAuth ارث‌بری‌شده از عامل اصلی را بخواند،
  نوسازی به‌جای کپی‌کردن توکن نوسازی در مخزن عامل ثانویه، در مخزن
  عامل اصلی نوشته می‌شود
- اعتبارنامه‌های CLI که به‌صورت خارجی مدیریت می‌شوند (Claude CLI و راه‌اندازی اولیهٔ محدود Codex CLI؛
  به [مخزن توکن](#the-token-sink-why-it-exists) مراجعه کنید) به‌جای مصرف
  یک توکن نوسازی کپی‌شده، دوباره خوانده می‌شوند. اگر نوسازی مدیریت‌شده ناموفق باشد، OpenClaw
  به‌جای بازگرداندن دادهٔ توکن CLI خارجی، نمایهٔ تحت‌تأثیر را برای احراز هویت مجدد
  گزارش می‌کند.

جریان نوسازی خودکار است؛ معمولاً نیازی نیست توکن‌ها را به‌صورت دستی مدیریت کنید.

## چند حساب (نمایه‌ها) + مسیریابی

دو الگو:

### ۱) ترجیحی: عامل‌های جداگانه

اگر می‌خواهید حساب‌های «شخصی» و «کاری» هرگز با هم تعامل نداشته باشند، از عامل‌های مجزا استفاده کنید (نشست‌ها + اعتبارنامه‌ها + فضای کاری جداگانه):

```bash
openclaw agents add work
openclaw agents add personal
```

سپس احراز هویت را برای هر عامل پیکربندی کنید (راهنمای گام‌به‌گام) و گفت‌وگوها را به عامل درست هدایت کنید.

### ۲) پیشرفته: چند نمایه در یک عامل

مخزن نمایهٔ احراز هویت از چند شناسهٔ نمایه برای یک ارائه‌دهنده پشتیبانی می‌کند.
نحوهٔ انتخاب مورد استفاده:

- به‌صورت سراسری از طریق ترتیب پیکربندی (`auth.order`)
- به‌ازای هر نشست از طریق `/model ...@<profileId>`

نمونه (بازنویسی نشست):

- `/model Opus@anthropic:work`

شناسه‌های نمایهٔ موجود را با فرمان زیر فهرست کنید:

```bash
openclaw models auth list --provider <id>
```

مستندات مرتبط:

- [تغییر مسیر مدل هنگام خرابی](/fa/concepts/model-failover) (قواعد چرخش + دورهٔ انتظار)
- [فرمان‌های اسلش](/fa/tools/slash-commands) (سطح فرمان)

## مرتبط

- [احراز هویت](/fa/gateway/authentication) - نمای کلی احراز هویت ارائه‌دهندهٔ مدل
- [اسرار](/fa/gateway/secrets) - ذخیره‌سازی اعتبارنامه و SecretRef
- [مرجع پیکربندی](/fa/gateway/configuration-reference#auth-storage) - کلیدهای پیکربندی احراز هویت