指标

模型调用观测单位¶

每个 openclaw.model.call span 通过 openclaw.model_call.observation_unit 标识其生命周期度量内容：

• request — 一个可观测的模型/提供商请求。原生嵌入式模型调用使用此单位，导出器为了兼容较旧或外部发射器，会将缺失值视为 request。
• turn — 一个不透明的代理 CLI 回合，其中可能包含隐藏的模型请求、重试、工具工作或后台工作。Claude Code CLI 和 Codex app-server 调用使用此单位。

这两种单位都仍然是模型调用 span，因此追踪后端可以渲染模型输入、输出、用量和层级。请求 span 使用 API 派生的 GenAI 操作（chat、generate_content 或 text_completion），而回合 span 使用 gen_ai.operation.name = invoke_agent。两者都会贡献到 gen_ai.client.operation.duration，其中操作名称将直接请求延迟与完整回合延迟分开。OpenClaw 的 OTEL 模型调用指标也包含 openclaw.model_call.observation_unit；Prometheus 模型调用指标暴露等效的 observation_unit 标签。

Claude Code CLI 模型调用保真度¶

Claude Code CLI 回合会发出一个合成的回合级 openclaw.model.call span。这些不是 Anthropic HTTP 请求 span。它们使用 openclaw.api = claude-code、openclaw.model_call.observation_unit = turn，并将操作标识为 gen_ai.operation.name = invoke_agent。它们通过 openclaw.transport 标识 OpenClaw 的 CLI 边界：

• stdio — 一次性本地 Claude Code 进程。
• stdio-live — 托管持久 Claude stdio 会话上的一个回合。
• paired-node-cli — 委托给配对节点的一次性 Claude Code 执行。

Claude CLI 诊断仅在进程诊断分发器启用且附加了内部或受信任的事件监听器时才会实例化。当没有可观测性插件或其他监听器处于活动状态时，Claude CLI 回合会跳过合成追踪层级、内容缓冲区和诊断流字节统计。启用内容捕获时，prompt 和 system-prompt 字段各自上限为 128 KiB；助手输出在至多 200 个信封中总计上限为 128 KiB，其中为最终可见的回退响应预留 16 KiB 和一个条目。达到限制时，一个标记会记录截断。

OpenClaw 为 Claude CLI 回合提供与其他代理运行时相同的归属层级：openclaw.harness.run（openclaw.harness.id = claude-cli）包含 openclaw.run，而后者包含 Claude 的 openclaw.model.call span。harness 和 run span 是合成的 OpenClaw 回合边界，而不是 Claude Code 内部阶段。一次性 stdio 回合和托管 stdio 回合使用相同的层级；真正的全新会话重试会在同一个 OpenClaw run 内再创建一个模型调用子 span。

该 span 在 OpenClaw 接纳准备好的 CLI 回合时开始，并仅在该回合成功或失败后才结束。对于托管会话，当 Claude 报告持有结果的后台代理或工作流时，中间成功结果不会结束该 span；最终排空后的结果才会结束。中止、超时、进程失败、输出/解析失败以及其他回合失败都会以错误状态结束同一个 span。

Claude Code 报告每条助手消息的用量，也可能在其最终结果上报告累计用量。OpenClaw 的回复统计继续使用最后一条助手消息，因此现有成本语义不变；回合级模型调用 span 在可用时使用最终累计用量，包括 cache-read 和 cache-creation token。

对于这些 CLI span，字节和时序字段描述的是可观测的 OpenClaw CLI 边界：

• openclaw.model_call.request_bytes 是通过一次性 stdin/argv 发送的 prompt 值，或托管 stdio JSONL 用户信封的 UTF-8 大小。它不是 Claude Code 隐藏模型请求的大小。
• openclaw.model_call.response_bytes 是回合期间观测到的 Claude CLI stdout 的 UTF-8 大小。它不是 Anthropic HTTP 响应大小。
• openclaw.model_call.time_to_first_byte_ms 是到首个可观测 Claude CLI stdout 或 stderr 输出的时间。它不是网络 TTFB。

启用 captureContent 后，span 通过 gen_ai.input.messages 和 gen_ai.output.messages 导出 OpenClaw 发送给 Claude Code 的有效 prompt，以及可见的助手文本/工具调用标识。Claude 助手信封中会省略工具参数、内部思考、不透明的思考签名、工具结果和系统提示。OpenClaw 不声称可以访问 Claude Code 的私有系统提示、隐藏的恢复或压缩请求负载、原生内部工具 schema、原始 Anthropic HTTP 请求、内部重试、上游请求 ID 或真实网络 TTFB。由于 Claude Code 无法准确暴露其有效的原生工具定义，这些 span 不会填充 gen_ai.tool.definitions。

即使启用了工具内容捕获，外部 Claude harness 工具 span 仍仅包含元数据。与每个模型 span 一样，捕获的 Claude CLI 内容使用仅受信任监听器路径以及导出器现有的脱敏和大小限制；内容默认保持关闭。

导出的指标¶

网关 RPC¶

经过身份验证的 Gateway WebSocket 请求（包括专用 worker RPC）在诊断启用且存在感兴趣的导出器时会发出这些指标。它们不包括连接握手、格式错误的请求帧和 HTTP 路由。

请求和计时指标仅有 openclaw.gateway.rpc.method 属性：核心或 Worker 方法的规范名称、插件方法的 other，或 unknown。结果指标仅有 openclaw.gateway.rpc.phase 和 openclaw.gateway.rpc.outcome 属性，因此错误不会使每个方法的序列成倍增加。指标属性中不包含请求、连接、会话或追踪 ID。

Operator 准入包括授权、路由器和处理器的懒加载，以及启动队列等待。Worker 准入包括套接字 FIFO 等待和外部帧验证。Worker 处理器耗时包括方法验证和服务调用。Worker 计时从 JavaScript 套接字回调开始，不包含该回调之前的网络延迟和事件循环延迟。对于已启动的处理器，队列等待是准入的一个子集，与命令/会话通道的 openclaw.queue.wait_ms 分开。处理器和准入样本仅针对已调用的处理器存在。队列等待在派发落定时记录。

Worker 推理启动计时衡量的是受理与设置，而非提供方完成情况。长时间运行的 Worker 计算机操作和会话操作在释放套接字 FIFO 后仍保留其处理器耗时。Worker 派发结果描述返回或抛出。连接关闭可能在成功执行后抑制响应，但本身并不能证明执行被取消。

已发送响应意味着 WebSocket 发送方接受了该帧，而非客户端已收到。早期确认计作首个响应；后续响应不会新增样本。不可用或被抑制的发送会贡献结果，但不会产生首响应样本。处理器可能在保留的回调发送其响应之前返回，之后分离的智能体工作可以继续。这些耗时度量的是经过的时间（包括异步等待），而非 CPU 时间或事件循环阻塞时间。

观测使用有界诊断队列。在饱和期间，先检查 openclaw.diagnostic.async_queue.dropped，再将计数或延迟分布视为完整。

模型用量¶

• openclaw.tokens（计数器，属性：openclaw.token、openclaw.channel、openclaw.provider、openclaw.model、openclaw.agent）
• 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）
• gen_ai.client.token.usage（直方图，GenAI 语义约定指标，属性：gen_ai.token.type = input/output、gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model）
• gen_ai.client.operation.duration（直方图，秒，用于模型请求和合成智能体轮次的 GenAI 语义约定指标；属性：gen_ai.provider.name、gen_ai.operation.name、gen_ai.request.model，可选 error.type；轮次观测使用 gen_ai.operation.name = invoke_agent）
• openclaw.model_call.duration_ms（直方图，属性：openclaw.provider、openclaw.model、openclaw.api、openclaw.transport、openclaw.model_call.observation_unit，以及分类错误上的 openclaw.errorCategory 和 openclaw.failureKind）
• openclaw.model_call.request_bytes（直方图，最终模型请求负载的 UTF-8 字节大小；对于 Claude Code CLI，为上述可观测的提示输入/信封；不包含原始负载内容）
• openclaw.model_call.response_bytes（直方图，流式响应块负载的 UTF-8 字节大小；高频文本、思考和工具调用增量仅计 delta 增量字节；对于 Claude Code CLI，为观测到的 stdout 字节；不包含原始响应内容）
• openclaw.model_call.time_to_first_byte_ms（直方图，首个流式响应事件之前的经过时间；对于 Claude Code CLI，为首次可观测的 CLI 输出，而非网络 TTFB）
• openclaw.model.failover（计数器，属性：openclaw.provider、openclaw.model、openclaw.failover.to_provider、openclaw.failover.to_model、openclaw.failover.reason、openclaw.failover.suspended、openclaw.lane）
• openclaw.skill.used（计数器，属性：openclaw.skill.name、openclaw.skill.source、openclaw.skill.activation，可选 openclaw.agent，可选 openclaw.toolName）

消息流¶

