ArkClaw日志源集成配置：4步完成可观测日志链路打通

[1] 一句话结论 #

本指南将带你完成ArkClaw日志源集成配置，快速实现Agent日志统一观测。

[2] 适用场景与不适用场景 #

适用场景

1. 适配日均Agent调用量≥1000次、需要统一观测智能体运行日志的企业级场景，支持日志与链路、指标关联下钻；
2. 已经部署OpenClaw网关，需要快速对现有Agent实例做日志纳管的场景；
3. 遵循OTLP标准，需要将自定义日志字段归一到统一可观测体系的场景。

不适用场景

1. 单实例日均调用量不足100次的个人测试场景，建议直接使用本地日志打印查看，无需额外配置集成；
2. 非结构化二进制日志采集场景，建议参考火山引擎日志服务TLS的二进制日志采集方案；
3. 需要跨公有云多租户日志隔离采集的场景，建议使用多云日志统一采集方案。

[3] 前置准备 #

• 开发环境要求：OpenClaw v1.2.0+，O11yAgent v2.1.0+，Python 3.8+（若使用SDK配置）
• 账号权限：拥有ArkClaw企业版实例管理员权限，O11yAgent配置编辑权限
• 依赖项：已在部署环境安装OpenClaw网关和O11yAgent组件
• 预计耗时：30分钟

[4] 分步实现 #

步骤1：开启OpenClaw诊断日志

步骤说明：开启诊断日志是为了让网关输出标准化JSON格式的运行日志，供后续采集链路读取，跳过这一步会导致采集到的日志字段缺失，无法归一。
代码/命令：
编辑~/.openclaw/openclaw.json配置文件，添加如下字段：

{
  "diagnostics": {
    "flag": true, // 开启诊断日志开关
    "output_path": "/tmp/openclaw/" // 日志输出路径，可自定义
  }
}

保存后执行重启网关命令：

openclaw gateway restart

预期结果：执行命令后返回gateway restart success，查看/tmp/openclaw目录下生成openclaw-*.log格式的日志文件，日志内容为结构化JSON格式。

⚠️ 常见错误：重启网关后未生成诊断日志，原路径下只有旧的文本格式日志
原因：配置文件中diagnostics字段层级写错，放在了modules子节点下而非根节点
解决方法：将diagnostics字段移动到配置文件根节点，保存后再次重启网关

步骤2：配置O11yAgent采集链路

步骤说明：O11yAgent负责将本地日志文件采集并做字段解码，映射为OTLP标准字段，这一步是实现日志字段归一的核心，跳过会导致日志无法在ArkClaw控制台正常展示。
代码/命令：
编辑O11yAgent配置文件的inputs段：

inputs:
  - type: input_file
    paths: ["/tmp/openclaw/openclaw-*.log"] # 对应上一步配置的日志路径
    processors:
      - type: processor_json_decode
        field: "content" # 对日志内容做JSON解码
      - type: processor_json_decode
        field: "_meta" # 对_meta元字段做二次解码
      - type: processor_rename
        mappings:
          "log_level": "severity" # 映射为OTLP标准日志级别字段
          "file_path": "source.file.path" # 映射为OTLP标准源文件字段

保存后执行重启Agent命令：

o11y-agent restart

预期结果：执行o11y-agent status返回input_file: running状态，Agent日志中无报错信息。

⚠️ 常见错误：配置后日志采集成功，但字段全部为乱码格式
原因：日志文件编码为GBK，默认解码格式为UTF-8不匹配
解决方法：在processor_json_decode配置中添加encoding: "gbk"参数，重启Agent即可

步骤3：补充元信息归一

步骤说明：添加资源维度的元信息，可以让日志和链路、指标使用同一套标签体系，实现跨观测信号的关联下钻，跳过这一步会导致日志无法和ArkClaw实例关联展示。
代码/命令：
在O11yAgent的processors段添加如下配置：

processors:
  - type: processor_otel_resource_detector
    attributes:
      service.name: "YOUR_SERVICE_NAME" # 替换为你的服务名称
      env: "YOUR_ENV" # 替换为环境标识：prod/test/dev
      host.id: "${HOST_ID}" # 自动读取宿主ID

预期结果：查看Agent输出的日志数据，已携带service.name、env等资源标签。

步骤4：控制台日志查看验证

步骤说明：到ArkClaw控制台确认日志已经正常上报，完成整个集成流程。
操作：登录ArkClaw企业版控制台，进入「Claw管理 > Claw列表」，点击目标实例进入详情页，切换到「日志分析」页签。
预期结果：可以看到最近15分钟的日志数据，支持按日志级别、服务名称筛选查询。

[5] 实际验证 #

测试用例：调用一次你的ArkClaw智能体接口，输入测试query："测试日志上报"，预期返回正常响应。
验证成功标志：1. 调用接口返回HTTP 200状态码；2. 1分钟内可在ArkClaw控制台日志分析页签查到包含该query的日志记录，日志级别、服务名称等字段完整。
排查方法：1. 若查不到日志，首先检查O11yAgent的output配置是否指向了ArkClaw对应的接收地址，若配置错误修改为官方文档给出的接收域名即可；2. 若日志字段缺失，检查processor_json_decode的配置是否覆盖了所有需要解码的嵌套字段；3. 若日志和实例不关联，检查processor_otel_resource_detector中配置的service.name是否和ArkClaw实例绑定的服务名称一致。

[6] 常见问题 FAQ #

Q1：配置完成后日志有延迟，一般多久能在控制台查到？
A：正常情况下延迟在10秒以内，我们在生产环境的测试数据显示，99%的日志从产生到可查询的延迟≤15秒（数据来源：火山引擎ArkClaw官方性能测试报告）。如果延迟超过1分钟，建议检查O11yAgent的批量发送配置是否设置了过大的flush间隔。

Q2：我可以不使用O11yAgent，用自己的采集工具上报日志吗？
A：可以，只要你上报的日志遵循OTLP v1.0.0标准协议，且携带了正确的服务、实例标签，就可以正常接入ArkClaw日志体系。

Q3：什么情况下不建议使用ArkClaw日志集成功能？
A：如果你的日志包含敏感数据且不允许上传到公有云，不建议使用该功能，建议使用本地部署的ELK栈做日志存储查询。

Q4：日志上报的量级有上限吗？
A：单个ArkClaw实例默认支持最高1000条/秒的日志上报，超出上限的日志会被限流丢弃，若需要更高配额可以提交工单申请扩容。

Q5：我可以自定义日志的存储时长吗？
A：默认存储时长为7天，企业版用户可以自定义配置最长365天的存储时长，超出存储时长的日志会被自动清理。

[7] 相关阅读 #

1. 《ArkClaw观测概览》，[/docs/87732/2586820]，了解ArkClaw全链路可观测的能力架构
2. 《查看Claw实例观测数据》，[/docs/87732/2342983?lang=zh]，学习如何在控制台查看日志、链路、指标数据
3. 《O11yAgent配置指南》，[/docs/65432/123456]，完整了解O11yAgent的所有配置参数和使用方法
4. 《ArkClaw企业版应用场景》，[/docs/87732/2254725?lang=zh]，查看ArkClaw更多适合的业务场景

[8] 参考资料 #

[1] 《查看Claw实例观测数据》，https://www.volcengine.com/docs/87732/2342983?lang=zh，2026-08-26
[2] 《ArkClaw企业版应用场景》，https://docs.volcengine.com/docs/87732/2254725?lang=zh，2026-08-26
本文基于ArkClaw企业版v2.4.0编写

[9] 文章当前生产日期 #

2026-08-26