name: observer description: > Agent self-evolution observer skill. Collects daily Agent session data and Gateway log anomalies, analyzes patterns, updates the .learnings/ ledger, generates a human-readable "daily iteration plan", and announces to the observer channel. Triggers: (1) daily cron (2) user request (3) urgent anomaly analysis

Observer — Agent Self-Evolution Observer

Purpose

Observer watches the entire AI team's daily operations — execution quality and infrastructure stability — and surfaces actionable improvement suggestions. It never acts autonomously; it only observes, records, and recommends.

Two data sources

Source 1: Agent Session Data

Use sessions_list to pull all active sessions, then sessions_history(sessionKey) for details.

Focus on:

• Session ended with error (isError)
• Tool call failures or retries
• Execution time > 60 seconds
• Model fallback triggered

Source 2: Gateway Logs

Scan local log files:

• {{OPENCLAW_HOME}}/logs/gateway.err.log — error log
• {{OPENCLAW_HOME}}/logs/gateway.log — normal requests (flag > 2000ms)
• {{OPENCLAW_HOME}}/logs/commands.log — command delivery log

Use exec + grep to scan for these patterns:

Count occurrences per pattern.

Execution flow (6 steps)

Step 1: Collect session data

sessions_list → get today's session list
→ sessions_history for each session
→ store structured data in .learnings/observer/raw/YYYY-MM-DD-sessions.jsonl

Step 2: Scan gateway logs

exec: grep -c to count each anomaly pattern
exec: grep to extract context (2 lines before/after)
→ store in .learnings/observer/raw/YYYY-MM-DD-gateway.jsonl

Step 3: Update .learnings/ ledger

Read .learnings/observer/index.json.

For each anomaly:

1. Check if key exists in recurrenceMap
2. Exists → update lastSeen and count
3. New → add entry
4. If root cause is clear → write markdown file to appropriate category directory

Step 4: Evaluate promote candidates

Check recurrenceMap:

• Key with count >= 7 and recurring within 7 days → flag as "suggest promote"
• Add to iteration plan's "needs human decision" section

Step 5: Generate daily iteration plan

Use references/plan-template.md format, fill with real data.

Output path: .learnings/observer/plans/YYYY-MM-DD-iteration-plan.md

Required 6 sections:

1. Today's execution overview (session stats)
2. Infrastructure anomalies (gateway analysis)
3. Agent execution anomalies (session analysis)
4. What to change today (max 3-5 items, with rationale and expected effect)
5. What NOT to change today (with rationale)
6. Needs human decision (list explicitly)

Step 6: Announce to observer channel

Generate a channel summary (≤ 20 lines) and send:

message(action=send, target={{OBSERVER_CHANNEL_ID}}, message=<summary>)

Format:

📊 **Observer Daily — YYYY-MM-DD**

**Infrastructure**: 🟢/🟡/🔴 one-line summary
**Agent execution**: 🟢/🟡/🔴 one-line summary

**Suggested changes today**:
1. suggestion 1
2. suggestion 2

**Needs decision**: yes/no (brief description)

*Full plan: .learnings/observer/plans/YYYY-MM-DD-iteration-plan.md*

.learnings/ directory structure

.learnings/
  observer/
    errors/          ← Agent execution failures / timeouts / tool call errors
    infrastructure/  ← Gateway / provider / plugin / command delivery errors
    corrections/     ← User corrections / preference updates
    insights/        ← Observed patterns / best practices
    promoted/        ← Learnings promoted to long-term rules
    plans/           ← Daily iteration plans (human-readable)
    raw/             ← Raw session / gateway structured summaries
    index.json       ← Recurrence counts / search index

See references/index-schema.md for the full schema. See references/plan-template.md for the plan format.

Learning file template

Each learning is a markdown file:

# Error: {{title}}

**Date:** {{DATE}}
**Type:** {{error_type}}
**Category:** errors / infrastructure / corrections / insights
**Severity:** high / medium / low
**Recurrence Count:** {{count}} (last 7 days)

## What Happened
{{description}}

## Context
- Agent: {{agent}} (if applicable)
- Sessions: {{session_ids}} (if applicable)
- Common Pattern: {{pattern}}

## Root Cause
{{root_cause}}

## Prevention
1. {{prevention_1}}
2. {{prevention_2}}

## Status
- [ ] Pending review
- [ ] Suggested (see iteration plan)
- [ ] Executed
- [ ] Promoted

Three-level safety mechanism

Hard rule: Never autonomously modify any skill / cron / openclaw.json. Only observe, record, suggest.

Setup

1. Configure {{OBSERVER_CHANNEL_ID}} in your cron prompt with your actual observer channel ID
2. Set {{OPENCLAW_HOME}} to your OpenClaw home directory (default: ~/.openclaw)
3. Create the .learnings/observer/ directory structure (or let the skill create it on first run)
4. Add the cron job using prompts/cron/observer-daily-0001.md as a template

Constraints

• Never modify skill / cron / openclaw.json without explicit human confirmation
• Never delete learning files (archive only)
• Raw logs in .learnings/raw/ auto-purge after 7 days
• All git commits must use [observer] prefix
• P0 frozen layer (identity, authority, hard rules) is never touched

Completion checklist

After each Observer run, confirm:

1. .learnings/observer/plans/YYYY-MM-DD-iteration-plan.md generated
2. .learnings/observer/index.json updated
3. .learnings/observer/raw/ written for today
4. Observer channel announced
5. Git commit made (if files changed)