initial: OPENCLAW_TRICKS.md — configuration recipes for OpenClaw agents
This commit is contained in:
user
commit
e5f596816c
854
OPENCLAW_TRICKS.md
Normal file
854
OPENCLAW_TRICKS.md
Normal file
@ -0,0 +1,854 @@
|
||||
# OPENCLAW_TRICKS.md — Configuration Recipes for OpenClaw Agents
|
||||
|
||||
A collection of tested patterns, prompts, and file structures for configuring
|
||||
an OpenClaw agent as a proactive personal assistant. These are extracted from a
|
||||
production setup that's been running since early 2026.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Workspace Bootstrapping](#workspace-bootstrapping)
|
||||
2. [Daily Context — The State File](#daily-context--the-state-file)
|
||||
3. [Sitrep (Situation Report)](#sitrep-situation-report)
|
||||
4. [Sleep Tracking](#sleep-tracking)
|
||||
5. [Location & Timezone Tracking](#location--timezone-tracking)
|
||||
6. [Medication Tracking](#medication-tracking)
|
||||
7. [Flight & Travel Logging](#flight--travel-logging)
|
||||
8. [Landing Checklist](#landing-checklist)
|
||||
9. [Memory Architecture](#memory-architecture)
|
||||
10. [Heartbeat Configuration](#heartbeat-configuration)
|
||||
11. [Gitea Integration & Notification Polling](#gitea-integration--notification-polling)
|
||||
12. [Sub-Agent Management](#sub-agent-management)
|
||||
13. [Urgent Notifications via ntfy](#urgent-notifications-via-ntfy)
|
||||
14. [Group Chat Behavior](#group-chat-behavior)
|
||||
15. [Cron vs Heartbeat — When to Use Each](#cron-vs-heartbeat)
|
||||
16. [Requirement Capture](#requirement-capture)
|
||||
|
||||
---
|
||||
|
||||
## Workspace Bootstrapping
|
||||
|
||||
Your workspace is the agent's home directory. Core files:
|
||||
|
||||
```
|
||||
workspace/
|
||||
├── AGENTS.md # Responsibilities, rules, procedures
|
||||
├── SOUL.md # Personality, tone, values
|
||||
├── USER.md # Info about your human (name, tz, prefs)
|
||||
├── IDENTITY.md # Agent's own identity
|
||||
├── HEARTBEAT.md # What to check on heartbeat polls
|
||||
├── MEMORY.md # Curated long-term memory
|
||||
├── TOOLS.md # Environment-specific notes (hosts, keys, devices)
|
||||
└── memory/
|
||||
├── daily-context.json
|
||||
├── YYYY-MM-DD.md # Daily raw notes
|
||||
├── sleep-log.csv
|
||||
├── location-log.csv
|
||||
├── flight-log.csv
|
||||
├── medications-log-YYYY-MM.csv
|
||||
├── medications-instructions.md
|
||||
├── landing-checklist.md
|
||||
├── checklist-*.md # Various operational checklists
|
||||
└── heartbeat-state.json
|
||||
```
|
||||
|
||||
### Session startup prompt (put in AGENTS.md):
|
||||
|
||||
```markdown
|
||||
## Every Session
|
||||
|
||||
Before doing anything else:
|
||||
|
||||
1. Read `SOUL.md` — this is who you are
|
||||
2. Read `USER.md` — this is who you're helping
|
||||
3. Read `memory/daily-context.json` — current state (location, timezone, sleep, meds)
|
||||
4. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
|
||||
5. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`
|
||||
|
||||
Don't ask permission. Just do it.
|
||||
```
|
||||
|
||||
This ensures the agent always has context on wake. The key insight is that the
|
||||
agent wakes up fresh every session — files ARE its memory.
|
||||
|
||||
---
|
||||
|
||||
## Daily Context — The State File
|
||||
|
||||
This is the single most important file. It's a JSON blob that every session
|
||||
reads on every message. It tracks the current state of your human.
|
||||
|
||||
### Schema: `memory/daily-context.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"isSleeping": false,
|
||||
"lastKnownWakeTime": "2026-02-28T12:30:00+07:00",
|
||||
"predictedSleepTime": "2026-03-01T05:30:00+07:00",
|
||||
"predictedWakeTime": "2026-03-01T12:45:00+07:00",
|
||||
"hasTakenDailyMedsToday": false,
|
||||
"dailyMedsTimestamp": "2026-02-27T11:43:00+07:00",
|
||||
"lastCaffeineTimestamp": null,
|
||||
"currentLocation": "City (IATA)",
|
||||
"currentTimezone": "Asia/Bangkok",
|
||||
"currentLodging": "Hotel Name",
|
||||
"travelLeg": "Description of current travel phase",
|
||||
"nearestAirport": "ICAO code",
|
||||
"lastMessageFromUser": "2026-02-28T05:20:00+07:00",
|
||||
"lastMessageChannel": "mattermost",
|
||||
"isAvailable": true,
|
||||
"lastUpdated": "2026-02-28T06:00:00+07:00",
|
||||
"lastSleep": "actual: 2026-02-28 05:15-12:30 ICT (~7h15m). Stable pattern."
|
||||
}
|
||||
```
|
||||
|
||||
### AGENTS.md prompt:
|
||||
|
||||
```markdown
|
||||
## Daily Context
|
||||
|
||||
Stored in `memory/daily-context.json`. All agents: review on every
|
||||
conversation/message to detect if any state has changed. Update the JSON file
|
||||
directly.
|
||||
```
|
||||
|
||||
### Why it works:
|
||||
- Every session reads this first, so the agent always knows where you are
|
||||
- Sleep predictions help the agent decide when to alert vs stay quiet
|
||||
- Medication timestamps enable overdue detection
|
||||
- Timezone field means the agent always converts times correctly
|
||||
- `lastMessageFromUser` lets the agent infer activity gaps = sleep
|
||||
|
||||
---
|
||||
|
||||
## Sitrep (Situation Report)
|
||||
|
||||
The sitrep is triggered by a keyword (e.g. "sitrep") and produces a concise
|
||||
status briefing. The key design feature is that the agent can **add sections
|
||||
dynamically** based on what it thinks you should know.
|
||||
|
||||
### AGENTS.md prompt:
|
||||
|
||||
```markdown
|
||||
### Sitrep (Situation Report)
|
||||
|
||||
When the user says "sitrep", provide a concise summary covering:
|
||||
|
||||
1. **Daily meds** — taken today or not
|
||||
2. **Interval meds** — any due/overdue or upcoming in next 48h.
|
||||
ALWAYS include "X days from now" countdown. ALWAYS include day of week.
|
||||
3. **Open issues assigned to me** — count
|
||||
4. **Open issues assigned to user** — count + brief summary
|
||||
5. **Upcoming travel** — flights in next 72h with times/airports.
|
||||
ALWAYS also include the next known flight even if beyond 72h.
|
||||
6. **Upcoming appointments** — next 48h
|
||||
7. **Todo list** — overdue, due today, due tomorrow (separate categories)
|
||||
8. **Unbooked travel** — flights that need booking. Flag deadlines.
|
||||
9. **Sleep conflicts** — appointments in next 48h that fall within
|
||||
predicted sleep window
|
||||
10. **Sleep** — one-line summary of last sleep + drift trend + concerns
|
||||
11. **Unanswered questions** — questions the agent asked that haven't
|
||||
been answered
|
||||
12. **Weather alerts** — only if significant or extreme. Use METAR from
|
||||
aviationweather.gov. Omit if nothing notable.
|
||||
13. **Overdue reminders** — anything pending
|
||||
14. **Open projects** — one-line status per project
|
||||
|
||||
Before generating a sitrep, review the last 3 days of daily memory files
|
||||
for context. **If anything notable isn't covered by the items above —
|
||||
recent lessons, pending decisions, things you think the user should know
|
||||
about — add additional sections as needed.**
|
||||
|
||||
Omit any item that is "none" or zero. Keep it scannable. Use bullet
|
||||
points, not prose. Only surface things the user might not know about or
|
||||
needs to act on.
|
||||
```
|
||||
|
||||
### Key design decisions:
|
||||
|
||||
- **"Add additional sections as needed"** — this is the magic line. It lets the
|
||||
agent surface things you didn't think to ask about. If there's a pending
|
||||
decision from 2 days ago, or a lesson from a recent mistake, it'll include it.
|
||||
- **"Omit any item that is none or zero"** — keeps it clean. No "Overdue
|
||||
reminders: none" clutter.
|
||||
- **Relative times** ("4 days from now, Tuesday") are more useful than bare
|
||||
dates
|
||||
- **Review last 3 days** ensures the agent has recent context, not just today
|
||||
- The sitrep pulls from multiple data sources (daily context, calendars, issue
|
||||
trackers, memory files) — it's a dashboard in prose form
|
||||
|
||||
### Time display tip:
|
||||
|
||||
```markdown
|
||||
Include current time in local timezone, UTC, and any other relevant timezone
|
||||
at the top.
|
||||
```
|
||||
|
||||
This anchors the reader and makes all the relative times unambiguous.
|
||||
|
||||
---
|
||||
|
||||
## Sleep Tracking
|
||||
|
||||
The agent infers sleep from message activity gaps, not from explicit "I'm going
|
||||
to sleep" statements (though those help too).
|
||||
|
||||
### File: `memory/sleep-log.csv`
|
||||
|
||||
```csv
|
||||
Date,SleepTime,WakeTime,TimeZone,Duration,Status,Notes
|
||||
2026-02-07,08:30,15:30,America/Los_Angeles,7h00m,actual,Approximate times
|
||||
2026-02-08,~12:00,~15:30,America/Los_Angeles,~3h30m,actual,Short sleep
|
||||
```
|
||||
|
||||
### AGENTS.md prompt:
|
||||
|
||||
```markdown
|
||||
### Sleep Tracking
|
||||
|
||||
- **`memory/sleep-log.csv`** — columns: Date, SleepTime, WakeTime,
|
||||
TimeZone, Duration, Status, Notes
|
||||
- Infer sleep/wake times from message activity and explicit statements
|
||||
- User's sleep pattern drifts later each day; typical duration 4–8 hours
|
||||
- Update daily-context.json isSleeping field accordingly
|
||||
- **On every message from user:** if there was a communication gap
|
||||
overlapping predicted sleep time, infer a sleep window (sleep start =
|
||||
last activity before gap, wake = first activity after gap). Activity
|
||||
includes direct messages, git commits/comments, scheduled flight
|
||||
departures, and any other observable actions — not just chat messages.
|
||||
Log based on observed gaps only, never from mathematical predictions.
|
||||
```
|
||||
|
||||
### Daily context fields for sleep:
|
||||
|
||||
```json
|
||||
{
|
||||
"isSleeping": false,
|
||||
"lastKnownWakeTime": "2026-02-28T12:30:00+07:00",
|
||||
"predictedSleepTime": "2026-03-01T05:30:00+07:00",
|
||||
"predictedWakeTime": "2026-03-01T12:45:00+07:00",
|
||||
"lastSleep": "actual: 2026-02-28 05:15-12:30 ICT (~7h15m). Stable pattern."
|
||||
}
|
||||
```
|
||||
|
||||
### How prediction works:
|
||||
|
||||
The agent observes the pattern drift (e.g., sleeping 30min later each day) and
|
||||
extrapolates. Predictions are updated after each actual observation. The agent
|
||||
uses predictions to:
|
||||
|
||||
- Avoid sending non-urgent alerts during predicted sleep
|
||||
- Flag sleep conflicts with upcoming appointments in sitreps
|
||||
- Factor caffeine intake into predictions (caffeine = 5-6h minimum awake)
|
||||
|
||||
### Caffeine integration:
|
||||
|
||||
```json
|
||||
{
|
||||
"lastCaffeineTimestamp": "2026-02-10T00:45:00-08:00"
|
||||
}
|
||||
```
|
||||
|
||||
Track caffeine in daily-context.json. If the user has caffeine, adjust sleep
|
||||
prediction forward by their typical caffeine-to-sleep duration.
|
||||
|
||||
---
|
||||
|
||||
## Location & Timezone Tracking
|
||||
|
||||
The agent always knows where you are and adjusts all time displays accordingly.
|
||||
|
||||
### File: `memory/location-log.csv`
|
||||
|
||||
```csv
|
||||
Date,City,Country,Timezone
|
||||
2026-02-08,Las Vegas,US,America/Los_Angeles
|
||||
2026-02-11,Berlin,DE,Europe/Berlin
|
||||
2026-02-18,Bangkok,TH,Asia/Bangkok
|
||||
```
|
||||
|
||||
### Timezone rules (AGENTS.md):
|
||||
|
||||
```markdown
|
||||
## Timezone/Time Rules
|
||||
|
||||
- System clock is PST. User's TZ is in daily-context.json — always convert.
|
||||
- "Today"/"tomorrow" = user's local TZ, not system clock.
|
||||
- Never state times without explicit conversion.
|
||||
- When logging medication times, always use the user's current timezone.
|
||||
```
|
||||
|
||||
### Why this matters:
|
||||
|
||||
OpenClaw runs on a server (probably in a fixed timezone). Your human travels.
|
||||
Without explicit timezone tracking:
|
||||
- "Take your meds" fires at 3am local time
|
||||
- "Today" means the wrong day
|
||||
- Sleep predictions are off by hours
|
||||
- Calendar events show wrong times
|
||||
|
||||
The daily-context.json `currentTimezone` field is the single source of truth.
|
||||
Everything else derives from it.
|
||||
|
||||
---
|
||||
|
||||
## Medication Tracking
|
||||
|
||||
This is a safety-critical system. The design prioritizes never missing a dose
|
||||
and never double-dosing over convenience.
|
||||
|
||||
### Files:
|
||||
|
||||
- `memory/medications-instructions.md` — the authoritative medication list,
|
||||
dosages, schedules, and safety rules
|
||||
- `memory/medications-log-YYYY-MM.csv` — one row per ingestion, split by month
|
||||
- `memory/checklist-medications.md` — pre-action verification checklist
|
||||
|
||||
### Log format: `memory/medications-log-YYYY-MM.csv`
|
||||
|
||||
```csv
|
||||
Date,Time,TimeZone,Medication,Dosage
|
||||
2026-02-27,11:43,Asia/Bangkok,Metoprolol,50 mg
|
||||
2026-02-27,11:43,Asia/Bangkok,Omeprazole,40 mg
|
||||
2026-02-27,11:43,Asia/Bangkok,Aspirin,162 mg
|
||||
```
|
||||
|
||||
### Instructions file structure (`memory/medications-instructions.md`):
|
||||
|
||||
```markdown
|
||||
# Medication Instructions
|
||||
|
||||
## General Rules
|
||||
|
||||
- Maintain cumulative CSV logs split by month as the authoritative record
|
||||
- CSV columns (fixed order): Date,Time,TimeZone,Medication,Dosage
|
||||
- "Today"/"yesterday"/"tomorrow" always mean relative to currentTimezone
|
||||
in daily-context.json — NEVER relative to system clock
|
||||
- Always spell medication names correctly; silently correct transcription errors
|
||||
|
||||
## Daily Medications
|
||||
|
||||
One batch per calendar day unless explicitly confirmed otherwise. "Log my
|
||||
daily meds" = log each as a separate row.
|
||||
|
||||
**CRITICAL: Never trust hasTakenDailyMedsToday without verifying
|
||||
dailyMedsTimestamp.**
|
||||
|
||||
- Resolve the current date in user's currentTimezone FIRST
|
||||
- Check if dailyMedsTimestamp falls on THAT date in THAT timezone
|
||||
- If the timestamp is from a previous calendar day, meds are NOT taken today
|
||||
regardless of the boolean
|
||||
|
||||
**Ideal dosing window:** every 24h ±4h. Hard minimum: 14h between doses.
|
||||
|
||||
| Medication | Dosage |
|
||||
| ------------ | ------ |
|
||||
| (your meds) | (dose) |
|
||||
|
||||
## Interval-Based Medications
|
||||
|
||||
Scheduling anchored to last actual dose, NOT intended dates.
|
||||
|
||||
| Medication | Dosage | Interval |
|
||||
| ---------- | ------ | ------------ |
|
||||
| (med name) | (dose) | Every X days |
|
||||
|
||||
**Missed dose rules:**
|
||||
- If missed, next dose date is unknown until the missed dose is taken and logged
|
||||
- Interval restarts from actual ingestion timestamp
|
||||
- Missed doses block future scheduling
|
||||
|
||||
## Safety Rules (HIGHEST PRIORITY)
|
||||
|
||||
1. Always triple-check before instructing any medication:
|
||||
- Last actual dose taken
|
||||
- Required dosing interval
|
||||
- Current eligibility without overdose risk
|
||||
2. If any ambiguity exists, **do not instruct dosing**
|
||||
3. Immediately block logging if same-day duplicate daily-med batch or other
|
||||
overdose pattern appears
|
||||
4. Require explicit confirmation in any overdose-risk scenario
|
||||
```
|
||||
|
||||
### Verification checklist (`memory/checklist-medications.md`):
|
||||
|
||||
```markdown
|
||||
# Medications Checklist
|
||||
|
||||
## Before reporting medication status
|
||||
|
||||
1. Check medications-log-YYYY-MM.csv for actual entries, not dailyMedsTimestamp
|
||||
2. Verify dailyMedsTimestamp is from today in user's timezone (not system clock)
|
||||
3. Cross-reference medications-instructions.md for what's due
|
||||
|
||||
## Before sending medication reminders
|
||||
|
||||
1. Confirm current time in user's timezone
|
||||
2. Check if already taken today (verify against CSV, not boolean)
|
||||
3. For interval meds: calculate days since last dose from CSV
|
||||
4. Never send PII (medication names) via public notification channels
|
||||
```
|
||||
|
||||
### Overdue escalation:
|
||||
|
||||
```markdown
|
||||
**CRITICAL: If daily meds are >26h since last dose, escalate aggressively.**
|
||||
Use urgent notification channel if chat messages go unacknowledged.
|
||||
Do not let this slide silently. Always include hours since last dose in
|
||||
reminders (e.g. "daily meds overdue — last dose was 27h ago").
|
||||
```
|
||||
|
||||
### Why the double-check on the boolean:
|
||||
|
||||
The daily-context.json has a `hasTakenDailyMedsToday` boolean AND a
|
||||
`dailyMedsTimestamp`. A midnight-reset cron flips the boolean to false. But
|
||||
if the user is in a timezone ahead of the server, the boolean may reset
|
||||
before their actual "today" ends — or after it began. The rule: **always
|
||||
verify the timestamp falls on today's date in the user's timezone.** The
|
||||
boolean is a convenience hint, not the source of truth.
|
||||
|
||||
---
|
||||
|
||||
## Flight & Travel Logging
|
||||
|
||||
### Files:
|
||||
|
||||
- `memory/flight-log.csv` — one row per flight segment
|
||||
- `memory/location-log.csv` — one row per calendar day
|
||||
- `memory/travel.md` — upcoming travel plans, booking status
|
||||
- `memory/checklist-flights.md` — pre-action checklist
|
||||
|
||||
### Flight log format:
|
||||
|
||||
```csv
|
||||
Date,FlightNumber,Origin,Destination,Duration,Alliance
|
||||
2026-02-10,DL9670,LAS,AMS,10h10m,SkyTeam
|
||||
2026-02-10,KL1856,AMS,BER,1h25m,SkyTeam
|
||||
```
|
||||
|
||||
### Flight prep blocks (put in HEARTBEAT.md):
|
||||
|
||||
```markdown
|
||||
## Flight Prep Blocks (daily)
|
||||
|
||||
Run `khal list today 7d`. For flights missing "shower and dress" /
|
||||
"travel to airport" blocks, create them:
|
||||
|
||||
- shower_start = flight_departure - airport_buffer - travel_buffer - 1h
|
||||
- Airport buffer: 2h domestic, 2.5h international
|
||||
- Travel to airport: 1h default
|
||||
- Create "shower and dress" block at shower_start (1h duration)
|
||||
- Create "travel to airport" block after shower
|
||||
- Set cron reminders: 15min before shower start, at departure time
|
||||
- Skip layover connections (already in airport)
|
||||
```
|
||||
|
||||
This means the agent automatically works backwards from flight times to create
|
||||
preparation blocks in the calendar. No manual planning needed.
|
||||
|
||||
---
|
||||
|
||||
## Landing Checklist
|
||||
|
||||
Triggered automatically after every flight lands. The agent doesn't wait to be
|
||||
asked.
|
||||
|
||||
### File: `memory/landing-checklist.md`
|
||||
|
||||
```markdown
|
||||
# Landing Checklist
|
||||
|
||||
Run this after EVERY flight, regardless of whether location/timezone changes.
|
||||
|
||||
## Immediate (within minutes of landing)
|
||||
|
||||
- [ ] Update daily-context.json → currentLocation, currentLodging,
|
||||
currentTimezone, nearestAirport, travelLeg
|
||||
- [ ] Update midnight-reset cron job timezone to new currentTimezone
|
||||
- [ ] Update location-log.csv with new city for today
|
||||
- [ ] Log flight segment in flight-log.csv
|
||||
|
||||
## Within 1 hour
|
||||
|
||||
- [ ] Check if daily meds are due/overdue (timezone change may shift the window)
|
||||
- [ ] Check if any interval meds are due today
|
||||
- [ ] Sync calendar and review next 48h for the new timezone
|
||||
- [ ] Check for any cron jobs with hardcoded timezones that need updating
|
||||
|
||||
## If entering a new country
|
||||
|
||||
- [ ] Check for medication resupply needs
|
||||
- [ ] Note any upcoming reminders that reference the old timezone
|
||||
```
|
||||
|
||||
### AGENTS.md prompt:
|
||||
|
||||
```markdown
|
||||
### Landing Checklist
|
||||
|
||||
- After EVERY flight the user takes, run through `memory/landing-checklist.md`
|
||||
- Trigger: calendar event landing time, or user messages after a flight
|
||||
- Do not wait to be asked — run it proactively
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Architecture
|
||||
|
||||
The two-tier memory system: daily files (raw) + MEMORY.md (curated).
|
||||
|
||||
### Daily files: `memory/YYYY-MM-DD.md`
|
||||
|
||||
Raw logs of what happened each day. Topics discussed, decisions made, tasks
|
||||
completed. Every session can read these.
|
||||
|
||||
```markdown
|
||||
# 2026-02-28
|
||||
|
||||
## Topics
|
||||
|
||||
| Time | Topic | Session |
|
||||
|------|-------|---------|
|
||||
| 14:30 | Discussed PR review workflow | main |
|
||||
| 16:00 | Medication logged | main |
|
||||
|
||||
## Notes
|
||||
|
||||
- Decided to switch deployment strategy for project X
|
||||
- User prefers Y approach over Z — standing rule
|
||||
```
|
||||
|
||||
### MEMORY.md — Long-term curated memory
|
||||
|
||||
```markdown
|
||||
## 🧠 MEMORY.md - Your Long-Term Memory
|
||||
|
||||
- **ONLY load in main session** (direct chats with your human)
|
||||
- **DO NOT load in shared contexts** (group chats, sessions with others)
|
||||
- This is for **security** — contains personal context that shouldn't leak
|
||||
- Write significant events, thoughts, decisions, opinions, lessons learned
|
||||
- This is your curated memory — the distilled essence, not raw logs
|
||||
- Over time, review daily files and update MEMORY.md with what's worth keeping
|
||||
```
|
||||
|
||||
### Memory maintenance (in AGENTS.md or HEARTBEAT.md):
|
||||
|
||||
```markdown
|
||||
### 🔄 Memory Maintenance (During Heartbeats)
|
||||
|
||||
Periodically (every few days), use a heartbeat to:
|
||||
|
||||
1. Read through recent memory/YYYY-MM-DD.md files
|
||||
2. Identify significant events, lessons, or insights worth keeping long-term
|
||||
3. Update MEMORY.md with distilled learnings
|
||||
4. Remove outdated info from MEMORY.md that's no longer relevant
|
||||
|
||||
Think of it like reviewing a journal and updating a mental model. Daily files
|
||||
are raw notes; MEMORY.md is curated wisdom.
|
||||
```
|
||||
|
||||
### Critical rule — write it down:
|
||||
|
||||
```markdown
|
||||
### 📝 Write It Down - No "Mental Notes"!
|
||||
|
||||
- **Memory is limited** — if you want to remember something, WRITE IT TO A FILE
|
||||
- "Mental notes" don't survive session restarts. Files do.
|
||||
- When someone says "remember this" → update memory file
|
||||
- When you learn a lesson → update AGENTS.md or relevant file
|
||||
- When you make a mistake → document it so future-you doesn't repeat it
|
||||
- **Text > Brain** 📝
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Heartbeat Configuration
|
||||
|
||||
Heartbeats are periodic polls from OpenClaw. The agent can do background work or
|
||||
stay quiet.
|
||||
|
||||
### HEARTBEAT.md structure:
|
||||
|
||||
```markdown
|
||||
# HEARTBEAT.md
|
||||
|
||||
## Inbox Check (PRIORITY)
|
||||
(check notifications, issues, emails — whatever applies)
|
||||
|
||||
## Flight Prep Blocks (daily)
|
||||
(create calendar prep blocks for upcoming flights)
|
||||
|
||||
## Open Projects Review
|
||||
(check project status, take next steps, or ask if blocked)
|
||||
|
||||
## Workspace Sync
|
||||
(commit and push workspace changes)
|
||||
|
||||
## Rules
|
||||
|
||||
- Post status updates to a designated channel, not the main chat
|
||||
- Update state files after any state change
|
||||
- If nothing needs attention, reply HEARTBEAT_OK
|
||||
|
||||
## Output Rules
|
||||
|
||||
Never send internal thinking or status narration to user's DM. Output should be:
|
||||
- HEARTBEAT_OK (if nothing needs attention)
|
||||
- A direct question or alert (if action needed)
|
||||
- Work narration → send to a status channel via message tool
|
||||
```
|
||||
|
||||
### Tracking heartbeat state: `memory/heartbeat-state.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"lastChecks": {
|
||||
"email": 1703275200,
|
||||
"calendar": 1703260800,
|
||||
"weather": null,
|
||||
"gitea": 1703280000
|
||||
},
|
||||
"lastWeeklyDocsReview": "2026-02-24"
|
||||
}
|
||||
```
|
||||
|
||||
### Heartbeat vs Cron:
|
||||
|
||||
```markdown
|
||||
**Use heartbeat when:**
|
||||
- Multiple checks can batch together
|
||||
- You need conversational context from recent messages
|
||||
- Timing can drift slightly (every ~30 min is fine)
|
||||
- You want to reduce API calls by combining periodic checks
|
||||
|
||||
**Use cron when:**
|
||||
- Exact timing matters ("9:00 AM sharp every Monday")
|
||||
- Task needs isolation from main session history
|
||||
- You want a different model or thinking level for the task
|
||||
- One-shot reminders ("remind me in 20 minutes")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gitea Integration & Notification Polling
|
||||
|
||||
For self-hosted Gitea instances, you can set up a notification poller that
|
||||
injects Gitea events (issue assignments, PR reviews, @-mentions) into the
|
||||
agent's session.
|
||||
|
||||
### Workflow rules (HEARTBEAT.md / AGENTS.md):
|
||||
|
||||
```markdown
|
||||
## Gitea Work Scope
|
||||
|
||||
Find issues/PRs assigned to me or where I'm @-mentioned → do the work.
|
||||
|
||||
- If @-mentioned with work but not assigned → assign myself, remove other
|
||||
assignees
|
||||
- When nothing is assigned to me, my Gitea work is done
|
||||
- PRs assigned to user = their queue, not my backlog
|
||||
|
||||
Workflow: issue → branch → PR "(closes #X)" → review/rework → assign user
|
||||
when all checks pass + reviewed.
|
||||
|
||||
### Rules
|
||||
|
||||
- Respond in the medium addressed: Gitea → Gitea comment, not chat
|
||||
- Before acting on ANY issue or PR: read ALL existing comments first
|
||||
- Never do work on a PR/issue that isn't assigned to you
|
||||
- Work done, no more needed → close the issue
|
||||
- Your part done, need feedback → unassign yourself, assign next person
|
||||
```
|
||||
|
||||
### Notification poller:
|
||||
|
||||
A Python script that polls the Gitea notifications API and injects events
|
||||
into OpenClaw sessions. It runs via launchd/systemd. Ask me for the full
|
||||
source code if you want to set this up — I can share it (it's a
|
||||
general-purpose tool with no PII).
|
||||
|
||||
---
|
||||
|
||||
## Sub-Agent Management
|
||||
|
||||
For complex coding tasks, spawn isolated sub-agents.
|
||||
|
||||
### Key rules:
|
||||
|
||||
```markdown
|
||||
### Sub-Agent Git Isolation (MANDATORY)
|
||||
|
||||
- NEVER let multiple sub-agents share the same git clone
|
||||
- Each sub-agent MUST clone to a unique temporary directory
|
||||
(e.g. `mktemp -d`)
|
||||
- When spawning, always instruct: `cd $(mktemp -d) && git clone <url> . && ...`
|
||||
- Dirty working directories cause false CI results
|
||||
|
||||
### Sub-Agent PR Quality Gate (MANDATORY)
|
||||
|
||||
- `make check` must pass with ZERO failures. No exceptions.
|
||||
- Pre-existing failures are YOUR problem. Fix them as part of your PR.
|
||||
- NEVER modify linter config to make checks pass. Fix the code.
|
||||
- Every PR must include full `make check` output
|
||||
- Rebase before and after committing
|
||||
- Never self-review
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Urgent Notifications via ntfy
|
||||
|
||||
For time-sensitive alerts when chat messages might go unacknowledged (e.g.,
|
||||
overdue medications):
|
||||
|
||||
```markdown
|
||||
## Urgent Notifications
|
||||
|
||||
Send urgent messages via ntfy.sh:
|
||||
|
||||
curl -d "MESSAGE HERE" ntfy.sh/YOUR-PRIVATE-TOPIC-ID
|
||||
|
||||
Use this for time-sensitive alerts (overdue meds, critical issues, etc.).
|
||||
**Never send PII via ntfy.** Keep messages generic (e.g. "daily meds overdue"
|
||||
not medication names or personal details).
|
||||
```
|
||||
|
||||
Create a random topic ID for your ntfy channel. The agent can `curl` to it
|
||||
directly.
|
||||
|
||||
---
|
||||
|
||||
## Group Chat Behavior
|
||||
|
||||
Rules for when the agent is in group chats with multiple people:
|
||||
|
||||
```markdown
|
||||
### Know When to Speak
|
||||
|
||||
**Respond when:**
|
||||
- Directly mentioned or asked a question
|
||||
- You can add genuine value (info, insight, help)
|
||||
- Something witty/funny fits naturally
|
||||
- Correcting important misinformation
|
||||
|
||||
**Stay silent when:**
|
||||
- Just casual banter between humans
|
||||
- Someone already answered the question
|
||||
- Your response would just be "yeah" or "nice"
|
||||
- The conversation is flowing fine without you
|
||||
|
||||
**The human rule:** Humans don't respond to every message. Neither should you.
|
||||
Quality > quantity.
|
||||
|
||||
### React Like a Human
|
||||
|
||||
Use emoji reactions naturally:
|
||||
- Appreciate something but don't need to reply → 👍, ❤️
|
||||
- Something made you laugh → 😂
|
||||
- Interesting/thought-provoking → 🤔, 💡
|
||||
- Acknowledge without interrupting → ✅, 👀
|
||||
|
||||
One reaction per message max.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Requirement Capture
|
||||
|
||||
Never lose a rule or preference your human states:
|
||||
|
||||
```markdown
|
||||
### Requirement Capture (MANDATORY)
|
||||
|
||||
- **Every single requirement, rule, preference, or instruction the user
|
||||
provides MUST be captured in the daily memory file immediately**
|
||||
- This includes: project rules, workflow preferences, corrections, new
|
||||
policies, technical decisions
|
||||
- If the user says something should be done a certain way, write it down
|
||||
in memory/YYYY-MM-DD.md AND in MEMORY.md if it's a standing rule
|
||||
- Nothing is to be missed. If in doubt, log it.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PII Output Routing — Audience-Aware Responses
|
||||
|
||||
A critical security pattern: **the audience determines what you can say, not
|
||||
who asked.** If your human asks for a sitrep (or any PII-containing info) in a
|
||||
group channel, you can't just dump it there — other people can read it.
|
||||
|
||||
### AGENTS.md / checklist prompt:
|
||||
|
||||
```markdown
|
||||
## PII Output Routing (CRITICAL)
|
||||
|
||||
- NEVER output PII in any non-private channel, even if your human asks for it
|
||||
- If a request would produce PII (medication status, travel details, financial
|
||||
info, etc.) in a shared channel: send the response via DM instead, and reply
|
||||
in-channel with "sent privately"
|
||||
- The rule is: the audience determines what you can say, not who asked
|
||||
- This applies to: group chats, public issue trackers, shared Mattermost
|
||||
channels, Discord servers — anywhere that isn't a 1:1 DM
|
||||
```
|
||||
|
||||
### Why this matters:
|
||||
|
||||
This is a real failure mode. If someone asks "sitrep" in a group channel and
|
||||
you respond with medication names, partner details, travel dates, and hotel
|
||||
names — you just leaked all of that to everyone in the channel. The human
|
||||
asking is authorized to see it; the channel audience is not. Always check
|
||||
WHERE you're responding, not just WHO asked.
|
||||
|
||||
---
|
||||
|
||||
## General Tips
|
||||
|
||||
### Bias toward action
|
||||
Don't ask blocking questions with obvious answers. Figure it out. Come back
|
||||
with results, not requests for permission.
|
||||
|
||||
### Checklists over trust
|
||||
For safety-critical operations (meds, deployments, external communications),
|
||||
maintain checklists in `memory/checklist-*.md` and reference them from
|
||||
AGENTS.md. The agent reads the checklist before acting.
|
||||
|
||||
### State repo
|
||||
Keep your workspace in a git repo that auto-syncs. This gives you version
|
||||
history and recovery:
|
||||
|
||||
```markdown
|
||||
### State Repo
|
||||
|
||||
- Commit and push workspace changes after any change
|
||||
- Push promptly — remote should reflect workspace in near-realtime
|
||||
- Auto-sync cron runs every 6h as a safety net
|
||||
```
|
||||
|
||||
### Error handling philosophy
|
||||
|
||||
```markdown
|
||||
## On Errors
|
||||
|
||||
When something goes wrong:
|
||||
1. Identify what input caused the wrong output
|
||||
2. Fix the input (rule, checklist, prompt, automation)
|
||||
3. Move on
|
||||
|
||||
No apologies. No promises. Fix the system.
|
||||
```
|
||||
|
||||
### Never weaken checks
|
||||
|
||||
```markdown
|
||||
## On Integrity
|
||||
|
||||
Never cheat. When a check fails, fix the code — don't weaken the check.
|
||||
When a test fails, fix the bug — don't loosen the assertion. When a linter
|
||||
flags something, fix the finding — don't suppress the rule.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_This document is a living reference. Patterns here have been tested in
|
||||
production and refined through real-world use._
|
||||
Loading…
Reference in New Issue
Block a user