Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

นี่คือ คู่มือผู้ร่วมพัฒนา สำหรับนักพัฒนาแกนหลักของ OpenClaw หากคุณกำลัง สร้าง Plugin ภายนอก ให้ดู การสร้าง plugins แทน สำหรับเอกสารอ้างอิงสถาปัตยกรรมเชิงลึก (โมเดลความสามารถ, ความเป็นเจ้าของ, ไปป์ไลน์การโหลด, ตัวช่วยรันไทม์) ให้ดู รายละเอียดภายในของ Plugin
ใช้สิ่งนี้เมื่อ OpenClaw ต้องการโดเมนที่ใช้ร่วมกันใหม่ เช่น การสร้างภาพ การสร้างวิดีโอ หรือพื้นที่ฟีเจอร์ในอนาคตบางอย่างที่มีผู้ขายรองรับ กฎคือ:
  • plugin = ขอบเขตความเป็นเจ้าของ
  • capability = สัญญาแกนหลักที่ใช้ร่วมกัน
อย่าเริ่มด้วยการเชื่อมต่อผู้ขายเข้ากับช่องทางหรือเครื่องมือโดยตรง ให้เริ่มจากการกำหนดความสามารถก่อน

​
เมื่อใดควรสร้างความสามารถ

สร้างความสามารถใหม่เมื่อ ทั้งหมด ต่อไปนี้เป็นจริง:
  1. มีผู้ขายมากกว่าหนึ่งรายที่อาจนำไปใช้งานได้อย่างสมเหตุสมผล
  2. ช่องทาง เครื่องมือ หรือ Plugin ฟีเจอร์ควรใช้งานโดยไม่ต้องสนใจผู้ขาย
  3. แกนหลักจำเป็นต้องเป็นเจ้าของพฤติกรรม fallback, นโยบาย, config หรือการส่งมอบ
หากงานนั้นเป็นของผู้ขายเท่านั้นและยังไม่มีสัญญาที่ใช้ร่วมกัน ให้หยุดและกำหนดสัญญาก่อน

​
ลำดับมาตรฐาน

  1. กำหนดสัญญาแกนหลักแบบมีชนิด
  2. เพิ่มการลงทะเบียน Plugin สำหรับสัญญานั้น
  3. เพิ่มตัวช่วยรันไทม์ที่ใช้ร่วมกัน
  4. เชื่อม Plugin ผู้ขายจริงหนึ่งตัวเพื่อเป็นหลักฐาน
  5. ย้ายผู้ใช้งานฟีเจอร์/ช่องทางไปใช้ตัวช่วยรันไทม์
  6. เพิ่มการทดสอบสัญญา
  7. จัดทำเอกสาร config ที่ผู้ปฏิบัติงานเห็นและโมเดลความเป็นเจ้าของ

​
อะไรอยู่ที่ไหน

แกนหลัก:
  • ชนิด request/response
  • รีจิสทรีผู้ให้บริการ + การ resolve
  • พฤติกรรม fallback
  • สคีมา config พร้อมเมทาดาทาเอกสาร title / description ที่เผยแพร่ต่อบน nested object, wildcard, array-item และ composition nodes
  • พื้นผิวตัวช่วยรันไทม์
Plugin ผู้ขาย:
  • การเรียก API ของผู้ขาย
  • การจัดการ auth ของผู้ขาย
  • การ normalize request เฉพาะผู้ขาย
  • การลงทะเบียน implementation ของความสามารถ
