clawpub/SETUP_CHECKLIST.md
user b0495d5b56
All checks were successful
check / check (push) Successful in 13s
rewrite SETUP_CHECKLIST.md: replace checklist items with paste-able agent prompts
Each section now contains a self-contained prompt in a code block that
adopting users can paste directly to their agent. Prompts include full
URLs to raw reference docs. Fixes 'you provide' wording to 'your human
provides'. Keeps same phase/section structure.
2026-02-28 03:22:08 -08:00

26 KiB
Raw Blame History

OpenClaw Setup Checklist

A step-by-step guide to configuring your own OpenClaw instance with the patterns described in OPENCLAW_TRICKS.md and AUTOMATED_DEV.md.

Each section contains a prompt you can paste directly to your agent. The prompts are self-contained — your agent should be able to execute each one without additional context. Work through them in order; each phase builds on the previous one.


Phase 1: Workspace Foundation

These are the core files every OpenClaw workspace needs.

1.1 Create SOUL.md

This defines your agent's personality, tone, and values. Paste this to your agent:

Create a SOUL.md file in the workspace root. This is who you are as an
agent. Include:

- Communication style: concise, direct, no filler. Have opinions. Be
  resourceful before asking.
- Error handling philosophy: when something goes wrong, identify what
  input caused the wrong output, fix the input (rule, checklist, prompt,
  automation), move on. No apologies, no promises. Fix the system.
- Integrity rules: never weaken checks to make things pass. When a check
  fails, fix the code, not the check.
- Bias toward action: try to figure it out first, then ask if stuck.

Reference for philosophy and examples:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md

1.2 Create USER.md

This tells your agent about you — the human it's helping. Paste this to your agent:

Create a USER.md file in the workspace root. Your human provides the
following info — ask them if not already known:

