مرجع چارچوب Codex

این مرجع پیکربندی تفصیلی Plugin رسمی codex را پوشش می‌دهد. برای راه‌اندازی و تصمیم‌گیری‌های مسیریابی، از مهار Codex شروع کنید.

سطح پیکربندی Plugin

تمام تنظیمات مهار Codex زیر plugins.entries.codex.config قرار دارند.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },          appServer: {            mode: "guardian",          },        },      },    },  },}

فیلدهای سطح بالا:

نظارت

نظارت، نشست‌های بایگانی‌نشده Codex را از رایانه Gateway و Nodeهای جفت‌شده‌ای که به‌صورت اختیاری فعال شده‌اند فهرست می‌کند. آن را مستقل از مهار عامل فعال کنید:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          supervision: {            enabled: true,          },        },      },    },  },}

فیلدهای supervision:

ورودی‌های نقطه پایانی این فیلدها را می‌پذیرند:

صفحه نشست‌های Codex از App Server نظارت Plugin استفاده می‌کند و فقط نشست‌های بایگانی‌نشده را نشان می‌دهد. بدون تنظیمات صریح اتصال appServer، این اتصال stdio مدیریت‌شده در خانه کاربر است. ردیف‌های محلی ذخیره‌شده یا بیکار می‌توانند یک گفت‌وگوی قفل‌شده به مدل با تاریخچه محدود کاربر و دستیار تا آخرین نوبت منبع نهاییِ ماندگارشده ایجاد کنند. اتصال خصوصی آن، انشعاب فوری، شاخه متعارف منبع appServer، تزریق تاریخچه و نوبت‌های بعدی را روی همان اتصال نگه می‌دارد. نخستین شروع متعارف از جفت بازگردانده‌شده توسط انشعاب استفاده می‌کند. ازسرگیری‌های بعدی جایگزینی‌های مدل و ارائه‌دهنده OpenClaw را حذف می‌کنند تا Codex جفت ماندگارشده رشته متعارف را بازیابی کند؛ یک تغییر بومی جداگانه می‌تواند آن جفت را به‌روزرسانی کند، اما مدل بیرونی و زنجیره جایگزین هرگز آن را جایگزین نمی‌کنند. ردیف‌های ذخیره‌شده و بیکار را می‌توان پس از تأیید نبود اجراکننده دیگر بایگانی کرد، مگر اینکه اتصال فعال دیگری در OpenClaw مالک همان هدف دقیق یا یکی از فرزندان ایجادشده بایگانی‌نشده آن باشد. OpenClaw صفحه‌بندی فرزندان Codex را دنبال می‌کند و در صورت خطای شمارش، چرخه یا تمام‌شدن حد ایمنی، به‌صورت بسته شکست می‌خورد. تأیید همچنان کلاینت‌های بومی ناشناخته و رقابت میان وضعیت و بایگانی را پوشش می‌دهد. گفت‌وگوی قفل‌شده به مدل تحت نظارت، تا زمانی که از اتصال بومی محافظت می‌کند، قابل حذف نیست. منابع فعال نمی‌توانند شاخه ایجاد کنند یا بایگانی شوند، اما همچنان می‌توان یک گفت‌وگوی تحت نظارت موجود را باز کرد. همه ردیف‌های Node جفت‌شده فقط‌خواندنی باقی می‌مانند؛ انتقال Node هنوز چرخه عمر جریانی موردنیاز مهار را فراهم نمی‌کند.

appServer.homeScope: "user" به‌تنهایی فقط تعیین می‌کند فرایند مهار مدیریت‌شده از کدام خانه Codex استفاده کند؛ این گزینه فهرست ناوگان را منتشر نمی‌کند. فعال‌کردن نظارت، پیش‌فرض مهار را تغییر نمی‌دهد. در عوض، وقتی هیچ تنظیم صریح اتصال appServer وجود ندارد، اتصال جداگانه نظارت به‌طور پیش‌فرض از stdio مدیریت‌شده در خانه کاربر استفاده می‌کند. تنظیمات صریح برای آن اتصال رعایت می‌شوند. اتصال‌های تحت نظارتِ در انتظار و ثبت‌شده، آن اتصال را برای هر نوبت حفظ می‌کنند؛ غیرفعال‌بودن نظارت یا انحراف اتصال یا چرخه عمر، به‌جای بازگشت به مهار خانه عامل، به‌صورت بسته شکست می‌خورد. اتصال پیش‌فرض، نشست‌های ذخیره‌شده را با کلاینت‌های بومی Codex به اشتراک می‌گذارد، نه وضعیت فعالیت محلیِ فرایند آن‌ها را.

