مرجع هارنس 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 مدیریت‌شده در پوشه خانگی کاربر است. ردیف‌های محلی ذخیره‌شده یا بیکار می‌توانند یک گفت‌وگوی قفل‌شده به مدل با تاریخچه محدود کاربر و دستیار تا آخرین نوبت منبع پایانیِ ماندگارشده ایجاد کنند. اتصال خصوصی آن، fork تصویر لحظه‌ای، شاخه منبع متعارف appServer، تزریق تاریخچه و نوبت‌های بعدی را روی همان اتصال نگه می‌دارد. نخستین شروع متعارف از جفت بازگردانده‌شده توسط fork استفاده می‌کند. در ادامه، ازسرگیری‌ها بازنویسی‌های مدل و ارائه‌دهنده 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.145.0) اجرا می‌کند:

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" استفاده می‌کند؛ هارنس معمولی با homeScope: "agent" روی stdio مدیریت‌شده باقی می‌ماند. تنظیمات صریح اتصال در هر دو مسیر رعایت می‌شوند. وقتی هارنس معمولی باید $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,          },        },      },    },  },}

Codex انتقال WebSocket را آزمایشی و پشتیبانی‌نشده طبقه‌بندی می‌کند. برای بارهای کاری تولیدی، stdio مدیریت‌شده یا سوکت کنترل محلی Unix را ترجیح دهید.

فیلدهای appServer:

appServer.networkProxy صریح است، زیرا قرارداد سندباکس 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",            },          },        },      },    },  },};

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

Plugin دست‌دهی‌های سرور برنامه قدیمی‌تر، جدیدترِ اعتبارسنجی‌نشده، پیش‌انتشار، دارای پسوند ساخت یا بدون نسخه را مسدود می‌کند. سرور برنامه Codex باید نسخه‌ای پایدار از 0.143.0 تا 0.145.0 همراه را گزارش کند.

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

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

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

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

اجرای بومی در سندباکس

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

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

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

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

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

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

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

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

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

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

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

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

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

OpenClaw برای راه‌اندازی‌های عادی سرور برنامه محلی، 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 یا Pluginهای مفیدی از CLI مربوط به Codex در یک خانه 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 فقط روی فرایند فرزند سرور برنامه Codex ایجادشده اثر می‌گذارد. OpenClaw هنگام عادی‌سازی راه‌اندازی محلی، CODEX_HOME و HOME را از این فهرست حذف می‌کند: CODEX_HOME همچنان به دامنه عامل یا کاربر انتخاب‌شده اشاره می‌کند و HOME همچنان به ارث می‌رسد تا زیرفرایندها بتوانند از وضعیت عادی خانه کاربر استفاده کنند.

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

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

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

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

بیشتر ابزارهای یکپارچه‌سازی باقی‌مانده 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 در دسترس می‌ماند. پاسخ‌های منبعی که فقط از ابزار پیام استفاده می‌کنند نیز مستقیم باقی می‌مانند، زیرا این یک قرارداد کنترل نوبت است.

حالت کد Codex نتایج عمومی ابزارهای پویای OpenClaw را به‌شکل متن ارائه می‌کند. پیش از خواندن فیلدها، نتیجه JSON را تجزیه کنید. فراخوانی‌های پویای تو‌در‌تو توسط زمان‌اجرای Codex به‌صورت ترتیبی اجرا می‌شوند، بنابراین Promise.all آن‌ها را هم‌زمان ارسال نمی‌کند؛ هنگام راه‌اندازی فرزندان گردآورنده، از یک حلقه راه‌اندازی ترتیبی و محدود استفاده کنید.

ابزارهایی که با 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.mediaModels.image.timeoutMs.
• برای image_generate بدون مهلت زمانی پیکربندی‌شده، پیش‌فرض 120 ثانیه‌ای تولید تصویر.
• برای ابزار درک رسانه image، مقدار timeoutSeconds از ورودی انتخاب‌شده و تصویرپذیر tools.media.models[] پس از تبدیل به میلی‌ثانیه، یا پیش‌فرض 60 ثانیه‌ای رسانه. برای درک تصویر، این مقدار بر خود درخواست اعمال می‌شود و به‌دلیل کارهای آماده‌سازی پیشین کاهش نمی‌یابد.
• برای ابزار message، یک بودجه بیرونی ثابت 600 ثانیه‌ای که تحویل Gateway و تطبیق محدود با کلید یکسان را پوشش می‌دهد.
• پیش‌فرض 90 ثانیه‌ای ابزار پویا.

این دیده‌بان، بودجه بیرونی item/tool/call پویا است. مهلت‌های زمانی درخواست مختص ارائه‌دهنده درون آن فراخوانی اجرا می‌شوند و معناشناسی مهلت زمانی خود را حفظ می‌کنند. بودجه ابزارهای پویا حداکثر 600000 ms است. agents_wait مقدار 30000 ms مهلت تکمیل بیرونی اضافه می‌کند و کلاینت app-server مقدار 660000 ms را مجاز می‌داند تا نتیجه ساختاریافته انتظار بتواند به Codex برسد. هنگام پایان مهلت، 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
• مرجع پیکربندی