---
read_when:
    - การเพิ่มความสามารถหลักใหม่และพื้นผิวการลงทะเบียน Plugin
    - การตัดสินใจว่าโค้ดควรอยู่ในแกนหลัก, Plugin ของผู้ให้บริการ, หรือ Plugin ของฟีเจอร์
    - การเชื่อมต่อตัวช่วยรันไทม์ใหม่สำหรับช่องทางหรือเครื่องมือ
sidebarTitle: Adding capabilities
summary: คู่มือผู้ร่วมพัฒนาสำหรับการเพิ่มความสามารถที่ใช้ร่วมกันใหม่ให้กับระบบ Plugin ของ OpenClaw
title: การเพิ่มความสามารถ (คู่มือผู้ร่วมพัฒนา)
x-i18n:
    generated_at: "2026-06-27T17:50:34Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: b8a25122a7b76ff5bbb7616748d5fad2397502f9accb5428134a75d65e872034
    source_path: plugins/adding-capabilities.md
    workflow: 16
---

<Info>
  นี่คือ**คู่มือผู้มีส่วนร่วม**สำหรับนักพัฒนาแกนหลักของ OpenClaw หากคุณกำลัง
  สร้าง Plugin ภายนอก โปรดดู [การสร้าง Plugin](/th/plugins/building-plugins)
  แทน สำหรับเอกสารอ้างอิงสถาปัตยกรรมเชิงลึก (โมเดลความสามารถ ความเป็นเจ้าของ
  ไปป์ไลน์การโหลด ตัวช่วยรันไทม์) โปรดดู [ส่วนภายในของ Plugin](/th/plugins/architecture)
</Info>

ใช้แนวทางนี้เมื่อ OpenClaw ต้องการโดเมนที่ใช้ร่วมกันใหม่ เช่น embeddings การสร้างภาพ
การสร้างวิดีโอ หรือพื้นที่ฟีเจอร์ในอนาคตที่มีผู้ให้บริการรองรับ

กฎคือ:

- **Plugin** = ขอบเขตความเป็นเจ้าของ
- **ความสามารถ** = สัญญาแกนหลักที่ใช้ร่วมกัน

อย่าเริ่มด้วยการเชื่อมผู้ให้บริการเข้ากับช่องทางหรือเครื่องมือโดยตรง ให้เริ่มจากการกำหนดความสามารถก่อน

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

สร้างความสามารถใหม่เมื่อ**ทั้งหมด**ต่อไปนี้เป็นจริง:

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

หากงานนั้นเป็นเฉพาะผู้ให้บริการและยังไม่มีสัญญาที่ใช้ร่วมกัน ให้หยุดและกำหนดสัญญาก่อน

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

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

## สิ่งใดอยู่ที่ใด

**แกนหลัก:**

- ประเภทคำขอ/คำตอบ
- รีจิสทรีผู้ให้บริการ + การ resolve
- พฤติกรรม fallback
- schema การกำหนดค่าพร้อม metadata เอกสาร `title` / `description` ที่ส่งต่อบนโหนดออบเจ็กต์ซ้อน wildcard รายการอาร์เรย์ และ composition
- พื้นผิวตัวช่วยรันไทม์

**Plugin ผู้ให้บริการ:**

- การเรียก API ของผู้ให้บริการ
- การจัดการ auth ของผู้ให้บริการ
- การ normalize คำขอเฉพาะผู้ให้บริการ
- การลงทะเบียน implementation ของความสามารถ

**Plugin ฟีเจอร์/ช่องทาง:**

- เรียก `api.runtime.*` หรือตัวช่วย `plugin-sdk/*-runtime` ที่ตรงกัน
- ไม่เรียก implementation ของผู้ให้บริการโดยตรง

## Seam ของผู้ให้บริการและ harness

ใช้ **provider hooks** เมื่อพฤติกรรมเป็นของสัญญาผู้ให้บริการโมเดล ไม่ใช่ลูปเอเจนต์ทั่วไป ตัวอย่างเช่น พารามิเตอร์คำขอเฉพาะผู้ให้บริการหลังจากเลือก transport แล้ว การตั้งค่า auth-profile ที่ต้องการ prompt overlays และการกำหนดเส้นทาง fallback ต่อเนื่องหลังจาก model/profile failover

