chore(i18n): refresh zh-CN translations

2026-04-26 20:48:24 +00:00 · 2026-04-26 20:48:24 +00:00 · a7d36dde32
commit a7d36dde32
parent 56502e48c6
2 changed files with 150 additions and 109 deletions
--- a/docs/zh-CN/gateway/opentelemetry.md
+++ b/docs/zh-CN/gateway/opentelemetry.md
@ -3,25 +3,31 @@ read_when:
    - 你想将 OpenClaw 模型使用情况、消息流或会话指标发送到 OpenTelemetry 收集器
    - 你正在将追踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端
    - 你需要确切的指标名称、span 名称或属性结构来构建仪表板或告警
-summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断数据导出到任意 OpenTelemetry 收集器
+summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断信息导出到任何 OpenTelemetry 收集器
 title: OpenTelemetry 导出
 x-i18n:
-    generated_at: "2026-04-26T19:56:12Z"
+    generated_at: "2026-04-26T20:47:25Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 379e0cada90888a3703785147d62ebe418f48216169577443cc8c95dc2a9fff8
+    source_hash: 4c0462a19d5eebde92f87fef3d26dfe7338c3d446caf4b8c7097eb1a13a278fe
    source_path: gateway/opentelemetry.md
    workflow: 15
 ---

-OpenClaw 通过内置的 `diagnostics-otel` 插件使用 **OTLP/HTTP（protobuf）** 导出诊断数据。任何接受 OTLP/HTTP 的收集器或后端都可以直接使用，无需修改代码。关于本地文件日志及其读取方式，请参见 [日志](/zh-CN/logging)。
+OpenClaw 通过内置的 `diagnostics-otel` 插件导出诊断信息，
+使用 **OTLP/HTTP（protobuf）**。任何接受 OTLP/HTTP 的收集器或后端
+都可以直接使用，无需修改代码。有关本地文件日志及其读取方式，请参阅
+[日志记录](/zh-CN/logging)。

-## 工作原理
+## 它如何协同工作

- **诊断事件** 是由 Gateway 网关和内置插件发出的结构化进程内记录，用于模型运行、消息流、会话、队列和 exec。
- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将其导出为 OpenTelemetry **指标**、**追踪** 和 **日志**。
- 当提供商传输支持自定义请求头时，**提供商调用** 会从 OpenClaw 受信任的模型调用 span 上下文中接收一个 W3C `traceparent` 请求头。插件发出的追踪上下文不会被传播。
- 只有在诊断功能面和插件都启用时，导出器才会附加，因此默认情况下进程内开销几乎为零。
+- **诊断事件** 是由 Gateway 网关和内置插件发出的结构化进程内记录，
+  用于模型运行、消息流、会话、队列和 exec。
+- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将其导出为
+  OpenTelemetry **指标**、**追踪** 和 **日志**。
+- **提供商调用** 会从 OpenClaw 受信任的模型调用 span 上下文接收一个 W3C
+  `traceparent` 请求头，前提是提供商传输层接受自定义请求头。插件发出的追踪上下文不会被传播。
+- 只有在诊断表面和插件都启用时，导出器才会附加，因此默认情况下进程内开销几乎为零。

 ## 快速开始

