From 103be39a570d52d4b9bcce2f480267ae47b65156 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 19:57:14 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/gateway/opentelemetry.md | 73 ++++++++++--------- docs/zh-CN/logging.md | 109 +++++++++++++++------------- 2 files changed, 96 insertions(+), 86 deletions(-) diff --git a/docs/zh-CN/gateway/opentelemetry.md b/docs/zh-CN/gateway/opentelemetry.md index 72637ec61..ba8c23d31 100644 --- 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 导出分开） diff --git a/docs/zh-CN/logging.md b/docs/zh-CN/logging.md index 9791e036b..28c039bda 100644 --- 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 ` / `--token ` / `--timeout `：标准 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 `**（例如，`openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。 +你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-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.*` 字段参考