- Name and preferred name
- Current timezone
- Communication preferences (direct? verbose? brief?)
- Standing rules (e.g. "don't ask too many questions, just figure it
  out", "always confirm before sending emails")

Keep it concise. This file is read every session.

1.3 Create IDENTITY.md

Let the agent define itself. Paste this to your agent:

Create an IDENTITY.md file in the workspace root. This is YOUR identity
— fill it in yourself. Include:

- Your chosen name (or accept what your human calls you)
- An emoji that represents you
- Your vibe / personality in a sentence
- Anything else that makes you YOU

This is not instructions — it's self-expression. Make it yours.

1.4 Create the memory directory

This is where all state and logs live. Paste this to your agent:

Set up the memory directory structure:

1. Create the directory: mkdir -p memory/
2. Create memory/daily-context.json with this initial structure:

{
    "isSleeping": false,
    "lastKnownWakeTime": null,
    "predictedSleepTime": null,
    "predictedWakeTime": null,
    "currentLocation": null,
    "currentTimezone": null,
    "lastMessageFromUser": null,
    "isAvailable": true,
    "lastUpdated": null
}

3. Create today's daily file: memory/YYYY-MM-DD.md (use actual date)
   with a Topics table:

## Topics

| Time  | Topic |
| ----- | ----- |
|       |       |

## Notes

Your human will tell you what fields to add to daily-context.json for
their specific needs (medications, travel, etc.).

1.5 Create AGENTS.md

This is the master configuration file — responsibilities, rules, and session startup procedure. Paste this to your agent:

Create an AGENTS.md file in the workspace root. This is your operating
manual. Include the following sections:

## 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
4. Read memory/YYYY-MM-DD.md (today + yesterday) for recent context
5. If in main session: Also read MEMORY.md

Don't ask permission. Just do it.

## 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/YYYY-MM-DD.md or
  relevant file
- When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant
  config
- Text > Brain

## Requirement Capture (MANDATORY)

Every single requirement, rule, preference, or instruction your human
provides MUST be captured in the daily memory file immediately. This
includes: project rules, workflow preferences, corrections, new
policies, technical decisions. If in doubt, log it.

## Topic Log Maintenance

Append a one-line summary to the Topics table in today's
memory/YYYY-MM-DD.md after every meaningful conversation or topic
change. Do this continuously as conversations happen.

## Safety

- Don't exfiltrate private data. Ever.
- Don't run destructive commands without asking.
- trash > rm (recoverable beats gone forever)
- When in doubt, ask.

Reference for detailed patterns:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md

1.6 Create MEMORY.md

This is long-term curated memory — distilled insights, not raw logs. Paste this to your agent:

Create a MEMORY.md file in the workspace root. This is your long-term
memory — curated, not raw. Include:

1. A checklist index at the top (populate as you add checklists):

## Checklists (read the relevant file before acting)

- **Any PR/code work** → memory/checklist-pr.md
- **Any message to user** → memory/checklist-messaging.md
- (add more as you create them)

2. A security rule:

**Only load MEMORY.md in private/main sessions.** Never load it in group
chats or shared contexts — it contains personal information.

3. Leave space below for curated memories. Over time, review daily files
and distill significant events, lessons, and decisions here.

Reference for memory architecture:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Memory Architecture" and "MEMORY.md — Long-term curated memory")

Phase 2: Daily Context State File

The single most important runtime file. Every session reads it on every message.

2.1 Add timezone rules

Time bugs are the most common agent mistake. Paste this to your agent:

Add a "Timezone/Time Rules" section to AGENTS.md:

## Timezone/Time Rules

- System clock may differ from user's timezone — always check
  daily-context.json
- "Today"/"tomorrow" = user's local TZ, not system clock
- Never state times without explicit timezone conversion
- When displaying times, show in user's local timezone first, then
  UTC if relevant

Also: review the daily-context.json file and update currentTimezone
and currentLocation based on what you know about your human. Ask if
you don't know.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Location & Timezone Tracking")

Phase 3: Memory Architecture

3.1 Set up daily files and memory maintenance

The two-tier memory system: daily files for raw logs, MEMORY.md for curated insights. Paste this to your agent:

Add a "Memory Maintenance" section to AGENTS.md (or HEARTBEAT.md if
you already have one):

### Memory Maintenance (During Heartbeats)

Periodically (every few days):
1. Read through recent memory/YYYY-MM-DD.md files
2. Identify significant events, lessons, insights worth keeping
3. Update MEMORY.md with distilled learnings
4. Remove outdated info from MEMORY.md

Daily files are raw notes; MEMORY.md is curated wisdom. Think of it
like reviewing a journal and updating your mental model.

Also verify that today's daily file exists and has a Topics table. If
not, create it now.

Reference for the full memory architecture:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Memory Architecture", "Daily files", and "Memory maintenance")

Phase 4: Heartbeat Configuration

4.1 Create HEARTBEAT.md

Heartbeats let your agent be proactive — checking on things periodically without being asked. Paste this to your agent:

Create a HEARTBEAT.md file in the workspace root. This is your
proactive checklist — things to check when you receive a heartbeat
poll. Structure it like this:

## Checks (rotate through these, 2-4 times per day)

- Emails — any urgent unread messages?
- Calendar — upcoming events in next 24-48h?
- Open issues/PRs — anything assigned to me?
- Workspace sync — any uncommitted changes to push?

## Rules

- Late night (23:00-08:00 user local time): only act on urgent items
- If nothing needs attention: reply HEARTBEAT_OK
- Work narration goes to a status channel, not user's DM
- Don't respond multiple times to the same trigger

## Output Rules

- HEARTBEAT_OK if nothing needs attention
- Direct message to user only if action needed or urgent
- Status updates → dedicated channel (not DM)

Also create memory/heartbeat-state.json:

{
    "lastChecks": {},
    "lastWeeklyDocsReview": null
}

Customize the checks list based on what's relevant to your human.
Remove what doesn't apply, add what does.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Heartbeat Configuration" and "Heartbeat vs Cron")

Phase 5: Checklists

Checklists prevent the most common agent mistakes. AGENTS.md references them; the agent reads the checklist before acting.

5.1 Messaging checklist

Prevents broken links, wrong timezones, and stale claims. Paste this to your agent:

Create memory/checklist-messaging.md:

# Messaging Checklist

## Before EVERY message to user

1. PR/issue mentioned? → Full clickable URL required
2. URL included? → Verify it resolves before sending
3. Time/date stated? → Convert to user's current TZ (check
   daily-context.json)
4. Status claim? → Verify via API call, not memory
5. "Today"/"tomorrow"? → Resolve in user's local TZ, not system clock

Then add a reference to this checklist in the MEMORY.md checklist index.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "PII Output Routing" and "Checklists Over Prose")

5.2 PII output routing

Prevents leaking private info in shared channels. Paste this to your agent:

Add the following warning banner near the TOP of AGENTS.md (before the
session startup section):

