Plugin สำหรับฮาร์เนสเอเจนต์

ฮาร์เนสเอเจนต์ คือ executor ระดับล่างสำหรับเทิร์นของเอเจนต์ OpenClaw หนึ่งครั้งที่เตรียมไว้แล้ว ไม่ใช่ผู้ให้บริการโมเดล ไม่ใช่ช่องทาง และไม่ใช่รีจิสทรีเครื่องมือ สำหรับโมเดลความเข้าใจที่แสดงต่อผู้ใช้ โปรดดู รันไทม์เอเจนต์.

ใช้พื้นผิวนี้เฉพาะกับ Plugin แบบเนทีฟที่บันเดิลมาหรือเชื่อถือได้เท่านั้น สัญญานี้ ยังอยู่ในขั้นทดลอง เพราะชนิดพารามิเตอร์ตั้งใจให้สะท้อน runner แบบฝังตัวปัจจุบัน

ควรใช้ฮาร์เนสเมื่อใด

ลงทะเบียนฮาร์เนสเอเจนต์เมื่อกลุ่มโมเดลมีรันไทม์เซสชันแบบเนทีฟของตัวเอง และการส่งผ่านผู้ให้บริการ OpenClaw ตามปกติไม่ใช่นามธรรมที่เหมาะสม

ตัวอย่าง:

• เซิร์ฟเวอร์เอเจนต์เขียนโค้ดแบบเนทีฟที่เป็นเจ้าของเธรดและ Compaction
• CLI หรือ daemon ภายในเครื่องที่ต้องสตรีมเหตุการณ์แผน/การให้เหตุผล/เครื่องมือแบบเนทีฟ
• รันไทม์โมเดลที่ต้องใช้ id การดำเนินต่อของตัวเองนอกเหนือจากทรานสคริปต์เซสชัน ของ OpenClaw

อย่า ลงทะเบียนฮาร์เนสเพียงเพื่อเพิ่ม API ของ LLM ใหม่ สำหรับ API โมเดล HTTP หรือ WebSocket ปกติ ให้สร้าง Plugin ผู้ให้บริการ

สิ่งที่ core ยังคงเป็นเจ้าของ

ก่อนเลือกฮาร์เนส OpenClaw ได้แก้ไขสิ่งต่อไปนี้แล้ว:

• ผู้ให้บริการและโมเดล
• สถานะ auth ของรันไทม์
• ระดับการคิดและงบประมาณบริบท
• ไฟล์ทรานสคริปต์/เซสชันของ OpenClaw
• workspace, sandbox และนโยบายเครื่องมือ
• callback การตอบกลับของช่องทางและ callback การสตรีม
• นโยบาย fallback ของโมเดลและการสลับโมเดลแบบ live

การแบ่งนี้เป็นความตั้งใจ ฮาร์เนสรันความพยายามที่เตรียมไว้แล้ว ไม่ได้เลือก ผู้ให้บริการ แทนที่การส่งข้อความผ่านช่องทาง หรือสลับโมเดลแบบเงียบๆ

ความพยายามที่เตรียมไว้ยังรวม params.runtimePlan ซึ่งเป็นชุดนโยบายที่ OpenClaw เป็นเจ้าของ สำหรับการตัดสินใจของรันไทม์ที่ต้องใช้ร่วมกันระหว่าง OpenClaw และฮาร์เนสเนทีฟ:

• runtimePlan.tools.normalize(...) และ runtimePlan.tools.logDiagnostics(...) สำหรับนโยบายสคีมาเครื่องมือที่รับรู้ผู้ให้บริการ
• runtimePlan.transcript.resolvePolicy(...) สำหรับการทำให้ทรานสคริปต์ปลอดภัยและ นโยบายซ่อมแซมการเรียกเครื่องมือ
• runtimePlan.delivery.isSilentPayload(...) สำหรับการระงับการส่ง NO_REPLY และสื่อ ร่วมกัน
• runtimePlan.outcome.classifyRunResult(...) สำหรับการจำแนก fallback ของโมเดล
• runtimePlan.observability สำหรับเมตาดาทาผู้ให้บริการ/โมเดล/ฮาร์เนสที่แก้ไขแล้ว

