مرجع هارنس 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: {          sessionCatalog: {            enabled: false,          },        },      },    },  },}

supervision ابزارهای در دسترس عامل را جداگانه کنترل می‌کند:

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

صفحه نشست‌های Codex از App Server نظارتی Plugin استفاده می‌کند و فقط نشست‌های بایگانی‌نشده را نمایش می‌دهد. بدون تنظیمات صریح اتصال appServer، آن اتصال به‌صورت stdio مدیریت‌شده در پوشه خانگی کاربر است. ردیف‌های محلی ذخیره‌شده یا بیکار می‌توانند یک Chat قفل‌شده به مدل با تاریخچه محدود کاربر و دستیار تا آخرین نوبت منبع نهایی ذخیره‌شده ایجاد کنند. اتصال خصوصی آن، انشعاب snapshot، شاخه منبع متعارف appServer، تزریق تاریخچه و نوبت‌های بعدی را روی همان اتصال نگه می‌دارد. نخستین شروع متعارف از جفت بازگردانده‌شده توسط انشعاب استفاده می‌کند. در ادامه، ازسرگیری‌ها جایگزینی‌های مدل و ارائه‌دهنده OpenClaw را حذف می‌کنند تا Codex جفت ذخیره‌شده رشته متعارف را بازیابی کند؛ یک تغییر بومی جداگانه می‌تواند آن جفت را به‌روزرسانی کند، اما مدل بیرونی و زنجیره جایگزین هرگز جای آن را نمی‌گیرند. ردیف‌های ذخیره‌شده و بیکار پس از تأیید نبود اجراکننده دیگر می‌توانند بایگانی شوند، مگر اینکه اتصال فعال دیگری در OpenClaw مالک دقیق همان هدف یا یکی از نوادگان ایجادشده بایگانی‌نشده آن باشد. OpenClaw صفحه‌بندی نوادگان Codex را دنبال می‌کند و در صورت خطاهای شمارش، چرخه‌ها یا پایان‌یافتن حد ایمنی، به‌صورت بسته شکست می‌خورد. تأیید همچنان کلاینت‌های بومی ناشناخته و رقابت میان وضعیت و بایگانی را پوشش می‌دهد. یک Chat قفل‌شده به مدل تحت نظارت، تا زمانی که از اتصال بومی محافظت می‌کند، قابل حذف نیست. منابع فعال نمی‌توانند شاخه ایجاد کنند یا بایگانی شوند، اما همچنان می‌توان یک Chat تحت نظارت موجود را باز کرد. همه ردیف‌های 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.3):

codex app-server --listen stdio://

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

تحویل فایل اجرایی و حصارگذاری پیکربندی بومی، کلاینت‌ها را درون یک فرایند در حال اجرای Gateway هماهنگ می‌کنند. پس از اینکه فرایند دیگری پیکربندی بومی Plugin کدکس را تغییر داد، 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 به‌جای آن از دسترسی به سیستم فایل به‌سبک workspace برای پروفایل مجوز تولیدشده استفاده می‌کند. اعمال محدودیت شبکه به‌دست Codex نوعی شبکه‌سازی sandbox‌شده است؛ بنابراین یک پروفایل با دسترسی کامل از ترافیک خروجی محافظت نمی‌کند.

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

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

حالت‌های تأیید و sandbox

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

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

برای تأییدهای 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 استفاده کنند.

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

اجرای بومی در sandbox

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

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

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

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

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

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

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

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

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

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

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

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

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

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

در محدوده پیش‌فرض عامل، Pluginهای OpenClaw و snapshotهای Skills در OpenClaw همچنان از registry مربوط به Plugin و loader مربوط به Skills خود OpenClaw عبور می‌کنند؛ دارایی‌های شخصی ~/.codex در Codex چنین نیستند. اگر Skills یا Pluginهای مفیدی از Codex CLI در یک home مربوط به 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 همچنان به ارث می‌رسد تا زیرفرایندها بتوانند از state عادی home کاربر استفاده کنند.

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

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

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

وقتی یک فهرست مجاز محدود در زمان اجرا، Code Mode بومی را غیرفعال کند، OpenClaw یک انتخاب خالی برای محیط اجرا ارسال می‌کند. در آن حالت مستقیم و بدون sandbox، OpenClaw ابزارهای exec و process پالایش‌شده بر اساس خط‌مشی خود را به‌عنوان گزینه جایگزین shell حفظ می‌کند. فهرست‌های مجاز زمان اجرا و codexDynamicToolsExclude همچنان اعمال می‌شوند.

بیشتر ابزارهای یکپارچه‌سازی باقی‌مانده OpenClaw، مانند پیام‌رسانی، رسانه، cron، مرورگر، نودها، 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 این ابزارها را در رشته‌های معمولی و رشته‌های مختص حالت کد به‌شکل DirectModelOnly عرضه می‌کند، نه اینکه آن‌ها را از طریق فراخوانی‌های تودرتوی tools.* در حالت کد مسیریابی کند. این مرز برای نتایج دارای تصویر ضروری است: سریال‌سازی تودرتو در حالت کد، خروجی تصویر را به متن مسطح تبدیل می‌کند و در نتیجه اسکرین‌شات موردنیاز برای اقدام بعدی رایانه از بین می‌رود.

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

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

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

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

این ناظر، بودجه بیرونی item/tool/call پویا است. مهلت‌های زمانی درخواست مختص ارائه‌دهنده درون آن فراخوانی اجرا می‌شوند و معناشناسی مهلت زمانی خود را حفظ می‌کنند. بودجه ابزارهای پویا حداکثر 600000 ms است. در صورت پایان مهلت، 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 در کانال توضیحات و پیشرفت خام استدلال یا دستیار پیش از ابزار ممکن است با یک پاسخ نهایی خودکار دنبال شوند؛ بنابراین به‌جای آزادسازی فوری مسیر نشست، از نگهبان پاسخ پس از پیشرفت استفاده می‌کنند. فقط آیتم‌های تکمیل‌شده agentMessage نهایی/غیرتوضیحی و تکمیل‌های خام دستیار پیش از ابزار، آزادسازی خروجی دستیار را فعال می‌کنند: اگر Codex سپس بدون turn/completed بی‌صدا شود، OpenClaw به‌صورت بهترین‌تلاش نوبت بومی را قطع و مسیر نشست را آزاد می‌کند. خطاهای app-server مبتنی بر stdio که بازپخش آن‌ها ایمن است، از جمله مهلت‌های بیکاری تکمیل نوبت بدون شواهد دستیار، ابزار، آیتم فعال یا اثر جانبی، یک‌بار با تلاش تازه app-server تکرار می‌شوند. مهلت‌های زمانی ناامن همچنان کلاینت app-server گیرکرده را از رده خارج کرده و مسیر نشست OpenClaw را آزاد می‌کنند. همچنین به‌جای بازپخش خودکار، پیوند منقضی‌شده رشته بومی را پاک می‌کنند. مهلت‌های زمانی پایش تکمیل، متن مهلت زمانی مختص Codex را نمایش می‌دهند: موارد ایمن برای بازپخش اعلام می‌کنند که ممکن است پاسخ ناقص باشد، درحالی‌که موارد ناامن از کاربر می‌خواهند پیش از تلاش مجدد وضعیت فعلی را بررسی کند. تشخیص‌های عمومی مهلت زمانی شامل فیلدهای ساختاری مانند آخرین متد اعلان app-server، شناسه/نوع/نقش آیتم پاسخ خام دستیار، تعداد درخواست‌ها/آیتم‌های فعال و وضعیت ناظر فعال‌شده هستند. هنگامی که آخرین اعلان یک آیتم پاسخ خام دستیار باشد، یک پیش‌نمایش محدود از متن دستیار را نیز شامل می‌شوند. آن‌ها محتوای خام پرامپت یا ابزار را شامل نمی‌شوند.

کشف مدل

به‌طور پیش‌فرض، Plugin مربوط به Codex از app-server درباره مدل‌های موجود پرس‌وجو می‌کند. مالکیت دسترس‌پذیری مدل با app-server مربوط به Codex است؛ بنابراین ممکن است هنگامی که 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
• مرجع پیکربندی