Codex harness
زمان اجرای هارنس Codex
این صفحه قرارداد زمان اجرای نوبتهای مهار Codex را مستند میکند. برای راهاندازی و مسیریابی، از مهار Codex شروع کنید. برای فیلدهای پیکربندی، مرجع مهار Codex را ببینید.
نمای کلی
حالت Codex صرفا OpenClaw با یک فراخوانی مدل متفاوت در زیر آن نیست. Codex بخش بیشتری از حلقه مدل بومی را در اختیار دارد، و OpenClaw سطحهای Plugin، ابزار، نشست، و تشخیص خود را پیرامون آن مرز تطبیق میدهد.
OpenClaw همچنان مالک مسیریابی کانال، فایلهای نشست، تحویل پیام قابل مشاهده، ابزارهای پویای OpenClaw، تأییدها، تحویل رسانه، و آینه رونوشت است. Codex مالک رشته بومی مرجع، حلقه مدل بومی، ادامه ابزار بومی، و Compaction بومی است.
مسیریابی پرامپت از زمان اجرای انتخابشده پیروی میکند، نه فقط رشته ارائهدهنده. یک نوبت بومی Codex دستورالعملهای توسعهدهنده app-server متعلق به Codex را دریافت میکند، در حالی که یک مسیر سازگاری صریح OpenClaw، حتی وقتی از احراز هویت یا انتقال OpenAI با طعم Codex استفاده میکند، پرامپت سیستمی معمول OpenClaw را نگه میدارد.
Codex بومی دستورالعملهای پایه/مدل و رفتار مستندات پروژه متعلق به Codex را
طبق پیکربندی رشته فعال Codex نگه میدارد. OpenClaw رشتههای بومی
Codex را با شخصیت داخلی Codex غیرفعالشده شروع و از سر میگیرد تا فایلهای شخصیت
فضای کاری و هویت عامل OpenClaw مرجع بمانند. اجراهای سبک
OpenClaw همچنان سرکوب مستندات پروژه موجود خود را حفظ میکنند. دستورالعملهای
توسعهدهنده OpenClaw نگرانیهای زمان اجرای OpenClaw مانند تحویل کانال مبدأ،
ابزارهای پویای OpenClaw، واگذاری ACP، زمینه آداپتور، و
فایلهای پروفایل فضای کاری عامل فعال را پوشش میدهند. کاتالوگهای Skills در OpenClaw و اشارهگرهای
MEMORY.md مسیریابیشده با ابزار، بهعنوان دستورالعملهای توسعهدهنده همکاری محدود به نوبت
برای Codex بومی نگاشت میشوند. محتوای فعال BOOTSTRAP.md و تزریق جایگزین کامل
MEMORY.md همچنان از زمینه ارجاع ورودی نوبت استفاده میکنند.
اتصال رشتهها و تغییرات مدل
وقتی یک نشست OpenClaw به یک رشته موجود Codex متصل میشود، نوبت بعدی
مدل OpenAI، سیاست تأیید، سندباکس، و سطح سرویس فعلا انتخابشده را دوباره به app-server میفرستد. تغییر از openai/gpt-5.5 به
openai/gpt-5.2 اتصال رشته را نگه میدارد اما از Codex میخواهد با
مدل تازه انتخابشده ادامه دهد.
پاسخهای قابل مشاهده و Heartbeatها
وقتی یک نوبت گفتوگوی مستقیم/مبدأ از طریق مهار Codex اجرا میشود، پاسخهای قابل مشاهده
بهصورت پیشفرض برای سطحهای داخلی WebChat به تحویل خودکار دستیار نهایی تنظیم میشوند.
این کار Codex را با قرارداد پرامپت مهار Pi همسو نگه میدارد: عاملها بهطور
عادی پاسخ میدهند، و OpenClaw متن نهایی را در گفتوگوی مبدأ ارسال میکند. وقتی یک گفتوگوی مستقیم/مبدأ باید
عمدا متن نهایی دستیار را خصوصی نگه دارد مگر اینکه عامل
message(action="send") را فراخوانی کند، messages.visibleReplies: "message_tool" را تنظیم کنید.
نوبتهای Heartbeat در Codex نیز بهصورت پیشفرض heartbeat_respond را در کاتالوگ ابزار
قابل جستوجوی OpenClaw دریافت میکنند، تا عامل بتواند ثبت کند که بیدارسازی باید
بیصدا بماند یا بدون رمزگذاری آن جریان کنترل در متن نهایی، اعلان بدهد.
راهنمای ابتکار مخصوص Heartbeat بهعنوان دستورالعمل توسعهدهنده حالت همکاری Codex
در خود نوبت Heartbeat ارسال میشود. نوبتهای معمول گفتوگو بهجای حمل فلسفه Heartbeat در پرامپت
زمان اجرای عادی خود، حالت Default Codex را بازیابی میکنند. وقتی یک HEARTBEAT.md غیرخالی وجود داشته باشد، دستورالعملهای
حالت همکاری Heartbeat بهجای درج محتوای فایل، Codex را به آن فایل ارجاع میدهند.
مرزهای هوک
مهار Codex سه لایه هوک دارد:
| لایه | مالک | هدف |
|---|---|---|
| هوکهای Plugin در OpenClaw | OpenClaw | سازگاری محصول/Plugin در مهارهای OpenClaw و Codex. |
| میانافزار افزونه app-server در Codex | Pluginهای بستهبندیشده OpenClaw | رفتار آداپتور در هر نوبت پیرامون ابزارهای پویای OpenClaw. |
| هوکهای بومی Codex | Codex | چرخه عمر سطح پایین Codex و سیاست ابزار بومی از پیکربندی Codex. |
OpenClaw از فایلهای پروژه یا سراسری hooks.json در Codex برای مسیریابی
رفتار Plugin در OpenClaw استفاده نمیکند. برای ابزار بومی و پل مجوز پشتیبانیشده،
OpenClaw پیکربندی Codex در سطح هر رشته را برای PreToolUse، PostToolUse،
PermissionRequest، و Stop تزریق میکند.
وقتی تأییدهای app-server در Codex فعال باشند، یعنی approvalPolicy برابر
"never" نباشد، پیکربندی هوک بومی تزریقشده پیشفرض PermissionRequest را حذف میکند تا
بازبین app-server در Codex و پل تأیید OpenClaw، ارتقاهای واقعی را پس از بازبینی
مدیریت کنند. اپراتورها میتوانند وقتی به رله سازگاری نیاز دارند، صراحتا permission_request را به
nativeHookRelay.events اضافه کنند.
هوکهای دیگر Codex مانند SessionStart و UserPromptSubmit همچنان
کنترلهای سطح Codex باقی میمانند. آنها در قرارداد v1 بهعنوان هوکهای Plugin در OpenClaw
ارائه نمیشوند.
برای ابزارهای پویای OpenClaw، OpenClaw پس از اینکه Codex درخواست فراخوانی را میدهد ابزار را اجرا میکند، بنابراین OpenClaw رفتار Plugin و میانافزاری را که مالک آن است در آداپتور مهار اجرا میکند. برای ابزارهای بومی Codex، Codex مالک رکورد ابزار مرجع است. OpenClaw میتواند رویدادهای منتخب را آینه کند، اما نمیتواند رشته بومی Codex را بازنویسی کند مگر اینکه Codex آن عملیات را از طریق app-server یا callbacks هوک بومی ارائه کند.
رویدادهای PreToolUse در حالت گزارش app-server در Codex درخواستهای تأیید Plugin را
به تأیید app-server متناظر واگذار میکنند. اگر یک هوک before_tool_call در OpenClaw
requireApproval برگرداند در حالی که payload بومی حالت تأیید گزارش را تنظیم کرده باشد
(openclaw_approval_mode برابر "report" است)، رله هوک بومی نیاز تأیید
Plugin را ثبت میکند و هیچ تصمیم بومی برنمیگرداند. وقتی Codex درخواست تأیید
app-server را برای همان استفاده از ابزار میفرستد، OpenClaw پرامپت تأیید
Plugin را باز میکند و تصمیم را به Codex نگاشت میکند. رویدادهای PermissionRequest
در Codex یک مسیر تأیید جداگانه هستند و وقتی زمان اجرا برای آن پل پیکربندی شده باشد،
همچنان میتوانند از طریق تأییدهای OpenClaw مسیریابی شوند.
اعلانهای مورد app-server در Codex همچنین مشاهدههای ناهمگام after_tool_call
را برای تکمیلهای ابزار بومی فراهم میکنند که از قبل توسط رله بومی
PostToolUse پوشش داده نشدهاند. این مشاهدهها فقط برای تلهمتری و سازگاری
Plugin هستند؛ نمیتوانند فراخوانی ابزار بومی را مسدود، با تأخیر، یا جهش دهند.
نگاشتهای Compaction و چرخه عمر LLM از اعلانهای app-server در Codex
و وضعیت آداپتور OpenClaw میآیند، نه از فرمانهای هوک بومی Codex.
رویدادهای before_compaction، after_compaction، llm_input، و
llm_output در OpenClaw مشاهدههای سطح آداپتور هستند، نه ضبط بایتبهبایت
درخواست داخلی یا payloadهای Compaction در Codex.
اعلانهای app-server بومی hook/started و hook/completed در Codex
بهعنوان رویدادهای عامل codex_app_server.hook برای مسیر اجرا و اشکالزدایی
نگاشت میشوند. آنها هوکهای Plugin در OpenClaw را فراخوانی نمیکنند.
قرارداد پشتیبانی V1
پشتیبانیشده در زمان اجرای Codex v1:
| سطح | پشتیبانی | دلیل |
|---|---|---|
| حلقه مدل OpenAI از طریق Codex | پشتیبانی میشود | app-server در Codex مالک نوبت OpenAI، ازسرگیری رشته بومی، و ادامه ابزار بومی است. |
| مسیریابی و تحویل کانال OpenClaw | پشتیبانی میشود | Telegram، Discord، Slack، WhatsApp، iMessage و کانالهای دیگر بیرون از زماناجرای مدل میمانند. |
| ابزارهای پویای OpenClaw | پشتیبانی میشود | Codex از OpenClaw میخواهد این ابزارها را اجرا کند، بنابراین OpenClaw در مسیر اجرا باقی میماند. |
| Pluginهای پرامپت و زمینه | پشتیبانی میشود | OpenClaw پرامپت/زمینه ویژه OpenClaw را به نوبت Codex نگاشت میکند، درحالیکه پرامپتهای پایه، مدل، و مستندات پروژه پیکربندیشده که مالکیتشان با Codex است در مسیر بومی Codex میمانند. OpenClaw شخصیت داخلی Codex را برای رشتههای بومی غیرفعال میکند تا فایلهای شخصیت فضای کاری عامل همچنان مرجع معتبر باشند. دستورالعملهای توسعهدهنده بومی Codex فقط راهنمایی فرمانی را میپذیرند که صراحتا به codex_app_server محدود شده باشد؛ راهنماییهای فرمان سراسری قدیمی برای سطوح پرامپت غیر Codex باقی میمانند. |
| چرخه عمر موتور زمینه | پشتیبانی میشود | مونتاژ، دریافت، و نگهداری پس از نوبت پیرامون نوبتهای Codex اجرا میشوند. موتورهای زمینه جایگزین Compaction بومی Codex نمیشوند. |
| هوکهای ابزار پویا | پشتیبانی میشود | میانافزارهای before_tool_call، after_tool_call و نتیجه ابزار پیرامون ابزارهای پویایی اجرا میشوند که مالکیتشان با OpenClaw است. |
| هوکهای چرخه عمر | بهصورت مشاهدههای آداپتور پشتیبانی میشود | llm_input، llm_output، agent_end، before_compaction و after_compaction با بارهای داده صادقانه حالت Codex اجرا میشوند. |
| دروازه بازبینی پاسخ نهایی | از طریق رله هوک بومی پشتیبانی میشود | Stop در Codex به before_agent_finalize رله میشود؛ revise از Codex میخواهد پیش از نهاییسازی یک گذر مدل دیگر انجام دهد. |
| مسدودسازی یا مشاهده شل، پچ، و MCP بومی | از طریق رله هوک بومی پشتیبانی میشود | PreToolUse و PostToolUse در Codex برای سطوح ابزار بومی ثبتشده رله میشوند، از جمله بارهای داده MCP روی app-server در Codex نسخه 0.125.0 یا جدیدتر. مسدودسازی پشتیبانی میشود؛ بازنویسی آرگومان پشتیبانی نمیشود. |
| سیاست مجوز بومی | از طریق تاییدهای app-server در Codex و رله هوک بومی سازگاری پشتیبانی میشود | درخواستهای تایید app-server در Codex پس از بازبینی Codex از مسیر OpenClaw عبور میکنند. رله هوک بومی PermissionRequest برای حالتهای تایید بومی اختیاری است، چون Codex آن را پیش از بازبینی محافظ صادر میکند. |
| ثبت مسیر app-server | پشتیبانی میشود | OpenClaw درخواستی را که به app-server فرستاده و اعلانهای app-server را که دریافت میکند ثبت میکند. |
در زماناجرای Codex نسخه ۱ پشتیبانی نمیشود:
| سطح | مرز V1 | مسیر آینده |
|---|---|---|
| جهش آرگومان ابزار بومی | هوکهای پیشاابزار بومی Codex میتوانند مسدود کنند، اما OpenClaw آرگومانهای ابزار بومی Codex را بازنویسی نمیکند. | به پشتیبانی هوک/اسکیمای Codex برای جایگزینی ورودی ابزار نیاز دارد. |
| تاریخچه رونوشت بومی قابل ویرایش Codex | Codex مالک تاریخچه متعارف رشته بومی است. OpenClaw مالک یک آینه است و میتواند زمینه آینده را نگاشت کند، اما نباید درونمایههای پشتیبانینشده را جهش دهد. | اگر جراحی رشته بومی لازم باشد، APIهای صریح app-server در Codex اضافه شود. |
tool_result_persist برای رکوردهای ابزار بومی Codex |
آن هوک نوشتنهای رونوشت تحت مالکیت OpenClaw را تبدیل میکند، نه رکوردهای ابزار بومی Codex را. | میتوان رکوردهای تبدیلشده را آینه کرد، اما بازنویسی متعارف به پشتیبانی Codex نیاز دارد. |
| فراداده غنی Compaction بومی | OpenClaw میتواند Compaction بومی را درخواست کند، اما فهرست پایدار نگهداشتهشده/حذفشده، دلتای توکن، خلاصه تکمیل، یا بار داده خلاصه دریافت نمیکند. | به رویدادهای غنیتر Compaction در Codex نیاز دارد. |
| مداخله در Compaction | OpenClaw به Pluginها یا موتورهای زمینه اجازه نمیدهد Compaction بومی Codex را وتو، بازنویسی، یا جایگزین کنند. | اگر Pluginها نیاز به وتو یا بازنویسی Compaction بومی داشته باشند، هوکهای پیشا/پسای Compaction در Codex اضافه شود. |
| ثبت درخواست API مدل بهصورت بایتبهبایت | OpenClaw میتواند درخواستها و اعلانهای app-server را ثبت کند، اما هسته Codex درخواست نهایی API در OpenAI را بهصورت داخلی میسازد. | به یک رویداد رهگیری درخواست مدل در Codex یا API اشکالزدایی نیاز دارد. |
مجوزهای بومی و درخواستهای MCP
برای PermissionRequest، OpenClaw فقط زمانی تصمیمهای صریح اجازه یا رد را برمیگرداند
که سیاست تصمیم بگیرد. نتیجه بدون تصمیم اجازه محسوب نمیشود. Codex آن را بهعنوان نبود
تصمیم هوک در نظر میگیرد و به مسیر محافظ یا تایید کاربر خودش میافتد.
حالتهای تایید app-server در Codex بهطور پیشفرض این هوک بومی را حذف میکنند. این رفتار
زمانی اعمال میشود که permission_request صراحتا در
nativeHookRelay.events گنجانده شود یا یک زماناجرای سازگاری آن را نصب کند.
وقتی یک اپراتور برای درخواست مجوز بومی Codex گزینه allow-always را انتخاب میکند،
OpenClaw اثرانگشت دقیق آن ورودی ارائهدهنده/نشست/ابزار/cwd را برای یک
پنجره نشست محدود به خاطر میسپارد. تصمیم بهخاطرمانده عمدا فقط با تطابق دقیق
کار میکند: فرمان، آرگومانها، بار داده ابزار، یا cwd تغییرکرده یک
تایید تازه ایجاد میکند.
درخواستهای تایید ابزار MCP در Codex وقتی Codex مقدار _meta.codex_approval_kind را
"mcp_tool_call" علامتگذاری کند، از مسیر جریان تایید Plugin در OpenClaw عبور داده میشوند.
پرامپتهای request_user_input در Codex به چت مبدأ فرستاده میشوند،
و پیام پیگیری بعدی در صف بهجای هدایتشدن بهعنوان زمینه اضافی، به همان
درخواست سرور بومی پاسخ میدهد. دیگر درخواستهای MCP بهصورت بسته شکست میخورند.
برای جریان عمومی تایید Plugin که این پرامپتها را حمل میکند، ببینید درخواستهای مجوز Plugin.
هدایت صف
هدایت صف اجرای فعال به turn/steer در app-server در Codex نگاشت میشود. با
messages.queue.mode: "steer" پیشفرض، OpenClaw پیامهای چت حالت هدایت را
برای پنجره سکوت پیکربندیشده دستهبندی میکند و آنها را بهترتیب ورود، بهعنوان یک درخواست
turn/steer ارسال میکند.
نوبتهای بازبینی Codex و Compaction دستی میتوانند هدایت در همان نوبت را رد کنند. در این
حالت، OpenClaw پیش از شروع پرامپت منتظر میماند اجرای فعال تمام شود.
وقتی پیامها باید بهطور پیشفرض بهجای هدایت، در صف قرار بگیرند، از
/queue followup یا /queue collect استفاده کنید. صف هدایت را ببینید.
بارگذاری بازخورد Codex
وقتی /diagnostics [note] برای یک نشست با استفاده از harness بومی Codex
تأیید میشود، OpenClaw همچنین برای رشتههای مرتبط Codex، feedback/upload را در
app-server متعلق به Codex فراخوانی میکند. این بارگذاری از app-server میخواهد
در صورت موجود بودن، لاگهای هر رشته فهرستشده و زیررشتههای ایجادشده Codex را
درج کند.
بارگذاری از مسیر عادی بازخورد Codex به سرورهای OpenAI عبور میکند. اگر بازخورد Codex
در آن app-server غیرفعال باشد، فرمان خطای app-server را برمیگرداند. پاسخ کاملشده
عیبیابی، کانالها، شناسههای نشست OpenClaw، شناسههای رشته Codex، و فرمانهای محلی
codex resume <thread-id> را برای رشتههایی که ارسال شدهاند فهرست میکند.
اگر تأیید را رد یا نادیده بگیرید، OpenClaw آن شناسههای Codex را چاپ نمیکند و بازخورد Codex را ارسال نمیکند. این بارگذاری جایگزین خروجی عیبیابی محلی Gateway نمیشود. برای رفتار مربوط به تأیید، حریم خصوصی، بسته محلی، و گفتوگوی گروهی، خروجی عیبیابی را ببینید.
فقط زمانی از /codex diagnostics [note] استفاده کنید که مشخصاً بارگذاری بازخورد Codex
را برای رشتهای که در حال حاضر متصل است، بدون بسته کامل عیبیابی Gateway میخواهید.
Compaction و آینه رونوشت
وقتی مدل انتخابشده از harness مربوط به Codex استفاده میکند، Compaction بومی رشته
متعلق به app-server متعلق به Codex است. OpenClaw برای نوبتهای Codex، Compaction
پیشپرواز را اجرا نمیکند، Compaction متعلق به Codex را با Compaction موتور زمینه
جایگزین نمیکند، و وقتی Compaction بومی Codex نمیتواند شروع شود، به خلاصهسازی
OpenClaw یا OpenAI عمومی بازنمیگردد. OpenClaw برای تاریخچه کانال، جستوجو،
/new، /reset، و تعویض مدل یا harness در آینده، یک آینه رونوشت نگه میدارد.
درخواستهای صریح Compaction، مانند /compact یا عملیات compact دستی درخواستشده توسط
Plugin، Compaction بومی Codex را با thread/compact/start شروع میکنند.
OpenClaw درخواست و اجاره کلاینت مشترک را باز نگه میدارد تا Codex آیتم تکمیل
contextCompaction مطابق را منتشر کند و سپس نوبت Compaction را کاملشده گزارش میکند.
اگر آن نوبت پایانی از مهلت configured Compaction فراتر برود، OpenClaw یک وقفه نوبت
بومی درخواست میکند. اجاره و حصار Compaction مختص هر رشته تا زمانی نگه داشته میشوند
که Codex وضعیت پایانی را گزارش کند یا RPC وقفه را تأیید کند.
اگر Codex در بازه مهلت وقفه تأیید نکند، OpenClaw پیش از آزاد کردن حصار، اتصال را
بازنشسته میکند. اتصالهای راهدور همچنین اتصال رشته مطابق را جدا میکنند تا کارهای
بعدی نتوانند با یک نوبت راهدور تأییدنشده همپوشانی داشته باشند. سایر نوبتها روی
یک اتصال بازنشسته شکست میخورند و میتوانند روی یک کلاینت تازه دوباره تلاش شوند.
بستن کلاینت، لغو درخواست، یا شکست نوبت Compaction یک عملیات شکستخورده برمیگرداند.
وقتی یک موتور زمینه درخواست projection راهاندازی رشته Codex میکند، OpenClaw نامها و شناسههای فراخوانی ابزار، شکلهای ورودی، و محتوای redactشده نتیجه ابزار را در رشته تازه Codex project میکند. مقادیر خام آرگومانهای فراخوانی ابزار را در آن projection کپی نمیکند.
این آینه شامل پرامپت کاربر، متن نهایی دستیار، و رکوردهای سبک reasoning یا plan مربوط به Codex است، وقتی app-server آنها را منتشر کند. OpenClaw شروع Compaction بومی و وضعیت پایانی را ثبت میکند، اما خلاصهای خواندنی برای انسان از Compaction یا فهرستی قابل حسابرسی از اینکه Codex پس از Compaction کدام ورودیها را نگه داشته است ارائه نمیکند.
از آنجا که Codex مالک رشته بومی canonical است، tool_result_persist در حال حاضر
رکوردهای نتیجه ابزار بومی Codex را بازنویسی نمیکند. این فقط زمانی اعمال میشود که
OpenClaw در حال نوشتن نتیجه ابزار در رونوشت نشست متعلق به OpenClaw باشد.
رسانه و تحویل
OpenClaw همچنان مالک تحویل رسانه و انتخاب ارائهدهنده رسانه است. تصویر، ویدئو،
موسیقی، PDF، TTS، و درک رسانه از تنظیمات ارائهدهنده/مدل مطابق مانند
agents.defaults.imageGenerationModel، videoGenerationModel،
pdfModel، و messages.tts استفاده میکنند.
متن، تصاویر، ویدئو، موسیقی، TTS، تأییدها، و خروجی ابزار پیامرسانی همچنان از مسیر
عادی تحویل OpenClaw عبور میکنند. تولید رسانه به runtime قدیمی نیاز ندارد.
وقتی Codex یک آیتم تولید تصویر بومی با savedPath منتشر میکند، OpenClaw همان فایل
دقیق را از مسیر عادی پاسخرسانه ارسال میکند، حتی اگر نوبت Codex هیچ متن دستیار
نداشته باشد.
