跳转至

配置 — 审计、日志、诊断和遥测

可观测性键：audit.*、logging.*、diagnostics.* 和 telemetry.*。

有关完整键索引及其他顶层配置域，请参阅配置参考。

审计

{
  logging: {
    audit: {
      enabled: true,
      executionIdentity: false,
      messages: "off", // off | direct | all
    },
  },
}

网关会将代理运行和工具操作的仅元数据审计事件记录到共享状态数据库中。消息生命周期元数据是单独的选择启用项。账本存储身份、时间、工具名称和规范化结果，但绝不存储提示词、消息正文、工具参数、结果或原始错误文本。消息行不存储原始平台账户、会话、消息和目标 ID。运行/工具会话键仍可用于关联分析，且其本身可能包含平台账户或对等节点 ID。记录在 30 天后过期，账本上限为 100,000 行。可通过 openclaw audit 或 audit.activity.list 网关 RPC 查询。有关完整数据模型、隐私语义和覆盖范围限制，请参阅审计历史。

  • enabled：记录新的审计事件（默认值：true）。账本默认开启，因为仅在事件发生后启用的审计轨迹无法解释该事件。设为 false 会立即停止收集新事件；现有记录在过期前仍可读取。重新开启后会从该时间点恢复记录——空缺部分不会回填。
  • executionIdentity：保留有界的归因上下文，以便进行精确的执行检查（默认值：false）。此隐私敏感元数据在新安装和升级后默认禁用。收集需要 enabled: true；使用 openclaw config set logging.audit.executionIdentity true 为新接纳的运行启用它。没有对应的环境变量别名。
  • messages：消息元数据范围（默认值："off"）。"direct" 仅记录已知的直接对话。"all" 还记录群组、频道和未知对话类型。两种模式均保持无内容状态，并在可关联时用安装本地的带键假名替换原始标识符。这些是关联辅助手段而非匿名化；状态数据库存储派生键，但 RPC 和 CLI 导出内容不包含。

根级 audit 块已退役；规范路径为 logging.audit。根配置对象是严格的，因此旧的顶层 audit 块会被拒绝。运行 openclaw doctor --fix 将其迁移到 logging.audit。

所有三项设置均可实时生效。已接受的写入仍通过同一个写入器流出，保留的身份上下文保持不变。启用收集不会回填活动记录，也不会为已接纳的运行添加身份信息。消息覆盖范围包括到达核心分发的已接受入站消息，以及每个到达共享持久投递的原始逻辑出站回复负载对应的一行终止记录。绕过这些共享边界的插件本地和直接发送路径不在覆盖范围内。有界后台写入器是尽力而为的，并非无损的合规存档。

日志

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | json
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}
  • 默认日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log；命名配置文件使用 /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log。当 /tmp/openclaw 不安全或不可用时（以及始终在 Windows 上），OpenClaw 会改用操作系统临时目录下的子目录：在存在数字用户 ID 时使用 openclaw-<uid>，否则使用纯 openclaw，这包括 Windows。带日期的日志文件在 24 小时后会被清理。
  • 设置 logging.file 以使用固定路径。
  • 使用 --verbose 时，consoleLevel 会提升为 debug。
  • consoleStyle："pretty" 或 "json"。较早的 "compact" 值已退役；openclaw doctor --fix 会将其映射为 "pretty"。
  • maxFileBytes：轮转前活动日志文件的最大字节数（正整数；默认值：104857600 = 100 MB）。OpenClaw 会在活动文件旁保留最多五个编号归档文件。
  • redactPatterns：用于对控制台输出、文件日志、OTLP 日志记录和持久化会话记录文本进行尽力而为屏蔽的正则表达式。设置此项仅替换日志和记录输出的默认字符串正则表达式列表。内置的表单正文、结构化认证头和裸 AWS 密钥保护始终生效。工具负载的脱敏是独立的，并且始终会将你的模式与默认字符串列表合并。
  • 脱敏始终开启，且不再可配置。openclaw doctor --fix 会从较旧的配置文件中移除已退役的开关；运行时始终对日志和记录应用 tools 模式脱敏。UI、工具和诊断安全界面独立于该策略对机密信息进行脱敏。

