OpenClaw Integration¶

Pisama integrates with OpenClaw to monitor agent sessions and detect failure modes in OpenClaw-built multi-agent systems.

Setup¶

1. Get a Bearer Token¶

Exchange your API key for a JWT:

curl -X POST https://api.pisama.ai/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "pisama_your_api_key_here"}'

Save the access_token from the response:

export TOKEN="<access_token>"

2. Register an OpenClaw Instance¶

curl -X POST https://api.pisama.ai/api/v1/openclaw/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-openclaw",
    "gateway_url": "http://localhost:18789",
    "api_key": "<your_openclaw_gateway_token>"
  }'

Optional fields: otel_endpoint, otel_enabled (bool), ingestion_mode ("full" or "trace_only").

3. Register Agents¶

Register each OpenClaw agent you want to monitor:

curl -X POST https://api.pisama.ai/api/v1/openclaw/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "<instance_id>",
    "agent_key": "pisama-intel",
    "agent_name": "Pisama Intel",
    "model": "claude-sonnet-4-20250514"
  }'

The response includes a webhook_secret used for signing. Save it.

4. Send Session Data via Webhook¶

Session data is sent to Pisama via a signed webhook. Each request requires HMAC-SHA256 authentication.

Webhook URL: https://api.pisama.ai/api/v1/openclaw/webhook

Required headers:

Signature computation:

import hmac, hashlib, time

timestamp = str(int(time.time()))
message = f"{timestamp}.{request_body}"
signature = "sha256=" + hmac.new(
    webhook_secret.encode(),
    message.encode(),
    hashlib.sha256
).hexdigest()

Payload schema:

{
  "session_id": "uuid",
  "instance_id": "uuid",
  "agent_name": "agent-key",
  "started_at": "ISO8601",
  "finished_at": "ISO8601",
  "status": "completed",
  "message_count": 10,
  "events": [
    {"type": "tool.call", "timestamp": "ISO8601", "data": {"name": "web_search", "input": {}}},
    {"type": "tool.result", "timestamp": "ISO8601", "data": {"name": "web_search", "status": "completed"}},
    {"type": "message.sent", "timestamp": "ISO8601", "data": {"content": "..."}}
  ],
  "elevated_mode": false,
  "sandbox_enabled": true
}

5. Automated Sync (Recommended)¶

OpenClaw stores sessions as JSONL files in ~/.openclaw/agents/<agent>/sessions/. Use the sync script to automatically push completed sessions to Pisama:

# Dry run to see what would be synced
python3 sync_to_pisama.py --dry-run

# Sync all new sessions
python3 sync_to_pisama.py

# Re-sync everything (ignores previous sync state)
python3 sync_to_pisama.py --force

Set up a cron job to sync periodically:

# Every 15 minutes
*/15 * * * * cd /path/to/openclaw-agents && python3 sync_to_pisama.py >> sync.log 2>&1

OpenClaw-Specific Attributes¶

Pisama recognizes OpenClaw OTEL attributes:

Detection Capabilities¶

When monitoring OpenClaw agents, Pisama detects:

• Session loops: Tool call repetition, spawn ping-pong, message loops
• Tool abuse: Excessive calls, redundancy, high error rates, sensitive tool usage
• Elevated privilege risk: Unauthorized escalation, risky operations
• Spawn chain depth: Deep agent chains, circular references, privilege escalation
• Channel mismatch: Format violations, PII exposure, cross-channel routing errors
• Sandbox escape: Unauthorized file, network, code execution, or database access
• Coordination failures: Agent handoff and communication issues
• Persona drift: Agents deviating from their assigned roles
• Loop detection: Agents stuck in repeated action patterns
• Hallucination: Unsupported claims in agent outputs
• Context overflow: Token accumulation across agent turns

API Endpoints¶