แมนิเฟสต์ของ Plugin

หน้านี้มีไว้สำหรับ แมนิเฟสต์ Plugin แบบเนทีฟของ OpenClaw เท่านั้น.

สำหรับเลย์เอาต์บันเดิลที่เข้ากันได้ โปรดดู บันเดิล Plugin.

รูปแบบบันเดิลที่เข้ากันได้ใช้ไฟล์แมนิเฟสต์ที่แตกต่างกัน:

• บันเดิล Codex: .codex-plugin/plugin.json
• บันเดิล Claude: .claude-plugin/plugin.json หรือเลย์เอาต์คอมโพเนนต์ Claude เริ่มต้น ที่ไม่มีแมนิเฟสต์
• บันเดิล Cursor: .cursor-plugin/plugin.json

OpenClaw ตรวจพบเลย์เอาต์บันเดิลเหล่านั้นโดยอัตโนมัติเช่นกัน แต่จะไม่ตรวจสอบ กับสคีมา openclaw.plugin.json ที่อธิบายไว้ที่นี่.

สำหรับบันเดิลที่เข้ากันได้ ปัจจุบัน OpenClaw อ่านเมทาดาต้าบันเดิลพร้อมราก Skills ที่ประกาศไว้ รากคำสั่ง Claude ค่าเริ่มต้น settings.json ของบันเดิล Claude, ค่าเริ่มต้น LSP ของบันเดิล Claude และชุด hook ที่รองรับเมื่อเลย์เอาต์ตรงกับ ความคาดหวังของรันไทม์ OpenClaw.

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

ดูคู่มือระบบ Plugin ฉบับเต็ม: Plugins. สำหรับโมเดลความสามารถแบบเนทีฟและคำแนะนำความเข้ากันได้ภายนอกในปัจจุบัน: โมเดลความสามารถ.

ไฟล์นี้ทำอะไร

openclaw.plugin.json คือเมทาดาต้าที่ OpenClaw อ่าน ก่อนโหลดโค้ด Plugin ของคุณ. ทุกอย่างด้านล่างต้องมีต้นทุนต่ำพอที่จะตรวจสอบได้โดยไม่ต้องบูต รันไทม์ Plugin.

ใช้สำหรับ:

• ตัวตนของ Plugin, การตรวจสอบการกำหนดค่า และคำใบ้ UI การกำหนดค่า
• เมทาดาต้า auth, onboarding และ setup (alias, auto-enable, provider env vars, auth choices)
• คำใบ้การเปิดใช้งานสำหรับพื้นผิวระนาบควบคุม
• ความเป็นเจ้าของตระกูลโมเดลแบบย่อ
• สแนปช็อตแบบคงที่ของความเป็นเจ้าของความสามารถ (contracts)
• เมทาดาต้า QA runner ที่โฮสต์ openclaw qa แบบใช้ร่วมกันสามารถตรวจสอบได้
• เมทาดาต้าการกำหนดค่าเฉพาะช่องทางที่ผสานเข้ากับแค็ตตาล็อกและพื้นผิวการตรวจสอบ

อย่าใช้สำหรับ: การลงทะเบียนพฤติกรรมรันไทม์, การประกาศ entrypoints ของโค้ด, หรือเมทาดาต้า npm install. สิ่งเหล่านั้นอยู่ในโค้ด Plugin ของคุณและ package.json.

ตัวอย่างขั้นต่ำ

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

ตัวอย่างแบบสมบูรณ์

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

อ้างอิงฟิลด์ระดับบนสุด

ข้อมูลอ้างอิงเมทาดาทาของผู้ให้บริการการสร้าง

ฟิลด์เมทาดาทาของผู้ให้บริการการสร้างอธิบายสัญญาณ auth แบบคงที่สำหรับ ผู้ให้บริการที่ประกาศในรายการ contracts.*GenerationProviders ที่ตรงกัน OpenClaw อ่านฟิลด์เหล่านี้ก่อนโหลด runtime ของผู้ให้บริการ เพื่อให้เครื่องมือหลักสามารถ ตัดสินได้ว่าผู้ให้บริการการสร้างพร้อมใช้งานหรือไม่โดยไม่ต้องนำเข้า Plugin ของผู้ให้บริการทุกตัว

ใช้ฟิลด์เหล่านี้เฉพาะกับข้อเท็จจริงเชิงประกาศที่มีต้นทุนต่ำเท่านั้น Transport, การแปลง request, การรีเฟรช token, การตรวจสอบ credential และพฤติกรรมการสร้างจริง ยังคงอยู่ใน runtime ของ Plugin

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

แต่ละรายการเมทาดาทารองรับ:

แต่ละรายการ configSignals รองรับ:

แต่ละตัวป้องกัน mode รองรับ:

แต่ละรายการ authSignals รองรับ:

แต่ละตัวป้องกัน providerBaseUrl รองรับ:

ข้อมูลอ้างอิงเมทาดาทาของเครื่องมือ

toolMetadata ใช้รูปทรง configSignals และ authSignals เดียวกับ เมทาดาทาของผู้ให้บริการการสร้าง โดยใช้ชื่อเครื่องมือเป็นคีย์ contracts.tools ประกาศ ความเป็นเจ้าของ toolMetadata ประกาศหลักฐานความพร้อมใช้งานที่มีต้นทุนต่ำ เพื่อให้ OpenClaw สามารถ หลีกเลี่ยงการนำเข้า runtime ของ Plugin เพียงเพื่อให้ factory ของเครื่องมือนั้นคืนค่า null

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

หากเครื่องมือไม่มี toolMetadata OpenClaw จะคงพฤติกรรมเดิมไว้และ โหลด Plugin เจ้าของเมื่อสัญญาเครื่องมือตรงกับ policy สำหรับเครื่องมือใน hot path ที่ factory ขึ้นอยู่กับ auth/config ผู้เขียน Plugin ควรประกาศ toolMetadata แทนการทำให้ core นำเข้า runtime เพื่อสอบถาม

ข้อมูลอ้างอิง providerAuthChoices

แต่ละรายการ providerAuthChoices อธิบายตัวเลือก onboarding หรือ auth หนึ่งรายการ OpenClaw อ่านข้อมูลนี้ก่อนโหลด runtime ของผู้ให้บริการ รายการ setup ของผู้ให้บริการใช้ตัวเลือกใน manifest เหล่านี้, ตัวเลือก setup ที่ได้จาก descriptor และเมทาดาทา install-catalog โดยไม่โหลด runtime ของผู้ให้บริการ

ข้อมูลอ้างอิง commandAliases

ใช้ commandAliases เมื่อ Plugin เป็นเจ้าของชื่อคำสั่ง runtime ที่ผู้ใช้อาจ ใส่ใน plugins.allow โดยผิดพลาด หรือพยายามรันเป็นคำสั่ง CLI ระดับ root OpenClaw ใช้ metadata นี้สำหรับการวินิจฉัยโดยไม่ import โค้ด runtime ของ Plugin

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

ข้อมูลอ้างอิง activation

ใช้ activation เมื่อ Plugin สามารถประกาศได้อย่างประหยัดว่าเหตุการณ์ control-plane ใด ควรรวม Plugin นี้ไว้ในแผน activation/load

