@captain-app/openclaw 2026.2.4

package/docs/zh-CN/install/uninstall.md

@@ -0,0 +1,135 @@
+---
+read_when:
+  - 你想从机器上移除 OpenClaw
+  - 卸载后 Gateway 网关服务仍在运行
+summary: 完全卸载 OpenClaw（CLI、服务、状态、工作区）
+title: 卸载
+x-i18n:
+  generated_at: "2026-02-03T07:50:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6673a755c5e1f90a807dd8ac92a774cff6d1bc97d125c75e8bf72a40e952a777
+  source_path: install/uninstall.md
+  workflow: 15
+---
+
+# 卸载
+
+两种方式：
+
+- 如果 `openclaw` 仍已安装，使用**简单方式**。
+- 如果 CLI 已删除但服务仍在运行，使用**手动服务移除**。
+
+## 简单方式（CLI 仍已安装）
+
+推荐：使用内置卸载程序：
+
+```bash
+openclaw uninstall
+```
+
+非交互式（自动化 / npx）：
+
+```bash
+openclaw uninstall --all --yes --non-interactive
+npx -y openclaw uninstall --all --yes --non-interactive
+```
+
+手动步骤（效果相同）：
+
+1. 停止 Gateway 网关服务：
+
+```bash
+openclaw gateway stop
+```
+
+2. 卸载 Gateway 网关服务（launchd/systemd/schtasks）：
+
+```bash
+openclaw gateway uninstall
+```
+
+3. 删除状态 + 配置：
+
+```bash
+rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+```
+
+如果你将 `OPENCLAW_CONFIG_PATH` 设置为状态目录外的自定义位置，也请删除该文件。
+
+4. 删除你的工作区（可选，移除智能体文件）：
+
+```bash
+rm -rf ~/.openclaw/workspace
+```
+
+5. 移除 CLI 安装（选择你使用的那个）：
+
+```bash
+npm rm -g openclaw
+pnpm remove -g openclaw
+bun remove -g openclaw
+```
+
+6. 如果你安装了 macOS 应用：
+
+```bash
+rm -rf /Applications/OpenClaw.app
+```
+
+注意事项：
+
+- 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），对每个状态目录重复步骤 3（默认为 `~/.openclaw-<profile>`）。
+- 在远程模式下，状态目录位于 **Gateway 网关主机**上，因此也需要在那里运行步骤 1-4。
+
+## 手动服务移除（CLI 未安装）
+
+如果 Gateway 网关服务持续运行但 `openclaw` 缺失，请使用此方法。
+
+### macOS（launchd）
+
+默认标签是 `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.openclaw.*` 可能仍然存在）：
+
+```bash
+launchctl bootout gui/$UID/bot.molt.gateway
+rm -f ~/Library/LaunchAgents/bot.molt.gateway.plist
+```
+
+如果你使用了配置文件，请将标签和 plist 名称替换为 `bot.molt.<profile>`。如果存在任何旧版 `com.openclaw.*` plist，请将其移除。
+
+### Linux（systemd 用户单元）
+
+默认单元名称是 `openclaw-gateway.service`（或 `openclaw-gateway-<profile>.service`）：
+
+```bash
+systemctl --user disable --now openclaw-gateway.service
+rm -f ~/.config/systemd/user/openclaw-gateway.service
+systemctl --user daemon-reload
+```
+
+### Windows（计划任务）
+
+默认任务名称是 `OpenClaw Gateway`（或 `OpenClaw Gateway (<profile>)`）。
+任务脚本位于你的状态目录下。
+
+```powershell
+schtasks /Delete /F /TN "OpenClaw Gateway"
+Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"
+```
+
+如果你使用了配置文件，请删除匹配的任务名称和 `~\.openclaw-<profile>\gateway.cmd`。
+
+## 普通安装 vs 源码检出
+
+### 普通安装（install.sh / npm / pnpm / bun）
+
+如果你使用了 `https://openclaw.ai/install.sh` 或 `install.ps1`，CLI 是通过 `npm install -g openclaw@latest` 安装的。
+使用 `npm rm -g openclaw` 移除（或 `pnpm remove -g` / `bun remove -g`，如果你是用那种方式安装的）。
+
+### 源码检出（git clone）
+
+如果你从仓库检出运行（`git clone` + `openclaw ...` / `bun run openclaw ...`）：
+
+1. 在删除仓库**之前**卸载 Gateway 网关服务（使用上面的简单方式或手动服务移除）。
+2. 删除仓库目录。
+3. 按上述方式移除状态 + 工作区。

