ไฟล์กำกับ Plugin

หน้านี้ครอบคลุม ไฟล์ manifest ของ Plugin OpenClaw แบบเนทีฟ ซึ่งคือ openclaw.plugin.json สำหรับโครงสร้างบันเดิลที่เข้ากันได้ (Codex, Claude, Cursor) โปรดดู บันเดิล Plugin

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

• บันเดิล Codex: .codex-plugin/plugin.json
• บันเดิล Claude: .claude-plugin/plugin.json หรือโครงสร้างคอมโพเนนต์ Claude เริ่มต้นที่ไม่มีไฟล์ manifest
• บันเดิล 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 หากไฟล์ manifest ขาดหายหรือไม่ถูกต้อง การตรวจสอบความถูกต้องของการกำหนดค่าจะถูกระงับและถือเป็นข้อผิดพลาดของ Plugin

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

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

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

ใช้ไฟล์นี้สำหรับ:

• ข้อมูลประจำตัวของ Plugin การตรวจสอบความถูกต้องของการกำหนดค่า และคำแนะนำสำหรับ UI การกำหนดค่า
• เมทาดาทาสำหรับการยืนยันตัวตน การเริ่มต้นใช้งาน และการตั้งค่า (นามแฝง การเปิดใช้งานอัตโนมัติ ตัวแปรสภาพแวดล้อมของผู้ให้บริการ ตัวเลือกการยืนยันตัวตน)
• คำแนะนำการเปิดใช้งานสำหรับพื้นผิวของระนาบควบคุม
• ความเป็นเจ้าของตระกูลโมเดลแบบย่อ
• สแนปช็อตแบบคงที่ของความเป็นเจ้าของความสามารถ (contracts)
• เมทาดาทาของตัวรัน QA ที่โฮสต์ openclaw qa ที่ใช้ร่วมกันสามารถตรวจสอบได้
• เมทาดาทาการกำหนดค่าเฉพาะช่องทางที่รวมเข้ากับแค็ตตาล็อกและพื้นผิวการตรวจสอบความถูกต้อง

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

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

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

ตัวอย่างแบบละเอียด

