Plugin สำหรับชุดควบคุมเอเจนต์

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

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

เมื่อใดควรใช้ harness

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

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

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

สิ่งที่คอร์ยังคงจัดการ

ก่อนเลือก harness OpenClaw ได้แก้ไขรายการต่อไปนี้แล้ว:

• ผู้ให้บริการและโมเดล
• สถานะการยืนยันตัวตนของรันไทม์ เว้นแต่ harness จะประกาศว่าเป็นผู้จัดการการบูตสแตรปการยืนยันตัวตน
• ระดับการคิดและงบประมาณบริบท
• ไฟล์ทรานสคริปต์/เซสชันของ OpenClaw
• พื้นที่ทำงาน แซนด์บ็อกซ์ และนโยบายเครื่องมือ
• คอลแบ็กการตอบกลับของช่องทางและคอลแบ็กการสตรีม
• นโยบายการใช้โมเดลสำรองและการสลับโมเดลขณะทำงาน

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

การบูตสแตรปการยืนยันตัวตนที่ harness จัดการ

โดยค่าเริ่มต้น คอร์จะแก้ไขข้อมูลประจำตัวของผู้ให้บริการก่อนเรียก harness harness ที่เชื่อถือได้และสามารถยืนยันตัวตนผ่านรันไทม์แบบเนทีฟของตนเองอาจตั้งค่า authBootstrap: "harness" ในการลงทะเบียน AgentHarness แบบคงที่ จากนั้นคอร์จะ ข้ามการบูตสแตรปข้อมูลประจำตัวของผู้ให้บริการแบบทั่วไปและความล้มเหลวเนื่องจากไม่มีข้อมูลประจำตัว สำหรับทุกความพยายามที่ harness นั้นรับผิดชอบ

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

อาร์ติแฟกต์รันไทม์สำหรับการตั้งค่าที่ผ่านการตรวจสอบ

harness ภายในเครื่องที่สามารถให้บริการอนุมานสำหรับการตั้งค่าครั้งแรกต้องรับรอง การติดตั้งใช้งานที่ทำโพรบเสร็จสมบูรณ์ เมื่อ params.captureRuntimeArtifact เป็นจริง ให้ส่งคืน result.runtimeArtifact แบบทึบแสงที่มีรหัสคงที่และลายนิ้วมือเนื้อหา ลงทะเบียน ความสามารถ runtimeArtifact.validate(...) ที่ตรงกัน ซึ่งตรวจสอบการผูกนั้นอีกครั้ง โดยไม่โหลด harness อื่นหรือสแกน Plugin ที่ไม่เกี่ยวข้อง

การดำเนินการต่อของ OpenClaw ที่ผ่านการตรวจสอบยังส่ง params.expectedRuntimeArtifact ด้วย harness ต้องเปรียบเทียบค่านี้กับโปรเซสแบบเนทีฟตัวจริงที่ได้รับมา และล้มเหลว ก่อนเริ่มหรือกลับมาทำเธรดแบบเนทีฟต่อ หากค่าไม่ตรงกัน รอบการทำงานปกติของเอเจนต์ จะละทั้งสองฟิลด์ไว้ ดังนั้นการแฮชเนื้อหาจึงไม่อยู่ในเส้นทางด่วนของคำขอตามปกติ harness แบบรีโมต/WebSocket ต้องมีสัญญาการรับรองจากเซิร์ฟเวอร์ก่อน จึงจะเข้าร่วมได้ สตริงเวอร์ชันเพียงอย่างเดียวไม่ใช่อัตลักษณ์ของอาร์ติแฟกต์

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

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

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

สัญญาการขนส่งคำขอ

supports(ctx) รับการขนส่งโมเดลที่แก้ไขแล้วใน ctx.modelProvider ข้อเท็จจริงสองรายการที่ไม่มีความลับและผู้ให้บริการเป็นผู้จัดการใช้อธิบายเส้นทางที่เลือก:

