---
title: "@prefactor/openclaw-prefactor-plugin"
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

[**Prefactor TypeScript SDK**](../../index.md)

***

[Prefactor TypeScript SDK](../../modules.md) / @prefactor/openclaw-prefactor-plugin

# @prefactor/openclaw-prefactor-plugin

OpenClaw plugin for Prefactor observability. Provides automatic tracing of agent
lifecycle events including sessions, user interactions, agent runs, and tool calls.

## `@prefactor/openclaw-prefactor-plugin` overview

This plugin hooks into OpenClaw's lifecycle events to create a hierarchical span
structure for distributed tracing. The span hierarchy follows:

```
session (24hr lifetime, root span)
  └─ user_interaction (5min idle timeout)
      ├─ user_message (instant, auto-closed)
      ├─ agent_run (child of interaction)
      │   ├─ tool_call (concurrent, children of agent_run)
      │   └─ tool_call
      └─ assistant_response (instant, auto-closed)
```

## Hook handlers

The plugin registers 14 hooks that automatically create and manage spans:

- **Gateway**: `gateway_start`, `gateway_stop`
- **Session**: `session_start`, `session_end`
- **Agent**: `before_agent_start`, `agent_end`
- **Compaction**: `before_compaction`, `after_compaction`
- **Tool**: `before_tool_call`, `after_tool_call`, `tool_result_persist`
- **Message**: `message_received`, `message_sending`, `message_sent`

## Span types

- `openclaw:session` - Root span for the OpenClaw session (24hr lifetime)
- `openclaw:user_interaction` - User interaction context (5min idle timeout)
- `openclaw:user_message` - Inbound user message event
- `openclaw:agent_run` - Agent execution run
- `openclaw:tool_call` - Tool execution (supports concurrent calls)
- `openclaw:assistant_response` - Assistant response event

## Exports

- [Agent](interfaces/Agent.md) - HTTP client for Prefactor API (span CRUD, instance lifecycle)
- [SessionStateManager](interfaces/SessionStateManager.md) - Manages span hierarchy and timeouts per session
- [Logger](interfaces/Logger.md) - Structured logger for plugin diagnostics
- [register](functions/default.md) - Plugin entry point (used by OpenClaw, not imported directly)

## Functions

- [default](functions/default.md)
- [createAgent](functions/createAgent.md)
- [createRiskConfig](functions/createRiskConfig.md)
- [createLogger](functions/createLogger.md)
- [createSessionStateManager](functions/createSessionStateManager.md)
- [getAllSupportedToolDefinitions](functions/getAllSupportedToolDefinitions.md)
- [getToolDefinition](functions/getToolDefinition.md)
- [getToolInputSchema](functions/getToolInputSchema.md)
- [isSupportedTool](functions/isSupportedTool.md)
- [normalizeToolName](functions/normalizeToolName.md)
- [buildToolSpanSchema](functions/buildToolSpanSchema.md)
- [createToolSpanInputs](functions/createToolSpanInputs.md)
- [createToolSpanOutputs](functions/createToolSpanOutputs.md)
- [createToolSpanResultPayload](functions/createToolSpanResultPayload.md)

## Interfaces

- [Agent](interfaces/Agent.md)
- [AgentConfig](interfaces/AgentConfig.md)
- [Logger](interfaces/Logger.md)
- [SessionStateManager](interfaces/SessionStateManager.md)
- [ToolDefinition](interfaces/ToolDefinition.md)

## Type Aliases

- [LogLevel](type-aliases/LogLevel.md)

## Variables

- [agentRunRisk](variables/agentRunRisk.md)
- [agentThinkingRisk](variables/agentThinkingRisk.md)
- [assistantResponseRisk](variables/assistantResponseRisk.md)
- [defaultSpanTypeRiskConfigs](variables/defaultSpanTypeRiskConfigs.md)
- [sessionRisk](variables/sessionRisk.md)
- [toolBrowserRisk](variables/toolBrowserRisk.md)
- [toolEditRisk](variables/toolEditRisk.md)
- [toolExecRisk](variables/toolExecRisk.md)
- [toolReadRisk](variables/toolReadRisk.md)
- [toolRisk](variables/toolRisk.md)
- [toolWebFetchRisk](variables/toolWebFetchRisk.md)
- [toolWebSearchRisk](variables/toolWebSearchRisk.md)
- [toolWriteRisk](variables/toolWriteRisk.md)
- [userInteractionRisk](variables/userInteractionRisk.md)
- [userMessageRisk](variables/userMessageRisk.md)
- [SUPPORTED\_TOOL\_DEFINITIONS](variables/SUPPORTED_TOOL_DEFINITIONS.md)
- [TOOL\_ALIAS\_MAP](variables/TOOL_ALIAS_MAP.md)
- [GENERIC\_OBJECT\_SCHEMA](variables/GENERIC_OBJECT_SCHEMA.md)