ไฟล์กำกับ 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": "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"      }    }  }}

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

ข้อมูลอ้างอิงแค็ตตาล็อก

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 อ่านข้อมูลนี้ก่อนโหลดรันไทม์ของผู้ให้บริการ รายการการตั้งค่าผู้ให้บริการใช้ตัวเลือกจากไฟล์รายการเหล่านี้ ตัวเลือกการตั้งค่าที่ได้มาจากตัวบรรยาย และเมทาดาทาของแค็ตตาล็อกการติดตั้ง โดยไม่โหลดรันไทม์ของผู้ให้บริการ

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

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

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

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

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

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

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

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

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

{  "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[] ระดับบนสุด เมื่อไม่มีเมทาดาทาการเปิดใช้งานผู้ให้บริการอย่างชัดเจน

การวินิจฉัยของตัววางแผนสามารถแยกคำใบ้การเปิดใช้งานอย่างชัดเจนออกจากการย้อนกลับไปใช้การเป็นเจ้าของของไฟล์กำกับได้ ตัวอย่างเช่น 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 รองรับกับโฮมเซิร์ฟเวอร์แบบใช้แล้วทิ้ง"    }  ]}

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

ข้อมูลอ้างอิงการตั้งค่า

ใช้ 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 ในการค้นหาการตรวจสอบสิทธิ์และตัวแปรสภาพแวดล้อมของผู้ให้บริการแบบทั่วไป providerAuthEnvVars ยังคงรองรับผ่านอะแดปเตอร์ความเข้ากันได้ในช่วงเลิกใช้งาน แต่ Plugin ที่ไม่ได้รวมมาให้ซึ่งยังคงใช้งานรายการนี้จะได้รับการวินิจฉัยไฟล์กำกับ Plugin ใหม่ควรใส่เมทาดาทาสภาพแวดล้อมสำหรับการตั้งค่า/สถานะไว้ใน 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 ที่ตัวอธิบายในไฟล์กำกับไม่ได้ประกาศไว้ หรือหากตัวอธิบายไม่มีการลงทะเบียนรันไทม์ที่ตรงกัน การวินิจฉัยเหล่านี้เป็นข้อมูลเพิ่มเติมและไม่ปฏิเสธ 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-only ของ Codex ที่มาพร้อมระบบ การแปลงผลลัพธ์เครื่องมือที่มาพร้อมระบบควรประกาศ contracts.agentToolResultMiddleware และลงทะเบียนด้วย api.registerAgentToolResultMiddleware(...) แทน Plugin ที่ติดตั้งอาจใช้จุดเชื่อมต่อมิดเดิลแวร์เดียวกันได้เฉพาะเมื่อเปิดใช้อย่างชัดเจน และเฉพาะกับรันไทม์ที่ประกาศไว้ใน contracts.agentToolResultMiddleware

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ผลที่ตามมา:

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

ข้อกำหนด JSON Schema

• Plugin ทุกตัวต้องมาพร้อมกับ JSON Schema แม้ว่าจะไม่รับการกำหนดค่าใดๆ ก็ตาม
• สามารถใช้สคีมาว่างได้ (ตัวอย่างเช่น { "type": "object", "additionalProperties": false })
• สคีมาจะได้รับการตรวจสอบความถูกต้องเมื่ออ่าน/เขียนการกำหนดค่า ไม่ใช่ขณะรันไทม์
• เมื่อขยายหรือฟอร์ก 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.* ที่ไม่รู้จักถือเป็น ข้อผิดพลาด เว้นแต่จะมีการประกาศรหัสช่องทางไว้ในแมนิเฟสต์ของ Plugin หากรหัสเดียวกันปรากฏใน plugins.allow, plugins.entries หรือ plugins.installs ด้วย (Plugin ที่ถูกอ้างอิงแต่ไม่สามารถค้นพบได้ในขณะนี้) OpenClaw จะลดระดับเป็น คำเตือน แทน
• plugins.entries.<id>, plugins.allow และ plugins.deny ที่อ้างอิงรหัส Plugin ที่ไม่รู้จักถือเป็น คำเตือน ("ละเว้นรายการการกำหนดค่าที่ล้าสมัย") ไม่ใช่ข้อผิดพลาด เพื่อไม่ให้การอัปเกรดและ Plugin ที่ถูกลบ/เปลี่ยนชื่อขัดขวางการเริ่มต้น Gateway
• plugins.slots.memory ที่อ้างอิงรหัส Plugin ที่ไม่รู้จักถือเป็น ข้อผิดพลาด ยกเว้น Plugin ภายนอกอย่างเป็นทางการ memory-lancedb ที่รู้จัก ซึ่งจะแสดงคำเตือนแทน
• หากติดตั้ง Plugin แล้ว แต่แมนิเฟสต์หรือสคีมาเสียหายหรือขาดหาย การตรวจสอบความถูกต้องจะล้มเหลวและ Doctor จะรายงานข้อผิดพลาดของ Plugin
• หากมีการกำหนดค่าของ Plugin แต่ Plugin ถูก ปิดใช้งาน ระบบจะเก็บการกำหนดค่าไว้และแสดง คำเตือน ใน Doctor และบันทึก

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

หมายเหตุ

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

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