From c36a493e80bfee98338b860d43b4877bfa4d3415 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 17 Mar 2026 23:27:18 -0700 Subject: [PATCH] Docs: clarify plugin compatibility signals --- docs/tools/plugin.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index e04c30f6003..a66579c9328 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -173,6 +173,28 @@ Direction: - prefer `before_prompt_build` for prompt mutation work - remove only after real usage drops and fixture coverage proves migration safety +### Compatibility signals + +OpenClaw treats config validity and plugin migration state as separate axes: + +- **config valid** — the config parses and referenced plugins can be resolved +- **compatibility advisory** — a plugin is still on a supported compatibility + path, such as `hook-only` +- **legacy warning** — a plugin still uses `before_agent_start` +- **hard error** — the config is invalid or plugin loading/validation fails + +Current compatibility guidance: + +- `hook-only` is advisory only. It remains a supported compatibility path for + existing plugins. +- `before_agent_start` is the only strong migration warning in the current + model. +- Neither state blocks an existing plugin by itself. + +You can see these signals in `openclaw doctor`, `openclaw status`, +`openclaw status --all`, `openclaw plugins doctor`, and +`openclaw plugins inspect `. + ## Architecture OpenClaw's plugin system has four layers: