clawpro-diagnostics-metrics-cls 2.0.0 → 2.0.2

package/README.md

@@ -8,8 +8,41 @@ OpenClaw 诊断指标导出插件，提供以下核心能力：
 
 ---
 
+## ⚠️ 数据访问声明（请务必阅读）
+
+> **本插件需要读取 LLM 会话内容才能产出 token / 长度 / 耗时类指标和 Trace 数据。**
+> 通过 onboard CLI 的 `install` / `UpdateParameter` 命令安装时，CLI 会自动在 `~/.openclaw/openclaw.json` 中为本插件写入 `plugins.entries["clawpro-diagnostics-metrics-cls"].hooks.allowConversationAccess = true`，以满足 OpenClaw 对 non-bundled 插件 typed hook 的安全策略。**安装即视为您授权本插件访问会话内容**，请在团队 / 公司合规要求允许的前提下使用。
+
+### 一、本插件会接触哪些数据
+
+| 数据类别 | 来源 hook | 是否上报到 CLS |
+|---|---|---|
+| 用户输入的 prompt 原文（含系统提示词、对话历史） | `llm_input` / `message_received` | ✅ 默认会通过 Trace 模块写入 CLS 的 **Trace 日志主题**（`traceTopicId`）字段 `gen_ai.input.messages` / `gen_ai.prompt`，未配置 `traceTopicId` 或 `trace.enabled=false` 时不上报 |
+| 模型生成的 completion 原文 | `llm_output` / `before_message_write` | ✅ 同上，写入字段 `gen_ai.output.messages` / `gen_ai.completion` |
+| Agent 最终输出 / 工具调用参数 / 工具返回结果 | `agent_end` / `before_tool_call` / `after_tool_call` | ✅ 同上，写入字段 `gen_ai.output.messages` / `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` |
+| Token 用量 / 耗时 / 模型名等元数据 | 全部 hook | ✅ 写入 **Prometheus 指标主题**（`metricTopicId`），**不含原文** |
+
+> Prometheus 指标主题（`metricTopicId`）只承载聚合后的数值类指标（counter / histogram / gauge），**不会包含 prompt 或 completion 原文**；会话原文仅出现在 Trace 主题（`traceTopicId`）中。
+
+### 二、如果您不希望插件读取会话原文
+
+可以选择以下任一方式，按需削减插件的数据访问范围：
+
+1. **完全禁用 Trace，仅保留指标**：`UpdateParameter --traceEnabled false`，或在 `openclaw.json` 中将 `plugins.entries["clawpro-diagnostics-metrics-cls"].config.trace.enabled` 设为 `false`。此时插件仍会保留 `allowConversationAccess=true` 以采集 token / 耗时类指标，但**不再向 CLS 写入任何 prompt / completion 原文**。
+2. **按 hook 粒度禁用**：在 `openclaw.json` 的 `config.trace.enabledHooks` 中只列出您允许的 hook（例如只保留 `["session_start", "session_end", "agent_end"]` 等不直接携带消息内容的 hook，不包含 `llm_input` / `before_message_write`），其余 hook 不会被注册到 OpenClaw runtime。
+3. **彻底拒绝插件访问会话内容**：在 `openclaw.json` 中手动将 `plugins.entries["clawpro-diagnostics-metrics-cls"].hooks.allowConversationAccess` 设为 `false`，OpenClaw 会拦截 `llm_input` / `llm_output` / `agent_end` 等 typed hook，本插件相关指标和 trace 将不可用，但其它非会话类指标（如 webhook、队列、会话状态等）仍正常工作。
+
+### 三、CLS 侧数据安全建议
+
+- 为 `traceTopicId` 单独创建日志主题，配置最严格的访问权限（仅运维 / SRE 可读），不要与业务日志主题混用。
+- 如需进一步限制原文长度，插件已内置**结构感知式渐进裁剪**（详见下文 Trace 章节"超长截断策略"），单字段最大 3,200,000 字符，APM 索引字段单条消息最长 4,096 字符。
+- 上报前可通过 `external_labels` 加上 `data_classification=internal` 等业务标签，便于在 CLS 侧做 RBAC / 脱敏策略。
+
+---
+
 ## 目录
 