ฮาร์เนสอาจใช้แผนนี้สำหรับการตัดสินใจที่ต้องตรงกับพฤติกรรมของ OpenClaw แต่ ยังควรมองว่ามันเป็นสถานะความพยายามที่ host เป็นเจ้าของ อย่าเปลี่ยนแปลงมันหรือใช้มันเพื่อ สลับผู้ให้บริการ/โมเดลภายในเทิร์น

ลงทะเบียนฮาร์เนส

อิมพอร์ต: 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 จะใช้ fallback แบบฝังตัว เฉพาะเมื่อไม่มีฮาร์เนส Plugin ที่ลงทะเบียนไว้รองรับผู้ให้บริการ/โมเดล ที่แก้ไขแล้วเท่านั้น เมื่อฮาร์เนส Plugin อ้างสิทธิ์การรันแล้ว OpenClaw จะไม่ เล่นเทิร์นเดียวกันนั้นซ้ำผ่านรันไทม์อื่น เพราะอาจเปลี่ยน ความหมายของ auth/รันไทม์หรือทำให้เกิด side effect ซ้ำ

การ pin รันไทม์ทั้งเซสชันและทั้งเอเจนต์จะถูกละเว้นในการเลือก ซึ่งรวมถึง ค่า agentHarnessId ของเซสชันที่ล้าสมัย, agents.defaults.agentRuntime, agents.list[].agentRuntime และ OPENCLAW_AGENT_RUNTIME /status แสดง รันไทม์ที่มีผลซึ่งเลือกจากเส้นทางผู้ให้บริการ/โมเดล หากฮาร์เนสที่เลือกน่าประหลาดใจ ให้เปิดการบันทึก debug agents/harness และ ตรวจสอบระเบียน agent harness selected แบบมีโครงสร้างของ Gateway ซึ่งรวม id ฮาร์เนสที่เลือก เหตุผลการเลือก นโยบายรันไทม์/fallback และในโหมด auto ผลการรองรับของผู้สมัคร Plugin แต่ละตัว

Plugin Codex ที่บันเดิลมาจะลงทะเบียน codex เป็น id ฮาร์เนสของตัวเอง Core มองสิ่งนี้ เป็น id ฮาร์เนส Plugin ปกติ alias เฉพาะ Codex ควรอยู่ใน Plugin หรือ config ของผู้ปฏิบัติงาน ไม่ใช่ในตัวเลือก shared runtime

การจับคู่ผู้ให้บริการกับฮาร์เนส

ฮาร์เนสส่วนใหญ่ควรลงทะเบียนผู้ให้บริการด้วย ผู้ให้บริการทำให้ model refs, สถานะ auth, เมตาดาทาโมเดล และการเลือก /model มองเห็นได้ต่อส่วนที่เหลือของ OpenClaw จากนั้นฮาร์เนสจึงอ้างสิทธิ์ผู้ให้บริการนั้นใน supports(...)

Plugin Codex ที่บันเดิลมาทำตามรูปแบบนี้:

• model refs ของผู้ใช้ที่แนะนำ: openai/gpt-5.5
• refs เพื่อความเข้ากันได้: refs แบบ legacy codex/gpt-* ยังคงยอมรับอยู่ แต่ config ใหม่ ไม่ควรใช้เป็น refs ผู้ให้บริการ/โมเดลตามปกติ
• id ฮาร์เนส: codex
• auth: ความพร้อมใช้งานของผู้ให้บริการแบบสังเคราะห์ เพราะฮาร์เนส Codex เป็นเจ้าของ login/เซสชัน Codex แบบเนทีฟ
• คำขอ app-server: OpenClaw ส่ง id โมเดลเปล่าไปยัง Codex และปล่อยให้ ฮาร์เนสคุยกับโปรโตคอล app-server แบบเนทีฟ

Plugin Codex เป็นแบบ additive refs เอเจนต์ openai/gpt-* ธรรมดาบนผู้ให้บริการ OpenAI ทางการจะเลือกฮาร์เนส Codex ตามค่าเริ่มต้น refs codex/gpt-* รุ่นเก่า ยังคงเลือกผู้ให้บริการและฮาร์เนส Codex เพื่อความเข้ากันได้

สำหรับการตั้งค่าของผู้ปฏิบัติงาน ตัวอย่างคำนำหน้าโมเดล และ config เฉพาะ Codex โปรดดู ฮาร์เนส Codex

