diff --git a/docs/zh-CN/plugins/hooks.md b/docs/zh-CN/plugins/hooks.md
index eb6197e52..fb2f6e7e6 100644
--- a/docs/zh-CN/plugins/hooks.md
+++ b/docs/zh-CN/plugins/hooks.md
@@ -1,26 +1,26 @@
 ---
 read_when:
-    - 你正在构建一个需要 `before_tool_call`、`before_agent_reply`、消息钩子或生命周期钩子的插件
+    - 你正在构建一个插件，需要 `before_tool_call`、`before_agent_reply`、消息钩子或生命周期钩子
     - 你需要从插件中阻止、重写或要求批准工具调用
     - 你正在内部钩子和插件钩子之间做选择
-summary: 插件钩子：拦截智能体、工具、消息、会话和 Gateway 网关生命周期事件
+summary: 插件钩子：拦截智能体、工具、消息、会话以及 Gateway 网关生命周期事件
 title: 插件钩子
 x-i18n:
-    generated_at: "2026-04-24T18:09:34Z"
+    generated_at: "2026-04-24T18:41:24Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 620f4a4c54c26efbab67b9e466624f8d72789937d7e056b88cdd00022b561943
+    source_hash: 122060cc36dd0ef0be4dbc6bab629742142543ba718fccd7f5a75885e73d43e1
     source_path: plugins/hooks.md
     workflow: 15
 ---
 
-插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装流程或 Gateway 网关启动时，请使用它们。
+插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装过程或 Gateway 网关启动时，请使用它们。
 
-如果你只是想要一个由运维人员安装的小型 `HOOK.md` 脚本，用于处理命令和 Gateway 网关事件，例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`，请改用 [内部钩子](/zh-CN/automation/hooks)。
+如果你想要一个由运维人员安装的、用于命令和 Gateway 网关事件（例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`）的小型 `HOOK.md` 脚本，请改用 [内部钩子](/zh-CN/automation/hooks)。
 
 ## 快速开始
 
-在你的插件入口中使用 `api.on(...)` 注册带类型的插件钩子：
+在你的插件入口中，使用 `api.on(...)` 注册带类型的插件钩子：
 
 ```typescript
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@@ -52,40 +52,40 @@ export default definePluginEntry({
 });
 ```
 
-钩子处理器会按 `priority` 降序依次运行。相同优先级的钩子保持注册顺序。
+钩子处理程序会按 `priority` 降序依次运行。同一优先级的钩子会保持注册顺序。
 
 ## 钩子目录
 
-钩子按其扩展的接口分组。**加粗**的名称接受决策结果（阻止、取消、覆盖或要求批准）；其他钩子仅用于观察。
+钩子按其扩展的表面进行分组。**粗体** 标出的名称接受决策结果（阻止、取消、覆盖或要求批准）；其余都仅用于观察。
 
 **智能体轮次**
 
 - `before_model_resolve` — 在加载会话消息之前覆盖提供商或模型
-- `before_prompt_build` — 在模型调用前添加动态上下文或系统提示词文本
-- `before_agent_start` — 仅为兼容性保留的组合阶段；优先使用上面两个钩子
-- **`before_agent_reply`** — 用合成回复或静默方式短路模型轮次
+- `before_prompt_build` — 在模型调用之前添加动态上下文或 system prompt 文本
+- `before_agent_start` — 仅用于兼容性的组合阶段；优先使用上面的两个钩子
+- **`before_agent_reply`** — 使用合成回复或静默来短路模型轮次
 - `agent_end` — 观察最终消息、成功状态和运行时长
 
-**对话观察**
+**会话观察**
 
-- `llm_input` — 观察提供商输入（系统提示词、提示词、历史记录）
+- `llm_input` — 观察提供商输入（system prompt、prompt、历史记录）
 - `llm_output` — 观察提供商输出
 
 **工具**
 
 - **`before_tool_call`** — 重写工具参数、阻止执行或要求批准
 - `after_tool_call` — 观察工具结果、错误和耗时
-- **`tool_result_persist`** — 重写根据工具结果生成的助手消息
-- **`before_message_write`** — 检查或阻止正在进行的消息写入（较少使用）
+- **`tool_result_persist`** — 重写由工具结果生成的助手消息
+- **`before_message_write`** — 检查或阻止进行中的消息写入（较少见）
 
 **消息与投递**
 
-- **`inbound_claim`** — 在智能体路由前声明一条入站消息（合成回复）
+- **`inbound_claim`** — 在智能体路由之前认领入站消息（合成回复）
 - `message_received` — 观察入站内容、发送者、线程和元数据
 - **`message_sending`** — 重写出站内容或取消投递
 - `message_sent` — 观察出站投递成功或失败
-- **`before_dispatch`** — 在移交给渠道前检查或重写一次出站分发
-- **`reply_dispatch`** — 参与最终回复分发流水线
+- **`before_dispatch`** — 在交给渠道之前检查或重写出站分发
+- **`reply_dispatch`** — 参与最终的回复分发流水线
 
 **会话与压缩**
 
