OpenAI CLI: تثبيت واستدعاء OpenAI API من سطر الأوامر

أداة OpenAI CLI هي أداة سطر الأوامر الرسمية من OpenAI لواجهة OpenAI REST API. تُثبّت ملفًا تنفيذيًا واحدًا باسم openai، وتضبط OPENAI_API_KEY، ثم تستدعي الواجهة من الطرفية أو من نص برمجي صدفي: openai responses create، openai files upload، openai batches create، openai images generate. وهي ليست Codex CLI. فـ Codex وكيل برمجي؛ أما openai فيرسل طلبًا واحدًا إلى الواجهة لكل أمر.

يغطي هذا الدليل التثبيت، والمصادقة، وأول الأوامر التي تستحق التجربة، وكيفية مقارنتها مع Codex CLI ومع أمر openai القديم الذي كانت حزمة Python SDK تضعها على مسار PATH لديك. كل أمر ومخرَج أدناه مأخوذ من الإصدار 1.44.1، بعد تثبيته وتشغيله في 28 أكتوبر 2026.

ما هي أداة OpenAI CLI؟

أداة OpenAI CLI هي ملف تنفيذي مفتوح المصدر مكتوب بلغة Go، تنشره OpenAI على github.com/openai/openai-cli بموجب رخصة Apache 2.0. تحاكي أوامرها موارد الواجهة (responses، files، batches، images، audio، vector-stores، admin)، لذا يتحول أي شيء كنت سترسله باستخدام curl أو إحدى حزم SDK إلى أمر طرفية واحد مع خيارات.

وهي ليست جديدة تمامًا. فقد صدر الإصدار 1.0.0 في 5 مايو 2026، وأصدر المشروع 99 إصدارًا منذ ذلك الحين؛ وصدر الإصدار 1.44.1 في 27 أكتوبر 2026. لذا تعامل معها كأداة ناضجة ربما فوّتها، لا كإطلاق جديد.

إليك ما تحصل عليه عند أول تشغيل:

تُجمّع المساعدة الأوامر حسب المهمة: توليد المحتوى (responses، chat، images، audio، videos)، والبيانات والاسترجاع (files، uploads، vector-stores، embeddings)، والنماذج والمهام، والإدارة، ومجموعة من الأدوات المحلية التي لا تلمس الشبكة أبدًا. المساعدة نفسها لا تحتاج إلى مفتاح API ولا إلى اتصال، ما يجعل openai <command> --help أسرع طريقة لتعلم الخيارات.

وهي تناسب المطورين الذين يختبرون طلبًا دون كتابة نص برمجي، وفرق التشغيل الذين يريدون رفع الملفات والدفعات ضمن مهمة cron، والوكلاء البرمجيين الذين يحتاجون إلى واجهة موثّقة بدلًا من curl المكتوب يدويًا.

كيفية تثبيت OpenAI CLI

لديك ثلاثة مسارات للتثبيت، جميعها مدرجة في ملف README الخاص بالمشروع:

1. ملف تنفيذي جاهز. نزّل الأرشيف الخاص بنظام التشغيل والمعمارية لديك من إصدارات GitHub (تُنشر إصدارات macOS و Linux و Windows)، واستخرجه، وضع openai على مسار PATH لديك.
2. Homebrew.

brew install openai/tools/openai

3. Go. يتطلب Go 1.26 أو أحدث.

go install 'github.com/openai/openai-cli/cmd/openai@latest'
export PATH="$PATH:$(go env GOPATH)/bin"

يمكن لعمليات التثبيت المُدارة ذاتيًا من الإصدارات أن تحدّث نفسها أثناء التشغيل التفاعلي. إذا ثبّت نسخًا محددة في CI، فاضبط OPENAI_CLI_NO_AUTO_UPDATE=1 لإيقاف التثبيت التلقائي، أو OPENAI_CLI_NO_UPDATE_CHECK=1 لإيقاف فحوص التحديث كليًا. أما تثبيتات Homebrew و Go فتحتفظ بإشعارات التحديث لكنها تترك الترقيات لمدير الحزم.

كيفية عمل المصادقة في OpenAI CLI

تقرأ الأداة مفتاح API قياسيًا من OPENAI_API_KEY (أو من الخيار --api-key، وهو ما يجدر تجنبه لأنه يبقى في سجل الطرفية). إن لم يكن لديك مفتاح بعد، فإن دليلنا حول الحصول على مفتاح OpenAI API يشرح ذلك خطوة بخطوة.

أسرع إعداد هو الدليل المدمج:

openai help setup

وهو يوجّهك إلى صفحة مفاتيح API ويمنحك سطر read -rs OPENAI_API_KEY الخاص بـ Bash أو zsh، بحيث يُكتب المفتاح مخفيًا ولا يظهر أبدًا.

