Codex Agent

步骤一：获取接入参数

1. 登录AgentArts 智能体平台。
2. 在左侧导航栏选择“观测与优化 > 观测”。
3. 在“智能体列表”页面，单击“接入智能体”，按照页面指引填写名称、智能体类型，创建一个“Codex”智能体，并获取各配置参数。
   图1 获取配置参数
   

步骤二：安装探针

1. 下载探针。
   下载Codex探针包，探针下载到本地项目后执行安装。

   pip install huaweicloud_opentelemetry_instrumentation_codex-1.0.0-py3-none-any.whl --force-reinstall

2. 验证探针安装成功。

   python -c "from opentelemetry.instrumentation.huawei_codex import auto_instrument; print('codex probe OK')"

   输出codex probe OK即安装成功。

3. 定位探针安装目录。

   whl包安装后，config.example.json（配置模板）、codex-traced.cmd（启动脚本）、load_config.py（配置加载脚本）等文件会释放到Python的site-packages目录下。执行以下命令查看site-packages路径：

   python -c "import sysconfig; print(sysconfig.get_paths()['purelib'])"

   输出示例（Windows）：C:\Users\<用户名>\AppData\Local\Programs\Python\Python311\Lib\site-packages

   探针文件位于该路径下的opentelemetry/instrumentation/huawei_codex/子目录中。请记录此路径，后续步骤需要用到。

步骤三：准备配置文件

探针通过本地配置文件config.json管理全部配置（凭证、代理、日志），无需再手动设置环境变量。

1. 创建探针工作目录。

   建议在本地创建一个专用目录用于存放探针配置和启动脚本，例如C:\codex-probe：

   mkdir C:\codex-probe

2. 从探针安装目录中复制所需文件到工作目录。

   将以下文件从<site-packages>\opentelemetry\instrumentation\huawei_codex\复制到C:\codex-probe\：

   • config.example.json（配置模板）
   • codex-traced.cmd（启动脚本）
   • load_config.py（配置加载脚本）

   copy "<site-packages路径>\opentelemetry\instrumentation\huawei_codex\config.example.json" C:\codex-probe\
   copy "<site-packages路径>\opentelemetry\instrumentation\huawei_codex\codex-traced.cmd" C:\codex-probe\
   copy "<site-packages路径>\opentelemetry\instrumentation\huawei_codex\load_config.py" C:\codex-probe\

   其中<site-packages路径>为步骤二：安装探针第3步中获取的路径。

3. 将模板复制为config.json。

   在工作目录中执行：

   cd C:\codex-probe
   copy config.example.json config.json

4. 编辑config.json，将占位符替换为实际值。各参数值参考步骤一：获取接入参数获取。

   用文本编辑器打开C:\codex-probe\config.json，编辑以下内容：

   {
     "version": "1.0.0",
     "enabled": true,
     "outputDir": "/tmp",
     "proxy": {
       "port": 8090,
       "upstream": "<CODEX_ORIGINAL_BASE_URL>"
     },
     "otel": {
       "agentarts_agentops_otel_agent_apm_enable": true,
       "agentarts_agentops_otel_agent_aom_enable": true,
       "agent_domain_id": "<AGENT_DOMAIN_ID>",
       "agentarts_project_id": "<AGENTARTS_PROJECT_ID>",
       "agent_resource_id": "<AGENT_RESOURCE_ID>",
       "resource_type": "<AGENT_TYPE>",
       "agentarts_agentops_apm_token": "<APM_TOKEN>",
       "agentarts_agentops_apm_exporter_endpoint": "<APM_ENDPOINT>:4317",
       "agentarts_agentops_aom_access_code": "<AOM_ACCESS_CODE>",
       "agentarts_agentops_aom_exporter_endpoint": "<AOM_ENDPOINT>:4317",
       "agentarts_agentops_aom_prometheus_id": "<AOM_PROMETHEUS_ID>"
     }
   }

   表2 参数说明

   参数	是否必填	说明
   otel.agent_domain_id	是	账号Domain ID。
   otel.agentarts_project_id	是	华为云项目ID。
   otel.agent_resource_id	是	智能体ID。
   otel.resource_type	是	智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。
   otel.agentarts_agentops_apm_token	条件必填（上报调用链数据时必填）	APM接入凭证。
   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。
   proxy.upstream	是	Codex接入观测前的模型端点地址（代理转发目标）。即Codex的config.toml中base_url的原始值。 例如：使用OpenAI API时填https://api.openai.com/v1；使用本地Ollama时填http://localhost:11434/v1。

   

   • proxy.upstream是探针代理转发的目标地址，必须与Codex接入观测前的base_url一致。探针代理会将拦截到的请求转发到该地址。
   • APM/AOM开关默认开启，某服务凭证缺失会只禁用该服务（日志warning），另一服务仍正常上报；显式设置=false可关闭对应服务。

