diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md
index d36241c8a7d..0c6864ccea2 100644
--- a/docs/cli/plugins.md
+++ b/docs/cli/plugins.md
@@ -200,6 +200,23 @@ table view to per-plugin detail lines with source/origin/version/activation
 metadata. Use `--json` for machine-readable inventory plus registry
 diagnostics.
 
+`plugins list` runs discovery from the current CLI environment and config. It is
+useful for checking whether a plugin is enabled/loadable, but it is not a live
+runtime probe of an already-running Gateway process. After changing plugin code,
+enablement, hook policy, or `plugins.load.paths`, restart the Gateway that
+serves the channel before expecting new `register(api)` code or hooks to run.
+For remote/container deployments, verify you are restarting the actual
+`openclaw gateway run` child, not only a wrapper process.
+
+For runtime hook debugging:
+
+- `openclaw plugins inspect <id> --json` shows registered hooks and diagnostics
+  from a module-loaded inspection pass.
+- `openclaw gateway status --deep --require-rpc` confirms the reachable Gateway,
+  service/process hints, config path, and RPC health.
+- Non-bundled conversation hooks (`llm_input`, `llm_output`, `agent_end`) require
+  `plugins.entries.<id>.hooks.allowConversationAccess=true`.
+
 Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
 
 ```bash
diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md
index b1ce85d02d2..74780758f3a 100644
--- a/docs/tools/plugin.md
+++ b/docs/tools/plugin.md
@@ -151,6 +151,17 @@ Looking for third-party plugins? See [Community Plugins](/plugins/community).
 Config changes **require a gateway restart**. If the Gateway is running with config
 watch + in-process restart enabled (the default `openclaw gateway` path), that
 restart is usually performed automatically a moment after the config write lands.
+There is no supported hot-reload path for native plugin runtime code or lifecycle
+hooks; restart the Gateway process that is serving the live channel before
+expecting updated `register(api)` code, `api.on(...)` hooks, tools, services, or
+provider/runtime hooks to run.
+
+`openclaw plugins list` is a local CLI/config snapshot. A `loaded` plugin there
+means the plugin is discoverable and loadable from the config/files seen by that
+CLI invocation. It does not prove that an already-running remote Gateway child
+has restarted into the same plugin code. On VPS/container setups with wrapper
+processes, send restarts to the actual `openclaw gateway run` process, or use
+`openclaw gateway restart` against the running Gateway.
 
 <Accordion title="Plugin states: disabled vs missing vs invalid">
   - **Disabled**: plugin exists but enablement rules turned it off. Config is preserved.
@@ -197,6 +208,27 @@ OpenClaw scans for plugins in this order (first match wins):
   app-server plugin is selected by `embeddedHarness.runtime: "codex"` or legacy
   `codex/*` model refs
 
+## Troubleshooting Runtime Hooks
+
+If a plugin appears in `plugins list` but `register(api)` side effects or hooks
+do not run in live chat traffic, check these first:
+
+- Run `openclaw gateway status --deep --require-rpc` and confirm the active
+  Gateway URL, profile, config path, and process are the ones you are editing.
+- Restart the live Gateway after plugin install/config/code changes. In wrapper
+  containers, PID 1 may only be a supervisor; restart or signal the child
+  `openclaw gateway run` process.
+- Use `openclaw plugins inspect <id> --json` to confirm hook registrations and
+  diagnostics. Non-bundled conversation hooks such as `llm_input`,
+  `llm_output`, and `agent_end` need
+  `plugins.entries.<id>.hooks.allowConversationAccess=true`.
+- For model switching, prefer `before_model_resolve`. It runs before model
+  resolution for agent turns; `llm_output` only runs after a model attempt
+  produces assistant output.
+- For proof of the effective session model, use `openclaw sessions` or the
+  Gateway session/status surfaces and, when debugging provider payloads, start
+  the Gateway with `--raw-stream --raw-stream-path <path>`.
+
 ## Plugin slots (exclusive categories)
 
 Some categories are exclusive (only one active at a time):