OpenClaw 本地文档摘要

日志优化

来源: /home/x32/.npm-global/lib/node_modules/openclaw/docs/logging.md

---

summary: "日志概览：文件日志、控制台输出、CLI 实时跟踪和控制 UI" read_when:

• 您需要适合初学者的日志概览
• 您想要配置日志级别或格式
• 您正在排查问题并需要快速查找日志 title: "日志"

---

日志

OpenClaw 在两个地方记录日志：

• 文件日志（JSON 行）由网关写入。
• 控制台输出显示在终端和控制 UI 中。

本页面解释日志存储位置、如何读取日志，以及如何配置日志级别和格式。

日志存储位置

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

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

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

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

{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

如何读取日志

CLI：实时跟踪（推荐）

使用 CLI 通过 RPC 实时跟踪网关日志文件：

openclaw logs --follow

输出模式：

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

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

• meta：流元数据（文件、光标、大小）
• log：解析的日志条目
• notice：截断/轮换提示
• raw：未解析的日志行

如果无法访问网关，CLI 会显示一个简短提示来运行：

openclaw doctor

控制 UI（Web）

控制 UI 的 Logs 选项卡使用 logs.tail 跟踪同一文件。 请参阅 /web/control-ui 了解如何打开它。

仅通道日志

要过滤通道活动（WhatsApp/Telegram 等），使用：

openclaw channels logs --channel whatsapp

日志格式

文件日志（JSONL）

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

控制台输出

控制台日志是 TTY 感知的，并格式化以提高可读性：

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

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

配置日志

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

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

日志级别

• logging.level：文件日志（JSONL）级别。
• logging.consoleLevel：控制台详细程度级别。

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

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

控制台样式

logging.consoleStyle：

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

敏感信息屏蔽

工具摘要可以在到达控制台之前屏蔽敏感令牌：

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

屏蔽仅影响控制台输出，不会更改文件日志。

诊断 + OpenTelemetry

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

诊断事件在进程中发出，但只有当诊断和导出器插件都启用时，导出器才会附加。

OpenTelemetry vs OTLP

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

导出的信号

• 指标：计数器 + 直方图（令牌使用、消息流、队列）。
• 跟踪：模型使用 + webhook/消息处理的跨度。
• 日志：当启用 diagnostics.otel.logs 时通过 OTLP 导出。日志量可能很高；请记住 logging.level 和导出器过滤器。

诊断事件目录

模型使用：

• model.usage：令牌、成本、持续时间、上下文、提供者/模型/通道、会话 ID。

消息流：

• webhook.received：每个通道的 webhook 入口。
• webhook.processed：webhook 已处理 + 持续时间。
• webhook.error：webhook 处理器错误。
• message.queued：消息排队等待处理

---

网络优化

来源: /home/x32/.npm-global/lib/node_modules/openclaw/docs/network.md

---

summary: "网络中心：网关表面、配对、发现和安全" read_when:

• 您需要网络架构 + 安全概览
• 您正在调试本地 vs tailnet 访问或配对问题
• 您想要网络文档的规范列表 title: "网络"

---

网络中心

此中心链接了 OpenClaw 如何在 localhost、LAN 和 tailnet 之间连接、配对和保护设备的核心文档。

核心模型

• 网关架构
• 网关协议
• 网关运行手册
• Web 表面 + 绑定模式

配对 + 身份

• 配对概览（DM + 节点）
• 网关拥有的节点配对
• 设备 CLI（配对 + 令牌轮换）
• 配对 CLI（DM 批准）

本地信任：

• 本地连接（环回或网关主机自己的 tailnet 地址）可以自动批准配对，以保持同机用户体验流畅。
• 非本地 tailnet/LAN 客户端仍需要明确的配对批准。

发现 + 传输

• 发现与传输
• Bonjour / mDNS
• 远程访问（SSH）
• Tailscale

节点 + 传输

• 节点概览
• 桥接协议（遗留节点）
• 节点运行手册：iOS
• 节点运行手册：Android

安全

• 安全概览
• 网关配置参考
• 故障排除
• 诊断工具

---

CI/CD 优化

来源: /home/x32/.npm-global/lib/node_modules/openclaw/docs/ci.md

---

title: CI 流水线 description: OpenClaw CI 流水线的工作原理 summary: "CI 作业图、作用域门控和本地命令等效项" read_when:

• 您需要了解为什么 CI 作业运行或未运行
• 您正在调试失败的 GitHub Actions 检查

---

CI 流水线

CI 在每次推送到 main 和每次拉取请求时运行。它使用智能作用域来跳过仅文档或原生代码更改时的昂贵作业。

作业概览

作业	目的	运行时机
docs-scope	检测仅文档更改	始终
changed-scope	检测哪些区域更改（node/macos/android）	非文档 PR
check	TypeScript 类型检查、lint、格式化	非文档更改
check-docs	Markdown lint + 损坏链接检查	文档已更改
code-analysis	LOC 阈值检查（1000 行）	仅 PR
secrets	检测泄漏的密钥	始终
build-artifacts	构建一次 dist，与其他作业共享	非文档、node 更改
release-check	验证 npm pack 内容	构建后
checks	Node/Bun 测试 + 协议检查	非文档、node 更改
checks-windows	Windows 特定测试	非文档、node 更改
macos	Swift lint/build/test + TS 测试	包含 macos 更改的 PR
android	Gradle 构建 + 测试	非文档、android 更改

快速失败顺序

作业经过排序，使廉价检查在昂贵作业运行之前失败：

1. docs-scope + code-analysis + check（并行，约 1-2 分钟）
2. build-artifacts（受上述阻塞）
3. checks、checks-windows、macos、android（受构建阻塞）

运行器

运行器	作业
blacksmith-16vcpu-ubuntu-2404	大多数 Linux 作业，包括作用域检测
blacksmith-16vcpu-windows-2025	checks-windows
macos-latest	macos、ios

本地等效命令

pnpm check          # 类型 + lint + 格式化
pnpm test           # vitest 测试
pnpm check:docs     # 文档格式 + lint + 损坏链接
pnpm release:check  # 验证 npm pack

---