• runtimePolicy.compatibleIds แสดงรายการรหัสรันไทม์ที่ผู้ให้บริการประกาศว่า เข้ากันได้กับเส้นทางที่เป็นรูปธรรมนั้น การไม่มีนโยบายหมายความว่าผู้ให้บริการไม่ได้ ประกาศความเข้ากันได้ระดับเส้นทาง ไม่ใช่การอนุญาตให้อนุมานว่ารองรับ
• requestTransportOverrides: "none" หมายความว่าไม่ต้องทำซ้ำการแทนที่คำขอ ของผู้ให้บริการ/โมเดลที่เขียนไว้ "present" หมายความว่ามีส่วนหัวที่เขียนไว้ การขนส่ง การยืนยันตัวตน พร็อกซี TLS บริการภายในเครื่อง พฤติกรรมเครือข่ายส่วนตัว หรือพารามิเตอร์ คำขอ ข้อเท็จจริงนี้ไม่เปิดเผยค่าเหล่านั้น

ส่งคืน { supported: false, reason } เมื่อ harness ไม่สามารถทำซ้ำ การขนส่งที่เตรียมไว้ อย่าอนุมานการรองรับด้วยการอ่านการกำหนดค่าดิบหลังการเลือก เมื่อการเตรียมการยืนยันตัวตนสร้างเส้นทางลองใหม่หลายเส้นทาง harness หนึ่งรายการต้องรองรับ ทั้งหมดก่อนส่งงาน การเลือกโดยนัยจะใช้ OpenClaw หากไม่มี Plugin ใดสามารถ จัดการทั้งชุดได้ ส่วนการเลือก Plugin แบบชัดเจนหรือที่คงไว้จะล้มเหลวแบบปิด

ลงทะเบียน harness

นำเข้า: openclaw/plugin-sdk/agent-harness

  const myHarness: AgentHarness = {  id: "my-harness",  label: "My native agent harness",   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: "effective route is not harness-compatible" };  },   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: "My Native Agent",  description: "เรียกใช้โมเดลที่เลือกผ่านดีมอนเอเจนต์แบบเนทีฟ",  register(api) {    api.registerAgentHarness(myHarness);  },});

authBootstrap ตั้งใจให้ไม่มีอยู่ในตัวอย่างทั่วไปนี้ เพิ่ม authBootstrap: "harness" เฉพาะเมื่อ harness เป็นไปตามสัญญาข้างต้น

การดำเนินการแบบมอบหมาย

เจ้าของ harness อาจตั้งค่า delegatedExecutionPluginIds เป็นรหัสของ Plugin ที่เชื่อถือได้และจำเป็นต้องดำเนินการเซสชันเดิมที่ล็อกโมเดลไว้ เช่น การขนส่ง เสียงที่ดำเนินบทสนทนาซึ่งใช้ Codex ต่อ นี่เป็นความยินยอมแบบคงที่จากเจ้าของ ไม่ใช่รายการอนุญาตของคอร์ ให้จำกัดขอบเขตไว้

ผู้รับมอบหมายจะได้รับเฉพาะการรับงานและการดำเนินการแบบฝังตัว OpenClaw กำหนดให้ใช้ คีย์เซสชัน เส้นทางสโตร์ และรหัสเซสชันที่จัดเก็บไว้ตรงกันทุกประการ; modelSelectionLocked: true; และค่า agentHarnessId กับ agentHarnessRuntimeOverride ที่ตรงกัน จากนั้นการเรียกใช้จะถูกจำกัดขอบเขตผ่านเจ้าของ harness การสร้างเซสชัน การแพตช์ การรีเซ็ต การลบ การเก็บถาวร และการเปลี่ยนแปลง Gateway ยังคงทำได้โดยเจ้าของเท่านั้น

นโยบายการเลือก

OpenClaw เลือก harness หลังแก้ไขผู้ให้บริการ/โมเดลแล้ว:

1. นโยบายรันไทม์ที่กำหนดขอบเขตระดับโมเดลมีสิทธิ์เหนือกว่า
2. นโยบายรันไทม์ที่กำหนดขอบเขตระดับผู้ให้บริการมีลำดับถัดมา
3. auto สอบถาม harness ที่ลงทะเบียนไว้ว่ารองรับเส้นทางที่มีผล และแก้ไขแล้วหรือไม่ คำนำหน้าผู้ให้บริการ/โมเดลเพียงอย่างเดียวจะไม่เลือก harness
4. หากไม่มี harness ที่ลงทะเบียนไว้ตรงกัน OpenClaw จะใช้รันไทม์แบบฝังตัว

