OpenClaw 中文文档
本页内容

本页内容

查看 Markdown以纯文本查看本页在 ChatGPT 中打开针对本页提问在 Claude 中打开针对本页提问

网关

导出的跨度和诊断事件

导出的 spans

  • openclaw.gateway.rpc.response, openclaw.gateway.rpc.handler, openclaw.gateway.rpc.dispatch

    • 使用 openclaw.gateway.rpc.method、openclaw.gateway.rpc.phase 和 openclaw.gateway.rpc.outcome 完成相位观测
    • Handler跨度包括openclaw.gateway.rpc.admission_ms；调度跨度包括openclaw.gateway.rpc.response，调度结算时的响应状态
    • 保留提供的上游请求父级；它们不会引入长期存在的 RPC 父跨度或更改下游跟踪传播

  • openclaw.model.usage

    • openclaw.channel、openclaw.provider、openclaw.model、可选 openclaw.agent（已知时拥有运行的代理）
    • 仅适用于受信任插件运行时完成的、可选的源自主机的 openclaw.plugin
    • openclaw.tokens.* (input/output/cache_read/cache_write/total)
    • 默认使用 gen_ai.system，或者在启用最新 GenAI 语义约定时使用 gen_ai.provider.name
    • gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.*

插件归属信息仅存在于 span 中。它不会向共享的 OpenTelemetry 指标添加插件维度，也不会更改 Prometheus 指标标签。

  • openclaw.run
    • openclaw.outcome、openclaw.channel、openclaw.provider、openclaw.model、openclaw.errorCategory、可选openclaw.agent
  • openclaw.model.call
    • 默认使用 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.model_call.observation_unit（request 或turn），可选 openclaw.agent
    • 出错时使用 openclaw.errorCategory、error.type，以及可选的 openclaw.failureKind
    • openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
    • openclaw.model_call.prompt.input_messages_count、openclaw.model_call.prompt.input_messages_chars、openclaw.model_call.prompt.system_prompt_chars、openclaw.model_call.prompt.tool_definitions_count、openclaw.model_call.prompt.tool_definitions_chars、openclaw.model_call.prompt.total_chars（仅包含安全的组件大小，不包含提示词文本）
    • 当结果携带该请求或聚合回合的使用量时，包含 openclaw.model_call.usage.* 和 gen_ai.usage.*
    • 当上游提供程序结果公开请求 ID 时，具有属性 openclaw.upstreamRequestIdHash（有界、基于哈希）的 Span 事件 openclaw.provider.request；原始 ID 永远不会导出
    • 当设置 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental 时，请求 spans 使用最新 GenAI 推理 span 名称 {gen_ai.operation.name} {gen_ai.request.model}。由于 OpenClaw 不会从不透明的 CLI 边界声明原生 agent 名称，回合 spans 使用 invoke_agent。两者都使用 CLIENT span 类型，而不是 openclaw.model.call。
  • openclaw.harness.run
    • openclaw.harness.id、openclaw.harness.plugin、openclaw.outcome、openclaw.provider、openclaw.model、openclaw.channel、可选openclaw.agent
    • 完成时：openclaw.harness.result_classification、openclaw.harness.yield_detected、openclaw.harness.items.started、openclaw.harness.items.completed、openclaw.harness.items.active
    • 出错时：openclaw.harness.phase、openclaw.errorCategory、可选的 openclaw.harness.cleanup_failed
    • Span 事件 openclaw.agent.commentary，用于来自支持的harness的完整前导码，包括内置运行时、Codex 和 Claude CLI。属性包括 openclaw.commentary.sequence、openclaw.commentary.text_length 和 openclaw.commentary.content_truncated。现有的 diagnostics.otel.captureContent 设置控制有界的、经过编辑的输出消息内容。
    • With captureContent: true：开始时有界、经过编辑的 input.value 和完成时的 output.value（运行时的最终消息文本）。对于 Claude CLI 后端，input.value 是 CLI 在历史记录重新播种、插件输入文本转换和提示上下文之后收到的精确组合提示； Codex harness记录 OpenClaw 递给它的转弯提示。 Gemini CLI 后端在 openclaw.message.processed 上发布捕获的内容（入站消息和模型的最终响应）；它不会在这些运行级别跨度上记录其组成的 CLI 提示符。
  • openclaw.tool.execution
    • gen_ai.tool.name、gen_ai.operation.name （execute_tool）、openclaw.toolName、openclaw.tool.source、可选 gen_ai.tool.call.id、openclaw.tool.owner、openclaw.tool.params.*、可选openclaw.agent
    • 出错时可选的 openclaw.errorCategory/openclaw.errorCode；当因策略或沙箱被拒绝时，使用 openclaw.deniedReason 和 openclaw.outcome=blocked
  • openclaw.exec
    • openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.exit_signal, openclaw.exec.timed_out
  • openclaw.webhook.processed
    • openclaw.channel, openclaw.webhook
  • openclaw.webhook.error
    • openclaw.channel, openclaw.webhook, openclaw.error
  • openclaw.message.processed
    • openclaw.channel、openclaw.outcome、openclaw.reason、可选 openclaw.agent（最初提取提示的代理）
    • Isolated cron 代理轮流使用此跨度作为其harness跨度的父级，使模型调用、工具和使用在完成或失败时保持在同一跟踪上。
    • 与 captureContent: true：有界、经过编辑的 input.value（入站消息文本）和 output.value（模型自己的响应文本；永远不会捕获挂钩回复和主机通知）
  • openclaw.message.delivery
    • openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory, openclaw.delivery.result_count
  • openclaw.session.stuck
    • openclaw.state, openclaw.ageMs, openclaw.queueDepth
  • openclaw.context.assembled
    • openclaw.prompt.size、openclaw.history.size、openclaw.context.tokens、openclaw.errorCategory（不包含提示词、历史、响应或 session-key 内容）
  • openclaw.tool.loop
    • openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count、可选 openclaw.loop.paired_tool、可选 openclaw.agent（无循环消息、参数或工具输出）
  • openclaw.memory.pressure
    • openclaw.memory.level、openclaw.memory.reason、openclaw.memory.rss_bytes、openclaw.memory.heap_used_bytes、openclaw.memory.heap_total_bytes、openclaw.memory.external_bytes、openclaw.memory.array_buffers_bytes、可选的 openclaw.memory.threshold_bytes/openclaw.memory.rss_growth_bytes/openclaw.memory.window_ms

