openclaw-agentlog

OpenClaw Agent 自动存证与 Trace 生命周期管理 Skill。 提供给 OpenClaw Agent 使用，实现： 1. 自动会话存证 - 通过 OpenClaw Hooks 自动记录 agent 活动 2. Trace 生命周期 - 管理 trace 的创建、认领、完成流程 When to a...

Security Scan

The skill claims to be an instruction-only logging/trace helper, but the bundle contains postinstall and install scripts that automatically patch OpenClaw's core dist files, run git/ssh commands, and write into workspaces — these invasive behaviors are disproportionate to the declared metadata and warrant caution.

Purpose & Capability

The declared purpose (agent session logging and trace handoff) aligns with many code behaviors (creating traces, writing sessions.json, capturing tool calls). However the package metadata claimed 'instruction-only' while the bundle includes executable code (postinstall script, install.sh, patch_dist.py) that modifies OpenClaw's global installation and the host filesystem. That degree of modification (hot-patching dist files under global node_modules, restarting services) is more intrusive than the SKILL.md/registry metadata suggests and not clearly justified in the manifest.

Instruction Scope

SKILL.md describes hooks, env vars, and sessions.json usage but does not document the install-time behaviors present in the code: automatic backup/patch of OpenClaw dist files, rsync/ssh synchronization to remote host, and postinstall hot-patching during npm install. The runtime code also executes git commands (git rev-parse), reads/writes files inside a repository's git common-dir (agentlog/sessions.json), and sets environment variables — actions that read/modify user repositories and system files beyond simple logging.

Install Mechanism

There is no declared install spec in registry metadata, yet package.json defines a postinstall script (scripts/postinstall.js) that will run automatically on npm install and attempts to patch global OpenClaw dist directories. Additionally install.sh can rsync to a remote host and run ssh commands and systemctl restarts. These behaviors are high-risk because they modify installed software and system services and run without an explicit curated install declaration in the registry metadata.

Credentials

The skill's documentation references environment variables (AGENTLOG_BACKEND_URL, AGENTLOG_MCP_URL, AGENTLOG_AGENT_ID) but the registry metadata lists no required env vars. The code will use those env vars (and defaults to http://localhost:7892). Because BACKEND_URL is configurable, a maliciously set BACKEND_URL could exfiltrate captured sessions/traces. The skill does not request cloud credentials, but it does read/write git repo files and interact with the filesystem — capabilities that are plausible for trace handoff but should be explicitly declared.

Persistence & Privilege

The plugin registers hooks (normal for a skill) but also includes scripts that modify OpenClaw's core dist JS files and restart the gateway service. Modifying the core dist bundle gives long-lived, system-wide influence over OpenClaw behavior beyond the plugin's own code. Although always:false (not force-enabled), the bundle's ability to patch runtime code and persist changes in global node_modules is a significant privilege and should be treated carefully.

What to consider before installing

This package is suspicious because it claims to be instruction-only but includes code that will automatically patch your OpenClaw installation and workspace files. Before installing: 1) Do not install on production systems without review. 2) Manually inspect postinstall.js, install.sh, and patch_dist.py (they modify files under global openclaw dist, run git commands, SSH/rsync, and restart services). 3) If you need the skill, run it first in an isolated VM/container and back up your OpenClaw installation. 4) Remove or disable the postinstall hook and do not run install.sh until you verify hosts/paths and understand its SSH usage. 5) Ensure any AGENTLOG_BACKEND_URL points to a trusted service (default is localhost; a remote URL could receive captured session data). 6) Prefer obtaining this functionality from a well-known, trusted source or request the author to provide a non-invasive install path and clearer declaration of required env/config and exact filesystem changes.

OpenClaw Agent Log Skill

Overview

本 Skill 是 agentlog-auto 和 openclaw-agent 的合并版本，为 OpenClaw Agent 提供统一的存证和 Trace 管理能力。

Architecture

OpenClaw Agent
      ↓
┌─────────────────────────────────┐
│   openclaw-agentlog Skill      │
├─────────────────────────────────┤
│  ┌───────────────────────────┐  │
│  │   Auto-Logging Module    │  │ ← Hooks 自动记录
│  │  - session_start         │  │
│  │  - before_tool_call      │  │
│  │  - after_tool_call       │  │
│  │  - agent_end             │  │
│  └───────────────────────────┘  │
│  ┌───────────────────────────┐  │
│  │   Trace Handoff Module   │  │ ← 任务交接
│  │  - checkAndClaimTrace    │  │
│  │  - claimTrace            │  │
│  │  - completeTrace         │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘
      ↓
AgentLog Backend (MCP Server)
      ↓
   SQLite DB

Configuration

Environment Variables

AGENTLOG_BACKEND_URL=http://localhost:7892  # Backend API URL
AGENTLOG_MCP_URL=http://localhost:7892      # MCP Server URL
AGENTLOG_AGENT_ID=<agent-name>             # Agent 标识（自动设置）

Optional Configuration

agentlog:
  mcpUrl: "http://localhost:7892"
  autoBindCommit: true      # 自动绑定 Git Commit
  reasoningCapture: true    # 捕获推理过程
  toolCallCapture: true     # 捕获工具调用
  sessionTimeout: 600       # Session 超时(秒)

Hook Events (Auto-Logging)

Hook	Purpose
session_start	创建新 session，生成 session_id
before_tool_call	记录工具调用参数
after_tool_call	记录工具执行结果
agent_end	调用 log_intent 归档
session_end	清理状态

Trace Handoff API

checkAndClaimTrace

启动时检查并认领 pending traces。

import { checkAndClaimTrace } from 'openclaw-agentlog';

const result = await checkAndClaimTrace('/path/to/workspace', 'architect');
// result: { success: true, traceId: '...', sessionId: '...' }

claimTrace

手动认领指定 trace。

import { claimTrace } from 'openclaw-agentlog';

const result = await claimTrace('TRACE_ID', 'architect', '/path/to/workspace');

completeActiveSession

完成当前 session。

import { completeActiveSession } from 'openclaw-agentlog';

await completeActiveSession('/path/to/workspace');

Skill Functions

Function	Description
checkAndClaimTrace	启动时检查并认领 pending traces
extractTraceIdFromMessage	从消息中提取 Trace ID
queryPendingTraces	查询 pending traces
claimTrace	认领 trace
getActiveSession	获取当前 active session
completeActiveSession	完成当前 session

Data Flow

1. Agent 启动
   ↓
2. checkAndClaimTrace() → 查找匹配的 pending trace
   ↓
3. 认领后 → 设置 AGENTLOG_TRACE_ID 环境变量
   ↓
4. Hooks 开始自动记录：
   - session_start → 创建 session
   - before_tool_call → 记录参数
   - after_tool_call → 记录结果
   ↓
5. Agent 完成任务 → agent_end → log_intent()
   ↓
6. completeActiveSession() → 清理

Requirements

• OpenClaw Gateway 运行中
• AgentLog Backend 运行中 (port 7892)
• Git 仓库（用于 commit binding）

Deprecation

本 Skill 替代以下已废弃的 Skills：

• agentlog-auto（与 OpenCode 插件重名）
• openclaw-agent（功能已合并）

Troubleshooting

Backend not reachable:

curl http://localhost:7892/health

Session not binding to commits:

• 确保 git 仓库存在
• 确保在 session 结束后 5 分钟内有 commit

Trace not found:

• 检查 sessions.json 是否存在
• 确认 trace 处于 pending 状态