دليل Codex CLI: دليل البدء السريع الكامل

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

Codex CLI هو وكيل ترميز قائم على الطرفية مفتوح المصدر من OpenAI. يعمل كمساعد ترميز AI يمكنه فهم قاعدة الكود الخاصة بك والبحث عبر الملفات وتحرير الكود وتشغيل الاختبارات وتنفيذ أوامر git. كونه مفتوح المصدر، يمكنك تخصيص وتوسيع وظائفه.

ما هو Codex CLI؟

تشمل الميزات الرئيسية: فهم الكود المدرك للسياق عبر المشروع بأكمله، قدرات تحرير الملفات (إنشاء وتعديل وحذف الملفات)، تنفيذ الأوامر (تشغيل الاختبارات وعمليات git والبناءات)، تصحيح الأخطاء وإصلاحها (تحديد وإصلاح الأخطاء)، وأتمتة سير العمل (تنفيذ مهام متعددة الخطوات بشكل مستقل).

المتطلبات الأساسية

قبل التثبيت، تأكد من أن لديك: Node.js 18 أو أحدث، npm أو yarn مثبت، حساب OpenAI مع مفتاح API، وبيئة طرفية (Terminal.app، Windows Terminal، أو أي محاكي طرفية).

npm install -g @openai/codex

يعمل Codex CLI كوكيل ترميز يمكنه: فهم قاعدة الكود الخاصة بك (قراءة وتحليل الملفات عبر مشروعك)، إجراء التغييرات (إنشاء وتحرير وحذف الملفات)، تنفيذ المهام (تشغيل الاختبارات والبناءات وعمليات git)، وتقديم التفسيرات (شرح الكود المعقد واقتراح التحسينات).

codex --version
# Output: @openai/codex/1.2.0 darwin-arm64 node-v20.11.0

سير العمل النموذجي مع Codex CLI يتبع نمطًا: 1) تصف ما تريد تحقيقه. 2) يقرأ Codex CLI الملفات ذات الصلة لفهم السياق. 3) يخطط Codex CLI للتغييرات ويقدمها. 4) تراجع التغييرات المقترحة. 5) يوافق Codex CLI على التغييرات وينفذها. 6) يتحقق Codex CLI من أن التغييرات تعمل (تشغيل الاختبارات، إلخ).

npx @openai/codex "Explain the architecture of this project"

تثبيت Codex CLI

ابدأ بوصف واضح: 'أضف التحقق من صحة البريد الإلكتروني إلى نموذج التسجيل' أو 'أصلح خطأ NullPointerException في UserService.' كلما كان وصفك أكثر تحديدًا، كانت النتائج أفضل.

• أوامر Codex CLI الأساسية: /help - عرض جميع الأوامر المتاحة، /clear - مسح سجل المحادثة، /context - عرض ملفات السياق الحالية.
• <مسار><مسار> - إزالة ملف من السياق، /review - مراجعة التغييرات الحالية، /commit - إنشاء رسالة التزام git.
• أدوات المطور: /test - تشغيل الاختبارات، /lint - تشغيل الفاحص، /build - تشغيل البناء، /format - تنسيق الكود.

المصادقة

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

{
  "model": "gpt-4o",
  "max_tokens": 4096,
  "temperature": 0.7,
  "max_files": 10,
  "confirm_before_write": true,
  "context_size": 128000
}

لتجنب الأخطاء، استخدم التحكم بالإصدارات (git) بحيث يمكنك إعادة التغييرات، واختبر بدقة بعد كل تغيير، وقم دائمًا بمراجعة الكود الذي ينتجه Codex CLI قبل دمجه.

الميزات الرئيسية

Codex CLI هو وكيل ترميز قائم على الطرفية مفتوح المصدر من OpenAI. يعمل كمساعد ترميز AI يمكنه فهم قاعدة الكود الخاصة بك والبحث عبر الملفات وتحرير الكود وتشغيل الاختبارات وتنفيذ أوامر git. يمكنه تنفيذ مهام ترميز معقدة من البداية إلى النهاية.

cd my-project
codex

Codex CLI مفتوح المصدر ومجاني للاستخدام. تحتاج إلى مفتاح API من OpenAI، والذي قد يكون له تكاليف مرتبطة اعتمادًا على استخدامك. راجع موقع OpenAI للحصول على أحدث معلومات التسعير.

You: Summarize the structure of this project
Codex: This project appears to be a React application built with Vite.
It has the following structure:
- src/          Main application source code
- src/components/  Reusable UI components
- src/pages/    Page-level components
- public/       Static assets
- package.json  Project dependencies and scripts

Key dependencies include React 18, React Router, and Axios for API calls.

npm install -g @openai/codex-cli، ثم قم بالمصادقة باستخدام codex login. يتطلب Node.js 18 أو أحدث.

التثبيت والإعداد

Codex CLI هو وكيل ترميز مستقل يمكنه تنفيذ مهام ترميز كاملة، بينما GitHub Copilot هو أداة إكمال تلقائي مدمجة في IDE. يمكن لـ Codex CLI إدارة الملفات وتنفيذ الأوامر وتشغيل الاختبارات. يقترح Copilot أسطرًا أو كتلًا من الكود أثناء الكتابة.

