# OpenClaw Agent 本文介绍如何将OpenClaw Agent接入华为云AgentArts观测服务，实现调用链追踪和业务指标监控。 **快速入门：** 前提：本地已安装OpenClaw（版本\>= 2026.7.1）。 1. 在AgentArts平台创建OpenClaw智能体，获取接入参数。 2. 在OpenClaw所在机器执行安装命令。 3. 触发OpenClaw会话，在AgentArts观测页面查看数据。 详细步骤见下方[接入步骤]。 #### 前提条件 - Node.js 版本 \>= 20 - OpenClaw 版本 \>= 2026.7.1 ![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/note_3.0-zh-cn.png) - 在AgentArts观测界面查看数据不收费。 - 但数据上报会产生费用： - 调用链上报到APM（应用性能管理服务），费用明细请参考[APM计费说明](https://support.huaweicloud.com/price-apm2/apm_07_0019.html)。 - 指标上报到AOM（应用运维管理服务），费用明细请参考[AOM计费说明](https://support.huaweicloud.com/price-aom2/aom_07_0004.html)。 - AOM和APM都是按需计费，并有一定量的免费额度，超出后按实际使用量收费。 #### 工作原理 OpenClaw是一款开源的AI Agent，提供工具调用、模型调用、多轮对话等能力。 OpenClaw可观测扩展插件（huawei-otel）是华为云AgentArts基于OpenTelemetry标准为OpenClaw开发的可观测采集插件。插件以Node.js扩展的形式安装到OpenClaw的扩展目录中，通过OpenClaw的运行时事件Hook机制采集数据，无需修改业务代码。 数据流转过程： ``` OpenClaw Agent运行时 ├── gateway加载huawei-otel插件 │ └── 注册事件Hook │ ├── before_agent_run / agent_end Agent回合 │ ├── model_call_started / model_call_ended 模型调用 │ ├── llm_input / llm_output 输入输出 │ ├── before_tool_call / after_tool_call 工具调用 │ └── before_message_write 消息写入 │ ├── Trace数据 ──OTLP gRPC──→ APM（调用链） └── Metrics数据 ──OTLP gRPC──→ AOM（指标） │ ▼ AgentArts观测平台展示 ``` 接入后，以下能力将被自动监控： - Agent执行链路（invoke_agent）：Agent回合的完整生命周期。 - 推理步骤（react step）：每轮"模型推理 + 工具调用"的详细过程。 - LLM调用（chat）：模型名称、Token用量、输入/输出内容、首Token时延。 - 工具调用（execute_tool）：工具名称、输入参数、返回结果、执行耗时。 - 技能调用（Skill）：技能名称、调用次数、耗时、错误数等指标。 #### 接入步骤 #### 步骤一：获取接入参数 1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。 2. 在左侧导航栏选择"观测与优化 \> 观测"。 3. 在"智能体列表"页面，单击"接入智能体"，按照页面指引填写名称、智能体类型，创建一个"OpenClaw"智能体，并获取各配置参数。 图1获取配置参数 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002806227557.png "点击放大") #### 步骤二：安装探针 下载OpenClaw探针。 表1探针下载地址 | 平台 | 产物包 | |:---|:---| | Linux / macOS | [huawei-openclaw-otel-plugin-1.0.0.tgz](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/huawei-openclaw-otel-plugin-1.0.0.tgz) | | Windows | [huawei-openclaw-otel-plugin-1.0.0.zip](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/huawei-openclaw-otel-plugin-1.0.0.zip) | 打开终端，执行以下命令，进行探针包的解压，及安装操作。 **Linux / macOS** 1. 将下载的探针包解压到一个独立目录。 ``` # 1. 解压到一个独立目录（包内无顶层目录，解压后即为插件包和脚本） mkdir -p openclaw-otel tar -xzf huawei-openclaw-otel-plugin-1.0.0.tgz -C openclaw-otel cd openclaw-otel ``` 2. 执行以下命令安装探针，命令中的参数按实际替换。参数获取方法参考[步骤一：获取接入参数]，参数说明参考[表2]。 ``` # 2. 安装（安装脚本自动发现同目录下的插件包及其 .sha256） ./install.sh \ --agent-id \ --domain-id \ --project-id \ --apm-endpoint \ --apm-token \ --aom-endpoint \ --aom-access-code \ --aom-prometheus-id \ --agent-name ``` 3. 重启gateway，安装完成后请手动重启使其生效。 ``` openclaw gateway restart ``` **Windows（PowerShell）** 1. 将下载的探针包解压到一个独立目录。 ``` # 1. 解压到一个独立目录 Expand-Archive .\huawei-openclaw-otel-plugin-1.0.0.zip -DestinationPath .\openclaw-otel Set-Location .\openclaw-otel ``` 2. 临时放开脚本执行权限。 仅对当前窗口生效，不影响系统全局策略，关闭窗口后自动失效。 ``` # 2. 允许当前窗口执行脚本 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass ``` 3. 执行以下命令安装探针，命令中的参数按实际替换。参数获取方法参考[步骤一：获取接入参数]，参数说明参考[表2]。 ``` # 3. 安装（自动发现同目录下的 .zip 插件包） .\install.ps1 ` --agent-id ` --domain-id ` --project-id ` --apm-endpoint ` --apm-token ` --aom-endpoint ` --aom-access-code ` --aom-prometheus-id ` --agent-name ``` 安装脚本只写入%USERPROFILE%\\.openclaw\\目录，无需管理员权限。 4. 重启gateway，安装完成后请手动重启使其生效。 ``` openclaw gateway restart ``` **参数说明** - 必填：--agent-id、--apm-endpoint、--apm-token - 启用AOM指标时还需：--project-id、--aom-endpoint、--aom-access-code、--aom-prometheus-id 表2参数说明 | 参数 | 是否必填 | 说明 | |:---|:---|:---| | --agent-name | 否 | 智能体名称。 | | --agent-id | 是 | 智能体ID。 | | --domain-id | 否 | 账号domain ID。 | | --project-id | 否 | 华为云项目ID。 | | --apm-endpoint | 是 | APM数据上报地址。 | | --apm-token | 是 | APM接入凭证Token。 | | --aom-endpoint | 否 | AOM数据上报地址。 | | --aom-access-code | 否 | AOM接入凭证Access Code。 | | --aom-prometheus-id | 否 | AOM Prometheus实例ID。 | | --apm-enable | 否 | 是否启用调用链上报，取值true、false，默认true。 | | --aom-enable | 否 | 是否启用指标上报，取值true、false，默认true。 | | --resource-type | 否 | 智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。 | | --content-capture | 否 | 是否采集LLM输入/输出文本内容，取值true、false，默认true。 | #### 步骤三：验证数据上报 安装完成后，可通过以下步骤验证插件是否正常工作。 1. 安装完成后，查看 OpenClaw gateway 日志确认插件已加载。 日志文件位置： ``` # Linux / macOS /tmp/openclaw/openclaw-YYYY-MM-DD.log # Windows %TEMP%\openclaw\openclaw-YYYY-MM-DD.log ``` 如果看到以下日志，说明插件已经成功加载并开始工作： ``` [huawei-otel] APM OTLP traces — exporting to [huawei-otel] AOM OTLP metrics — exporting to [huawei-otel] APM=on, AOM=on, content_capture=on [huawei-otel] registered 9 hooks: before_agent_run, agent_end, model_call_started, model_call_ended, llm_input, llm_output, before_tool_call, after_tool_call, before_message_write ``` 也可以用命令直接查看： ``` openclaw logs --follow ``` 2. 触发OpenClaw会话，进入AgentArts平台观测功能中查看数据上报。 #### 查看监控数据 数据上报成功后，可在AgentArts智能体平台的观测功能中查看监控数据。 1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。 2. 在左侧导航栏选择"观测与优化 \> 观测"。 3. 在"智能体列表"页面，找到已接入的智能体，单击智能体名称进入详情页面。 **查看业务指标** 在"指标分析"页签中，可以查看关键业务指标： - Tokens消耗：Input Tokens和Output Tokens的消耗总量 - 模型调用次数：应用调用大模型的累计次数 - 模型调用平均耗时：模型调用的平均响应时间 - 模型调用成功率：大模型调用成功的比例 - 会话数：应用产生的会话总数 - 响应成功率：服务响应的成功率 **查看调用链信息** 在"调用链分析"页签中，可以查看完整的Trace调用链路： - 查看各Span类型的层级关系及各节点耗时 - 单击具体Span查看详细信息 **查看会话分析** 在"会话分析"页签中，可以查看智能体与用户对话的历史数据： - 追踪对话上下文 - 分析模型响应耗时 - 统计Token消耗 - 快速定位对话异常问题 #### 常见问题 **插件未加载（日志中无huawei-otel）** 依次检查以下项目： 1. 检查\~/.openclaw/openclaw.json文件中plugins.allow配置项是否包含huawei-otel。 2. 检查openclaw.json中plugins.load.paths是否包含扩展目录路径。 3. 检查\~/.openclaw/extensions/huawei-otel/dist/index.js文件是否存在。 4. 检查\~/.openclaw/extensions/huawei-otel/node_modules/目录下的依赖是否安装完整。 如以上检查均正常但仍无插件日志，建议重新执行安装脚本。 **安装脚本提示校验和不匹配** 日志出现Checksum mismatch： 1. 插件包在下载或传输过程中可能已损坏，请重新解压产物包。 2. 确认插件包与同名.sha256来自同一次发布（都在产物包内，正常情况不会错配）。 3. 如果.sha256缺失，安装只会告警并继续；此时无法确认包完整性，建议重新下载产物包。 **Windows提示无法加载文件，因为在此系统上禁止运行脚本** 执行install.ps1时报UnauthorizedAccess： ``` Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass ``` 在当前窗口重新执行即可，无需修改系统级策略。 **调用链无数据** 1. 确认apm_enable=true，且apm_exporter_endpoint和apm_token已正确配置。 2. 确认目标节点能够访问APM端点，可通过curl \命令验证网络连通性。 3. 确认已通过OpenClaw发起实际的Agent对话活动（发送消息触发LLM调用）。 4. 查看gateway日志中是否出现export result: code=0, error=none。 **指标无数据** 1. 确认aom_enable=true（安装时默认已开启）。 2. 确认已配置aom_access_code、aom_exporter_endpoint、aom_prometheus_id三个参数。 3. 确认agentarts_project_id已正确配置。 4. 指标上报存在15秒周期延迟，请等待后再查询。 **AOM认证失败** 日志出现UNAUTHENTICATED: accesscode_does_not_match_the_projectId错误： 1. 确认aom_access_code与agentarts_project_id是同一账号下的一对凭证。 2. 确认aom_prometheus_id属于同一AOM实例。 3. 登录AgentArts平台，重新创建"OpenClaw"智能体，获取最新凭证参数，并重新执行安装脚本。 **调用链中看不到LLM输入/输出内容** 1. 确认content_capture_enable=true（默认已开启）。 2. 确认openclaw.json中已配置hooks.allowConversationAccess: true。 3. 中间推理步骤的内容由插件自动补全，无需额外配置。 **技能指标始终为0** 技能指标仅在检测到Skill相关的工具调用时触发，普通工具调用（如exec、calculator等）不会产生技能指标。满足以下条件之一时才会触发技能指标采集： 1. 工具调用参数中包含skills/\/路径模式（如\~/.openclaw/skills/hatch-pet/...）。 2. 工具调用参数中包含\/SKILL.md文件路径模式（如\~/.openclaw/hatch-pet/SKILL.md）。 3. 工具名匹配技能名单（如Skill、load_skill、read_skill、skill_view、skill_manage等）。 **全局Provider冲突警告** 日志中出现以下WARN日志属于正常行为，不影响数据上报： ``` [huawei-otel] a global OTel TracerProvider/MeterProvider is already registered by another component. ``` 插件使用独立的Provider实例，业务属性注入和指标记录不受影响。 **重启gateway** ``` openclaw gateway restart ``` **卸载探针** 卸载脚本就在安装时解压出的产物包目录里（与 install.sh / install.ps1 同级），在该目录下执行： ``` # Linux / macOS ./uninstall.sh # Windows .\uninstall.ps1 ``` 卸载脚本会移除插件目录、清理 openclaw.json 中的插件配置、删除环境变量文件。加 --yes（或 -y）可跳过确认。 与安装一致，卸载脚本不会重启 gateway（避免中断正在运行的 agent 任务）。卸载完成后请手动重启使其生效： ``` openclaw gateway restart ```