日志

日志用于排查设备智能体创建、设备接入、对话控制、IM 接入、语音和视觉等运行问题。你可以在控制台查看和筛选记录，也可以直接读取本地日志文件。

打开日志页面

在控制台左侧导航点击日志，进入 /workspace/logs。页面主要分为两部分：

区域	用途
日志文件	查看当前可用的日志文件，文件名通常类似 `device-agent-2026-05-11.log`。
日志记录	查看选中文件里的最近记录，默认加载最近 200 条。

如果页面提示“文件日志已关闭”，点击右上角 日志配置，启用文件日志并保存。启用后，新记录会开始写入日志文件；启用前的历史记录不会补写。

日志页面

本地日志文件

文件日志默认写入运行时目录下的 logs 子目录：

运行方式	默认目录
仓库源码开发	`<repo>/.device_agent/logs`
已安装的生产二进制	`~/.device_agent/logs`

Agent Gateway 启动时会打印 Runtime Home。LOG_DIR=logs 会相对这个目录解析；如果 LOG_DIR 是绝对路径，则直接写入该路径。注意目录名是 .device_agent。

同一天日志按大小切分，文件名如下：

text

device-agent-2026-05-11.log
device-agent-2026-05-11.001.log
device-agent-2026-05-11.002.log

device-agent-YYYY-MM-DD.log 是当天第一个文件；超过 LOG_MAX_SIZE_MB 后继续写入 .001.log、.002.log 等分片。日志页面只列出符合这个命名规则的文件。

日志记录格式

日志文件是 JSON Lines，每行是一条完整 JSON 记录。

json

{
  "time": "2026-05-11T05:20:12.123Z",
  "level": "info",
  "module": "MQTT",
  "msg": "device connected",
  "requestId": "req-...",
  "productId": "product-001",
  "deviceId": "device-001",
  "topic": "device-agent/product-001/device/device-001/out",
  "args": [{ "durationMs": 18 }]
}

常用字段如下：

字段	说明
`time`	ISO 时间，始终按 UTC 写入。
`level`	`debug`、`info`、`warn` 或 `error`。
`module`	产生日志的后端模块，例如 `Gateway`、`HTTP`、`MQTT`、`Agent`、`Tools`、`Skills`、`Voice`、`NTP`、`A2A-Channel`。
`msg`	日志消息。
`requestId` / `sessionId` / `traceId`	串联一次请求、对话或工具调用。
`namespace` / `productId` / `deviceId` / `topic`	定位租户、设备和 MQTT 主题。
`method` / `path` / `statusCode` / `durationMs`	HTTP 或服务调用相关信息。
`provider` / `tool`	模型服务、语音服务或工具执行相关信息。
`args` / `error`	补充上下文和异常信息，已做脱敏和截断。

包含 apiKey、authorization、cookie、password、secret、token、privateKey 等敏感含义的字段会写成 [redacted]。普通业务数据不会自动移除，分享日志前仍要检查设备 ID、主题、状态值和第三方用户 ID。

本地排查命令

在源码开发环境中，从仓库根目录查看日志：

bash

ls -lh .device_agent/logs
tail -n 200 .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.level == "error")' .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.deviceId == "device-001") | {time, level, module, msg, topic}' \
  .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.requestId == "req-...")' .device_agent/logs/device-agent-2026-05-11.log

日志页面使用这些本地接口：

接口	用途
`GET /api/logs/files`	列出可读日志文件。
`GET /api/logs/tail?file=device-agent-2026-05-11.log&lines=200`	读取指定文件末尾记录，`lines` 最大为 `1000`。
`GET /api/logs/tail?file=device-agent-2026-05-11.log&before=<offset>`	继续读取更早记录，`before` 使用上一次响应里的 `nextBeforeOffset`。
`GET /api/logs/download?file=device-agent-2026-05-11.log`	下载指定日志文件。

查看和筛选记录

选中一个日志文件后，可以用以下方式定位问题：

操作	适合场景
刷新	设备刚上线、刚下发命令或刚完成一次对话后，刷新查看最新记录。
查看更早记录	当前 200 条不够时，继续加载更早的记录。
按级别筛选	只看 `warn` 或 `error`，快速定位异常。
按消息搜索	搜索错误关键词、平台名称、MQTT 主题或模型服务返回信息。
按模块筛选	只看某类能力的记录，例如 MQTT、HTTP、Voice、Tools、A2A。
按请求 ID 搜索	对一次 HTTP 请求、对话或工具调用做链路排查。
按设备 ID 搜索	只查看某台设备的上报、命令和响应记录。

每条记录都可以展开查看完整 JSON。需要分享单条记录时，点击右侧复制按钮；需要导出当前文件时，点击右上角下载按钮。

日志级别

级别	说明
`debug`	最详细，适合临时排查复杂问题。记录量较大，不建议长期打开。
`info`	默认推荐级别，记录启动、连接、请求和主要运行状态。
`warn`	只记录可能影响功能但未必导致失败的问题。
`error`	只记录失败和异常。

日常使用建议保持 info。如果某个问题难以复现，可以临时切到 debug，复现后再调回 info。

配置日志

在日志页面点击 日志配置，可以调整：

配置	作用
级别	控制记录多少日志。
控制台日志	是否在服务启动终端中输出日志。
文件日志	是否写入可在日志页面查看和下载的日志文件。
日志目录	文件日志保存位置。相对路径会放在设备智能体数据目录下。
单文件上限	单个日志文件达到上限后会自动切分。
保留天数	超过保留天数的旧日志会自动清理。
总容量上限	所有日志文件超过上限后，会优先删除更旧的文件。
文件日期时区	控制日志文件名按系统时区还是 UTC 日期生成。

保存后的日志配置会写入本地配置。.env 中的同名配置仍会在服务启动时覆盖控制台保存的值。

常用 .env 配置如下：

bash

LOG_LEVEL=info
LOG_CONSOLE_ENABLED=true
LOG_FILE_ENABLED=true
LOG_DIR=logs
LOG_MAX_SIZE_MB=50
LOG_RETENTION_DAYS=14
LOG_MAX_TOTAL_SIZE_MB=1024
LOG_TIMEZONE=system

更多配置入口见配置。

常见排查路径

问题	建议查看
设备没有出现在列表中	按设备 ID 搜索，确认设备是否连接 MQTT、上报在线状态或遥测。
对话控制没有生效	搜索设备 ID 或请求 ID，查看命令是否下发、设备是否返回响应。
IM 机器人没有回复	按模块或平台名称搜索，查看平台凭证、白名单、消息接收和回复是否正常。
语音没有识别或没有播报	按语音相关模块筛选，查看语音服务、会话和识别结果。
工具或技能没有执行	按工具相关模块筛选，查看工具加载、权限和执行结果。
模型服务返回异常	按 `error` 或模型服务名称搜索，查看请求失败、鉴权失败或超时信息。

下载或分享日志前，先确认日志中是否包含设备 ID、主题、状态值、第三方平台用户 ID 等敏感信息。常见密钥字段会被脱敏，但业务数据仍可能出现在日志消息中。

日志 ​

打开日志页面 ​

本地日志文件 ​

日志记录格式 ​

本地排查命令 ​

查看和筛选记录 ​

日志级别 ​

配置日志 ​

常见排查路径 ​

日志