{  "id": "openrouter",  "name": "OpenRouter",  "description": "Plugin ผู้ให้บริการ OpenRouter",  "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"  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "คีย์ API ของ OpenRouter",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "คีย์ API ของ OpenRouter",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "คีย์ API",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

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

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

catalog ให้คำแนะนำการแสดงผลเพิ่มเติมแก่เบราว์เซอร์ Plugin โฮสต์อาจไม่ใช้คำแนะนำเหล่านี้ คำแนะนำเหล่านี้จะไม่ติดตั้งหรือเปิดใช้งาน Plugin และไม่เปลี่ยนพฤติกรรมขณะรันไทม์หรือระดับความน่าเชื่อถือของ Plugin

{  "catalog": {    "featured": true,    "order": 10  }}

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

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

ใช้ฟิลด์เหล่านี้เฉพาะกับข้อเท็จจริงเชิงประกาศที่ตรวจสอบได้โดยใช้ทรัพยากรน้อยเท่านั้น การรับส่งข้อมูล การแปลงคำขอ การรีเฟรชโทเค็น การตรวจสอบข้อมูลประจำตัว และพฤติกรรมการสร้างจริงยังคงอยู่ในรันไทม์ของ 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 หลีกเลี่ยงการนำเข้ารันไทม์ของ Plugin เพียงเพื่อให้แฟกทอรีเครื่องมือส่งคืน 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 ยังรองรับ optional (ระบุว่าเครื่องมือนี้ไม่จำเป็นต่อการเปิดใช้งาน Plugin) และ replaySafe (ระบุว่าสามารถเรียกใช้เครื่องมือซ้ำได้อย่างปลอดภัยหลังจากรอบการทำงานของโมเดลที่ไม่สมบูรณ์) นอกเหนือจากฟิลด์ configSignals/authSignals ที่ใช้ร่วมกันข้างต้น

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

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

รายการ providerAuthChoices แต่ละรายการอธิบายตัวเลือกการเริ่มต้นใช้งานหรือการยืนยันตัวตนหนึ่งตัวเลือก OpenClaw อ่านข้อมูลนี้ก่อนโหลดรันไทม์ของผู้ให้บริการ รายการการตั้งค่าผู้ให้บริการใช้ตัวเลือกในไฟล์ manifest เหล่านี้ ตัวเลือกการตั้งค่าที่ได้จาก descriptor และเมทาดาทา catalog สำหรับการติดตั้ง โดยไม่ต้องโหลดรันไทม์ของผู้ให้บริการ

เมื่อ appGuidedDiscovery เป็น true วิธีการยืนยันตัวตนของผู้ให้บริการที่ตรงกันต้องเปิดเผย appGuidedSetup.detect และ appGuidedSetup.prepare การตรวจหาต้องเป็นแบบ อ่านอย่างเดียว: ห้ามเข้าสู่ระบบ ดึงโมเดล ดาวน์โหลด หรือเขียนการกำหนดค่า การเตรียมการจะตรวจสอบ โมเดลที่เลือกอย่างเจาะจงอีกครั้งและส่งคืนข้อเสนอการกำหนดค่า OpenClaw จะทดสอบข้อเสนอแบบสด โดยแยกจากระบบ และบันทึกการเปลี่ยนแปลงเมื่อสำเร็จแล้วเท่านั้น

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

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

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

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

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

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

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

Plugin ทุกตัวควรกำหนด activation.onStartup โดยตั้งใจ ตั้งเป็น true เฉพาะเมื่อ Plugin ต้องทำงานระหว่างการเริ่มต้น Gateway ตั้งเป็น false เมื่อ Plugin ไม่ทำงานขณะเริ่มต้นและควรโหลดจากทริกเกอร์ที่แคบกว่าเท่านั้น การละ onStartup จะไม่ทำให้ Plugin ถูกโหลดเมื่อเริ่มต้นโดยปริยายอีกต่อไป ให้ใช้ข้อมูลเมตาการเปิดใช้งานอย่างชัดเจนสำหรับการเริ่มต้น ช่องทาง การกำหนดค่า harness ของเอเจนต์ หน่วยความจำ หรือทริกเกอร์การเปิดใช้งานอื่นที่แคบกว่า

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

ผู้ใช้งานจริงในปัจจุบัน:

• การวางแผนการเริ่มต้น Gateway ใช้ activation.onStartup สำหรับการนำเข้าขณะเริ่มต้นอย่างชัดเจน
• การวางแผน CLI ที่ทริกเกอร์ด้วยคำสั่งจะใช้ commandAliases[].cliCommand หรือ commandAliases[].name แบบเดิมเป็นทางเลือกสำรอง
• การวางแผนการเริ่มต้นรันไทม์ของเอเจนต์ใช้ activation.onAgentHarnesses สำหรับชุดทดสอบแบบฝัง และใช้ cliBackends[] ระดับบนสุดสำหรับนามแฝงรันไทม์ CLI
• การวางแผนการตั้งค่า/ช่องทางที่ทริกเกอร์โดยช่องทางจะใช้การเป็นเจ้าของ channels[] แบบเดิมเป็นทางเลือกสำรอง เมื่อไม่มีเมทาดาทาการเปิดใช้งานช่องทางอย่างชัดเจน
• การวางแผน Plugin ขณะเริ่มต้นใช้ activation.onConfigPaths สำหรับพื้นผิวการกำหนดค่ารูทที่ไม่ใช่ช่องทาง เช่น บล็อก browser ของ Plugin เบราว์เซอร์ที่รวมมาให้
• การวางแผนการตั้งค่า/รันไทม์ที่ทริกเกอร์โดยผู้ให้บริการจะใช้การเป็นเจ้าของ providers[] แบบเดิมและ cliBackends[] ระดับบนสุดเป็นทางเลือกสำรอง เมื่อไม่มีเมทาดาทาการเปิดใช้งานผู้ให้บริการอย่างชัดเจน

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

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

ใช้ qaRunners เมื่อ Plugin สนับสนุนตัวรันการขนส่งอย่างน้อยหนึ่งรายการภายใต้ รูท openclaw qa ที่ใช้ร่วมกัน ทำให้เมทาดาทานี้ประมวลผลได้รวดเร็วและคงที่ รันไทม์ ของ Plugin ยังคงเป็นเจ้าของการลงทะเบียน CLI จริงผ่านพื้นผิว runtime-api.ts แบบน้ำหนักเบาซึ่งส่งออก qaRunnerCliRegistrations ที่ตรงกัน ส่วน adapterFactory ซึ่งเป็นตัวเลือกจะเปิดเผยการขนส่งแก่สถานการณ์ QA ที่ใช้ร่วมกันโดยไม่ เปลี่ยนตัวรันของคำสั่งที่ลงทะเบียนไว้

{  "qaRunners": [    {      "commandName": "matrix",      "description": "เรียกใช้เลน QA แบบสดของ Matrix ที่ใช้ Docker กับ homeserver แบบใช้แล้วทิ้ง"    }  ]}

รหัส adapterFactory ต้องตรงกับ commandName อย่าส่งออกการลงทะเบียน สำหรับคำสั่งที่ไม่มีอยู่ในไฟล์ manifest

ข้อมูลอ้างอิง 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"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

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

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

OpenClaw รวม setup.providers[].envVars ไว้ในการค้นหาการยืนยันตัวตนของผู้ให้บริการและตัวแปรสภาพแวดล้อมแบบทั่วไป ให้ใส่เมทาดาทาสภาพแวดล้อมสำหรับการตั้งค่าและสถานะไว้ที่นั่น

ใช้ providerUsageAuthEnvVars เมื่อข้อมูลประจำตัวระดับการเรียกเก็บเงินหรือระดับองค์กรต้องเปิดใช้งาน resolveUsageAuth โดยไม่กลายเป็นข้อมูลประจำตัวสำหรับการอนุมาน ชื่อเหล่านี้จะรวมอยู่ในการบล็อก dotenv ของเวิร์กสเปซ การตัดออกจากโปรเซสลูก ACP การกรองข้อมูลลับในแซนด์บ็อกซ์ และการล้างข้อมูลลับในวงกว้าง รันไทม์ของผู้ให้บริการยังคงอ่านและจำแนกค่าภายใน resolveUsageAuth

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 ใช้สำหรับเครื่องหมายข้อมูลประจำตัวภายในเครื่องที่ผู้ให้บริการเป็นเจ้าของ ซึ่งสามารถตรวจสอบได้โดยไม่ต้องโหลดโค้ดรันไทม์ การตรวจสอบเหล่านี้ต้องประมวลผลได้รวดเร็วและอยู่ภายในเครื่องเท่านั้น: ห้ามเรียกใช้เครือข่าย ห้ามอ่านพวงกุญแจหรือตัวจัดการข้อมูลลับ ห้ามใช้คำสั่งเชลล์ และห้ามตรวจสอบ API ของผู้ให้บริการ

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

ฟิลด์ setup

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

uiHints คือแมปจากชื่อฟิลด์การกำหนดค่าไปยังคำแนะนำการแสดงผลขนาดเล็ก คีย์สามารถใช้จุดสำหรับฟิลด์การกำหนดค่าที่ซ้อนกันได้ แต่ส่วนใดของพาธต้องไม่เป็น __proto__, constructor หรือ prototype; การตั้งค่าจะปฏิเสธชื่อเหล่านั้น

{  "uiHints": {    "apiKey": {      "label": "คีย์ API",      "help": "ใช้สำหรับคำขอ OpenRouter",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

คำแนะนำของแต่ละฟิลด์สามารถมีรายการต่อไปนี้:

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

ใช้ contracts เฉพาะสำหรับเมทาดาทาการเป็นเจ้าของความสามารถแบบคงที่ที่ 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"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

แต่ละรายการเป็นตัวเลือก:

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

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

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

Plugin ผู้ให้บริการที่ใช้งาน resolveExternalAuthProfiles ควรประกาศ contracts.externalAuthProviders ฮุกการยืนยันตัวตนภายนอกที่ไม่ได้ประกาศจะถูกละเว้น

Plugin ผู้ให้บริการที่ใช้งานทั้ง resolveUsageAuth และ fetchUsageSnapshot ควรประกาศรหัสผู้ให้บริการที่ค้นพบอัตโนมัติแต่ละรายการใน contracts.usageProviders การค้นหาการใช้งานจะอ่านสัญญานี้ก่อนโหลดโค้ดรันไทม์ จากนั้นตรวจสอบฮุกทั้งสองหลังจากโหลดเฉพาะเจ้าของที่ประกาศไว้

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

ผู้ให้บริการเวิร์กเกอร์ต้องประกาศรหัส api.registerWorkerProvider(...) แต่ละรายการใน contracts.workerProviders Core จะบันทึกเจตนาที่คงทนก่อนเรียก provision ผู้ให้บริการจะตรวจสอบการตั้งค่าของตนก่อนจัดสรรทรัพยากรภายนอก และการเรียกซ้ำด้วยรหัสการดำเนินการเดียวกันต้องรับช่วงสัญญาเช่าเดิม Core ยังบันทึกสแนปช็อตการตั้งค่าที่ผ่านการตรวจสอบนั้น และส่งไปพร้อมกับ leaseId ให้แก่ inspect({ leaseId, profile }) และ destroy({ leaseId, profile }) รวมถึงหลังจากโปรไฟล์ที่ระบุชื่อถูกเปลี่ยนแปลงหรือลบแล้ว การทำลายเป็นแบบ idempotent การตรวจสอบจะส่งคืนยูเนียนสถานะปิด active / destroyed / unknown และวัสดุคีย์ส่วนตัว SSH จะถูกอ้างอิงผ่าน SecretRef เท่านั้น ปลายทาง SSH ที่จัดเตรียมแล้วต้องมี hostKey สาธารณะจากผลลัพธ์การจัดเตรียมที่เชื่อถือได้ในรูปแบบ algorithm base64 อย่างเคร่งครัด โดยไม่มีชื่อโฮสต์หรือความคิดเห็น เพื่อให้ Core สามารถตรึงโฮสต์ก่อนเชื่อมต่อ ผู้ให้บริการที่สร้างการอ้างอิงข้อมูลประจำตัวแบบไดนามิกอาจใช้งาน resolveSshIdentity({ leaseId, profile, keyRef }) ที่มีอำนาจสูงสุด ผู้ให้บริการที่ไม่มีรายการนี้จะใช้ตัวแก้ไขข้อมูลลับทั่วไปของ Core unknown ที่มีอำนาจสูงสุดจะทำให้ระเบียนภายในที่ใช้งานอยู่กลายเป็นระเบียนกำพร้า และหลังจากคำขอทำลายถูกบันทึกแล้ว จะใช้ยืนยันว่าการรื้อถอนได้เสร็จสิ้น

ปัจจุบัน contracts.gatewayMethodDispatch ยอมรับ "authenticated-request" รายการนี้เป็นด่านตรวจสุขอนามัยของ API สำหรับเส้นทาง HTTP แบบเนทีฟของ Plugin ที่ตั้งใจส่งต่อเมธอดระนาบควบคุมของ Gateway ภายในโปรเซส ไม่ใช่แซนด์บ็อกซ์สำหรับป้องกัน Plugin แบบเนทีฟที่เป็นอันตราย ใช้เฉพาะกับพื้นผิวที่มาพร้อมระบบหรือสำหรับผู้ปฏิบัติงานซึ่งผ่านการตรวจสอบอย่างเข้มงวด และกำหนดให้ใช้การยืนยันตัวตน HTTP ของ Gateway อยู่แล้ว เส้นทางที่มีสิทธิ์จะยังเข้าถึงได้ขณะที่ปิดการรับงานระดับรากของ Gateway เฉพาะเมื่อเส้นทางนั้นประกาศทั้ง auth: "gateway" และ gatewayRuntimeScopeSurface: "trusted-operator" เฉพาะเส้นทาง ส่วนเส้นทางพี่น้องทั่วไปจาก Plugin เดียวกันจะยังคงอยู่หลังขอบเขตการรับงาน วิธีนี้ช่วยให้ยังเข้าถึงสถานะการระงับและการดำเนินการต่อได้ โดยไม่ให้สิทธิ์ข้ามการรับงานแก่ทั้ง Plugin จำกัดขอบเขตการแยกวิเคราะห์และการจัดรูปแบบการตอบกลับไว้นอกการส่งต่อ งานที่มีสาระสำคัญหรือแก้ไขข้อมูลต้องดำเนินการผ่านการส่งต่อเมธอดของ Gateway ซึ่งเป็นเจ้าของการบังคับใช้การรับงานและขอบเขต

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

ใช้ configContracts สำหรับพฤติกรรมการกำหนดค่าที่แมนิเฟสต์เป็นเจ้าของ ซึ่งตัวช่วยทั่วไปของ Core ต้องใช้โดยไม่ต้องนำเข้ารันไทม์ของ Plugin ได้แก่ การตรวจจับแฟล็กอันตราย เป้าหมายการย้าย SecretRef และการจำกัดเส้นทางการกำหนดค่าแบบเดิม

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "routes.*.secret",          "expected": "string",          "ownerKind": "route"        }      ]    }  }}

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

