skill-template/docs/LOGGING.md

OpenClaw 技能日志约定（各技能统一）

本文档为规范：新技能与 account-manager 等现有技能应遵循同一套路径、格式与环境变量，便于排查与运维。

目录与文件

• 日志目录与技能数据目录同级：
  • {JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/logs/
• 主日志文件（示例）：
  • {...}/account-manager/logs/account-manager.log
• skill_slug 与 SKILL.md 中 metadata.openclaw.slug 一致。

轮转与编码

• 使用 Python logging.handlers.TimedRotatingFileHandler，when=midnight，保留约 30 个历史文件（可按技能调整 backupCount）。
• 文件编码 UTF-8。
• 首次写日志前创建 logs/ 目录（exist_ok=True）。

日志格式（行文本）

推荐单行格式（与 account-manager 一致）：

%(asctime)s | %(levelname)-8s | %(name)s | %(message)s

datefmt 建议：%Y-%m-%dT%H:%M:%S（本地时间）。

Logger 命名

• 使用分层命名，便于按前缀过滤，例如：openclaw.skill.account_manager。
• 子进程若需写同一文件，可使用子 logger：openclaw.skill.account_manager.login_child，仍追加到同一日志文件（logging.FileHandler(..., encoding='utf-8') 追加模式）。

环境变量（全局）

变量	说明
JIANGCHANG_LOG_LEVEL	默认 INFO；调试轮询等可设 DEBUG。
JIANGCHANG_LOG_TO_STDERR	设为 1/true 时，将 WARNING 及以上同时输出到 stderr（不替代文件）。
JIANGCHANG_{SKILL}_LOG_FILE	可选，覆盖该技能主日志绝对路径（需自行保证目录可写）。account-manager 使用 JIANGCHANG_ACCOUNT_MANAGER_LOG_FILE。

级别与内容建议

• INFO：子命令入口、成功结束（含关键业务 id，避免仅打「成功」）。
• WARNING：可恢复问题、校验失败、登录未检测到。
• ERROR：依赖缺失、不可继续的异常。
• DEBUG：高频轮询状态（URL 列表、规则命中说明）；默认关闭。
• 日志中可能含 手机号、路径等敏感信息，注意文件权限与留存策略；必要时仅记录后四位或 hash（按合规要求）。

与标准输出的关系

• 面向用户的 print（成功提示、ERROR: 前缀）可保留；诊断细节以日志为准。
• 登录失败等场景可在终端提示日志文件路径，便于用户打开 *.log。

参考实现

• account-manager/scripts/main.py：get_skill_logs_dir、get_skill_logger、get_skill_log_file_path、login 子进程内 FileHandler 追加同一文件。

新技能可复制上述函数结构，替换 SKILL_SLUG 与 LOG_LOGGER_NAME 即可。