package/docs/zh-CN/install/updating.md

@@ -0,0 +1,233 @@
+---
+read_when:
+  - 更新 OpenClaw
+  - 更新后出现问题
+summary: 安全更新 OpenClaw（全局安装或源码），以及回滚策略
+title: 更新
+x-i18n:
+  generated_at: "2026-02-03T07:50:25Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 38cccac0839f0f22403b6508cd94ba1b401133ffc1d92d4f7640b8d04e082317
+  source_path: install/updating.md
+  workflow: 15
+---
+
+# 更新
+
+OpenClaw 发展迅速（尚未到"1.0"）。将更新视为发布基础设施：更新 → 运行检查 → 重启（或使用会重启的 `openclaw update`）→ 验证。
+
+## 推荐：重新运行网站安装程序（原地升级）
+
+**首选**的更新路径是重新运行网站上的安装程序。它会检测现有安装、原地升级，并在需要时运行 `openclaw doctor`。
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+说明：
+
+- 如果你不想再次运行新手引导向导，添加 `--no-onboard`。
+- 对于**源码安装**，使用：
+  ```bash
+  curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
+  ```
+  安装程序**仅**在仓库干净时才会执行 `git pull --rebase`。
+- 对于**全局安装**，脚本底层使用 `npm install -g openclaw@latest`。
+- 旧版说明：`clawdbot` 仍可作为兼容性垫片使用。
+
+## 更新之前
+
+- 了解你的安装方式：**全局**（npm/pnpm）还是**源码**（git clone）。
+- 了解你的 Gateway 网关运行方式：**前台终端**还是**受管理服务**（launchd/systemd）。
+- 快照你的定制内容：
+  - 配置：`~/.openclaw/openclaw.json`
+  - 凭证：`~/.openclaw/credentials/`
+  - 工作区：`~/.openclaw/workspace`
+
+## 更新（全局安装）
+
+全局安装（选择一个）：
+
+```bash
+npm i -g openclaw@latest
+```
+
+```bash
+pnpm add -g openclaw@latest
+```
+
+我们**不**推荐将 Bun 用于 Gateway 网关运行时（WhatsApp/Telegram 有 bug）。
+
+切换更新渠道（git + npm 安装）：
+
+```bash
+openclaw update --channel beta
+openclaw update --channel dev
+openclaw update --channel stable
+```
+
+使用 `--tag <dist-tag|version>` 进行一次性安装指定标签/版本。
+
+渠道语义和发布说明参见[开发渠道](/install/development-channels)。
+
+注意：在 npm 安装上，Gateway 网关在启动时会记录更新提示（检查当前渠道标签）。通过 `update.checkOnStart: false` 禁用。
+
+然后：
+
+```bash
+openclaw doctor
+openclaw gateway restart
+openclaw health
+```
+
+说明：
+
+- 如果你的 Gateway 网关作为服务运行，`openclaw gateway restart` 优于杀死 PID。
+- 如果你固定在特定版本，参见下面的"回滚/固定"。
+
+## 更新（`openclaw update`）
+
+对于**源码安装**（git checkout），首选：
+
+```bash
+openclaw update
+```
+
+它运行一个相对安全的更新流程：
+
+- 需要干净的工作树。
+- 切换到选定的渠道（标签或分支）。
+- 获取并 rebase 到配置的上游（dev 渠道）。
+- 安装依赖、构建、构建控制 UI，并运行 `openclaw doctor`。
+- 默认重启 Gateway 网关（使用 `--no-restart` 跳过）。
+
+如果你通过 **npm/pnpm** 安装（没有 git 元数据），`openclaw update` 将尝试通过你的包管理器更新。如果无法检测到安装，请改用"更新（全局安装）"。
+
+## 更新（控制 UI / RPC）
+
+控制 UI 有**更新并重启**（RPC：`update.run`）。它：
+
+1. 运行与 `openclaw update` 相同的源码更新流程（仅限 git checkout）。
+2. 写入带有结构化报告（stdout/stderr 尾部）的重启哨兵。
+3. 重启 Gateway 网关并向最后活跃的会话 ping 报告。
+
+如果 rebase 失败，Gateway 网关会中止并在不应用更新的情况下重启。
+
+## 更新（从源码）
+
+从仓库 checkout：
+
+首选：
+
+```bash
+openclaw update
+```
+
+手动（大致等效）：
+
+```bash
+git pull
+pnpm install
+pnpm build
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+openclaw doctor
+openclaw health
+```
+
+说明：
+
+- 当你运行打包的 `openclaw` 二进制文件（[`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)）或使用 Node 运行 `dist/` 时，`pnpm build` 很重要。
+- 如果你从仓库 checkout 运行而没有全局安装，CLI 命令使用 `pnpm openclaw ...`。
+- 如果你直接从 TypeScript 运行（`pnpm openclaw ...`），通常不需要重新构建，但**配置迁移仍然适用** → 运行 doctor。
+- 在全局和 git 安装之间切换很容易：安装另一种方式，然后运行 `openclaw doctor` 以便将 Gateway 网关服务入口点重写为当前安装。
+
+## 始终运行：`openclaw doctor`
+
+Doctor 是"安全更新"命令。它故意很无聊：修复 + 迁移 + 警告。
+
+注意：如果你是**源码安装**（git checkout），`openclaw doctor` 会提供先运行 `openclaw update`。
+
+它通常做的事情：
+
+- 迁移已弃用的配置键/旧版配置文件位置。
+- 审计私信策略并对有风险的"开放"设置发出警告。
+- 检查 Gateway 网关健康状况，可以提供重启。
+- 检测并将旧版 Gateway 网关服务（launchd/systemd；旧版 schtasks）迁移到当前 OpenClaw 服务。
+- 在 Linux 上，确保 systemd 用户 lingering（这样 Gateway 网关在登出后仍能存活）。
+
+详情：[Doctor](/gateway/doctor)
+
+## 启动/停止/重启 Gateway 网关
+
+CLI（无论操作系统都适用）：
+
+```bash
+openclaw gateway status
+openclaw gateway stop
+openclaw gateway restart
+openclaw gateway --port 18789
+openclaw logs --follow
+```
+
+如果你使用受管理服务：
+
+- macOS launchd（应用捆绑的 LaunchAgent）：`launchctl kickstart -k gui/$UID/bot.molt.gateway`（使用 `bot.molt.<profile>`；旧版 `com.openclaw.*` 仍然有效）
+- Linux systemd 用户服务：`systemctl --user restart openclaw-gateway[-<profile>].service`
+- Windows（WSL2）：`systemctl --user restart openclaw-gateway[-<profile>].service`
+  - `launchctl`/`systemctl` 仅在服务已安装时有效；否则运行 `openclaw gateway install`。
+
+运行手册 + 确切的服务标签：[Gateway 网关运行手册](/gateway)
+
+## 回滚/固定（当出问题时）
+
+### 固定（全局安装）
+
+安装已知良好的版本（将 `<version>` 替换为最后可用的版本）：
+
+```bash
+npm i -g openclaw@<version>
+```
+
+```bash
+pnpm add -g openclaw@<version>
+```
+
+提示：要查看当前发布的版本，运行 `npm view openclaw version`。
+
+然后重启 + 重新运行 doctor：
+
+```bash
+openclaw doctor
+openclaw gateway restart
+```
+
+### 按日期固定（源码）
+
+选择某个日期的提交（示例："2026-01-01 时 main 的状态"）：
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+```
+
+然后重新安装依赖 + 重启：
+
+```bash
+pnpm install
+pnpm build
+openclaw gateway restart
+```
+
+如果你之后想回到最新版本：
+
+```bash
+git checkout main
+git pull
+```
+
+## 如果你卡住了
+
+- 再次运行 `openclaw doctor` 并仔细阅读输出（它通常会告诉你修复方法）。
+- 查看：[故障排除](/gateway/troubleshooting)
+- 在 Discord 上提问：https://discord.gg/clawd

package/docs/zh-CN/logging.md

@@ -0,0 +1,329 @@
+---
+read_when:
+  - 你需要一个适合初学者的日志概述
+  - 你想配置日志级别或格式
+  - 你正在故障排除并需要快速找到日志
+summary: 日志概述：文件日志、控制台输出、CLI 跟踪和控制 UI
+title: 日志
+x-i18n:
+  generated_at: "2026-02-03T07:50:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 884fcf4a906adff34d546908e22abd283cb89fe0845076cf925c72384ec3556b
+  source_path: logging.md
+  workflow: 15
+---
+
+# 日志
+
+OpenClaw 在两个地方记录日志：
+
+- **文件日志**（JSON 行）由 Gateway 网关写入。
+- **控制台输出**显示在终端和控制 UI 中。
+
+本页说明日志存放位置、如何读取日志以及如何配置日志级别和格式。
+
+## 日志存放位置
+
+默认情况下，Gateway 网关在以下位置写入滚动日志文件：
+
+`/tmp/openclaw/openclaw-YYYY-MM-DD.log`
+
+日期使用 Gateway 网关主机的本地时区。
+
+你可以在 `~/.openclaw/openclaw.json` 中覆盖此设置：
+
+```json
+{
+  "logging": {
+    "file": "/path/to/openclaw.log"
+  }
+}
+```
+
+## 如何读取日志
+
+### CLI：实时跟踪（推荐）
+
+使用 CLI 通过 RPC 跟踪 Gateway 网关日志文件：
+
+```bash
+openclaw logs --follow
+```
+
+输出模式：
+
+- **TTY 会话**：美观、彩色、结构化的日志行。
+- **非 TTY 会话**：纯文本。
+- `--json`：行分隔的 JSON（每行一个日志事件）。
+- `--plain`：在 TTY 会话中强制纯文本。
+- `--no-color`：禁用 ANSI 颜色。
+
+在 JSON 模式下，CLI 输出带 `type` 标签的对象：
+
+- `meta`：流元数据（文件、游标、大小）
+- `log`：解析的日志条目
+- `notice`：截断/轮转提示
+- `raw`：未解析的日志行
+
+如果 Gateway 网关无法访问，CLI 会打印一个简短提示运行：
+
+```bash
+openclaw doctor
+```
+
+### 控制 UI（Web）
+
+控制 UI 的**日志**标签页使用 `logs.tail` 跟踪相同的文件。
+参见 [/web/control-ui](/web/control-ui) 了解如何打开它。
+
+### 仅渠道日志
+
+要过滤渠道活动（WhatsApp/Telegram 等），使用：
+
+```bash
+openclaw channels logs --channel whatsapp
+```
+
+## 日志格式
+
+### 文件日志（JSONL）
+
+日志文件中的每一行都是一个 JSON 对象。CLI 和控制 UI 解析这些条目以渲染结构化输出（时间、级别、子系统、消息）。
+
+### 控制台输出
+
+控制台日志**感知 TTY**并格式化以提高可读性：
+
+- 子系统前缀（例如 `gateway/channels/whatsapp`）
+- 级别着色（info/warn/error）
+- 可选的紧凑或 JSON 模式
+
+控制台格式由 `logging.consoleStyle` 控制。
+
+## 配置日志
+
+所有日志配置都在 `~/.openclaw/openclaw.json` 的 `logging` 下。
+
+```json
+{
+  "logging": {
+    "level": "info",
+    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
+    "consoleLevel": "info",
+    "consoleStyle": "pretty",
+    "redactSensitive": "tools",
+    "redactPatterns": ["sk-.*"]
+  }
+}
+```
+
+### 日志级别
+
+- `logging.level`：**文件日志**（JSONL）级别。
+- `logging.consoleLevel`：**控制台**详细程度级别。
+
+`--verbose` 仅影响控制台输出；它不改变文件日志级别。
+
+### 控制台样式
+
+`logging.consoleStyle`：
+
+- `pretty`：人类友好、彩色、带时间戳。
+- `compact`：更紧凑的输出（最适合长会话）。
+- `json`：每行 JSON（用于日志处理器）。
+
+### 脱敏
+
+工具摘要可以在敏感令牌输出到控制台之前对其进行脱敏：
+
+- `logging.redactSensitive`：`off` | `tools`（默认：`tools`）
+- `logging.redactPatterns`：用于覆盖默认集的正则表达式字符串列表
+
+脱敏仅影响**控制台输出**，不会改变文件日志。
+
+## 诊断 + OpenTelemetry
+
+诊断是用于模型运行**和**消息流遥测（webhooks、队列、会话状态）的结构化、机器可读事件。它们**不**替代日志；它们存在是为了向指标、追踪和其他导出器提供数据。
+
+诊断事件在进程内发出，但导出器仅在启用诊断 + 导出器插件时才附加。
+
+### OpenTelemetry 与 OTLP
+
+- **OpenTelemetry（OTel）**：追踪、指标和日志的数据模型 + SDK。
+- **OTLP**：用于将 OTel 数据导出到收集器/后端的线路协议。
+- OpenClaw 目前通过 **OTLP/HTTP（protobuf）** 导出。
+
+### 导出的信号
+
+- **指标**：计数器 + 直方图（令牌使用、消息流、队列）。
+- **追踪**：模型使用 + webhook/消息处理的 span。
+- **日志**：启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请注意 `logging.level` 和导出器过滤器。
+
+### 诊断事件目录
+
+模型使用：
+
+- `model.usage`：令牌、成本、持续时间、上下文、提供商/模型/渠道、会话 ID。
+
+消息流：
+
+- `webhook.received`：每渠道的 webhook 入口。
+- `webhook.processed`：webhook 已处理 + 持续时间。
+- `webhook.error`：webhook 处理程序错误。
+- `message.queued`：消息入队等待处理。
+- `message.processed`：结果 + 持续时间 + 可选错误。
+
+队列 + 会话：
+
+- `queue.lane.enqueue`：命令队列通道入队 + 深度。
+- `queue.lane.dequeue`：命令队列通道出队 + 等待时间。
+- `session.state`：会话状态转换 + 原因。
+- `session.stuck`：会话卡住警告 + 持续时间。
+- `run.attempt`：运行重试/尝试元数据。
+- `diagnostic.heartbeat`：聚合计数器（webhooks/队列/会话）。
+
+### 启用诊断（无导出器）
+
+如果你希望诊断事件可用于插件或自定义接收器，使用此配置：
+
+```json
+{
+  "diagnostics": {
+    "enabled": true
+  }
+}
+```
+
+### 诊断标志（定向日志）
+
+使用标志在不提高 `logging.level` 的情况下开启额外的定向调试日志。
+标志不区分大小写，支持通配符（例如 `telegram.*` 或 `*`）。
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http"]
+  }
+}
+```
+
+环境变量覆盖（一次性）：
+
+```
+OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
+```
+
+注意：
+
+- 标志日志进入标准日志文件（与 `logging.file` 相同）。
+- 输出仍根据 `logging.redactSensitive` 进行脱敏。
+- 完整指南：[/diagnostics/flags](/diagnostics/flags)。
+
+### 导出到 OpenTelemetry
+
+诊断可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器/后端。
+
+```json
+{
+  "plugins": {
+    "allow": ["diagnostics-otel"],
+    "entries": {
+      "diagnostics-otel": {
+        "enabled": true
+      }
+    }
+  },
+  "diagnostics": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "endpoint": "http://otel-collector:4318",
+      "protocol": "http/protobuf",
+      "serviceName": "openclaw-gateway",
+      "traces": true,
+      "metrics": true,
+      "logs": true,
+      "sampleRate": 0.2,
+      "flushIntervalMs": 60000
+    }
+  }
+}
+```
+
+注意：
+
+- 你也可以使用 `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`。
+
+### 导出的指标（名称 + 类型）
+
+模型使用：
+
+- `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+- `openclaw.cost.usd`（计数器，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+- `openclaw.run.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+- `openclaw.context.tokens`（直方图，属性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
+
+消息流：
+
+- `openclaw.webhook.received`（计数器，属性：`openclaw.channel`、`openclaw.webhook`）
+- `openclaw.webhook.error`（计数器，属性：`openclaw.channel`、`openclaw.webhook`）
+- `openclaw.webhook.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.webhook`）
+- `openclaw.message.queued`（计数器，属性：`openclaw.channel`、`openclaw.source`）
+- `openclaw.message.processed`（计数器，属性：`openclaw.channel`、`openclaw.outcome`）
+- `openclaw.message.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.outcome`）
+
+队列 + 会话：
+
+- `openclaw.queue.lane.enqueue`（计数器，属性：`openclaw.lane`）
+- `openclaw.queue.lane.dequeue`（计数器，属性：`openclaw.lane`）
+- `openclaw.queue.depth`（直方图，属性：`openclaw.lane` 或 `openclaw.channel=heartbeat`）
+- `openclaw.queue.wait_ms`（直方图，属性：`openclaw.lane`）
+- `openclaw.session.state`（计数器，属性：`openclaw.state`、`openclaw.reason`）
+- `openclaw.session.stuck`（计数器，属性：`openclaw.state`）
+- `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`）
+- `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`）
+
+### 导出的 span（名称 + 关键属性）
+
+- `openclaw.model.usage`
+  - `openclaw.channel`、`openclaw.provider`、`openclaw.model`
+  - `openclaw.sessionKey`、`openclaw.sessionId`
+  - `openclaw.tokens.*`（input/output/cache_read/cache_write/total）
+- `openclaw.webhook.processed`
+  - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`
+- `openclaw.webhook.error`
+  - `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`、`openclaw.error`
+- `openclaw.message.processed`
+  - `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、`openclaw.messageId`、`openclaw.sessionKey`、`openclaw.sessionId`、`openclaw.reason`
+- `openclaw.session.stuck`
+  - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth`、`openclaw.sessionKey`、`openclaw.sessionId`
+
+### 采样 + 刷新
+
+- 追踪采样：`diagnostics.otel.sampleRate`（0.0–1.0，仅根 span）。
+- 指标导出间隔：`diagnostics.otel.flushIntervalMs`（最小 1000ms）。
+
+### 协议说明
+
+- OTLP/HTTP 端点可以通过 `diagnostics.otel.endpoint` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。
+- 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则按原样使用。
+- 如果端点已包含 `/v1/logs`，则按原样用于日志。
+- `diagnostics.otel.logs` 为主日志器输出启用 OTLP 日志导出。
+
+### 日志导出行为
+
+- OTLP 日志使用与写入 `logging.file` 相同的结构化记录。
+- 遵守 `logging.level`（文件日志级别）。控制台脱敏**不**适用于 OTLP 日志。
+- 高流量安装应优先使用 OTLP 收集器采样/过滤。
+
+## 故障排除提示
+
+- **Gateway 网关无法访问？** 先运行 `openclaw doctor`。
+- **日志为空？** 检查 Gateway 网关是否正在运行并写入 `logging.file` 中的文件路径。
+- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 并重试。