@ -60,15 +66,16 @@ openclaw plugins enable diagnostics-otel
 `protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。
 </Note>

-## 导出的信号
+## 已导出的信号

-| 信号 | 包含内容 |
+| 信号 | 其中包含的内容 |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | **指标** | 用于 token 使用量、成本、运行时长、消息流、队列通道、会话状态、exec 和内存压力的计数器与直方图。 |
-| **追踪** | 用于模型使用、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 span。 |
+| **追踪** | 用于模型使用、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 spans。 |
 | **日志** | 当启用 `diagnostics.otel.logs` 时，通过 OTLP 导出的结构化 `logging.file` 记录。 |

-可以分别切换 `traces`、`metrics` 和 `logs`。当 `diagnostics.otel.enabled` 为 true 时，这三者默认都会开启。
+你可以独立切换 `traces`、`metrics` 和 `logs`。当
+`diagnostics.otel.enabled` 为 true 时，这三者默认都开启。

 ## 配置参考

@ -107,20 +114,26 @@ openclaw plugins enable diagnostics-otel

 | 变量 | 用途 |
 | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果该值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则按原样使用。 |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当对应的 `diagnostics.otel.*Endpoint` 配置键未设置时，用作按信号区分的 endpoint 覆盖。按信号区分的配置优先于按信号区分的环境变量，后者优先于共享 endpoint。 |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果该值已经包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则按原样使用。 |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当对应的 `diagnostics.otel.*Endpoint` 配置键未设置时，使用按信号区分的端点覆盖。信号专用配置优先于信号专用环境变量，后者优先于共享端点。 |
 | `OTEL_SERVICE_NAME` | 覆盖 `diagnostics.otel.serviceName`。 |
-| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖线协议（当前仅 `http/protobuf` 会生效）。 |
-| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental`，以发出最新的实验性 GenAI span 属性 `gen_ai.provider.name`，而不是旧版的 `gen_ai.system`。GenAI 指标始终使用有界、低基数的语义属性。 |
-| `OPENCLAW_OTEL_PRELOADED` | 当另一个预加载项或宿主进程已注册全局 OpenTelemetry SDK 时，将其设置为 `1`。这样插件会跳过自身的 NodeSDK 生命周期，但仍会连接诊断监听器并遵循 `traces`/`metrics`/`logs`。 |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖线协议（当前仅支持 `http/protobuf`）。 |
+| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental` 时，会发出最新的实验性 GenAI span 属性（`gen_ai.provider.name`），而不是旧版的 `gen_ai.system`。无论如何，GenAI 指标始终使用有界、低基数的语义属性。 |
+| `OPENCLAW_OTEL_PRELOADED` | 当另一个预加载项或宿主进程已经注册了全局 OpenTelemetry SDK 时，将其设置为 `1`。这样插件会跳过自身的 NodeSDK 生命周期，但仍会连接诊断监听器并遵循 `traces`/`metrics`/`logs`。 |

-## 隐私与内容采集
+## 隐私与内容捕获

-默认**不会**导出原始模型/工具内容。span 携带的是有界标识符（渠道、提供商、模型、错误类别、仅哈希的请求 id），绝不包含提示词文本、响应文本、工具输入、工具输出或会话键。
+默认情况下，原始模型/工具内容 **不会** 被导出。Spans 仅携带有界
+标识符（渠道、提供商、模型、错误类别、仅哈希的请求 id），
+绝不会包含提示文本、响应文本、工具输入、工具输出或会话键。

-出站模型请求可能包含 W3C `traceparent` 请求头。该请求头仅根据 OpenClaw 自有的活动模型调用诊断追踪上下文生成。现有的调用方提供的 `traceparent` 请求头会被替换，因此插件或自定义提供商选项无法伪造跨服务追踪祖先关系。
+出站模型请求可能包含 W3C `traceparent` 请求头。该请求头
+仅根据 OpenClaw 自有的活动模型调用诊断追踪上下文生成。
+现有调用方提供的 `traceparent` 请求头会被替换，因此插件或
+自定义提供商选项无法伪造跨服务追踪祖先关系。

-仅当你的收集器和保留策略已获准存储提示词、响应、工具或系统提示文本时，才将 `diagnostics.otel.captureContent.*` 设为 `true`。每个子键都需要单独选择加入：
+仅当你的收集器和保留策略已获批准，可用于提示词、响应、工具或系统提示
+文本时，才将 `diagnostics.otel.captureContent.*` 设为 `true`。每个子键都需要单独选择启用：

 - `inputMessages` — 用户提示内容。
 - `outputMessages` — 模型响应内容。
@ -128,16 +141,22 @@ openclaw plugins enable diagnostics-otel
 - `toolOutputs` — 工具结果负载。
 - `systemPrompt` — 组装后的 system/developer 提示词。

-当任一子键启用时，模型和工具 span 会仅针对该类内容附加有界、已脱敏的 `openclaw.content.*` 属性。
+启用任意子键后，模型和工具 spans 将仅为该类别附加有界、已脱敏的
+`openclaw.content.*` 属性。

 ## 采样与刷新

- **追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 表示全部丢弃，`1.0` 表示全部保留）。
- **指标：** `diagnostics.otel.flushIntervalMs`（最小值为 `1000`）。
- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用诊断日志记录脱敏路径，而不是控制台格式化。高流量部署应优先使用 OTLP 收集器采样/过滤，而不是本地采样。
- **文件日志关联：** 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志会包含顶层的 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，这样日志处理器就可以将本地日志行与导出的 span 关联起来。
+- **追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 全部丢弃，
+  `1.0` 全部保留）。
+- **指标：** `diagnostics.otel.flushIntervalMs`（最小值 `1000`）。
+- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用
+  诊断日志记录脱敏路径，而不是控制台格式化。高流量安装应优先使用
+  OTLP 收集器采样/过滤，而不是本地采样。
+- **文件日志关联：** 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志会包含顶层
+  `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，
+  这使日志处理器能够将本地日志行与导出的 spans 关联起来。