@@ -104,13 +104,13 @@ export default definePluginEntry({
 
 ## 工具调用策略
 
-`before_tool_call` 接收：
+`before_tool_call` 会接收：
 
 - `event.toolName`
 - `event.params`
 - 可选的 `event.runId`
 - 可选的 `event.toolCallId`
-- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`，以及诊断用的 `ctx.trace`
+- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`，以及诊断字段 `ctx.trace`
 
 它可以返回：
 
@@ -135,23 +135,25 @@ type BeforeToolCallResult = {
 
 规则：
 
-- `block: true` 是终止性的，并会跳过更低优先级的处理器。
-- `block: false` 会被视为没有决策。
-- `params` 会重写执行时的工具参数。
-- `requireApproval` 会暂停智能体运行，并通过插件审批向用户发起请求。`/approve` 命令既可批准 exec 审批，也可批准插件审批。
-- 即使更高优先级的钩子请求了批准，更低优先级的 `block: true` 仍然可以阻止执行。
-- `onResolution` 会收到最终解析的审批决定 —— `allow-once`、`allow-always`、`deny`、`timeout` 或 `cancelled`。
+- `block: true` 是终止性的，并会跳过更低优先级的处理程序。
+- `block: false` 会被视为没有作出决定。
+- `params` 会重写执行时使用的工具参数。
+- `requireApproval` 会暂停智能体运行，并通过插件批准机制向用户发起请求。`/approve` 命令既可以批准 exec 批准，也可以批准插件批准。
+- 即使更高优先级的钩子请求了批准，更低优先级的 `block: true` 仍然可以阻止调用。
+- `onResolution` 会接收最终的批准决定——`allow-once`、`allow-always`、`deny`、`timeout` 或 `cancelled`。
 
-## 提示词和模型钩子
+## Prompt 和模型钩子
 
-新插件请使用特定阶段的钩子：
+对于新插件，请使用按阶段划分的钩子：
 
-- `before_model_resolve`：只接收当前提示词和附件元数据。返回 `providerOverride` 或 `modelOverride`。
-- `before_prompt_build`：接收当前提示词和会话消息。返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。
+- `before_model_resolve`：仅接收当前 prompt 和附件元数据。返回 `providerOverride` 或 `modelOverride`。
+- `before_prompt_build`：接收当前 prompt 和会话消息。返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。
 
-`before_agent_start` 仍然保留用于兼容性。优先使用上述显式钩子，这样你的插件就不会依赖旧版组合阶段。
+`before_agent_start` 仍然保留用于兼容性。优先使用上面的显式钩子，这样你的插件就不会依赖旧版的组合阶段。
 
-需要 `llm_input`、`llm_output` 或 `agent_end` 的非内置插件必须设置：
+当 OpenClaw 能识别当前活跃运行时，`before_agent_start` 和 `agent_end` 会包含 `event.runId`。同一个值也可通过 `ctx.runId` 获取。
+
+需要使用 `llm_input`、`llm_output` 或 `agent_end` 的非内置插件必须设置：
 
 ```json
 {
@@ -167,38 +169,41 @@ type BeforeToolCallResult = {
 }
 ```
 
-可修改提示词的钩子可以按插件通过 `plugins.entries.<id>.hooks.allowPromptInjection=false` 禁用。
+可变更 prompt 的钩子可以按插件禁用，方式是设置 `plugins.entries.<id>.hooks.allowPromptInjection=false`。
 
 ## 消息钩子
 
 将消息钩子用于渠道级路由和投递策略：
 
-- `message_received`：观察入站内容、发送者、`threadId` 和元数据。
+- `message_received`：观察入站内容、发送者、`threadId`、`messageId`、`senderId`、可选的运行/会话关联信息，以及元数据。
 - `message_sending`：重写 `content` 或返回 `{ cancel: true }`。
 - `message_sent`：观察最终成功或失败。
 
+消息钩子上下文会在可用时公开稳定的关联字段：
+`ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、
+`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。在读取旧版元数据之前，优先使用这些一等字段。
+
 在使用渠道特定元数据之前，优先使用带类型的 `threadId` 和 `replyToId` 字段。
 
 决策规则：
 
 - 带有 `cancel: true` 的 `message_sending` 是终止性的。
-- 带有 `cancel: false` 的 `message_sending` 会被视为没有决策。
+- 带有 `cancel: false` 的 `message_sending` 会被视为没有作出决定。
 - 被重写的 `content` 会继续传递给更低优先级的钩子，除非后续钩子取消投递。
 
 ## 安装钩子
 
-`before_install` 会在内置的 Skills 和插件安装扫描之后运行。
-返回额外发现项，或返回 `{ block: true, blockReason }` 以停止安装。
+`before_install` 会在内置的 Skills 和插件安装扫描之后运行。返回额外发现项，或返回 `{ block: true, blockReason }` 以停止安装。
 
-`block: true` 是终止性的。`block: false` 会被视为没有决策。
+`block: true` 是终止性的。`block: false` 会被视为没有作出决定。
 
 ## Gateway 网关生命周期
 
-对于需要使用 Gateway 网关拥有状态的插件服务，请使用 `gateway_start`。其上下文暴露 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，可用于检查和更新 cron。使用 `gateway_stop` 清理长时间运行的资源。
+对需要 Gateway 网关拥有状态的插件服务，请使用 `gateway_start`。上下文会公开 `ctx.config`、`ctx.workspaceDir` 以及用于检查和更新 cron 的 `ctx.getCron?.()`。使用 `gateway_stop` 清理长时间运行的资源。
 
-不要依赖内部的 `gateway:startup` 钩子来运行插件拥有的运行时服务。
+不要依赖内部的 `gateway:startup` 钩子来实现插件拥有的运行时服务。
 
-## 相关
+## 相关内容
 
 - [构建插件](/zh-CN/plugins/building-plugins)
 - [插件 SDK 概览](/zh-CN/plugins/sdk-overview)