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

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

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

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

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

نمونه‌ها:

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

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

# هسته همچنان مالک چه چیزهایی است

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

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

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

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

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

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

# ثبت یک مهار

Import: 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. شناسه مهار ثبت‌شده یک نشست موجود برنده می‌شود، بنابراین تغییرات config/env آن متن را به‌صورت داغ به زمان‌اجرای دیگری منتقل نمی‌کنند.
2. OPENCLAW_AGENT_RUNTIME=<id> برای نشست‌هایی که از قبل پین نشده‌اند، مهار ثبت‌شده‌ای با همان شناسه را اجبار می‌کند.
3. OPENCLAW_AGENT_RUNTIME=pi مهار داخلی PI را اجبار می‌کند.
4. OPENCLAW_AGENT_RUNTIME=auto از مهارهای ثبت‌شده می‌پرسد که آیا از ارائه‌دهنده/مدل حل‌شده پشتیبانی می‌کنند یا نه.
5. اگر هیچ مهار ثبت‌شده‌ای تطبیق نداشته باشد، OpenClaw از PI استفاده می‌کند مگر اینکه fallback به PI غیرفعال شده باشد.

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

شناسه مهار انتخاب‌شده پس از یک اجرای تعبیه‌شده همراه با شناسه نشست پایدار می‌شود. نشست‌های قدیمی که پیش از پین‌های مهار ساخته شده‌اند، پس از داشتن سابقه متن، به‌عنوان پین‌شده به PI در نظر گرفته می‌شوند. هنگام جابه‌جایی میان PI و مهار بومی Plugin از نشست جدید/ریست‌شده استفاده کنید. /status شناسه‌های مهار غیراستاندارد مانند codex را کنار Fast نشان می‌دهد؛ PI پنهان می‌ماند چون مسیر سازگاری پیش‌فرض است. اگر مهار انتخاب‌شده غیرمنتظره است، لاگ‌گیری دیباگ agents/harness را فعال کنید و رکورد ساخت‌یافته agent harness selected در gateway را بررسی کنید. این رکورد شامل شناسه مهار انتخاب‌شده، دلیل انتخاب، سیاست زمان‌اجرا/fallback، و در حالت auto نتیجه پشتیبانی هر نامزد Plugin است.

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

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

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

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

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

Plugin Codex افزایشی است. ارجاع‌های ساده openai/gpt-* همچنان از مسیر عادی ارائه‌دهنده OpenClaw استفاده می‌کنند، مگر اینکه مهار Codex را با agentRuntime.id: "codex" اجبار کنید. ارجاع‌های قدیمی‌تر codex/gpt-* همچنان برای سازگاری، ارائه‌دهنده و مهار Codex را انتخاب می‌کنند.

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

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

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

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

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

# طبقه‌بندی پیامد پایانی

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

# حالت مهار بومی Codex

مهار باندل‌شده codex حالت بومی Codex برای نوبت‌های عامل تعبیه‌شده OpenClaw است. ابتدا Plugin باندل‌شده codex را فعال کنید، و اگر config شما از allowlist محدودکننده استفاده می‌کند، codex را در plugins.allow قرار دهید. configهای بومی app-server باید از openai/gpt-* همراه با agentRuntime.id: "codex" استفاده کنند. برای OAuth مربوط به Codex از طریق PI از openai-codex/* استفاده کنید. ارجاع‌های مدل قدیمی codex/* همچنان aliasهای سازگاری برای مهار بومی باقی می‌مانند.

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

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

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

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

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

اگر می‌خواهید هر مهار Plugin ثبت‌شده‌ای مدل‌های مطابق را بپذیرد و در غیر این صورت از PI استفاده شود، id: "auto" را تنظیم کنید:

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

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

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

OPENCLAW_AGENT_RUNTIME همچنان زمان‌اجرای پیکربندی‌شده را override می‌کند.

OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run

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

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

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

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

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

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

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

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

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

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

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

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

# مرتبط

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