OAuth

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 و هم OAuth ‏ChatGPT/Codex را زیر شناسهٔ رسمی ارائه‌دهندهٔ openai ذخیره می‌کند. شناسه‌های قدیمی نمایهٔ openai-codex:* و ورودی‌های auth.order.openai-codex وضعیت قدیمی‌ای هستند که با openclaw doctor --fix اصلاح می‌شوند؛ برای پیکربندی جدید از شناسه‌های نمایهٔ openai:* و auth.order.openai استفاده کنید.

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

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

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

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

برای ارجاع‌های ثابت اطلاعات محرمانه و رفتار فعال‌سازی اسنپ‌شات محیط اجرا، مدیریت اطلاعات محرمانه را ببینید.

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

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

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

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

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

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

شکل جریان:

1. توکن را با اجرای claude setup-token روی هر دستگاهی که Claude Code دارد ایجاد کنید، سپس توکن راه‌اندازی Anthropic یا چسباندن توکن را از OpenClaw آغاز کنید
2. OpenClaw اعتبارنامهٔ حاصل از Anthropic را در یک نمایهٔ احراز هویت ذخیره می‌کند
3. انتخاب مدل روی anthropic/... باقی می‌ماند
4. نمایه‌های احراز هویت موجود Anthropic برای بازگشت/کنترل ترتیب در دسترس می‌مانند

OpenAI Codex (ChatGPT OAuth)

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

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

openclaw models auth login --provider openai

برای چند حساب OAuth ‏ChatGPT/Codex در یک عامل از --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 است و فقط میزبان‌های حلقهٔ بازگشتی را می‌پذیرد؛ با 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؛ مخزن توکن را ببینید) به‌جای مصرف یک توکن نوسازی کپی‌شده، دوباره خوانده می‌شوند. اگر نوسازی مدیریت‌شده ناموفق باشد، OpenClaw به‌جای بازگرداندن داده‌های توکن CLI خارجی، نمایهٔ متأثر را برای احراز هویت مجدد گزارش می‌کند.

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

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

دو الگو:

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

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

openclaw agents add workopenclaw agents add personal

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

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

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

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

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

• /model Opus@anthropic:work

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

openclaw models auth list --provider <id>

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

• جایگزینی مدل هنگام خرابی (قواعد چرخش + دورهٔ انتظار)
• فرمان‌های اسلش (سطح فرمان)

مرتبط

• احراز هویت - نمای کلی احراز هویت ارائه‌دهندهٔ مدل
• اطلاعات محرمانه - ذخیره‌سازی اعتبارنامه و SecretRef
• مرجع پیکربندی - کلیدهای پیکربندی احراز هویت