OpenAI

OpenClaw يستخدم معرّف مزوّد واحدًا، openai، لكلٍّ من المصادقة المباشرة بمفتاح API ومصادقة اشتراك ChatGPT/Codex. ويُعدّ openai/* مسار النموذج القياسي. بالنسبة إلى دورات الوكيل المضمّنة التي لم تُضبط فيها سياسة وقت التشغيل أو ضُبطت على auto، تحدد حقائق مسار OpenAI ما إذا كان يجوز لـ OpenClaw اختيار وقت تشغيل خادم تطبيق Codex المضمّن ضمنيًا. ولا تحدد البادئة openai/* وحدها وقت تشغيل.

• نماذج الوكيل - openai/* عبر وقت التشغيل الذي تحدده تهيئة agentRuntime الصريحة أو سياسة المسار الضمنية لـ OpenAI. سجّل الدخول باستخدام مصادقة Codex لاستخدام اشتراك ChatGPT/Codex، أو هيّئ ملف تعريف مصادقة بمفتاح API عندما تريد فوترة قائمة على المفتاح.
• واجهات OpenAI API غير الخاصة بالوكيل - وصول مباشر إلى منصة OpenAI، مع فوترة حسب الاستخدام، عبر OPENAI_API_KEY أو ملف تعريف مصادقة بمفتاح API من نوع openai.
• التهيئة القديمة - تُصلَح مراجع codex/* وopenai-codex/* إلى openai/* بالإضافة إلى agentRuntime.id: "codex" على مستوى النموذج بواسطة openclaw doctor --fix.

تدعم OpenAI صراحةً استخدام OAuth الخاص بالاشتراك في الأدوات الخارجية وسير العمل مثل OpenClaw.

تتبّع الاستخدام والتكلفة

يفصل OpenClaw بين حصة الاشتراك وفوترة Platform API:

• يعرض OAuth الخاص بـ ChatGPT/Codex خطة الاشتراك ونوافذ الحصة ورصيد الاعتمادات.
• يعرض OPENAI_ADMIN_KEY مدة 30 يومًا من تكلفة المؤسسة واستخدام الإكمالات اللذين أبلغ عنهما المزوّد في الاستخدام ضمن واجهة التحكم، بما في ذلك الإنفاق اليومي وإجماليات الطلبات/الرموز المميزة وأبرز النماذج وفئات التكلفة.
• يقيّد OPENAI_PROJECT_ID اختياريًا سجل Admin API بمشروع واحد.
• لا يرسل OpenClaw مطلقًا OPENAI_API_KEY أو ملف تعريف استدلال openai إلى واجهات API الخاصة بالمؤسسة؛ فقد تخص بيانات الاعتماد هذه نقاط نهاية مخصصة أو Azure أو نقاط نهاية محلية للوكيل.

يكون لمفتاح Admin الصريح أسبقية على OAuth. ولا يُدمج السجل الذي أبلغ عنه المزوّد مع التكلفة التقديرية المستمدة من جلسات OpenClaw؛ وقد يتضمن نشاط API من عملاء آخرين وتعديلات فوترة من جانب المزوّد.

توضح وثائق لوحة معلومات استخدام API من OpenAI متطلبات مالك المؤسسة والإذن الصريح للوحة معلومات الاستخدام اللازمة لبيانات الاستخدام.

المزوّد والنموذج ووقت التشغيل والقناة طبقات منفصلة. إذا كانت هذه التسميات تختلط معًا، فاقرأ أوقات تشغيل الوكيل قبل تغيير التهيئة.

اختيار سريع

خريطة التسمية

وقت تشغيل الوكيل الضمني

عندما تكون سياسة المزوّد/النموذج agentRuntime غير مضبوطة أو مضبوطة على auto، تختار سياسة المسار المملوكة لـ OpenAI وقت التشغيل الضمني من نقطة النهاية والمهايئ الفعليين:

يظل إعداد المزوّد/النموذج agentRuntime.id الصريح وغير الافتراضي هو المرجع الحاكم. على سبيل المثال، يُبقي agentRuntime.id: "openclaw" مسارًا مؤهلًا لولا ذلك لاستخدام Codex على OpenClaw، بينما يتطلب agentRuntime.id: "codex" استخدام Codex ويفشل بصورة مغلقة عندما لا يُعلَن أن المسار الفعلي متوافق مع Codex. لا يغيّر اختيار وقت التشغيل نوع بيانات الاعتماد أو الفوترة: تظل مصادقة Platform بمفتاح API ومصادقة اشتراك ChatGPT/Codex منفصلتين.

ينقل openclaw doctor --fix مراجع نماذج codex/* وopenai-codex/* القديمة، ومعرّفات ملفات تعريف مصادقة Codex القديمة، وإدخالات ترتيب مصادقة Codex القديمة إلى مسار openai القياسي. وتتلقى مراجع النماذج المنقولة agentRuntime.id: "codex" على مستوى النموذج؛ استخدم auth.order.openai لتهيئة ترتيب المصادقة الجديدة.

المعاينة المحدودة لـ GPT-5.6

يتعرف OpenClaw على معرّفات النماذج الدقيقة openai/gpt-5.6-sol وopenai/gpt-5.6-terra وopenai/gpt-5.6-luna. وتتيح النماذج الثلاثة استدلال xhigh وmax في الكتالوج الحالي. تصف OpenAI نموذج Sol بأنه الفئة الرائدة، وTerra بأنه الفئة المتوازنة، وLuna بأنه الفئة السريعة والأقل تكلفة. راجع إعلان إطلاق GPT-5.6 ودليل الوصول.

عند استخدام مصادقة OpenAI المباشرة بمفتاح API، يكون المعرّف المجرّد openai/gpt-5.6 اسمًا مستعارًا لـ Sol والقيمة الافتراضية للإعداد الجديد. ولا يطبق كتالوج Codex الأصلي هذا الاسم المستعار لـ API المباشر من جانب العميل؛ وبحسب صلاحية وصول مساحة العمل، يمكنه عرض معرّفات Sol وTerra وLuna الدقيقة. لذلك يستخدم إعداد OAuth الجديد لـ ChatGPT/Codex ‏openai/gpt-5.6-sol. تحقّق من الحساب الحالي باستخدام:

openclaw models list --provider openai

قد تختلف صلاحية وصول مؤسسة API عن صلاحية وصول مساحة عمل Codex. إذا لم يكن GPT-5.6 متاحًا، فحدد GPT-5.5 صراحةً:

openclaw models set openai/gpt-5.5

يعرض OpenClaw خطأ الوصول الصادر من المصدر ولا يستبدل ضمنيًا اختيار GPT-5.6 بـ GPT-5.5.

تغطية ميزات 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.6" } } },}

{  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.6-sol

openclaw models list --provider openai

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  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 }],      },    },  },}

مصادقة خادم تطبيق Codex الأصلي

تستخدم منظومة خادم تطبيق Codex الأصلية مراجع نماذج openai/* عندما يحددها ضمنيًا مسار HTTPS رسمي دقيق ومؤهل، أو عندما يحددها صراحةً agentRuntime.id: "codex" الخاص بالمزوّد/النموذج. تظل مصادقتها معتمدة على الحساب. يحدد OpenClaw المصادقة بهذا الترتيب:

1. ملفات تعريف مصادقة OpenAI المرتبة للوكيل، ويُفضّل أن تكون ضمن auth.order.openai. شغّل openclaw doctor --fix لترحيل معرّفات ملفات تعريف مصادقة Codex القديمة وترتيب المصادقة.
2. الحساب الموجود في خادم التطبيق، مثل تسجيل دخول ChatGPT محلي عبر Codex CLI. بالنسبة إلى مجلد الوكيل المعزول الافتراضي، يصل OpenClaw حساب CLI الأصلي هذا بخادم التطبيق عبر RPC لتسجيل الدخول؛ ولا يشارك إعدادات CLI أو plugins الخاصة به أو مخزن سلاسل المحادثات.
3. لتشغيل خادم التطبيق محليًا عبر stdio فقط، وفقط عندما يبلغ خادم التطبيق عن عدم وجود حساب: CODEX_API_KEY، ثم OPENAI_API_KEY.

لا يُستبدل تسجيل دخول محلي باشتراك ChatGPT/Codex لمجرد أن عملية Gateway تحتوي أيضًا على OPENAI_API_KEY لنماذج OpenAI المباشرة أو التضمينات. ينطبق الرجوع الاحتياطي إلى مفتاح API من البيئة فقط على مسار stdio المحلي الذي لا يحتوي على حساب؛ ولا يُرسل أبدًا عبر اتصالات خادم التطبيق باستخدام WebSocket. عند تحديد ملف تعريف Codex بنمط الاشتراك، يمنع OpenClaw أيضًا CODEX_API_KEY وOPENAI_API_KEY من الوصول إلى عملية خادم التطبيق الفرعية المشغّلة عبر stdio، ويرسل بيانات الاعتماد المحددة عبر RPC لتسجيل الدخول إلى خادم التطبيق بدلًا من ذلك.

عندما يُحظر ملف تعريف الاشتراك هذا بسبب حد استخدام Codex، يضع OpenClaw علامة الحظر على ملف التعريف حتى وقت إعادة الضبط الذي يعلنه Codex، ويسمح لترتيب المصادقة بالانتقال إلى ملف تعريف openai:* التالي، من دون تغيير النموذج المحدد أو الخروج من منظومة Codex. بعد انقضاء وقت إعادة الضبط، يصبح ملف تعريف الاشتراك مؤهلًا مجددًا.

توليد الصور

يسجّل 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 قابلة للاستخدام كتجاوزات صريحة للنموذج. استخدم openai/gpt-image-1.5 لإخراج PNG/WebP بخلفية شفافة؛ ترفض واجهة 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 "ملصق دائرة حمراء بسيط على خلفية شفافة" \  --json

استخدم علامتي --output-format و--background نفسيهما مع openclaw infer image edit عند البدء من ملف إدخال. يظل --openai-background متاحًا كاسم بديل خاص بـ OpenAI. استخدم --quality low|medium|high|auto للتحكم في جودة OpenAI Images وتكلفتها. استخدم --openai-moderation low|auto لتمرير تلميح الإشراف الخاص بـ OpenAI من image generate أو image edit.

بالنسبة إلى عمليات تثبيت OAuth عبر ChatGPT/Codex، أبقِ مرجع openai/gpt-image-2 نفسه. عند إعداد ملف تعريف OAuth من نوع openai، يحل OpenClaw رمز وصول OAuth المخزّن ويرسل طلبات الصور عبر واجهة Codex Responses الخلفية؛ ولا يحاول أولًا استخدام OPENAI_API_KEY ولا يرجع بصمت إلى مفتاح API. اضبط models.providers.openai صراحةً باستخدام مفتاح API أو عنوان URL أساسي مخصص أو نقطة نهاية Azure عندما تريد استخدام مسار OpenAI Images API المباشر بدلًا من ذلك. إذا كانت نقطة نهاية الصور المخصصة هذه على شبكة LAN موثوقة أو عنوان خاص، فاضبط أيضًا browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true؛ إذ يبقي OpenClaw نقاط نهاية الصور الخاصة/الداخلية المتوافقة مع OpenAI محظورة ما لم يكن هذا الاشتراك الصريح موجودًا.

التوليد:

/tool image_generate model=openai/gpt-image-2 prompt="ملصق إطلاق مصقول لـ OpenClaw على macOS" size=3840x2160 count=1

توليد صورة PNG شفافة:

/tool image_generate model=openai/gpt-image-1.5 prompt="ملصق دائرة حمراء بسيط على خلفية شفافة" outputFormat=png background=transparent

التحرير:

/tool image_generate model=openai/gpt-image-2 prompt="حافظ على شكل العنصر، وغيّر مادته إلى زجاج شفاف جزئيًا" 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 لدى المزوّد openai (بما في ذلك مراجع Codex القديمة السابقة للإصلاح التي تُسوّى إلى openai/*). لا تتلقى المزوّدات الأخرى التي توفر أيضًا معرّفات نماذج عائلة GPT-5، مثل مسارات OpenRouter أو opencode، هذه الطبقة؛ إذ تعتمد بوابتها على معرّف المزوّد openai، لا على معرّف النموذج وحده. ولا تتلقاها نماذج GPT-4.x الأقدم مطلقًا.

لا يتلقى إطار خادم التطبيق الأصلي في Codex عقد سلوك الشخصية والانضباط في استخدام الأدوات، ولا طبقة أسلوب التفاعل الودّي، عبر تعليمات المطوّر؛ إذ يحتفظ Codex الأصلي بسلوك الأساس والنموذج ووثائق المشروع الذي يملكه Codex، ويعطّل OpenClaw الشخصية المضمّنة في Codex لسلاسل المحادثات الأصلية كي تظل ملفات شخصية مساحة عمل الوكيل هي المرجع المعتمد. ولا يضيف OpenClaw إلى سلاسل Codex الأصلية سوى سياق وقت التشغيل: تسليم القنوات، وأدوات OpenClaw الديناميكية، وتفويض ACP، وسياق مساحة العمل، وSkills في OpenClaw. ويُعد نص إرشادات Heartbeat من هذه المساهمة نفسها الاستثناء الوحيد: إذ تتلقى دورات Heartbeat الأصلية في Codex هذا النص، ويُحقن بوصفه تعليمات تعاون مخصصة بدلًا من حقنه عبر خطاف مساهمة الموجّه المشتركة.

تضيف مساهمة GPT-5 عقد سلوك موسومًا لاستمرار الشخصية، وسلامة التنفيذ، والانضباط في استخدام الأدوات، وشكل المخرجات، وفحوصات الإكمال، والتحقق في الموجّهات المطابقة التي يجمعها 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 المضمّن استهداف مورد Azure OpenAI لتوليد الصور من خلال تجاوز عنوان URL الأساسي. في مسار توليد الصور، تكتشف 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=... بكل طلب
• تستخدم مهلة طلب افتراضية قدرها 600s لاستدعاءات توليد الصور عبر 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="ملصق أنيق" 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.

الإعداد المتقدم

تحدد أمثلة params لكل نموذج أدناه بنية طلب المزوّد المضمّن في OpenClaw. يُعد ضبطها سلوكًا مؤلفًا للطلب، ولذلك يظل مسار auto المؤهل بطريقة أخرى على OpenClaw بدلًا من اختيار Codex ضمنيًا. يدير مسخّر خادم تطبيق Codex الأصلي إعدادات النقل والطلب الخاصة به؛ ويفشل agentRuntime.id: "codex" الصريح بصورة مغلقة عندما لا يكون المسار الفعلي معلنًا على أنه متوافق مع Codex.

{  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: "default" },    },  },}

ذو صلة