إذا نسيت المفتاح فستحصل على فشل واضح وقابل للبرمجة. هذا هو المخرَج الفعلي دون ضبط أي مفتاح:

يخرج بحالة 1 ويخبرك بدقة من أين يمكن أن يأتي المفتاح. أضِف --format-error json عندما يحتاج نص برمجي إلى جسم الخطأ الخام.

إعدادات المصادقة الأخرى:

أول أوامر OpenAI CLI التي تستحق التشغيل

يتبع شكل الأمر الواجهة: openai <resource> [subresource...] <command> [flags...]. وهذه هي الأوامر التي تستحق مكانًا في صندوق أدواتك.

إجراء استدعاء إلى Responses API

openai responses create \
  --model gpt-5.5 \
  --input "Say this is a test"

الطلبات الطويلة لا تحتاج إلى تهريب. تقرأ خيارات إدخال JSON من ملف باستخدام @path:

openai responses create --model gpt-5.5 --input @prompt.txt

إذا مرّرت JSON أو YAML عبر أنبوب من مصدر لا تثق به، فاضبط OPENAI_UNTRUSTED_STDIN=1 حتى لا ي triggering ذلك الإدخال قراءات محلية للملفات.

رفع الملفات وجلبها

openai files upload report.txt --purpose user_data
openai files get file-example
openai files download file-example --output downloaded-report.txt

تشغيل دفعة

ضع طلبًا واحدًا في كل سطر في requests.jsonl، ولكل منها custom_id فريد، ثم:

openai files upload requests.jsonl --purpose batch
openai batches create --input-file-id file-example \
  --endpoint /v1/responses --completion-window 24h
openai batches wait batch_example --output-dir ./results

يستمر batches wait في الاستعلام حتى تنتهي الدفعة ويحفظ ملفات النتائج، ما يغني عن حلقة الاستعلام التي كنت ستكتبها بنفسك. يسرد دليل الدفعات الخاص بالمشروع الحدود الحالية بأنها 50,000 طلب و200 ميغابايت لكل ملف إدخال، مع نافذة إكمال 24h. تختلف أسعار الدفعات عن الاستدعاءات المتزامنة؛ راجع تفصيلنا حول أسعار OpenAI API قبل أن تصفّ مهمة كبيرة.

عدّ الرموز محليًا، دون مفتاح

يعمل الأمر tokenizer دون اتصال بالكامل: لا بيانات اعتماد، ولا شبكة، ولا إدخال محفوظ.

الترميز الافتراضي هو o200k_base، ويسرد openai tokenizer encodings الترميزات الأخرى (cl100k_base، إضافة إلى ترميزين قديمين). والمساعدة صريحة بشأن الحدود: العدّ للنص العادي لا يشمل بنية الطلب ولا المدخلات متعددة الوسائط، لذا فهو ليس رقم فاتورة. للحصول على عدّ من جانب الخادم، استخدم openai responses input-tokens count.

الحصول على مخرَج يمكن لنص برمجي تحليله

المخرَج الافتراضي نص مقروء، حتى عند تمريره عبر أنبوب. اطلب البيانات صراحةً:

openai models list --format jsonl | jq '.id'
openai files list --format json > files.json
openai files get file-example --transform filename --raw-output

يقبل --format القيم auto، text، json، jsonl، yaml، explore (عارض JSON تفاعلي) وpretty. يستخرج --transform الحقول بصيغة GJSON، ويتولى jq أي شيء أعقد. تحقق دائمًا من حالة الخروج قبل الوثوق بملف معاد توجيهه: فالطلب الفاشل قد يترك ملفًا جزئيًا خلفه.

عندما يسلك استدعاء سلوكًا غير سليم، يضيف --debug توقيت HTTP لكل محاولة؛ ونقّح سجلاته قبل مشاركتها. إذا كنت تواجه أخطاء 429، فإن دليلنا حول حدود معدل OpenAI يشرح الفئات.

OpenAI CLI مقابل Codex CLI مقابل أمر openai القديم

ثلاث أدوات تشترك في المورّد واثنتان تشتركان في الاسم. هذه هي النسخة المختصرة:

شغّل openai codex وستطبع OpenAI CLI أوامر تثبيت Codex بنفسها، مع التنبيه إلى أنها أداة منفصلة بتسجيل دخول خاص بها. يغطي دليلنا حول Codex CLI جانب الوكيل، والمصدر موجود على github.com/openai/codex.

احترس من تعارض المسار

حزمة openai بلغة Python تثبّت أيضًا ملفًا تنفيذيًا اسمه openai. إذا سبق أن شغّلت pip install openai، فقد يكون لديك اثنان:

