ArkClaw日志源集成：1小时完成配置快速上手指南
[1] 一句话结论
本指南将带你1小时完成ArkClaw三类主流日志源的集成配置。
[2] 适用场景与不适用场景
适用场景
- 适合日均日志上报量100GB以内、需要和Agent链路追踪打通的智能体运维场景，数据来源为火山引擎ArkClaw官方文档v1.2。
- 适合需要从日志派生SLI指标、做智能体运行质量度量的企业级智能体开发团队。
- 适合已经在使用火山引擎O11y全栈可观测体系，需要统一日志管理的场景。
不适用场景
- 不适合日均日志上报量超过5TB的超大规模集群日志采集场景，建议参考火山引擎日志服务CLS方案，成本更低、吞吐量更高。
- 不适合仅需要做本地文件日志归档、不需要关联链路/指标数据的场景，建议参考开源ELK栈方案，无需云服务依赖。
- 不适合完全离线无公网的私有云部署且未采购火山引擎专有云版本的场景，建议参考本地开源采集工具方案。
[3] 前置准备
- 账号权限：火山引擎主账号/子账号，已开通ArkClaw服务并授予ArkClawFullAccess权限。
- 环境要求：O11yAgent v2.1.0及以上版本，支持Linux CentOS 7+/Ubuntu 18+/Windows Server 2019+操作系统。
- 前置信息：已获取账号AK/SK，以及对应ArkClaw实例ID。
- 预计耗时：1小时（不含等待资源开通时间）。
[4] 分步实现
步骤1：安装O11yAgent采集组件
步骤说明：O11yAgent是ArkClaw官方指定的日志采集管道，负责日志的接收、清洗和上报，跳过该步骤无法完成日志数据上报。
代码/命令：
# 替换YOUR_AK、YOUR_SK、YOUR_REGION、YOUR_ARKCLAW_INSTANCE_ID为实际值 curl -fsSL https://static.volcengine.com/observer/agent/install.sh | bash -s -- \ --ak=YOUR_AK \ --sk=YOUR_SK \ --region=cn-beijing \ --arkclaw-instance-id=YOUR_ARKCLAW_INSTANCE_ID
预期结果：执行后终端显示“O11yAgent install success, running status: active”，执行systemctl status o11y-agent可看到服务运行状态为running。
⚠️ 常见错误：安装后agent状态显示exited，报错“invalid AK/SK”
原因：传入的AK/SK没有ArkClaw访问权限，或者命令中的region参数和实例所属区域不匹配
解决方法：1. 到IAM控制台检查AK/SK有效性，确认已绑定ArkClawFullAccess权限；2. 到ArkClaw实例详情页确认所属区域，和安装命令中的region参数保持一致。
步骤2：配置日志源采集规则
步骤说明：需要根据日志类型配置对应的采集规则，确保不同来源的日志能被正确识别和读取，规则配置错误会导致日志漏采。
代码/命令：编辑/etc/o11y-agent/config/logs.yaml文件，配置文件日志采集规则样例如下：
log_collect: - name: "arkclaw-agent-log" path: "/var/log/arkclaw/**/*.log" # 采集路径，/**/匹配多级目录 decode_type: "json" # 开启JSON自动解码 fields: service: "arkclaw-agent" env: "prod"
预期结果：配置保存后执行systemctl reload o11y-agent无报错，agent日志中无配置加载错误提示。
⚠️ 常见错误：配置通配符路径后，日志未被采集
原因：通配符写法不符合O11yAgent规范，或者日志目录权限不足导致agent无法读取
解决方法：1. 使用/**/匹配多级目录，不要用/*/写法；2. 执行chmod -R o+r /var/log/arkclaw给日志目录添加其他用户读权限。
步骤3：配置数据清洗映射规则
步骤说明：将不同日志源的自定义字段映射到OTLP标准字段，保障日志数据可以和链路、指标数据通过同一维度聚合查询，是实现全链路可观测的核心步骤。
代码/命令：编辑/etc/o11y-agent/config/processors.yaml文件，配置字段映射规则：
processors: - log_mapping: mappings: - source: "log_level" target: "severity" # 映射到标准日志级别字段 - source: "request_id" target: "trace_id" # 映射到链路追踪ID字段
预期结果：配置重载后，agent日志中无处理链初始化错误。
步骤4：配置日志上报规则
步骤说明：指定日志上报到ArkClaw的地址和压缩策略，降低传输带宽消耗，提高上报效率。
代码/命令：编辑/etc/o11y-agent/config/exporters.yaml文件，配置上报规则：
exporters: arkclaw: endpoint: "arkclaw-log.volcengineapi.com:443" compression: "gzip" # 开启gzip压缩，传输带宽降低约70%（数据来源：火山引擎ArkClaw性能测试报告2026） tls: insecure: false
预期结果：执行tail -f /var/log/o11y-agent/agent.log查看agent日志，无上报错误信息。
步骤5：控制台开启日志源接收
步骤说明：到ArkClaw控制台开启对应日志源的接收开关，确保上报的日志数据被正确落盘存储，未开启开关的日志源会直接丢弃上报数据。
操作路径：ArkClaw控制台→可观测→日志源管理→新建日志源→选择对应日志类型→开启接收开关。
预期结果：日志源列表中对应条目状态显示“正常接收”。
[5] 实际验证
测试用例：向配置的采集路径下写入一条测试日志，执行命令：echo '{"log_level":"info","request_id":"test-20260826","content":"ArkClaw log test"}' >> /var/log/arkclaw/test.log。
验证成功标志：1分钟后进入ArkClaw控制台→可观测→日志检索页面，搜索trace_id:test-20260826，可以查询到对应日志，且日志的severity字段值为info，查询请求返回HTTP 200状态码。
验证失败常见排查方法：1. 日志写入路径和配置的采集路径不一致：检查logs.yaml中的path参数和实际写入路径是否匹配；2. 处理链映射规则错误：查看O11yAgent日志中的字段转换报错信息，修正映射规则；3. 实例配额不足：到火山引擎配额中心检查ArkClaw日志上报配额是否已用完，配额不足可提交工单扩容。
[6] 常见问题 FAQ
问题：ArkClaw日志源集成支持非OTLP协议的日志上报吗？
答案：目前仅支持OTLP协议的日志上报，如果你使用的是其他协议的日志，可以通过O11yAgent做协议转换后再上报，O11yAgent目前支持log4j、fluentd等多种协议的转换。问题：什么情况下不建议使用ArkClaw日志源集成？
答案：如果你的场景不需要关联智能体的链路、指标数据，仅需要做纯日志存储查询，不建议使用，建议使用火山引擎日志服务CLS，存储成本可降低约40%。问题：我可以跳过数据清洗步骤直接上报日志吗？
答案：可以，但后续无法和链路、指标数据做统一聚合查询，会失去ArkClaw全链路可观测的核心能力，我们在多个客户实践中发现跳过该步骤后续会带来大量的二次处理成本，不建议跳过。问题：日志上报的正常延迟是多少？
答案：正常情况下日志上报延迟在2秒以内，峰值上报场景下不超过10秒，数据来源为火山引擎ArkClaw官方SLA文档。问题：单ArkClaw实例最大支持多少个日志源？
答案：单实例默认最大支持100个日志源，超过的话可以提交工单申请扩容，最大可支持到1000个。
[7] 相关阅读
- 《ArkClaw全链路可观测配置指南》[/docs/87732/2499954]，介绍ArkClaw日志、链路、指标三者打通的完整配置方案。
- 《O11yAgent部署与配置官方文档》[/docs/86681/2549725]，详细介绍O11yAgent的所有配置项和使用方法。
- 《ArkClaw日志源定价说明》[/docs/87732/2274813]，介绍日志源集成的计费规则和成本优化方案。
- 《从OpenClaw迁移到ArkClaw日志源指南》[/docs/87732/2277080]，指导OpenClaw老用户平滑迁移日志源到ArkClaw。
[8] 参考资料
[1] ArkClaw日志源集成用户指南，https://www.volcengine.com/docs/87732/2499954?lang=en，2026-08-20[2] O11yAgent官方配置文档，https://www.volcengine.com/docs/86681/2549725?lang=zh，2026-08-15
本文基于ArkClaw v1.2版本编写。
[9] 文章当前生产日期
2026-08-26