ใช้ **agent harness hooks** เมื่อพฤติกรรมเป็นของรันไทม์ที่กำลังดำเนินการ turn Harness สามารถจัดประเภทผลลัพธ์ของโปรโตคอลที่ชัดเจน เช่น เอาต์พุตว่าง reasoning ที่ไม่มีเอาต์พุตที่มองเห็นได้ หรือแผนแบบมีโครงสร้างที่ไม่มีคำตอบสุดท้าย เพื่อให้นโยบาย fallback ของโมเดลภายนอกตัดสินใจ retry ได้

รักษา seam ทั้งสองให้แคบ:

- แกนหลักเป็นเจ้าของนโยบาย retry/fallback
- Provider plugins เป็นเจ้าของคำใบ้คำขอ/auth/routing เฉพาะผู้ให้บริการ
- Harness plugins เป็นเจ้าของการจัดประเภท attempt เฉพาะรันไทม์
- 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 หนึ่งรายการขึ้นไป
- การกำหนดค่า เอกสาร การทดสอบ

## ตัวอย่างที่ทำงานจริง: การสร้างภาพ

การสร้างภาพทำตามรูปแบบมาตรฐาน:

1. แกนหลักกำหนด `ImageGenerationProvider`
2. แกนหลักเปิดเผย `registerImageGenerationProvider(...)`
3. แกนหลักเปิดเผย `runtime.imageGeneration.generate(...)`
4. Plugin `openai`, `google`, `fal` และ `minimax` ลงทะเบียน implementation ที่มีผู้ให้บริการรองรับ
5. ผู้ให้บริการในอนาคตลงทะเบียนสัญญาเดียวกันโดยไม่ต้องเปลี่ยนช่องทาง/เครื่องมือ

คีย์การกำหนดค่าถูกแยกจากการกำหนดเส้นทางการวิเคราะห์ภาพโดยเจตนา:

- `agents.defaults.imageModel` วิเคราะห์ภาพ
- `agents.defaults.imageGenerationModel` สร้างภาพ

แยกสองอย่างนี้ไว้เพื่อให้ fallback และนโยบายยังคงชัดเจน

## ผู้ให้บริการ embedding

ใช้ `embeddingProviders` สำหรับผู้ให้บริการ vector embedding ที่นำกลับมาใช้ซ้ำได้ สัญญานี้
ตั้งใจให้กว้างกว่า memory: เครื่องมือ การค้นหา retrieval ตัวนำเข้า หรือ
Plugin ฟีเจอร์ในอนาคตสามารถใช้ embeddings ได้โดยไม่ต้องขึ้นกับ memory
engine

การค้นหา memory สามารถใช้ `embeddingProviders` ทั่วไปได้ สัญญา
`memoryEmbeddingProviders` เดิมเป็นความเข้ากันได้ที่ deprecated ระหว่างที่ผู้ให้บริการเฉพาะ
memory ที่มีอยู่กำลัง migrate; ผู้ให้บริการ embedding ที่นำกลับมาใช้ซ้ำได้ใหม่ควรใช้
`embeddingProviders`

## รายการตรวจสอบการรีวิว

ก่อนส่งมอบความสามารถใหม่ ให้ตรวจสอบว่า:

- ไม่มีช่องทาง/เครื่องมือ import โค้ดผู้ให้บริการโดยตรง
- ตัวช่วยรันไทม์คือ path ที่ใช้ร่วมกัน
- มีการทดสอบสัญญาอย่างน้อยหนึ่งรายการที่ assert ความเป็นเจ้าของแบบ bundled
- เอกสารการกำหนดค่าระบุชื่อ model/config key ใหม่
- เอกสาร Plugin อธิบายขอบเขตความเป็นเจ้าของ

หาก PR ข้ามเลเยอร์ความสามารถและ hardcode พฤติกรรมผู้ให้บริการลงในช่องทาง/เครื่องมือ ให้ส่งกลับและกำหนดสัญญาก่อน

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

- [ส่วนภายในของ Plugin](/th/plugins/architecture) — โมเดลความสามารถ ความเป็นเจ้าของ ไปป์ไลน์การโหลด ตัวช่วยรันไทม์
- [การสร้าง Plugin](/th/plugins/building-plugins) — บทช่วยสอน Plugin แรก
- [ภาพรวม SDK](/th/plugins/sdk-overview) — เอกสารอ้างอิง import map และ API การลงทะเบียน
- [การสร้าง Skills](/th/tools/creating-skills) — พื้นผิวผู้มีส่วนร่วมที่ใช้ร่วมกัน