ความล้มเหลวของ harness จาก Plugin จะแสดงเป็นความล้มเหลวของการเรียกใช้ ในโหมด auto การกลับไปใช้แบบฝังตัวจะใช้เฉพาะเมื่อไม่มี harness จาก Plugin ที่ลงทะเบียนไว้รองรับ ผู้ให้บริการ/โมเดลที่แก้ไขแล้ว เมื่อ harness จาก Plugin รับผิดชอบการเรียกใช้แล้ว OpenClaw จะไม่ เล่นรอบเดียวกันนั้นซ้ำผ่านรันไทม์อื่น เพราะอาจเปลี่ยน ความหมายของการยืนยันตัวตน/รันไทม์ หรือทำให้ผลข้างเคียงเกิดซ้ำ

นโยบายรันไทม์ที่กำหนดค่าไว้ยังคงเป็นข้อมูลหลักที่กำหนดรันไทม์ที่ต้องการ agentHarnessId ของเซสชันที่คงไว้จะรักษาความเป็นเจ้าของทรานสคริปต์แบบเนทีฟ ขณะที่การเตรียมเส้นทาง/การยืนยันตัวตนยังอยู่ระหว่างดำเนินการ ทั้งสองอย่างไม่ได้ทำให้เส้นทางที่ไม่เข้ากัน กลายเป็นเข้ากันได้: เมื่อมีข้อเท็จจริงที่เตรียมไว้แล้ว harness ที่เลือกหรือปักหมุดไว้ ต้องรองรับข้อเท็จจริงเหล่านั้น มิฉะนั้นการเรียกใช้จะล้มเหลวแบบปิด /status แสดงรันไทม์ที่มีผล ซึ่งเลือกจากนโยบาย ความเป็นเจ้าของที่คงไว้ และการรองรับเส้นทาง สถานะการเตรียมเป็นแบบชัดเจน: runtimePolicy ที่หายไปจะยังคงไม่ประกาศ แทนที่จะอนุมานจากฟิลด์การขนส่งใดก็ตามที่มีอยู่ เมื่อการยืนยันตัวตนที่ harness จัดการยังมีเส้นทางจริงหลายเส้นทางที่ไม่ได้แก้ไข ข้อเท็จจริงการรองรับที่เตรียมไว้คือส่วนตัดกันของรหัสรันไทม์ที่เข้ากันได้ และ รายงานการแทนที่คำขอหากตัวเลือกใดมีอยู่ ดังนั้นตัวเลือกที่ไม่ประกาศเพียงหนึ่งรายการ จะทำให้ความเข้ากันได้แบบเนทีฟว่างเปล่า; preparedAuth.source: "harness" เป็นเจ้าของการยืนยันตัวตน ไม่ใช่การอนุญาตให้อนุมานการรองรับเส้นทาง

หาก harness ที่เลือกไม่เป็นไปตามคาด ให้เปิดใช้การบันทึกดีบัก agents/harness และตรวจสอบระเบียน agent harness selected แบบมีโครงสร้างของ Gateway ซึ่ง รวมรหัส harness ที่เลือก เหตุผลในการเลือก นโยบายรันไทม์/การใช้สำรอง และในโหมด auto ผลการรองรับของผู้สมัครจาก Plugin แต่ละรายการ

Plugin Codex ที่รวมมาให้ลงทะเบียน codex เป็นรหัส harness คอร์ถือว่า รหัสดังกล่าวเป็นรหัส harness จาก Plugin ปกติ ส่วนชื่อแทนเฉพาะ Codex อยู่ใน Plugin หรือการกำหนดค่าของผู้ดำเนินการ ไม่ใช่ในตัวเลือกรันไทม์ที่ใช้ร่วมกัน

การจับคู่ผู้ให้บริการกับ harness

harness ส่วนใหญ่ควรลงทะเบียนผู้ให้บริการด้วย ผู้ให้บริการทำให้การอ้างอิงโมเดล สถานะการยืนยันตัวตน ข้อมูลเมตาของโมเดล และการเลือก /model ปรากฏแก่ส่วนอื่นๆ ของ OpenClaw จากนั้น harness จะรับผิดชอบผู้ให้บริการนั้นใน supports(...)

Plugin Codex ที่รวมมาให้ใช้รูปแบบนี้:

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