-## 导出的指标
+## 已导出的指标

 ### 模型使用情况

@ -146,7 +165,11 @@ openclaw plugins enable diagnostics-otel
 - `openclaw.run.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
 - `openclaw.context.tokens`（直方图，属性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
 - `gen_ai.client.token.usage`（直方图，GenAI 语义约定指标，属性：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`）
- `gen_ai.client.operation.duration`（直方图，单位为秒，GenAI 语义约定指标，属性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`、可选的 `error.type`）
+- `gen_ai.client.operation.duration`（直方图，单位为秒，GenAI 语义约定指标，属性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`，可选 `error.type`）
+- `openclaw.model_call.duration_ms`（直方图，属性：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`）
+- `openclaw.model_call.request_bytes`（直方图，最终模型请求负载的 UTF-8 字节大小；不包含原始负载内容）
+- `openclaw.model_call.response_bytes`（直方图，流式模型响应事件的 UTF-8 字节大小；不包含原始响应内容）
+- `openclaw.model_call.time_to_first_byte_ms`（直方图，第一个流式响应事件到达前的耗时）

 ### 消息流

@ -172,13 +195,13 @@ openclaw plugins enable diagnostics-otel

 ### Harness 生命周期

- `openclaw.harness.duration_ms`（直方图，属性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，出错时还包括 `openclaw.harness.phase`）
+- `openclaw.harness.duration_ms`（直方图，属性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，错误时包含 `openclaw.harness.phase`）

 ### Exec

 - `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`）

-### 诊断内部指标（内存与工具循环）
+### 诊断内部机制（内存和工具循环）

 - `openclaw.memory.heap_used_bytes`（直方图，属性：`openclaw.memory.kind`）
 - `openclaw.memory.rss_bytes`（直方图）
@ -186,19 +209,20 @@ openclaw plugins enable diagnostics-otel
 - `openclaw.tool.loop.iterations`（计数器，属性：`openclaw.toolName`、`openclaw.outcome`）
 - `openclaw.tool.loop.duration_ms`（直方图，属性：`openclaw.toolName`、`openclaw.outcome`）

-## 导出的 span
+## 已导出的 spans

 - `openclaw.model.usage`
  - `openclaw.channel`、`openclaw.provider`、`openclaw.model`
  - `openclaw.tokens.*`（input/output/cache_read/cache_write/total）
-  - 默认使用 `gen_ai.system`，或者在启用最新 GenAI 语义约定时使用 `gen_ai.provider.name`
+  - 默认使用 `gen_ai.system`，或者在选择启用最新的 GenAI 语义约定时使用 `gen_ai.provider.name`
  - `gen_ai.request.model`、`gen_ai.operation.name`、`gen_ai.usage.*`
 - `openclaw.run`
  - `openclaw.outcome`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.errorCategory`
 - `openclaw.model.call`
-  - 默认使用 `gen_ai.system`，或者在启用最新 GenAI 语义约定时使用 `gen_ai.provider.name`
+  - 默认使用 `gen_ai.system`，或者在选择启用最新的 GenAI 语义约定时使用 `gen_ai.provider.name`
  - `gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`
-  - `openclaw.provider.request_id_hash`（上游提供商请求 id 的有界 SHA 哈希；不会导出原始 id）
+  - `openclaw.model_call.request_bytes`、`openclaw.model_call.response_bytes`、`openclaw.model_call.time_to_first_byte_ms`
+  - `openclaw.provider.request_id_hash`（上游提供商请求 id 的有界、基于 SHA 的哈希；不会导出原始 id）
 - `openclaw.harness.run`
  - `openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`、`openclaw.provider`、`openclaw.model`、`openclaw.channel`
  - 完成时：`openclaw.harness.result_classification`、`openclaw.harness.yield_detected`、`openclaw.harness.items.started`、`openclaw.harness.items.completed`、`openclaw.harness.items.active`