บล็อกนี้เป็น metadata สำหรับ planner ไม่ใช่ lifecycle API บล็อกนี้ไม่ลงทะเบียน พฤติกรรม runtime ไม่แทนที่ register(...) และไม่ให้สัญญาว่า โค้ด Plugin ได้รันแล้ว activation planner ใช้ฟิลด์เหล่านี้เพื่อ จำกัด Plugin ที่เป็นผู้สมัครก่อน fallback ไปยัง metadata ความเป็นเจ้าของใน manifest ที่มีอยู่ เช่น providers, channels, commandAliases, setup.providers, contracts.tools และ hooks

ควรใช้ metadata ที่แคบที่สุดซึ่งอธิบายความเป็นเจ้าของอยู่แล้ว ใช้ providers, channels, commandAliases, ตัวอธิบาย setup หรือ contracts เมื่อฟิลด์เหล่านั้นแสดงความสัมพันธ์ได้ ใช้ activation สำหรับ hint เพิ่มเติมของ planner ที่ไม่สามารถแทนด้วยฟิลด์ความเป็นเจ้าของเหล่านั้นได้ ใช้ cliBackends ระดับบนสุดสำหรับ alias runtime ของ CLI เช่น claude-cli, my-cli หรือ google-gemini-cli; activation.onAgentHarnesses ใช้สำหรับ id ของ embedded agent harness ที่ยังไม่มีฟิลด์ความเป็นเจ้าของเท่านั้น

บล็อกนี้เป็น metadata เท่านั้น บล็อกนี้ไม่ลงทะเบียนพฤติกรรม runtime และไม่ แทนที่ register(...), setupEntry หรือ entrypoint runtime/Plugin อื่นๆ consumer ปัจจุบันใช้บล็อกนี้เป็น hint สำหรับจำกัดขอบเขตก่อนโหลด Plugin แบบกว้างขึ้น ดังนั้น metadata activation ที่ไม่ใช่ startup ซึ่งขาดหายไปโดยทั่วไปจึงมีผลแค่ด้านประสิทธิภาพเท่านั้น และ ไม่ควรเปลี่ยนความถูกต้องตราบใดที่ fallback ความเป็นเจ้าของจาก manifest ยังมีอยู่

ทุก Plugin ควรกำหนด activation.onStartup อย่างตั้งใจ ตั้งค่าเป็น true เฉพาะเมื่อ Plugin ต้องรันระหว่างการเริ่มต้น Gateway ตั้งค่าเป็น false เมื่อ Plugin ไม่ทำงานที่ startup และควรโหลดจาก trigger ที่แคบกว่าเท่านั้น การละ onStartup จะไม่ startup-load Plugin โดยปริยายอีกต่อไป ให้ใช้ metadata activation ที่ชัดเจนสำหรับ startup, channel, config, agent-harness, memory หรือ trigger activation อื่นที่แคบกว่า

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

consumer สดปัจจุบัน:

• การวางแผน startup ของ Gateway ใช้ activation.onStartup สำหรับ startup import แบบชัดเจน
• การวางแผน CLI ที่ trigger ด้วยคำสั่ง fallback ไปยัง legacy commandAliases[].cliCommand หรือ commandAliases[].name
• การวางแผน startup ของ agent-runtime ใช้ activation.onAgentHarnesses สำหรับ embedded harnesses และ cliBackends[] ระดับบนสุดสำหรับ alias runtime ของ CLI
• การวางแผน setup/channel ที่ trigger ด้วย channel fallback ไปยังความเป็นเจ้าของ legacy channels[] เมื่อ metadata activation ของ channel แบบชัดเจนขาดหายไป
• การวางแผน Plugin ตอน startup ใช้ activation.onConfigPaths สำหรับพื้นผิว config ระดับ root ที่ไม่ใช่ channel เช่นบล็อก browser ของ Plugin browser ที่ bundled มา
• การวางแผน setup/runtime ที่ trigger ด้วย Provider fallback ไปยังความเป็นเจ้าของ legacy providers[] และ cliBackends[] ระดับบนสุด เมื่อ metadata activation ของ Provider แบบชัดเจน ขาดหายไป

การวินิจฉัยของ planner สามารถแยก hint activation แบบชัดเจนออกจาก fallback ความเป็นเจ้าของใน manifest ได้ ตัวอย่างเช่น activation-command-hint หมายถึง activation.onCommands ตรงกัน ขณะที่ manifest-command-alias หมายถึง planner ใช้ความเป็นเจ้าของ commandAliases แทน ป้ายเหตุผลเหล่านี้มีไว้สำหรับ การวินิจฉัยและการทดสอบของ host; ผู้เขียน Plugin ควรประกาศ metadata ที่อธิบายความเป็นเจ้าของได้ดีที่สุดต่อไป

ข้อมูลอ้างอิง qaRunners

ใช้ qaRunners เมื่อ Plugin เพิ่ม transport runner หนึ่งรายการขึ้นไปไว้ใต้ root openclaw qa ที่ใช้ร่วมกัน รักษา metadata นี้ให้ประหยัดและเป็น static; runtime ของ Plugin ยังคงเป็นเจ้าของการลงทะเบียน CLI จริงผ่านพื้นผิว runtime-api.ts แบบเบาที่ export qaRunnerCliRegistrations

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

ข้อมูลอ้างอิง setup

ใช้ setup เมื่อพื้นผิวการตั้งค่าและการเริ่มใช้งานต้องการเมทาดาทาราคาถูกที่ Plugin เป็นเจ้าของก่อนที่รันไทม์จะโหลด

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

cliBackends ระดับบนสุดยังคงใช้ได้และยังอธิบายแบ็กเอนด์การอนุมานของ CLI ต่อไป setup.cliBackends คือพื้นผิวดีสคริปเตอร์เฉพาะการตั้งค่าสำหรับโฟลว์ control-plane/setup ที่ควรคงเป็นเมทาดาทาเท่านั้น

เมื่อมี setup.providers และ setup.cliBackends จะเป็นพื้นผิวการค้นหาแบบดีสคริปเตอร์ก่อนที่แนะนำสำหรับการค้นพบการตั้งค่า หากดีสคริปเตอร์เพียงจำกัด Plugin ตัวเลือกให้แคบลง และการตั้งค่ายังต้องใช้ฮุกของรันไทม์ในช่วงตั้งค่าที่สมบูรณ์กว่า ให้ตั้ง requiresRuntime: true และคง setup-api ไว้เป็นเส้นทางการทำงานสำรอง

OpenClaw ยังรวม setup.providers[].envVars ไว้ในการค้นหาการยืนยันตัวตนผู้ให้บริการทั่วไปและการค้นหา env-var ด้วย providerAuthEnvVars ยังคงรองรับผ่านอะแดปเตอร์ความเข้ากันได้ระหว่างช่วงเลิกใช้ แต่ Plugin ที่ไม่ถูกบันเดิลซึ่งยังใช้อยู่จะได้รับการวินิจฉัย manifest Plugin ใหม่ควรวางเมทาดาทา env ของการตั้งค่า/สถานะไว้ที่ setup.providers[].envVars

