diff --git a/src/agent-sec-core/docs/guide/OPENCLAW_COMPAT_DEPLOY_UPGRADE_CN.md b/src/agent-sec-core/docs/guide/OPENCLAW_COMPAT_DEPLOY_UPGRADE_CN.md
new file mode 100644
index 000000000..36471af45
--- /dev/null
+++ b/src/agent-sec-core/docs/guide/OPENCLAW_COMPAT_DEPLOY_UPGRADE_CN.md
@@ -0,0 +1,293 @@
+# OpenClaw 兼容部署与升级指南
+
+本文说明如何部署、升级、回滚和排查 AgentSecCore OpenClaw plugin。
+
+## 适用范围
+
+AgentSecCore OpenClaw plugin 的 OpenClaw host 兼容边界是 `>=2026.4.14`。
+该边界在以下位置保持一致：
+
+- `openclaw-plugin/package.json` 的 `openclaw.install.minHostVersion`
+- `openclaw-plugin/package.json` 的 `openclaw.compat.pluginApi`
+- `openclaw-plugin/package.json` 的 `peerDependencies.openclaw`
+
+当前 e2e 流水线已验证以下 OpenClaw host 矩阵：
+
+| OpenClaw host | 验证结果 |
+|---------------|----------|
+| `2026.4.14` | 通过 |
+| `2026.4.23` | 通过 |
+| `2026.4.24` | 通过 |
+| `2026.4.29` | 通过 |
+| `2026.5.7` | 通过 |
+| `2026.5.28` | 通过 |
+| `2026.6.10` | 通过 |
+| `latest` | 通过 |
+
+验证证据：GitHub Actions `OpenClaw Plugin E2E` run `28774739252`。
+
+## 前置条件
+
+部署主机需要具备：
+
+- `openclaw`
+- `agent-sec-cli`
+- `jq`
+- 已构建的 OpenClaw plugin `dist/index.js`
+- `openclaw-plugin/openclaw.plugin.json`
+
+`deploy.sh` 会在执行前检查这些条件；缺失时会直接失败并打印原因。
+
+## 从源码部署
+
+在 `agent-sec-core` 仓库根目录执行：
+
+```bash
+make build-openclaw-plugin
+```
+
+该目标会构建 TypeScript，并把 `openclaw.plugin.json`、`package.json`、
+`dist/` 和 `scripts/` 放入 `target/openclaw-plugin/`。
+
+然后安装到目标目录。默认源码安装路径由 Makefile 变量
+`OPENCLAW_PLUGIN_DIR` 控制，默认值是
+`/usr/local/lib/anolisa/sec-core/openclaw-plugin`：
+
+```bash
+sudo make install-openclaw-plugin
+```
+
+最后运行 deploy 脚本注册插件：
+
+```bash
+sudo /usr/local/lib/anolisa/sec-core/openclaw-plugin/scripts/deploy.sh \
+    /usr/local/lib/anolisa/sec-core/openclaw-plugin
+```
+
+如果要安装到 RPM profile 使用的路径，显式传入 `OPENCLAW_PLUGIN_DIR`：
+
+```bash
+sudo make install-openclaw-plugin OPENCLAW_PLUGIN_DIR=/opt/agent-sec/openclaw-plugin
+sudo /opt/agent-sec/openclaw-plugin/scripts/deploy.sh \
+    /opt/agent-sec/openclaw-plugin
+```
+
+源码开发环境也可以直接在插件目录内构建和部署：
+
+```bash
+cd openclaw-plugin
+npm install
+npm run build
+./scripts/deploy.sh "$(pwd)"
+```
+
+如果 OpenClaw 使用非默认 state directory，部署时传入 `OPENCLAW_STATE_DIR`：
+
+```bash
+OPENCLAW_STATE_DIR=~/.openclaw-dev ./scripts/deploy.sh "$(pwd)"
+```
+
+## deploy.sh 做了什么
+
+`deploy.sh` 负责安装期兼容处理：
+
+- 读取 `openclaw --version`，要求 OpenClaw `>=2026.4.14`
+- 读取 `openclaw plugins install --help`，确认支持 `--force`
+- 如果当前 OpenClaw installer help 暴露 `--dangerously-force-unsafe-install`，安装时传入该参数
+- 如果当前 OpenClaw installer help 不暴露该参数，安装时不传入
+- OpenClaw `>=2026.4.24` 时写入 `plugins.entries.agent-sec.hooks.allowConversationAccess=true`
+- OpenClaw `2026.4.14` 到 `2026.4.23` 跳过 `allowConversationAccess`
+- 使用 `openclaw plugins inspect agent-sec --json` 校验安装记录
+- 当当前 OpenClaw 支持 `plugins inspect --runtime` 时，使用 `openclaw plugins inspect agent-sec --runtime --json` 校验运行时加载
+- 校验到插件状态不是 `loaded` 时失败
+
+`deploy.sh` 不会启动、停止或重启 OpenClaw gateway。
+
+## 重启 Gateway
+
+部署或升级插件后，重启 OpenClaw gateway：
+
+```bash
+openclaw gateway restart
+```
+
+如果环境使用 systemd user service，使用对应服务重启命令：
+
+```bash
+systemctl --user restart openclaw-gateway-dev.service
+```
+
+## 验证安装
+
+先验证 OpenClaw 安装记录：
+
+```bash
+openclaw plugins inspect agent-sec --json | jq -e '.plugin.id == "agent-sec"'
+```
+
+如果当前 OpenClaw 支持 runtime inspect，再验证运行时加载：
+
+```bash
+openclaw plugins inspect agent-sec --runtime --json | jq -e '.plugin.status == "loaded"'
+```
+
+不支持 `--runtime` 的 OpenClaw 版本使用普通 inspect 的 `plugin.status`：
+
+```bash
+openclaw plugins inspect agent-sec --json | jq -e '.plugin.status == "loaded"'
+```
+
+OpenClaw `>=2026.4.24` 部署后，还应确认配置中存在：
+
+```bash
+openclaw config get plugins.entries.agent-sec.hooks.allowConversationAccess
+```
+
+期望值为 `true`。
+
+## 默认安全策略
+
+默认配置是观察优先：
+
+- `promptScanBlock=false`：prompt scanner 检测到 `deny` 时记录告警，但不阻断模型调用
+- `codeScanRequireApproval=false`：code scanner 检测到风险时记录告警，但不弹审批
+- `piiScanUserInput=true`：扫描用户输入中的 PII 和凭据
+- `piiIncludeLowConfidence=false`：不包含低置信度 PII findings
+- `pii-scan-user-input.enableBlock=false`：PII deny 默认不阻断
+- `skill-ledger.policy=ask`：有用户可见消息时优先要求确认
+- `observability.enabled=true`：启用观测记录
+
+启用 prompt 阻断：
+
+```bash
+openclaw config set plugins.entries.agent-sec.config.promptScanBlock true
+```
+
+启用代码扫描审批：
+
+```bash
+openclaw config set plugins.entries.agent-sec.config.codeScanRequireApproval true
+```
+
+启用 PII deny 阻断：
+
+```bash
+openclaw config set 'plugins.entries.agent-sec.config.capabilities.pii-scan-user-input.enableBlock' true
+```
+
+配置 Skill Ledger 为直接阻断：
+
+```bash
+openclaw config set 'plugins.entries.agent-sec.config.capabilities.skill-ledger.policy' block
+```
+
+## 运行时兼容策略
+
+不要为旧版 OpenClaw 写入持久化 hook disable 配置。
+
+AgentSecCore 的策略是：
+
+- `before_dispatch`、`before_tool_call`、`after_tool_call` 是支持矩阵内的核心安全 hook
+- `model_call_started`、`model_call_ended` 属于可选模型调用观测 hook
+- `llm_input`、`llm_output`、`agent_end` 需要 `allowConversationAccess`
+- 旧版 OpenClaw 缺失可选观测 hook 时，插件允许观测能力降级
+- 用户升级 OpenClaw 后，重新运行 `deploy.sh` 并重启 gateway，即可获得新版本支持的 hook 行为
+
+如果把缺失 hook 写成持久化禁用配置，升级 OpenClaw 后这些 hook 可能仍被旧配置禁用，因此不要这么做。
+
+## 升级流程
+
+升级 AgentSecCore OpenClaw plugin：
+
+```bash
+make build-openclaw-plugin
+sudo make install-openclaw-plugin
+sudo /usr/local/lib/anolisa/sec-core/openclaw-plugin/scripts/deploy.sh \
+    /usr/local/lib/anolisa/sec-core/openclaw-plugin
+openclaw gateway restart
+```
+
+升级 OpenClaw host 后，也要重新运行 `deploy.sh`：
+
+```bash
+sudo /usr/local/lib/anolisa/sec-core/openclaw-plugin/scripts/deploy.sh \
+    /usr/local/lib/anolisa/sec-core/openclaw-plugin
+openclaw gateway restart
+```
+
+原因是新版 OpenClaw 可能支持旧版本没有的配置或 hook，例如
+`plugins.entries.agent-sec.hooks.allowConversationAccess`。
+
+## 回滚流程
+
+如果新版本插件部署后需要回滚：
+
+1. 将旧版本 plugin 目录恢复到目标路径。
+2. 重新运行旧版本目录中的 `deploy.sh`。
+3. 重启 OpenClaw gateway。
+4. 使用 `openclaw plugins inspect agent-sec --json` 和 runtime inspect 校验状态。
+
+示例：
+
+```bash
+sudo /usr/local/lib/anolisa/sec-core/openclaw-plugin/scripts/deploy.sh \
+    /usr/local/lib/anolisa/sec-core/openclaw-plugin
+openclaw gateway restart
+openclaw plugins inspect agent-sec --json | jq -e '.plugin.id == "agent-sec"'
+```
+
+## 常见问题
+
+### 插件安装失败
+
+先确认命令可用：
+
+```bash
+openclaw --version
+agent-sec-cli --help
+jq --version
+```
+
+再确认 plugin 目录存在：
+
+```bash
+test -f /usr/local/lib/anolisa/sec-core/openclaw-plugin/openclaw.plugin.json
+test -f /usr/local/lib/anolisa/sec-core/openclaw-plugin/dist/index.js
+```
+
+### runtime inspect 不是 loaded
+
+执行：
+
+```bash
+openclaw plugins inspect agent-sec --runtime --json
+```
+
+查看 `diagnostics`。如果当前 OpenClaw 不支持 `--runtime`，使用：
+
+```bash
+openclaw plugins inspect agent-sec --json
+```
+
+### 会话观测 hook 被阻止
+
+OpenClaw `>=2026.4.24` 需要：
+
+```bash
+openclaw config set plugins.entries.agent-sec.hooks.allowConversationAccess true
+openclaw gateway restart
+```
+
+OpenClaw `2026.4.14` 到 `2026.4.23` 不支持该配置。核心安全 hook 仍应可用，但会话级观测 hook 会降级。
+
+### 升级 OpenClaw 后观测能力没有变化
+
+重新运行：
+
+```bash
+sudo /usr/local/lib/anolisa/sec-core/openclaw-plugin/scripts/deploy.sh \
+    /usr/local/lib/anolisa/sec-core/openclaw-plugin
+openclaw gateway restart
+```
+
+不要手动保留旧版本下写入的 hook disable 配置。
diff --git a/src/agent-sec-core/openclaw-plugin/README.md b/src/agent-sec-core/openclaw-plugin/README.md
index 0a04a627f..4eb2405af 100644
--- a/src/agent-sec-core/openclaw-plugin/README.md
+++ b/src/agent-sec-core/openclaw-plugin/README.md
@@ -26,6 +26,8 @@ The installable package declares the OpenClaw compatibility boundary in `package
 
 Package entrypoints follow the current OpenClaw plugin contract: `openclaw.extensions` points at the TypeScript source entry for checkout development, and `openclaw.runtimeExtensions` points at the built JavaScript entry used by installed packages. `openclaw.plugin.json` keeps its legacy `extensions` declaration pointed at the same built runtime entry for older manifest readers.
 
+中文部署与升级指南：[docs/guide/OPENCLAW_COMPAT_DEPLOY_UPGRADE_CN.md](../docs/guide/OPENCLAW_COMPAT_DEPLOY_UPGRADE_CN.md)。
+
 ---
 
 ## Project Structure
@@ -135,17 +137,20 @@ cd src/agent-sec-core
 # Build the plugin
 make build-openclaw-plugin
 
-# Install files to /opt/agent-sec/openclaw-plugin/
+# Install files to the default source-build path:
+# /usr/local/lib/anolisa/sec-core/openclaw-plugin/
 sudo make install-openclaw-plugin
 
 # Register the plugin with OpenClaw
-sudo /opt/agent-sec/openclaw-plugin/scripts/deploy.sh /opt/agent-sec/openclaw-plugin
+sudo /usr/local/lib/anolisa/sec-core/openclaw-plugin/scripts/deploy.sh \
+    /usr/local/lib/anolisa/sec-core/openclaw-plugin
 
 # Restart gateway to load the plugin
 openclaw gateway restart
 ```
 
 > **Note:** `make install-openclaw-plugin` only copies files. You must run `deploy.sh` separately to register the plugin.
