OpenAI

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

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

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

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

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

# اختيار سريع

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

الأسماء متشابهة لكنها ليست قابلة للتبادل:

يعني هذا أن الإعدادات يمكن أن تحتوي عمدًا على مراجع نماذج openai/* وملفات تعريف مصادقة 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

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

openclaw doctor --fix
openclaw config validate

openclaw models auth login --provider openai-codex
openclaw 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-codex صريح في OpenClaw مربوط بالوكيل.
2. حساب خادم التطبيق الموجود، مثل تسجيل دخول ChatGPT المحلي في Codex CLI.
3. لعمليات تشغيل خادم التطبيق المحلية عبر stdio فقط، CODEX_API_KEY، ثم OPENAI_API_KEY، عندما يبلّغ خادم التطبيق عن عدم وجود حساب ولا يزال يتطلب مصادقة OpenAI.

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

# إنشاء الصور

يسجّل 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 المفروضة عبر agentRuntime.id: "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.

# إصدار API

اضبط 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 مع خطأ تحقق، فتحقق من مجموعة المعلمات المدعومة بواسطة عملية النشر وإصدار API المحددين في بوابة Azure.

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

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

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

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

# ذات صلة