---
read_when:
    - می‌خواهید OAuth در OpenClaw را از ابتدا تا انتها درک کنید
    - با مشکلات باطل‌شدن توکن / خروج از حساب مواجه می‌شوید
    - جریان‌های احراز هویت Claude CLI یا OAuth را می‌خواهید
    - به چند حساب یا مسیریابی پروفایل نیاز دارید
summary: 'OAuth در OpenClaw: تبادل و ذخیره‌سازی توکن و الگوهای چندحسابی'
title: OAuth
x-i18n:
    generated_at: "2026-07-16T16:43:00Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 3ef94af0601b7d57bb7e2d53c3d8231708b401251eca7dc1bb1e7e4fc09b46da
    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 دارید،
فرایند آغازبه‌کار/پیکربندی می‌تواند مستقیماً از آن استفاده کند. setup-token متعلق به 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` پیاده‌سازی شده‌اند و به راهنماهای گام‌به‌گام/فرمان‌ها متصل هستند.

### setup-token متعلق به Anthropic

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

1. توکن را با اجرای `claude setup-token` روی هر دستگاهی که Claude Code دارد ایجاد کنید، سپس setup-token متعلق به Anthropic یا paste-token را از 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` است و فقط میزبان‌های loopback را می‌پذیرد؛
   با `OPENCLAW_OAUTH_CALLBACK_HOST` بازنویسی کنید)
4. اگر پیش از رسیدن فراخوان برگشتی بتوانید کدی جای‌گذاری کنید (یا در محیط
   دوردست/بدون رابط گرافیکی هستید و فراخوان برگشتی نمی‌تواند متصل شود)، به‌جای آن URL/کد تغییرمسیر را
   جای‌گذاری کنید؛ جای‌گذاری دستی با فراخوان برگشتی مرورگر رقابت می‌کند و هرکدام
   زودتر تکمیل شود برنده است
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 خارجی، نیاز پروفایل آسیب‌دیده به
  احراز هویت مجدد را گزارش می‌کند.

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

## چند حساب (پروفایل) + مسیریابی

دو الگو:

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

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

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

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

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

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

- به‌صورت سراسری از طریق ترتیب پیکربندی (`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) - کلیدهای پیکربندی احراز هویت