OpenClaw ต้องใช้ Codex app-server 0.125.0 หรือใหม่กว่า Plugin Codex ตรวจสอบ handshake การ initialize ของ app-server และบล็อกเซิร์ฟเวอร์ที่เก่ากว่าหรือไม่มีเวอร์ชัน เพื่อให้ OpenClaw รันเฉพาะกับพื้นผิวโปรโตคอลที่ผ่านการทดสอบแล้วเท่านั้น ข้อกำหนดขั้นต่ำ 0.125.0 รวมการรองรับ payload ของ hook MCP แบบเนทีฟที่เข้ามาใน Codex 0.124.0 พร้อมทั้ง pin OpenClaw ไว้กับสาย stable ที่ใหม่กว่าและผ่านการทดสอบแล้ว

Middleware ผลลัพธ์เครื่องมือ

Plugin ที่บันเดิลมาและ Plugin ที่ติดตั้งซึ่งเปิดใช้อย่างชัดเจนพร้อมสัญญา manifest ที่ตรงกัน สามารถแนบ middleware ผลลัพธ์เครื่องมือที่เป็นกลางต่อรันไทม์ผ่าน api.registerAgentToolResultMiddleware(...) เมื่อ manifest ประกาศ id รันไทม์เป้าหมายใน contracts.agentToolResultMiddleware พื้นผิวที่เชื่อถือได้นี้ มีไว้สำหรับ transform ผลลัพธ์เครื่องมือแบบ async ที่ต้องรันก่อนที่ OpenClaw หรือ Codex จะป้อนผลลัพธ์เครื่องมือกลับเข้าโมเดล

Plugin legacy ที่บันเดิลมายังใช้ api.registerCodexAppServerExtensionFactory(...) สำหรับ middleware เฉพาะ Codex app-server ได้ แต่ transform ผลลัพธ์ใหม่ควรใช้ API ที่เป็นกลางต่อรันไทม์ hook api.registerEmbeddedExtensionFactory(...) ที่ใช้เฉพาะ embedded runner ถูกลบออกแล้ว; transform ผลลัพธ์เครื่องมือแบบฝังตัวต้องใช้ middleware ที่เป็นกลางต่อรันไทม์

การจำแนกผลลัพธ์ปลายทางของเทอร์มินัล

ฮาร์เนสเนทีฟที่เป็นเจ้าของการฉายโปรโตคอลของตัวเองสามารถใช้ classifyAgentHarnessTerminalOutcome(...) จาก openclaw/plugin-sdk/agent-harness-runtime เมื่อเทิร์นที่เสร็จสมบูรณ์ไม่มี ข้อความ assistant ที่มองเห็นได้ helper จะคืนค่า empty, reasoning-only หรือ planning-only เพื่อให้นโยบาย fallback ของ OpenClaw ตัดสินใจว่าจะลองใหม่บน โมเดลอื่นหรือไม่ planning-only ต้องใช้ฟิลด์ planText ที่ฮาร์เนสระบุอย่างชัดเจน; OpenClaw จะไม่อนุมานจาก prose ของ assistant helper ตั้งใจปล่อยให้ ข้อผิดพลาด prompt, เทิร์นที่กำลังดำเนินอยู่ และการตอบกลับแบบเงียบโดยเจตนา เช่น NO_REPLY ไม่ถูกจำแนก

Side effect เมื่อเอเจนต์สิ้นสุด

ฮาร์เนสเนทีฟต้องเรียก runAgentEndSideEffects(...) จาก openclaw/plugin-sdk/agent-harness-runtime หลังจาก finalize ความพยายามแล้ว มัน dispatch hook agent_end แบบพกพาและการจับข้อมูลงานวิจัยของ OpenClaw โดยไม่ หน่วงการตอบกลับแบบโต้ตอบ ใช้ awaitAgentEndSideEffects(...) สำหรับการรันภายในเครื่อง ที่ไม่โต้ตอบ ซึ่งความพยายามต้องไม่ resolve จนกว่า side effect เหล่านั้น จะเสร็จ ทั้งสอง helper รับ payload { event, ctx } เดียวกับ runAgentHarnessAgentEndHook(...); ความล้มเหลวของพวกมันไม่เปลี่ยนผลลัพธ์ ความพยายามที่เสร็จสมบูรณ์

อินพุตผู้ใช้และพื้นผิวเครื่องมือ