OpenClaw ยังสามารถอนุมานตัวเลือกการตั้งค่าง่าย ๆ จาก setup.providers[].authMethods เมื่อไม่มีรายการการตั้งค่า หรือเมื่อ setup.requiresRuntime: false ประกาศว่าไม่จำเป็นต้องใช้รันไทม์การตั้งค่า รายการ providerAuthChoices แบบชัดเจนยังคงเป็นตัวเลือกที่แนะนำสำหรับป้ายกำกับแบบกำหนดเอง แฟล็ก CLI ขอบเขตการเริ่มใช้งาน และเมทาดาทาของผู้ช่วย

ตั้ง requiresRuntime: false เฉพาะเมื่อดีสคริปเตอร์เหล่านั้นเพียงพอสำหรับพื้นผิวการตั้งค่า OpenClaw ถือค่า false แบบชัดเจนเป็นสัญญาแบบดีสคริปเตอร์เท่านั้น และจะไม่เรียกใช้ setup-api หรือ openclaw.setupEntry สำหรับการค้นหาการตั้งค่า หาก Plugin แบบดีสคริปเตอร์เท่านั้นยังส่งรายการรันไทม์การตั้งค่าอย่างใดอย่างหนึ่งเหล่านั้นมาด้วย OpenClaw จะรายงานการวินิจฉัยแบบเพิ่มเติมและยังคงเพิกเฉยต่อรายการนั้น การละ requiresRuntime ไว้จะคงพฤติกรรมสำรองแบบเดิมไว้ เพื่อไม่ให้ Plugin ที่มีอยู่ซึ่งเพิ่มดีสคริปเตอร์โดยไม่มีแฟล็กเสียหาย

เนื่องจากการค้นหาการตั้งค่าสามารถเรียกใช้โค้ด setup-api ที่ Plugin เป็นเจ้าของได้ ค่า setup.providers[].id และ setup.cliBackends[] ที่ทำให้เป็นรูปแบบปกติแล้วต้องไม่ซ้ำกันในทุก Plugin ที่ค้นพบ ความเป็นเจ้าของที่กำกวมจะล้มเหลวแบบปิดแทนที่จะเลือกผู้ชนะจากลำดับการค้นพบ

เมื่อรันไทม์การตั้งค่าถูกเรียกใช้จริง การวินิจฉัยรีจิสทรีการตั้งค่าจะรายงานความคลาดเคลื่อนของดีสคริปเตอร์ หาก setup-api ลงทะเบียนผู้ให้บริการหรือแบ็กเอนด์ CLI ที่ดีสคริปเตอร์ manifest ไม่ได้ประกาศ หรือหากดีสคริปเตอร์ไม่มีการลงทะเบียนรันไทม์ที่ตรงกัน การวินิจฉัยเหล่านี้เป็นแบบเพิ่มเติมและไม่ปฏิเสธ Plugin เดิม

ข้อมูลอ้างอิง setup.providers

authEvidence มีไว้สำหรับ marker ข้อมูลประจำตัวในเครื่องที่ผู้ให้บริการเป็นเจ้าของ ซึ่งสามารถตรวจสอบได้โดยไม่ต้องโหลดโค้ดรันไทม์ การตรวจสอบเหล่านี้ต้องยังคงราคาถูกและอยู่ในเครื่อง: ไม่มีการเรียกเครือข่าย ไม่มีการอ่าน keychain หรือตัวจัดการความลับ ไม่มีคำสั่ง shell และไม่มีการ probe API ของผู้ให้บริการ

รายการหลักฐานที่รองรับ:

ฟิลด์ setup

ข้อมูลอ้างอิง uiHints

uiHints คือแผนที่จากชื่อฟิลด์ config ไปยังคำใบ้การเรนเดอร์ขนาดเล็ก

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

คำใบ้ของแต่ละฟิลด์สามารถมี:

ข้อมูลอ้างอิง contracts

ใช้ contracts เฉพาะสำหรับเมทาดาทาความเป็นเจ้าของ capability แบบสแตติกที่ OpenClaw สามารถอ่านได้โดยไม่ต้องนำเข้ารันไทม์ของ Plugin

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

แต่ละรายการเป็นแบบไม่บังคับ:

contracts.embeddedExtensionFactories ถูกเก็บไว้สำหรับ extension factory แบบเฉพาะ app-server ของ Codex ที่บันเดิลมาด้วยเท่านั้น การแปลงผลลัพธ์เครื่องมือที่บันเดิลมาด้วยควร ประกาศ contracts.agentToolResultMiddleware และลงทะเบียนด้วย api.registerAgentToolResultMiddleware(...) แทน Plugin ที่ติดตั้งแล้วอาจใช้ จุดเชื่อมมิดเดิลแวร์เดียวกันได้เฉพาะเมื่อเปิดใช้อย่างชัดเจน และเฉพาะสำหรับรันไทม์ที่ ประกาศไว้ใน contracts.agentToolResultMiddleware เท่านั้น

Plugin ที่ติดตั้งแล้วซึ่งต้องใช้ชั้นนโยบายก่อนใช้เครื่องมือที่โฮสต์เชื่อถือ ต้องประกาศ id โลคัลแต่ละรายการที่ลงทะเบียนไว้ใน contracts.trustedToolPolicies และต้องถูกเปิดใช้อย่างชัดเจน Plugin ที่บันเดิลมาด้วยยังคงใช้เส้นทาง trusted-policy เดิม แต่ Plugin ที่ติดตั้งแล้ว ซึ่งมี id นโยบายที่ไม่ได้ประกาศจะถูกปฏิเสธก่อนการลงทะเบียน id ของนโยบาย ถูกจำกัดขอบเขตไว้กับ Plugin ที่ลงทะเบียน ดังนั้น Plugin สองตัวอาจประกาศและ ลงทะเบียน workflow-budget ได้ทั้งคู่ แต่ Plugin ตัวเดียวกันไม่สามารถลงทะเบียน id โลคัลเดียวกัน ซ้ำสองครั้งได้

การลงทะเบียน api.registerTool(...) ของรันไทม์ต้องตรงกับ contracts.tools การค้นหาเครื่องมือใช้รายการนี้เพื่อโหลดเฉพาะรันไทม์ของ Plugin ที่สามารถเป็นเจ้าของ เครื่องมือที่ร้องขอได้

Plugin ผู้ให้บริการที่ implement resolveExternalAuthProfiles ควรประกาศ contracts.externalAuthProviders; ฮุก external-auth ที่ไม่ได้ประกาศจะถูกละเว้น

ผู้ให้บริการ embedding ทั่วไปควรประกาศ contracts.embeddingProviders สำหรับ แต่ละ adapter ที่ลงทะเบียนด้วย api.registerEmbeddingProvider(...) ใช้ สัญญาทั่วไปสำหรับการสร้างเวกเตอร์ที่ใช้ซ้ำได้ รวมถึงผู้ให้บริการที่ถูกใช้โดย การค้นหาหน่วยความจำ contracts.memoryEmbeddingProviders เป็นความเข้ากันได้ เฉพาะหน่วยความจำที่เลิกใช้แล้ว และยังคงอยู่เฉพาะระหว่างที่ผู้ให้บริการเดิมย้าย ไปยังจุดเชื่อมผู้ให้บริการ embedding แบบทั่วไป

