logs-management

name	logs-management
description	日志管理全链路：实时跟踪、列出、查看、清理与导出日志文件。当需要查看系统日志、跟踪实时输出、排查运行问题或导出日志存档时使用此技能。
tools	gateway
metadata	{"category":"operations","emoji":"📋","tree_id":"system/gateway","tree_group":"system","min_tier":"task_write","intent_priority":10,"intent_keywords":{"zh":["查看日志","看日志","日志管理","跟踪日志","实时日志","日志清理","导出日志","日志排查","logs","log文件","tail日志"],"en":["logs","view logs","tail logs","log management","export logs","clear logs"]},"scene_hint":"查看/跟踪/清理系统日志用此→全面系统诊断用doctor-diagnostics→只看运行状态用crabclaw status"}

日志管理技能

适用场景

用户需要查看、跟踪或管理系统日志时触发。

选择原则

场景	工具/技能
查看/跟踪系统日志	本技能
频道日志	crabclaw channels logs 或本技能（频道过滤）
系统诊断	→ doctor-diagnostics
运行状态查看	→ crabclaw status CLI

一、实时跟踪日志

1.1 通过 Gateway RPC

gateway(action="logs.tail")

返回最近的日志行。

1.2 通过 CLI（更适合持续跟踪）

crabclaw logs follow [--lines 100] [--channel telegram]

参数：

• --lines <n>: 显示最近 n 行（默认全部）
• --channel <name>: 按频道过滤

二、列出日志文件

crabclaw logs list [--json]

返回所有可用日志文件列表，含文件名、大小、最后修改时间。

日志文件位置

平台	默认路径
macOS	/tmp/crabclaw/ (即 os.TempDir()/crabclaw)
Linux	/tmp/crabclaw/
Windows	%TEMP%\crabclaw\

注意: 日志目录可通过运行时配置覆盖。以上为 DefaultLogDir 默认值。

日志文件类型

文件	内容
gateway.log	Gateway 核心运行日志
agent-<id>.log	智能体运行日志
channel-<name>.log	频道操作日志
cron.log	定时任务执行日志
update.log	更新操作日志

三、查看指定日志

crabclaw logs show <filename> [--lines 200]

显示指定日志文件的内容。大文件建议用 --lines 限制输出行数。

四、清理日志

crabclaw logs clear

清除所有日志文件。

注意：此操作不可逆。建议先 logs export 导出存档。

五、导出日志

crabclaw logs export <output-path>

将所有日志合并导出到指定文件，便于分享或归档。output-path 为必填参数。

六、通过智能体工具读取日志

当需要在智能体会话中查看日志时，也可以使用文件系统工具直接读取：

read_file(path="~/.crabclaw/logs/gateway.log")

但建议优先使用 logs.tail RPC，因为它：

• 自动处理日志轮转
• 支持结构化输出
• 不受文件系统权限限制

七、日志级别

日志条目包含级别标记：

级别	说明
DEBUG	详细调试信息（需 --verbose 启用）
INFO	正常操作信息
WARN	警告信息（非致命）
ERROR	错误信息（需关注）

八、常见排查模式

8.1 Gateway 启动失败

crabclaw logs show gateway.log --lines 50

查找 ERROR 或 FATAL 级别条目。

8.2 频道连接问题

crabclaw logs follow --channel <channel-name>

关注 connection, auth, timeout 关键词。

8.3 智能体运行异常

crabclaw logs show agent-<id>.log

查看完整执行轨迹和错误信息。

8.4 定时任务未执行

crabclaw logs show cron.log

确认调度触发和执行结果。

九、CLI 命令对照

CLI 命令	说明
crabclaw logs follow	实时跟踪日志
crabclaw logs follow --lines 100	显示最近 100 行并跟踪
crabclaw logs follow --channel telegram	过滤特定频道
crabclaw logs list	列出日志文件
crabclaw logs list --json	JSON 格式列表
crabclaw logs show <file>	查看指定日志
crabclaw logs clear	清理所有日志
crabclaw logs export <path>	导出日志到指定文件