• 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.received（计数器，属性：openclaw.channel、openclaw.source）
• openclaw.message.dispatch.started（计数器，属性：openclaw.channel、openclaw.source）
• openclaw.message.dispatch.completed（计数器，属性：openclaw.channel、openclaw.outcome、openclaw.reason、openclaw.source）
• openclaw.message.dispatch.duration_ms（直方图，属性：openclaw.channel、openclaw.outcome、openclaw.reason、openclaw.source）
• openclaw.message.processed（计数器，属性：openclaw.channel、openclaw.outcome）
• openclaw.message.duration_ms（直方图，属性：openclaw.channel、openclaw.outcome）
• openclaw.message.delivery.started（计数器，属性：openclaw.channel、openclaw.delivery.kind）
• openclaw.message.delivery.duration_ms（直方图，属性：openclaw.channel、openclaw.delivery.kind、openclaw.outcome、openclaw.errorCategory）

对话¶

• openclaw.talk.event（计数器，attrs：openclaw.talk.event_type、openclaw.talk.mode、openclaw.talk.transport、openclaw.talk.brain、openclaw.talk.provider）
• openclaw.talk.event.duration_ms（直方图，attrs：与 openclaw.talk.event 相同；在 Talk 事件报告持续时间时发出）
• openclaw.talk.audio.bytes（直方图，attrs：与 openclaw.talk.event 相同；在 Talk 音频帧事件报告字节长度时发出）

队列与会话¶

• openclaw.queue.lane.enqueue（计数器，attrs：openclaw.lane）
• openclaw.queue.lane.dequeue（计数器，attrs：openclaw.lane）
• openclaw.queue.depth（直方图，attrs：openclaw.lane 或 openclaw.channel=heartbeat）
• openclaw.queue.wait_ms（直方图，attrs：openclaw.lane）
• openclaw.session.state（计数器，attrs：openclaw.state、openclaw.reason）
• openclaw.session.stuck（计数器，attrs：openclaw.state；在可恢复的过期会话簿记时发出）
• openclaw.session.stuck_age_ms（直方图，attrs：openclaw.state；在可恢复的过期会话簿记时发出）
• openclaw.session.turn.created（计数器，attrs：openclaw.agent、openclaw.channel、openclaw.trigger）
• openclaw.session.recovery.requested（计数器，attrs：openclaw.state、openclaw.action、openclaw.active_work_kind、openclaw.reason）
• openclaw.session.recovery.completed（计数器，attrs：openclaw.state、openclaw.action、openclaw.status、openclaw.active_work_kind、openclaw.reason）
• openclaw.session.recovery.age_ms（直方图，attrs：与对应的恢复计数器相同）
• openclaw.run.attempt（计数器，attrs：openclaw.attempt）

会话活性遥测¶

当 OpenClaw 观察到回复、工具、状态、block 或 ACP 运行时进度时，processing 会话不会向内置活性阈值老化。打字 keepalive 不算作进度，因此静默的模型或 harness 仍可被检测到。

OpenClaw 根据其仍能观测到的工作将会话分类：

• session.long_running：活跃的嵌入式工作、模型调用或工具调用仍在取得进展。自有静默模型调用在内置中止阈值之前也报告为 long-running，因此，在仍可观测并中止它们的期间，缓慢或非流式的模型提供商不会看起来像停滞的网关会话。
• session.stalled：存在活跃工作，但当前运行尚未报告近期进展。自有模型调用在达到或超过内置中止阈值时，会从 session.long_running 切换为 session.stalled；无主的过期模型/工具活动不会被当作无害的长期运行工作。停滞的嵌入式运行一开始仅处于观测模式（observe-only），然后在超过中止阈值且仍无进展时进行中止排空（abort-drain），以便车道后方排队的轮次得以恢复。
• session.stuck：没有活跃工作的过期会话簿记，或带有过期无主模型/工具活动的空闲排队会话。恢复门控通过后，将立即释放受影响的会话车道。

恢复机制会发出结构化的 session.recovery.requested 和 session.recovery.completed 事件。仅当产生变更的恢复结果（aborted 或 released）出现之后，且同一处理代（processing generation）仍为当前代时，会话的诊断状态才会被标记为空闲。

只有 session.stuck 会发出 openclaw.session.stuck 计数器、openclaw.session.stuck_age_ms 直方图以及 openclaw.session.stuck span。在会话保持不变的情况下，重复的 session.stuck 诊断会退避（back off），因此仪表盘应针对持续增长发出告警，而不是对每次心跳滴答都告警。有关配置项和默认值，请参阅配置参考。

活性警告还会发出：