ปัจจุบัน contracts.gatewayMethodDispatch รับ "authenticated-request" ได้ เป็นด่านสุขอนามัยของ API สำหรับเส้นทาง HTTP ของ Plugin แบบเนทีฟที่ตั้งใจ dispatch เมธอด control-plane ของ Gateway ภายในกระบวนการ ไม่ใช่ sandbox สำหรับป้องกัน Plugin เนทีฟที่เป็นอันตราย ใช้เฉพาะกับพื้นผิว ที่บันเดิลมาด้วยหรือสำหรับโอเปอเรเตอร์ซึ่งผ่านการตรวจทานอย่างเข้มงวด และต้องใช้การยืนยันตัวตน HTTP ของ Gateway อยู่แล้ว

อ้างอิง mediaUnderstandingProviderMetadata

ใช้ mediaUnderstandingProviderMetadata เมื่อผู้ให้บริการทำความเข้าใจสื่อมี โมเดลเริ่มต้น ลำดับความสำคัญของ fallback การยืนยันตัวตนอัตโนมัติ หรือการรองรับเอกสารเนทีฟที่ ตัวช่วยทั่วไปของ core ต้องใช้ก่อนโหลดรันไทม์ คีย์ต้องถูกประกาศใน contracts.mediaUnderstandingProviders ด้วย

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"]    }  }}

แต่ละรายการผู้ให้บริการสามารถมี:

อ้างอิง channelConfigs

ใช้ channelConfigs เมื่อ Plugin ช่องทางต้องใช้ metadata ของ config ที่มีต้นทุนต่ำก่อน โหลดรันไทม์ การค้นหาการตั้งค่า/สถานะแบบอ่านอย่างเดียวของช่องทางสามารถใช้ metadata นี้ โดยตรงสำหรับช่องทางภายนอกที่กำหนดค่าไว้เมื่อไม่มีรายการตั้งค่าให้ใช้ หรือ เมื่อ setup.requiresRuntime: false ประกาศว่าไม่จำเป็นต้องมีรันไทม์สำหรับการตั้งค่า

channelConfigs เป็น metadata ใน manifest ของ Plugin ไม่ใช่ส่วน config ผู้ใช้ระดับบนสุด ส่วนใหม่ ผู้ใช้ยังคงกำหนดค่าอินสแตนซ์ช่องทางภายใต้ channels.<channel-id> OpenClaw อ่าน metadata ใน manifest เพื่อตัดสินว่า Plugin ใดเป็นเจ้าของช่องทาง ที่กำหนดค่าไว้นั้น ก่อนที่โค้ดรันไทม์ของ Plugin จะทำงาน

สำหรับ Plugin ช่องทาง configSchema และ channelConfigs อธิบายเส้นทางที่ต่างกัน:

• configSchema ตรวจสอบ plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema ตรวจสอบ channels.<channel-id>

Plugin ที่ไม่ได้บันเดิลมาด้วยซึ่งประกาศ channels[] ควรประกาศรายการ channelConfigs ที่ตรงกันด้วย หากไม่มี OpenClaw ยังสามารถโหลด Plugin ได้ แต่ schema ของ config ในเส้นทาง cold-path, การตั้งค่า, และพื้นผิว Control UI จะไม่สามารถรู้ รูปร่างตัวเลือกที่ช่องทางเป็นเจ้าของได้จนกว่ารันไทม์ของ Plugin จะทำงาน

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled และ nativeSkillsAutoEnabled สามารถประกาศค่าเริ่มต้น auto แบบสแตติกสำหรับการตรวจสอบ config คำสั่ง ที่ทำงานก่อนโหลดรันไทม์ของช่องทาง ช่องทางที่บันเดิลมาด้วยยังสามารถเผยแพร่ ค่าเริ่มต้นเดียวกันผ่าน package.json#openclaw.channel.commands ควบคู่กับ metadata แค็ตตาล็อกช่องทางอื่น ๆ ที่ package เป็นเจ้าของได้

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

แต่ละรายการช่องทางสามารถมี:

การแทนที่ Plugin ช่องทางอื่น

ใช้ preferOver เมื่อ Plugin ของคุณเป็นเจ้าของที่ต้องการสำหรับ id ช่องทางที่ Plugin อื่นก็สามารถให้ได้เช่นกัน กรณีทั่วไปคือ id ของ Plugin ที่เปลี่ยนชื่อ, Plugin แบบสแตนด์อโลนที่มาแทน Plugin ที่บันเดิลมาด้วย, หรือ fork ที่มีการดูแลต่อ ซึ่งคง id ช่องทางเดิมไว้เพื่อความเข้ากันได้ของ config

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

เมื่อกำหนดค่า channels.chat แล้ว OpenClaw จะพิจารณาทั้ง id ช่องทางและ id ของ Plugin ที่ต้องการ หาก Plugin ที่มีลำดับความสำคัญต่ำกว่าถูกเลือกเพียงเพราะ เป็น Plugin ที่บันเดิลมาด้วยหรือถูกเปิดใช้โดยค่าเริ่มต้น OpenClaw จะปิดใช้งานใน config รันไทม์ที่มีผล เพื่อให้ Plugin เดียวเป็นเจ้าของช่องทางและเครื่องมือของช่องทางนั้น การเลือกของผู้ใช้ที่ชัดเจนยังคงมีผลเหนือกว่า: หากผู้ใช้เปิดใช้ Plugin ทั้งสองอย่างชัดเจน OpenClaw จะรักษาตัวเลือกนั้นไว้และรายงานการวินิจฉัยช่องทาง/เครื่องมือซ้ำ แทนที่จะ เปลี่ยนชุด Plugin ที่ร้องขอแบบเงียบ ๆ

จำกัดขอบเขต preferOver ไว้กับ id ของ Plugin ที่สามารถให้ช่องทางเดียวกันได้จริง ไม่ใช่ฟิลด์ลำดับความสำคัญทั่วไป และไม่ได้เปลี่ยนชื่อคีย์ config ของผู้ใช้

อ้างอิง modelSupport

ใช้ modelSupport เมื่อ OpenClaw ควรอนุมาน provider plugin ของคุณจาก รหัสโมเดลแบบย่อ เช่น gpt-5.5 หรือ claude-sonnet-4.6 ก่อนที่ plugin runtime จะโหลด

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw ใช้ลำดับความสำคัญนี้:

• การอ้างอิง provider/model แบบชัดเจนจะใช้เมทาดาทา manifest ของ providers ที่เป็นเจ้าของ
• modelPatterns มีลำดับเหนือกว่า modelPrefixes
• หาก plugin ที่ไม่ถูกบันเดิลหนึ่งตัวและ plugin ที่ถูกบันเดิลหนึ่งตัวตรงกันทั้งคู่ plugin ที่ไม่ถูกบันเดิลจะชนะ
• ความกำกวมที่เหลือจะถูกละเว้นจนกว่าผู้ใช้หรือ config จะระบุ provider

ฟิลด์:

รายการ modelPatterns จะถูกคอมไพล์ผ่าน compileSafeRegex ซึ่งปฏิเสธ แพตเทิร์นที่มีการทำซ้ำแบบซ้อนกัน (เช่น (a+)+$) แพตเทิร์นที่ไม่ผ่าน การตรวจสอบความปลอดภัยจะถูกข้ามอย่างเงียบ ๆ เช่นเดียวกับ regex ที่ไวยากรณ์ไม่ถูกต้อง ให้ใช้แพตเทิร์นที่เรียบง่ายและหลีกเลี่ยง quantifier แบบซ้อนกัน