فهم سير العمل

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

codex "Create a Python script that fetches weather data from OpenWeatherMap API, caches results in SQLite, and exposes a simple CLI interface with --city and --forecast flags"

Codex CLI generates a complete, well-structured script with proper error handling, API request logic, database operations, and argument parsing — all from a single natural language prompt. The generated code follows Python conventions, includes type hints where appropriate, and handles edge cases like network failures and missing API keys.

الأوامر الأساسية

Codex CLI understands project context across multiple files. When you request a feature that spans several modules — such as adding authentication to a web application — it creates or modifies all the relevant files in a single coherent operation. This includes creating new components, updating routing configuration, adding API endpoints, and modifying data models as needed. The tool maintains consistency across files, ensuring that imports are correct, function signatures match, and naming conventions stay uniform throughout your codebase.

الأوامر المتقدمة

Dropped into an unfamiliar codebase? Codex CLI can explain what any block of code does, trace the flow of data through a system, and identify potential issues. You can point it to specific files or functions:

codex "Explain the authentication middleware in src/middleware/auth.ts. What flow does a request follow, and what edge cases are handled?"

For code review, you can ask Codex to examine a diff or a set of changed files and provide feedback on code quality, potential bugs, performance concerns, and adherence to best practices. This makes it an excellent tool for self-review before opening a pull request.

أدوات المطور

Writing tests is often tedious, but Codex CLI can generate comprehensive test suites from your existing code. It analyzes your functions, identifies edge cases, and produces unit tests, integration tests, or end-to-end tests depending on what you request:

codex "Write unit tests for src/utils/validator.ts using Vitest. Cover all functions, edge cases for empty input, invalid types, and boundary values. Aim for 100% coverage."

Codex also understands mocking — it can look at your dependencies and generate appropriate mocks for external services, database calls, and file system operations, producing tests that actually run without requiring a full environment setup.

ضمان الجودة

Codex CLI integrates naturally with Git workflows. It can generate meaningful commit messages based on your staged changes, create pull request descriptions that summarize your work, and even help resolve merge conflicts by understanding the intent behind conflicting changes:

codex "Generate a detailed commit message for my staged changes"
codex "Create a PR description summarizing the changes in this branch compared to main"

For more advanced Git operations, you can ask Codex to explain a complex Git history, suggest branching strategies, or generate a changelog from commit history — all from the comfort of your terminal.

مقارنة Codex CLI و Claude Code

findgrepawkjq command, explaining each part so you learn as you go:

codex "Write a command to list the 10 largest files in my project, excluding node_modules and .git"

سير العمل الأساسي

Understanding Codex CLI's modes and options unlocks its full potential. Here are the essential commands and workflow patterns you will use daily.

مقارنة Codex CLI و GitHub Copilot

Interactive modecodex without arguments) starts a persistent session where you can have a multi-turn conversation, refining your requests iteratively. The AI maintains context throughout the session, so each follow-up builds on previous exchanges. This is ideal for complex, multi-step tasks where you want to guide the AI through incremental improvements.

One-shot modecodex "your prompt") executes a single prompt and returns the result immediately. This is perfect for quick tasks — generating a script, explaining a function, or creating a configuration file — where you do not need an ongoing conversation. One-shot mode is also well-suited for scripting and automation, where you pipe Codex CLI's output into other tools.

مقارنة Codex CLI و Cursor

--file-f) flag to include specific files:

codex --file src/api/users.ts --file src/types/user.ts "Add a new endpoint for updating user roles"

--dir, or use glob patterns to include multiple files matching a pattern. This targeted context passing is essential for large projects where including every file would exceed the model's context window.

ما هو Codex CLI؟

gpt-4o--model flag:

gpt-4o-minigpt-4o and the reasoning models for complex architectural decisions, difficult debugging sessions, or when you need the highest-quality output for production-critical code.

هل Codex CLI مجاني؟

codex sessionscodex --session <id>codex sessions clear. Sessions persist across terminal restarts, so you can pick up exactly where you left off:

codex sessions
# ID        Started              Model     Messages
# abc123    2026-05-25 14:30     gpt-4o    12
# def456    2026-05-25 09:15     gpt-4o    8

codex --session abc123

الميزات المتقدمة

With multiple AI coding tools now available in the terminal, choosing between them can be challenging. Here is an honest comparison between Codex CLI and Claude Code to help you decide which tool fits your workflow.

كيفية تثبيت Codex CLI؟

Both tools operate in the terminal as AI pair programmers. They can read your codebase, understand context across multiple files, and generate or modify code based on natural language prompts. Both support interactive sessions and one-shot commands, integrate with Git workflows, and let you choose between different model tiers. They also share core capabilities like code explanation, refactoring, test generation, and shell command assistance.

ما الفرق بين Codex CLI و GitHub Copilot؟

هل يمكن لـ Codex CLI كتابة ملفات المشروع بأكمله؟