ฮาร์เนสเนทีฟที่เปิดเผยคำขออินพุตผู้ใช้ระดับรันไทม์ควรใช้ helper อินพุตผู้ใช้จาก openclaw/plugin-sdk/agent-harness-runtime เพื่อจัดรูปแบบ prompt ส่งผ่านเส้นทางตอบกลับแบบ blocking ของ OpenClaw และ normalize คำตอบแบบตัวเลือก/ข้อความอิสระกลับเป็นรูปแบบการตอบกลับเนทีฟของรันไทม์ helper ทำให้การนำเสนอผ่านช่องทาง/TUI สอดคล้องกัน ขณะที่แต่ละฮาร์เนสยังคงดูแล การ parse โปรโตคอลและวงจรชีวิตคำขอที่รอดำเนินการของตัวเอง

ฮาร์เนสเนทีฟที่ต้องการการจัดเส้นทางเครื่องมือแบบกระชับคล้าย PI ควรใช้ createAgentHarnessToolSurfaceRuntime(...) จาก openclaw/plugin-sdk/agent-harness-tool-runtime มันเป็นเจ้าของ การเลือก control สำหรับ tool-search/code-mode, ค่าเริ่มต้นแบบ lean ของ local model, การกรองสคีมาที่เข้ากันได้กับรันไทม์, การดำเนินการ catalog ที่ซ่อนอยู่, การเติมข้อมูลไดเรกทอรี และการล้าง catalog ฮาร์เนสยังคงเป็นเจ้าของการแปลงเครื่องมือ เฉพาะ SDK ของตัวเองและ callback การดำเนินการแบบเนทีฟ

โหมดฮาร์เนส Codex แบบเนทีฟ