อ้างอิง modelCatalog

ใช้ modelCatalog เมื่อ OpenClaw ควรรู้เมทาดาทาโมเดลของ provider ก่อน โหลด plugin runtime นี่คือแหล่งที่เป็นของ manifest สำหรับแถวแค็ตตาล็อกแบบคงที่, นามแฝงของ provider, กฎการระงับ และโหมดการค้นพบ การรีเฟรช runtime ยังคงเป็นหน้าที่ของโค้ด provider runtime แต่ manifest จะบอก core ว่าเมื่อใดต้องใช้ runtime

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

ฟิลด์ระดับบนสุด:

aliases มีส่วนร่วมในการค้นหาความเป็นเจ้าของของ provider สำหรับการวางแผน model-catalog เป้าหมายของนามแฝงต้องเป็น provider ระดับบนสุดที่ plugin เดียวกันเป็นเจ้าของ เมื่อรายการ ที่กรองด้วย provider ใช้นามแฝง OpenClaw จะอ่าน manifest ของเจ้าของและ ใช้การ override API/base URL ของนามแฝงได้โดยไม่ต้องโหลด provider runtime นามแฝงจะไม่ขยายรายการแค็ตตาล็อกที่ไม่ได้กรอง รายการแบบกว้างจะแสดงเฉพาะแถว ของ provider canonical ที่เป็นเจ้าของเท่านั้น

suppressions แทนที่ hook suppressBuiltInModel ของ provider runtime แบบเก่า รายการการระงับจะมีผลเฉพาะเมื่อ provider เป็นของ plugin หรือ ประกาศเป็นคีย์ modelCatalog.aliases ที่ชี้ไปยัง provider ที่เป็นเจ้าของเท่านั้น hook การระงับ ของ runtime จะไม่ถูกเรียกอีกต่อไประหว่างการ resolve โมเดล

ฟิลด์ของ provider:

ฟิลด์ของโมเดล:

ฟิลด์การระงับ:

อย่าใส่ข้อมูลที่มีเฉพาะ runtime ใน modelCatalog ใช้ static เฉพาะเมื่อแถวใน manifest สมบูรณ์พอให้พื้นผิวรายการที่กรองด้วย provider และตัวเลือกข้าม การค้นพบ registry/runtime ได้ ใช้ refreshable เมื่อแถวใน manifest มีประโยชน์ ในฐานะ seed หรือส่วนเสริมที่แสดงเป็นรายการได้ แต่ refresh/cache สามารถเพิ่มแถวเพิ่มเติมภายหลังได้ แถวแบบ refreshable ไม่ถือเป็นแหล่งอ้างอิงที่เด็ดขาดด้วยตัวเอง ใช้ runtime เมื่อ OpenClaw ต้องโหลด provider runtime เพื่อทราบรายการ

อ้างอิง modelIdNormalization

ใช้ modelIdNormalization สำหรับการทำความสะอาด model-id ที่ provider เป็นเจ้าของแบบต้นทุนต่ำ ซึ่งต้อง เกิดขึ้นก่อน provider runtime โหลด สิ่งนี้เก็บนามแฝง เช่น ชื่อโมเดลแบบสั้น, รหัส legacy ภายใน provider และกฎคำนำหน้า proxy ไว้ใน manifest ของ plugin เจ้าของ แทนที่จะอยู่ในตารางการเลือกโมเดลของ core

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

ฟิลด์ของ provider:

อ้างอิง providerEndpoints

ใช้ providerEndpoints สำหรับการจำแนก endpoint ที่นโยบายคำขอทั่วไป ต้องรู้ก่อน provider runtime โหลด Core ยังคงเป็นเจ้าของความหมายของแต่ละ endpointClass; plugin manifest เป็นเจ้าของเมทาดาทา host และ base URL

ฟิลด์ของ Endpoint:

เอกสารอ้างอิง providerRequest

ใช้ providerRequest สำหรับเมตาดาต้าความเข้ากันได้ของคำขอที่มีต้นทุนต่ำ ซึ่งนโยบายคำขอทั่วไปต้องใช้โดยไม่ต้องโหลด runtime ของผู้ให้บริการ เก็บการเขียน payload ใหม่ที่เฉพาะเจาะจงกับพฤติกรรมไว้ใน hook runtime ของผู้ให้บริการหรือ helper ของกลุ่มผู้ให้บริการที่ใช้ร่วมกัน