**⚠️ NEVER output PII in non-private channels.** If asked for
PII-containing info (medical, financial, personal) in a shared channel,
send via DM to your human instead.

Also add a PII section to memory/checklist-messaging.md:

## PII Check (before every message in shared channels)

1. Contains names, addresses, medical info, financial info? → DM only
2. Contains login credentials or tokens? → NEVER send, period
3. When in doubt → send via DM

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "PII-Aware Output Routing")

5.3 Additional checklists

Create checklists for your specific workflow. Paste this to your agent:

Review the following checklist templates and create any that are
relevant to your human's workflow. Ask your human which ones apply:

- memory/checklist-pr.md — for code review and PR work. Key rules:
  make check must pass with ZERO failures, never modify linter config
  to make checks pass, rebase before pushing.

- memory/checklist-medications.md — for medication tracking (if
  applicable)

- memory/checklist-flights.md — for travel/flight management (if
  applicable)

For each checklist created, add a reference line to the MEMORY.md
checklist index at the top.

Reference for PR checklist patterns:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Git Quality Standards" and "Sub-Agent PR Quality Gate")

Reference for medication checklist:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Medication Tracking")

Phase 6: Sitrep

6.1 Define your sitrep

The sitrep gives your human a scannable status overview on demand. Paste this to your agent:

Add a "Sitrep" section to AGENTS.md:

### Sitrep (Situation Report)

When your human says "sitrep", provide a concise summary. Include items
relevant to your setup — choose from:

1. Current time (user's local TZ + UTC)
2. Open tasks/issues assigned to you
3. Open tasks/issues assigned to your human
4. Upcoming calendar events (next 48h)
5. Upcoming travel (next 72h + next known flight)
6. Medication status (if tracking)
7. Sleep summary (if tracking)
8. Weather alerts (if relevant)
9. Overdue reminders
10. Unanswered questions from your human

Rules:
- Omit any item that is "none" or zero
- Keep it scannable — bullet points, not prose
- Don't recap things your human was directly involved in
- If anything notable isn't covered above, add additional sections
- When listing PRs/issues, always include full clickable URLs

Customize this list: remove what doesn't apply to your human, add what
does. The "add additional sections" line is key — it lets you surface
things your human didn't think to ask about.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Sitrep (Situation Report)")

Phase 7: Tracking Systems (Optional)

Add whichever tracking systems are relevant. Each follows the same pattern: a CSV/JSON log file, an instructions file, and a checklist.

7.1 Sleep tracking

Paste this to your agent:

Set up sleep tracking. Create the following:

1. memory/sleep-log.csv with headers:
   Date,SleepTime,WakeTime,TimeZone,Duration,Status,Notes

2. Add sleep tracking rules to AGENTS.md:

### Sleep Tracking
- Infer sleep/wake times from message activity and explicit statements
- Log based on observed communication gaps, never from mathematical
  predictions alone
- Update daily-context.json isSleeping field accordingly
- Sleep start = last activity before gap, wake = first activity after

3. Add sleep fields to daily-context.json if not already present:
   isSleeping, lastKnownWakeTime, predictedSleepTime, predictedWakeTime

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Sleep Tracking")

7.2 Medication tracking

Paste this to your agent:

Set up medication tracking. Your human provides the medication list,
dosages, and schedules. Create:

1. memory/medications-instructions.md — ask your human for their
   medication list, dosages, frequency, and any safety rules (e.g.
   interactions, maximum doses). Structure with sections: General Rules,
   Daily Medications, Interval-Based Medications, Safety Rules.

2. memory/medications-log-YYYY-MM.csv (current month) with headers:
   Date,Time,TimeZone,Medication,Dosage

3. memory/checklist-medications.md with verification steps:
   - Before reporting status: verify against the CSV, not memory
   - Before sending reminders: check if already taken today
   - Overdue escalation: use push notification (ntfy or similar)

4. Add medication fields to daily-context.json:
   hasTakenDailyMedsToday, dailyMedsTimestamp

5. Add the checklist to MEMORY.md's checklist index.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Medication Tracking")

7.3 Location and travel tracking

Paste this to your agent:

Set up location and travel tracking. Create:

1. memory/location-log.csv with headers:
   Date,City,Country,Timezone

2. memory/flight-log.csv with headers:
   Date,FlightNumber,Origin,Destination,Duration,Alliance

3. memory/travel.md — for upcoming trip plans and unbooked flights

4. memory/landing-checklist.md — things to do after every flight:
   - Update daily-context.json location and timezone
   - Update location-log.csv
   - Log the flight in flight-log.csv
   - Check for country-specific actions (SIM, currency, etc.)

5. Add to AGENTS.md:

### Landing Checklist
After EVERY flight, run through memory/landing-checklist.md. Trigger:
calendar event landing time or human messages after a flight. Do not
wait to be asked.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Flight & Travel Logging" and "Landing Checklist")

7.4 Urgent notifications

Paste this to your agent:

Set up urgent push notifications. Ask your human for their preferred
push notification channel (ntfy.sh topic, Pushover, etc.).

Add to AGENTS.md:

## Urgent Notifications

Send urgent messages via push notification:

    curl -d "MESSAGE HERE" ntfy.sh/YOUR-PRIVATE-TOPIC-ID

Use for: overdue medications, critical system issues, time-sensitive
alerts.

Rules:
- Never send PII via push notifications
- Keep messages generic (e.g. "daily meds overdue" not medication names)
- Only use for genuinely urgent items

Replace the ntfy.sh URL with whatever your human provides.

Phase 8: Workspace as Git Repo

8.1 Initialize the state repo

Your workspace should be version-controlled for disaster recovery and debugging. Paste this to your agent:

Set up the workspace as a git repo for state persistence:

1. If not already a git repo: git init in the workspace root
2. Ask your human to create a PRIVATE repo on their git host
3. git remote add origin <url your human provides>
4. Initial commit and push of all workspace files

5. Add to AGENTS.md:

### State Repo
- Commit and push workspace changes after any change to workspace files
- Push promptly — remote should reflect workspace in near-realtime
- Auto-sync cron runs as a safety net (set up separately)

6. IMPORTANT: Clone code repos OUTSIDE the workspace directory to avoid
   embedded repo issues. Add a note to AGENTS.md about where to clone
   repos (e.g. ~/repos/ or a dedicated path).

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "The Workspace as a Git Repo" and "State Repo")