تنظیمات قدیمی plugins.entries.codex-supervisor بازنشسته شده‌اند. برای مهاجرت ورودی قدیمی، تعریف‌های نقطه پایانی، پرچم‌های خط‌مشی و ارجاع‌های مجاز/غیرمجاز Plugin به این بلوک، openclaw doctor --fix را اجرا کنید. در تعارض‌ها، مقادیر متعارف صریح codex.config.supervision اولویت دارند.

انتقال app-server

برای نوبت‌های عادی مهار، OpenClaw باینری مدیریت‌شده Codex را که همراه Plugin رسمی عرضه می‌شود اجرا می‌کند (در حال حاضر @openai/codex 0.144.1):

codex app-server --listen stdio://

این کار نسخه app-server را به Plugin رسمی codex وابسته نگه می‌دارد، نه به هر Codex CLI جداگانه‌ای که اتفاقاً به‌صورت محلی نصب شده باشد. تنها زمانی appServer.command را تنظیم کنید که عمداً اجرایی متفاوتی می‌خواهید. نوبت‌های مدیریت‌شده عادی با خانه عامل ایزوله پیش‌فرض، حتی در صورت نصب بسته برنامه رومیزی macOS، این بسته سنجاق‌شده را ترجیح می‌دهند. وقتی استفاده از رایانه فعال باشد، یا وقتی homeScope برابر "user" باشد و بتواند وضعیت بومی استفاده از رایانه را بارگیری کند، راه‌اندازی مدیریت‌شده در عوض باینری برنامه رومیزی دارای مجوزهای لازم macOS را ترجیح می‌دهد. همین قاعده اولویت‌دادن به برنامه رومیزی زمانی اعمال می‌شود که پیکربندی مؤثر Codex در خانه عامل ایزوله، استفاده بومی از رایانه را فعال کند. اگر هیچ بسته برنامه رومیزی نصب نشده باشد، OpenClaw به باینری بسته سنجاق‌شده بازمی‌گردد.

تحویل فایل اجرایی و محصورسازی پیکربندی بومی، کلاینت‌ها را درون یک فرایند Gateway در حال اجرا هماهنگ می‌کنند. پس از تغییر پیکربندی Plugin بومی Codex توسط فرایندی دیگر، Gateway را مجدداً راه‌اندازی کنید.

نظارت، یک اتصال جداگانه را تفکیک می‌کند. بدون تنظیمات صریح اتصال appServer، از stdio مدیریت‌شده با homeScope: "user" استفاده می‌کند؛ مهار عادی همچنان stdio مدیریت‌شده با homeScope: "agent" باقی می‌ماند. تنظیمات صریح اتصال در هر دو مسیر رعایت می‌شوند. وقتی مهار عادی باید $CODEX_HOME (یا ~/.codex) را با کلاینت‌های بومی به اشتراک بگذارد، homeScope: "user" را صریحاً تنظیم کنید. یک اتصال خصوصی تحت نظارت، صرف‌نظر از پیش‌فرض مهار عادی، از اتصال نظارت استفاده می‌کند. فرایندهای مستقل App Server وضعیت زنده و وضعیت تأیید جداگانه‌ای را حفظ می‌کنند.

برای app-serverی که از قبل در حال اجرا است، از انتقال WebSocket استفاده کنید:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",            requestTimeoutMs: 60000,          },        },      },    },  },}

فیلدهای appServer:

appServer.networkProxy صریح است، زیرا قرارداد sandbox در Codex را تغییر می‌دهد. هنگام فعال بودن، OpenClaw همچنین features.network_proxy.enabled و default_permissions را در پیکربندی رشته Codex تنظیم می‌کند تا نمایه مجوز تولیدشده بتواند شبکه‌سازی مدیریت‌شده توسط Codex را آغاز کند. OpenClaw به‌طور پیش‌فرض یک نام نمایه مقاوم در برابر تداخل به‌شکل openclaw-network-<fingerprint> را از بدنه نمایه تولید می‌کند؛ فقط زمانی از profileName استفاده کنید که یک نام محلی پایدار لازم باشد.

export default {  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },};

اگر محیط اجرای معمول app-server برابر با danger-full-access باشد، فعال‌کردن networkProxy به‌جای آن، برای نمایهٔ مجوزِ تولیدشده از دسترسی به سیستم فایل به سبک فضای کاری استفاده می‌کند. اعمال محدودیت شبکه که Codex مدیریت می‌کند، شبکه‌ای سندباکس‌شده است؛ بنابراین نمایهٔ دسترسی کامل از ترافیک خروجی محافظت نمی‌کند.

Plugin دست‌دهی‌های قدیمی یا بدون نسخهٔ app-server را مسدود می‌کند: app-server متعلق به Codex باید نسخهٔ پایدار 0.143.0 یا جدیدتر را گزارش کند.

OpenClaw نشانی‌های WebSocket مربوط به app-server را که local loopback نیستند، راه‌دور در نظر می‌گیرد و احراز هویت WebSocket حامل هویت را از طریق appServer.authToken یا سرآیند Authorization الزامی می‌کند. appServer.authToken و هر مقدار appServer.headers.* می‌توانند SecretInput باشند؛ محیط اجرای اسرار، SecretRefها و نگارش کوتاه متغیرهای محیطی را پیش از آن‌که OpenClaw گزینه‌های شروع app-server را بسازد تفکیک می‌کند، و SecretRefهای ساخت‌یافتهٔ تفکیک‌نشده پیش از ارسال هرگونه توکن یا سرآیند با خطا مواجه می‌شوند. هنگامی که Pluginهای بومی Codex پیکربندی شده باشند، OpenClaw از صفحهٔ کنترل Plugin در app-server متصل‌شده برای نصب یا نوسازی آن Pluginها استفاده می‌کند و سپس موجودی برنامه‌ها را نوسازی می‌کند تا برنامه‌های متعلق به Plugin برای رشتهٔ Codex قابل مشاهده باشند. app/list همچنان منبع معتبر موجودی و فراداده است، اما سیاست OpenClaw تعیین می‌کند که آیا thread/start برای یک برنامهٔ فهرست‌شده و قابل دسترس، حتی اگر Codex در حال حاضر آن را غیرفعال علامت‌گذاری کرده باشد، مقدار config.apps[appId].enabled = true را ارسال کند یا نه. شناسه‌های ناشناخته یا مفقود برنامه همچنان به‌صورت بسته و امن شکست می‌خورند؛ این مسیر فقط Pluginهای بازار را از طریق plugin/install فعال می‌کند و موجودی را نوسازی می‌کند. OpenClaw را فقط به app-serverهای راه‌دوری متصل کنید که برای پذیرش نصب Pluginهای مدیریت‌شده توسط OpenClaw و نوسازی موجودی برنامه‌ها مورد اعتماد هستند.

حالت‌های تأیید و سندباکس

نشست‌های محلی app-server مبتنی بر stdio به‌طور پیش‌فرض از حالت YOLO استفاده می‌کنند: approvalPolicy: "never"، approvalsReviewer: "user" و sandbox: "danger-full-access". این وضعیتِ مورد اعتماد برای گردانندهٔ محلی به نوبت‌های بدون‌نظارت OpenClaw و Heartbeatها اجازه می‌دهد بدون اعلان‌های تأیید بومی که کسی برای پاسخ‌گویی به آن‌ها حضور ندارد، پیشرفت کنند.

اگر فایل الزامات سامانهٔ محلی Codex مقادیر ضمنی تأیید، بازبین یا سندباکس YOLO را مجاز نداند، OpenClaw در عوض مقدار پیش‌فرض ضمنی را guardian در نظر می‌گیرد و مجوزهای مجاز guardian را انتخاب می‌کند. tools.exec.mode: "auto" نیز تأییدهای Codex با بازبینی guardian را اجباری می‌کند و بازنویسی‌های قدیمی و ناامن approvalPolicy: "never" یا sandbox: "danger-full-access" را حفظ نمی‌کند؛ برای وضعیت عمدیِ بدون تأیید، tools.exec.mode: "full" را تنظیم کنید. ورودی‌های [[remote_sandbox_config]] منطبق با نام میزبان در همان فایل الزامات، در تصمیم‌گیری دربارهٔ مقدار پیش‌فرض سندباکس رعایت می‌شوند.

برای تأییدهای Codex با بازبینی guardian، مقدار appServer.mode: "guardian" را تنظیم کنید:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            mode: "guardian",            serviceTier: "priority",          },        },      },    },  },}

پیش‌تنظیم guardian، در صورت مجازبودن این مقادیر، به approvalPolicy: "on-request"، approvalsReviewer: "auto_review" و sandbox: "workspace-write" گسترش می‌یابد. فیلدهای منفرد سیاست بر mode اولویت دارند. مقدار قدیمی‌تر guardian_subagent برای بازبین همچنان به‌عنوان نام مستعار سازگاری پذیرفته می‌شود، اما پیکربندی‌های جدید باید از auto_review استفاده کنند.

هنگامی که سندباکس OpenClaw فعال است، فرایند محلی app-server متعلق به Codex همچنان روی میزبان Gateway اجرا می‌شود. بنابراین OpenClaw به‌جای آن‌که سندباکس‌سازی سمت میزبان Codex را معادل با پشتیبان سندباکس OpenClaw بداند، برای آن نوبت Code Mode بومی Codex، سرورهای MCP کاربر و اجرای Plugin مبتنی بر برنامه را غیرفعال می‌کند. هنگامی که ابزارهای معمول exec/process در دسترس باشند، دسترسی پوسته از طریق ابزارهای پویای متکی به سندباکس OpenClaw مانند sandbox_exec و sandbox_process ارائه می‌شود.