{  "providers": ["vllm"],  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

ฟิลด์ของผู้ให้บริการ:

เอกสารอ้างอิง secretProviderIntegrations

ใช้ secretProviderIntegrations เมื่อ Plugin สามารถเผยแพร่พรีเซ็ตผู้ให้บริการ exec ของ SecretRef ที่นำกลับมาใช้ซ้ำได้ OpenClaw อ่านเมตาดาต้านี้ก่อนที่ runtime ของ Plugin จะโหลด เก็บความเป็นเจ้าของของ Plugin ไว้ใน secrets.providers.<alias>.pluginIntegration และปล่อยให้การ resolve secret จริงเป็นหน้าที่ของ runtime ของ SecretRef พรีเซ็ตจะเปิดเผยเฉพาะสำหรับ Plugin ที่ bundled และ Plugin ที่ติดตั้งซึ่งค้นพบจากรากการติดตั้ง Plugin ที่จัดการไว้ เช่น การติดตั้งจาก git และ ClawHub

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

คีย์ของแมปคือ id ของการผสานรวม หากละ providerAlias ไว้ OpenClaw จะใช้ id ของการผสานรวมเป็น alias ของผู้ให้บริการ SecretRef alias ของผู้ให้บริการต้องตรงกับรูปแบบ alias ผู้ให้บริการ SecretRef ปกติ เช่น team-secrets หรือ onepassword-work

เมื่อ operator เลือกพรีเซ็ต OpenClaw จะเขียนการอ้างอิงผู้ให้บริการเช่น:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

เมื่อเริ่มต้นหรือโหลดซ้ำ OpenClaw จะ resolve ผู้ให้บริการนั้นโดยโหลดเมตาดาต้า manifest ของ Plugin ปัจจุบัน ตรวจสอบว่า Plugin เจ้าของติดตั้งและใช้งานอยู่ แล้วสร้างคำสั่ง exec จาก manifest การปิดใช้งานหรือลบ Plugin จะเพิกถอนผู้ให้บริการสำหรับ SecretRefs ที่ใช้งานอยู่ operator ที่ต้องการการกำหนดค่า exec แบบ standalone ยังสามารถเขียนผู้ให้บริการ command/args แบบแมนนวลได้โดยตรง

ปัจจุบันรองรับเฉพาะพรีเซ็ต source: "exec" เท่านั้น command ต้องเป็น ${node} และ args[0] ต้องเป็นสคริปต์ resolver แบบสัมพันธ์กับรากของ Plugin ที่ขึ้นต้นด้วย ./ OpenClaw จะ materialize ในตอนเริ่มต้นหรือโหลดซ้ำให้เป็นไฟล์ปฏิบัติการ Node ปัจจุบันและพาธสคริปต์แบบสัมบูรณ์ภายใน Plugin ตัวเลือก Node เช่น --require, --import, --loader, --env-file, --eval และ --print ไม่ได้เป็นส่วนหนึ่งของสัญญาพรีเซ็ต manifest operator ที่ต้องใช้คำสั่งที่ไม่ใช่ Node สามารถกำหนดค่าผู้ให้บริการ exec แบบแมนนวล standalone ได้โดยตรง

OpenClaw อนุมาน trustedDirs สำหรับพรีเซ็ต manifest จากรากของ Plugin และสำหรับพรีเซ็ต ${node} จะรวมไดเรกทอรีของไฟล์ปฏิบัติการ Node ปัจจุบันด้วย trustedDirs ที่เขียนใน manifest จะถูกละเว้น ตัวเลือกผู้ให้บริการ exec อื่น ๆ เช่น timeoutMs, maxOutputBytes, jsonOnly, env, passEnv และ allowInsecurePath จะส่งผ่านไปยังการกำหนดค่าผู้ให้บริการ exec ของ SecretRef ปกติ

เอกสารอ้างอิง modelPricing

ใช้ modelPricing เมื่อผู้ให้บริการต้องการพฤติกรรม pricing ของ control-plane ก่อนที่ runtime จะโหลด แคช pricing ของ Gateway อ่านเมตาดาต้านี้โดยไม่ต้อง import โค้ด runtime ของผู้ให้บริการ

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

ฟิลด์ของผู้ให้บริการ:

ฟิลด์ของแหล่งข้อมูล:

OpenClaw Provider Index

OpenClaw Provider Index คือเมตาดาต้า preview ที่ OpenClaw เป็นเจ้าของสำหรับผู้ให้บริการที่ Plugin ของผู้ให้บริการนั้นอาจยังไม่ได้ติดตั้ง ยังไม่ใช่ส่วนหนึ่งของ manifest ของ Plugin manifest ของ Plugin ยังคงเป็นแหล่งอำนาจของ Plugin ที่ติดตั้งแล้ว Provider Index คือสัญญา fallback ภายในที่พื้นผิวสำหรับผู้ให้บริการที่ติดตั้งได้ในอนาคตและตัวเลือกโมเดลก่อนติดตั้งจะใช้เมื่อ Plugin ของผู้ให้บริการยังไม่ได้ติดตั้ง

ลำดับอำนาจของ catalog:

1. การกำหนดค่าของผู้ใช้
2. modelCatalog ใน manifest ของ Plugin ที่ติดตั้งแล้ว
3. แคช catalog โมเดลจากการ refresh อย่างชัดเจน
4. แถว preview ของ OpenClaw Provider Index

Provider Index ต้องไม่มี secret, สถานะ enabled, hook runtime หรือข้อมูลโมเดลที่เฉพาะกับบัญชีแบบ live catalog preview ของมันใช้ shape แถวผู้ให้บริการ modelCatalog เดียวกับ manifest ของ Plugin แต่ควรจำกัดไว้ที่เมตาดาต้าการแสดงผลที่เสถียร เว้นแต่ฟิลด์ adapter runtime เช่น api, baseUrl, pricing หรือแฟล็กความเข้ากันได้จะถูกตั้งใจให้สอดคล้องกับ manifest ของ Plugin ที่ติดตั้งแล้ว ผู้ให้บริการที่มีการค้นพบ /models แบบ live ควรเขียนแถวที่ refresh แล้วผ่านพาธแคช catalog โมเดลแบบชัดเจน แทนที่จะให้การ list ปกติหรือ onboarding เรียก API ของผู้ให้บริการ

รายการใน Provider Index อาจมีเมตาดาต้า Plugin ที่ติดตั้งได้สำหรับผู้ให้บริการที่ Plugin ย้ายออกจาก core แล้วหรือยังไม่ได้ติดตั้งด้วย เมตาดาต้านี้สะท้อนรูปแบบ catalog ของ channel: ชื่อแพ็กเกจ, npm install spec, integrity ที่คาดหวัง และป้ายกำกับตัวเลือก auth ที่ต้นทุนต่ำก็เพียงพอสำหรับแสดงตัวเลือก setup ที่ติดตั้งได้ เมื่อ Plugin ติดตั้งแล้ว manifest ของมันจะชนะ และรายการ Provider Index จะถูกละเว้นสำหรับผู้ให้บริการนั้น

คีย์ capability ระดับบนสุดแบบ legacy ถูกเลิกใช้แล้ว ใช้ openclaw doctor --fix เพื่อย้าย speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders และ webSearchProviders ไปไว้ใต้ contracts; การโหลด manifest ปกติจะไม่ถือว่าฟิลด์ระดับบนสุดเหล่านั้นเป็นความเป็นเจ้าของ capability อีกต่อไป

Manifest เทียบกับ package.json

สองไฟล์นี้ทำหน้าที่ต่างกัน:

หากไม่แน่ใจว่าเมตาดาต้าชิ้นหนึ่งควรอยู่ที่ไหน ให้ใช้กฎนี้:

• หาก OpenClaw ต้องรู้ก่อนโหลดโค้ด Plugin ให้ใส่ไว้ใน openclaw.plugin.json
• หากเกี่ยวกับ packaging, ไฟล์ entry หรือพฤติกรรมการติดตั้ง npm ให้ใส่ไว้ใน package.json

ฟิลด์ package.json ที่ส่งผลต่อการค้นพบ

เมตาดาต้า Plugin บางส่วนก่อน runtime ตั้งใจให้อยู่ใน package.json ใต้บล็อก openclaw แทนที่จะอยู่ใน openclaw.plugin.json openclaw.bundle และ openclaw.bundle.json ไม่ใช่สัญญา Plugin ของ OpenClaw; Plugin แบบ native ต้องใช้ openclaw.plugin.json ร่วมกับฟิลด์ package.json#openclaw ที่รองรับด้านล่าง

ตัวอย่างสำคัญ:

เมตาดาทา manifest ตัดสินว่าตัวเลือก provider/channel/setup ใดจะแสดงใน onboarding ก่อนที่รันไทม์จะโหลด package.json#openclaw.install บอก onboarding ว่าจะดึงหรือเปิดใช้ Plugin นั้นอย่างไรเมื่อผู้ใช้เลือกหนึ่งใน ตัวเลือกเหล่านั้น อย่าย้ายคำใบ้การติดตั้งไปไว้ใน openclaw.plugin.json

openclaw.install.minHostVersion ถูกบังคับใช้ระหว่างการติดตั้งและการโหลด registry ของ manifest สำหรับแหล่ง Plugin ที่ไม่ใช่ bundled ค่าที่ไม่ถูกต้องจะถูกปฏิเสธ; ค่าที่ใหม่กว่าแต่ถูกต้องจะข้าม Plugin ภายนอกบนโฮสต์รุ่นเก่า Plugin source แบบ bundled ถือว่า co-versioned กับ checkout ของโฮสต์

openclaw.install.requiredPlatformPackages ใช้สำหรับแพ็กเกจ npm ที่เปิดเผย ไบนารีเนทีฟที่จำเป็นผ่าน alias แบบ optional และเฉพาะแพลตฟอร์ม ระบุชื่อ แพ็กเกจ npm แบบ bare สำหรับทุก alias แพลตฟอร์มที่รองรับ ระหว่างการติดตั้ง npm, OpenClaw จะตรวจสอบเฉพาะ alias ที่ประกาศซึ่งข้อจำกัดใน lockfile ตรงกับ โฮสต์ปัจจุบัน หาก npm รายงานว่าสำเร็จแต่ละเว้น alias นั้น OpenClaw จะลองอีกครั้งหนึ่ง ด้วย cache ใหม่และ rollback การติดตั้งหาก alias ยังขาดอยู่

openclaw.compat.pluginApi ถูกบังคับใช้ระหว่างการติดตั้งแพ็กเกจสำหรับแหล่ง Plugin ที่ไม่ใช่ bundled ใช้ค่านี้สำหรับ floor ของ API ของ SDK/รันไทม์ Plugin OpenClaw ที่ แพ็กเกจถูก build มาด้วย ค่านี้อาจเข้มงวดกว่า minHostVersion ได้เมื่อ แพ็กเกจ Plugin ต้องการ API ที่ใหม่กว่าแต่ยังคงคำใบ้การติดตั้งที่ต่ำกว่าสำหรับ flow อื่น การซิงก์ release อย่างเป็นทางการของ OpenClaw จะ bump floor ของ API ของ Plugin อย่างเป็นทางการที่มีอยู่ เป็นเวอร์ชัน release ของ OpenClaw โดยค่าเริ่มต้น แต่ release เฉพาะ Plugin สามารถคง floor ที่ต่ำกว่าได้เมื่อแพ็กเกจตั้งใจรองรับโฮสต์รุ่นเก่า อย่าใช้ เวอร์ชันแพ็กเกจเพียงอย่างเดียวเป็นสัญญาความเข้ากันได้ peerDependencies.openclaw ยังคงเป็นเมตาดาทาแพ็กเกจ npm; OpenClaw ใช้สัญญา openclaw.compat.pluginApi สำหรับการตัดสินใจความเข้ากันได้ของการติดตั้ง

เมตาดาทา install-on-demand อย่างเป็นทางการควรใช้ clawhubSpec เมื่อ Plugin เผยแพร่บน ClawHub; onboarding จะถือค่านี้เป็นแหล่ง remote ที่ต้องการและ บันทึกข้อเท็จจริง artifact ของ ClawHub หลังการติดตั้ง npmSpec ยังคงเป็น fallback ด้านความเข้ากันได้สำหรับแพ็กเกจที่ยังไม่ได้ย้ายไป ClawHub

การ pin เวอร์ชัน npm แบบ exact อยู่ใน npmSpec แล้ว เช่น "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3" รายการแค็ตตาล็อกภายนอกอย่างเป็นทางการ ควรจับคู่ spec แบบ exact กับ expectedIntegrity เพื่อให้ flow การอัปเดต fail closed หาก artifact npm ที่ดึงมาไม่ตรงกับ release ที่ pin ไว้อีกต่อไป onboarding แบบ interactive ยังคงเสนอ spec ของ npm registry ที่เชื่อถือได้ รวมถึงชื่อ แพ็กเกจแบบ bare และ dist-tag เพื่อความเข้ากันได้ การวินิจฉัยแค็ตตาล็อกสามารถ แยกแยะระหว่างแหล่งแบบ exact, floating, integrity-pinned, missing-integrity, package-name mismatch และ default-choice ที่ไม่ถูกต้องได้ นอกจากนี้ยังเตือนเมื่อ มี expectedIntegrity แต่ไม่มีแหล่ง npm ที่ถูกต้องซึ่งสามารถ pin ค่านั้นได้ เมื่อมี expectedIntegrity, flow การติดตั้ง/อัปเดตจะบังคับใช้ค่านี้; เมื่อไม่มีค่านี้ การ resolve registry จะถูก บันทึกโดยไม่มี integrity pin

Plugin channel ควรมี openclaw.setupEntry เมื่อการสแกนสถานะ, รายการ channel หรือ SecretRef จำเป็นต้องระบุบัญชีที่กำหนดค่าแล้วโดยไม่โหลดรันไทม์ทั้งหมด entry การตั้งค่าควรเปิดเผยเมตาดาทา channel พร้อม adapter สำหรับ config, สถานะ และ secrets ที่ปลอดภัยสำหรับการตั้งค่า; เก็บ network client, listener ของ Gateway และ รันไทม์ transport ไว้ใน entrypoint หลักของ extension

ฟิลด์ entrypoint ของรันไทม์ไม่ได้ override การตรวจสอบขอบเขตแพ็กเกจสำหรับฟิลด์ entrypoint ของ source ตัวอย่างเช่น openclaw.runtimeExtensions ไม่สามารถทำให้ path openclaw.extensions ที่หลุดออกนอกขอบเขตโหลดได้

openclaw.install.allowInvalidConfigRecovery มีขอบเขตแคบโดยเจตนา ค่านี้ไม่ได้ ทำให้ config ที่เสียโดยอำเภอใจติดตั้งได้ ปัจจุบันค่านี้อนุญาตเฉพาะให้ flow การติดตั้ง กู้คืนจากความล้มเหลวเฉพาะของการอัปเกรด Plugin ที่ bundled ซึ่งล้าสมัย เช่น path ของ Plugin ที่ bundled หายไป หรือรายการ channels.<id> ที่ล้าสมัยสำหรับ Plugin ที่ bundled เดียวกันนั้น ข้อผิดพลาด config ที่ไม่เกี่ยวข้องยังคงบล็อกการติดตั้งและส่งผู้ปฏิบัติงาน ไปที่ openclaw doctor --fix

openclaw.channel.persistedAuthState คือเมตาดาทาแพ็กเกจสำหรับโมดูลตัวตรวจสอบ ขนาดเล็ก:

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

ใช้เมื่อ flow การตั้งค่า, doctor, สถานะ หรือ presence แบบอ่านอย่างเดียวต้องการ probe auth แบบ yes/no ที่ประหยัดก่อนที่ Plugin channel ทั้งหมดจะโหลด สถานะ auth ที่คงไว้ ไม่ใช่สถานะ channel ที่กำหนดค่าแล้ว: อย่าใช้เมตาดาทานี้เพื่อเปิดใช้ Plugin อัตโนมัติ, ซ่อมแซม dependency ของรันไทม์ หรือตัดสินว่าควรโหลดรันไทม์ channel หรือไม่ export เป้าหมายควรเป็นฟังก์ชันขนาดเล็กที่อ่านเฉพาะสถานะที่คงไว้; อย่า route ผ่าน barrel รันไทม์ channel ทั้งหมด

openclaw.channel.configuredState ใช้รูปแบบเดียวกันสำหรับการตรวจสอบแบบประหยัดว่า ตั้งค่า env-only แล้วหรือไม่:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

ใช้เมื่อ channel สามารถตอบสถานะที่กำหนดค่าแล้วจาก env หรือ input ขนาดเล็กอื่นที่ไม่ใช่รันไทม์ หากการตรวจสอบต้องการการ resolve config ทั้งหมดหรือรันไทม์ channel จริง ให้เก็บ logic นั้นไว้ใน hook config.hasConfiguredState ของ Plugin แทน

ลำดับความสำคัญในการค้นพบ (id ของ Plugin ซ้ำ)

OpenClaw ค้นพบ Plugin จาก root หลายแห่ง สำหรับลำดับการสแกน filesystem แบบ raw ดูที่ ลำดับการสแกน Plugin หากการค้นพบสองรายการใช้ id เดียวกัน จะเก็บเฉพาะ manifest ที่มี ลำดับความสำคัญสูงสุด เท่านั้น; duplicate ที่มีลำดับความสำคัญต่ำกว่าจะถูกทิ้งแทนที่จะโหลดเคียงข้างกัน

ลำดับความสำคัญ จากสูงสุดไปต่ำสุด:

1. เลือกโดย config — path ที่ pin อย่างชัดเจนใน plugins.entries.<id>
2. Bundled — Plugin ที่มาพร้อมกับ OpenClaw
3. ติดตั้งแบบ global — Plugin ที่ติดตั้งลงใน root ของ Plugin OpenClaw แบบ global
4. Workspace — Plugin ที่ค้นพบโดยอิงกับ workspace ปัจจุบัน

ผลที่ตามมา:

• สำเนา fork หรือล้าสมัยของ Plugin ที่ bundled ซึ่งอยู่ใน workspace จะไม่ shadow build ที่ bundled
• หากต้องการ override Plugin ที่ bundled ด้วย Plugin local จริง ๆ ให้ pin ผ่าน plugins.entries.<id> เพื่อให้ชนะด้วยลำดับความสำคัญ แทนการพึ่งพาการค้นพบจาก workspace
• การทิ้ง duplicate จะถูกบันทึกใน log เพื่อให้ Doctor และการวินิจฉัยการเริ่มต้นชี้ไปยังสำเนาที่ถูกทิ้งได้
• override duplicate ที่เลือกโดย config จะถูกเขียนใน diagnostics ว่าเป็น override อย่างชัดเจน แต่ยังคงเตือนเพื่อให้ fork ที่ล้าสมัยและ shadow โดยไม่ตั้งใจยังมองเห็นได้

ข้อกำหนด JSON Schema

• Plugin ทุกตัวต้องมาพร้อม JSON Schema แม้ว่าจะไม่รับการกำหนดค่าใดๆ ก็ตาม.
• สคีมาเปล่าสามารถใช้ได้ (เช่น { "type": "object", "additionalProperties": false }).
• สคีมาจะถูกตรวจสอบความถูกต้องตอนอ่าน/เขียนการกำหนดค่า ไม่ใช่ตอน runtime.
• เมื่อขยายหรือ fork Plugin ที่ bundled พร้อมคีย์การกำหนดค่าใหม่ ให้อัปเดต configSchema ใน openclaw.plugin.json ของ Plugin นั้นพร้อมกัน สคีมาของ Plugin ที่ bundled มีความเข้มงวด ดังนั้นการเพิ่ม plugins.entries.<id>.config.myNewKey ในการกำหนดค่าของผู้ใช้โดยไม่เพิ่ม myNewKey ลงใน configSchema.properties จะถูกปฏิเสธก่อนที่ runtime ของ Plugin จะโหลด.

ตัวอย่างการขยายสคีมา:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

พฤติกรรมการตรวจสอบความถูกต้อง

• คีย์ channels.* ที่ไม่รู้จักคือ ข้อผิดพลาด เว้นแต่ id ของ channel จะถูกประกาศโดย manifest ของ Plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny และ plugins.slots.* ต้องอ้างอิง id ของ Plugin ที่ ค้นพบได้ id ที่ไม่รู้จักคือ ข้อผิดพลาด.
• หากติดตั้ง Plugin แล้วแต่ manifest หรือสคีมาเสียหายหรือขาดหาย การตรวจสอบความถูกต้องจะล้มเหลวและ Doctor จะรายงานข้อผิดพลาดของ Plugin.
• หากมีการกำหนดค่า Plugin อยู่แต่ Plugin ถูก ปิดใช้งาน การกำหนดค่าจะถูกเก็บไว้และ จะแสดง คำเตือน ใน Doctor + บันทึก.

ดู ข้อมูลอ้างอิงการกำหนดค่า สำหรับสคีมา plugins.* แบบเต็ม.

หมายเหตุ

• manifest เป็นสิ่งที่ จำเป็นสำหรับ Plugin แบบ native ของ OpenClaw รวมถึงการโหลดจากระบบไฟล์ภายในเครื่อง runtime ยังโหลดโมดูล Plugin แยกต่างหาก; manifest ใช้สำหรับการค้นพบ + การตรวจสอบความถูกต้องเท่านั้น.
• manifest แบบ native จะถูก parse ด้วย JSON5 ดังนั้นจึงยอมรับคอมเมนต์ comma ท้ายรายการ และคีย์ที่ไม่ใส่เครื่องหมายคำพูดได้ ตราบใดที่ค่าสุดท้ายยังเป็นออบเจ็กต์.
• loader ของ manifest จะอ่านเฉพาะฟิลด์ manifest ที่มีเอกสารกำกับเท่านั้น หลีกเลี่ยงคีย์ระดับบนสุดแบบกำหนดเอง.
• channels, providers, cliBackends และ skills สามารถละไว้ได้ทั้งหมดเมื่อ Plugin ไม่จำเป็นต้องใช้.
• providerCatalogEntry ต้องคงความเบาและไม่ควร import โค้ด runtime ขนาดใหญ่; ใช้สำหรับเมตาดาต้าแค็ตตาล็อก provider แบบ static หรือ descriptor การค้นพบแบบแคบ ไม่ใช่การประมวลผลระหว่างคำขอ.
• ชนิด Plugin แบบ exclusive จะถูกเลือกผ่าน plugins.slots.*: kind: "memory" ผ่าน plugins.slots.memory, kind: "context-engine" ผ่าน plugins.slots.contextEngine (ค่าเริ่มต้น legacy).
• ประกาศชนิด Plugin แบบ exclusive ใน manifest นี้ OpenClawPluginDefinition.kind ใน entry ของ runtime เลิกแนะนำให้ใช้แล้ว และยังคงอยู่เพื่อเป็น fallback ด้านความเข้ากันได้สำหรับ Plugin รุ่นเก่าเท่านั้น.
• เมตาดาต้า env-var (setup.providers[].envVars, providerAuthEnvVars ที่เลิกแนะนำให้ใช้แล้ว และ channelEnvVars) เป็นแบบ declarative เท่านั้น สถานะ การ audit การตรวจสอบความถูกต้องของการส่งผ่าน Cron และพื้นผิวแบบอ่านอย่างเดียวอื่นๆ ยังคงใช้นโยบายความเชื่อถือของ Plugin และการเปิดใช้งานที่มีผลจริงก่อนจะถือว่า env var ถูกกำหนดค่าแล้ว.
• สำหรับเมตาดาต้า wizard ของ runtime ที่ต้องใช้โค้ด provider ดู hooks ของ runtime provider.
• หาก Plugin ของคุณขึ้นกับ native modules ให้จัดทำเอกสารขั้นตอนการ build และข้อกำหนด allowlist ของ package-manager (เช่น pnpm allow-build-scripts + pnpm rebuild <package>).

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