Plugin Codex เป็นส่วนเสริม เมื่อไม่ได้ตั้งค่านโยบายรันไทม์หรือเป็น auto OpenAI อาจ เลือก Codex เฉพาะเมื่อสัญญาเส้นทางที่ผู้ให้บริการเป็นผู้จัดการประกาศว่า codex เข้ากันได้: เส้นทาง HTTPS อย่างเป็นทางการที่ตรงกันทุกประการสำหรับ Platform Responses หรือ ChatGPT Responses โดยไม่มีการแทนที่คำขอที่เขียนไว้ คำนำหน้า openai/* เพียงอย่างเดียวจะไม่ เลือก Codex ปลายทางแบบกำหนดเอง อะแดปเตอร์ Completions และพฤติกรรมคำขอที่เขียนไว้ จะยังคงอยู่บน OpenClaw ปลายทาง HTTP แบบข้อความธรรมดาที่เป็นทางการจะถูกปฏิเสธ การอ้างอิง codex/gpt-* รุ่นเก่ายังคงเป็นอินพุตเพื่อความเข้ากันได้ โปรดดู รันไทม์เอเจนต์โดยนัยของ OpenAI

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

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

มิดเดิลแวร์ผลลัพธ์เครื่องมือ

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

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

การจำแนกผลลัพธ์ปลายทาง

ฮาร์เนสเนทีฟที่จัดการการฉายภาพโปรโตคอลของตนเองสามารถใช้ 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 จะจัดการ ID เธรดเนทีฟ พฤติกรรมการทำงานต่อ Compaction และการเรียกใช้ app-server ส่วน OpenClaw ยังคงจัดการช่องทางแชต สำเนาทรานสคริปต์ที่มองเห็นได้ นโยบายเครื่องมือ การอนุมัติ การส่งสื่อ และการเลือกเซสชัน ใช้ผู้ให้บริการ/โมเดล agentRuntime.id: "codex" เมื่อต้องการ พิสูจน์ว่ามีเพียงเส้นทาง app-server ของ 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-4-8",      "models": {        "anthropic/claude-opus-4-8": {          "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 หรืออื่น ๆ

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

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

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

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

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

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

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

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

ตั้งค่า AgentHarnessAttemptResult.hostOwnedToolMediaUrls เฉพาะสำหรับอาร์ติแฟกต์เนทีฟ ที่รันไทม์ฮาร์เนสที่เชื่อถือได้สร้างและจัดเก็บไว้ด้วยตนเองเท่านั้น ทุกรายการต้อง ปรากฏใน toolMediaUrls ด้วย ห้ามรวมสื่อจากเครื่องมือแบบไดนามิกที่โมเดลเลือกหรือ เครื่องมือ OpenClaw บนเส้นทาง message_tool_only ที่มาที่จำกัดนี้ช่วยให้ อาร์ติแฟกต์รันไทม์เนทีฟยังคงอยู่ได้เมื่อระงับการตอบกลับจากต้นทาง โดยนโยบายการส่ง ตามปกติและการอนุญาตเข้าห้องโดยรอบยังคงมีผล

ผลลัพธ์ปลายทางของเครื่องมือ

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

รายงานข้อเท็จจริงจากขอบเขตการเรียกใช้:

• ส่ง ID การเรียกโปรโตคอลเมื่อมี ชื่อเครื่องมือมาตรฐาน และ อาร์กิวเมนต์ที่ส่งถึงเครื่องมือจริงหลังจากการเตรียมหรือการเขียนใหม่โดยฮุก
• ตั้งค่า executionStarted: false เมื่อการตรวจสอบความถูกต้อง การอนุมัติ หรือตัวป้องกันอื่น หยุดการเรียกก่อนเริ่มการทำงานของเครื่องมือ เมื่อมีความเป็นไปได้ว่าเกิดการส่งต่อแล้ว ให้รายงาน true อย่างระมัดระวัง
• รายงาน outcome: "success" หรือ outcome: "failure" ให้รวมฟิลด์ ความล้มเหลวแบบมีโครงสร้างที่รันไทม์มีให้ แทนที่จะอนุมานความล้มเหลวจาก ข้อความที่แสดง
• ใช้ nativeMutation เฉพาะสำหรับเครื่องมือเนทีฟที่ไม่ใช้คำจำกัดความเครื่องมือ ของ OpenClaw ระบุข้อเท็จจริงด้านการเปลี่ยนแปลงและการเล่นซ้ำที่โปรโตคอลเป็นเจ้าของไว้ที่นั่น ห้าม คัดลอกตัวจำแนกการเปลี่ยนแปลงของ OpenClaw เข้าไปในฮาร์เนส

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

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

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

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

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

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