@ -224,15 +248,20 @@ openclaw plugins enable diagnostics-otel
 - `openclaw.memory.pressure`
  - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes`

-当显式启用内容采集时，模型和工具 span 还可以包含你选择加入的特定内容类别对应的有界、已脱敏 `openclaw.content.*` 属性。
+当明确启用内容捕获时，模型和工具 spans 还可以为你选择启用的特定
+内容类别包含有界、已脱敏的 `openclaw.content.*` 属性。

 ## 诊断事件目录

-下列事件为上述指标和 span 提供支撑。插件也可以在不进行 OTLP 导出的情况下直接订阅这些事件。
+以下事件为上述指标和 spans 提供基础。插件也可以直接订阅
+这些事件，而无需 OTLP 导出。

 **模型使用情况**

- `model.usage` — token、成本、时长、上下文、提供商/模型/渠道、会话 id。`usage` 是用于成本和遥测的提供商/轮次统计；`context.used` 是当前提示词/上下文快照，在涉及缓存输入或工具循环调用时，可能低于提供商的 `usage.total`。
+- `model.usage` — token、成本、时长、上下文、提供商/模型/渠道、
+  会话 id。`usage` 是提供商/轮次维度的成本和遥测统计；
+  `context.used` 是当前提示词/上下文快照，在涉及缓存输入或工具循环调用时，
+  其值可能低于提供商 `usage.total`。

 **消息流**

@ -249,15 +278,22 @@ openclaw plugins enable diagnostics-otel

 **Harness 生命周期**

- `harness.run.started` / `harness.run.completed` / `harness.run.error` — 智能体 harness 的每次运行生命周期。包含 `harnessId`、可选的 `pluginId`、provider/model/channel 以及 run id。完成事件会新增 `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected` 和 `itemLifecycle` 计数。错误事件会新增 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 以及可选的 `cleanupFailed`。
+- `harness.run.started` / `harness.run.completed` / `harness.run.error` —
+  智能体 harness 的单次运行生命周期。包括 `harnessId`、可选的
+  `pluginId`、提供商/模型/渠道以及运行 id。完成事件会附加
+  `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected`
+  和 `itemLifecycle` 计数。错误事件会附加 `phase`
+  （`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 以及
+  可选的 `cleanupFailed`。

 **Exec**

- `exec.process.completed` — 最终结果、时长、目标、模式、退出码和失败类型。不包含命令文本和工作目录。
+- `exec.process.completed` — 最终结果、时长、目标、模式、退出
+  码和失败类型。不包含命令文本和工作目录。

 ## 不使用导出器

-你可以在不运行 `diagnostics-otel` 的情况下，仍然让诊断事件可供插件或自定义接收端使用：
+你可以在不运行 `diagnostics-otel` 的情况下，仍让诊断事件可供插件或自定义接收器使用：

 ```json5
 {
@ -265,7 +301,9 @@ openclaw plugins enable diagnostics-otel
 }
 ```

-如果想在不提高 `logging.level` 的情况下输出定向调试信息，请使用诊断标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）：
+若想在不提高 `logging.level` 的情况下获得定向调试输出，请使用诊断
+标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或
+`*`）：

 ```json5
 {
@ -279,7 +317,8 @@ openclaw plugins enable diagnostics-otel
 OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
 ```

-标志输出会进入标准日志文件（`logging.file`），并且仍会由 `logging.redactSensitive` 进行脱敏。完整指南：
+标志输出会进入标准日志文件（`logging.file`），并且仍会受到
+`logging.redactSensitive` 的脱敏处理。完整指南：
 [诊断标志](/zh-CN/diagnostics/flags)。

 ## 禁用
