@posthog/openclaw

PostHog LLM Analytics plugin for OpenClaw. Captures LLM generations, tool executions, and conversation traces, sending them to PostHog as structured $ai_* events for the LLM Analytics dashboard.

Screen.Recording.2026-02-27.at.12.43.06.mov

Install

openclaw plugins install @posthog/openclaw

Configuration

Add to your openclaw.json (or openclaw.yaml):

{
    "plugins": {
        "entries": {
            "posthog": {
                "enabled": true,
                "config": {
                    "apiKey": "phc_your_project_key",
                    "host": "https://us.i.posthog.com",
                    "privacyMode": false,
                    "traceGrouping": "message",
                    "sessionWindowMinutes": 60,
                },
            },
        },
    },
    "diagnostics": {
        "enabled": true,
    },
}

Options

Option	Type	Default	Description
apiKey	string	(required)	Your PostHog project API key
host	string	https://us.i.posthog.com	PostHog instance URL
privacyMode	boolean	false	When enabled, LLM input/output content is not sent to PostHog
traceGrouping	"message" | "session"	"message"	Trace grouping mode. "message": one trace per runId. "session": group all generations in a session into one trace
sessionWindowMinutes	number	60	Minutes of inactivity before starting a new session window. Applies to both trace grouping modes
enabled	boolean	true	Enable or disable the plugin

Note: diagnostics.enabled must be true in your OpenClaw config for trace-level events ($ai_trace) to be captured.

What gets captured

$ai_generation

Captured on every LLM call (correlated llm_input + llm_output hooks).

Property	Description
$ai_model	Model name (e.g. gpt-4o, claude-3)
$ai_provider	Provider name (e.g. openai, anthropic)
$ai_latency	Request duration in seconds
$ai_input_tokens	Input token count
$ai_output_tokens	Output token count
$ai_total_cost_usd	Total cost in USD
$ai_input_cost_usd	Input cost in USD
$ai_output_cost_usd	Output cost in USD
$ai_stop_reason	Why generation stopped (stop, length, tool_calls, error)
$ai_is_error	Whether the generation errored
$ai_error	Error message (if any)
$ai_input	Input messages in OpenAI format (redacted in privacy mode)
$ai_output_choices	Output choices (redacted in privacy mode)
$ai_trace_id	Trace ID for hierarchical grouping
$ai_span_id	Span ID for this generation
$ai_session_id	Session identifier
$ai_channel	Message channel (e.g. telegram, slack)
$ai_agent_id	Agent identifier
cache_read_input_tokens	Cache read token count
cache_creation_input_tokens	Cache creation token count

$ai_span

Captured for each tool call (after_tool_call hook).

Property	Description
$ai_span_name	Tool name
$ai_latency	Tool execution duration in seconds
$ai_is_error	Whether the tool call errored
$ai_error	Error message (if any)
$ai_input_state	Tool input parameters (redacted in privacy mode)
$ai_output_state	Tool output result (redacted in privacy mode)
$ai_trace_id	Trace ID
$ai_span_id	Span ID for this tool call
$ai_parent_id	Parent generation span ID

$ai_trace

Captured when a message cycle completes (message.processed diagnostic event).

Property	Description
$ai_trace_id	Trace ID
$ai_session_id	Session identifier
$ai_latency	Total message cycle duration in seconds
$ai_total_input_tokens	Accumulated input tokens across all generations in the trace
$ai_total_output_tokens	Accumulated output tokens across all generations in the trace
$ai_is_error	Whether the message cycle errored
$ai_error	Error message (if any)
$ai_channel	Message channel

Privacy

With privacyMode: true, no message content, prompts, or tool parameters are sent to PostHog. Token counts, latency, model info, and error status are always captured.

Development

pnpm install
pnpm test
pnpm typecheck
pnpm lint

Local testing with OpenClaw

To test the plugin locally against a running OpenClaw gateway, use plugins.load.paths to point OpenClaw at your local checkout:

// ~/.openclaw/openclaw.json
{
    "plugins": {
        "load": {
            "paths": ["/path/to/posthog-openclaw"],
        },
        "entries": {
            "posthog": {
                "enabled": true,
                "config": {
                    "apiKey": "phc_your_project_key",
                    "host": "https://us.i.posthog.com",
                    "privacyMode": false,
                },
            },
        },
    },
    "diagnostics": { "enabled": true },
}

Then start the gateway:

cd /path/to/openclaw
pnpm install && pnpm build
node openclaw.mjs gateway --force --allow-unconfigured

Open WebChat at http://127.0.0.1:18789/__openclaw__/canvas/ and send a message. Events will appear in your PostHog project under LLM Analytics.

Note: The config entry key must be "posthog" (matching the id field in openclaw.plugin.json), not the npm package name.

License

MIT