• openclaw.liveness.warning（计数器，attrs：openclaw.liveness.reason）
• openclaw.liveness.event_loop_delay_p99_ms（直方图，attrs：openclaw.liveness.reason）
• openclaw.liveness.event_loop_delay_max_ms（直方图，attrs：openclaw.liveness.reason）
• openclaw.liveness.event_loop_utilization（直方图，attrs：openclaw.liveness.reason）
• openclaw.liveness.cpu_core_ratio（直方图，attrs：openclaw.liveness.reason）

CPU 比率以核心当量（core equivalents）衡量整个进程的 CPU 使用率，包括工作线程和原生线程，并且可能超过 1。事件循环延迟和利用率分别衡量主线程。请参阅 CPU 压力与事件循环延迟。

网关事件循环观测窗口¶

• openclaw.gateway.event_loop.delay_max_ms（直方图，无 attrs；每个已完成的健康监控窗口的最大延迟）
• openclaw.gateway.event_loop.observed_ms（计数器，无 attrs；已完成的窗口所代表的经过毫秒数）

这些指标使用现有的诊断插件设置，并且需要指标处于激活状态。每个被接受的健康监控窗口都会被记录一次，因此后续的健康就绪结果不会抹除先前的高延迟观测。健康检查与抓取（scrape）读取不会提交或重置样本。进程级观测不携带请求追踪上下文，也不会创建任何 span 或日志，即使使用预加载的 SDK 也是如此。

监控器每 20 毫秒对事件循环间隔采样一次，并在至少一秒后完成窗口，或在出现延迟警告时更早完成。常规的窗口重置会保留待处理（pending）的间隔，即使健康状态是在某个逾期样本之前被读取的也是如此。计数和分位数描述的是已完成的窗口及其最大值，而不是单个停滞事件或采样延迟分布的整体 p99。有意的监控器重置会丢弃未完成的窗口；如果没有感兴趣的导出器，采集不会回填这些时间段。诊断队列丢弃、SDK/导出失败以及重启都会限制覆盖范围。请使用代表时长（represented-duration）计数器和导出器/丢弃遥测来评估覆盖情况。就绪决策和持续的活性警告阈值保持不变。有关拉取指标和示例查询，请参阅 Prometheus 事件循环窗口。

Harness 生命周期¶

• openclaw.harness.duration_ms（直方图，attrs：openclaw.harness.id、openclaw.harness.plugin、openclaw.outcome，错误时含 openclaw.harness.phase）

工具执行与循环检测¶

• openclaw.tool.execution.duration_ms（直方图，属性：gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind，错误时附加 openclaw.errorCategory）
• openclaw.tool.execution.blocked（计数器，属性：gen_ai.tool.name、openclaw.toolName、openclaw.tool.source、openclaw.tool.owner、openclaw.tool.params.kind、openclaw.deniedReason）
• openclaw.tool.loop（计数器，属性：openclaw.toolName、openclaw.loop.level、openclaw.loop.action、openclaw.loop.detector、openclaw.loop.count，可选 openclaw.loop.paired_tool；在检测到重复的工具调用循环时发出）

执行（Exec）¶

• openclaw.exec.duration_ms（直方图，属性：openclaw.exec.target、openclaw.exec.mode、openclaw.outcome、openclaw.failureKind）

诊断内部机制（内存、载荷、导出器健康状态）¶

• openclaw.gc.duration_ms（直方图，无属性；宿主 JavaScript 隔离区的垃圾回收耗时）

GC 耗时使用 Node.js performance entries，并且仅在启用指标时导出。它既不是 CPU 时间，也不保证是 stop-the-world 暂停。观测从现有诊断心跳检测到感兴趣的使用者时开始；启动后的注册需要等待下一个 30 秒周期，且不会回填历史数据。诊断禁用/关闭会立即断开连接。参见 GC 耗时覆盖范围与相关性限制。

• openclaw.payload.large（计数器，属性：openclaw.payload.surface、openclaw.payload.action、openclaw.channel、openclaw.plugin、openclaw.reason）
• openclaw.payload.large_bytes（直方图，属性：与 openclaw.payload.large 相同）
• 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.pressure（计数器，属性：openclaw.memory.level、openclaw.memory.reason）
• openclaw.diagnostic.async_queue.dropped（计数器，属性：openclaw.diagnostic.async_queue.drop_class；内部诊断队列背压丢弃）
• openclaw.telemetry.exporter.events（计数器，属性：openclaw.exporter、openclaw.signal、openclaw.status，可选 openclaw.reason，可选 openclaw.errorCategory；导出器生命周期/故障自监控）