@ -290,13 +329,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
 }
 ```

-你也可以不在 `plugins.allow` 中加入 `diagnostics-otel`，或者运行
+你也可以不将 `diagnostics-otel` 加入 `plugins.allow`，或者运行
 `openclaw plugins disable diagnostics-otel`。

 ## 相关内容

- [日志](/zh-CN/logging) — 文件日志、控制台输出、CLI tail，以及 Control UI 的日志标签页
- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
+- [日志记录](/zh-CN/logging) — 文件日志、控制台输出、CLI tail 和 Control UI 日志标签页
+- [Gateway 网关日志记录内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
 - [诊断标志](/zh-CN/diagnostics/flags) — 定向调试日志标志
- [诊断导出](/zh-CN/gateway/diagnostics) — 面向运维的支持包工具（与 OTEL 导出分开）
+- [诊断导出](/zh-CN/gateway/diagnostics) — 面向运维人员的支持包工具（与 OTEL 导出分开）
 - [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考
--- a/docs/zh-CN/logging.md
+++ b/docs/zh-CN/logging.md
@ -1,37 +1,35 @@
 ---
 read_when:
    - 你需要一份适合初学者的 OpenClaw 日志概览
-    - 你想要配置日志级别、格式或敏感信息脱敏处理
+    - 你想配置日志级别、格式或脱敏处理
    - 你正在进行故障排除，需要快速找到日志
-summary: 文件日志、控制台输出、CLI 尾部输出，以及 Control UI 的“日志”选项卡
+summary: 文件日志、控制台输出、CLI 尾部日志，以及 Control UI 的日志标签页
 title: 日志
 x-i18n:
-    generated_at: "2026-04-26T19:56:09Z"
+    generated_at: "2026-04-26T20:47:22Z"
    model: gpt-5.4
    provider: openai
-    source_hash: b4846f17e911e6fc2c202ec78ce83c8d0fc8e567942f88324ffc1ba230c0b8b0
+    source_hash: 2a6e363818e1d48b8b265bf18214772f40ffd55c423acd50dee7659f37b44bfa
    source_path: logging.md
    workflow: 15
 ---

-OpenClaw 有两个主要的日志界面：
+OpenClaw 有两个主要的日志表面：

- 由 Gateway 网关写入的**文件日志**（JSON 行）。
+- 由 Gateway 网关写入的**文件日志**（JSON Lines）。
 - 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。

-Control UI 的**日志**选项卡会尾随 Gateway 网关文件日志。本页说明日志位于哪里、如何阅读日志，以及如何配置日志级别和格式。
+Control UI 的**日志**标签页会实时跟踪 gateway 文件日志。此页面说明日志位于哪里、如何读取它们，以及如何配置日志级别和格式。

-## 日志位于哪里
+## 日志位置

-默认情况下，Gateway 网关会在以下位置写入滚动日志文件：
+默认情况下，Gateway 网关会在以下路径写入滚动日志文件：

 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

-日期使用 Gateway 网关主机的本地时区。
+日期使用 gateway 主机的本地时区。

-每个文件在达到 `logging.maxFileBytes` 时轮转（默认值：100 MB）。
-OpenClaw 会在活动文件旁边最多保留五个带编号的归档文件，例如
-`openclaw-YYYY-MM-DD.1.log`，并继续写入新的活动日志文件，而不是抑制诊断信息。
+每个文件在达到 `logging.maxFileBytes`（默认：100 MB）时轮转。OpenClaw 会在活动文件旁边最多保留五个带编号的归档文件，例如 `openclaw-YYYY-MM-DD.1.log`，并继续写入一个新的活动日志文件，而不是抑制诊断信息。

 你可以在 `~/.openclaw/openclaw.json` 中覆盖此设置：

@ -43,11 +41,11 @@ OpenClaw 会在活动文件旁边最多保留五个带编号的归档文件，
 }
 ```

-## 如何阅读日志
+## 如何读取日志

-### CLI：实时尾随（推荐）
+### CLI：实时 tail（推荐）

