Docs: update zh-CN translations and pipeline

What: - update zh-CN glossary, TM, and translator prompt - regenerate zh-CN docs and apply targeted fixes - add zh-CN AGENTS pipeline guidance Why: - address terminology/spacing feedback from #6995 Tests: - pnpm build && pnpm check && pnpm test
2026-06-28 17:01:53 +03:00 · 2026-02-03 13:23:00 -08:00
parent 9f03791aa9
commit a3ec2d0734
228 changed files with 10651 additions and 10475 deletions
@@ -1,12 +1,12 @@
 ---
 read_when:
-  - 你需要一份面向初学者的日志概览
+  - 你需要一个适合初学者的日志概述
  - 你想配置日志级别或格式
-  - 你正在故障排除，需要快速找到日志
-summary: 日志概览：文件日志、控制台输出、CLI 实时追踪和控制界面
+  - 你正在故障排除并需要快速找到日志
+summary: 日志概述：文件日志、控制台输出、CLI 跟踪和控制 UI
 title: 日志
 x-i18n:
-  generated_at: "2026-02-01T21:17:08Z"
+  generated_at: "2026-02-03T07:50:52Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 884fcf4a906adff34d546908e22abd283cb89fe0845076cf925c72384ec3556b
@@ -18,18 +18,18 @@ x-i18n:

 OpenClaw 在两个地方记录日志：

- **文件日志**（JSON 行格式），由 Gateway网关写入。
- **控制台输出**，显示在终端和控制界面中。
+- **文件日志**（JSON 行）由 Gateway 网关写入。
+- **控制台输出**显示在终端和控制 UI 中。

-本页说明日志的存储位置、如何读取日志，以及如何配置日志级别和格式。
+本页说明日志存放位置、如何读取日志以及如何配置日志级别和格式。

-## 日志存储位置
+## 日志存放位置

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

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

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

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

@@ -43,9 +43,9 @@ OpenClaw 在两个地方记录日志：

 ## 如何读取日志

-### CLI：实时追踪（推荐）
+### CLI：实时跟踪（推荐）

-使用 CLI 通过 RPC 追踪 Gateway网关日志文件：
+使用 CLI 通过 RPC 跟踪 Gateway 网关日志文件：

 ```bash
 openclaw logs --follow
@@ -53,33 +53,33 @@ openclaw logs --follow

 输出模式：

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

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

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

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

 ```bash
 openclaw doctor
 ```

-### 控制界面（Web）
+### 控制 UI（Web）

-控制界面的**日志**选项卡使用 `logs.tail` 追踪同一文件。
-请参阅 [/web/control-ui](/web/control-ui) 了解如何打开它。
+控制 UI 的**日志**标签页使用 `logs.tail` 跟踪相同的文件。
+参见 [/web/control-ui](/web/control-ui) 了解如何打开它。

 ### 仅渠道日志

-要过滤渠道活动（WhatsApp/Telegram 等），请使用：
+要过滤渠道活动（WhatsApp/Telegram 等），使用：

 ```bash
 openclaw channels logs --channel whatsapp
@@ -89,21 +89,21 @@ openclaw channels logs --channel whatsapp

 ### 文件日志（JSONL）

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

 ### 控制台输出