Plugin ฟีเจอร์/ช่องทาง:
  • เรียก api.runtime.* หรือตัวช่วย plugin-sdk/*-runtime ที่ตรงกัน
  • ห้ามเรียก implementation ของผู้ขายโดยตรง

​
รอยต่อของผู้ให้บริการและ harness

ใช้ provider hooks เมื่อพฤติกรรมเป็นของสัญญาผู้ให้บริการโมเดล ไม่ใช่ลูปเอเจนต์ทั่วไป ตัวอย่างรวมถึงพารามิเตอร์ request เฉพาะผู้ให้บริการหลังเลือก transport, การตั้งค่า auth-profile, prompt overlays และการกำหนดเส้นทาง fallback ต่อเนื่องหลัง model/profile failover ใช้ agent harness hooks เมื่อพฤติกรรมเป็นของรันไทม์ที่กำลังดำเนินการ turn Harness สามารถจัดประเภทผลลัพธ์ความพยายามที่สำเร็จแต่ใช้งานไม่ได้ เช่น คำตอบว่าง, มีแต่ reasoning หรือมีแต่ planning เพื่อให้นโยบาย fallback ของโมเดลชั้นนอกตัดสินใจ retry ได้ รักษารอยต่อทั้งสองให้แคบ:
  • แกนหลักเป็นเจ้าของนโยบาย retry/fallback
  • Plugin ผู้ให้บริการเป็นเจ้าของคำแนะนำ request/auth/routing เฉพาะผู้ให้บริการ
  • Plugin harness เป็นเจ้าของการจัดประเภทความพยายามเฉพาะรันไทม์
  • Plugin ของบุคคลที่สามส่งคืนคำแนะนำ ไม่ใช่การแก้ไขสถานะแกนหลักโดยตรง

​
เช็กลิสต์ไฟล์

สำหรับความสามารถใหม่ คาดว่าจะต้องแตะพื้นที่เหล่านี้:
  • src/<capability>/types.ts
  • src/<capability>/...registry/runtime.ts
  • src/plugins/types.ts
  • src/plugins/registry.ts
  • src/plugins/captured-registration.ts
  • src/plugins/contracts/registry.ts
  • src/plugins/runtime/types-core.ts
  • src/plugins/runtime/index.ts
  • src/plugin-sdk/<capability>.ts
  • src/plugin-sdk/<capability>-runtime.ts
  • แพ็กเกจ Plugin ที่ bundled หนึ่งรายการขึ้นไป
  • Config, เอกสาร, การทดสอบ

​
ตัวอย่างที่ทำครบแล้ว: การสร้างภาพ

การสร้างภาพทำตามรูปแบบมาตรฐาน:
  1. แกนหลักกำหนด ImageGenerationProvider
  2. แกนหลักเปิดเผย registerImageGenerationProvider(...)
  3. แกนหลักเปิดเผย runtime.imageGeneration.generate(...)
  4. Plugin openai, google, fal และ minimax ลงทะเบียน implementation ที่มีผู้ขายรองรับ
  5. ผู้ขายในอนาคตลงทะเบียนสัญญาเดียวกันได้โดยไม่ต้องเปลี่ยนช่องทาง/เครื่องมือ
คีย์ config ถูกแยกจากการกำหนดเส้นทางการวิเคราะห์ภาพโดยตั้งใจ:
  • agents.defaults.imageModel วิเคราะห์ภาพ
  • agents.defaults.imageGenerationModel สร้างภาพ
แยกสิ่งเหล่านี้ไว้เพื่อให้ fallback และนโยบายยังคงชัดเจน

​
เช็กลิสต์การตรวจทาน

ก่อนส่งความสามารถใหม่ ให้ตรวจสอบว่า:
  • ไม่มีช่องทาง/เครื่องมือใด import โค้ดผู้ขายโดยตรง
  • ตัวช่วยรันไทม์คือเส้นทางที่ใช้ร่วมกัน
  • มีการทดสอบสัญญาอย่างน้อยหนึ่งรายการที่ยืนยันความเป็นเจ้าของแบบ bundled
  • เอกสาร config ระบุชื่อโมเดล/คีย์ config ใหม่
  • เอกสาร Plugin อธิบายขอบเขตความเป็นเจ้าของ
หาก PR ข้ามชั้นความสามารถและ hardcode พฤติกรรมผู้ขายเข้าไปในช่องทาง/เครื่องมือ ให้ส่งกลับไปและกำหนดสัญญาก่อน

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