# OpenCode Agent 本文介绍如何将OpenCode Agent接入华为云AgentArts观测服务，实现调用链追踪和业务指标监控。接入后无需修改业务代码，插件自动采集Agent调用、模型调用、工具调用等数据并上报。 **快速入门：** 前提：本地已安装OpenCode（版本\>= 1.x），且OpenCode首次启动后已自动生成opencode.json配置文件。 1. 在AgentArts平台创建OpenCode智能体，获取接入参数。 2. 安装whl包并运行install.py部署脚本，传入接入参数，按提示在opencode.json中注册插件。 3. 重启OpenCode，触发会话后在AgentArts观测页面查看调用链和指标数据。 详细步骤见下方[接入步骤]。 #### 前提条件 - Python环境版本 \>= 3.9 - OpenCode版本 \>= 1.x - 已安装OpenCode，且OpenCode首次启动后已自动生成全局配置文件opencode.json。 - 目标节点上已存在OpenCode的插件目录\~/.opencode/plugins/（若不存在，部署步骤会创建）。 ![](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都是按需计费，并有一定量的免费额度，超出后按实际使用量收费。 #### 工作原理 OpenCode是一款AI编程助手，可以在终端中直接运行，帮助用户完成代码编写、代码分析等任务。 OpenCode Metrics插件用于对OpenCode智能体进行可观测。插件本质上是一段JavaScript程序（编译为plugin.mjs，自包含全部依赖），运行在OpenCode进程内，直接读取OpenCode的运行事件，将数据整理成OTel格式后上报到AgentArts。 数据流转过程： ``` OpenCode Agent运行时 ├── 加载opencode-metrics插件（plugin.mjs） │ ├── 采集Agent调用事件 │ ├── 采集模型调用事件 │ └── 采集工具调用事件 │ ├── Trace数据 ──OTLP gRPC──→ APM（调用链） └── Metrics数据 ──OTLP gRPC──→ AOM（指标） │ ▼ AgentArts观测平台展示 ``` 接入后，以下能力将被自动监控： - Agent执行链路：Agent调用、Turn回合的完整生命周期。 - LLM调用（chat）：模型名称、Token用量、输入/输出内容、首Token时延。 - 工具调用（Tool）：工具名称、参数、返回结果、执行耗时。 - 技能调用（Skill）：技能名称、调用次数、耗时等指标。 #### 接入步骤 #### 步骤一：获取接入参数 1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。 2. 在左侧导航栏选择"观测与优化 \> 观测"。 3. 在"智能体列表"页面，单击"接入智能体"，按照页面指引填写名称、智能体类型，创建一个"OpenCode"智能体，并获取各配置参数。 图1获取配置参数 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002806227281.png "点击放大") #### 步骤二：安装插件 OpenCode Metrics插件提供两种部署方式，可任选其一： - 方式一（推荐）：通过pip安装whl包，使用install.py脚本一键部署。适合希望自动化完成文件复制、配置生成的场景。 - 方式二：手动放置构建产物文件（plugin.mjs、package.json、config.json文件）到对应目录。适合已获取构建产物、希望手动控制部署过程的场景。 无论采用哪种路径，部署完成后的最终文件布局完全一致： ``` ~/.config/opencode/ └── opencode.json # OpenCode主配置（首次启动OpenCode后自动生成，追加插件注册） ~/.opencode/ └── plugins/ └── opencode-metrics/ ├── plugin.mjs # 插件主程序（自包含全部依赖） └── package.json # 插件元数据 ~/.opencode-metrics/ # 插件数据/配置根目录 ├── config.json # 插件配置（含OTel上报参数） └── data/ └── logs/ └── plugin-YYYY-MM-DD.log # 插件运行日志（按天滚动，自动创建） ``` **方式一：whl包 + install.py一键部署（推荐）** 1. 安装探针包。 下载[OpenCode探针包](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/huaweicloud_opentelemetry_instrumentation_opencode-1.0.0-py3-none-any.whl)，将探针包复制到目标节点，执行以下命令安装： ``` pip install huaweicloud_opentelemetry_instrumentation_opencode-1.0.0-py3-none-any.whl --force-reinstall ``` 执行后，whl包内的文件（含plugin.mjs、config.example.json、scripts/install.py等）会被释放到Python安装目录的site-packages目录下，具体位置是： ``` /opencode_metrics/ ``` 其中\是Python安装第三方库的目录。可用以下命令确认它的实际路径： ``` python -c "import sysconfig; print(sysconfig.get_paths()['purelib'])" ``` 2. 运行install.py一键安装。 install.py位于\/opencode_metrics/scripts/install.py路径下。执行以下命令完成安装，命令中的参数按实际替换。 参数获取方法参考[步骤一：获取接入参数]。 Linux / macOS（bash） ``` python /opencode_metrics/scripts/install.py \ --agent-id {{agent_id}} \ --domain-id {{domain_id}} \ --project-id {{project_id}} \ --endpoint {{trace_endpoint}} \ --token {{trace_token}} \ --aom-endpoint {{metric_endpoint}} \ --aom-access-code {{metric_token}} \ --aom-prometheus-id {{prom_id}} \ --resource-type {{agent|multiagents|workflow}} ``` Windows（PowerShell） ``` python /opencode_metrics/scripts/install.py ` --agent-id {{agent_id}} ` --domain-id {{domain_id}} ` --project-id {{project_id}} ` --endpoint {{trace_endpoint}} ` --token {{trace_token}} ` --aom-endpoint {{metric_endpoint}} ` --aom-access-code {{metric_token}} ` --aom-prometheus-id {{prom_id}} ` --resource-type {{agent|multiagents|workflow}} ``` 表1参数说明 | 参数 | 是否必选 | 说明 | |:---|:---|:---| | --agent-id | 是 | 智能体ID。 | | --domain-id | 是 | 账号domain ID。 | | --project-id | 是 | 华为云项目ID。 | | --endpoint | 是 | APM数据上报地址。 | | --token | 是 | APM接入凭证Token。 | | --aom-endpoint | 条件必填（上报指标数据时必填） | AOM数据上报地址。 | | --aom-access-code | 条件必填（上报指标数据时必填） | AOM接入凭证Access Code。 | | --aom-prometheus-id | 条件必填（上报指标数据时必填） | AOM Prometheus实例ID。 | | --resource-type | 是 | 智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。 | install.py自动完成以下操作： - 定位plugin.mjs并复制到\~/.opencode/plugins/opencode-metrics/目录。 - 生成插件元数据package.json。 - 使用传入的参数值生成config.json并写入\~/.opencode-metrics/目录。 - 打印opencode.json中需要追加的plugin配置（file:// URL自动适配Windows/Linux）。 3. 在opencode.json中注册插件并重启OpenCode。 按照install.py打印的提示，将plugin配置追加到\~/.config/opencode/opencode.json中（详细步骤参考[方式二的第3步]），然后重启OpenCode即可。 **方式二：手动放置构建产物文件** 本方式适用于已经获取到构建产物（plugin.mjs + package.json + config.json）的情况。适合希望手动控制文件来源的场景。 下载[OpenCode探针包](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/huaweicloud_opentelemetry_instrumentation_opencode-1.0.0-py3-none-any.whl)，将探针包复制到目标节点，执行以下命令安装： ``` pip install huaweicloud_opentelemetry_instrumentation_opencode-1.0.0-py3-none-any.whl ``` 执行后，whl包内的文件（含plugin.mjs、config.example.json、scripts/install.py等）会被释放到Python安装目录的site-packages目录下，具体位置是： ``` /opencode_metrics/ ``` ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002779831582.png "点击放大") 构建产物包含以下文件： - plugin.mjs：插件主程序 - package.json：插件元数据 - config.json或config.example.json：插件配置模板 1. 创建插件目录。 Linux / macOS（bash） ``` # 插件安装目录（存放plugin.mjs和package.json） mkdir -p ~/.opencode/plugins/opencode-metrics # 插件数据目录（运行时日志输出到data/logs/plugin-YYYY-MM-DD.log） mkdir -p ~/.opencode-metrics/data/logs ``` Windows（PowerShell） ``` New-Item -ItemType Directory -Force "$env:USERPROFILE\.opencode\plugins\opencode-metrics" | Out-Null New-Item -ItemType Directory -Force "$env:USERPROFILE\.opencode-metrics\data\logs" | Out-Null ``` 2. 放置插件文件。 将获取到的三个文件分别放置到对应目录： ``` # 插件主程序（esbuild单文件，自包含全部依赖） cp plugin.mjs ~/.opencode/plugins/opencode-metrics/ # 插件元数据（OpenCode通过它识别插件，main字段必须与plugin.mjs同名） cp package.json ~/.opencode/plugins/opencode-metrics/ # 插件配置（含OTel上报参数，需按实际环境修改） cp config.json ~/.opencode-metrics/ ``` 3. 在opencode.json中注册插件。 - 确认opencode.json文件是否存在。 正常安装OpenCode后，会自动生成opencode.json文件，该文件是OpenCode的全局主配置文件，位于用户配置目录（注意：是\~/.config/opencode/，不是\~/.opencode/）： - Linux/macOS路径：\~/.config/opencode/opencode.json - Windows路径：\<用户主目录\>\\.config\\opencode\\opencode.json 执行以下命令确认文件是否存在： Linux / macOS（bash） ``` ls ~/.config/opencode/opencode.json ``` Windows（PowerShell） ``` Get-Item "$env:USERPROFILE\.config\opencode\opencode.json" ``` - 若文件不存在，创建目录和文件： Linux / macOS（bash） ``` mkdir -p ~/.config/opencode touch ~/.config/opencode/opencode.json ``` Windows（PowerShell） ``` New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null New-Item -ItemType File -Force "$env:USERPROFILE\.config\opencode\opencode.json" | Out-Null ``` - 编辑opencode.json，在文件中追加plugin数组配置（注意是追加，不要覆盖文件里已有的其他字段）。 ``` { "$schema": "https://opencode.ai/config.json", "plugin": [ "file://C:/Users/<用户名>/.opencode/plugins/opencode-metrics/plugin.mjs" ] } ``` 路径格式说明： - Windows：file://C:/Users/...。使用正斜杠，盘符后没有额外的斜杠。 - macOS/Linux：file:///Users/\<用户名\>/.opencode/plugins/opencode-metrics/plugin.mjs。注意是三个斜杠。 4. 重启OpenCode。 #### 步骤三：验证数据上报 数据上报成功后，可在AgentArts平台中查看观测数据。 1. 验证OpenCode Metrics插件是否正常加载。 重启OpenCode后，执行以下命令检查插件是否加载成功： ``` # 列出插件日志文件（按天滚动），确认日志目录已生成 ls -la ~/.opencode-metrics/data/logs/plugin-*.log # 查看最近 20 行日志，确认插件初始化成功，无报错 tail -20 ~/.opencode-metrics/data/logs/plugin-*.log ``` 正常情况下，日志应包含以下关键信息： - \[opencode-metrics\] OTel init config: {...}：初始化配置加载成功 - \[opencode-metrics\] AsyncLocalStorageContextManager registered：上下文管理器注册成功 - \[opencode-metrics\] APM (Traces) initialized：APM Trace初始化成功 - \[opencode-metrics\] AOM (Metrics) initialized：AOM Metrics初始化成功 2. 触发OpenCode会话，验证数据上报。 在OpenCode中做一轮问答后，触发数据上报，然后执行以下命令查看日志： ``` tail -50 ~/.opencode-metrics/data/logs/plugin-*.log ``` 正常情况下，日志应包含以下关键信息： - OTel processTurn: \ events: N：事件采集成功 - APM (Traces) export SUCCESS {spanCount: N, ...}：Trace上报成功 - AOM (Metrics) export SUCCESS {totalDataPoints: N, ...}：Metrics上报成功（按collectInterval周期，默认每30秒一次） - AOM All Metric Details: {...}：上报属性明细（仅当features.debug: true时打印） #### 配置参数说明 插件安装后，所有配置集中在\~/.opencode-metrics/config.json中。一键部署（方式一）由install.py自动生成，手动部署（方式二）需手动编辑。 config.json是OpenCode Metrics插件的核心配置文件，包含OTel上报参数、功能开关等。完整配置模板如下： ``` { "version": "3.0.0", // 插件总开关 "enabled": true, // 日志输出目录（兼容多种路径写法：/d/data/example、D:/data/example、D:\\data\\example） "outputDir": "/d/codezone", // 用户ID（注入user.id）：为空或不设置则兜底使用主机名 "user.id": "", // 采集周期（毫秒）：每隔多久从内存缓冲采集并上报一次事件，默认30000（30秒） "collectInterval": 30000, "features": { "debug": false, // debug日志开关，默认false "captureMessageContent": true // 是否采集trace输入/输出消息内容，默认true }, // ============ OTel上报配置（AgentArts） ============ "otel": { "agentarts_agentops_otel_agent_apm_enable": true, "agentarts_agentops_otel_agent_aom_enable": true, "agent_domain_id": "", "agentarts_project_id": "", "agent_resource_id": "", "resource_type": "", "agentarts_agentops_apm_token": "", "agentarts_agentops_apm_exporter_endpoint": "", "agentarts_agentops_aom_access_code": "", "agentarts_agentops_aom_exporter_endpoint": "", "agentarts_agentops_aom_prometheus_id": "" } } ``` 表2config.json文件各字段说明 | 参数 | 是否必填 | 默认值 | 说明 | |:---|:---|:---|:---| | version | 是 | - | 版本号。 | | enabled | 是 | true | 插件总开关。false时插件完全休眠，不采集、不上报。 | | outputDir | 否 | \~/.opencode-metrics/data | 日志输出目录（日志文件logs/plugin-YYYY-MM-DD.log），默认\~/.opencode-metrics/data。路径兼容\~/xxx、/d/codezone（Git Bash 风格）、D:/codezone、D:\\codezone等多种写法。 | | user.id | 否 | 空 | 用户ID（注入 user.id，Span与Metrics均生效）。为空/不设置则兜底主机名。 | | collectInterval | 否 | 30000 | 采集上报周期（ms），默认 30000（30 秒）。 | | features.debug | 否 | false | debug日志开关，默认false。为true时打印AOM上报属性明细等DEBUG日志，排查问题时使用。 | | features.captureMessageContent | 否 | true | 是否采集Trace输入/输出消息内容，默认true。为false时，Trace各Span（根/LLM/工具/Skill）不携带input.value、output.value、gen_ai.input.messages、gen_ai.output.messages、gen_ai.tool.call.arguments、gen_ai.tool.call.result等内容属性。其他Trace属性与Metrics上报不受影响。 | | otel.agentarts_agentops_otel_agent_apm_enable | 是 | true | APM（Trace调用链数据）上报开关。 | | otel.agentarts_agentops_otel_agent_aom_enable | 是 | true | AOM（Metrics指标数据）上报开关。 | | otel.agent_domain_id | 是 | - | 账号ID。 | | otel.agentarts_project_id | 是 | - | 华为云项目ID。 | | otel.agent_resource_id | 是 | - | 智能体ID。 | | otel.resource_type | 是 | - | 智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。 | | otel.agentarts_agentops_apm_token | 条件必填（上报调用链数据时必填） | - | APM接入凭证Token。 | | otel.agentarts_agentops_apm_exporter_endpoint | 条件必填（上报调用链数据时必填） | - | APM数据上报地址。 | | otel.agentarts_agentops_aom_access_code | 条件必填（上报指标数据时必填） | - | AOM接入凭证Access Code。 | | otel.agentarts_agentops_aom_exporter_endpoint | 条件必填（上报指标数据时必填） | - | AOM数据上报地址。 | | otel.agentarts_agentops_aom_prometheus_id | 条件必填（上报指标数据时必填） | - | AOM Prometheus实例ID。 | #### 查看监控数据 数据上报成功后，可在AgentArts智能体平台的观测功能中查看监控数据。 1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。 2. 在左侧导航栏选择"观测与优化 \> 观测"。 3. 在"智能体列表"页面，找到已接入的智能体，单击智能体名称进入详情页面。 **查看业务指标** 在"指标分析"页签中，可以查看关键业务指标： - Tokens消耗：Input Tokens和Output Tokens的消耗总量 - 模型调用次数：应用调用大模型的累计次数 - 模型调用平均耗时：模型调用的平均响应时间 - 模型调用成功率：大模型调用成功的比例 - 会话数：应用产生的会话总数 - 响应成功率：服务响应的成功率 **查看调用链信息** 在"调用链分析"页签中，可以查看完整的Trace调用链路： - 查看各Span类型的层级关系及各节点耗时 - 单击具体Span查看详细信息 **查看会话分析** 在"会话分析"页签中，可以查看智能体与用户对话的历史数据： - 追踪对话上下文 - 分析模型响应耗时 - 统计Token消耗 - 快速定位对话异常问题 #### 更多参考 **控制内容采集** 默认情况下，插件会采集trace输入/输出消息内容。如需关闭（隐私或合规场景），在config.json中设置： ``` "features": { "captureMessageContent": false } ``` 关闭后，trace各span不携带input.value、output.value、gen_ai.input.messages、gen_ai.output.messages、gen_ai.tool.call.arguments、gen_ai.tool.call.result等内容属性。模型名、Token用量、耗时、调用链结构、工具名称等非内容属性不受影响。 **开启调试日志** 排查问题时，在config.json中设置： ``` "features": { "debug": true } ``` 开启后，日志中会打印AOM上报属性明细等DEBUG信息。排查完成后建议关闭，减少日志量。 **用户ID注入** 插件支持把用户标识注入到user.id属性中，用于按用户维度统计和过滤。 设置方式：在config.json中配置： ``` "user.id": "" ``` 如果不设置或留空，插件会使用主机名作为兜底值。多用户共享主机时，建议显式设置以区分不同用户。 #### 常见问题 **插件未加载** 现象：日志目录下没有生成plugin-\*.log文件，或者日志文件长时间为空。 排查步骤： 1. 确认\~/.config/opencode/opencode.json中的plugin配置已经追加，路径格式正确。 2. 确认plugin.mjs文件存在于配置中指定的路径下。 3. 重启OpenCode后再次检查。 4. 如果opencode.json的plugin路径是file:// URL，检查斜杠数量是否符合平台要求（Windows两个斜杠，macOS/Linux三个斜杠）。 **日志中出现AOM export FAILED** 现象：AOM上报失败，日志中出现AOM export FAILED 排查步骤： 1. 检查config.json中agentarts_agentops_aom_access_code的值是否与AgentArts平台提供的一致。 2. 检查agentarts_agentops_aom_exporter_endpoint取值是否正确。 3. 检查网络连接，确保目标节点能访问AOM的endpoint。 **页面指标为0，但日志显示SUCCESS** 现象：日志中显示AOM (Metrics) export SUCCESS或APM (Traces) export SUCCESS，但AgentArts中查不到数据或数据为0。 排查步骤： 1. 检查config.json中的agent_resource_id是否与AgentArts中绑定的OpenCode智能体ID一致。不一致会导致页面看不到数据。 2. 检查agent_domain_id和agentarts_project_id是否正确。 3. 检查resource_type是否与实际智能体类型一致（agent / multiagents / workflow）。 **页面Skill数为0** 现象：AgentArts平台中Skill相关指标为0。 排查步骤： 1. 确认使用OpenCode执行任务过程中是否有调用Skill。 2. 确认Skill调用走的是可被插件采集的路径。若Skill走 command 路径，可能不被采集。 3. 查看日志中是否有skillCallCount.add输出，确认Skill调用已被记录。