+> To install into `/opt/agent-sec/openclaw-plugin`, pass `OPENCLAW_PLUGIN_DIR=/opt/agent-sec/openclaw-plugin` to `make install-openclaw-plugin`.
 
 ---
 
@@ -153,12 +158,16 @@ openclaw gateway restart
 
 The deployment script performs these steps:
 
-1. **Pre-checks** — Verifies `openclaw` and `agent-sec-cli` are in PATH; validates `openclaw.plugin.json` and `dist/` exist
-2. **Plugin installation** — Runs `openclaw plugins install <path> --force --dangerously-force-unsafe-install` to register the plugin
-3. **Conversation access policy** — Sets `plugins.entries.agent-sec.hooks.allowConversationAccess=true` so conversation observability hooks can register
-4. **User guidance** — Displays instructions to restart the OpenClaw gateway (does NOT restart automatically)
+1. **Pre-checks** — Verifies `agent-sec-cli` and `jq` are in PATH; validates `openclaw.plugin.json`, `dist/`, and `dist/index.js` exist
+2. **OpenClaw version check** — Reads `openclaw --version` and requires OpenClaw `>=2026.4.14`
+3. **Installer capability check** — Reads `openclaw plugins install --help`, requires `--force`, and detects whether `--dangerously-force-unsafe-install` is available
+4. **Inspect capability check** — Reads `openclaw plugins inspect --help`, requires `--json`, and detects whether `--runtime` is available
+5. **Plugin installation** — Runs `openclaw plugins install <path> --force`, adding `--dangerously-force-unsafe-install` only when the current installer advertises that compatibility flag
+6. **Conversation access policy** — Sets `plugins.entries.agent-sec.hooks.allowConversationAccess=true` on OpenClaw `>=2026.4.24`; older supported hosts skip it and degrade conversation observability hooks
+7. **Runtime verification** — Uses `openclaw plugins inspect agent-sec --runtime --json` when supported, otherwise `openclaw plugins inspect agent-sec --json`, and fails unless the plugin status is `loaded`
+8. **User guidance** — Displays instructions to restart the OpenClaw gateway and optional policy commands (does NOT restart automatically)
 
