Pluginهای هارنس عامل

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

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

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

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

نمونه‌ها:

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

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

آنچه هسته همچنان مالک آن است

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

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

این جداسازی عمدی است. هارنس یک تلاش آماده‌شده را اجرا می‌کند؛ ارائه‌دهنده‌ها را انتخاب نمی‌کند، تحویل کانال را جایگزین نمی‌کند، و مدل‌ها را بی‌سروصدا عوض نمی‌کند.

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

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

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

ثبت هارنس

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

  const myHarness: AgentHarness = {  id: "my-harness",  label: "My native agent harness",   supports(ctx) {    return ctx.provider === "my-provider"      ? { supported: true, priority: 100 }      : { supported: false };  },   async runAttempt(params) {    // Start or resume your native thread.    // Use params.prompt, params.tools, params.images, params.onPartialReply,    // params.onAgentEvent, and the other prepared attempt fields.    return await runMyNativeTurn(params);  },}; export default definePluginEntry({  id: "my-native-agent",  name: "My Native Agent",  description: "Runs selected models through a native agent daemon.",  register(api) {    api.registerAgentHarness(myHarness);  },});

سیاست انتخاب

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

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

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

پین‌های زمان اجرای کل نشست و کل عامل در انتخاب نادیده گرفته می‌شوند. این شامل مقادیر قدیمی agentHarnessId نشست، agents.defaults.agentRuntime، agents.list[].agentRuntime، و OPENCLAW_AGENT_RUNTIME است. /status زمان اجرای موثر انتخاب‌شده از مسیر ارائه‌دهنده/مدل را نشان می‌دهد. اگر هارنس انتخاب‌شده غیرمنتظره است، لاگ‌گیری اشکال‌زدایی agents/harness را فعال کنید و رکورد ساختاریافته agent harness selected در Gateway را بررسی کنید. این رکورد شامل شناسه هارنس انتخاب‌شده، دلیل انتخاب، سیاست زمان اجرا/بازگشت، و در حالت auto، نتیجه پشتیبانی هر نامزد Plugin است.

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

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

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

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

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

Plugin Codex افزایشی است. ارجاع‌های عامل ساده openai/gpt-* روی ارائه‌دهنده رسمی OpenAI به‌صورت پیش‌فرض هارنس Codex را انتخاب می‌کنند. ارجاع‌های قدیمی codex/gpt-* هنوز برای سازگاری ارائه‌دهنده و هارنس Codex را انتخاب می‌کنند.

برای راه‌اندازی اپراتور، نمونه‌های پیشوند مدل، و پیکربندی‌های فقط Codex، هارنس Codex را ببینید.

OpenClaw به app-server نسخه 0.125.0 یا جدیدتر Codex نیاز دارد. Plugin Codex handshake مقداردهی اولیه app-server را بررسی می‌کند و سرورهای قدیمی‌تر یا بدون نسخه را مسدود می‌کند تا OpenClaw فقط در برابر سطح پروتکلی اجرا شود که با آن آزموده شده است. کف 0.125.0 شامل پشتیبانی payload قلاب بومی MCP است که در Codex 0.124.0 وارد شد، درحالی‌که OpenClaw را به خط پایدار آزموده‌شده جدیدتر پین می‌کند.

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

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

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

طبقه‌بندی خروجی نهایی ترمینال

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

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

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

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

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

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

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

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

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

سخت‌گیری زمان اجرا

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

برای اجراهای تعبیه‌شده فقط Codex:

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

اگر برای یک مدل canonical به backend مبتنی بر CLI نیاز دارید، زمان اجرا را روی همان ورودی مدل قرار دهید:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مرتبط

• نمای کلی SDK
• راهنماهای زمان اجرا
• Pluginهای ارائه‌دهنده
• هارنس Codex
• ارائه‌دهندگان مدل