当显式启用内容捕获时，模型和工具 spans 还可以包含针对你选择启用的特定内容类别的、受限且已脱敏的 openclaw.content.* 属性。

openclaw.message.processed 和 openclaw.harness.run 跨度遵循相同的现有 captureContent 设置。当它是 true 时，input.value 和 output.value 携带入站消息或转向提示以及模型的最终响应文本，每个字段限制为 128 个 KiB（131072 UTF-16 代码单元），并通过与其他导出内容相同的敏感文本过滤器进行编辑。 output.value 记录了 LLM 实际响应的内容（模型自己在传递过滤之前的最终响应），因此 NO_REPLY 等哨兵回复会逐字显示；这是LLM-可观测性数据，不是交货记录。只有模型最后一条消息的文本才有效。传递给 message 工具的模型文本是工具调用的参数，而不是其最终消息，因此仅工具会记录模型的关闭消息（通常是 NO_REPLY）或什么也不记录；发送的文本位于子 openclaw.model.call 输出消息上，对于内置运行时，位于 openclaw.tool.execution 范围 （gen_ai.tool.call.arguments） 上。 CLI 后端不导出工具参数，因此它们的消息工具文本不会在任何范围内捕获。轮中的早期旁白（“现在检查...”）永远不会被报告为最终响应：以工具调用结束的消息不是最终消息，CLI 轮流仅记录最终消息，而不是累积回复文本。模型未编写的文本永远不会被捕获，即使它被传递到聊天：插件挂钩回复（before_dispatch、before_agent_reply）、不可见回复回退、继续状态、失败文本和网关重启通知。没有模型生成的文本的转弯不带有 output.value。捕获的内容仅作为私有侦听器有效负载数据路由到受信任的诊断导出器；它永远不会出现在公共事件有效负载中。

升级说明： 如果您已经使用 diagnostics.otel.captureContent: true 运行，这些消息和运行范围属性是新的 - 您现有的设置现在也导出此提示和回复内容，无需进一步更改配置。当 captureContent 未设置或 false 时，不会导出任何新内容。

诊断事件目录

下面的事件支持 metrics 并跨越上面。公共活动也可用于直接插件订阅；受信任的核心事件（例如 model.usage）仅限于授权的内部使用者。 run.progress 和 run.execution_phase 是直接生命周期信号； Diagnostics-otel 插件不会将它们导出为独立的 OTLP 信号。事件类型和 run.execution_phase.phase 值是相加的。 TypeScript 消费者应该保留默认分支，而不是假设任一联合永久详尽。

在负载丰富和排队之前，没有感兴趣的订阅者或跟踪导出者的事件将被丢弃；它们不会为未来的订阅者缓冲。

agent.commentary 记录完整的前导码，而不是文本增量。它携带原始代理事件序列和时间戳，并附加到活动harness跨度。每次尝试都会抑制最近的重复完成。与其他排队诊断一样，评论可能会在队列压力下被丢弃；会话记录仍然是持久的对话记录。在调试级别，diagnostic 记录器还记录没有注释文本的完成元数据。

模型使用

model.usage 是受信任的进程内诊断事件，而不是 JSONL 日志记录。一个具有代表性的事件如下：

