OpenAI

OpenAI APIهای توسعه‌دهنده را برای مدل‌های GPT ارائه می‌کند، و Codex نیز به‌عنوان عامل کدنویسیِ طرح ChatGPT از طریق کلاینت‌های Codex متعلق به OpenAI در دسترس است. OpenClaw برای هر دو شکل احراز هویت از یک شناسهٔ ارائه‌دهنده، openai، استفاده می‌کند.

OpenClaw از openai/* به‌عنوان مسیر رسمی مدل OpenAI استفاده می‌کند. نوبت‌های عاملِ تعبیه‌شده روی مدل‌های OpenAI به‌طور پیش‌فرض از طریق زمان‌اجرای بومی سرور برنامهٔ Codex اجرا می‌شوند؛ احراز هویت مستقیم با کلید API OpenAI همچنان برای سطوح غیرعاملی OpenAI مانند تصاویر، جاسازی‌ها، گفتار، و بلادرنگ در دسترس است.

• مدل‌های عامل - مدل‌های openai/* از طریق زمان‌اجرای Codex؛ برای استفاده از اشتراک ChatGPT/Codex با احراز هویت Codex وارد شوید، یا وقتی عمداً احراز هویت با کلید API می‌خواهید، یک پروفایل پشتیبانِ کلید API سازگار با Codex برای OpenAI پیکربندی کنید.
• APIهای غیرعاملی OpenAI - دسترسی مستقیم به OpenAI Platform با صورتحساب مبتنی بر مصرف از طریق OPENAI_API_KEY یا راه‌اندازی کلید API OpenAI.
• پیکربندی قدیمی - ارجاع‌های قدیمی مدل Codex توسط openclaw doctor --fix به openai/* به‌همراه زمان‌اجرای Codex اصلاح می‌شوند.

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

ارائه‌دهنده، مدل، زمان‌اجرا، و کانال لایه‌های جداگانه‌ای هستند. اگر این برچسب‌ها با هم مخلوط می‌شوند، پیش از تغییر پیکربندی زمان‌اجراهای عامل را بخوانید.

انتخاب سریع

نگاشت نام‌ها

نام‌ها مشابه‌اند اما قابل‌جایگزینی با یکدیگر نیستند:

یعنی یک پیکربندی می‌تواند عمداً شامل ارجاع‌های مدل openai/* باشد، در حالی‌که پروفایل‌های احراز هویت به اعتبارنامه‌های کلید API یا OAuth مربوط به ChatGPT/Codex اشاره کنند. برای پیکربندی از auth.order.openai استفاده کنید؛ openclaw doctor --fix ارجاع‌های قدیمی مدل Codex، شناسه‌های قدیمی پروفایل احراز هویت Codex، و ترتیب قدیمی احراز هویت Codex را به مسیر رسمی OpenAI بازنویسی می‌کند.

پیش‌نمایش محدود GPT-5.6

OpenClaw سه شناسهٔ عمومی مدل GPT-5.6 را می‌شناسد:

• openai/gpt-5.6-sol
• openai/gpt-5.6-terra
• openai/gpt-5.6-luna

هر سه در کاتالوگ فعلی سرور برنامهٔ Codex استدلال max را ارائه می‌کنند. اطلاعیهٔ انتشار OpenAI، Sol را سطح پرچم‌دار، Terra را سطح متوازن، و Luna را سطح سریع و کم‌هزینه‌تر توصیف می‌کند. اطلاعیهٔ انتشار GPT-5.6 و راهنمای دسترسی به پیش‌نمایش را ببینید.

دسترسی در طول پیش‌نمایش فهرست‌مجاز است و می‌تواند جداگانه برای API و Codex اعطا شود. داشتن یک طرح پولی ChatGPT به‌تنهایی دسترسی نمی‌دهد. OpenClaw همچنان openai/gpt-5.5 را به‌عنوان پیش‌فرض نگه می‌دارد؛ انتخاب یک ارجاع GPT-5.6 بدون دسترسی، به‌جای بازگشت بی‌صدا، خطای دسترسی بالادستی را برمی‌گرداند.

پوشش قابلیت‌های OpenClaw

جاسازی‌های حافظه

OpenClaw می‌تواند از OpenAI، یا یک نقطهٔ پایانی جاسازی سازگار با OpenAI، برای نمایه‌سازی memory_search و جاسازی‌های پرس‌وجو استفاده کند:

{  agents: {    defaults: {      memorySearch: {        provider: "openai",        model: "text-embedding-3-small",      },    },  },}

برای نقاط پایانی سازگار با OpenAI که به برچسب‌های جاسازی نامتقارن نیاز دارند، queryInputType و documentInputType را زیر memorySearch تنظیم کنید. OpenClaw آن‌ها را به‌عنوان فیلدهای درخواست input_type ویژهٔ ارائه‌دهنده ارسال می‌کند: جاسازی‌های پرس‌وجو از queryInputType استفاده می‌کنند؛ قطعه‌های حافظهٔ نمایه‌شده و نمایه‌سازی دسته‌ای از documentInputType استفاده می‌کنند. برای نمونهٔ کامل، مرجع پیکربندی حافظه را ببینید.

شروع به کار

روش احراز هویت دلخواه خود را انتخاب کنید و مراحل راه‌اندازی را دنبال کنید.

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

openclaw models auth login --provider openai --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.5

openclaw models list --provider openai

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

{  models: {    providers: {      openai: {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

احراز هویت بومی app-server Codex

هارنس بومی app-server Codex از ارجاع‌های مدل openai/* به‌همراه پیکربندی زمان اجرای حذف‌شده یا provider/model agentRuntime.id: "codex" استفاده می‌کند، اما احراز هویت آن همچنان مبتنی بر حساب است. OpenClaw احراز هویت را به این ترتیب انتخاب می‌کند:

1. پروفایل‌های احراز هویت OpenAI مرتب‌شده برای عامل، ترجیحاً زیر auth.order.openai. برای مهاجرت شناسه‌های پروفایل احراز هویت قدیمی Codex و ترتیب احراز هویت قدیمی Codex، openclaw doctor --fix را اجرا کنید.
2. حساب موجود app-server، مانند ورود محلی ChatGPT در Codex CLI.
3. فقط برای راه‌اندازی‌های محلی app-server از نوع stdio، ابتدا CODEX_API_KEY، سپس OPENAI_API_KEY، وقتی app-server هیچ حسابی گزارش نمی‌کند و همچنان به احراز هویت OpenAI نیاز دارد.

این یعنی یک ورود محلی اشتراک ChatGPT/Codex فقط به این دلیل جایگزین نمی‌شود که فرایند gateway برای مدل‌های مستقیم OpenAI یا embeddings هم OPENAI_API_KEY دارد. Fallback کلید API محیطی فقط مسیر محلی stdio بدون حساب است؛ به اتصال‌های app-server از نوع WebSocket ارسال نمی‌شود. وقتی یک پروفایل Codex به سبک اشتراک انتخاب شود، OpenClaw همچنین CODEX_API_KEY و OPENAI_API_KEY را از فرزند app-server از نوع stdio که spawn شده بیرون نگه می‌دارد و اعتبارنامه‌های انتخاب‌شده را از طریق RPC ورود app-server ارسال می‌کند. وقتی آن پروفایل اشتراک با محدودیت استفاده Codex مسدود شود، OpenClaw می‌تواند بدون تغییر مدل انتخاب‌شده یا خروج از هارنس Codex، به پروفایل کلید API مرتب‌شده بعدی openai:* بچرخد. پس از عبور زمان ریست اشتراک، پروفایل اشتراک دوباره واجد شرایط می‌شود.

تولید تصویر

Plugin بسته‌بندی‌شده openai تولید تصویر را از طریق ابزار image_generate ثبت می‌کند. این ابزار هم از تولید تصویر با کلید API OpenAI و هم از تولید تصویر با OAuth برای Codex از طریق همان ارجاع مدل openai/gpt-image-2 پشتیبانی می‌کند.

{  agents: {    defaults: {      imageGenerationModel: { primary: "openai/gpt-image-2" },    },  },}

gpt-image-2 پیش‌فرض هر دو مورد تولید متن به تصویر OpenAI و ویرایش تصویر است. gpt-image-1.5، gpt-image-1، و gpt-image-1-mini همچنان به‌عنوان بازنویسی‌های صریح مدل قابل استفاده هستند. برای خروجی PNG/WebP با پس‌زمینه شفاف از openai/gpt-image-1.5 استفاده کنید؛ API فعلی gpt-image-2 گزینه background: "transparent" را رد می‌کند.

برای درخواست پس‌زمینه شفاف، عامل‌ها باید image_generate را با model: "openai/gpt-image-1.5"، outputFormat: "png" یا "webp"، و background: "transparent" فراخوانی کنند؛ گزینه قدیمی‌تر ارائه‌دهنده openai.background همچنان پذیرفته می‌شود. OpenClaw همچنین مسیرهای عمومی OpenAI و OAuth OpenAI Codex را با بازنویسی درخواست‌های شفاف پیش‌فرض openai/gpt-image-2 به gpt-image-1.5 محافظت می‌کند؛ Azure و نقاط پایانی سفارشی سازگار با OpenAI نام‌های استقرار/مدل پیکربندی‌شده خود را نگه می‌دارند.

همین تنظیم برای اجراهای CLI بدون رابط نیز ارائه شده است:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "A simple red circle sticker on a transparent background" \  --json

هنگام شروع از یک فایل ورودی، همین پرچم‌های --output-format و --background را با openclaw infer image edit استفاده کنید. --openai-background همچنان به‌عنوان نام مستعار ویژه OpenAI در دسترس است. وقتی لازم است کیفیت و هزینه تصاویر OpenAI را کنترل کنید، از --quality low|medium|high|auto استفاده کنید. برای ارسال راهنمای تعدیل ویژه ارائه‌دهنده OpenAI از image generate یا image edit، از --openai-moderation low|auto استفاده کنید.

برای نصب‌های OAuth ChatGPT/Codex، همان ارجاع openai/gpt-image-2 را نگه دارید. وقتی یک نمایه OAuth مربوط به openai پیکربندی شده باشد، OpenClaw آن توکن دسترسی OAuth ذخیره‌شده را resolve می‌کند و درخواست‌های تصویر را از طریق بک‌اند پاسخ‌های Codex می‌فرستد. برای آن درخواست ابتدا OPENAI_API_KEY را امتحان نمی‌کند و بی‌صدا به کلید API برنمی‌گردد. وقتی مسیر مستقیم API تصاویر OpenAI را می‌خواهید، models.providers.openai را صراحتا با یک کلید API، نشانی پایه سفارشی، یا نقطه پایانی Azure پیکربندی کنید. اگر آن نقطه پایانی تصویر سفارشی روی یک نشانی LAN/خصوصی مورد اعتماد است، همچنین browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true را تنظیم کنید؛ OpenClaw نقاط پایانی تصویر خصوصی/داخلی سازگار با OpenAI را تا زمانی که این opt-in وجود نداشته باشد مسدود نگه می‌دارد.

تولید:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

تولید PNG شفاف:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

ویرایش:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

تولید ویدیو

Plugin همراه openai تولید ویدیو را از طریق ابزار video_generate ثبت می‌کند.

درخواست‌های تصویر به ویدیوی OpenAI از POST /v1/videos با یک input_reference تصویری استفاده می‌کنند. ویرایش‌های تک‌ویدیو از POST /v1/videos/edits با ویدیوی بارگذاری‌شده در فیلد video استفاده می‌کنند.

{  agents: {    defaults: {      videoGenerationModel: { primary: "openai/sora-2" },    },  },}

مشارکت پرامپت GPT-5

OpenClaw یک مشارکت پرامپت مشترک GPT-5 برای اجراهای خانواده GPT-5 روی سطوح پرامپتی که OpenClaw مونتاژ می‌کند اضافه می‌کند. این بر اساس شناسه مدل اعمال می‌شود، بنابراین مسیرهای OpenClaw/ارائه‌دهنده مانند ارجاع‌های قدیمی پیش از تعمیر legacy (ارجاع legacy Codex GPT-5.5)، openrouter/openai/gpt-5.5، opencode/gpt-5.5، و سایر ارجاع‌های سازگار GPT-5 همان پوشش را دریافت می‌کنند. مدل‌های قدیمی‌تر GPT-4.x دریافت نمی‌کنند.

هارنس native Codex همراه، این پوشش GPT-5 متعلق به OpenClaw را از طریق دستورالعمل‌های توسعه‌دهنده app-server Codex دریافت نمی‌کند. native Codex رفتار پایه، مدل، و سندهای پروژه متعلق به Codex را نگه می‌دارد، در حالی که OpenClaw شخصیت داخلی Codex را برای threadهای native غیرفعال می‌کند تا فایل‌های شخصیت فضای کاری عامل مرجع باقی بمانند. OpenClaw فقط زمینه runtime مانند تحویل کانال، ابزارهای پویا OpenClaw، تفویض ACP، زمینه فضای کاری، و Skills مربوط به OpenClaw را مشارکت می‌دهد.

مشارکت GPT-5 یک قرارداد رفتاری برچسب‌دار برای پایداری persona، ایمنی اجرا، انضباط ابزار، شکل خروجی، بررسی‌های تکمیل، و راستی‌آزمایی روی پرامپت‌های مونتاژشده توسط OpenClaw که مطابق باشند اضافه می‌کند. رفتار پاسخ ویژه کانال و پیام خاموش در پرامپت سیستم مشترک OpenClaw و سیاست تحویل خروجی باقی می‌ماند. لایه سبک تعامل دوستانه جدا و قابل پیکربندی است.

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

صدا و گفتار

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

نقاط پایانی Azure OpenAI

ارائه‌دهنده همراه openai می‌تواند با بازنویسی URL پایه، یک منبع Azure OpenAI را برای تولید تصویر هدف بگیرد. در مسیر تولید تصویر، OpenClaw نام میزبان‌های Azure را روی models.providers.openai.baseUrl تشخیص می‌دهد و به‌صورت خودکار به شکل درخواست Azure تغییر می‌کند.

از Azure OpenAI زمانی استفاده کنید که:

• از قبل اشتراک، سهمیه، یا توافق سازمانی Azure OpenAI دارید
• به اقامت داده منطقه‌ای یا کنترل‌های انطباقی که Azure فراهم می‌کند نیاز دارید
• می‌خواهید ترافیک را داخل یک مستاجری Azure موجود نگه دارید

پیکربندی

برای تولید تصویر Azure از طریق ارائه‌دهنده همراه openai، مقدار models.providers.openai.baseUrl را به منبع Azure خود اشاره دهید و apiKey را روی کلید Azure OpenAI تنظیم کنید (نه کلید OpenAI Platform):

{  models: {    providers: {      openai: {        baseUrl: "https://<your-resource>.openai.azure.com",        apiKey: "<azure-openai-api-key>",      },    },  },}

OpenClaw این پسوندهای میزبان Azure را برای مسیر تولید تصویر Azure تشخیص می‌دهد:

• *.openai.azure.com
• *.services.ai.azure.com
• *.cognitiveservices.azure.com

برای درخواست‌های تولید تصویر روی میزبان Azure شناخته‌شده، OpenClaw:

• هدر api-key را به‌جای Authorization: Bearer ارسال می‌کند
• از مسیرهای محدود به استقرار (/openai/deployments/{deployment}/...) استفاده می‌کند
• به هر درخواست ?api-version=... اضافه می‌کند
• از مهلت زمانی پیش‌فرض 600 ثانیه برای فراخوانی‌های تولید تصویر Azure استفاده می‌کند. مقادیر timeoutMs در هر فراخوانی همچنان این پیش‌فرض را بازنویسی می‌کنند.

URLهای پایه دیگر (OpenAI عمومی، پراکسی‌های سازگار با OpenAI) شکل استاندارد درخواست تصویر OpenAI را حفظ می‌کنند.

نسخه API

برای سنجاق کردن یک نسخه پیش‌نمایش یا GA مشخص Azure برای مسیر تولید تصویر Azure، AZURE_OPENAI_API_VERSION را تنظیم کنید:

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

وقتی متغیر تنظیم نشده باشد، پیش‌فرض 2024-12-01-preview است.

نام مدل‌ها همان نام‌های استقرار هستند

Azure OpenAI مدل‌ها را به استقرارها متصل می‌کند. برای درخواست‌های تولید تصویر Azure که از طریق ارائه‌دهنده همراه openai مسیریابی می‌شوند، فیلد model در OpenClaw باید نام استقرار Azure باشد که در پورتال Azure پیکربندی کرده‌اید، نه شناسه مدل عمومی OpenAI.

اگر استقراری به نام gpt-image-2-prod ایجاد کنید که gpt-image-2 را ارائه می‌دهد:

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

همین قاعده نام استقرار برای فراخوانی‌های تولید تصویر مسیریابی‌شده از طریق ارائه‌دهنده همراه openai نیز اعمال می‌شود.

دسترس‌پذیری منطقه‌ای

تولید تصویر Azure در حال حاضر فقط در زیرمجموعه‌ای از مناطق در دسترس است (برای مثال eastus2،‏ swedencentral،‏ polandcentral،‏ westus3، uaenorth). پیش از ایجاد استقرار، فهرست منطقه‌ای فعلی Microsoft را بررسی کنید و تایید کنید که مدل مشخص در منطقه شما ارائه می‌شود.

تفاوت‌های پارامترها

Azure OpenAI و OpenAI عمومی همیشه پارامترهای تصویر یکسانی را نمی‌پذیرند. Azure ممکن است گزینه‌هایی را که OpenAI عمومی اجازه می‌دهد رد کند (برای مثال برخی مقادیر background روی gpt-image-2) یا آن‌ها را فقط روی نسخه‌های مدل مشخصی ارائه کند. این تفاوت‌ها از Azure و مدل زیرین می‌آیند، نه از OpenClaw. اگر یک درخواست Azure با خطای اعتبارسنجی شکست خورد، مجموعه پارامترهای پشتیبانی‌شده توسط استقرار و نسخه API مشخص خود را در پورتال Azure بررسی کنید.

پیکربندی پیشرفته

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { transport: "auto" },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { serviceTier: "priority" } },      },    },  },}

{  agents: {    defaults: {      models: {        "azure-openai-responses/gpt-5.5": {          params: { responsesServerCompaction: true },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 120000,          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { responsesServerCompaction: false },        },      },    },  },}

{  agents: {    defaults: {      embeddedAgent: { executionContract: "strict-agentic" },    },  },}

مرتبط