-使用 CLI 通过 RPC 尾随 Gateway 网关日志文件：
+使用 CLI 通过 RPC 实时跟踪 gateway 日志文件：

 ```bash
 openclaw logs --follow
@ -67,27 +65,27 @@ openclaw logs --follow
 - `--plain`：在 TTY 会话中强制使用纯文本。
 - `--no-color`：禁用 ANSI 颜色。

-当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要认证，请自行包含 `--token`。
+当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量中的凭证；如果目标 Gateway 网关需要身份验证，请自行包含 `--token`。

-在 JSON 模式下，CLI 会输出带 `type` 标签的对象：
+在 JSON 模式下，CLI 会输出带有 `type` 标签的对象：

 - `meta`：流元数据（文件、游标、大小）
 - `log`：已解析的日志条目
 - `notice`：截断 / 轮转提示
- `raw`：未解析的原始日志行
+- `raw`：未解析的日志行

-如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式 `--url` 目标不会使用此回退。
+如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式的 `--url` 目标不会使用此回退。

-如果 Gateway 网关不可访问，CLI 会打印一条简短提示，建议运行：
+如果 Gateway 网关无法访问，CLI 会打印一个简短提示，建议运行：

 ```bash
 openclaw doctor
 ```

-### Control UI（网页）
+### Control UI（Web）

-Control UI 的**日志**选项卡会使用 `logs.tail` 尾随同一个文件。
-有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。
+Control UI 的**日志**标签页会使用 `logs.tail` 实时跟踪同一个文件。
+关于如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。

 ### 仅渠道日志

@ -101,14 +99,14 @@ openclaw channels logs --channel whatsapp

 ### 文件日志（JSONL）

-日志文件中的每一行都是一个 JSON 对象。CLI 和 Control UI 会解析这些条目，以呈现结构化输出（时间、级别、子系统、消息）。
+日志文件中的每一行都是一个 JSON 对象。CLI 和 Control UI 会解析这些条目，以渲染结构化输出（时间、级别、子系统、消息）。

 ### 控制台输出

-控制台日志会**感知 TTY**，并以便于阅读的方式格式化：
+控制台日志**感知 TTY**，并针对可读性进行了格式化：

 - 子系统前缀（例如 `gateway/channels/whatsapp`）
- 级别着色（info/warn/error）
+- 级别颜色区分（info/warn/error）
 - 可选的紧凑或 JSON 模式

 控制台格式由 `logging.consoleStyle` 控制。
@ -117,9 +115,9 @@ openclaw channels logs --channel whatsapp

 `openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志：

- 普通模式：仅记录值得关注的结果（错误、解析错误、慢调用）
- `--verbose`：记录所有请求/响应流量
- `--ws-log auto|compact|full`：选择详细输出的渲染样式
+- 普通模式：仅显示重要结果（错误、解析错误、慢调用）
+- `--verbose`：显示所有请求/响应流量
+- `--ws-log auto|compact|full`：选择详细日志的渲染样式
 - `--compact`：`--ws-log compact` 的别名

 示例：
@ -130,7 +128,7 @@ openclaw gateway --verbose --ws-log compact
 openclaw gateway --verbose --ws-log full
 ```

-## 配置日志记录
+## 配置日志

 所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。

@ -152,50 +150,54 @@ openclaw gateway --verbose --ws-log full
 - `logging.level`：**文件日志**（JSONL）级别。
 - `logging.consoleLevel`：**控制台**详细程度级别。

-你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level <level>`**（例如 `openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。
+你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level <level>`**（例如 `openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。

-`--verbose` 仅影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。
+`--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。

-### 追踪关联
+### 跟踪关联

-文件日志采用 JSONL 格式。当一次日志调用携带有效的诊断追踪上下文时，
-OpenClaw 会将追踪字段写为顶层 JSON 键（`traceId`、`spanId`、
-`parentSpanId`、`traceFlags`），以便外部日志处理器能够将该行与 OTEL span 以及 provider `traceparent` 传播关联起来。
+文件日志是 JSONL。当一次日志调用携带有效的诊断跟踪上下文时，OpenClaw 会将跟踪字段写为顶层 JSON 键（`traceId`、`spanId`、`parentSpanId`、`traceFlags`），以便外部日志处理器将该行与 OTEL span 以及 provider 的 `traceparent` 传播关联起来。
+
+### 模型调用大小与时序
+
+模型调用诊断会记录有界的请求/响应测量数据，而不会捕获原始提示词或响应内容：
+
+- `requestPayloadBytes`：最终模型请求负载的 UTF-8 字节大小
+- `responseStreamBytes`：流式模型响应事件的 UTF-8 字节大小
+- `timeToFirstByteMs`：首个流式响应事件之前经过的时间
+- `durationMs`：模型调用总时长
+
+启用诊断导出后，这些字段可用于诊断快照、模型调用插件钩子，以及 OTEL 模型调用 span / 指标。

 ### 控制台样式

 `logging.consoleStyle`：

- `pretty`：适合人类阅读、带颜色、包含时间戳。
+- `pretty`：适合人类阅读，带颜色和时间戳。
 - `compact`：更紧凑的输出（最适合长时间会话）。
 - `json`：每行一个 JSON（用于日志处理器）。

-### 脱敏处理
+### 脱敏

