OpenAI

توفر OpenAI واجهات API للمطورين لنماذج GPT، ويتوفر Codex أيضًا كوكيل برمجة ضمن خطة ChatGPT عبر عملاء Codex من OpenAI. يبقي OpenClaw هذه الأسطح منفصلة حتى يظل الإعداد قابلاً للتنبؤ.

يستخدم OpenClaw المسار openai/* باعتباره مسار نموذج OpenAI القياسي. تعمل دورات الوكيل المضمّنة على نماذج OpenAI عبر وقت تشغيل خادم تطبيق Codex الأصلي افتراضيًا؛ وتظل مصادقة مفتاح API المباشرة من OpenAI متاحة لأسطح OpenAI غير الوكيلة مثل الصور والتضمينات والكلام والوقت الفعلي.

• نماذج الوكلاء - نماذج openai/* عبر وقت تشغيل Codex؛ سجّل الدخول باستخدام مصادقة Codex لاستخدام اشتراك ChatGPT/Codex، أو اضبط نسخة احتياطية متوافقة مع Codex لمفتاح API من OpenAI عندما تريد عمدًا مصادقة مفتاح API.
• واجهات 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

تضمينات الذاكرة

يمكن لـ 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: "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:[email protected]",        "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 }],      },    },  },}

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

تستخدم حاضنة خادم تطبيق Codex الأصلية مراجع نماذج openai/* مع تكوين وقت تشغيل محذوف أو موفر/نموذج agentRuntime.id: "codex"، لكن مصادقتها لا تزال قائمة على الحساب. يختار OpenClaw المصادقة بهذا الترتيب:

1. ملفات تعريف مصادقة OpenAI المرتبة للوكيل، ويفضل أن تكون تحت auth.order.openai. تظل ملفات تعريف openai-codex:* الحالية و auth.order.openai-codex صالحة للتثبيتات الأقدم.
2. حساب خادم التطبيق الحالي، مثل تسجيل دخول ChatGPT محلي عبر Codex CLI.
3. لعمليات تشغيل خادم التطبيق المحلي عبر stdio فقط، CODEX_API_KEY، ثم OPENAI_API_KEY، عندما يبلّغ خادم التطبيق عن عدم وجود حساب ولا يزال يتطلب مصادقة OpenAI.

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

توليد الصور

يسجل Plugin openai المضمّن توليد الصور عبر أداة image_generate. يدعم توليد الصور بمفتاح API الخاص بـ OpenAI وتوليد الصور عبر Codex OAuth من خلال مرجع النموذج نفسه 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 بخلفية شفافة؛ ترفض واجهة API الحالية لـ gpt-image-2 background: "transparent".

لطلب بخلفية شفافة، يجب أن يستدعي الوكلاء image_generate مع model: "openai/gpt-image-1.5" و outputFormat: "png" أو "webp" و background: "transparent"؛ ولا يزال خيار الموفر الأقدم openai.background مقبولًا. يحمي OpenClaw أيضًا مسارات OpenAI العامة و OpenAI Codex OAuth بإعادة كتابة طلبات الشفافية الافتراضية لـ 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.

بالنسبة إلى تثبيتات Codex OAuth، أبقِ المرجع نفسه openai/gpt-image-2. عند تكوين ملف تعريف OAuth باسم openai-codex، يحل 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="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 عبر تعليمات المطوّر لخادم تطبيق 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 المضمّن استهداف مورد 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=... إلى كل طلب
• يستخدم مهلة طلب افتراضية قدرها 600 ثانية لاستدعاءات توليد الصور في Azure. تظل قيم timeoutMs لكل استدعاء تتجاوز هذا الافتراضي.

تحافظ عناوين URL الأساسية الأخرى (OpenAI العام، والوكلاء المتوافقون مع OpenAI) على شكل طلب الصور القياسي في OpenAI.

إصدار واجهة برمجة التطبيقات

اضبط AZURE_OPENAI_API_VERSION لتثبيت إصدار معاينة Azure محدد أو إصدار GA لمسار إنشاء الصور في 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 بخطأ تحقق، فتحقق من مجموعة المعلمات المدعومة بواسطة النشر وإصدار واجهة برمجة التطبيقات المحددين لديك في بوابة 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" },    },  },}

ذات صلة