Choose Codex CLI when: You need rapid code generation, are working on greenfield projects where speed matters, want to generate boilerplate or scaffolding quickly, need efficient multi-file batch operations, or are already using other OpenAI tools and have API credits available. Codex CLI's generation speed makes it especially well-suited for prototyping and iterating quickly.

Choose Claude Code when: You are doing deep code review and analysis, need nuanced architectural guidance, are working on safety-critical systems where thoroughness matters more than speed, or prefer Anthropic's approach to AI safety and alignment. Claude Code's strength in reasoning and careful analysis makes it excellent for understanding complex legacy codebases.

Many developers find value in using both tools. A common pattern is using Codex CLI for initial generation and rapid iteration, then switching to Claude Code for final review and refinement before merging. The tools are complementary rather than competing, and using them together can produce better results than relying on either one alone.

أفضل الممارسات

Getting the most out of Codex CLI requires more than just knowing the commands. These best practices will help you produce higher-quality results, manage costs, and avoid common pitfalls.

Crafting Effective Prompts

specificcontext-richconstraint-aware. Instead of "Add authentication to my app," try:

codex "Add JWT-based authentication to the Express API in src/server.ts. Requirements:
- Use bcrypt for password hashing
- Create a POST /auth/login endpoint that returns access and refresh tokens
- Add an auth middleware that validates tokens on protected routes
- Store refresh tokens in the existing PostgreSQL database
- Follow the existing error handling pattern from src/middleware/errorHandler.ts
- Write tests using the existing Vitest setup"

The more context and specific requirements you provide, the more accurate and useful the output will be. Mention existing patterns, libraries, and conventions in your project to help Codex CLI produce code that integrates seamlessly.

Managing Context Windows

--file flag to include only the files relevant to your current task. Start new sessions for unrelated tasks to keep the context focused. If you notice the AI losing track of earlier instructions, it is a sign that the context window is getting crowded — break your task into smaller pieces or start a fresh session with a tighter prompt.

Security Considerations

AI-generated code should never be trusted blindly, especially when it involves security-sensitive operations. Always review generated code for potential vulnerabilities before running it in production. Common concerns include SQL injection risks in generated queries, hardcoded credentials or API keys, insufficient input validation, improper handling of user data, and outdated or vulnerable dependency versions. Treat AI-generated code the same way you would treat code from a junior developer — review it thoroughly before merging.

Additionally, be mindful of what code you share with Codex CLI. If your codebase contains proprietary algorithms, API keys, or sensitive business logic, consider whether that data should be sent to OpenAI's servers. Review OpenAI's data usage policies and consider using a dedicated API key with appropriate restrictions.

Code Verification After AI Generation

Establish a verification workflow for AI-generated code. At a minimum, run your existing test suite to confirm the generated code does not break anything. For new functionality, ask Codex CLI to generate tests alongside the implementation, then verify those tests actually pass. Use linters and formatters to ensure the generated code matches your project's style guidelines. For critical systems, perform a manual code review focusing on edge cases, error handling, and security implications.

مقارنة الأدوات

Codex CLI excels across a wide range of development scenarios. Here are the most common use cases where it delivers the greatest productivity gains.

Rapid Prototyping

When you need to validate an idea quickly, Codex CLI can generate a working prototype in minutes instead of hours. Describe the core functionality you want, and it produces a functional implementation with proper structure, error handling, and even basic styling if you are building a web interface. This dramatically shortens the feedback loop between idea and working prototype:

codex "Create a real-time collaborative whiteboard app using Next.js, Socket.io, and Canvas API. Users should be able to create rooms, share a link, and draw together in real time. Include a color picker and brush size controls."

Converting Code Between Languages

Porting a utility from Python to Go? Translating a React component to Vue? Codex CLI handles language translation with remarkable accuracy, understanding not just the syntax differences but also the idiomatic patterns of each language. Simply point it at the source file and specify the target language:

codex --file src/utils/data_processor.py "Convert this Python module to idiomatic Rust. Use serde for serialization, anyhow for error handling, and maintain the same test coverage."

Writing Boilerplate Code

Every project accumulates boilerplate — CRUD endpoints, form validation, authentication flows, database migrations, configuration files. Codex CLI eliminates the tedium of writing repetitive code. Describe the pattern once, and it generates all the boilerplate with proper structure, letting you focus on the unique parts of your application.

Debugging Complex Issues

When you are stuck on a bug, Codex CLI can analyze error logs, trace through code paths, and suggest fixes. Paste your error message along with the relevant code, and it provides a diagnosis with suggested solutions:

codex "I'm getting this error in my Next.js app: 'Hydration failed because the initial UI does not match what was rendered on the server.' Here's the component code..." [paste code]

Codex CLI can identify root causes that might take hours to discover manually — mismatched server/client rendering, race conditions, incorrect dependency versions, or subtle logical errors in complex conditionals.

Learning New APIs and Frameworks

Codex CLI is an exceptional learning companion. Instead of reading through pages of documentation, you can ask it to demonstrate how to accomplish specific tasks with a framework you are learning. Request working examples with explanations, then ask follow-up questions about the patterns and conventions:

codex "Show me how to implement file uploads with progress tracking in a FastAPI application. Explain the multipart form handling, streaming approach, and best practices for saving files securely."