Phase 9: Git Quality Standards (For Development Work)

If your agent does coding work, set up the interlocking check system.

9.1 Adopt repo policies

Paste this to your agent:

Set up code quality standards for development repos. For each code
repo your agent works on:

1. Fetch and add REPO_POLICIES.md:
   https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md

2. For new repos, also fetch:
   https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md

3. For existing repos, fetch:
   https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md

4. Ensure every repo has a Makefile with these targets:
   test, lint, fmt, fmt-check, check, docker, hooks
   - "make check" depends on: test, lint, fmt-check
   - Dockerfile runs "make check" as a build step
   - CI workflow runs "docker build ."

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md
(see "The Interlocking Chain")

9.2 Set up PR quality gate

Paste this to your agent:

Create memory/checklist-pr.md with the PR quality gate:

# PR Checklist

## Before pushing to a branch
1. Associated PR is still open?
2. make check passes locally with ZERO failures?
3. docker build . passes locally (if Dockerfile exists)?
4. Formatter passes?
5. No linter config / Makefile changes in diff?
6. All external refs pinned by SHA?
7. Rebased against main, no merge conflicts?

## After sub-agent pushes code
1. Check diff for linter / test config changes
2. Check diff for -short / -timeout flags added
3. If any config files changed unexpectedly: reject and rework

## PR pipeline (every PR, no exceptions)
1. Review/rework loop until clean
2. Check/rework loop until clean
3. Only then: assign to human for final review

CRITICAL RULES:
- make check must pass with ZERO failures. No exceptions.
- Pre-existing failures are YOUR problem. Fix them.
- NEVER modify linter config to make checks pass. Fix the code.
- Never self-review.

Add this checklist to the MEMORY.md checklist index.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Git Quality Standards" and "The PR Pipeline")

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md
(see "PR State Machine")

9.3 Set up branch protection

Paste this to your agent:

For each code repo, enable branch protection on the main branch. Ask
your human to configure (or configure via API if you have admin
access):

- Require pull request reviews before merging
- Require CI status checks to pass
- Block force-pushes to main
- Require branches to be up-to-date before merging

These settings prevent both humans and agents from merging broken code.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md
(see "Branch Protection")

Phase 10: Gitea Integration (Optional)

If you use Gitea (or similar self-hosted git platform) for issue tracking and code review.

10.1 Set up bot account and poller

Paste this to your agent:

Set up Gitea integration. Your human provides: the Gitea instance URL,
a bot account username, and an API token.

