chore(i18n): refresh zh-CN translations

2026-04-26 19:57:14 +00:00 · 2026-04-26 19:57:14 +00:00 · 103be39a57
commit 103be39a57
parent 9fb0ac6bfe
2 changed files with 96 additions and 86 deletions
--- a/docs/zh-CN/gateway/opentelemetry.md
+++ b/docs/zh-CN/gateway/opentelemetry.md
@ -1,26 +1,26 @@
 ---
 read_when:
-    - 你想将 OpenClaw 的模型使用情况、消息流或会话指标发送到 OpenTelemetry 收集器
+    - 你想将 OpenClaw 模型使用情况、消息流或会话指标发送到 OpenTelemetry 收集器
    - 你正在将追踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端
-    - 你需要精确的指标名称、span 名称或属性结构来构建仪表板或告警
+    - 你需要确切的指标名称、span 名称或属性结构来构建仪表板或告警
 summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断数据导出到任意 OpenTelemetry 收集器
 title: OpenTelemetry 导出
 x-i18n:
-    generated_at: "2026-04-26T18:13:23Z"
+    generated_at: "2026-04-26T19:56:12Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 1301b5d8e7852b8e94be3a5928b5075c0109a3f3879033e52efcd1a75098cac9
+    source_hash: 379e0cada90888a3703785147d62ebe418f48216169577443cc8c95dc2a9fff8
    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` 标头，前提是提供商传输支持自定义标头。插件发出的追踪上下文不会被传播。
+- 当提供商传输支持自定义请求头时，**提供商调用** 会从 OpenClaw 受信任的模型调用 span 上下文中接收一个 W3C `traceparent` 请求头。插件发出的追踪上下文不会被传播。
 - 只有在诊断功能面和插件都启用时，导出器才会附加，因此默认情况下进程内开销几乎为零。

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

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

 ## 配置参考

@ -108,33 +108,34 @@ 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` 配置键未设置时，使用按信号划分的端点覆盖。按信号划分的配置优先于按信号划分的环境变量，后者又优先于共享端点。 |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当对应的 `diagnostics.otel.*Endpoint` 配置键未设置时，用作按信号区分的 endpoint 覆盖。按信号区分的配置优先于按信号区分的环境变量，后者优先于共享 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），绝不会包含提示词文本、响应文本、工具输入、工具输出或会话键。
+默认**不会**导出原始模型/工具内容。span 携带的是有界标识符（渠道、提供商、模型、错误类别、仅哈希的请求 id），绝不包含提示词文本、响应文本、工具输入、工具输出或会话键。

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

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

 - `inputMessages` — 用户提示内容。
 - `outputMessages` — 模型响应内容。
 - `toolInputs` — 工具参数负载。
 - `toolOutputs` — 工具结果负载。
- `systemPrompt` — 已组装的 system/developer 提示词。
+- `systemPrompt` — 组装后的 system/developer 提示词。

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

 ## 采样与刷新

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

 ## 导出的指标

@ -158,7 +159,7 @@ openclaw plugins enable diagnostics-otel
 - `openclaw.message.delivery.started`（计数器，属性：`openclaw.channel`、`openclaw.delivery.kind`）
 - `openclaw.message.delivery.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`）

-### 队列与会话
+### 队列和会话

 - `openclaw.queue.lane.enqueue`（计数器，属性：`openclaw.lane`）
 - `openclaw.queue.lane.dequeue`（计数器，属性：`openclaw.lane`）
@ -171,7 +172,7 @@ 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

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

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

 - `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.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`
@ -223,15 +224,15 @@ openclaw plugins enable diagnostics-otel
 - `openclaw.memory.pressure`
  - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes`

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

 ## 诊断事件目录

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

 **模型使用情况**

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

 **消息流**

@ -239,7 +240,7 @@ openclaw plugins enable diagnostics-otel
 - `message.queued` / `message.processed`
 - `message.delivery.started` / `message.delivery.completed` / `message.delivery.error`

-**队列与会话**
+**队列和会话**

 - `queue.lane.enqueue` / `queue.lane.dequeue`
 - `session.state` / `session.stuck`
@ -248,7 +249,7 @@ openclaw plugins enable diagnostics-otel

 **Harness 生命周期**

- `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`。
+- `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`。

 **Exec**

@ -256,7 +257,7 @@ openclaw plugins enable diagnostics-otel

 ## 不使用导出器

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

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

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

 ```json5
 {
@ -278,7 +279,7 @@ 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)。

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

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

 ## 相关内容

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

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

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

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

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

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

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

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

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

 你可以在 `~/.openclaw/openclaw.json` 中覆盖此设置：
@ -43,7 +43,7 @@ OpenClaw 会在当前活动文件旁边最多保留五个带编号的归档文
 }
 ```

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

 ### CLI：实时尾随（推荐）

@ -53,32 +53,32 @@ OpenClaw 会在当前活动文件旁边最多保留五个带编号的归档文
 openclaw logs --follow
 ```

-当前有用的选项：
+当前实用选项：

- `--local-time`：使用你的本地时区渲染时间戳
+- `--local-time`：以你的本地时区显示时间戳
 - `--url <url>` / `--token <token>` / `--timeout <ms>`：标准 Gateway 网关 RPC 标志
- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（这里通过共享客户端层接受）
+- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（此处通过共享客户端层接受）

 输出模式：

 - **TTY 会话**：美观、带颜色、结构化的日志行。
 - **非 TTY 会话**：纯文本。
- `--json`：行分隔 JSON（每行一个日志事件）。
+- `--json`：按行分隔的 JSON（每行一个日志事件）。
 - `--plain`：在 TTY 会话中强制使用纯文本。
 - `--no-color`：禁用 ANSI 颜色。

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

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

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

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

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

 ```bash
 openclaw doctor
@ -86,7 +86,7 @@ openclaw doctor

 ### Control UI（网页）

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

 ### 仅渠道日志
@ -101,15 +101,15 @@ openclaw channels logs --channel whatsapp

 ### 文件日志（JSONL）

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

 ### 控制台输出

-控制台日志是**TTY 感知的**，并经过格式化以提高可读性：
+控制台日志会**感知 TTY**，并以便于阅读的方式格式化：

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

 控制台格式由 `logging.consoleStyle` 控制。

@ -117,9 +117,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 +130,7 @@ openclaw gateway --verbose --ws-log compact
 openclaw gateway --verbose --ws-log full
 ```

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

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

@ -152,41 +152,50 @@ 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` 传播关联起来。

 ### 控制台样式

 `logging.consoleStyle`：

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

 ### 脱敏处理

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

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

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

-## Diagnostics 和 OpenTelemetry
+## 诊断与 OpenTelemetry

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

-两个相邻的展示面：
+两个相邻界面：

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

-要为插件或自定义接收端启用 Diagnostics 事件，而不使用 OTLP 导出：
+要为插件或自定义接收器启用诊断事件，而不使用 OTLP 导出：

 ```json5
 {
@ -194,17 +203,17 @@ Diagnostics 是用于模型运行和消息流遥测（webhook、排队、会话
 }
 ```

-如需将 OTLP 导出到收集器，请参见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。
+要将 OTLP 导出到收集器，请参见 [OpenTelemetry export](/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 导出](/zh-CN/gateway/opentelemetry) — OTLP/HTTP 导出、指标 / span 目录、隐私模型
- [Diagnostics 标志](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志
- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获
- [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考
+- [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.*` 字段参考