-> **Important:** `deploy.sh` installs the plugin and applies required OpenClaw config. It does **NOT** start/stop/restart the gateway service.
+> **Important:** `deploy.sh` installs the plugin, applies supported OpenClaw config, and verifies the plugin load status. It does **NOT** start/stop/restart the gateway service.
 > 
 > To restart the gateway:
 > ```bash
@@ -167,55 +176,40 @@ The deployment script performs these steps:
 > systemctl --user restart openclaw-gateway-dev.service  # If using systemd user service
 > ```
 
-### Custom Config Path
+### Custom State Directory
 
 ```bash
-OPENCLAW_CONFIG=~/.openclaw-dev/openclaw.json ./scripts/deploy.sh "$(pwd)"
+OPENCLAW_STATE_DIR=~/.openclaw-dev ./scripts/deploy.sh "$(pwd)"
 ```
 
 ---
 
 ## Verify Installation
 
-After deployment, verify the plugin is loaded:
+First verify the OpenClaw install record:
 
 ```bash
-openclaw plugins inspect agent-sec
+openclaw plugins inspect agent-sec --json | jq -e '.plugin.id == "agent-sec"'
 ```
 
-Expected output:
+If the current OpenClaw supports runtime inspect, verify the runtime load state:
 
-```
-Agent Security
-id: agent-sec
-Security hooks powered by agent-sec-cli
-
-Status: loaded
-Version: 0.x.y
-Source: ~/path/to/openclaw-plugin/dist/index.js
-
-Typed hooks:
-before_dispatch (priority 200)
-before_dispatch (priority 190)
-llm_input (priority 1000)
-model_call_started (priority 1000)
-model_call_ended (priority 1000)
-llm_output (priority 1000)
-agent_end (priority 1000)
-before_tool_call (priority 80)
-before_tool_call (priority 0)
-before_tool_call (priority -10000)
-after_tool_call (priority 1000)
+```bash
+openclaw plugins inspect agent-sec --runtime --json | jq -e '.plugin.status == "loaded"'
 ```
 
-Also check the plugin is activated by gateway after openclaw **v2026.4.25**
-```
-openclaw gateway call health --params '{"probe":true}' --json | jq -e '(.plugins.loaded // []) | index("agent-sec") != null'
-```
-Expected output:
+Older supported OpenClaw versions that do not support `--runtime` use the ordinary inspect status:
+
+```bash
+openclaw plugins inspect agent-sec --json | jq -e '.plugin.status == "loaded"'
 ```
-true
+
+OpenClaw `>=2026.4.24` should also have conversation access enabled:
+
+```bash
+openclaw config get plugins.entries.agent-sec.hooks.allowConversationAccess
 ```
+
 ---
 
 ## Testing
@@ -395,7 +389,8 @@ make build-openclaw-plugin
 sudo make install-openclaw-plugin
 
 # Re-register plugin
-sudo /opt/agent-sec/openclaw-plugin/scripts/deploy.sh /opt/agent-sec/openclaw-plugin
+sudo /usr/local/lib/anolisa/sec-core/openclaw-plugin/scripts/deploy.sh \
+    /usr/local/lib/anolisa/sec-core/openclaw-plugin
 
 # Restart gateway
 openclaw gateway restart