1. Store the Gitea URL and token in TOOLS.md (workspace-only, never in
   code repos):

## Gitea
- Instance: https://your-gitea-instance.example
- User: your-bot-username
- Token: (your human provides this)
- API base: https://your-gitea-instance.example/api/v1

2. Add Gitea workflow rules to AGENTS.md:

## Gitea Work Scope

Find issues/PRs assigned to me → do the work.

- If @-mentioned with work but not assigned → assign myself, then work
- When nothing assigned to me, my Gitea work is done
- Respond in the medium addressed: Gitea mention → Gitea comment
- Work done, no more work needed → close the issue
- My part done, need feedback → unassign myself, assign the party
  responsible for the next step

Workflow: issue → branch → PR "(closes #X)" → review/rework → assign
human when all checks pass.

3. Set up the notification poller (see reference for implementation).
   Configure env vars: GITEA_URL, GITEA_TOKEN, HOOK_TOKEN. Run as a
   system service.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Gitea Integration & Notification Polling")

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md
(see "The Notification Poller" and "Real-Time Activity Feed")

10.2 Set up PR state machine labels

Paste this to your agent:

Set up PR state tracking with labels. For each code repo, create these
labels via the Gitea API:

- needs-rebase (color: red) — PR has merge conflicts
- needs-checks (color: orange) — CI hasn't passed yet
- needs-review (color: yellow) — ready for human review
- needs-rework (color: purple) — reviewer requested changes
- merge-ready (color: green) — all gates passed, ready to merge

Create memory/pr-pipeline.md documenting the state machine transitions
and assignment rules.

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md
(see "PR State Machine", "States", and "Transitions")

Phase 11: Deployment Pipeline (Optional)

If you want push-to-deploy for your services.

11.1 Set up deployment

Paste this to your agent:

Set up a deployment pipeline. This is environment-specific — ask your
human about their infrastructure. Common pattern:

1. Deploy a PaaS layer on your server. Options:
   - µPaaS (https://git.eeqj.de/sneak/upaas) — lightweight,
     Docker-based, webhook-triggered
   - Dokku, Coolify, or similar

2. Configure your reverse proxy (Traefik, Caddy, nginx) for automatic
   TLS

3. Create deploy keys (read-only SSH) for each repo that should
   auto-deploy

4. Add Gitea webhooks pointing to your PaaS for repos that should
   auto-deploy on merge to main

5. Test: merge a PR, verify the service updates automatically

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md
(see "Deployment: µPaaS" and "The Full Pipeline")

Phase 12: Group Chat Rules (If Applicable)

If your agent participates in group chats.

12.1 Add group chat behavior

Paste this to your agent:

Add group chat behavior rules to AGENTS.md:

### Know When to Speak

Respond when: directly mentioned, can add genuine value, correcting
important misinformation, something witty fits naturally.

Stay silent when: casual banter between humans, someone already
answered, your response would just be "yeah" or "nice", the
conversation is flowing fine without you.

The human rule: humans in group chats don't respond to every message.
Neither should you. Quality > quantity.

### React Like a Human

On platforms that support reactions, use emoji reactions naturally:
- Appreciate something but don't need to reply → 👍 ❤️
- Something made you laugh → 😂
- Acknowledge without interrupting → 👀
- One reaction per message max

### Per-Channel Rules

For channels with specific rules, create memory/CHANNEL_NAME.md and
add a reference line near the top of AGENTS.md:
**⚠️ #channel → read memory/CHANNEL_NAME.md first**

Reference:
https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md
(see "Group Chat Behavior")

Verification

After completing the phases relevant to you, run these checks. Paste this to your agent:

Run a verification check on the workspace setup:

1. Start a fresh session — verify you read all startup files (SOUL.md,
   USER.md, daily-context.json, today's daily file)
2. Run "sitrep" — verify it covers all configured items
3. If PII routing is set up: test by asking for sensitive info in a
   hypothetical shared channel context — verify it would redirect to DM
4. If Gitea is set up: verify you can list issues assigned to you via
   the API
5. If git quality gates are set up: verify make check passes on at
   least one repo
6. Verify the workspace git repo has recent commits and is pushed
7. List any missing files or incomplete sections from the setup

Report what passed and what needs attention.

Reference Documents


Start with Phases 14 (workspace foundation, daily context, memory, heartbeat). These give you 80% of the value. Add the remaining phases as your needs grow.