اجرای بومی سندباکس‌شده

مقدار پیش‌فرض پایدار، شکست بسته و امن است: سندباکس‌سازی فعال OpenClaw سطوح اجرای بومی Codex را که در غیر این صورت از میزبان app-server متعلق به Codex اجرا می‌شدند، غیرفعال می‌کند. تنها هنگامی از appServer.experimental.sandboxExecServer: true استفاده کنید که می‌خواهید پشتیبانی محیط راه‌دور Codex را با پشتیبان سندباکس OpenClaw امتحان کنید. این مسیر پیش‌نمایش با تمام نسخه‌های پشتیبانی‌شدهٔ app-server متعلق به Codex کار می‌کند.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            experimental: {              sandboxExecServer: true,            },          },        },      },    },  },}

وقتی این پرچم روشن باشد و نشست جاری OpenClaw سندباکس‌شده باشد، OpenClaw یک exec-server مبتنی بر local loopback و متکی به سندباکس فعال راه‌اندازی می‌کند، آن را در app-server متعلق به Codex ثبت می‌کند و رشته و نوبت Codex را با آن محیط متعلق به OpenClaw آغاز می‌کند. اگر app-server نتواند محیط را ثبت کند، اجرا به‌جای بازگشت بی‌سروصدا به اجرای میزبان، به‌صورت بسته و امن شکست می‌خورد.

این مسیر پیش‌نمایش فقط محلی است. app-server راه‌دور مبتنی بر WebSocket، مگر آن‌که روی همان میزبان اجرا شود، نمی‌تواند به exec-server مبتنی بر local loopback دسترسی پیدا کند؛ بنابراین OpenClaw این ترکیب را رد می‌کند.

احراز هویت و جداسازی محیط

در خانهٔ پیش‌فرض مختص هر عامل، احراز هویت با ترتیب زیر انتخاب می‌شود:

1. یک نمایهٔ صریح احراز هویت Codex در OpenClaw برای عامل.
2. حساب موجود app-server در خانهٔ Codex همان عامل.
3. فقط برای راه‌اندازی‌های محلی app-server مبتنی بر stdio، ابتدا CODEX_API_KEY و سپس OPENAI_API_KEY، هنگامی که هیچ حساب app-server موجود نیست و احراز هویت OpenAI همچنان الزامی است.

هنگامی که OpenClaw یک نمایهٔ احراز هویت Codex به سبک اشتراک ChatGPT مشاهده می‌کند (از نوع اعتبارنامهٔ OAuth یا توکن)، CODEX_API_KEY و OPENAI_API_KEY را از فرایند فرزند Codex که ایجاد می‌شود حذف می‌کند. این کار کلیدهای API در سطح Gateway را برای تعبیه‌ها یا مدل‌های مستقیم OpenAI در دسترس نگه می‌دارد، بدون آن‌که نوبت‌های بومی app-server متعلق به Codex به‌طور تصادفی از طریق API صورتحساب شوند.

نمایه‌های صریح کلید API مربوط به Codex و راه‌حل جایگزین کلید محیطی در stdio محلی، به‌جای محیط به‌ارث‌رسیدهٔ فرایند فرزند از ورود app-server استفاده می‌کنند. اتصال‌های app-server مبتنی بر WebSocket راه‌حل جایگزین کلید API محیطی Gateway را دریافت نمی‌کنند؛ از یک نمایهٔ صریح احراز هویت یا حساب خود app-server راه‌دور استفاده کنید.

راه‌اندازی‌های app-server مبتنی بر stdio به‌طور پیش‌فرض محیط فرایند OpenClaw را به ارث می‌برند. OpenClaw مالک پل حساب app-server متعلق به Codex است و CODEX_HOME را روی یک پوشهٔ مختص هر عامل در وضعیت OpenClaw همان عامل تنظیم می‌کند. این کار پیکربندی، حساب‌ها، حافظهٔ نهان/داده‌های Plugin و وضعیت رشتهٔ Codex را به عامل OpenClaw محدود می‌کند، به‌جای آن‌که از خانهٔ شخصی ~/.codex گرداننده به آن نشت کنند.

برای اشتراک‌گذاری وضعیت بومی Codex با Codex Desktop و CLI، مقدار appServer.homeScope: "user" را تنظیم کنید. این حالت خانهٔ کاربر محلی از stdio مدیریت‌شده و انتقال صریح Unix پشتیبانی می‌کند. در صورت تنظیم‌بودن $CODEX_HOME از آن استفاده می‌کند و در غیر این صورت از ~/.codex بهره می‌گیرد؛ این شامل احراز هویت بومی، پیکربندی، Pluginها و رشته‌ها است. OpenClaw برای app-server از پل نمایهٔ احراز هویت خود صرف‌نظر می‌کند. نوبت‌های تأییدشدهٔ مالک می‌توانند از codex_threads برای فهرست‌کردن (با فیلتر اختیاری search)، خواندن، انشعاب‌گرفتن، تغییر نام، بایگانی و خارج‌کردن آن رشته‌ها از بایگانی استفاده کنند. پیش از ادامه‌دادن یک رشته در OpenClaw از آن انشعاب بگیرید؛ فرایندهای مستقل Codex نویسندگان هم‌زمان یک رشته را هماهنگ نمی‌کنند.

این انتخاب اختیاری homeScope بر نشست‌های معمول مهار اعمال می‌شود. یک Chat ایجادشده از طریق Codex Sessions در عوض از اتصال نظارت خصوصی خود استفاده می‌کند که پیکربندی احراز هویت و ارائه‌دهندهٔ اتصال بومی را برای شاخهٔ معیار و ازسرگیری‌های آینده حفظ می‌کند.

در یک Chat نظارت‌شده و قفل‌شده به مدل، codex_threads نمی‌تواند انشعاب دیگری را پیوست کند یا رشتهٔ بومی متصل به Chat را بایگانی کند. فهرست و خواندن صرفاً فراداده‌ای همچنان در دسترس هستند. خواندن خام رونوشت‌ها به allowRawTranscripts نیاز دارد؛ هنگامی که غیرفعال باشد، جست‌وجوی فهرست نیز رد می‌شود، زیرا جست‌وجوی بومی می‌تواند با پیش‌نمایش رونوشت‌ها تطبیق پیدا کند. تغییر نام، خارج‌کردن از بایگانی، انشعاب جداشده و بایگانی یک رشتهٔ نامرتبط که متعلق به Chat دیگری در OpenClaw نیست، به allowWriteControls نیاز دارند. هیچ‌کدام از این گزینه‌ها اتصال قفل‌شده را دور نمی‌زنند.

OpenClaw برای راه‌اندازی‌های معمول app-server محلی، HOME را بازنویسی نمی‌کند. زیرفرایندهایی که Codex اجرا می‌کند، مانند openclaw، gh، git، CLIهای ابری و فرمان‌های پوسته، خانهٔ معمول فرایند را می‌بینند و می‌توانند پیکربندی و توکن‌های خانهٔ کاربر را پیدا کنند. Codex همچنین ممکن است $HOME/.agents/skills و $HOME/.agents/plugins/marketplace.json را کشف کند؛ این کشف .agents عمداً با خانهٔ گرداننده مشترک است و از وضعیت جداسازی‌شدهٔ ~/.codex مستقل است.

در محدودهٔ پیش‌فرض عامل، Pluginهای OpenClaw و عکس‌های فوری Skills در OpenClaw همچنان از طریق رجیستری Plugin و بارگذار Skills خود OpenClaw جریان می‌یابند؛ دارایی‌های شخصی Codex در ~/.codex چنین نیستند. اگر Skills مربوط به Codex CLI یا Pluginهای مفیدی در یک خانهٔ Codex دارید که باید بخشی از یک عامل جداسازی‌شدهٔ OpenClaw شوند، آن‌ها را صریحاً فهرست‌برداری کنید:

openclaw migrate codex --dry-runopenclaw migrate apply codex --yes

اگر یک استقرار به جداسازی محیطی بیشتری نیاز دارد، آن متغیرها را به appServer.clearEnv اضافه کنید:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv فقط بر فرایند فرزند app-server متعلق به Codex که ایجاد می‌شود اثر می‌گذارد. OpenClaw هنگام عادی‌سازی راه‌اندازی محلی، CODEX_HOME و HOME را از این فهرست حذف می‌کند: CODEX_HOME همچنان به محدودهٔ انتخاب‌شدهٔ عامل یا کاربر اشاره می‌کند و HOME به‌صورت به‌ارث‌رسیده باقی می‌ماند تا زیرفرایندها بتوانند از وضعیت معمول خانهٔ کاربر استفاده کنند.

ابزارهای پویا

بارگذاری پیش‌فرض ابزارهای پویای Codex به‌صورت searchable است و با deferLoading: true در فضای نام openclaw ارائه می‌شود. OpenClaw ابزارهای پویایی را که عملیات بومی فضای کاری Codex یا سطح جست‌وجوی ابزار خود Codex را تکرار می‌کنند، ارائه نمی‌دهد:

• read
• write
• edit
• apply_patch
• exec
• process
• update_plan
• tool_call
• tool_describe
• tool_search
• tool_search_code

بیشتر ابزارهای یکپارچه‌سازی باقی‌ماندهٔ OpenClaw، مانند پیام‌رسانی، رسانه، cron، مرورگر، Nodeها، Gateway، heartbeat_respond و web_search، از طریق جست‌وجوی ابزار Codex در آن فضای نام در دسترس هستند. این کار زمینهٔ اولیهٔ مدل را کوچک‌تر نگه می‌دارد. مجموعهٔ کوچکی از ابزارها صرف‌نظر از codexDynamicToolsLoading مستقیماً قابل فراخوانی باقی می‌مانند، زیرا ممکن است جست‌وجوی ابزار Codex در دسترس نباشد یا فقط مجموعه‌ای محدود به اتصال‌دهنده‌ها را تفکیک کند: agents_list، sessions_spawn و sessions_yield. دستورالعمل‌های توسعه‌دهنده همچنان زیرعامل‌های معمول Codex را برای کار زیرعامل بومی Codex به سمت spawn_agent هدایت می‌کنند، درحالی‌که sessions_spawn برای واگذاری صریح OpenClaw یا ACP در دسترس می‌ماند. پاسخ‌های منبعی که فقط از ابزار پیام استفاده می‌کنند نیز مستقیم باقی می‌مانند، زیرا این یک قرارداد کنترل نوبت است.

ابزارهایی که با catalogMode: "direct-only" علامت‌گذاری شده‌اند، از جمله ابزار computer متعلق به OpenClaw، در openclaw_direct گروه‌بندی می‌شوند. OpenClaw آن فضای نام را بدون جایگزین‌کردن ورودی‌های ارائه‌شده توسط گرداننده، به فهرست code_mode.direct_only_tool_namespaces در Codex اضافه می‌کند. بنابراین Codex این ابزارها را در رشته‌های معمول و رشته‌های فقط Code Mode به‌صورت DirectModelOnly ارائه می‌کند، به‌جای آن‌که آن‌ها را از طریق فراخوانی‌های تو‌در‌توی tools.* در Code Mode مسیریابی کند. این مرز برای نتایج دارای تصویر الزامی است: سریال‌سازی تو‌در‌توی Code Mode خروجی تصویر را به متن مسطح تبدیل می‌کند و در نتیجه تصویر صفحهٔ مورد نیاز برای کنش بعدی رایانه را از بین می‌برد.

codexDynamicToolsLoading: "direct" را فقط هنگام اتصال به یک app-server سفارشی Codex که نمی‌تواند ابزارهای پویای معوق را جست‌وجو کند، یا هنگام اشکال‌زدایی بار کامل ابزار، تنظیم کنید.

مهلت‌های زمانی

فراخوانی‌های پویای ابزار متعلق به OpenClaw، مستقل از appServer.requestTimeoutMs محدود می‌شوند. هر درخواست Codex از نوع item/tool/call، نخستین مهلت زمانی موجود را با ترتیب زیر به‌کار می‌برد:

• آرگومان مثبت timeoutMs برای هر فراخوانی.
• برای image_generate، مقدار agents.defaults.imageGenerationModel.timeoutMs.
• برای image_generate بدون مهلت زمانی پیکربندی‌شده، پیش‌فرض ۱۲۰ثانیه‌ای تولید تصویر.
• برای ابزار image مربوط به درک رسانه، مقدار tools.media.image.timeoutSeconds که به میلی‌ثانیه تبدیل می‌شود، یا پیش‌فرض ۶۰ثانیه‌ای رسانه. برای درک تصویر، این مهلت برای خود درخواست اعمال می‌شود و با کارهای آماده‌سازی پیشین کاهش نمی‌یابد.
• برای ابزار message، پیش‌فرض ثابت ۱۲۰ ثانیه.
• پیش‌فرض ۹۰ثانیه‌ای ابزار پویا.

این پایشگر، بودجه بیرونی فراخوانی پویای item/tool/call است. مهلت‌های زمانی درخواست مختص ارائه‌دهنده درون آن فراخوانی اجرا می‌شوند و معناشناسی مهلت زمانی خود را حفظ می‌کنند. بودجه ابزارهای پویا حداکثر ۶۰۰۰۰۰ میلی‌ثانیه است. هنگام اتمام مهلت، OpenClaw در صورت پشتیبانی سیگنال ابزار را لغو می‌کند و پاسخی ناموفق برای ابزار پویا به Codex بازمی‌گرداند تا نوبت بتواند ادامه یابد و نشست در وضعیت processing باقی نماند.

