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 و هم ChatGPT/Codex OAuth را زیر شناسهٔ اصلی ارائه‌دهنده، یعنی 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. توکن راه‌اندازی 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

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

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

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

دو الگو:

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

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

openclaw agents add workopenclaw agents add personal

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

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

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

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

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

• /model Opus@anthropic:work

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

openclaw models auth list --provider <id>

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

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

مرتبط

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