ฮาร์เนส codex ที่บันเดิลมาคือโหมด Codex แบบเนทีฟสำหรับเทิร์นเอเจนต์ OpenClaw แบบฝังตัว เปิดใช้ Plugin codex ที่บันเดิลมาก่อน และรวม codex ใน plugins.allow หาก config ของคุณใช้ allowlist แบบจำกัด config app-server แบบเนทีฟ ควรใช้ openai/gpt-*; เทิร์นเอเจนต์ OpenAI เลือกฮาร์เนส Codex ตามค่าเริ่มต้น เส้นทาง refs โมเดล Codex legacy ควรถูกซ่อมด้วย openclaw doctor --fix และ refs โมเดล legacy codex/* ยังคงเป็น alias เพื่อความเข้ากันได้สำหรับฮาร์เนสเนทีฟ

เมื่อโหมดนี้รัน Codex เป็นเจ้าของ id เธรดเนทีฟ พฤติกรรมการดำเนินต่อ Compaction และการดำเนินการ app-server OpenClaw ยังคงเป็นเจ้าของช่องแชต, กระจกทรานสคริปต์ที่มองเห็นได้, นโยบายเครื่องมือ, approvals, การส่งสื่อ และการเลือก เซสชัน ใช้ผู้ให้บริการ/โมเดล agentRuntime.id: "codex" เมื่อคุณต้องพิสูจน์ ว่ามีเพียงเส้นทาง Codex app-server เท่านั้นที่อ้างสิทธิ์การรันได้ รันไทม์ Plugin ที่ระบุอย่างชัดเจน จะ fail closed; ความล้มเหลวในการเลือก Codex app-server และความล้มเหลวของรันไทม์ จะไม่ถูกลองใหม่ผ่านรันไทม์อื่น

ความเข้มงวดของรันไทม์

ตามค่าเริ่มต้น OpenClaw ใช้นโยบายรันไทม์ผู้ให้บริการ/โมเดล auto: ฮาร์เนส Plugin ที่ลงทะเบียนไว้สามารถอ้างสิทธิ์คู่ผู้ให้บริการ/โมเดล และรันไทม์แบบฝังตัว จะจัดการเทิร์นเมื่อไม่มีรายการใดตรงกัน refs เอเจนต์ 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"    }  }}

หากคุณต้องการ backend CLI สำหรับโมเดล canonical หนึ่งตัว ให้วางรันไทม์ไว้บน รายการโมเดลนั้น:

{  "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" }          }        }      }    ]  }}

ตัวอย่างรันไทม์ทั้งเอเจนต์แบบ legacy เช่นนี้จะถูกละเว้น:

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

เมื่อมี Plugin runtime ที่ระบุอย่างชัดเจน เซสชันจะล้มเหลวตั้งแต่เนิ่น ๆ เมื่อฮาร์เนสที่ร้องขอยังไม่ได้ลงทะเบียน ไม่รองรับผู้ให้บริการ/โมเดลที่ถูก resolve แล้ว หรือล้มเหลวก่อนสร้างผลข้างเคียงของรอบการโต้ตอบ นี่เป็นพฤติกรรมที่ตั้งใจไว้สำหรับการปรับใช้ที่ใช้ Codex เท่านั้น และสำหรับการทดสอบสดที่ต้องพิสูจน์ว่าเส้นทาง app-server ของ Codex ถูกใช้งานจริง

การตั้งค่านี้ควบคุมเฉพาะฮาร์เนสเอเจนต์แบบฝังเท่านั้น ไม่ได้ปิดใช้งานการกำหนดเส้นทางโมเดลเฉพาะผู้ให้บริการสำหรับรูปภาพ วิดีโอ เพลง TTS, PDF หรืออย่างอื่น

เซสชันเนทีฟและมิเรอร์ทรานสคริปต์

ฮาร์เนสอาจเก็บ ID เซสชันเนทีฟ, ID เธรด หรือโทเค็นสำหรับทำงานต่อที่ฝั่ง daemon ได้ ให้ผูกข้อมูลนั้นกับเซสชัน OpenClaw อย่างชัดเจน และมิเรอร์เอาต์พุตของผู้ช่วย/เครื่องมือที่ผู้ใช้มองเห็นได้ลงในทรานสคริปต์ของ OpenClaw ต่อไป

ทรานสคริปต์ของ OpenClaw ยังคงเป็นเลเยอร์ความเข้ากันได้สำหรับ:

• ประวัติเซสชันที่มองเห็นได้ในช่องทาง
• การค้นหาและการทำดัชนีทรานสคริปต์
• การสลับกลับไปใช้ฮาร์เนส OpenClaw ในตัวในรอบการโต้ตอบถัดไป
• พฤติกรรมทั่วไปของ /new, /reset และการลบเซสชัน

หากฮาร์เนสของคุณเก็บการผูกแบบ sidecar ให้ implement reset(...) เพื่อให้ OpenClaw สามารถล้างข้อมูลนั้นเมื่อเซสชัน OpenClaw ที่เป็นเจ้าของถูกรีเซ็ต

ผลลัพธ์ของเครื่องมือและสื่อ

คอร์จะสร้างรายการเครื่องมือของ OpenClaw และส่งต่อเข้าไปในการพยายามที่เตรียมไว้ เมื่อฮาร์เนสดำเนินการเรียกเครื่องมือแบบไดนามิก ให้ส่งผลลัพธ์ของเครื่องมือกลับผ่านรูปแบบผลลัพธ์ของฮาร์เนส แทนที่จะส่งสื่อไปยังช่องทางด้วยตัวเอง

สิ่งนี้ทำให้เอาต์พุตข้อความ รูปภาพ วิดีโอ เพลง TTS การอนุมัติ และเครื่องมือรับส่งข้อความอยู่บนเส้นทางการส่งมอบเดียวกับการรันที่มี OpenClaw รองรับ

ข้อจำกัดปัจจุบัน

• เส้นทาง import สาธารณะเป็นแบบทั่วไป แต่ alias ของชนิด attempt/result บางรายการยังคงใช้ชื่อเดิมเพื่อความเข้ากันได้
• การติดตั้งฮาร์เนสของบุคคลที่สามยังอยู่ในขั้นทดลอง ควรใช้ Plugin ผู้ให้บริการจนกว่าคุณจะต้องใช้ runtime เซสชันเนทีฟ
• รองรับการสลับฮาร์เนสข้ามรอบการโต้ตอบ อย่าสลับฮาร์เนสกลางรอบหลังจากเครื่องมือเนทีฟ การอนุมัติ ข้อความผู้ช่วย หรือการส่งข้อความเริ่มทำงานแล้ว

ที่เกี่ยวข้อง

• ภาพรวม SDK
• ตัวช่วย Runtime
• Plugin ผู้ให้บริการ
• ฮาร์เนส Codex
• ผู้ให้บริการโมเดล