Pluginهای چارچوب عامل

یک مهار عامل اجراکنندهٔ سطح پایین یک نوبت آماده‌شدهٔ عامل OpenClaw است. این مهار نه ارائه‌دهندهٔ مدل است، نه کانال و نه رجیستری ابزار. برای مدل ذهنی کاربرمحور، به زمان‌های اجرای عامل مراجعه کنید.

این سطح را فقط برای Plugin‌های باندل‌شده یا بومیِ مورداعتماد استفاده کنید. این قرارداد همچنان آزمایشی است، زیرا نوع پارامترها عمداً بازتاب‌دهندهٔ اجراکنندهٔ تعبیه‌شدهٔ فعلی هستند.

چه زمانی از مهار استفاده کنید

هنگامی یک مهار عامل ثبت کنید که یک خانوادهٔ مدل، زمان اجرای نشست بومی خود را دارد و انتقال عادی ارائه‌دهندهٔ OpenClaw انتزاع مناسبی نیست:

• یک سرور بومی عامل کدنویسی که مالک رشته‌ها و Compaction است
• یک CLI یا دیمن محلی که باید رویدادهای بومی طرح/استدلال/ابزار را به‌صورت جریانی ارسال کند
• یک زمان اجرای مدل که علاوه بر رونوشت نشست OpenClaw، به شناسهٔ ادامهٔ اختصاصی خود نیاز دارد

فقط برای افزودن یک API جدید LLM، مهار ثبت نکنید. برای APIهای عادی مدل مبتنی بر HTTP یا WebSocket، یک Plugin ارائه‌دهنده بسازید.

مواردی که همچنان در مالکیت هسته هستند

پیش از انتخاب مهار، OpenClaw موارد زیر را از قبل تعیین کرده است:

• ارائه‌دهنده و مدل
• وضعیت احراز هویت زمان اجرا، مگر آنکه مهار اعلام کند راه‌اندازی اولیهٔ احراز هویت را در اختیار دارد
• سطح تفکر و بودجهٔ زمینه
• فایل رونوشت/نشست OpenClaw
• فضای کاری، محیط ایزوله و سیاست ابزار
• فراخوان‌های بازگشتی پاسخ کانال و فراخوان‌های بازگشتی جریان
• سیاست بازگشت به مدل جایگزین و تعویض زندهٔ مدل

مهار یک تلاش آماده‌شده را اجرا می‌کند؛ ارائه‌دهنده انتخاب نمی‌کند، تحویل کانال را جایگزین نمی‌کند و مدل‌ها را به‌طور پنهانی تغییر نمی‌دهد.

راه‌اندازی اولیهٔ احراز هویت در مالکیت مهار

به‌طور پیش‌فرض، هسته پیش از فراخوانی مهار، اطلاعات اعتبارسنجی ارائه‌دهنده را تعیین می‌کند. یک مهار مورداعتماد که می‌تواند از طریق زمان اجرای بومی خود احراز هویت کند، ممکن است authBootstrap: "harness" را در ثبت ایستای AgentHarness خود تنظیم کند. سپس هسته راه‌اندازی اولیهٔ عمومی اطلاعات اعتبارسنجی ارائه‌دهنده و خطای نبود اطلاعات اعتبارسنجی را برای هر تلاشی که آن مهار در اختیار می‌گیرد، نادیده می‌گیرد.

اگر یک پروفایل احراز هویت سازگار و صراحتاً انتخاب‌شده یا مرتب‌شدهٔ OpenClaw و مخزن محدودشدهٔ آن وجود داشته باشد، هسته همچنان آن‌ها را ارسال می‌کند. مهار باید پیش از ارسال درخواست‌های مدل، آن پروفایل یا اطلاعات اعتبارسنجی بومی خود را تعیین کند، اسرار را به همان تلاش محدود نگه دارد و خطاهای احراز هویت قابل‌اقدام ارائه دهد. این قابلیت را روی مهاری که فقط گاهی مالک احراز هویت است تنظیم نکنید.

مصنوعات تأییدشدهٔ زمان اجرای راه‌اندازی

مهار محلی‌ای که می‌تواند برای راه‌اندازی اجرای نخست استنتاج فراهم کند، باید پیاده‌سازی‌ای را که کاوش را تکمیل کرده است تصدیق کند. هنگامی که params.captureRuntimeArtifact درست است، یک result.runtimeArtifact مبهم با شناسه‌ای پایدار و اثرانگشت محتوا برگردانید. یک قابلیت متناظر runtimeArtifact.validate(...) ثبت کنید که آن پیوند را بدون بارگذاری مهاری دیگر یا پیمایش Plugin‌های نامرتبط دوباره بررسی کند.

ادامه‌های تأییدشدهٔ OpenClaw همچنین params.expectedRuntimeArtifact را ارسال می‌کنند. مهار باید آن را با دقیقاً همان فرایند بومی‌ای که به دست آورده است مقایسه کند و اگر متفاوت بودند، پیش از آغاز یا ادامهٔ یک رشتهٔ بومی شکست بخورد. نوبت‌های عادی عامل هر دو فیلد را حذف می‌کنند تا هش‌کردن محتوا از مسیر داغ درخواست عادی خارج بماند. مهارهای راه‌دور/WebSocket پیش از مشارکت به قرارداد تصدیق سرور نیاز دارند؛ رشتهٔ نسخه به‌تنهایی هویت یک مصنوع نیست.

تلاش آماده‌شده همچنین شامل params.runtimePlan است؛ مجموعه‌سیاستی در مالکیت OpenClaw برای تصمیم‌های زمان اجرا که باید میان OpenClaw و مهارهای بومی مشترک بماند:

• runtimePlan.tools.normalize(...) و runtimePlan.tools.logDiagnostics(...) برای سیاست طرح‌وارهٔ ابزار آگاه از ارائه‌دهنده
• runtimePlan.transcript.resolvePolicy(...) برای پاک‌سازی رونوشت و سیاست ترمیم فراخوانی ابزار
• runtimePlan.delivery.isSilentPayload(...) برای NO_REPLY مشترک و جلوگیری از تحویل رسانه
• runtimePlan.outcome.classifyRunResult(...) برای دسته‌بندی بازگشت به مدل جایگزین
• runtimePlan.observability برای فرادادهٔ تعیین‌شدهٔ ارائه‌دهنده/مدل/مهار

مهارها می‌توانند برای تصمیم‌هایی که باید با رفتار OpenClaw مطابقت داشته باشند از طرح استفاده کنند، اما با آن به‌عنوان وضعیت تلاش در مالکیت میزبان رفتار کنید: آن را تغییر ندهید و از آن برای تعویض ارائه‌دهنده‌ها/مدل‌ها درون یک نوبت استفاده نکنید.

قرارداد انتقال درخواست

supports(ctx) انتقال تعیین‌شدهٔ مدل را در ctx.modelProvider دریافت می‌کند. دو واقعیت بدون اسرار و در مالکیت ارائه‌دهنده، مسیر انتخاب‌شده را توصیف می‌کنند:

• runtimePolicy.compatibleIds شناسه‌های زمان اجرایی را فهرست می‌کند که ارائه‌دهنده آن‌ها را با آن مسیر مشخص سازگار اعلام کرده است. نبود سیاست یعنی ارائه‌دهنده سازگاری در سطح مسیر را اعلام نکرده است؛ این مجوزی برای فرض‌کردن پشتیبانی نیست.
• requestTransportOverrides: "none" یعنی هیچ بازنویسی تألیفی درخواست ارائه‌دهنده/مدل نباید بازتولید شود. "present" یعنی سرآیندهای تألیفی، انتقال احراز هویت، پراکسی، TLS، سرویس محلی، رفتار شبکهٔ خصوصی یا پارامترهای درخواست وجود دارند. این واقعیت آن مقادیر را افشا نمی‌کند.

هنگامی که مهار نمی‌تواند انتقال آماده‌شده را بازتولید کند، { supported: false, reason } را برگردانید. پس از انتخاب، با خواندن پیکربندی خام پشتیبانی را استنباط نکنید. اگر آماده‌سازی احراز هویت چند مسیر تلاش مجدد ایجاد کند، یک مهار باید پیش از ارسال از همهٔ آن‌ها پشتیبانی کند. انتخاب ضمنی، اگر هیچ Plugin‌ای نتواند مالک مجموعهٔ کامل باشد، از OpenClaw استفاده می‌کند؛ انتخاب صریح یا ماندگارشدهٔ Plugin با رویکرد بسته شکست می‌خورد.

ثبت مهار