json
{  "type": "model.usage",  "ts": 1735689600000,  "seq": 42,  "provider": "openai",  "model": "gpt-5.4",  "channel": "webchat",  "agentId": "main",  "sessionId": "session-123",  "sessionKey": "agent:main:main",  "usage": {    "input": 120,    "output": 40,    "cacheRead": 30,    "cacheWrite": 10,    "promptTokens": 160,    "total": 200  },  "lastCallUsage": {    "input": 120,    "output": 40,    "cacheRead": 30,    "cacheWrite": 10,    "total": 200  },  "context": { "limit": 128000, "used": 160 },  "costUsd": 0.0012,  "durationMs": 850,  "trace": {    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",    "spanId": "00f067aa0ba902b7",    "traceFlags": "01"  }}
  • ts 是以毫秒为单位的 Unix 时间戳；seq 是进程本地的序列号。
  • usage 保存单轮的令牌计数。promptTokens 包含 input、 cacheRead 和 cacheWrite；如果可用，lastCallUsage 描述最终的模型调用。
  • context.used 是当前 prompt/context 快照，当涉及缓存输入或工具循环调用时，可以低于 usage.total。
  • Provider/model/session标识符、令牌桶、lastCallUsage、context、costUsd、durationMs和trace字段是可选的。 costUsd 是估计值，当模型定价不可用时可以不存在；这不是提供商报告的账单。跟踪上下文还可以包括 parentSpanId。

Gateway 的 /tmp/openclaw/openclaw-YYYY-MM-DD.log JSONL 文件和 diagnostics.otel.logsExporter: "stdout" 包含普通日志记录，而不是原始的 model.usage 事件。公共诊断订阅和 diagnostics.stability 不会暴露受信任的核心使用事件。 diagnostics-otel 插件会将它们转换为诸如 openclaw.tokens 和 openclaw.cost.usd 这样的指标，以及 openclaw.model.usage 跨度；这些使用指标和跨度会有意省略会话标识符。

对于需要按会话关联使用情况的外部集成，请改为查询经过身份验证的 Gateway：

bash
openclaw gateway call sessions.usage --params '{"range":"30d","agentScope":"all"}' --jsonopenclaw gateway usage-cost --days 30 --all-agents --json

这两个命令都需要 operator.read。 sessions.usage 可以包括每个会话的 sessionId、provider/model 详细信息和 token/cost 摘要；当缓存刷新时，每个会话的使用量可以暂时为 null。 usage-cost 提供汇总估算。省略 agentScope 或 --all-agents 可将报告范围限定为默认代理。对于持续更新的客户端， 订阅会话更改，而不是轮询使用情况报告。使用方法和请求选项请参见Gateway RPC方法参考。

消息流转

  • webhook.received / webhook.processed / webhook.error
  • message.queued / message.processed
  • message.delivery.started / message.delivery.completed / message.delivery.error

网关 RPC

  • gateway.rpc - 具有 received、response、handler 和 dispatch 阶段的可信请求观察。响应结果为 ok、error、unavailable 或 suppressed；处理程序结果为 returned 或 threw；调度结果为 returned、threw、rejected 或 cancelled。 Dispatch 在结算时记录其响应状态（none、sent、unavailable 或 suppressed）；稍后的回复仍然可以到达。持续时间和 queue/admission 语义在 Gateway RPC 指标 中描述。

队列和会话

  • queue.lane.enqueue / queue.lane.dequeue
  • session.state / session.long_running / session.stalled / session.stuck
  • run.attempt / run.progress
  • run.execution_phase（公共事件，与会话关联的嵌入式运行器启动里程碑）
  • diagnostic.heartbeat（合计计数器：webhooks/queue/session）
  • gateway.event_loop.sample（仅内部指标完成窗口：intervalMs、delayMaxMs；无读者身份）

Harness 生命周期

  • harness.run.started / harness.run.completed / harness.run.error - 代理harness的每次运行生命周期。包括 harnessId、可选 pluginId、provider/model/channel 和运行 ID。完成添加 durationMs、outcome、可选 resultClassification、yieldDetected 和 itemLifecycle 计数。错误添加 phase （prepare/start/send/resolve/cleanup）、errorCategory 和可选的 cleanupFailed。使用 captureContent: true，开始和完成的事件还带有有界的、经过编辑的转向提示和最终辅助文本，作为在跨度上导出的私有侦听器数据，而不是在公共有效负载上。

Exec

  • exec.process.completed - 最终结果、持续时间、目标、模式、退出码，以及失败类型。命令文本和工作目录不包括在内。
  • exec.approval.followup_suppressed - 过时的批准跟进在盘中反弹后下降。包括 approvalId、reason （session_rebound）、phase（direct_delivery 或 gateway_preflight）和调度程序时间戳。不包括会话密钥、路由和命令文本。
本页有帮助吗？