OAuth

OpenClaw از «احراز هویت اشتراکی» از طریق OAuth برای ارائه‌دهندگانی که آن را ارائه می‌کنند پشتیبانی می‌کند (به‌ویژه OpenAI Codex (ChatGPT OAuth)). برای Anthropic، تقسیم‌بندی عملی اکنون چنین است:

• کلید API Anthropic: صورت‌حساب معمول API Anthropic
• Anthropic Claude CLI / احراز هویت اشتراکی داخل OpenClaw: کارکنان Anthropic به ما گفتند این استفاده دوباره مجاز است

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

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

برای Anthropic در محیط تولید، احراز هویت با کلید API مسیر ایمن‌تر و توصیه‌شده است.

این صفحه توضیح می‌دهد:

• تبادل توکن OAuth چگونه کار می‌کند (PKCE)
• توکن‌ها کجا ذخیره می‌شوند (و چرا)
• چگونه چند حساب را مدیریت کنید (پروفایل‌ها + بازنویسی‌های هر نشست)

OpenClaw همچنین از Plugin‌های ارائه‌دهنده پشتیبانی می‌کند که جریان‌های OAuth یا کلید API خودشان را ارائه می‌کنند. آن‌ها را این‌گونه اجرا کنید:

openclaw models auth login --provider <id>

محل جذب توکن (چرا وجود دارد)

ارائه‌دهندگان OAuth معمولاً در جریان‌های ورود/نوسازی یک توکن نوسازی جدید صادر می‌کنند. برخی ارائه‌دهندگان (یا کلاینت‌های OAuth) می‌توانند وقتی توکن جدیدی برای همان کاربر/برنامه صادر می‌شود، توکن‌های نوسازی قدیمی‌تر را نامعتبر کنند.

نشانه عملی:

• شما از طریق OpenClaw و از طریق Claude Code / Codex CLI وارد می‌شوید → یکی از آن‌ها بعداً به‌صورت تصادفی «از حساب خارج» می‌شود

برای کاهش این وضعیت، OpenClaw با auth-profiles.json به‌عنوان یک محل جذب توکن رفتار می‌کند:

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

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

اسرار در فروشگاه‌های احراز هویت عامل ذخیره می‌شوند:

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

فایل میراثی فقط برای واردسازی (هنوز پشتیبانی می‌شود، اما فروشگاه اصلی نیست):

• ~/.openclaw/credentials/oauth.json (در اولین استفاده به auth-profiles.json وارد می‌شود)

همه موارد بالا همچنین به $OPENCLAW_STATE_DIR (بازنویسی دایرکتوری وضعیت) احترام می‌گذارند. مرجع کامل: /gateway/configuration

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

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

سازگاری توکن میراثی Anthropic

OpenClaw همچنین setup-token متعلق به Anthropic را به‌عنوان یک مسیر پشتیبانی‌شده احراز هویت با توکن ارائه می‌کند، اما اکنون در صورت موجود بودن، استفاده مجدد از Claude CLI و claude -p را ترجیح می‌دهد.

مهاجرت Anthropic Claude CLI

OpenClaw دوباره از استفاده مجدد Anthropic Claude CLI پشتیبانی می‌کند. اگر از قبل یک ورود محلی Claude روی میزبان دارید، onboarding/configure می‌تواند مستقیماً از آن استفاده کند.

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

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

setup-token در Anthropic

شکل جریان:

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

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth به‌صراحت برای استفاده بیرون از 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. تولید verifier/challenge در PKCE + state تصادفی
2. باز کردن https://auth.openai.com/oauth/authorize?...
3. تلاش برای دریافت callback روی http://127.0.0.1:1455/auth/callback
4. اگر callback نتواند bind شود (یا شما از راه دور/بدون رابط هستید)، URL/code تغییرمسیر را جای‌گذاری کنید
5. تبادل در https://auth.openai.com/oauth/token
6. استخراج accountId از توکن دسترسی و ذخیره { access, refresh, expires, accountId }

مسیر جادوگر openclaw onboard → انتخاب احراز هویت openai است.

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

پروفایل‌ها یک timestamp به نام expires ذخیره می‌کنند.

در زمان اجرا:

• اگر expires در آینده باشد → از توکن دسترسی ذخیره‌شده استفاده می‌شود
• اگر منقضی شده باشد → نوسازی می‌شود (زیر file lock) و اعتبارنامه‌های ذخیره‌شده بازنویسی می‌شوند
• اگر یک عامل ثانویه پروفایل OAuth به‌ارث‌رسیده از عامل اصلی را بخواند، نوسازی به‌جای کپی کردن توکن نوسازی در فروشگاه عامل ثانویه، دوباره در فروشگاه عامل اصلی نوشته می‌شود
• استثنا: برخی اعتبارنامه‌های CLI خارجی به‌صورت خارجی مدیریت‌شده باقی می‌مانند؛ OpenClaw به‌جای مصرف توکن‌های نوسازی کپی‌شده، آن فروشگاه‌های احراز هویت CLI را دوباره می‌خواند. راه‌اندازی Codex CLI عمداً محدودتر است: فقط پیش از آنکه OpenClaw مالک OAuth برای ارائه‌دهنده شود، می‌تواند یک openai:default خالی یا پروفایل OpenAI صراحتاً درخواست‌شده را seed کند. پس از آن، نوسازی‌های تحت مالکیت OpenClaw پروفایل‌های محلی را متعارف نگه می‌دارند و کشف، احراز هویت Codex CLI را در هیچ جایگاه هم‌ردیفی اضافه نمی‌کند. اگر نوسازی مدیریت‌شده شکست بخورد، OpenClaw به‌جای برگرداندن مواد توکن CLI خارجی، پروفایل متأثر را برای احراز هویت مجدد گزارش می‌کند.

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

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

دو الگو:

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

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

openclaw agents add workopenclaw agents add personal

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

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

auth-profiles.json از چند شناسه پروفایل برای یک ارائه‌دهنده پشتیبانی می‌کند.

انتخاب کنید کدام پروفایل استفاده شود:

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

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

• /model Opus@anthropic:work

چگونه ببینید چه شناسه‌های پروفایلی وجود دارند:

• openclaw channels list --json (‏auth[] را نشان می‌دهد)

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

• بازیابی پس از خرابی مدل (قواعد چرخش + cooldown)
• فرمان‌های اسلش (سطح فرمان)

مرتبط

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