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

规范目标：同一用户工作区下一份按日轮转的主日志，行内带 技能标识 与 trace_id，便于跨技能排查。

目录与文件

统一日志目录（与技能数据目录无关，不按 skill 分子目录）：
- {JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/
主日志文件（默认）：
- {...}/logs/jiangchang.log（午夜轮转，历史带日期后缀，由 TimedRotatingFileHandler 管理）
覆盖主日志绝对路径（可选）：
- JIANGCHANG_LOG_FILE

实现源码以 jiangchang-platform-kit/sdk/jiangchang_skill_core/unified_logging.py 为准；各技能 scripts/jiangchang_skill_core/unified_logging.py 为发布用副本，修改后请同步各技能。

数据根与用户 id 的解析与本地 CLI 注入见同目录 runtime_env.py（get_data_root / get_user_id / apply_cli_local_defaults）；新技能应在 main.py 最早阶段调用 apply_cli_local_defaults()（在 import 业务包之前）。

轮转与编码

TimedRotatingFileHandler，when=midnight，保留份数默认 30，可用 JIANGCHANG_LOG_BACKUP_COUNT 覆盖（1～365）。
编码 UTF-8。
目录在首次写日志前创建（exist_ok=True）。

日志格式（行文本）

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

datefmt：%Y-%m-%dT%H:%M:%S（本地时间）
skill_slug：与 SKILL.md 中 metadata.openclaw.slug 一致（如 account-manager）
name：分层 logger，如 openclaw.skill.account_manager、openclaw.skill.account_manager.login_child
trace_id：调用链 ID，见下节

调用链（trace）

环境变量 JIANGCHANG_TRACE_ID：同一 shell/进程树内子进程默认继承；跨技能 subprocess 时父进程应使用 subprocess_env_with_trace() 构造 env，保证子进程沿用同一 trace。
若未设置，各技能在 setup_skill_logging 时会生成 12 位 hex 并写入环境，供后续子进程继承。

Logger 命名

主 logger：openclaw.skill.<slug_下划线>（如 openclaw.skill.content_manager）
子进程专用 logger：如 openclaw.skill.account_manager.login_child，仍写入同一主日志文件（FileHandler 追加，格式与主进程一致）

环境变量

变量	说明
`JIANGCHANG_DATA_ROOT`	数据根
`JIANGCHANG_USER_ID`	用户/工作区 id，默认 `_anon`
`JIANGCHANG_LOG_LEVEL`	默认 `INFO`
`JIANGCHANG_LOG_TO_STDERR`	`1`/`true` 时 WARNING+ 同时打 stderr
`JIANGCHANG_LOG_FILE`	覆盖主日志文件绝对路径
`JIANGCHANG_LOG_BACKUP_COUNT`	轮转保留份数，默认 `30`
`JIANGCHANG_TRACE_ID`	可选；由运行时注入以串联调用链

技能侧接入（最少改动）

保证 scripts/jiangchang_skill_core/ 与平台 kit 中实现保持同步。
main.py 将 scripts 目录加入 sys.path（若尚未加入）。
CLI main 早期调用：setup_skill_logging(SKILL_SLUG, LOG_LOGGER_NAME)。
业务代码：get_skill_logger() 打日志。
拉起子技能 CLI 时：subprocess.run(..., env=subprocess_env_with_trace())。

级别与敏感信息

INFO：子命令入口、成功结束（含关键业务 id）。
WARNING：可恢复问题、校验失败。
ERROR：不可继续的异常。
DEBUG：高频细节；默认关闭。
日志可能含路径、账号信息，注意权限与留存。

参考实现

jiangchang-platform-kit/sdk/jiangchang_skill_core/unified_logging.py
account-manager / content-manager / llm-manager 的 util/logging_config.py（re-export）与 CLI 入口

3.7 KiB Raw Permalink Blame History Unescape Escape