แมนิเฟสต์ Plugin

หน้านี้มีไว้สำหรับ native OpenClaw plugin manifest เท่านั้น

สำหรับรูปแบบ bundle ที่เข้ากันได้ โปรดดู Plugin bundles

รูปแบบ bundle ที่เข้ากันได้ใช้ไฟล์ manifest คนละแบบ:

• Codex bundle: .codex-plugin/plugin.json
• Claude bundle: .claude-plugin/plugin.json หรือรูปแบบองค์ประกอบ Claude เริ่มต้น ที่ไม่มี manifest
• Cursor bundle: .cursor-plugin/plugin.json

OpenClaw ตรวจพบรูปแบบ bundle เหล่านั้นโดยอัตโนมัติด้วย แต่รูปแบบเหล่านั้นไม่ได้ถูกตรวจสอบ กับ schema openclaw.plugin.json ที่อธิบายไว้ที่นี่

สำหรับ bundle ที่เข้ากันได้ ปัจจุบัน OpenClaw อ่าน metadata ของ bundle พร้อมกับ skill roots ที่ประกาศไว้, Claude command roots, ค่าเริ่มต้น settings.json ของ Claude bundle, ค่าเริ่มต้น LSP ของ Claude bundle และ hook packs ที่รองรับ เมื่อรูปแบบตรงกับ ความคาดหวังของ runtime ของ OpenClaw

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

ดูคู่มือระบบ plugin ฉบับเต็ม: Plugins สำหรับ capability model แบบ native และแนวทางความเข้ากันได้ภายนอกในปัจจุบัน: Capability model

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

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

ใช้สำหรับ:

• ตัวตนของ plugin, การตรวจสอบ config และคำใบ้ UI ของ config
• metadata สำหรับ auth, onboarding และ setup (alias, auto-enable, provider env vars, ตัวเลือก auth)
• คำใบ้ activation สำหรับพื้นผิว control-plane
• ความเป็นเจ้าของ model-family แบบย่อ
• snapshots ความเป็นเจ้าของ capability แบบ static (contracts)
• metadata ของ QA runner ที่โฮสต์ openclaw qa ร่วมกันสามารถตรวจสอบได้
• metadata config เฉพาะ channel ที่ถูกรวมเข้าใน catalog และพื้นผิว validation

อย่าใช้สำหรับ: การลงทะเบียนพฤติกรรม runtime, การประกาศ code entrypoints, หรือ metadata การติดตั้ง 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"],  "providerAuthEnvVars": {    "openrouter": ["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"      }    }  }}

อ้างอิง field ระดับบนสุด

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

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

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

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

อ้างอิง providerAuthChoices

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

อ้างอิง commandAliases

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

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

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

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

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

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

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

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

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

consumer ที่ใช้งานจริงในปัจจุบัน:

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

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

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

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

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

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

ใช้ setup เมื่อพื้นผิว setup และ onboarding ต้องการ metadata ราคาถูกที่ 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 inference backend ต่อไป setup.cliBackends คือพื้นผิว descriptor เฉพาะ setup สำหรับ โฟลว์ control-plane/setup ที่ควรคงเป็น metadata-only

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

OpenClaw ยังรวม setup.providers[].envVars ไว้ในการค้นหา provider auth และ env-var ทั่วไปด้วย providerAuthEnvVars ยังรองรับผ่าน compatibility adapter ระหว่างช่วง deprecation แต่ Plugin ที่ไม่ bundled ซึ่งยังใช้ฟิลด์นี้ จะได้รับการวินิจฉัย manifest Plugin ใหม่ควรใส่ metadata env ของ setup/status ไว้ที่ setup.providers[].envVars