واردکردن: openclaw/plugin-sdk/agent-harness

  const myHarness: AgentHarness = {  id: "my-harness",  label: "مهار بومی عامل من",   supports(ctx) {    const routeSupportsHarness =      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest      ? { supported: true, priority: 100 }      : { supported: false, reason: "مسیر مؤثر با مهار سازگار نیست" };  },   async runAttempt(params) {    // رشتهٔ بومی خود را آغاز یا ادامه دهید.    // از params.prompt، params.tools، params.images، params.onPartialReply،    // params.onAgentEvent و دیگر فیلدهای تلاش آماده‌شده استفاده کنید.    return await runMyNativeTurn(params);  },}; export default definePluginEntry({  id: "my-native-agent",  name: "عامل بومی من",  description: "مدل‌های انتخاب‌شده را از طریق یک دیمن بومی عامل اجرا می‌کند.",  register(api) {    api.registerAgentHarness(myHarness);  },});

authBootstrap عمداً در این مثال عمومی وجود ندارد. فقط هنگامی authBootstrap: "harness" را اضافه کنید که مهار قرارداد بالا را برآورده کند.

اجرای واگذارشده

مالک مهار ممکن است delegatedExecutionPluginIds را روی شناسه‌های Plugin‌های مورداعتمادی تنظیم کند که باید یک نشست موجود و قفل‌شده به مدل را اجرا کنند؛ مانند انتقال صوتی‌ای که گفت‌وگویی متکی بر Codex را ادامه می‌دهد. این رضایت ایستای مالک است، نه فهرست مجاز هسته. آن را محدود نگه دارید.

واگذارشوندگان فقط پذیرش کار و اجرای تعبیه‌شده را دریافت می‌کنند. OpenClaw کلید دقیق ذخیره‌شدهٔ نشست، مسیر مخزن و شناسهٔ نشست؛ modelSelectionLocked: true؛ و مقادیر منطبق agentHarnessId و agentHarnessRuntimeOverride را الزامی می‌کند. سپس اجرا از طریق مالک مهار محدود می‌شود. ایجاد، وصله‌کردن، بازنشانی، حذف و بایگانی نشست و تغییر Gateway همچنان فقط در اختیار مالک است.

سیاست انتخاب

OpenClaw پس از تعیین ارائه‌دهنده/مدل، یک مهار انتخاب می‌کند:

1. سیاست زمان اجرای محدود به مدل اولویت دارد.
2. سیاست زمان اجرای محدود به ارائه‌دهنده در رتبهٔ بعدی است.
3. auto از مهارهای ثبت‌شده می‌پرسد آیا از مسیر مؤثر تعیین‌شده پشتیبانی می‌کنند. پیشوندهای ارائه‌دهنده/مدل به‌تنهایی هرگز مهاری را انتخاب نمی‌کنند.
4. اگر هیچ مهار ثبت‌شده‌ای مطابقت نداشته باشد، OpenClaw از زمان اجرای تعبیه‌شدهٔ خود استفاده می‌کند.

شکست‌های مهار Plugin به‌عنوان شکست اجرا ارائه می‌شوند. در حالت auto، بازگشت به اجرای تعبیه‌شده فقط زمانی اعمال می‌شود که هیچ مهار Plugin ثبت‌شده‌ای از ارائه‌دهنده/مدل تعیین‌شده پشتیبانی نکند. وقتی یک مهار Plugin اجرای کاری را در اختیار گرفته باشد، OpenClaw همان نوبت را از طریق زمان اجرایی دیگر دوباره پخش نمی‌کند، زیرا این کار می‌تواند معنای احراز هویت/زمان اجرا را تغییر دهد یا اثرات جانبی را تکرار کند.

سیاست پیکربندی‌شدهٔ زمان اجرا همچنان مرجع نهایی زمان اجرای مطلوب است. یک agentHarnessId نشست ماندگارشده، درحالی‌که آماده‌سازی مسیر/احراز هویت هنوز در انتظار است، مالکیت رونوشت بومی خود را حفظ می‌کند. هیچ‌کدام مسیری ناسازگار را سازگار نمی‌کنند: پس از موجودشدن واقعیت‌های آماده‌شده، مهار انتخاب‌شده یا سنجاق‌شده باید از آن‌ها پشتیبانی کند، وگرنه اجرا با رویکرد بسته شکست می‌خورد. /status زمان اجرای مؤثر انتخاب‌شده از سیاست، مالکیت ماندگارشده و پشتیبانی مسیر را نشان می‌دهد. وضعیت آماده‌شده صریح است: runtimePolicy مفقود، اعلام‌نشده باقی می‌ماند و از فیلدهای انتقالی که اتفاقاً وجود دارند استنباط نمی‌شود. هنگامی که احراز هویت در مالکیت مهار چند مسیر فیزیکی را تعیین‌نشده باقی می‌گذارد، واقعیت پشتیبانی آماده‌شده، اشتراک شناسه‌های زمان اجرای سازگار آن‌ها است و اگر هر نامزدی بازنویسی درخواست داشته باشد، آن را گزارش می‌کند. بنابراین یک نامزد اعلام‌نشده سازگاری بومی را خالی می‌کند؛ preparedAuth.source: "harness" مالک احراز هویت است، نه مجوزی برای استنباط پشتیبانی مسیر.

اگر مهار انتخاب‌شده غافلگیرکننده است، ثبت اشکال‌زدایی agents/harness را فعال کنید و رکورد ساختاریافتهٔ agent harness selected مربوط به Gateway را بررسی کنید: این رکورد شامل شناسهٔ مهار انتخاب‌شده، دلیل انتخاب، سیاست زمان اجرا/بازگشت جایگزین و در حالت auto، نتیجهٔ پشتیبانی هر نامزد Plugin است.

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

جفت‌سازی ارائه‌دهنده و مهار

بیشتر مهارها باید یک ارائه‌دهنده نیز ثبت کنند. ارائه‌دهنده ارجاعات مدل، وضعیت احراز هویت، فرادادهٔ مدل و انتخاب /model را برای بقیهٔ OpenClaw قابل‌مشاهده می‌کند. سپس مهار آن ارائه‌دهنده را در supports(...) در اختیار می‌گیرد.

Plugin باندل‌شدهٔ Codex از این الگو پیروی می‌کند:

• ارجاعات ترجیحی مدل کاربر: openai/gpt-5.6-sol
• ارجاعات سازگاری: ارجاعات قدیمی codex/gpt-* همچنان پذیرفته می‌شوند، اما پیکربندی‌های جدید نباید از آن‌ها به‌عنوان ارجاعات عادی ارائه‌دهنده/مدل استفاده کنند
• شناسهٔ مهار: codex
• احراز هویت: دسترس‌پذیری مصنوعی ارائه‌دهنده، زیرا مهار Codex مالک ورود/نشست بومی Codex است
• درخواست app-server: OpenClaw شناسهٔ خام مدل را به Codex می‌فرستد و اجازه می‌دهد مهار با پروتکل بومی app-server ارتباط برقرار کند

Plugin مربوط به Codex افزایشی است. وقتی سیاست زمان اجرا تنظیم نشده یا auto باشد، OpenAI فقط زمانی می‌تواند Codex را انتخاب کند که قرارداد مسیر در مالکیت ارائه‌دهندهٔ آن، codex را سازگار اعلام کند: یک مسیر دقیق و رسمی HTTPS برای Platform Responses یا ChatGPT Responses بدون بازنویسی تألیفی درخواست. پیشوند openai/* به‌تنهایی هرگز Codex را انتخاب نمی‌کند. نقاط پایانی سفارشی، سازگارکننده‌های Completions و رفتار تألیفی درخواست روی OpenClaw باقی می‌مانند. نقاط پایانی رسمی HTTP بدون رمزگذاری رد می‌شوند. ارجاعات قدیمی‌تر codex/gpt-* همچنان ورودی‌های سازگاری هستند. به زمان اجرای ضمنی عامل OpenAI مراجعه کنید.

برای راه‌اندازی اپراتور، مثال‌های پیشوند مدل و پیکربندی‌های مخصوص Codex، به مهار Codex مراجعه کنید.

Plugin مربوط به Codex حداقل نسخهٔ app-server مستندشده در مهار Codex را اعمال می‌کند. این Plugin دست‌دهی آغازین را بررسی می‌کند و سرورهای قدیمی‌تر یا بدون نسخه را مسدود می‌کند تا OpenClaw فقط روی سطح پروتکلی اجرا شود که آزمایش کرده است.

میان‌افزار نتیجهٔ ابزار

Plugin‌های باندل‌شده و Plugin‌های نصب‌شده‌ای که صراحتاً فعال شده‌اند و قراردادهای مانیفست منطبق دارند، می‌توانند از طریق api.registerAgentToolResultMiddleware(...) میان‌افزار نتیجهٔ ابزار مستقل از زمان اجرا را متصل کنند، مشروط بر اینکه مانیفست آن‌ها شناسه‌های زمان اجرای هدف را در contracts.agentToolResultMiddleware اعلام کند. این درگاه مورداعتماد برای تبدیل‌های ناهمگام نتیجهٔ ابزار است که باید پیش از آنکه OpenClaw یا Codex خروجی ابزار را دوباره به مدل بدهد اجرا شوند.

Pluginهای همراه قدیمی همچنان می‌توانند از api.registerCodexAppServerExtensionFactory(...) برای میان‌افزار مختص app-server در Codex استفاده کنند، اما تبدیل‌های نتیجه جدید باید از API مستقل از محیط اجرا استفاده کنند. هوک api.registerEmbeddedExtensionFactory(...) که فقط برای اجراکننده تعبیه‌شده بود حذف شده است؛ تبدیل‌های نتیجه ابزار تعبیه‌شده باید از میان‌افزار مستقل از محیط اجرا استفاده کنند.

طبقه‌بندی نتیجه نهایی

هارنس‌های بومی که نگاشت پروتکل خود را مدیریت می‌کنند، وقتی یک نوبت تکمیل‌شده هیچ متن قابل‌مشاهده‌ای از دستیار تولید نکرده است، می‌توانند از classifyAgentHarnessTerminalOutcome(...) در openclaw/plugin-sdk/agent-harness-runtime استفاده کنند. این تابع کمکی empty، reasoning-only یا planning-only را برمی‌گرداند تا سیاست بازگشت جایگزین OpenClaw بتواند تصمیم بگیرد آیا باید با مدلی دیگر دوباره تلاش کند یا نه. planning-only به فیلد صریح planText در هارنس نیاز دارد؛ OpenClaw آن را از نثر دستیار استنباط نمی‌کند. این تابع کمکی عمداً خطاهای پرامپت، نوبت‌های در حال اجرا و پاسخ‌های عمداً بی‌صدا مانند NO_REPLY را طبقه‌بندی‌نشده باقی می‌گذارد.

اثرات جانبی پایان عامل

هارنس‌های بومی باید پس از نهایی‌کردن یک تلاش، runAgentEndSideEffects(...) را از openclaw/plugin-sdk/agent-harness-runtime فراخوانی کنند. این تابع، هوک قابل‌انتقال agent_end و ثبت پژوهشی OpenClaw را بدون تأخیر در پاسخ‌های تعاملی اجرا می‌کند. برای اجراهای محلی و غیرتعاملی که تلاش نباید تا پایان این اثرات جانبی خاتمه یابد، از awaitAgentEndSideEffects(...) استفاده کنید. هر دو تابع کمکی همان محموله { event, ctx } مربوط به runAgentHarnessAgentEndHook(...) را می‌پذیرند؛ شکست آن‌ها نتیجه تلاش تکمیل‌شده را تغییر نمی‌دهد.

ورودی کاربر و سطوح ابزار

هارنس‌های بومی که درخواست ورودی کاربر در سطح محیط اجرا ارائه می‌کنند، باید از توابع کمکی ورودی کاربر در openclaw/plugin-sdk/agent-harness-runtime برای قالب‌بندی پرامپت، تحویل آن از مسیر پاسخ مسدودکننده OpenClaw و نرمال‌سازی پاسخ‌های انتخابی یا آزاد به شکل پاسخ بومی محیط اجرا استفاده کنند. این تابع کمکی نمایش در کانال/TUI را یکپارچه نگه می‌دارد، درحالی‌که هر هارنس تجزیه پروتکل و چرخه عمر درخواست‌های در انتظار خود را مدیریت می‌کند.

هارنس‌های بومی که به مسیریابی فشرده ابزار مشابه PI نیاز دارند، باید از createAgentHarnessToolSurfaceRuntime(...) در openclaw/plugin-sdk/agent-harness-tool-runtime استفاده کنند. این تابع انتخاب کنترل جست‌وجوی ابزار/حالت کد، پیش‌فرض‌های سبک مدل محلی، فیلترکردن شِمای سازگار با محیط اجرا، اجرای کاتالوگ پنهان، آماده‌سازی دایرکتوری و پاک‌سازی کاتالوگ را مدیریت می‌کند. هارنس‌ها همچنان مسئول تبدیل ابزار مختص SDK و تابع بازخوانی اجرای بومی خود هستند.

حالت هارنس بومی Codex

هارنس همراه codex حالت بومی Codex برای نوبت‌های عامل تعبیه‌شده OpenClaw است. ابتدا Plugin همراه codex را فعال کنید و اگر پیکربندی شما از فهرست مجاز محدودکننده استفاده می‌کند، codex را در plugins.allow قرار دهید. پیکربندی‌های بومی app-server باید از openai/gpt-* استفاده کنند؛ نوبت‌های عامل OpenAI فقط زمانی هارنس Codex را انتخاب می‌کنند که مسیر مؤثر، سازگاری با Codex را اعلام کرده باشد. ارجاع‌های قدیمی مدل Codex باید با openclaw doctor --fix اصلاح شوند و ارجاع‌های قدیمی مدل codex/* همچنان نام‌های مستعار سازگاری برای هارنس بومی باقی می‌مانند.

هنگام اجرای این حالت، Codex شناسه بومی رشته، رفتار ازسرگیری، Compaction و اجرای app-server را مدیریت می‌کند. OpenClaw همچنان کانال گفت‌وگو، نسخه آینه‌ای رونوشت قابل‌مشاهده، سیاست ابزار، تأییدها، تحویل رسانه و انتخاب نشست را مدیریت می‌کند. وقتی لازم است ثابت کنید فقط مسیر app-server در Codex می‌تواند اجرا را در اختیار بگیرد، از ارائه‌دهنده/مدل agentRuntime.id: "codex" استفاده کنید. محیط‌های اجرای صریح Plugin به‌صورت بسته شکست می‌خورند؛ شکست‌های انتخاب app-server در Codex و شکست‌های محیط اجرا از طریق محیط اجرایی دیگر دوباره امتحان نمی‌شوند.

سخت‌گیری محیط اجرا

OpenClaw به‌طور پیش‌فرض از سیاست محیط اجرای ارائه‌دهنده/مدل auto استفاده می‌کند: هارنس‌های Plugin ثبت‌شده می‌توانند مسیرهای مؤثر سازگار را در اختیار بگیرند و وقتی هیچ‌کدام مطابقت ندارند، محیط اجرای تعبیه‌شده نوبت را مدیریت می‌کند. پیشوند ارائه‌دهنده/مدل به‌تنهایی هرگز هارنسی را انتخاب نمی‌کند. وقتی نبود انتخاب هارنس باید به‌جای مسیریابی از طریق محیط اجرای تعبیه‌شده باعث شکست شود، از یک محیط اجرای صریح Plugin برای ارائه‌دهنده/مدل، مانند agentRuntime.id: "codex"، استفاده کنید. انتخاب صریح، مسیر ناسازگار را سازگار نمی‌کند. شکست هارنس‌های Plugin انتخاب‌شده همیشه به شکست قطعی منجر می‌شود. این کار یک agentRuntime.id: "openclaw" صریح برای ارائه‌دهنده/مدل را مسدود نمی‌کند.

برای اجراهای تعبیه‌شده مختص Codex:

{  "models": {    "providers": {      "openai": {        "agentRuntime": {          "id": "codex"        }      }    }  },  "agents": {    "defaults": {      "model": "openai/gpt-5.6-sol"    }  }}

اگر برای یک مدل مرجع به بک‌اند CLI نیاز دارید، محیط اجرا را در ورودی همان مدل قرار دهید:

{  "agents": {    "defaults": {      "model": "anthropic/claude-opus-5",      "models": {        "anthropic/claude-opus-5": {          "agentRuntime": {            "id": "claude-cli"          }        }      }    }  }}

بازنویسی‌های مختص هر عامل از همان ساختار محدود به مدل استفاده می‌کنند:

{  "agents": {    "list": [      {        "id": "codex-only",        "model": "openai/gpt-5.6-sol",        "models": {          "openai/gpt-5.6-sol": {            "agentRuntime": { "id": "codex" }          }        }      }    ]  }}

نمونه‌های قدیمی محیط اجرای سراسری عامل مانند نمونه زیر نادیده گرفته می‌شوند:

{  "agents": {    "defaults": {      "agentRuntime": {        "id": "codex"      }    }  }}

با محیط اجرای صریح Plugin، اگر هارنس درخواستی ثبت نشده باشد، از ارائه‌دهنده/مدل حل‌شده پشتیبانی نکند یا پیش از ایجاد اثرات جانبی نوبت شکست بخورد، نشست زودهنگام شکست می‌خورد. این رفتار برای استقرارهای مختص Codex و آزمون‌های زنده‌ای که باید ثابت کنند مسیر app-server در Codex واقعاً در حال استفاده است، عمدی است.

این تنظیم فقط هارنس عامل تعبیه‌شده را کنترل می‌کند. مسیریابی مدل مختص ارائه‌دهنده برای تصویر، ویدئو، موسیقی، TTS، PDF یا موارد دیگر را غیرفعال نمی‌کند.

نشست‌های بومی و نسخه آینه‌ای رونوشت

یک هارنس ممکن است شناسه نشست بومی، شناسه رشته یا توکن ازسرگیری سمت دیمن را نگه دارد. این اتصال را صریحاً با نشست OpenClaw مرتبط نگه دارید و خروجی قابل‌مشاهده دستیار/ابزار را همچنان در رونوشت OpenClaw آینه‌سازی کنید.

رونوشت OpenClaw همچنان لایه سازگاری برای موارد زیر است:

• تاریخچه نشست قابل‌مشاهده در کانال
• جست‌وجو و نمایه‌سازی رونوشت
• بازگشت به هارنس داخلی OpenClaw در نوبتی بعدی
• رفتار عمومی /new، /reset و حذف نشست

اگر هارنس شما یک اتصال جانبی ذخیره می‌کند، reset(...) را پیاده‌سازی کنید تا OpenClaw بتواند هنگام بازنشانی نشست OpenClaw مالک، آن را پاک کند.

نتایج ابزار و رسانه

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

این کار خروجی‌های متن، تصویر، ویدئو، موسیقی، TTS، تأیید و ابزار پیام‌رسانی را در همان مسیر تحویل اجراهای متکی بر OpenClaw نگه می‌دارد.

AgentHarnessAttemptResult.hostOwnedToolMediaUrls را فقط برای مصنوعات بومی‌ای تنظیم کنید که محیط اجرای قابل‌اعتماد هارنس، خودش آن‌ها را ایجاد و ماندگار کرده است. هر ورودی باید در toolMediaUrls نیز وجود داشته باشد. هرگز رسانه ابزار پویای انتخاب‌شده توسط مدل یا ابزار OpenClaw را وارد نکنید. در مسیرهای message_tool_only، این منشأ محدود اجازه می‌دهد مصنوعات بومی محیط اجرا از سرکوب پاسخ منبع جان سالم به در ببرند؛ سیاست عادی ارسال و پذیرش در اتاق عمومی همچنان اعمال می‌شوند.

نتایج نهایی ابزار

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

واقعیت‌ها را از مرز اجرا گزارش کنید:

• در صورت وجود، شناسه فراخوانی پروتکل، نام مرجع ابزار و آرگومان‌هایی را ارسال کنید که پس از آماده‌سازی یا بازنویسی‌های هوک واقعاً به ابزار رسیده‌اند.
• وقتی اعتبارسنجی، تأیید یا محافظی دیگر پیش از شروع پیاده‌سازی ابزار، فراخوانی را متوقف کرده است، executionStarted: false را تنظیم کنید. پس از آن‌که احتمال اجرای ارسال وجود دارد، true را به‌صورت محافظه‌کارانه گزارش کنید.
• outcome: "success" یا outcome: "failure" را گزارش کنید. به‌جای استنباط شکست از متن نمایشی، فیلدهای ساخت‌یافته شکست موجود در محیط اجرا را وارد کنید.
• از nativeMutation فقط برای ابزارهای بومی‌ای استفاده کنید که از تعریف ابزار OpenClaw استفاده نمی‌کنند. واقعیت‌های تغییر و بازپخش متعلق به پروتکل را در آن ارائه دهید؛ طبقه‌بندی‌کننده تغییر OpenClaw را در هارنس کپی نکنید.

تابع بازخوانی، نتیجه مرجع آن فراخوانی را برمی‌گرداند. مقدار lastToolError آن را به AgentHarnessAttemptResult منتقل کنید و به‌جای استخراج وضعیت موازی، از واقعیت‌های اجرا، آرگومان‌ها و اثرات جانبی آن در نگاشت هارنس استفاده کنید. میزبان یک شکست تغییر‌دهنده حل‌نشده را با وجود موفقیت ابزارهای نامرتبط حفظ می‌کند و فقط پس از موفقیت عمل متناظر آن را پاک می‌کند.

تابع بازخوانی برای سازگاری منبع با هارنس‌های آزمایشی قدیمی همچنان اختیاری است. اختیاری‌بودن برای هارنسی که ابزار اجرا می‌کند به معنای قابل‌چشم‌پوشی‌بودن نیست: بدون گزارش‌های نهایی، OpenClaw نمی‌تواند واقعیت شکست ابزار تغییر‌دهنده را در فراخوانی‌های بعدی ابزار، از جمله تکمیل بی‌صدای Heartbeat، حفظ کند.

نهایی‌سازی ابزارهای خاتمه‌یافته

ممکن است پس از آن‌که یک هارنس همه فراخوانی‌های ابزار را تکمیل کرده، اما نوبت بومی آن بدون متن دستیار پایان یافته است، OpenClaw به یک پاسخ قابل‌مشاهده نهایی نیاز داشته باشد. هارنس می‌تواند با پیاده‌سازی finalizeSettledTurn({ attempt, settledAttempt }) این بازیابی را فعال کند.

این تابع بازخوانی یک قابلیت جداگانه است، نه یک تلاش عادی دیگر. باید:

• یا از همان رونوشت محدود بومی استفاده کند، یا از رونوشت کامل برنامه که تا مرز نتیجه ابزار خاتمه‌یافته ثابت شده است؛
• هیچ ابزار، قابلیت اعطای مجوز یا ورودی کاربر، هوک اجرای بومی، عامل، Skills، حافظه، زمان‌بندی، افزونه یا کنترل از راه دوری ارائه نکند؛
• فقط پرامپت نهایی‌سازی ارائه‌شده توسط میزبان را ارسال کند؛ و
• اگر راهبرد انتخاب‌شده برای رونوشت/جداسازی نتواند این محدودیت‌ها را اعمال کند، به‌صورت بسته شکست بخورد.

OpenClaw تابع بازخوانی را یک‌بار به‌عنوان زیرعملیات نهایی، خارج از چرخه عادی تلاش و تکرار، فراخوانی می‌کند. شکست، اجرا را با هشدار نوبت ناقصِ آگاه از اثرات جانبی پایان می‌دهد؛ این شکست نمی‌تواند وارد مسیرهای عادی چرخش احراز هویت/نمایه، بازگشت جایگزین مدل، بازیابی زمینه، ادامه Compaction یا بازبینی درخواستی هوک شود. نهایی‌سازی همچنین از تغییر پرامپت Plugin، before_agent_run، ورودی/خروجی LLM، بازبینی نهایی و هوک‌های agent_end صرف‌نظر می‌کند. عیب‌یابی هسته همچنان عملیات و شکست آن را ثبت می‌کند.

تابع بازخوانی AgentHarnessSettledTurnFinalizationResult را برمی‌گرداند، نه یک نتیجه تلاش عادی. فیلدهای عمومی آن به پیام تکمیل‌شده دستیار، میزان استفاده فراخوانی نهایی‌سازی، فراداده مالکیت رونوشت و رد عیب‌یابی محدود هستند. وضعیت ابزار، تحویل، رسانه، ایجاد، چرخه عمر، بازپخش، نشست و بازگشت جایگزین نمی‌تواند از مرز این نتیجه عبور کند. فیلدهای ناشناخته و فراخوانی ابزار توسط دستیار به شکست بسته منجر می‌شوند.

هارنسی که در داخل از موتور کامل تلاش خود دوباره استفاده می‌کند، می‌تواند پیش از بازگشت projectSettledTurnFinalizationAttemptResult(...) را فراخوانی کند. این تابع کمکی شواهد مرجع شکست، ابزار، تحویل، بازپخش و چرخه عمر را رد می‌کند و سپس فقط نتیجه محدود را نگاشت می‌کند. این کار پس از جداسازی بومی، دفاع عمقی است، نه جایگزینی برای حذف سطح قابلیت بومی.

هارنسی که بر نگاشت متکی است باید زمینه کامل را با source: "openclaw-transcript" در settledAttempt.settledTurnFinalizationContext قرار دهد. باید پس از آینه‌سازی نوبت خاتمه‌یافته، شاخه فعال را ثبت کند، ثابت کند پرامپت فعلی و همه فراخوانی‌ها/نتایج ابزار فعلی تا آن مرز وجود دارند و آرایه پیام حاصل را پیش از بازگرداندن تلاش ثابت کند. نهایی‌ساز باید زمینه مفقود، پشتیبانی‌نشده، مبهم یا بیش‌ازحد بزرگ را رد کند. نباید پیام‌ها را کوتاه کند، تاریخچه قبلی را حذف کند یا این رونوشت برنامه را به‌عنوان تاریخچه دقیق بومی توصیف کند. هارنس‌هایی که یک نشست محدود بومی را از سر می‌گیرند، به این فیلد نگاشت نیاز ندارند.

این تابع بازخوانی را با فراخوانی runAttempt و یک راهنمای تقریبی disableTools پیاده‌سازی نکنید. مالک هارنس باید مرز کامل قابلیت بومی را اعمال کند. OpenClaw بازگشت جایگزین عمومی ارائه نمی‌کند، زیرا نمی‌تواند گواهی دهد که یک محیط اجرای بومی دلخواه این محدودیت‌ها را رعایت کرده است.

فراخوان بازگشتی برای سازگاری با هارنس‌های آزمایشی شخص ثالث همچنان اختیاری است. وقتی هارنس انتخاب‌شده آن را ارائه نمی‌کند، OpenClaw به‌جای به‌خطرانداختن تکرار اثرات جانبی، خطای موجودِ ناتمام‌بودن نوبت را حفظ می‌کند.

محدودیت‌های فعلی

• مسیر import عمومی کلی است، اما برخی نام‌های مستعار نوعِ تلاش/نتیجه همچنان برای سازگاری نام‌های قدیمی را حفظ کرده‌اند.
• نصب هارنس شخص ثالث آزمایشی است. تا زمانی که به یک محیط اجرای بومی نشست نیاز ندارید، Pluginهای ارائه‌دهنده را ترجیح دهید.
• تغییر هارنس میان نوبت‌ها پشتیبانی می‌شود. پس از شروع ابزارهای بومی، تأییدها، متن دستیار یا ارسال پیام‌ها، هارنس را در میانه یک نوبت تغییر ندهید.

مرتبط

• نمای کلی SDK
• توابع کمکی محیط اجرا
• Pluginهای ارائه‌دهنده
• هارنس Codex
• ارائه‌دهندگان مدل