ไฟล์กำกับ Plugin

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

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

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

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

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

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

ข้อมูลอ้างอิง 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": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

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

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

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

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

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

เมื่อมี 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 key",      "help": "Used for OpenRouter requests",      "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 ยังคงเก็บไว้สำหรับโรงงานส่วนขยายที่ใช้เฉพาะกับเซิร์ฟเวอร์แอป 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 การค้นหาการใช้งานจะอ่านสัญญานี้ก่อนโหลดโค้ดรันไทม์ จากนั้นตรวจสอบฮุกทั้งสองหลังจากโหลดเฉพาะเจ้าของที่ประกาศไว้แล้ว

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

ผู้ให้บริการเวิร์กเกอร์ต้องประกาศรหัส api.registerWorkerProvider(...) แต่ละรายการใน contracts.workerProviders คอร์จะบันทึกเจตนาที่คงทนก่อนเรียก provision ผู้ให้บริการจะตรวจสอบการตั้งค่าก่อนจัดสรรทรัพยากรภายนอก และการเรียกซ้ำด้วยรหัสการดำเนินการเดียวกันต้องรับช่วงสัญญาเช่าเดิม คอร์ยังบันทึกสแนปช็อตการตั้งค่าที่ผ่านการตรวจสอบนั้น และส่งพร้อม leaseId ไปยัง inspect({ leaseId, profile }) และ destroy({ leaseId, profile }) รวมถึงหลังจากโปรไฟล์ที่ระบุชื่อถูกเปลี่ยนแปลงหรือลบแล้ว การทำลายเป็นแบบเรียกซ้ำได้โดยให้ผลลัพธ์เดิม การตรวจสอบส่งคืนยูเนียนสถานะแบบปิด 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": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "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": "not available on 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 ของ 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 และปล่อยให้การแก้ค่า secret จริงเป็นหน้าที่ของรันไทม์ 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. modelCatalog ในมานิเฟสต์ของ Plugin ที่ติดตั้ง
3. แคชแค็ตตาล็อกโมเดลจากการรีเฟรชอย่างชัดเจน
4. แถวตัวอย่างจากดัชนีผู้ให้บริการของ OpenClaw

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

ระบบบังคับใช้ openclaw.install.minHostVersion ระหว่างการติดตั้งและการโหลดรีจิสทรี manifest สำหรับแหล่ง 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": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

ใช้เมื่อช่องทางสามารถตอบสถานะการกำหนดค่าจากตัวแปรสภาพแวดล้อมหรืออินพุตขนาดเล็กอื่นที่ไม่ใช่รันไทม์ หากการตรวจสอบต้องใช้การแก้ค่าการกำหนดค่าแบบเต็มหรือรันไทม์ช่องทางจริง ให้เก็บตรรกะนั้นไว้ในฮุก config.hasConfiguredState ของ Plugin แทน

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

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

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

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

ผลที่ตามมา:

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

ข้อกำหนด JSON Schema

• Plugin ทุกตัวต้องมาพร้อม JSON Schema แม้ว่าจะไม่รับการกำหนดค่าใด ๆ ก็ตาม
• อนุญาตให้ใช้สคีมาว่างได้ (เช่น { "type": "object", "additionalProperties": false })
• ระบบตรวจสอบความถูกต้องของสคีมาขณะอ่าน/เขียนการกำหนดค่า ไม่ใช่ขณะรันไทม์
• เมื่อขยายหรือฟอร์ก Plugin ที่รวมมาให้โดยเพิ่มคีย์การกำหนดค่าใหม่ ให้อัปเดต configSchema ใน openclaw.plugin.json ของ 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 จะลดระดับกรณีนี้เป็น คำเตือน แทน
• การอ้างอิงรหัส Plugin ที่ไม่รู้จักใน plugins.entries.<id>, plugins.allow และ plugins.deny ถือเป็น คำเตือน ("ละเว้นรายการการกำหนดค่าที่ล้าสมัย") ไม่ใช่ข้อผิดพลาด เพื่อให้การอัปเกรดและ 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 ของคุณขึ้นอยู่กับโมดูลเนทีฟ ให้จัดทำเอกสารขั้นตอนการบิลด์และข้อกำหนดเกี่ยวกับรายการอนุญาตของตัวจัดการแพ็กเกจ (เช่น allow-build-scripts ของ pnpm และ pnpm rebuild <package>)

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