步骤四：修改Codex配置

将Codex的base_url从原始模型端点改为探针代理地址，使Codex的请求经过探针代理拦截。

1. 打开Codex配置文件。

   Codex配置文件路径：

   • Windows：%USERPROFILE%\.codex\config.toml（即C:\Users\<用户名>\.codex\config.toml）
   • Linux/macOS：~/.codex/config.toml

   如果该文件不存在，先创建.codex目录和文件：

   mkdir %USERPROFILE%\.codex
   type nul > %USERPROFILE%\.codex\config.toml

2. 找到[model_providers.<id>]段（当前使用的model provider），将base_url改为探针代理地址。

   修改前（示例，base_url指向原始模型端点）：

   model_provider = "custom"
   model = "gpt-4o"
   model_reasoning_effort = "high"
   
   [model_providers.custom]
   name = "custom"
   wire_api = "responses"
   base_url = "https://api.openai.com/v1"

   修改后（base_url指向探针代理端口8090）：

   model_provider = "custom"
   model = "gpt-4o"
   model_reasoning_effort = "high"
   
   [model_providers.custom]
   name = "custom"
   wire_api = "responses"
   base_url = "http://localhost:8090/v1"

   

   • 仅修改base_url的值，将其从原始模型端点改为探针代理地址（默认http://localhost:8090/v1）。其他配置项（model、model_provider、wire_api、env_key等）保持不变。
   • base_url的端口必须与config.json中proxy.port的取值一致（默认8090）。
   • 如果代理端口被占用，修改config.json中proxy.port（如8091）后，必须在此处同步修改base_url端口为http://localhost:8091/v1。
   • 原始模型端点地址已记录在config.json的proxy.upstream中（步骤三：准备配置文件），探针代理会自动将请求转发到该地址。
   • 以上示例使用custom作为provider ID，仅为说明格式。请根据实际配置修改，provider ID不能使用保留名称openai、ollama、lmstudio。

步骤五：启动与验证

方式一：使用启动脚本（推荐）

1. 在命令行中切换到探针工作目录（即存放codex-traced.cmd和config.json的目录）：
   在步骤三：准备配置文件中，已创建一个专用目录用于存放探针配置和启动脚本，进入到该目录。

   cd C:\codex-probe

2. 执行启动脚本。

   codex-traced

   脚本会自动完成以下操作：

   1. 通过load_config.py自动从config.json（或config.example.json）加载配置，设置代理端口、上游端点、APM/AOM凭证等对应环境变量。
   2. 检查CODEX_UPSTREAM_ENDPOINT是否设置。
   3. 在后台（无窗口）启动OTel代理。
   4. 轮询/health端点验证代理是否就绪。
   5. 启动Codex CLI。
   6. Codex退出后自动清理代理进程。

方式二：手动启动

如果不使用启动脚本，可以手动分步执行：

1. 在命令行中切换到探针工作目录：

   在步骤三：准备配置文件中，已创建一个专用目录用于存放探针配置和启动脚本，进入到该目录。

   cd C:\codex-probe

2. 通过load_config.py加载config.json设置环境变量，然后在后台启动代理：

   for /f "delims=" %v in ('python -m opentelemetry.instrumentation.huawei_codex.load_config .') do %v
   start /min cmd /c "python -c "from opentelemetry.instrumentation.huawei_codex import auto_instrument; auto_instrument(); import time; time.sleep(99999)""

3. 等待2-3秒后，验证代理是否就绪：

   python -c "import http.client; c=http.client.HTTPConnection('localhost', 8090, timeout=3); c.request('GET', '/health'); r=c.getresponse(); print('proxy ready' if r.status==200 else 'proxy NOT ready'); c.close()"

   输出proxy ready后启动Codex：

   codex

验证数据上报

启动完成后，可通过以下步骤验证探针是否正常工作：

1. 查看代理日志，确认代理已正常启动。

   如果config.json中outputDir配置为/tmp（默认值），日志文件为%TEMP%\codex-proxy.log：

   type %TEMP%\codex-proxy.log

   如果配置了自定义outputDir（如/d/codex-probe-logs），则查看对应目录下的codex-proxy.log。

   正常情况下，日志应包含以下关键信息：

   CodexProbe | TracerProvider configured successfully
   CodexProbe | MeterProvider configured successfully
   CodexProxy | listening on port 8090, forwarding to <proxy.upstream地址>
   CodexProxy | 127.0.0.1 - POST /v1/responses

2. 在Codex中进行几轮对话，触发数据上报。
3. 前往AgentArts平台观测页面查看数据。数据上报存在延迟：Trace几秒内上报，Metrics最长60秒。

配置文件说明

探针不再依赖手动设置环境变量，全部配置集中在config.json（模板config.example.json），由启动脚本自动加载。以下为config.json各字段与对应含义：