على هذا الجهاز Mac يُبلّغ إصدار Python عن openai 2.30.0 ويوفر الأوامر الفرعية api و tools و migrate و grit؛ بينما يُبلّغ إصدار Go عن openai version 1.44.1. وأي دليل يأتي أولًا في مسار PATH يفوز. شغّل which -a openai و openai --version بعد التثبيت. إذا قال المخرَج openai version 1.44.1 (أو أحدث)، فلديك الإصدار الصحيح. أما إذا طبع رقم إصدار مجردًا مثل openai 2.30.0، فأعد ترتيب مسار PATH أو استدعِ الملف التنفيذي الجديد بمساره الكامل.

أين يقع Apidog CLI بجانب OpenAI CLI

توجّه OpenAI CLI استدعاءات إلى OpenAI. وهي لا تعرف شيئًا عن واجهتك الخاصة: النقاط الطرفية التي يعرضها تطبيقك فوق OpenAI، أو البيئات التي تنشر إليها، أو التأكيدات التي تثبت أن الإصدار الجديد لم يكسر شيئًا. فتلك مهمة مختلفة، وهنا يأتي دور Apidog CLI. أنت لا تختار إحداهما على حساب الأخرى؛ فمعظم الفرق التي تشحن ميزة ذكاء اصطناعي تريد الاثنتين.

والأفضل من ذلك، دع وكيلك البرمجي يشغّل الاثنتين. هيّئ Apidog CLI مرة واحدة:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

ثم أعطِ وكيلك طلبًا واحدًا:

Use the openai CLI to confirm my key works with one responses create call on gpt-5.5.
Then import ./openapi.yaml into Apidog project <id>, create a test case for
POST /v1/summarize that asserts a 200 and a non-empty "summary" field, run it
against the staging environment and summarize any failures.

يتحقق الوكيل من المفتاح باستخدام openai، ثم يعمل عبر Apidog CLI. يقرأ المخطط قبل كتابة أي حِمل، ويتحقق من الملف، وعندها فقط ينشئ الحالة ويشغّلها:

apidog import --project <id> --format openapi --file ./openapi.yaml
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json

هناك تفصيلان من apidog test-case create --help يوفّران جولة كاملة: تحتاج الحالة إلى categoryId صالح (اسردها باستخدام apidog test-case category --project <id>)، ويجب أن تأتي الحِمول من cli-schema، لا من الذاكرة أبدًا. والسطر نفسه من apidog run مع -r junit يندمج في CI، كما يوضح دليل Apidog CLI لتكامل CI/CD. وإذا كان Codex هو وكيلك، فابدأ بـ Apidog CLI في Codex.

تغطي خطة Apidog المجانية ما يصل إلى 4 مستخدمين، لذا يمكن لفريق صغير تجربة هذا دون قرار شراء.

الأسئلة الشائعة

هل OpenAI CLI مجانية؟ الأداة مجانية ومفتوحة المصدر بموجب Apache 2.0. أما استدعاءات API التي تجريها فتُحسب على حسابك في OpenAI بأسعار API العادية. الأوامر المحلية مثل openai tokenizer وكل صفحة --help لا تكلف شيئًا ولا تحتاج إلى مفتاح.

هل OpenAI CLI هي نفسها Codex CLI؟ لا. يرسل openai طلبات API مباشرة، طلبًا واحدًا لكل أمر. أما codex فهو وكيل برمجي يقرأ مشروعك ويعدّله ويشغّل الأوامر. وهما يُثبّتان بشكل منفصل ويُصادَقان بشكل منفصل.

كيف أثبّت OpenAI CLI على جهاز Mac؟ شغّل brew install openai/tools/openai، أو نزّل ملف zip الخاص بـ macos_arm64 (Apple Silicon) أو macos_amd64 (Intel) من إصدارات GitHub وضع الملف التنفيذي على مسار PATH لديك. ثم شغّل openai --version للتأكد من أنك لا تصادف أمر openai القديم الخاص بـ Python.

هل تعمل OpenAI CLI في النصوص البرمجية الصدفية و CI؟ نعم، وهذا هدفها التصميمي الأساسي. استخدم --format json أو jsonl للحصول على مخرَج قابل للتحليل، وتحقّق من حالة الخروج، واحتفظ بالمفتاح في OPENAI_API_KEY من مدير الأسرار لديك، واضبط OPENAI_CLI_NO_AUTO_UPDATE=1 للحفاظ على الإصدار مثبّتًا.

متى صدرت OpenAI CLI؟ نُشر الإصدار 1.0.0 على GitHub في 5 مايو 2026. واعتبارًا من 28 أكتوبر 2026، فإن أحدث إصدار هو 1.44.1، من 27 أكتوبر.