OpenAI

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

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

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

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

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

انتخاب سریع

نقشه نام‌گذاری

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

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

پوشش قابلیت OpenClaw

Embeddingهای حافظه

OpenClaw می‌تواند از OpenAI یا یک endpoint سازگار با OpenAI برای indexing در memory_search و embeddingهای query استفاده کند:

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

برای endpointهای سازگار با OpenAI که به برچسب‌های embedding نامتقارن نیاز دارند، queryInputType و documentInputType را زیر memorySearch تنظیم کنید. OpenClaw این‌ها را به‌عنوان فیلدهای درخواست input_type ویژه ارائه‌دهنده ارسال می‌کند: embeddingهای query از queryInputType استفاده می‌کنند؛ قطعه‌های حافظه indexشده و indexing دسته‌ای از 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: "sk-..." },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

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

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

openclaw models list --provider openai-codex

{  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-codex:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw 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-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

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

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

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

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

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

تولید تصویر

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" را رد می‌کند.

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

همان تنظیم برای اجراهای 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

هنگام شروع از یک فایل ورودی، همان flagهای --output-format و --background را با openclaw infer image edit استفاده کنید. --openai-background همچنان به‌عنوان alias ویژه OpenAI دردسترس است.

برای نصب‌های OAuth مربوط به Codex، همان مرجع openai/gpt-image-2 را نگه دارید. وقتی یک پروفایل OAuth از نوع openai-codex پیکربندی شده باشد، OpenClaw آن توکن دسترسی OAuth ذخیره‌شده را resolve می‌کند و درخواست‌های تصویر را از طریق backend مربوط به Codex Responses می‌فرستد. این سیستم ابتدا OPENAI_API_KEY را امتحان نمی‌کند یا برای آن درخواست بی‌صدا به کلید API fallback نمی‌کند. وقتی مسیر مستقیم OpenAI Images API را می‌خواهید، models.providers.openai را به‌طور صریح با یک کلید API، URL پایه سفارشی، یا endpoint مربوط به Azure پیکربندی کنید. اگر آن endpoint تصویر سفارشی روی یک LAN/نشانی خصوصی مورد اعتماد است، همچنین browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true را تنظیم کنید؛ OpenClaw endpointهای تصویر خصوصی/داخلی سازگار با 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 ثبت می‌کند.

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

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

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

مهار بومی Codex همراه، همان رفتار GPT-5 و هم‌پوشانی heartbeat را از طریق دستورالعمل‌های توسعه‌دهنده app-server در Codex استفاده می‌کند، بنابراین نشست‌های openai/gpt-5.x که از طریق Codex مسیریابی می‌شوند همان راهنمایی پیگیری و heartbeat پیش‌دستانه را حفظ می‌کنند، هرچند Codex مالک بقیه پرامپت مهار است.

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

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

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

صدا و گفتار

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", voice: "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 فراهم می‌کند نیاز دارید
• می‌خواهید ترافیک را داخل یک tenancy موجود 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

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

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: true } },      },    },  },}

{  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: {      embeddedPi: { executionContract: "strict-agentic" },    },  },}

مرتبط