-控制台日志**感知 TTY**，并以可读性为目标进行格式化：
+控制台日志**感知 TTY**并格式化以提高可读性：

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

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

 ## 配置日志

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

 ```json
 {
@@ -123,55 +123,55 @@ openclaw channels logs --channel whatsapp
 - `logging.level`：**文件日志**（JSONL）级别。
 - `logging.consoleLevel`：**控制台**详细程度级别。

-`--verbose` 仅影响控制台输出；不会更改文件日志级别。
+`--verbose` 仅影响控制台输出；它不改变文件日志级别。

 ### 控制台样式

 `logging.consoleStyle`：

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

 ### 脱敏

-工具摘要可以在输出到控制台之前对敏感令牌进行脱敏处理：
+工具摘要可以在敏感令牌输出到控制台之前对其进行脱敏：

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

-脱敏**仅影响控制台输出**，不会更改文件日志。
+脱敏仅影响**控制台输出**，不会改变文件日志。

 ## 诊断 + OpenTelemetry

-诊断是结构化的、机器可读的事件，用于模型运行**以及**消息流遥测（webhook、队列、会话状态）。它们**不会**替代日志；其存在是为了向指标、追踪和其他导出器提供数据。
+诊断是用于模型运行**和**消息流遥测（webhooks、队列、会话状态）的结构化、机器可读事件。它们**不**替代日志；它们存在是为了向指标、追踪和其他导出器提供数据。

-诊断事件在进程内发出，但导出器仅在启用诊断和导出器插件时才会挂载。
+诊断事件在进程内发出，但导出器仅在启用诊断 + 导出器插件时才附加。

 ### OpenTelemetry 与 OTLP

- **OpenTelemetry (OTel)**：用于追踪、指标和日志的数据模型 + SDK。
- **OTLP**：用于将 OTel 数据导出到收集器/后端的传输协议。
- OpenClaw 目前通过 **OTLP/HTTP (protobuf)** 导出。
+- **OpenTelemetry（OTel）**：追踪、指标和日志的数据模型 + SDK。
+- **OTLP**：用于将 OTel 数据导出到收集器/后端的线路协议。
+- OpenClaw 目前通过 **OTLP/HTTP（protobuf）** 导出。

 ### 导出的信号

 - **指标**：计数器 + 直方图（令牌使用、消息流、队列）。
 - **追踪**：模型使用 + webhook/消息处理的 span。
- **日志**：当 `diagnostics.otel.logs` 启用时通过 OTLP 导出。日志量可能很大；请注意 `logging.level` 和导出器过滤器。
+- **日志**：启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请注意 `logging.level` 和导出器过滤器。

 ### 诊断事件目录

 模型使用：

- `model.usage`：令牌数、成本、持续时间、上下文、提供商/模型/渠道、会话 ID。
+- `model.usage`：令牌、成本、持续时间、上下文、提供商/模型/渠道、会话 ID。

 消息流：

- `webhook.received`：每个渠道的 webhook 入口。
+- `webhook.received`：每渠道的 webhook 入口。
 - `webhook.processed`：webhook 已处理 + 持续时间。
- `webhook.error`：webhook 处理器错误。
- `message.queued`：消息已入队等待处理。
+- `webhook.error`：webhook 处理程序错误。
+- `message.queued`：消息入队等待处理。
 - `message.processed`：结果 + 持续时间 + 可选错误。

 队列 + 会话：
@@ -181,11 +181,11 @@ openclaw channels logs --channel whatsapp
 - `session.state`：会话状态转换 + 原因。
 - `session.stuck`：会话卡住警告 + 持续时间。
 - `run.attempt`：运行重试/尝试元数据。
- `diagnostic.heartbeat`：聚合计数器（webhook/队列/会话）。
+- `diagnostic.heartbeat`：聚合计数器（webhooks/队列/会话）。

 ### 启用诊断（无导出器）

-如果你希望诊断事件可供插件或自定义接收器使用，请使用此配置：
+如果你希望诊断事件可用于插件或自定义接收器，使用此配置：

 ```json
 {
@@ -197,7 +197,8 @@ openclaw channels logs --channel whatsapp

 ### 诊断标志（定向日志）

-使用标志可以在不提高 `logging.level` 的情况下开启额外的定向调试日志。标志不区分大小写，支持通配符（例如 `telegram.*` 或 `*`）。
+使用标志在不提高 `logging.level` 的情况下开启额外的定向调试日志。
+标志不区分大小写，支持通配符（例如 `telegram.*` 或 `*`）。

 ```json
 {
@@ -213,10 +214,10 @@ openclaw channels logs --channel whatsapp
 OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
 ```

-注意事项：
+注意：

- 标志日志写入标准日志文件（与 `logging.file` 相同）。
- 输出仍然根据 `logging.redactSensitive` 进行脱敏。
+- 标志日志进入标准日志文件（与 `logging.file` 相同）。
+- 输出仍根据 `logging.redactSensitive` 进行脱敏。
 - 完整指南：[/diagnostics/flags](/diagnostics/flags)。

 ### 导出到 OpenTelemetry
@@ -250,13 +251,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
 }
 ```

-注意事项：
+注意：

- 你也可以使用 `openclaw plugins enable diagnostics-otel` 来启用插件。
- `protocol` 目前仅支持 `http/protobuf`。`grpc` 会被忽略。
- 指标包括令牌使用、成本、上下文大小、运行持续时间，以及消息流计数器/直方图（webhook、队列、会话状态、队列深度/等待时间）。
- 追踪/指标可以通过 `traces` / `metrics` 切换（默认：开启）。启用时，追踪包括模型使用 span 以及 webhook/消息处理 span。
- 当你的收集器需要认证时，请设置 `headers`。
+- 你也可以使用 `openclaw plugins enable diagnostics-otel` 启用插件。
+- `protocol` 目前仅支持 `http/protobuf`。`grpc` 被忽略。
+- 指标包括令牌使用、成本、上下文大小、运行持续时间和消息流计数器/直方图（webhooks、队列、会话状态、队列深度/等待）。
+- 追踪/指标可以通过 `traces` / `metrics` 切换（默认：开启）。启用时，追踪包括模型使用 span 加上 webhook/消息处理 span。
+- 当你的收集器需要认证时设置 `headers`。
 - 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。

 ### 导出的指标（名称 + 类型）
@@ -310,19 +311,19 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

 ### 协议说明

- OTLP/HTTP 端点可通过 `diagnostics.otel.endpoint` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。
+- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。
 - 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则按原样使用。
- 如果端点已包含 `/v1/logs`，则日志导出按原样使用。
- `diagnostics.otel.logs` 启用主日志输出的 OTLP 日志导出。
+- 如果端点已包含 `/v1/logs`，则按原样用于日志。
+- `diagnostics.otel.logs` 为主日志器输出启用 OTLP 日志导出。

 ### 日志导出行为

 - OTLP 日志使用与写入 `logging.file` 相同的结构化记录。
- 遵循 `logging.level`（文件日志级别）。控制台脱敏**不适用于** OTLP 日志。
- 高流量实例应优先使用 OTLP 收集器的采样/过滤功能。
+- 遵守 `logging.level`（文件日志级别）。控制台脱敏**不**适用于 OTLP 日志。
+- 高流量安装应优先使用 OTLP 收集器采样/过滤。

 ## 故障排除提示

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