پس از آنکه Codex یک نوبت را می‌پذیرد، و پس از آنکه OpenClaw به یک درخواست app-server با دامنه همان نوبت پاسخ می‌دهد، سازوکار اجرا انتظار دارد Codex در نوبت جاری پیشرفت کند و در نهایت نوبت بومی را با turn/completed به پایان برساند. اگر app-server برای مدت appServer.turnCompletionIdleTimeoutMs خاموش بماند، OpenClaw در حد توان نوبت Codex را قطع می‌کند، یک مهلت زمانی تشخیصی ثبت می‌کند و مسیر نشست OpenClaw را آزاد می‌سازد تا پیام‌های گفت‌وگوی بعدی پشت یک نوبت بومی منقضی‌شده در صف نمانند.

بیشتر اعلان‌های غیرپایانی همان نوبت، این پایشگر کوتاه را غیرفعال می‌کنند، زیرا Codex ثابت کرده است که نوبت همچنان فعال است. واگذاری‌های ابزار از بودجه بیکاری طولانی‌تری پس از ابزار استفاده می‌کنند: پس از اینکه OpenClaw پاسخ item/tool/call را بازمی‌گرداند، پس از تکمیل آیتم‌های ابزار بومی مانند commandExecution، پس از تکمیل‌های خام custom_tool_call_output، و پس از پیشرفت خام دستیار، تکمیل‌های استدلال یا پیشرفت استدلال بعد از ابزار. نگهبان، در صورت پیکربندی از appServer.postToolRawAssistantCompletionIdleTimeoutMs استفاده می‌کند و در غیر این صورت پیش‌فرض آن پنج دقیقه است. همین بودجه پس از ابزار، پایشگر پیشرفت را نیز برای بازه خاموش ترکیب پاسخ، پیش از آنکه Codex رویداد بعدی نوبت جاری را منتشر کند، تمدید می‌کند. تکمیل‌های استدلال، تکمیل‌های agentMessage از نوع commentary، و پیشرفت خام استدلال یا دستیار پیش از ابزار ممکن است با یک پاسخ نهایی خودکار دنبال شوند؛ بنابراین به‌جای آزادسازی فوری مسیر نشست، از نگهبان پاسخ پس از پیشرفت استفاده می‌کنند. تنها آیتم‌های تکمیل‌شده نهایی/غیر-commentary از نوع agentMessage و تکمیل‌های خام دستیار پیش از ابزار، آزادسازی خروجی دستیار را فعال می‌کنند: اگر Codex سپس بدون turn/completed خاموش بماند، OpenClaw در حد توان نوبت بومی را قطع می‌کند و مسیر نشست را آزاد می‌سازد. خرابی‌های app-server مبتنی بر stdio که بازپخش آن‌ها ایمن است، از جمله اتمام مهلت بیکاری تکمیل نوبت بدون شواهدی از دستیار، ابزار، آیتم فعال یا اثر جانبی، یک بار در تلاش تازه‌ای برای app-server تکرار می‌شوند. مهلت‌های زمانی ناامن همچنان سرویس‌گیرنده گیرکرده app-server را کنار می‌گذارند و مسیر نشست OpenClaw را آزاد می‌کنند. همچنین به‌جای بازپخش خودکار، اتصال منقضی‌شده رشته بومی را پاک می‌کنند. مهلت‌های زمانی پایش تکمیل، متن مهلت زمانی مختص Codex نمایش می‌دهند: مواردی که بازپخش آن‌ها ایمن است می‌گویند ممکن است پاسخ ناقص باشد، در حالی که موارد ناامن از کاربر می‌خواهند پیش از تلاش مجدد، وضعیت فعلی را بررسی کند. تشخیص‌های عمومی مهلت زمانی شامل فیلدهای ساختاری مانند آخرین متد اعلان app-server، شناسه/نوع/نقش آیتم پاسخ خام دستیار، تعداد درخواست‌ها/آیتم‌های فعال و وضعیت پایش فعال‌شده هستند. وقتی آخرین اعلان یک آیتم پاسخ خام دستیار باشد، پیش‌نمایش محدودی از متن دستیار را نیز شامل می‌شوند. این تشخیص‌ها محتوای خام پرامپت یا ابزار را شامل نمی‌شوند.

کشف مدل

به‌طور پیش‌فرض، Plugin مربوط به Codex فهرست مدل‌های موجود را از app-server درخواست می‌کند. مالکیت دسترس‌پذیری مدل بر عهده Codex app-server است؛ بنابراین وقتی OpenClaw نسخه همراه @openai/codex را ارتقا می‌دهد یا یک استقرار، appServer.command را به باینری متفاوتی از Codex هدایت می‌کند، این فهرست ممکن است تغییر کند. دسترس‌پذیری همچنین ممکن است به حساب وابسته باشد. برای مشاهده کاتالوگ زنده آن سازوکار اجرا و حساب، از /codex models روی یک Gateway در حال اجرا استفاده کنید.