OpenClaw ยังสามารถอนุมานตัวเลือก setup แบบเรียบง่ายจาก setup.providers[].authMethods เมื่อไม่มี setup entry หรือเมื่อ setup.requiresRuntime: false ประกาศว่าไม่จำเป็นต้องใช้รันไทม์ setup รายการ providerAuthChoices แบบชัดเจนยังคง เป็นตัวเลือกที่ต้องการสำหรับ label แบบกำหนดเอง, CLI flags, scope ของ onboarding และ metadata ของ assistant

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

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

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

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

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

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

ฟิลด์ setup

อ้างอิง uiHints

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

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

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

อ้างอิง contracts

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "codex"],    "externalAuthProviders": ["acme-ai"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai", "openai-codex"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

แต่ละลิสต์เป็นแบบไม่บังคับ:

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

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

Provider Plugin ที่ implement resolveExternalAuthProfiles ควรประกาศ contracts.externalAuthProviders Plugin ที่ไม่มีการประกาศยังคงรัน ผ่าน fallback ความเข้ากันได้ที่เลิกใช้แล้ว แต่ fallback นั้นช้ากว่าและ จะถูกนำออกหลังช่วง migration

ผู้ให้บริการ memory embedding แบบ bundled ควรประกาศ contracts.memoryEmbeddingProviders สำหรับทุก id adapter ที่เปิดเผย รวมถึง adapter ในตัว เช่น local พาธ CLI แบบ standalone ใช้ contract ใน manifest นี้ เพื่อโหลดเฉพาะ Plugin เจ้าของ ก่อนที่ runtime ของ Gateway แบบเต็มจะ ลงทะเบียนผู้ให้บริการ

อ้างอิง mediaUnderstandingProviderMetadata

ใช้ mediaUnderstandingProviderMetadata เมื่อผู้ให้บริการ media-understanding มี โมเดล default, ลำดับความสำคัญของ auto-auth fallback หรือการรองรับเอกสาร native ที่ helper ของ core แบบทั่วไปต้องใช้ก่อน runtime โหลด คีย์ต้องถูกประกาศใน contracts.mediaUnderstandingProviders ด้วย

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

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

อ้างอิง channelConfigs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ฟิลด์:

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

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

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

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

ฟิลด์ของ provider:

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

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

ฟิลด์ของ endpoint:

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

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

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

ฟิลด์ของ provider:

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

ใช้ modelPricing เมื่อ provider ต้องควบคุมพฤติกรรม pricing ฝั่ง control-plane ก่อน runtime โหลด pricing cache ของ Gateway อ่าน metadata นี้โดยไม่ import โค้ด runtime ของ provider

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

ฟิลด์ของ provider:

ฟิลด์ของ source:

ดัชนี Provider ของ OpenClaw

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Plugin channel ควรให้ openclaw.setupEntry เมื่อ status, รายการ channel, หรือการสแกน SecretRef จำเป็นต้องระบุบัญชีที่ configured โดยไม่โหลด runtime ทั้งหมด entry setup ควรเปิดเผย metadata ของ channel รวมถึง adapter สำหรับ config, status, และ secrets ที่ปลอดภัยต่อ setup; ให้เก็บ network clients, gateway listeners, และ transport runtimes ไว้ใน entrypoint หลักของ extension

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

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

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

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

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

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

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

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

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

OpenClaw ค้นพบ Plugin จาก root หลายแหล่ง (bundled, global install, workspace, path ที่เลือกอย่างชัดเจนด้วย config) หากการค้นพบสองรายการใช้ id เดียวกัน จะเก็บเฉพาะ manifest ที่มี ลำดับความสำคัญสูงสุด เท่านั้น; duplicate ที่มีลำดับความสำคัญต่ำกว่าจะถูกทิ้งแทนที่จะโหลดเคียงข้างกัน

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

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

ผลกระทบ:

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

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

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

ตัวอย่างการขยาย schema:

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

พฤติกรรมการตรวจสอบ

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

ดู ข้อมูลอ้างอิงการกำหนดค่า สำหรับ schema plugins.* ทั้งหมด

หมายเหตุ

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

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