+- [⚠️ 数据访问声明（请务必阅读）](#-数据访问声明请务必阅读)
 - [快速安装（推荐）](#快速安装推荐)
 - [手动安装](#手动安装)
 - [配置说明](#配置说明)
@@ -69,6 +102,10 @@ npx --yes clawpro-diagnostics-metrics-cls-onboard-cli install
 | `--externalLabels <labels>` | Prometheus 自定义标签（格式：`key1=value1,key2=value2`） | 可选 |
 | `--traceEnabled <bool>` | 是否启用 Trace 链路追踪功能（`true`/`false`，默认 `true`） | 可选 |
 | `--traceTopicId <id>` | Trace 数据上报使用的 CLS 日志主题 ID | 可选（可在配置文件中动态更新） |
+| `--instanceId <id>` | 显式指定实例 ID，写入配置文件后插件启动时直接使用，跳过腾讯云 metadata 接口请求 | 可选 |
+| `--instanceName <name>` | 显式指定实例名称，仅覆盖 `cvm_instance_name`，不影响 `host_name`（后者始终取 `os.hostname()`） | 可选 |
+| `--localIpv4 <ip>` | 显式指定内网 IPv4 | 可选 |
+| `--pluginVersion <version>` | 指定安装的插件版本号（如 `1.2.3`），仅在从 npm registry 安装时生效；本地路径存在时忽略 | 可选，默认安装最新版本 |
 
 ### 安装示例
 
@@ -120,6 +157,17 @@ npx clawpro-diagnostics-metrics-cls-onboard-cli install \
   --traceTopicId "zzzzzzzz-trace-topic-id"
 ```
 
+安装指定版本（从 npm registry 安装时生效）：
+
+```bash
+npx openclaw-diagnostics-metrics-cls-onboard-cli install \
+  --metricTopicId "xxxxxxxx-metric-topic-id" \
+  --secretId "AKIDxxxxxxxx" \
+  --secretKey "xxxxxxxxxxxxxxxx" \
+  --endpoint "ap-guangzhou.cls.tencentcs.com" \
+  --pluginVersion "1.2.3"
+```
+
 安装完成后，CLI 会自动重启网关并输出确认信息：
 
 ```
@@ -776,9 +824,8 @@ Trace 数据中同时包含以下 APM 兼容的索引属性，可在 CLS 控制
 | `cvm_instance_intra_ip` | string | CVM 内网 IP | `instance-metadata.ts` 通过腾讯云 metadata API 获取 `local-ipv4` | 网络定位和故障排查 |
 | `cvm_instance_internet_ip` | string | CVM 公网 IP | `instance-metadata.ts` 通过腾讯云 metadata API 获取 `public-ipv4` | 网络定位和故障排查 |
 | `cvm_instance_region` | string | CVM 所在地域 | `instance-metadata.ts` 通过腾讯云 metadata API 获取 `placement/region` | 标识实例所在地域 |
-| `host_name` | string | 操作系统 hostname | `instance-metadata.ts` 中 `os.hostname()` | 与 `host.name` 类似，字段名格式与指标服务一致 |
 
-> **说明**：`cvm_*` 和 `host_name` 字段仅在腾讯云环境下有值，非腾讯云环境不注入。
+> **说明**：`cvm_*` 字段仅在腾讯云环境下有值，非腾讯云环境不注入。
 
 ##### 三、通用 Span 属性（`createSpan()` 注入）
 
@@ -1012,14 +1059,28 @@ agent_end (结束所有长生命周期 Span)
 | 字段 | 获取方式 | 说明 |
 |------|---------|------|
 | `cvm_instance_id` | 腾讯云 Metadata 接口 `/latest/meta-data/instance-id` | 实例 ID |
-| `cvm_instance_name` | `os.hostname()` 本机主机名 | 实例名称 |
-| `cvm_instance_intra_ip` | 遍历本地网卡接口（非回环、非虚拟网卡的 IPv4 地址） | 内网 IPv4 地址 |
+| `cvm_instance_name` | 腾讯云 Metadata 接口 `/latest/meta-data/instance-name` | 实例名称 |
+| `cvm_instance_intra_ip` | 腾讯云 Metadata 接口 `/latest/meta-data/local-ipv4` | 内网 IPv4 地址 |
+| `host_name` | `os.hostname()` 本机主机名 | OTel 资源属性，独立于 CVM 实例名（不参与持久化） |
+
+> **用户覆盖（Override）**：可在 `openclaw.json` 的 `plugins.entries["openclaw-diagnostics-metrics-cls"].config.instance_metadata` 下显式传入以下字段，覆盖自动获取值。这三个字段**支持热更新**，修改配置文件后约 10 秒内自动生效，无需重启网关：
+>
+> | 配置字段 | 覆盖目标 | 跳过的自动逻辑 |
+> |---------|---------|---------------|
+> | `instance_id` | `cvm_instance_id` | 腾讯云 Metadata HTTP 请求（以及 `openclaw.json` 持久化读写）、首次失败重试 |
+> | `instance_name` | `cvm_instance_name` | 腾讯云 Metadata HTTP 请求与 `openclaw.json` 持久化读写（**但不影响 `host_name` 字段**，后者始终取 `os.hostname()`） |
+> | `local_ipv4` | `cvm_instance_intra_ip` | 腾讯云 Metadata HTTP 请求与 `openclaw.json` 持久化读写 |
+>
+> 空字符串或缺失视为未提供，仍走原自动获取逻辑。任一字段提供后，对应的网络请求/持久化读写均会被跳过。
 
 #### 刷新策略
 
-- 启动时优先从持久化文件（`openclaw.json`）的插件配置项（`plugins.entries["clawpro-diagnostics-metrics-cls"].config.instance_metadata.instance_id`）读取已缓存的 `instance-id`，若已有则直接使用，不发起网络请求
-- 若无持久化值，则立即通过 metadata 接口获取（请求超时 2 秒），成功后写入 `openclaw.json` 的插件配置项持久化，不再启动定时刷新
-- 首次获取失败的字段会在 30 秒后重试，最多重试 3 次，重试成功后同样持久化并停止重试
+- 优先级：**`openclaw.json` 中 `instance_metadata` 显式配置值** > `openclaw.json` 已持久化值 > 腾讯云 metadata 接口
+- 持久化字段：`plugins.entries["clawpro-diagnostics-metrics-cls"].config.instance_metadata.{instance_id, instance_name, local_ipv4}`
+- 启动时先从持久化文件读取三个字段，已有值的字段直接使用，不发起网络请求
+- 仅对- 仅对"未被 override 覆盖且无持久化值"的字段调用 metadata 接口（请求超时 2 秒），成功后立即增量写入 `openclaw.json`；写入采用文件锁 + 临时文件 rename 的方式，支持多进程并发
+- 首次获取失败的字段会在 30 秒后重试，最多重试 3 次；仅当仍存在未就绪字段时才继续重试，全部就绪后停止
+- 用户显式传入的 `*_override` 值**不会**被持久化写入 `openclaw.json`（视为用户已掌握权威值）
 - 非腾讯云环境下，元数据字段为空字符串，不影响插件正常运行
 
 ---
@@ -1052,6 +1113,9 @@ npx --yes clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter [选项]
 | `--externalLabels <labels>` | Prometheus 自定义标签（格式：`key1=value1,key2=value2`） | ✅ 需要重启网关 |
 | `--traceEnabled <bool>` | 是否启用 Trace 链路追踪功能（`true`/`false`） | ❌ 热加载（约 10 秒内生效） |
 | `--traceTopicId <id>` | Trace 数据上报使用的 CLS 日志主题 ID | ❌ 热加载（约 10 秒内生效） |
+| `--instanceId <id>` | 显式指定实例 ID，写入配置文件后插件启动时直接使用，跳过腾讯云 metadata 接口请求 | ❌ 热加载（约 10 秒内生效） |
+| `--instanceName <name>` | 显式指定实例名称，仅覆盖 `cvm_instance_name`（不影响 `host_name`） | ❌ 热加载（约 10 秒内生效） |
+| `--localIpv4 <ip>` | 显式指定内网 IPv4 | ❌ 热加载（约 10 秒内生效） |
 
 > **智能重启判断**
 > **智能重启判断**：CLI 会自动分析本次更新的参数，如果所有参数均支持热加载，则不会重启网关；如果包含需要重启的参数，CLI 会自动重启网关使配置生效。
@@ -1177,12 +1241,17 @@ npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
 | `cls.secretId` | 自动更新静态密钥（static 模式），新密钥加密后回写配置文件；同时影响 Trace 模块的凭证 |
 | `cls.secretKey` | 自动更新静态密钥（static 模式），新密钥加密后回写配置文件；同时影响 Trace 模块的凭证 |
 | `cls.token` | 自动更新临时 Token（CVM 角色模式），同时影响 Trace 模块的凭证 |
+| `instance_metadata.instance_id` | 热更新 `cvm_instance_id`，覆盖自动获取值；设为空字符串可清空覆盖值并重新触发 metadata 接口获取 |
+| `instance_metadata.instance_name` | 热更新 `cvm_instance_name`，覆盖自动获取值；不影响 `host_name`（后者始终取 `os.hostname()`）；设为空字符串可清空覆盖值并重新触发 metadata 接口获取 |
+| `instance_metadata.local_ipv4` | 热更新 `cvm_instance_intra_ip`，覆盖自动获取值；设为空字符串可清空覆盖值并重新触发 metadata 接口获取 |
 | `trace.enabled` | 动态启用/禁用 Trace 链路追踪功能。即使初始配置不完整导致 trace 禁用，后续补全配置后也可通过热更新自动恢复 |
 | `trace.traceTopicId` | 自动切换 Trace 数据上报的 CLS 日志主题 |
 | `trace.debug` | 动态开启/关闭 Trace 调试日志，无需重启即可在运行时排查问题 |
 | `trace.enabledHooks` | 动态调整启用的 hook 列表，可在运行时按需启用/禁用特定 hook，无需重启 |
 
 > **注意**：`credentialMode`、`roleName` 等凭证模式相关字段，以及 `prometheusEnabled`、`pushIntervalMs`、`externalLabels` 等 Prometheus 配置字段变更后需要重启网关才能生效。可通过 `UpdateParameter` 命令更新，CLI 会自动判断是否需要重启。
+>
+> `instance_metadata.instance_id`、`instance_metadata.instance_name`、`instance_metadata.local_ipv4` 三个字段支持热更新，修改后约 10 秒内自动生效，无需重启网关。将字段设为空字符串时，插件会清空对应的覆盖值并重新通过 metadata 接口自动获取（最多重试 3 次，每次间隔 30 秒）。
 
 ---
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
 "id": "clawpro-diagnostics-metrics-cls",
   "name": "Diagnostics Metrics CLS",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "CLS诊断指标导出插件：Prometheus 指标（pull/remote-write）+ 全链路 Trace 追踪",
   "type": "plugin",
   "configSchema": {
@@ -90,6 +90,14 @@
           "instance_id": {
             "type": "string",
             "description": "腾讯云 CVM 实例 ID，由插件自动获取并持久化"
+          },
+          "instance_name": {
+            "type": "string",
+            "description": "腾讯云 CVM 实例名称，由插件自动获取并持久化"
+          },
+          "local_ipv4": {
+            "type": "string",
+            "description": "腾讯云 CVM 内网 IPv4 地址，由插件自动获取并持久化"
           }
         }
       },

package/package.json

@@ -1,31 +1 @@
-{
-"name": "clawpro-diagnostics-metrics-cls",
-  "version": "2.0.0",
-  "description": "CLS OpenClaw diagnostics exporter: Prometheus metrics (pull/remote-write) + full-link Trace",
-  "type": "module",
-  "main": "index.ts",
-  "files": [
-    "index.ts",
-    "src/**/*.ts",
-    "openclaw.plugin.json"
-  ],
-  "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "scripts": {
-    "build": "echo 'Plugin publishes .ts source files, no build needed.'",
-    "typecheck": "tsc --noEmit",
-    "dev": "tsc --noEmit --watch"
-  },
-  "license": "MIT",
-  "dependencies": {
-    "prom-client": "^15.1.3",
-    "snappyjs": "^0.7.0",
-    "tencentcloud-cls-sdk-nodejs": "1.0.3"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0"
-  }
-}
+{"name":"clawpro-diagnostics-metrics-cls","version":"2.0.2","description":"CLS OpenClaw diagnostics exporter: Prometheus metrics (pull/remote-write) + full-link Trace","type":"module","main":"index.ts","files":["index.ts","src/**/*.ts","openclaw.plugin.json"],"openclaw":{"extensions":["./index.ts"]},"scripts":{"build":"echo 'Plugin publishes .ts source files, no build needed.'","typecheck":"tsc --noEmit","dev":"tsc --noEmit --watch"},"license":"MIT","dependencies":{"prom-client":"^15.1.3","snappyjs":"^0.7.0","tencentcloud-cls-sdk-nodejs":"1.0.3"},"devDependencies":{"typescript":"^5.0.0"}}

package/src/cls-service.ts

@@ -87,7 +87,7 @@ import { onDiagnosticEvent } from "openclaw/plugin-sdk/diagnostics-otel";
 import { Registry, Counter, Histogram, Gauge, collectDefaultMetrics } from "prom-client";
 import type { PromTimeSeries, PromLabel } from "./protobuf.ts";
 import { RemoteWriteClient, type RemoteWriteConfig } from "./remote-write.ts";
-import { getInstanceMetadata, startInstanceMetadataRefresh, stopInstanceMetadataRefresh } from "./instance-metadata.ts";
+import { getInstanceMetadata, startInstanceMetadataRefresh, stopInstanceMetadataRefresh, updateInstanceMetadata } from "./instance-metadata.ts";
 import type { SharedCredentialManager, CredentialSnapshot } from "./shared-credential.ts";
 import { decrypt, encrypt, isEncrypted } from "./crypto-utils.ts";
 import { PLUGIN_ID } from "./shared-constants.ts";
@@ -212,7 +212,16 @@ const ENV_POLL_INTERVAL_MS = 10_000;
  */
 async function readHotConfigFromDisk(
   configPath: string,
-): Promise<{ metricTopicId: string | undefined; endpoint: string; enableReport: boolean; secretId: string; secretKey: string } | null> {
+): Promise<{
+  metricTopicId: string | undefined;
+  endpoint: string;
+  enableReport: boolean;
+  secretId: string;
+  secretKey: string;
+  instanceId: string;
+  instanceName: string;
+  localIpv4: string;
+} | null> {
   try {
     const raw = await nodeFs.readFile(configPath, "utf8");
     const config = JSON.parse(raw) as Record<string, unknown>;
@@ -225,7 +234,7 @@ async function readHotConfigFromDisk(
     const rawMetricTopicId = typeof clsCfg?.metricTopicId === "string" ? clsCfg.metricTopicId.trim() : "";
     const endpoint = typeof clsCfg?.endpoint === "string" ? clsCfg.endpoint.trim() : "";
     const enableReport = clsCfg?.enableReport === false ? false : true;
-    // 读取并解密 secretId/secretKey，支持 static 模式下密钥热更新
+    // 读取并解密 secretId/secretKey，支持 static 模式下密鑰热更新
     const secretId = typeof clsCfg?.secretId === "string" ? decrypt(clsCfg.secretId.trim()) : "";
     const secretKey = typeof clsCfg?.secretKey === "string" ? decrypt(clsCfg.secretKey.trim()) : "";
 
@@ -235,13 +244,30 @@ async function readHotConfigFromDisk(
       metricTopicId = undefined;
     }
 
-    return { metricTopicId, endpoint, enableReport, secretId, secretKey };
+    // 读取 instance_metadata 三个字段，用于热更新实例元数据缓存
+    // 使用 pickOrNull 区分「字段不存在/非字符串」（返回 null）和「字段被显式设为空字符串」（返回 ""）：
+    // - null：配置文件中无此字段，热更新时不修改缓存
+    // - ""：用户显式清空，热更新时清空缓存并触发重新从 metadata 接口获取
+    // - 非空字符串：用新值覆盖缓存
+    const instanceMetadataCfg = entryCfg?.instance_metadata as Record<string, unknown> | undefined;
+    const pickOrNull = (v: unknown): string | null => {
+      if (typeof v !== "string") return null;
+      return v.trim();
+    };
+    const instanceIdRaw = instanceMetadataCfg ? pickOrNull(instanceMetadataCfg.instance_id) : null;
+    const instanceNameRaw = instanceMetadataCfg ? pickOrNull(instanceMetadataCfg.instance_name) : null;
+    const localIpv4Raw = instanceMetadataCfg ? pickOrNull(instanceMetadataCfg.local_ipv4) : null;
+    // 对外仍使用 string 类型（null 转为空字符串），调用方通过与 active 值比较判断是否变化
+    const instanceId = instanceIdRaw ?? "";
+    const instanceName = instanceNameRaw ?? "";
+    const localIpv4 = localIpv4Raw ?? "";
+
+    return { metricTopicId, endpoint, enableReport, secretId, secretKey, instanceId, instanceName, localIpv4 };
   } catch {
     // 文件不存在、JSON 解析失败等，返回 null 表示无法读取
     return null;
   }
 }
-
 /**
  * 根据 endpoint 和 metricTopicId 生成 Prometheus Remote Write URL。
  * URL 格式与 CLI 工具保持一致：https://<endpoint>/prometheus/<metricTopicId>/api/v1/write
@@ -351,10 +377,13 @@ export function createPrometheusService(
   let activeEndpoint = "";
   /** 当前生效的 enableReport（支持热更新） */
   let activeEnableReport = true;
-  /** 追踪 static 模式下的密钥，用于热更新时检测变化 */
+  /** 追踪 static 模式下的密鑰，用于热更新时检测变化 */
   let activeSecretId = "";
   let activeSecretKey = "";
-
+  /** 追踪 instance_metadata 三个字段，用于热更新时检测变化 */
+  let activeInstanceId = "";
+  let activeInstanceName = "";
+  let activeLocalIpv4 = "";
   return {
     id: "clawpro-diagnostics-metrics-cls",
 
@@ -372,7 +401,7 @@ export function createPrometheusService(
       const prefix = promCfg?.metric_prefix ?? "openclaw";
       const externalLabels = { ...promCfg?.external_labels ?? {} };
 
-      // 启动实例元数据获取，优先从 openclaw.json 读取已持久化的 instance-id
+      // 启动实例元数据获取：优先使用 openclaw.json 持久化值，缺失字段再通过 metadata 接口拉取
       await startInstanceMetadataRefresh(ctx.logger, ctx.stateDir).catch((err: unknown) => {
         const detail = err instanceof Error ? err.message : String(err);
         ctx.logger.warn(
@@ -736,6 +765,10 @@ export function createPrometheusService(
       // 从 CLS 配置初始化密钥（变量声明已提升到 start() 外部，确保 stop() 可访问）
       activeSecretId = clsCfg?.secretId ?? "";
       activeSecretKey = clsCfg?.secretKey ?? "";
+      // 初始化 instance_metadata 追踪值（从当前缓存读取，避免启动时误判为变化）
+      activeInstanceId = getInstanceMetadata().cvmInstanceId;
+      activeInstanceName = getInstanceMetadata().cvmInstanceName;
+      activeLocalIpv4 = getInstanceMetadata().cvmInstanceIntraIp;
 
       const remoteWriteConfigs = promCfg?.remote_write ?? [];
 
@@ -896,16 +929,54 @@ export function createPrometheusService(
           const latestEnableReport = diskConfig.enableReport;
           const latestSecretId = diskConfig.secretId;
           const latestSecretKey = diskConfig.secretKey;
+          const latestInstanceId = diskConfig.instanceId;
+          const latestInstanceName = diskConfig.instanceName;
+          const latestLocalIpv4 = diskConfig.localIpv4;
 
           // 注意：metricTopicId 格式校验已在 readHotConfigFromDisk 中完成，
           // 不合法时返回 undefined，?? 运算符会自动回退到初始配置值 cfgMetricTopicId
 
           const metricChanged = latestMetric !== activeMetricTopicId;
           const endpointChanged = latestEndpoint !== activeEndpoint;
+
+          // 在比较前先将追踪值与当前缓存同步：
+          // 若 activeInstance* 为空但缓存已有值，说明是 metadata 重试成功后缓存被更新，
+          // 而非配置文件发生变化。此时静默同步追踪值，避免误判为热更新触发 updateInstanceMetadata。
+          const currentCache = getInstanceMetadata();
+          if (!activeInstanceId && currentCache.cvmInstanceId) {
+            activeInstanceId = currentCache.cvmInstanceId;
+          }
+          if (!activeInstanceName && currentCache.cvmInstanceName) {
+            activeInstanceName = currentCache.cvmInstanceName;
+          }
+          if (!activeLocalIpv4 && currentCache.cvmInstanceIntraIp) {
+            activeLocalIpv4 = currentCache.cvmInstanceIntraIp;
+          }
+
+          // 检测 instance_metadata 三个字段是否变化（包括清空字段的情况，清空表示恢复自动获取）
+          const instanceOverrideChanged =
+            latestInstanceId !== activeInstanceId
+            || latestInstanceName !== activeInstanceName
+            || latestLocalIpv4 !== activeLocalIpv4;
           const enableReportChanged = latestEnableReport !== activeEnableReport;
-          // static 模式下检测密钥是否变化
+          // static 模式下检测密鑰是否变化
           const secretChanged = credentialMode === "static" && latestSecretId && latestSecretKey
             && (latestSecretId !== activeSecretId || latestSecretKey !== activeSecretKey);
+          // instance_metadata 热更新：检测三个字段变化并更新实例元数据缓存
+          if (instanceOverrideChanged) {
+            activeInstanceId = latestInstanceId;
+            activeInstanceName = latestInstanceName;
+            activeLocalIpv4 = latestLocalIpv4;
+            // 传入 stateDir，使 updateInstanceMetadata 在字段被清空时能触发重新从 metadata 接口获取并持久化
+            updateInstanceMetadata({
+              instanceId: latestInstanceId,
+              instanceName: latestInstanceName,
+              localIpv4: latestLocalIpv4,
+            }, ctx.logger, ctx.stateDir);
+            ctx.logger.debug(
+              `diagnostics-metrics/prometheus: 配置文件热更新，instance_metadata 已更新 (instance_id=${activeInstanceId}, instance_name=${activeInstanceName}, local_ipv4=${activeLocalIpv4})`,
+            );
+          }
 
           // static 模式密钥热更新：检测 secretId/secretKey 变化并通知共享凭证管理器
           if (secretChanged) {
@@ -1091,6 +1162,9 @@ export function createPrometheusService(
       activeEnableReport = true;
       activeSecretId = "";
       activeSecretKey = "";
+      activeInstanceId = "";
+      activeInstanceName = "";
+      activeLocalIpv4 = "";
     },
   } satisfies OpenClawPluginService & { getExports: () => PrometheusPluginExports | null };
 }

package/src/instance-metadata.ts

@@ -1,14 +1,16 @@
 /**
  * 腾讯云实例元数据获取模块
  *
- * 通过腾讯云 metadata 接口获取当前实例的 instance-id。
- * instance-name 直接使用本机 hostname，local-ipv4 通过遍历本地网卡接口获取。
- * - 启动时先从 openclaw.json 的插件配置项中读取已持久化的 instance-id，若已有则直接使用，不再发起网络请求
- * - 若插件配置项中无 instance-id，则通过 metadata 接口获取，成功后写入 openclaw.json 的插件配置项
- * - 首次获取失败的字段会在 30 秒后重试，最多重试 3 次
- * - instance-id 成功持久化后不再启动定时刷新
+ * 通过腾讯云 metadata 接口获取当前实例的 instance-id / instance-name / local-ipv4 三个字段。
+ * hostName 字段独立使用 os.hostname()（OTel 资源语义，与 CVM 实例名不同维度）。
+ *
+ * 三个字段共享统一的获取与持久化流程：
+ * - 启动时先从 openclaw.json 的插件配置项中读取已持久化值，已有的字段直接使用，不再发起网络请求
+ * - 配置项中缺失的字段通过 metadata 接口获取，成功后写入 openclaw.json 的插件配置项
+ * - 首次获取失败的字段会在 30 秒后重试，最多重试 3 次；仅当 * - 全部字段已成功获取或持久化后不再启动定时刷新
  * - 请求超时 2 秒，失败时使用空字符串作为默认值
- * - 持久化位置：openclaw.json 的 plugins.entries["clawpro-diagnostics-metrics-cls"].config.instance_metadata.instance_id
+ * - 持久化位置：openclaw.json 的 plugins.entries["clawpro-diagnostics-metrics-cls"].config.instance_metadata
+ *   字段名：instance_id / instance_name / local_ipv4
  * - 写入 openclaw.json 时使用锁文件（openclaw.json.lock）防止并发写入冲突，锁文件记录 PID 防止僵尸锁
  * - 写入时先写临时文件（openclaw.json.tmp）再 rename 实现原子替换，跨设备时自动降级为直接写入
  */
@@ -161,40 +163,15 @@ function readResponseBody(
 }
 
 /**
- * 获取本机非回环、非虚拟网卡的 IPv4 地址
- * 遍历所有网卡接口，跳过回环地址和常见虚拟网卡（docker、veth、br-、virbr 等）
- * @returns 第一个匹配的 IPv4 地址，未找到时返回空字符串
- */
-function getLocalIPv4(): string {
-  const interfaces = os.networkInterfaces();
-  // 常见虚拟网卡前缀
-  const virtualPrefixes = ["docker", "veth", "br-", "virbr", "vnet", "flannel", "cni", "cali"];
-
-  for (const [name, addrs] of Object.entries(interfaces)) {
-    if (!addrs) continue;
-    // 跳过虚拟网卡
-    const isVirtual = virtualPrefixes.some((prefix) => name.toLowerCase().startsWith(prefix));
-    if (isVirtual) continue;
-
-    for (const addr of addrs) {
-      // 仅取 IPv4、非回环、非内部地址优先但也接受内部地址
-      if (addr.family === "IPv4" && !addr.internal) {
-        return addr.address;
-      }
-    }
-  }
-  return "";
-}
-
-/**
- * 从 openclaw.json 的插件配置项中读取已持久化的 instance-id
- * 读取路径：plugins.entries[PLUGIN_ID].config.instance_metadata.instance_id
+ * 从 openclaw.json 的插件配置项中读取已持久化的实例元数据三元组
+ * 读取路径：plugins.entries[PLUGIN_ID].config.instance_metadata.{instance_id, instance_name, local_ipv4}
  * @param stateDir openclaw.json 所在目录
- * @returns 已持久化的 instance-id，不存在或读取失败时返回空字符串
+ * @returns 包含三个字段的对象，缺失字段返回空字符串
  */
-async function readInstanceIdFromConfig(
+async function readPersistedMetadata(
   stateDir: string,
-): Promise<string> {
+): Promise<{ instanceId: string; instanceName: string; localIpv4: string }> {
+  const empty = { instanceId: "", instanceName: "", localIpv4: "" };
   try {
     const configPath = nodePath.join(stateDir, "openclaw.json");
     const raw = await nodeFs.readFile(configPath, "utf8");
@@ -204,10 +181,15 @@ async function readInstanceIdFromConfig(
     const pluginEntry = entries?.[PLUGIN_ID] as Record<string, unknown> | undefined;
     const pluginConfig = pluginEntry?.config as Record<string, unknown> | undefined;
     const instanceMetadata = pluginConfig?.instance_metadata as Record<string, unknown> | undefined;
-    const instanceId = instanceMetadata?.instance_id;
-    return typeof instanceId === "string" && instanceId.trim() ? instanceId.trim() : "";
+    if (!instanceMetadata) return empty;
+    const pick = (v: unknown): string => (typeof v === "string" && v.trim() ? v.trim() : "");
+    return {
+      instanceId: pick(instanceMetadata.instance_id),
+      instanceName: pick(instanceMetadata.instance_name),
+      localIpv4: pick(instanceMetadata.local_ipv4),
+    };
   } catch {
-    return "";
+    return empty;
   }
 }
 
@@ -312,19 +294,29 @@ async function releaseFileLock(lockPath: string): Promise<void> {
 }
 
 /**
- * 将 instance-id 持久化写入 openclaw.json 的插件配置项
- * 写入路径：plugins.entries[PLUGIN_ID].config.instance_metadata.instance_id
+ * 将实例元数据增量持久化写入 openclaw.json 的插件配置项
+ * 写入路径：plugins.entries[PLUGIN_ID].config.instance_metadata.{instance_id, instance_name, local_ipv4}
  * - 使用锁文件（openclaw.json.lock）防止并发写入
  * - 先写临时文件再 rename 实现原子替换，避免写入中途崩溃产生损坏文件
+ * - 仅写入 updates 中非空的字段；空字符串字段保留文件中原值（增量合并）
  * @param stateDir openclaw.json 所在目录
- * @param instanceId 要写入的 instance-id
+ * @param updates 待写入的字段，空字符串字段将被忽略
  * @param logger 可选的日志记录器
  */
-async function writeInstanceIdToConfig(
+async function writePersistedMetadata(
   stateDir: string,
-  instanceId: string,
+  updates: { instanceId?: string; instanceName?: string; localIpv4?: string },
   logger?: { info: (msg: string) => void; warn: (msg: string) => void; debug: (msg: string) => void },
 ): Promise<void> {
+  // 过滤掉空字符串字段，避免用空值覆盖文件中已有的旧值
+  const effective: Record<string, string> = {};
+  if (updates.instanceId) effective.instance_id = updates.instanceId;
+  if (updates.instanceName) effective.instance_name = updates.instanceName;
+  if (updates.localIpv4) effective.local_ipv4 = updates.localIpv4;
+  if (Object.keys(effective).length === 0) {
+    return;
+  }
+
   const configPath = nodePath.join(stateDir, "openclaw.json");
   const lockPath = configPath + ".lock";
   const tmpPath = configPath + ".tmp";
@@ -367,7 +359,8 @@ async function writeInstanceIdToConfig(
     const pluginConfig = pluginEntry.config as Record<string, unknown>;
 
     const prev = pluginConfig.instance_metadata as Record<string, unknown> | undefined;
-    pluginConfig.instance_metadata = { ...(prev ?? {}), instance_id: instanceId };
+    // 增量合并：保留文件中已有的其他字段（如用户 override_* 配置），仅覆盖本次 effective 中的字段
+    pluginConfig.instance_metadata = { ...(prev ?? {}), ...effective };
 
     const content = JSON.stringify(config, null, 2) + "\n";
     // 先写入临时文件，再 rename 实现原子替换，避免写入中途崩溃损坏原文件
@@ -388,13 +381,13 @@ async function writeInstanceIdToConfig(
     }
 
     logger?.debug(
-      `diagnostics-metrics/instance-metadata: instance-id 已持久化写入 openclaw.json`,
+      `diagnostics-metrics/instance-metadata: 实例元数据已持久化写入 openclaw.json (${Object.keys(effective).join(", ")})`,
     );
   } catch (err) {
     // 清理可能残留的临时文件
     try { await nodeFs.unlink(tmpPath); } catch { /* ignore */ }
     logger?.warn(
-      `diagnostics-metrics/instance-metadata: 写入 instance-id 到 openclaw.json 失败: ${String(err)}`,
+      `diagnostics-metrics/instance-metadata: 写入实例元数据到 openclaw.json 失败: ${String(err)}`,
     );
   } finally {
     // 无论成功与否，都释放文件锁
@@ -404,63 +397,97 @@ async function writeInstanceIdToConfig(
 
 /**
  * 刷新实例元数据
- * 通过 metadata 接口获取 instance-id，instance-name 使用本机 hostname，
- * local-ipv4 通过遍历本地网卡接口获取。
- * @returns 包含 idSuccess（是否成功）和 fetchedInstanceId（获取到的 instance-id）的对象
+ * 通过 metadata 接口并行获取 instance-id、instance-name、local-ipv4 三个字段。
+ * hostName 字段独立使用 os.hostname()（不依赖网络）。
+ *
+ * 缓存中已有值的字段会跳过网络请求，避免重试阶段重复拉取已经就绪的字段。
+ *
+ * @returns
+ *   - allSuccess：三个 CVM 字段（id/name/ipv4）是否全部就绪
+ *   - fetched：本次通过 metadata 接口新获取到的字段，仅这些字段需要被持久化
  */
 async function refreshMetadata(
   logger?: { info: (msg: string) => void; warn: (msg: string) => void; debug: (msg: string) => void },
-): Promise<{ idSuccess: boolean; fetchedInstanceId: string }> {
-  // 仅从 metadata 接口请求 instance-id
-  const idResult = await fetchMetadataField("instance-id").then(
-    (value) => ({ status: "fulfilled" as const, value }),
-    (reason) => ({ status: "rejected" as const, reason }),
-  );
+): Promise<{
+  allSuccess: boolean;
+  fetched: { instanceId?: string; instanceName?: string; localIpv4?: string };
+}> {
+  const prev = cachedMetadata;
+
+  // 仅为缓存中尚未就绪的字段发起 metadata 请求，避免重试阶段重复拉取已就绪字段
+  const needIdFetch = !prev.cvmInstanceId;
+  const needNameFetch = !prev.cvmInstanceName;
+  const needIpFetch = !prev.cvmInstanceIntraIp;
+
+  const [idResult, nameResult, ipResult] = await Promise.all([
+    needIdFetch ? settle(fetchMetadataField("instance-id")) : Promise.resolve({ status: "skipped" as const }),
+    needNameFetch ? settle(fetchMetadataField("instance-name")) : Promise.resolve({ status: "skipped" as const }),
+    needIpFetch ? settle(fetchMetadataField("local-ipv4")) : Promise.resolve({ status: "skipped" as const }),
+  ]);
 
   // 获取本机 hostname（同步调用，不依赖网络）
-  let hostName = "";
+  // hostName 字段始终保留 os.hostname()，不受 metadata 响应影响
+  let hostName = prev.hostName;
   try {
     hostName = os.hostname();
   } catch {
     logger?.warn(`diagnostics-metrics/instance-metadata: 获取 hostname 失败`);
   }
 
-  // 获取本机 IPv4 地址（同步调用，不依赖网络）
-  let localIpv4 = "";
-  try {
-    localIpv4 = getLocalIPv4();
-  } catch {
-    logger?.warn(`diagnostics-metrics/instance-metadata: 获取本地 IPv4 地址失败`);
-  }
+  const fetched: { instanceId?: string; instanceName?: string; localIpv4?: string } = {};
+  const merged: InstanceMetadata = { ...prev, hostName: hostName || prev.hostName };
 
-  // 基于当前缓存构建新值，失败的字段保留上次缓存值
-  const prev = cachedMetadata;
-  const updated: InstanceMetadata = {
-    cvmInstanceId: prev.cvmInstanceId,
-    cvmInstanceName: hostName || prev.cvmInstanceName,
-    cvmInstanceIntraIp: localIpv4 || prev.cvmInstanceIntraIp,
-    hostName: hostName || prev.hostName,
-  };
-
-  let idSuccess = false;
-  let fetchedInstanceId = "";
+  // ── instance-id ────────────────────────────────────────────────────
   if (idResult.status === "fulfilled" && idResult.value) {
-    updated.cvmInstanceId = idResult.value;
-    fetchedInstanceId = idResult.value;
-    idSuccess = true;
-  } else {
-    const reason = idResult.status === "rejected" ? String(idResult.reason) : "empty response";
-    logger?.warn(`diagnostics-metrics/instance-metadata: 获取 instance-id 失败: ${reason}`);
+    merged.cvmInstanceId = idResult.value;
+    fetched.instanceId = idResult.value;
+  } else if (idResult.status === "rejected") {
+    logger?.warn(`diagnostics-metrics/instance-metadata: 获取 instance-id 失败: ${String(idResult.reason)}`);
+  } else if (idResult.status === "fulfilled") {
+    logger?.warn(`diagnostics-metrics/instance-metadata: 获取 instance-id 失败: empty response`);
+  }
+
+  // ── instance-name ──────────────────────────────────────────────────
+  if (nameResult.status === "fulfilled" && nameResult.value) {
+    merged.cvmInstanceName = nameResult.value;
+    fetched.instanceName = nameResult.value;
+  } else if (nameResult.status === "rejected") {
+    logger?.warn(`diagnostics-metrics/instance-metadata: 获取 instance-name 失败: ${String(nameResult.reason)}`);
+  } else if (nameResult.status === "fulfilled") {
+    logger?.warn(`diagnostics-metrics/instance-metadata: 获取 instance-name 失败: empty response`);
+  }
+
+  // ── local-ipv4 ─────────────────────────────────────────────────────
+  if (ipResult.status === "fulfilled" && ipResult.value) {
+    merged.cvmInstanceIntraIp = ipResult.value;
+    fetched.localIpv4 = ipResult.value;
+  } else if (ipResult.status === "rejected") {
+    logger?.warn(`diagnostics-metrics/instance-metadata: 获取 local-ipv4 失败: ${String(ipResult.reason)}`);
+  } else if (ipResult.status === "fulfilled") {
+    logger?.warn(`diagnostics-metrics/instance-metadata: 获取 local-ipv4 失败: empty response`);
   }
 
   // 原子替换缓存引用（不可变对象，避免并发读写问题）
-  cachedMetadata = Object.freeze(updated);
+  cachedMetadata = Object.freeze(merged);
+
+  const allSuccess = Boolean(merged.cvmInstanceId) && Boolean(merged.cvmInstanceName)
+    && Boolean(merged.cvmInstanceIntraIp);
 
   logger?.debug(
     `diagnostics-metrics/instance-metadata: 当前实例信息 cvm_instance_id=${cachedMetadata.cvmInstanceId}, cvm_instance_name=${cachedMetadata.cvmInstanceName}, cvm_instance_intra_ip=${cachedMetadata.cvmInstanceIntraIp}, host_name=${cachedMetadata.hostName}`,
   );
 
-  return { idSuccess, fetchedInstanceId };
+  return { allSuccess, fetched };
+}
+
+/** 将 Promise 包装为 settled 风格结果（status + value/reason），便于统一处理 */
+function settle<T>(
+  p: Promise<T>,
+): Promise<{ status: "fulfilled"; value: T } | { status: "rejected"; reason: unknown }> {
+  return p.then(
+    (value) => ({ status: "fulfilled" as const, value }),
+    (reason) => ({ status: "rejected" as const, reason }),
+  );
 }
 
 /**
@@ -471,14 +498,89 @@ export function getInstanceMetadata(): Readonly<InstanceMetadata> {
   return cachedMetadata;
 }
 
+/**
+ * 热更新实例元数据中的三个 CVM 字段（instance_id / instance_name / local_ipv4）
+ * 仅在已初始化后生效；未初始化时打印 warn 日志并返回，避免覆盖启动流程的初始化逻辑。
+ * 三个字段均未变化时跳过，避免无意义的缓存替换。
+ * - 传入非空字符串：用新值覆盖缓存中对应字段
+ * - 传入空字符串：清空对应字段，并触发重新从 metadata 接口获取（恢复自动获取逻辑）
+ * - 传入 undefined：保留缓存中当前值不变
+ * hostName 字段始终保持 os.hostname()，不受此函数影响。
+ *
+ * @param updates 待更新的字段，undefined 表示保留当前值，空字符串表示清空并恢复自动获取
+ * @param logger 可选的日志记录器，用于输出未初始化时的警告
+ * @param stateDir openclaw.json 所在目录，清空字段时用于触发重新获取并持久化
+ */
+export function updateInstanceMetadata(
+  updates: { instanceId?: string; instanceName?: string; localIpv4?: string },
+  logger?: { info: (msg: string) => void; warn: (msg: string) => void; debug: (msg: string) => void },
+  stateDir?: string,
+): void {
+  // 未初始化时不做任何操作，避免干扰启动流程；打印 warn 便于排查热更新静默失效问题
+  if (!initialized) {
+    logger?.warn(
+      `diagnostics-metrics/instance-metadata: updateInstanceMetadata 调用时模块尚未初始化，本次热更新已跳过`,
+    );
+    return;
+  }
+
+  const prev = cachedMetadata;
+  // 使用 ?? 而非 ||：undefined 表示"不修改，保留旧值"；空字符串表示"清空，恢复自动获取"
+  const newInstanceId = updates.instanceId !== undefined ? updates.instanceId : prev.cvmInstanceId;
+  const newInstanceName = updates.instanceName !== undefined ? updates.instanceName : prev.cvmInstanceName;
+  const newLocalIpv4 = updates.localIpv4 !== undefined ? updates.localIpv4 : prev.cvmInstanceIntraIp;
+
+  // 三个字段均未变化，跳过无意义的缓存替换
+  if (
+    newInstanceId === prev.cvmInstanceId
+    && newInstanceName === prev.cvmInstanceName
+    && newLocalIpv4 === prev.cvmInstanceIntraIp
+  ) {
+    return;
+  }
+
+  cachedMetadata = Object.freeze({
+    cvmInstanceId: newInstanceId,
+    cvmInstanceName: newInstanceName,
+    cvmInstanceIntraIp: newLocalIpv4,
+    hostName: prev.hostName,
+  });
+
+  // 若有字段被清空（恢复自动获取），重置重试计数并重新触发 metadata 接口获取
+  const needRefetch = !newInstanceId || !newInstanceName || !newLocalIpv4;
+  if (needRefetch) {
+    logger?.debug(
+      `diagnostics-metrics/instance-metadata: 热更新清空了部分字段，重新触发 metadata 接口获取`,
+    );
+    // 重置重试计数，使 scheduleRetry 可以重新发起最多 MAX_RETRY_COUNT 次重试
+    retryCount = 0;
+    if (retryTimer) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+    // 异步触发重新获取，不阻塞当前调用
+    void refreshMetadata(logger).then(({ allSuccess, fetched }) => {
+      if (stopped) return;
+      if (stateDir && (fetched.instanceId || fetched.instanceName || fetched.localIpv4)) {
+        void writePersistedMetadata(stateDir, fetched, logger);
+      }
+      if (!allSuccess) {
+        scheduleRetry(logger, stateDir);
+      }
+    });
+  }
+}
+
 /**
  * 启动实例元数据获取
- * - 优先从 openclaw.json 中读取已持久化的 instance-id，若已有则直接使用，不发起网络请求
- * - 若无持久化值，则通过 metadata 接口获取，成功后写入 openclaw.json，不再启动定时刷新
- * - 首次获取失败的字段会在 30 秒后重试，最多重试 3 次
+ * - 优先应用用户显式传入的 override（不持久化，不触发网络请求）
+ * - 其次从 openclaw.json 中读取已持久化的值，直接注入缓存
+ * - 最后仅对尚未就绪的字段调用 metadata 接口拉取
+ * - 获取成功的字段立即持久化写入 openclaw.json（override 值不持久化）
+ * - 若仍有字段未就绪，启动 30 秒间隔的重试，最多 MAX_RETRY_COUNT 次
  *
  * @param logger 可选的日志记录器
- * @param stateDir openclaw.json 所在目录，用于持久化 instance-id
+ * @param stateDir openclaw.json 所在目录，用于持久化三元组
  */
 export async function startInstanceMetadataRefresh(
   logger?: { info: (msg: string) => void; warn: (msg: string) => void; debug: (msg: string) => void },
@@ -502,50 +604,51 @@ export async function startInstanceMetadataRefresh(
   initialized = true;
 
   try {
-    // 优先从 openclaw.json 中读取已持久化的 instance-id
-    if (stateDir) {
-      const persistedId = await readInstanceIdFromConfig(stateDir);
-      if (persistedId) {
-        logger?.debug(
-          `diagnostics-metrics/instance-metadata: 从 openclaw.json 读取到已持久化的 instance-id: ${persistedId}`,
-        );
-        // 同步获取 hostname 和本地 IP
-        let hostName = "";
-        try { hostName = os.hostname(); } catch { /* ignore */ }
-        let localIpv4 = "";
-        try { localIpv4 = getLocalIPv4(); } catch { /* ignore */ }
-        cachedMetadata = Object.freeze({
-          cvmInstanceId: persistedId,
-          cvmInstanceName: hostName,
-          cvmInstanceIntraIp: localIpv4,
-          hostName,
-        });
-        logger?.debug(
-          `diagnostics-metrics/instance-metadata: 当前实例信息 cvm_instance_id=${cachedMetadata.cvmInstanceId}, cvm_instance_name=${cachedMetadata.cvmInstanceName}, cvm_instance_intra_ip=${cachedMetadata.cvmInstanceIntraIp}, host_name=${cachedMetadata.hostName}`,
-        );
-        // instance-id 已从持久化文件读取，无需网络请求和定时刷新
-        return;
-      }
+    // 同步预取 hostName，该字段独立于 CVM metadata 流程
+    let hostName = "";
+    try { hostName = os.hostname(); } catch { /* ignore */ }
+
+    // 读取持久化值；配置文件中已有的字段直接使用，不再发起网络请求
+    const persisted = stateDir ? await readPersistedMetadata(stateDir) : {
+      instanceId: "",
+      instanceName: "",
+      localIpv4: "",
+    };
+
+    // 基于持久化值构建初始缓存；尚未就绪的字段留空，后续由 metadata 接口填充
+    const initial: InstanceMetadata = {
+      cvmInstanceId: persisted.instanceId,
+      cvmInstanceName: persisted.instanceName,
+      cvmInstanceIntraIp: persisted.localIpv4,
+      hostName,
+    };
+    cachedMetadata = Object.freeze(initial);
+
+    // 全部字段已由 override 或持久化值填充，无需网络请求
+    if (initial.cvmInstanceId && initial.cvmInstanceName && initial.cvmInstanceIntraIp) {
+      logger?.debug(
+        `diagnostics-metrics/instance-metadata: 当前实例信息 cvm_instance_id=${initial.cvmInstanceId}, cvm_instance_name=${initial.cvmInstanceName}, cvm_instance_intra_ip=${initial.cvmInstanceIntraIp}, host_name=${initial.hostName}`,
+      );
+      return;
     }
 
-    // 启动时立即获取一次，等待完成以确保 start() 返回时元数据已就绪
-    // 在腾讯云环境下通常 < 100ms 完成，非腾讯云环境下最多等待 REQUEST_TIMEOUT_MS（2秒）
-    const { idSuccess, fetchedInstanceId } = await refreshMetadata(logger);
+    // 仍有字段未就绪，通过 metadata 接口拉取
+    // refreshMetadata 内部已按缓存和 override 做了跳过处理，仅对未就绪字段发起请求
+    const { allSuccess, fetched } = await refreshMetadata(logger);
 
-    // 首次获取全部失败（很可能不在腾讯云环境），启动短间隔重试
-    if (!idSuccess) {
+    // 新获取到的字段立即持久化（override 值不会出现在 fetched 中，因此不会被写入）
+    if (stateDir && (fetched.instanceId || fetched.instanceName || fetched.localIpv4)) {
+      await writePersistedMetadata(stateDir, fetched, logger);
+    }
+
+    if (!allSuccess) {
       logger?.warn(
-        "diagnostics-metrics/instance-metadata: 首次获取全部失败，可能不在腾讯云环境，将在 30 秒后重试",
+        "diagnostics-metrics/instance-metadata: 首次获取存在未就绪字段，可能不在腾讯云环境，将在 30 秒后重试",
       );
       scheduleRetry(logger, stateDir);
       return;
     }
-
-    // instance-id 获取成功，持久化写入 openclaw.json
-    if (stateDir && fetchedInstanceId) {
-      await writeInstanceIdToConfig(stateDir, fetchedInstanceId, logger);
-    }
-    // instance-id 已成功获取并持久化，不再启动定时刷新
+    // 全部就绪，不再启动定时刷新
   } catch (err) {
     // 启动过程中发生未预期的异常，重置初始化标记，使调用方可以在修复问题后重新调用 start()
     // 注意：仅在 refCount > 0 时才递减，防止并发 stop() 已将 refCount 减为 0 后再次变为负数
@@ -560,7 +663,8 @@ export async function startInstanceMetadataRefresh(
 /**
  * 安排短间隔重试
  * 首次失败后每 30 秒重试一次，最多重试 MAX_RETRY_COUNT 次
- * 重试成功后将 instance-id 持久化写入 openclaw.json，不再启动定时刷新
+ * 每次重试仅对未就绪字段发起 metadata 请求；新获取的字段立即持久化写入 openclaw.json
+ * 所有 CVM 字段（id/name/ipv4）全部就绪后停止重试
  */
 function scheduleRetry(
   logger?: { info: (msg: string) => void; warn: (msg: string) => void; debug: (msg: string) => void },
@@ -583,22 +687,22 @@ function scheduleRetry(
       `diagnostics-metrics/instance-metadata: 第 ${retryCount}/${MAX_RETRY_COUNT} 次重试获取元数据`,
     );
 
-    const { idSuccess, fetchedInstanceId } = await refreshMetadata(logger);
+    const { allSuccess, fetched } = await refreshMetadata(logger);
 
     // 再次检查：refreshMetadata 是异步的，期间 stop() 可能已被调用
     if (stopped) return;
 
-    if (!idSuccess) {
-      // 获取失败，继续重试
-      scheduleRetry(logger, stateDir);
-      return;
+    // 本次新获取到的字段立即持久化（override 值不会出现在 fetched 中）
+    if (stateDir && (fetched.instanceId || fetched.instanceName || fetched.localIpv4)) {
+      await writePersistedMetadata(stateDir, fetched, logger);
     }
 
-    // instance-id 获取成功，持久化写入 openclaw.json
-    if (stateDir && fetchedInstanceId) {
-      await writeInstanceIdToConfig(stateDir, fetchedInstanceId, logger);
+    if (!allSuccess) {
+      // 仍有未就绪字段，继续重试
+      scheduleRetry(logger, stateDir);
+      return;
     }
-    // 成功后不再启动定时刷新
+    // 全部就绪后不再启动定时刷新
   }, RETRY_INTERVAL_MS);
 
   // 避免定时器阻止进程退出（Node.js 环境下 setTimeout 返回的 Timeout 对象具有 unref 方法）

package/src/trace-service.ts

@@ -134,7 +134,6 @@ export function createTraceService(config: TraceConfig) {
     if (metadata.cvmInstanceId) attrs.cvm_instance_id = metadata.cvmInstanceId;
     if (metadata.cvmInstanceName) attrs.cvm_instance_name = metadata.cvmInstanceName;
     if (metadata.cvmInstanceIntraIp) attrs.cvm_instance_intra_ip = metadata.cvmInstanceIntraIp;
-    if (metadata.hostName) attrs.host_name = metadata.hostName;
     return attrs;
   }