اگر کشف ناموفق شود یا مهلت آن پایان یابد، OpenClaw از کاتالوگ جایگزین همراه استفاده می‌کند:

کشف را در plugins.entries.codex.config.discovery تنظیم کنید:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: true,            timeoutMs: 2500,          },        },      },    },  },}

اگر می‌خواهید راه‌اندازی از بررسی Codex خودداری کند و فقط از کاتالوگ جایگزین استفاده شود، کشف را غیرفعال کنید:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          discovery: {            enabled: false,          },        },      },    },  },}

فایل‌های راه‌اندازی اولیه فضای کاری

Codex فایل AGENTS.md را مستقیماً از طریق کشف بومی مستندات پروژه مدیریت می‌کند. OpenClaw فایل‌های مصنوعی مستندات پروژه Codex را نمی‌نویسد و برای فایل‌های شخصیت به نام فایل‌های جایگزین Codex وابسته نیست، زیرا جایگزین‌های Codex فقط وقتی اعمال می‌شوند که AGENTS.md وجود نداشته باشد.

برای همسانی فضای کاری OpenClaw، سازوکار اجرای Codex سایر فایل‌های راه‌اندازی اولیه را به‌عنوان دستورالعمل توسعه‌دهنده منتقل می‌کند، اما نه به‌شکلی یکسان:

• TOOLS.md به‌عنوان دستورالعمل توسعه‌دهنده به‌ارث‌رسیده Codex منتقل می‌شود؛ بنابراین زیرعامل‌های بومی Codex که در طول نوبت ایجاد می‌شوند نیز آن را می‌بینند.
• SOUL.md، IDENTITY.md و USER.md به‌عنوان دستورالعمل‌های همکاری محدود به نوبت منتقل می‌شوند. زیرعامل‌های بومی Codex آن‌ها را به ارث نمی‌برند؛ در نتیجه نوبت‌های زیرعامل، شخصیت و نمایه کاربر عامل والد را دریافت نمی‌کنند.
• فهرست فشرده Skills بارگذاری‌شده OpenClaw نیز به‌عنوان دستورالعمل توسعه‌دهنده همکاری محدود به نوبت منتقل می‌شود؛ بنابراین زیرعامل‌های بومی Codex آن را نیز به ارث نمی‌برند.
• محتوای HEARTBEAT.md تزریق نمی‌شود؛ نوبت‌های Heartbeat یک اشاره‌گر در حالت همکاری دریافت می‌کنند تا در صورت وجود و خالی‌نبودن فایل، آن را بخوانند.
• وقتی ابزارهای حافظه برای فضای کاری پیکربندی‌شده عامل در دسترس باشند، محتوای MEMORY.md از آن فضای کاری در ورودی نوبت بومی Codex جای‌گذاری نمی‌شود؛ در صورت وجود فایل، سازوکار اجرا یک اشاره‌گر کوچک حافظه فضای کاری به دستورالعمل‌های توسعه‌دهنده همکاری محدود به نوبت اضافه می‌کند و Codex باید هرگاه حافظه پایدار مرتبط است از memory_search یا memory_get استفاده کند. اگر ابزارها غیرفعال باشند، جست‌وجوی حافظه در دسترس نباشد، یا فضای کاری فعال با فضای کاری حافظه عامل متفاوت باشد، MEMORY.md به‌جای آن از مسیر عادی و محدود زمینه نوبت استفاده می‌کند.
• BOOTSTRAP.md، در صورت وجود، به‌عنوان زمینه مرجع ورودی نوبت OpenClaw منتقل می‌شود.

بازنویسی‌های محیطی

بازنویسی‌های محیطی برای آزمایش محلی همچنان در دسترس‌اند:

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

وقتی appServer.command تنظیم نشده باشد، OPENCLAW_CODEX_APP_SERVER_BIN باینری مدیریت‌شده را دور می‌زند.

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 حذف شده است. به‌جای آن از plugins.entries.codex.config.appServer.mode: "guardian" یا برای آزمایش محلی یک‌باره از OPENCLAW_CODEX_APP_SERVER_MODE=guardian استفاده کنید. برای استقرارهای تکرارپذیر، پیکربندی ترجیح داده می‌شود، زیرا رفتار Plugin را در همان فایل بررسی‌شده مربوط به سایر تنظیمات سازوکار اجرای Codex نگه می‌دارد.

مرتبط

• سازوکار اجرای Codex
• زمان اجرای سازوکار Codex
• نظارت بر Codex
• Plugin‌های بومی Codex
• کار با رایانه در Codex
• ارائه‌دهنده OpenAI
• مرجع پیکربندی