诊断

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf",
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      logsExporter: "otlp",
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: false,
    },

    cacheTrace: {
      enabled: false,
    },
  },
}
  • enabled：插桩输出的总开关（默认值：true）。
  • flags：启用定向日志输出的标志字符串数组（支持 "telegram.*" 或 "*" 等通配符）。
  • otel.enabled：启用 OpenTelemetry 导出管道（默认值：false）。有关完整配置、信号目录和隐私模型，请参阅 OpenTelemetry 导出。
  • otel.endpoint：OTel 导出的收集器 URL。
  • otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint：可选的信号专用 OTLP 端点。设置后，它们仅对该信号覆盖 otel.endpoint。
  • otel.protocol："http/protobuf"（默认值）。gRPC 导出已退役；运行 openclaw doctor --fix 以修复已持久化的旧值，或获取特定来源的手动编辑指导。
  • otel.headers：随 OTel 导出请求发送的额外 HTTP 请求头。
  • otel.serviceName：资源属性的服务名称。
  • otel.traces / otel.metrics / otel.logs：启用追踪、指标或日志导出。
  • otel.logsExporter：日志导出接收端："otlp"（默认值）、"stdout"（每行 stdout 输出一个 JSON 对象）或 "both"。
  • otel.sampleRate：追踪采样率，范围 0-1。
  • otel.flushIntervalMs：周期性遥测刷新的间隔毫秒数。
  • otel.captureContent：OTEL span 属性的选择启用内容捕获。默认关闭。true 会捕获非系统可见的消息、工具和工具定义内容以及 OTLP 日志正文；提供方内部的思考负载仍被排除在外。
  • OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental：用于最新实验性 GenAI 推理 span 形态的环境开关，包括 {gen_ai.operation.name} {gen_ai.request.model} span 名称、CLIENT span 类型，以及使用 gen_ai.provider.name 替代旧的 gen_ai.system。默认情况下，span 为兼容性保留 openclaw.model.call 和 gen_ai.system；GenAI 指标使用有界的语义属性。
  • OPENCLAW_OTEL_PRELOADED=1：用于已注册全局 OpenTelemetry SDK 的主机的环境开关。OpenClaw 随后会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、OTEL_EXPORTER_OTLP_METRICS_ENDPOINT 和 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT：当对应的配置键未设置时使用的信号专用端点环境变量。
  • OTEL_EXPORTER_OTLP_TRACES_PROTOCOL、OTEL_EXPORTER_OTLP_METRICS_PROTOCOL 和 OTEL_EXPORTER_OTLP_LOGS_PROTOCOL：当 otel.protocol 未设置时使用的信号专用协议回退值。每个变量都针对其对应信号覆盖 OTEL_EXPORTER_OTLP_PROTOCOL。
  • OTEL_EXPORTER_OTLP_PROTOCOL：当 otel.protocol 和对应的信号专用变量均未设置时使用的共享协议回退值。仅支持 http/protobuf。协议验证按信号隔离，因此不支持的解析值只会禁用该信号的 OTLP 导出器，而不会阻止受支持的兄弟信号。Doctor 不会重写环境变量。
  • cacheTrace.enabled：记录嵌入式运行的缓存追踪快照（默认值：false）。

遥测

{
  telemetry: {
    enabled: false,
    consentedAt: "2026-08-02T12:00:00.000Z",
  },
}
  • enabled：在现有每日更新检查请求中包含已公开配置的通道和提供商名称、插件清单名称和数量，以及保留的会话创建计数（默认：false）。这些字段不会测量按插件的使用情况或活动会话。交互式设置可以提供明确的加入选项，默认选中 不用了；非交互式设置不会自动启用它，但可以保留明确启用的偏好设置。DO_NOT_TRACK=1 或 DO_NOT_TRACK=true 始终禁用功能统计，而不会禁用更新检查。
  • consentedAt：记录操作员接受或拒绝功能统计时间的 ISO 时间戳。防止交互式设置再次询问。
  • openclaw telemetry show 使用 CLI 进程的当前上下文预览请求，该上下文可能与正在运行的 Gateway 不同；openclaw telemetry on 和 openclaw telemetry off 会更新偏好设置和同意时间戳。
  • OPENCLAW_TELEMETRY_ENDPOINT：用于测试或自托管服务的可选完整端点 URL。默认为 https://telemetry.openclaw.ai/api/latest-version。

有关完整负载、隐私保证和所有退出控制，请参阅使用遥测和更新检查。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw