# 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` 一致）：

```text
%(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` 即可。