secretInputs รองรับ:

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

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

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

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

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

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

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

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

• configSchema ตรวจสอบความถูกต้องของ plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema ตรวจสอบความถูกต้องของ channels.<channel-id>

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

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

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "URL ของโฮมเซิร์ฟเวอร์",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "การเชื่อมต่อโฮมเซิร์ฟเวอร์ Matrix",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

รายการช่องทางแต่ละรายการสามารถมีสิ่งต่อไปนี้:

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

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

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

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

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

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

ใช้ modelSupport เมื่อ OpenClaw ควรอนุมาน Plugin ผู้ให้บริการของคุณจากรหัสโมเดลแบบย่อ เช่น gpt-5.6-sol หรือ claude-sonnet-4.6 ก่อนโหลดรันไทม์ของ Plugin

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

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

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

ฟิลด์:

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

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

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

{  "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": "ไม่มีให้ใช้งานบน Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

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

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

suppressions แทนที่ฮุก suppressBuiltInModel แบบเก่าของรันไทม์ผู้ให้บริการ รายการระงับจะมีผลเฉพาะเมื่อ Plugin เป็นเจ้าของผู้ให้บริการ หรือประกาศเป็นคีย์ modelCatalog.aliases ที่ชี้ไปยังผู้ให้บริการที่เป็นเจ้าของ ระบบจะไม่เรียกฮุกระงับของรันไทม์ระหว่างการแปลงค่าโมเดลอีกต่อไป

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

ฟิลด์โมเดล:

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

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

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

ใช้ modelIdNormalization สำหรับการปรับแต่งรหัสโมเดลที่ผู้ให้บริการเป็นเจ้าของแบบประหยัด ซึ่งต้องเกิดขึ้นก่อนโหลดรันไทม์ของผู้ให้บริการ วิธีนี้เก็บนามแฝง เช่น ชื่อโมเดลแบบสั้น รหัสเดิมภายในผู้ให้บริการ และกฎคำนำหน้าพร็อกซี ไว้ในแมนิเฟสต์ของ Plugin เจ้าของ แทนที่จะอยู่ในตารางเลือกโมเดลของแกนหลัก

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

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

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

ใช้ providerEndpoints สำหรับการจำแนกปลายทางที่นโยบายคำขอทั่วไปต้องทราบก่อนโหลดรันไทม์ของผู้ให้บริการ แกนหลักยังคงเป็นเจ้าของความหมายของ endpointClass แต่ละรายการ ส่วนแมนิเฟสต์ของ Plugin เป็นเจ้าของเมทาดาทาโฮสต์และ URL ฐาน

Plugin ผู้ให้บริการที่แยกออกเป็นภายนอกอย่างเป็นทางการจะไม่รวมอยู่ในชุดแจกจ่ายหลัก ดังนั้น แมนิเฟสต์ของ Plugin เหล่านั้นจึงมองไม่เห็นจนกว่าจะติดตั้ง และต้องทำสำเนา providerEndpoints ไว้ใน scripts/lib/official-external-provider-catalog.json ด้วย เพื่อให้ การจำแนกปลายทางยังคงทำงานได้โดยไม่มี Plugin โดยมีการทดสอบสัญญา คอยบังคับให้ข้อมูลสำเนาตรงกัน

ฟิลด์ปลายทาง:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ใช้ modelPricing เมื่อผู้ให้บริการต้องควบคุมพฤติกรรมการกำหนดราคาของระนาบควบคุมก่อนโหลดรันไทม์ แคชราคาของ Gateway จะอ่านข้อมูลเมตานี้โดยไม่ต้องนำเข้าโค้ดรันไทม์ของผู้ให้บริการ

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

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

ฟิลด์แหล่งที่มา:

ดัชนีผู้ให้บริการ OpenClaw

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

ลำดับความน่าเชื่อถือของแค็ตตาล็อก:

1. การกำหนดค่าของผู้ใช้
2. แมนิเฟสต์ Plugin ที่ติดตั้ง modelCatalog
3. แคชแค็ตตาล็อกโมเดลจากการรีเฟรชอย่างชัดเจน
4. แถวตัวอย่างจากดัชนีผู้ให้บริการ OpenClaw

ดัชนีผู้ให้บริการต้องไม่มีข้อมูลลับ สถานะการเปิดใช้งาน ฮุกรันไทม์ หรือข้อมูลโมเดลสดที่เฉพาะเจาะจงกับบัญชี แค็ตตาล็อกตัวอย่างใช้รูปแบบแถวผู้ให้บริการ modelCatalog เดียวกับแมนิเฟสต์ Plugin แต่ควรจำกัดไว้เฉพาะข้อมูลเมตาสำหรับการแสดงผลที่เสถียร เว้นแต่ฟิลด์อะแดปเตอร์รันไทม์ เช่น api, baseUrl, ราคา หรือแฟล็กความเข้ากันได้ จะได้รับการรักษาให้สอดคล้องกับแมนิเฟสต์ Plugin ที่ติดตั้งโดยเจตนา ผู้ให้บริการที่มีการค้นหา /models แบบสดควรเขียนแถวที่รีเฟรชผ่านพาธแคชแค็ตตาล็อกโมเดลอย่างชัดเจน แทนที่จะให้การแสดงรายการหรือการเริ่มต้นใช้งานตามปกติเรียก API ของผู้ให้บริการ

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

openclaw doctor --fix ย้ายชุดคีย์ความสามารถระดับบนสุดแบบเดิมของแมนิเฟสต์ที่มีขนาดเล็กและจำกัดไปยัง contracts.* ได้แก่ speechProviders, mediaUnderstandingProviders, imageGenerationProviders และ tools คีย์เหล่านี้ทั้งหมด (รวมถึงรายการความสามารถอื่นๆ) จะไม่ถูกอ่านเป็นฟิลด์ระดับบนสุดของแมนิเฟสต์อีกต่อไป การโหลดแมนิเฟสต์ตามปกติจะรู้จักคีย์เหล่านี้เฉพาะภายใต้ contracts

แมนิเฟสต์เทียบกับ package.json

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

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

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

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

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

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

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

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

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

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

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

การตรึงเวอร์ชัน npm แบบตรงตัวมีอยู่แล้วใน npmSpec ตัวอย่างเช่น "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3" รายการแค็ตตาล็อกภายนอกอย่างเป็นทางการควรจับคู่ข้อกำหนดแบบตรงตัวกับ expectedIntegrity เพื่อให้ขั้นตอนการอัปเดตหยุดอย่างปลอดภัยหากอาร์ติแฟกต์ npm ที่ดึงมาไม่ตรงกับรีลีสที่ตรึงไว้อีกต่อไป การเริ่มต้นใช้งานแบบโต้ตอบยังคงเสนอข้อกำหนด npm จากรีจิสทรีที่เชื่อถือได้ รวมถึงชื่อแพ็กเกจแบบไม่มีส่วนขยายและ dist-tags เพื่อความเข้ากันได้ การวินิจฉัยแค็ตตาล็อกสามารถแยกแยะแหล่งตัวเลือกเริ่มต้นแบบตรงตัว แบบลอยตัว แบบตรึงความถูกต้องสมบูรณ์ แบบไม่มีความถูกต้องสมบูรณ์ แบบชื่อแพ็กเกจไม่ตรงกัน และแบบไม่ถูกต้องได้ นอกจากนี้ยังเตือนเมื่อมี expectedIntegrity แต่ไม่มีแหล่ง npm ที่ถูกต้องให้ตรึง เมื่อมี expectedIntegrity ขั้นตอนการติดตั้ง/อัปเดตจะบังคับใช้ค่านี้ เมื่อไม่มีค่านี้ ระบบจะบันทึกการแก้ไขรีจิสทรีโดยไม่มีการตรึงความถูกต้องสมบูรณ์

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

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

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

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

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

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

openclaw.channel.configuredState รองรับการตรวจสอบการกำหนดค่าที่มีต้นทุนต่ำ ควรใช้เมทาดาทาตัวแปรสภาพแวดล้อมแบบประกาศเมื่อใช้เพียงตัวแปรสภาพแวดล้อมก็เพียงพอ:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

ใช้ env.allOf เมื่อต้องมีทุกตัวแปรที่ระบุ และใช้ env.anyOf เมื่อตัวแปรใดตัวแปรหนึ่งที่ไม่ว่างก็เพียงพอ หากการตรวจสอบขนาดเล็กที่ไม่ใช่รันไทม์ต้องการมากกว่าเมทาดาทาตัวแปรสภาพแวดล้อม ให้ใช้ specifier ร่วมกับ exportName ตามที่แสดงสำหรับ persistedAuthState; เมื่อมี env OpenClaw จะใช้ค่านี้โดยไม่โหลดโมดูลนั้น หากการตรวจสอบต้องใช้การแก้ไขการกำหนดค่าแบบเต็มหรือรันไทม์ช่องทางจริง ให้เก็บตรรกะนั้นไว้ในฮุก config.hasConfiguredState ของ Plugin แทน

ลำดับความสำคัญในการค้นหา (รหัส Plugin ซ้ำกัน)

OpenClaw ค้นหา Plugin จากสามรูท โดยตรวจสอบตามลำดับนี้: Plugin ที่รวมและจัดส่งมากับ OpenClaw, รูทการติดตั้งส่วนกลาง (~/.openclaw/extensions) และรูทพื้นที่ทำงานปัจจุบัน (<workspace>/.openclaw/extensions) รวมถึงรายการ plugins.load.paths ที่ระบุไว้อย่างชัดเจน

หากผลการค้นหาสองรายการมี id เดียวกัน ระบบจะเก็บเฉพาะแมนิเฟสต์ที่มีลำดับความสำคัญสูงสุด ส่วนรายการซ้ำที่มีลำดับความสำคัญต่ำกว่าจะถูกทิ้งแทนที่จะโหลดควบคู่กัน ลำดับความสำคัญจากสูงสุดไปต่ำสุด:

1. เลือกโดยการกำหนดค่า — พาธที่ตรึงไว้อย่างชัดเจนใน plugins.entries.<id>
2. การติดตั้งส่วนกลางที่ตรงกับระเบียนการติดตั้งที่ติดตามไว้ — Plugin ที่ติดตั้งผ่าน openclaw plugin install/openclaw plugin update ซึ่งการติดตามการติดตั้งของ OpenClaw รู้จักว่าเป็นรหัสเดียวกัน แม้ว่ารหัสนั้นจะเป็นของ Plugin ที่รวมมาด้วยด้วยก็ตาม
3. รวมมาด้วย — Plugin ที่จัดส่งมากับ OpenClaw
4. พื้นที่ทำงาน — Plugin ที่ค้นพบโดยอ้างอิงจากพื้นที่ทำงานปัจจุบัน
5. ตัวเลือกอื่นใดที่ค้นพบ

ผลที่ตามมา:

• สำเนาที่ fork ไว้หรือล้าสมัยของ Plugin ที่รวมมา ซึ่งวางอยู่โดยไม่ถูกติดตามในเวิร์กสเปซหรือรูทส่วนกลาง จะไม่บดบังบิลด์ที่รวมมา
• หากต้องการแทนที่ Plugin ที่รวมมา ให้เรียกใช้ openclaw plugin install สำหรับ id นั้น เพื่อให้การติดตั้งส่วนกลางที่ติดตามไว้มีลำดับความสำคัญสูงกว่าสำเนาที่รวมมา หรือปักหมุดพาธเฉพาะผ่าน plugins.entries.<id> เพื่อให้พาธนั้นชนะตามลำดับความสำคัญที่เลือกด้วยการกำหนดค่า
• ระบบจะบันทึกการทิ้งรายการซ้ำลงในล็อก เพื่อให้ Doctor และการวินิจฉัยเมื่อเริ่มต้นระบบสามารถชี้ไปยังสำเนาที่ถูกละทิ้งได้
• การแทนที่รายการซ้ำที่เลือกด้วยการกำหนดค่าจะแสดงถ้อยคำในการวินิจฉัยว่าเป็นการแทนที่อย่างชัดเจน แต่ยังคงแจ้งเตือนเพื่อให้ fork ที่ล้าสมัยและการบดบังโดยไม่ตั้งใจยังคงมองเห็นได้

ข้อกำหนดของ JSON Schema

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

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

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

ลักษณะการตรวจสอบความถูกต้อง

• คีย์ channels.* ที่ไม่รู้จักถือเป็น ข้อผิดพลาด เว้นแต่ id ของช่องทางจะประกาศโดยไฟล์ manifest ของ Plugin หาก id เดียวกันปรากฏใน plugins.allow, plugins.entries หรือ plugins.installs ด้วย (Plugin ที่ถูกอ้างอิงแต่ยังค้นหาไม่พบในขณะนี้) OpenClaw จะลดระดับกรณีนี้เป็น คำเตือน แทน
• plugins.entries.<id>, plugins.allow และ plugins.deny ที่อ้างอิง id ของ Plugin ที่ไม่รู้จักถือเป็น คำเตือน ("ละเว้นรายการการกำหนดค่าที่ล้าสมัย") ไม่ใช่ข้อผิดพลาด เพื่อให้การอัปเกรดและ Plugin ที่ถูกลบ/เปลี่ยนชื่อไม่ขัดขวางการเริ่มต้น Gateway
• plugins.slots.memory ที่อ้างอิง id ของ Plugin ที่ไม่รู้จักถือเป็น ข้อผิดพลาด ยกเว้น Plugin ภายนอกอย่างเป็นทางการ memory-lancedb ที่ระบบรู้จัก ซึ่งจะแจ้งเตือนแทน
• หากมีการติดตั้ง Plugin แต่ไฟล์ manifest หรือสคีมาเสียหายหรือขาดหาย การตรวจสอบความถูกต้องจะล้มเหลว และ Doctor จะรายงานข้อผิดพลาดของ Plugin
• หากมีการกำหนดค่าของ Plugin แต่ Plugin ถูกปิดใช้งาน ระบบจะเก็บการกำหนดค่าไว้และแสดง คำเตือน ใน Doctor และล็อก

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

หมายเหตุ

• ไฟล์ manifest จำเป็นสำหรับ Plugin แบบเนทีฟของ OpenClaw รวมถึงการโหลดจากระบบไฟล์ภายในเครื่อง รันไทม์ยังคงโหลดโมดูลของ Plugin แยกต่างหาก ส่วนไฟล์ manifest ใช้สำหรับการค้นหาและการตรวจสอบความถูกต้องเท่านั้น
• ไฟล์ manifest แบบเนทีฟได้รับการแยกวิเคราะห์ด้วย JSON5 จึงรองรับความคิดเห็น เครื่องหมายจุลภาคต่อท้าย และคีย์ที่ไม่ใส่เครื่องหมายคำพูด ตราบใดที่ค่าสุดท้ายยังคงเป็นออบเจ็กต์
• ตัวโหลดไฟล์ manifest จะอ่านเฉพาะฟิลด์ที่มีเอกสารกำกับเท่านั้น หลีกเลี่ยงการใช้คีย์ระดับบนสุดแบบกำหนดเอง
• สามารถละเว้น channels, providers, cliBackends และ skills ทั้งหมดได้เมื่อ Plugin ไม่จำเป็นต้องใช้
• providerCatalogEntry ต้องมีขนาดเบาและไม่ควรนำเข้าโค้ดรันไทม์ในวงกว้าง ให้ใช้สำหรับเมทาดาทาของแค็ตตาล็อกผู้ให้บริการแบบคงที่หรือตัวอธิบายการค้นหาที่มีขอบเขตแคบ ไม่ใช่การดำเนินการขณะประมวลผลคำขอ
• ชนิด Plugin แบบเลือกได้เพียงรายการเดียวจะเลือกผ่าน plugins.slots.*: kind: "memory" ผ่าน plugins.slots.memory (ค่าเริ่มต้น memory-core), kind: "context-engine" ผ่าน plugins.slots.contextEngine (ค่าเริ่มต้น legacy)
• ประกาศชนิด Plugin แบบเลือกได้เพียงรายการเดียวในไฟล์ manifest นี้ OpenClawPluginDefinition.kind ของรายการเข้าสู่รันไทม์เลิกแนะนำให้ใช้แล้ว และยังคงมีอยู่เฉพาะเป็นทางเลือกสำรองเพื่อความเข้ากันได้สำหรับ Plugin รุ่นเก่า
• เมทาดาทาของตัวแปรสภาพแวดล้อมใน setup.providers[].envVars มีไว้เพื่อการประกาศเท่านั้น สถานะ การตรวจสอบ การตรวจสอบความถูกต้องของการส่ง Cron และส่วนอื่นที่อ่านอย่างเดียวยังคงใช้นโยบายความน่าเชื่อถือและการเปิดใช้งานที่มีผลของ Plugin ก่อนถือว่าตัวแปรสภาพแวดล้อมได้รับการกำหนดค่าแล้ว
• สำหรับเมทาดาทาของวิซาร์ดรันไทม์ที่ต้องใช้โค้ดของผู้ให้บริการ โปรดดู ฮุกของรันไทม์ผู้ให้บริการ
• หาก Plugin ของคุณพึ่งพาโมดูลแบบเนทีฟ ให้จัดทำเอกสารขั้นตอนการบิลด์และข้อกำหนดของรายการอนุญาตสำหรับตัวจัดการแพ็กเกจ (ตัวอย่างเช่น pnpm allow-build-scripts + pnpm rebuild <package>)

เนื้อหาที่เกี่ยวข้อง