ملفات تعريف أذونات Codex (Permission Profiles) هي سياسات مُسمّاة داخل config.toml تحدد ما يمكن للأوامر التي يشغّلها Codex على جهازك أن تقرأه وتكتبه وتصل إليه عبر الشبكة. تختار واحدًا منها عبر default_permissions، بدءًا من ملف تعريف مدمج (:read-only أو :workspace أو :danger-full-access)، ثم تضيف مسارات read وwrite وdeny بالإضافة إلى قائمة نطاقات مسموح بها.
يقدّم لك هذا الدليل أمثلة جاهزة للنسخ من config.toml لأكثر الإعدادات شيوعًا، بما في ذلك إعداد للعمل على واجهات API يتيح لوكيل البرمجة لديك تشغيل اختبارات Apidog CLI على مضيفات API الخاصة بك دون إنترنت مفتوح.
ما هي ملفات تعريف أذونات Codex؟
ملف تعريف الأذونات هو سياسة صندوق رمل (sandbox) قابلة لإعادة الاستخدام في Codex. فهو يجمع بين قواعد نظام الملفات (المسارات التي يمكن للأوامر قراءتها أو الكتابة فيها أو عدم لمسها مطلقًا) وقواعد الشبكة (ما إذا كان بإمكان الأوامر الوصول إلى الشبكة، وإلى أي نطاقات). يفرض Codex هذه السياسة باستخدام Seatbelt على macOS، وbubblewrap مع seccomp على Linux وWSL، وMXC على Windows.
شرحت OpenAI هذا التصميم في مقال Inside the Codex sandbox المنشور في 18 نوفمبر 2026. فبدلًا من نقل عملك إلى حاوية (container)، يقيّد Codex الأوامر داخل بيئتك الحالية، بحيث تظل سلاسل الأدوات الأصلية (native toolchains) تعمل.
يأتي Codex بثلاثة ملفات تعريف مدمجة:
| ملف التعريف | نظام الملفات | الشبكة |
|---|---|---|
:read-only |
يمكن للأوامر القراءة دون الكتابة | معطّلة |
:workspace |
الكتابة داخل جذور مساحة العمل والمجلدات المؤقتة؛ تبقى .git و.agents و.codex و.aws للقراءة فقط |
معطّلة |
:danger-full-access |
لا توجد قيود صندوق رمل محلية | كاملة ومباشرة |
لا تزال وثائق الأذونات تصنّف الميزة على أنها Beta، لذا توقّع تغيّر المفاتيح بين الإصدارات.
أين يوضع جدول الأذونات في config.toml
توجد ملفات التعريف لديك في ~/.codex/config.toml (أو في طبقة خاصة بالمشروع أو النظام). هناك جزءان رئيسيان في المستوى الأعلى يهمّانك:
default_permissionsيحدد اسم ملف التعريف الذي يطبّقه Codex افتراضيًا. ويجب أن يطابق ملفًا مدمجًا أو ملف تعريف تحت[permissions].[permissions.<name>]يعرّف ملف تعريف. أعطهdescription؛ إذ يظهر في منتقي/permissions.
هناك قاعدة يقع فيها الكثيرون. ملفات تعريف الأذونات لا تتوافق مع إعدادات صندوق الرمل القديمة. فإذا وُجد sandbox_mode في أي ملف تهيئة يتم تحميله، أو مرّرت --sandbox، فسيستخدم Codex الإعدادات القديمة ويتجاهل default_permissions. أزل sandbox_mode و[sandbox_workspace_write] قبل أن تُبدّل.
تتبع ملفات التعريف نموذج أولوية التهيئة المعتاد. تُدمج الجداول بشكل تكراري، بحيث يمكن لتهيئة فريق ما أن تضيف نطاقًا واحدًا أو مسارًا واحدًا إلى ملف تعريف المؤسسة دون إعادة كتابة كل شيء.
قواعد نظام الملفات: read وwrite وdeny
كل إدخال في نظام الملفات يربط مسارًا بقيمة read أو write أو deny. المسارات الأكثر تحديدًا تتغلب على الأعمّ، وعندما يستهدف إدخالان المسار نفسه، تتغلب deny على write، وwrite على read.
أكثر صيغ المسارات استخدامًا:
:minimal: مسارات المنصة وبيئة التشغيل التي تحتاجها الأدوات الشائعة:workspace_roots: جذور مساحة العمل للجلسة بالإضافة إلى أي جذور يضيفها ملف التعريف:rootو:tmpdirو:slash_tmpوالمسارات المطلقة ومسارات~/
استخدم extends لترث الحمايات المدمجة بدلًا من إعادة بنائها. إليك ملف تعريف يحافظ على إعدادات :workspace الافتراضية ويقيّد الأسرار:
default_permissions = "dev"
[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"
[permissions.dev.filesystem]
"~/build-cache" = "write"
[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
تُطبَّق القواعد تحت :workspace_roots على كل جذر، لذا تعني secrets مجلد secrets في كل جذر مشروع. يمكن لملف التعريف أن يمتد من :read-only أو :workspace أو أي ملف تعريف مُسمّى آخر. ولا يمكنه الامتداد من :danger-full-access.
على Linux وWSL وWindows الأصلي، قد يحتاج نمط deny غير المحدود ** إلى glob_scan_max_depth (بقيمة 1 على الأقل) تحت [permissions.<name>.filesystem] كي يتمكن Codex من توسيعه قبل بدء صندوق الرمل.

قواعد الشبكة: معطّلة أو مفتوحة أو بقائمة سماح
للشبكة ثلاث حالات، ويتحكم فيها إعدادان:
- الشبكة معطّلة (
enabled = false، وهو الافتراضي في:workspace): لا يمكن للأوامر الوصول إلى الشبكة. - الشبكة مفعّلة والوكيل (proxy) معطّل: تحصل الأوامر على وصول مباشر وغير مقيّد. ويتم تجاهل قواعد النطاقات لديك.
- الشبكة مفعّلة والوكيل مفعّل: تمر حركة المرور عبر وكيل شبكة Codex، الذي يفرض قواعد النطاقات الخاصة بملف التعريف.
الحالة الثانية هي الفخ. فتعيين permissions.<name>.network.enabled = true لا يشغّل الوكيل. تحتاج أيضًا إلى ما يلي في المستوى الأعلى:
[features]
network_proxy = true
تدعم أنماط النطاقات المضيفات الدقيقة (api.example.com)، و*.example.com للنطاقات الفرعية فقط، و**.example.com للنطاق الجذر مع النطاقات الفرعية، و* كنمط عام للسماح فقط. إدخالات deny تتغلب على إدخالات allow، والوكيل النشط بدون إدخالات allow يحجب كل شيء خارجي.
عند تفعيل الوكيل، فإنه يحجب أيضًا أهداف الشبكة المحلية والخاصة افتراضيًا. للوصول إلى خدمة محلية، أضف المضيف الحرفي إلى قائمة السماح، مثل "localhost" = "allow" أو "127.0.0.1" = "allow".
ملف تعريف أذونات Codex للعمل على API
إليك ملف التعريف الذي اختبرناه لتطوير API. يعدّل الكود داخل مساحة العمل، ولا يقرأ أبدًا ملفات .env أو مجلد secrets، ولا يمكنه الوصول إلا إلى مضيف API الخاص بك وApidog:
default_permissions = "api-work"
[features]
network_proxy = true
[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"
[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"
[permissions.api-work.network]
enabled = true
[permissions.api-work.network.domains]
"api.your-company.com" = "allow" # the API under test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow" # Apidog CLI and its API
استبدل المضيفين بمضيفات الاختبار الفعلية لديك. يرسل Apidog CLI طلبات الاختبار من جهازك إلى API المختبر، لذا يجب أن يكون ذلك المضيف على قائمة السماح، وليس Apidog فقط. وإذا كنت تختبر خادمًا محليًا، فأضف "localhost" = "allow".
ثبّت الحزم قبل الجلسة، وليس خلالها. فتشغيل npm install -g apidog-cli@latest يحتاج إلى registry.npmjs.org، الذي يحجبه ملف التعريف هذا عمدًا.
عقبة واجهناها أثناء الاختبار: على جهاز Mac يشغّل تطبيق وكيل أو VPN في وضع DNS الوهمي (fake-IP DNS)، كان كل مضيف مسموح به يُحلّ إلى عنوان 198.18.x.x. فتعاملت حماية الشبكة المحلية/الخاصة معها على أنها خاصة وحجبتها، وأبلغ Codex عن الخطأ "local/private network addresses are blocked by the sandbox policy." أدت إضافة allow_local_binding = true تحت [permissions.api-work.network] إلى إصلاح المشكلة، لكنها تفتح أيضًا أسماء مضيفات مسموح بها تُحلّ إلى عناوين خاصة، لذا لا تضبطها إلا عند الحاجة.
اختبر ملف التعريف باستخدام codex sandbox
لا تثق بملف تعريف حتى تشاهده يحجب شيئًا فعليًا. يأمر codex sandbox بتشغيل أي أمر ضمن ملف تعريف مُسمّى، ويعامل دليل العمل الحالي كجذر لمساحة العمل:
codex sandbox --permission-profile api-work -- cat README.md .env
مع ملف التعريف أعلاه، طبع تشغيلنا ملف README ثم:
cat: .env: Operation not permitted
فشلت الكتابة خارج مساحة العمل بالطريقة نفسها (Operation not permitted)، بينما أُنشئ ملف جديد داخل مساحة العمل. أما بالنسبة للشبكة، فتحقق من أن الوكيل يحجب مضيفًا لم تُدرجه:
codex sandbox -P api-work -- curl -sI https://example.org
أجاب الوكيل بـ403 Forbidden مع x-proxy-error: blocked-by-allowlist، بينما أعاد apidog.com الرمز 200. على macOS، أضف --log-denials لطباعة رفض Seatbelt بعد خروج الأمر.
يمكنك أيضًا استخدام codex sandbox لتغليف عمليات لا يضعها Codex في صندوق رمل من تلقاء نفسه. تشير مقالة OpenAI إلى أن خوادم MCP من نوع stdio في config.toml تعمل دون صندوق رمل، وتعرض ملف تعريف memory-mcp يحتوي على "~/mcp-data" = "write" وnetwork.enabled = false يغلّف أمر npx الخاص بالخادم.
بدّل ملفات التعريف أثناء الجلسة باستخدام /permissions
في Codex CLI، اكتب /permissions لفتح المنتقي. وعند وجود ملفات تعريف مُسمّاة، يعرضها مع أوصافها. لاختيار أحدها مباشرةً:
/permissions api-work --approval-policy=on-request --reviewer=user
هذا يضبط ملف التعريف للجلسة الحالية ويرسل طلبات الموافقة إليك. ملفات التعريف والموافقات أدوات تحكم منفصلة: يحدد ملف التعريف ما يمكن للأمر المعزول في صندوق الرمل لمسه، بينما تحدد سياسة الموافقة متى يسأل Codex قبل الخروج عنه. تسرد مرجع أوامر CLI أوامر الجلسة الأخرى.
دع Codex يختبر API الخاص بك باستخدام Apidog CLI
مع تفعيل api-work، يمكن لـ Codex تشغيل اختبارات API حقيقية دون إنترنت مفتوح. يمنح Apidog CLI وكيلك أوامر للنقاط الطرفية وحالات الاختبار وعمليات التشغيل، مع مخرجات JSON يمكنه قراءتها. عليك إعداده مرة واحدة خارج صندوق الرمل:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
ثم أعطِ Codex أمرًا واحدًا:
Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.
يقرأ Codex مخطط الحمولة (payload schema)، ويتحقق من صحة JSON الخاص به، ويشغّل الحالة:
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json
في اختبارنا، عمل كل من apidog auth status وapidog project list داخل صندوق الرمل api-work مع السماح بـ**.apidog.com فقط. يبقى رمزك المميز في ~/.apidog، الذي يستطيع ملف التعريف قراءته دون تعديله. للحصول على شرح كامل، راجع كيفية استخدام Apidog CLI في Codex، واستبدل -r cli,json بـ-r junit عندما ينتقل التشغيل نفسه إلى خط أنابيب CI. تغطي خطة Apidog المجانية ما يصل إلى 4 مستخدمين.

حدود يجب معرفتها قبل الوثوق بملف تعريف
تقلّص ملفات تعريف الأذونات نطاق التأثير. لكنها لا تجعل الوكيل آمنًا بمفرده. تسرد الوثائق ومقالة OpenAI هذه الحدود:
- تبقى عمليات القراءة الواسعة مفعّلة مع
:workspace. تحتاج المترجمات (compilers) إلى SDKs وملفات تهيئة خارج المستودع، لذا قد يبقى ملف تهيئة في مكان آخر يحتوي على مفاتيح API قابلًا للقراءة. امنع~/.sshوالمسارات المشابهة صراحةً، أو استخدم":root" = "deny"مع":minimal" = "read". - أنماط deny المحجوبة عبر glob هي لقطة لحظية. على Linux وWSL وWindows، تُوسّع المطابقات عند بدء كل عملية داخل صندوق الرمل. لذا يمكن لصدفة طويلة الأمد أو خادم تطوير قراءة ملف
.envأُنشئ لاحقًا. - قد تتسرّب أحرف البدل عبر DNS. يحلّ الوكيل اسم المضيف فقط بعد السماح به، لكن قواعد أحرف البدل الواسعة أو الوصول إلى خدمات DNS يمكن أن تسمح بتسريب البيانات عبر DNS.
- يغطي الوكيل الأوامر المعزولة في صندوق الرمل فقط. يستخدم البحث على الويب والموصلات (connectors) وخوادم MCP والمتصفح وحركة مرور النموذج الخاصة بـ Codex أدوات تحكم منفصلة.
- يمكن أن تتجاوز الكتابات الجلسة. مثال OpenAI هو
node_modules/prettierمعدّل يشتغّله محررك لاحقًا عند الحفظ، خارج صندوق الرمل.
إذا كنت قد استخدمت حلولًا بديلة لتجاوز صندوق رمل Codex، فإن ملف تعريف مخصصًا ضيقًا هو عادةً الحل الأنظف. أما الفرق التي تحتاج إلى سياسة على مستوى الأجهزة فعليها قراءة كتاب أمان Codex وإعداد allowed_permission_profiles المُدار.
الأسئلة الشائعة
ما ملف تعريف أذونات Codex الافتراضي؟
لا يوجد ملف تعريف افتراضي يُعتمد عليه. تنص الوثائق على ضبط default_permissions صراحةً لسلوك متوقع. لمعظم أعمال البرمجة، يكون :workspace هو الأساس المنطقي: الكتابة داخل جذور مساحة العمل والمجلدات المؤقتة، والشبكة معطّلة.
لماذا تُتجاهل قواعد النطاقات الخاصة بي؟
عادةً لأن features.network_proxy مفقود. مع network.enabled = true وبدون وكيل، تحصل الأوامر على وصول شبكة مباشر وغير مقيّد. تحقّق أيضًا من عدم وجود ملف تهيئة محمّل يضبط sandbox_mode، لأنه يعطّل ملفات التعريف بالكامل.
كيف أوقف Codex من قراءة ملفات .env؟
أضف "**/*.env" = "deny" تحت [permissions.<name>.filesystem.":workspace_roots"]. على Linux وWSL وWindows، اضبط glob_scan_max_depth لأنماط ** غير المحدودة، وتذكّر أن المطابقات الجديدة لا تُضاف إلى العمليات التي تعمل بالفعل.
هل يمكنني السماح بـ localhost في ملف تعريف أذونات Codex؟
نعم. أضف المضيف الحرفي إلى قائمة السماح، مثل "localhost" = "allow" أو "127.0.0.1" = "allow". واضبط allow_local_binding = true فقط عندما يُحلّ اسم مضيف مسموح به إلى عنوان محلي أو خاص.
هل تضع ملفات تعريف الأذونات خوادم MCP في صندوق رمل؟
لا. تبدأ خوادم MCP من نوع stdio في config.toml دون صندوق رمل. غلّف أمر الخادم بـcodex sandbox --permission-profile <name> -- مع ملف تعريف خاص به.
هل يمكنني استخدام ملفات التعريف مع خيار --sandbox؟
لا. تمرير --sandbox أو ضبط sandbox_mode يجعل Codex يستخدم إعدادات صندوق الرمل القديمة بدلًا من default_permissions. اختر نظامًا واحدًا لكل جلسة.