-OpenClaw 可以在敏感令牌写入控制台输出、文件日志、OTLP 日志记录或持久化会话转录文本之前，对其进行脱敏处理：
+OpenClaw 可以在敏感令牌写入控制台输出、文件日志、OTLP 日志记录或持久化的会话转录文本之前对其进行脱敏：

- `logging.redactSensitive`：`off` | `tools`（默认值：`tools`）
+- `logging.redactSensitive`：`off` | `tools`（默认：`tools`）
 - `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表

-文件日志和会话转录仍保持为 JSONL，但匹配到的敏感值会在该行或消息写入磁盘之前被遮蔽。脱敏处理是尽力而为的：它适用于承载文本的消息内容和日志字符串，而不是每个标识符或二进制负载字段。
+文件日志和会话转录仍然保持为 JSONL，但匹配到的敏感值会在该行或消息写入磁盘前被屏蔽。脱敏属于尽力而为：它适用于承载文本的消息内容和日志字符串，而不是每一个标识符或二进制负载字段。

 ## 诊断与 OpenTelemetry

-诊断是结构化、机器可读的事件，用于模型运行和消息流遥测（webhook、排队、会话状态）。它们**不会**替代日志——它们为指标、追踪和导出器提供数据。无论你是否导出它们，这些事件都会在进程内发出。
+诊断是针对模型运行和消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志——它们用于提供指标、跟踪和导出器。无论你是否导出它们，这些事件都会在进程内发出。

-两个相邻界面：
+两个相邻的表面：

- **OpenTelemetry 导出**——通过 OTLP/HTTP 将指标、追踪和日志发送到任何兼容 OpenTelemetry 的收集器或后端（Grafana、Datadog、
-  Honeycomb、New Relic、Tempo 等）。完整配置、信号目录、
-  指标 / span 名称、环境变量以及隐私模型位于专门页面：
-  [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。
- **诊断标志**——有针对性的调试日志标志，可将额外日志路由到
-  `logging.file`，而无需提高 `logging.level`。标志不区分大小写，
-  并支持通配符（`telegram.*`、`*`）。可在 `diagnostics.flags`
-  下配置，或通过 `OPENCLAW_DIAGNOSTICS=...` 环境变量覆盖。完整指南：
-  [Diagnostics flags](/zh-CN/diagnostics/flags)。
+- **OpenTelemetry 导出** —— 通过 OTLP/HTTP 将指标、跟踪和日志发送到任何兼容 OpenTelemetry 的收集器或后端（Grafana、Datadog、Honeycomb、New Relic、Tempo 等）。完整配置、信号目录、指标 / span 名称、环境变量和隐私模型位于专门页面中：
+  [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。
+- **诊断标志** —— 有针对性的调试日志标志，可将额外日志路由到 `logging.file`，而无需提高 `logging.level`。标志不区分大小写，并支持通配符（`telegram.*`、`*`）。可在 `diagnostics.flags` 下配置，或通过 `OPENCLAW_DIAGNOSTICS=...` 环境变量覆盖。完整指南：
+  [诊断标志](/zh-CN/diagnostics/flags)。

-要为插件或自定义接收器启用诊断事件，而不使用 OTLP 导出：
+如果你想为插件或自定义 sink 启用诊断事件，而不使用 OTLP 导出：

 ```json5
 {
@ -203,17 +205,17 @@ OpenClaw 可以在敏感令牌写入控制台输出、文件日志、OTLP 日志
 }
 ```

-要将 OTLP 导出到收集器，请参见 [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。
+如需将 OTLP 导出到收集器，请参见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。

 ## 故障排除提示

- **Gateway 网关不可访问？** 先运行 `openclaw doctor`。
- **日志为空？** 检查 Gateway 网关是否正在运行，并且是否正在写入 `logging.file` 中的文件路径。
- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace`，然后重试。
+- **Gateway 网关无法访问？** 先运行 `openclaw doctor`。
+- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在写入 `logging.file` 中的文件路径。
+- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。

 ## 相关内容

- [OpenTelemetry export](/zh-CN/gateway/opentelemetry) — OTLP/HTTP 导出、指标 / span 目录、隐私模型
- [Diagnostics flags](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志
- [Gateway logging internals](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
- [Configuration reference](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考
+- [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry) — OTLP/HTTP 导出、指标 / span 目录、隐私模型
+- [诊断标志](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志
+- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
+- [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考